用途:面向 Svelte 5 与 SvelteKit 项目,帮助构建、审查、重构和调试代码,优先采用当前惯用法而非遗留模式,并关注 SSR、hydration 与导航下的可推理性。
主要能力与工作流:先检查 package.json、svelte.config.、路由布局和邻近组件,沿用仓库既有约定(除非明确迁移);新代码默认 runes 模式与当前 SvelteKit API。先确定边界:仅服务端的工作放入 +page.server.、+layout.server.、+server.、hooks 或 $lib/server/*;可复用视图逻辑放入组件而非路由文件。先解决数据流,再处理 UI:明确真相应位于 URL、服务端数据、组件状态、context 还是共享响应式对象,优先派生而非同步副本,仅对外部副作用使用 effect。
Svelte 惯用法:新代码使用 $state、$derived、$props、snippets 与当前事件语法;大对象整体替换可用 $state.raw;多语句计算用 $derived.by;用 $inspect、$inspect.trace 调试响应性;props 视为实时输入并从中派生;新代码优先 snippets、onclick 等当前事件属性、键控 {#each}(不用索引作键);样式传递用 style:--token 与 CSS 自定义属性;优先 createContext;不默认用 stores,保留给异步流、外部订阅或生态集成。
组件设计:展示组件保持纯函数式,props 进、回调出;副作用编排放在路由或布局组件;避免过早全局状态,局部子树用 context。
SvelteKit 数据与变更:需密钥、数据库、cookie 或可信请求上下文时用 +page.server.* 或 +layout.server.;通用 load 仅在服务端与客户端均安全且允许浏览器重跑时使用;load 保持无副作用,变更放 actions、endpoints 或服务端处理器;load 内使用 SvelteKit 提供的 fetch;谨慎使用 parent()、depends() 与定向失效,不滥用 invalidateAll();使用生成的 PageProps、LayoutProps 等类型。表单变更优先 form actions,可预期错误通过 action 结果返回,use:enhance 用于渐进增强;API 式交互、webhook 用 +server.;幂等筛选/搜索表单用 GET 加 URL 参数。
状态放置与 SSR:可分享或需跨刷新、深链、SSR 的状态放 URL;一次性 UI 状态留组件;短暂状态可用 snapshots。避免在共享模块放请求相关服务端状态。浏览器专用 API 需在 onMount 或浏览器检查后使用;防止 hydration 不匹配(非确定性渲染、仅浏览器分支、时间/随机、locale 差异、SSR 与 hydration 间数据变化),SSR 渲染稳定占位符。
导航、性能与调试:尽量用声明式链接与表单,真正需要时才用 goto;变更后用最窄依赖失效;路由变化需重置时显式 key 子树。优先移除不必要 effect,避免过大的布局 load、路由瀑布、过度集中 stores 及既取数又渲染复杂 UI 的组件。调试时检查 load 重跑条件、depends、失效、组件复用、snapshots、原生 action 与 use:enhance 差异、服务端认证边界与 hydration。
迁移与限制:既有 pre-runes 代码除非迁移任务或明显更清晰,否则不强行改写;新旧范式不混用于同一文件;promise-in-template 需兼容版本且启用相关实验选项。官方参考:https://svelte.dev/docs/svelte/best-practices、https://svelte.dev/docs/svelte/$state、https://svelte.dev/docs/svelte/$derived、https://svelte.dev/docs/svelte/$effect、https://svelte.dev/docs/svelte/$props、https://svelte.dev/docs/kit/load、https://svelte.dev/docs/kit/form-actions、https://svelte.dev/docs/kit/state-management。收费、价格、平台与效果等未提供。