svelte

Svelte

概览

Svelte 是一个基于编译器的 UI 框架，将工作从运行时转移到构建时，生成精简的 JavaScript，且不使用虚拟 DOM。Svelte 5 引入了 runes，实现显式、细粒度的响应式。SvelteKit 是基于 Svelte 构建的全栈框架，提供基于文件的路由、服务器端渲染和部署适配器。

适用场景： 全栈 Web 应用、静态网站、渐进式增强、SSR/SSG、小型打包体积的项目，以及从 Svelte 4 迁移到 5 的项目。

不适用场景： 需要绑定 React/Vue 生态的项目、需要大量仅适用于其他框架的第三方组件库的项目，以及在紧迫期限内由没有 Svelte 经验的团队开发的项目。

快速参考

模式	API / 语法	要点
响应式状态	let count = $state(0)	替代 Svelte 4 中 let 的响应式写法
派生状态	const double = $derived(count * 2)	替代 $: 响应式声明
复杂派生	const value = $derived.by(() => { ... })	用于包含多条语句的派生计算
副作用	$effect(() => { ... })	在 DOM 更新后运行，并自动跟踪依赖
组件属性	let { name, age = 25 } = $props()	替代 export let，支持默认值
可绑定属性	let { value = $bindable() } = $props()	使用 bind:value 实现双向绑定
调试检查	$inspect(value)	仅在开发环境中记录，生产环境中会移除
片段	{#snippet name(params)}...{/snippet}	替代插槽，可复用的模板块
渲染片段	{@render name(args)}	使用参数调用片段
事件处理	<button onclick={handler}>	使用属性替代 on:click 指令
each 块	{#each items as item (item.id)}...{/each}	使用键控迭代实现高效更新
await 块	{#await promise}...{:then}...{:catch}...	内联异步渲染
服务端加载	export function load({ params }) in +page.server.ts	仅在服务端运行，可访问数据库和机密信息
通用加载	export function load({ fetch }) in +page.ts	在服务端和客户端运行
表单操作	export const actions in +page.server.ts	使用 use:enhance 实现渐进增强
布局	+layout.svelte / +layout.server.ts	在子路由间共享 UI 和数据
服务端钩子	handle() in src/hooks.server.ts	请求中间件、身份验证和重定向
错误页面	+error.svelte	按路由划分的错误边界
适配器	adapter-auto、adapter-node、adapter-static	部署到 Vercel、Node 或静态托管环境
API 路由	+server.ts with GET、POST 等	独立端点，不与页面绑定
页面选项	export const prerender = true	按路由控制 SSR、CSR 和预渲染
共享状态	$state() in .svelte.ts modules	替代 writable stores，用于跨组件状态
原始状态	$state.raw(data)	对大型数据集禁用深层代理

Svelte 4 到 5 迁移

Svelte 4（旧版）	Svelte 5（当前）
let count = 0（响应式）	let count = $state(0)
$: double = count * 2	const double = $derived(count * 2)
$: { sideEffect() }	$effect(() => { sideEffect() })
export let name	let { name } = $props()
<slot />	{#snippet children()}{/snippet} + {@render}
on:click={handler}	onclick={handler}
createEventDispatcher()	回调 props：let { onclick } = $props()
import { writable } from 'svelte/store'	在 .svelte.ts 模块中使用 $state()
$store 自动订阅	直接访问基于 rune 的状态值

常见错误

错误	正确模式
不加注意地在非原始值上使用 $state	$state 会对对象进行深层代理；对于大型只读数据，使用 $state.raw()
解构 $props() 会失去响应性	仅在声明时解构：let { x } = $props()
有条件地读取 $effect 依赖项	确保所有被跟踪的读取都无条件发生
从 $effect 错误地返回清理函数	返回一个函数：$effect(() => { return () => cleanup() })
在 Svelte 5 中混用 on:click 和 onclick	在 Svelte 5 组件中只使用 onclick
在新的 Svelte 5 代码中使用 stores	在 .svelte.ts 模块中使用 $state() 管理共享状态
忘记在 {#each} 块中使用 (key)	始终使用 key：{#each items as item (item.id)}
从 .svelte 文件导出 load	Load 函数应放在 +page.ts 或 +page.server.ts 中
在布局中未等待父级 load	当子级 load 依赖布局时，使用 await parent()
在服务器 load 函数中使用 goto()	使用来自 @sveltejs/kit 的 redirect(303, '/path')

委派

• 模式发现：使用 Explore Agent
• 代码审查：委派给 code-reviewer Agent
• 构建配置：委派给 Task Agent

如果有 tailwind 技能，将 Tailwind CSS 工具类模式和配置委派给它。 如果有 vitest-testing 技能，将 Svelte 组件单元测试模式委派给它。 如果有 playwright 技能，将 SvelteKit 路由和表单操作的端到端测试委派给它。 如果有 drizzle-orm 技能，将 SvelteKit 服务器 load 函数中使用的数据库架构和查询模式委派给它。 如果有 vite 技能，将 Vite 构建配置和插件设置委派给它。

参考资料

• Runes 和响应式模式（$state、$derived、$effect、$props）
• 片段、渲染和组件组合
• SvelteKit 路由、load 函数和布局
• 表单操作、渐进增强和验证
• 钩子、中间件和错误处理
• Svelte 4 到 5 迁移模式
• SvelteKit 适配器和部署