SuperAPI AI 工具集

svelte5-runes-static

前端与建站

查看项目

更新于 10-15 14:20

技能介绍

用途

该技能用于在 SvelteKit 中使用 adapter-static 进行静态预渲染(SSG/SSR)时,正确结合 Svelte 5 runes 与传统 store,避免 hydration 后状态失效或响应式断裂。资料将其定位为“静态优先”的 Svelte 5 应用构建模式,适用于需要预渲染、又要在客户端保持响应式的场景。

主要能力

技能围绕三类兼容规则展开:

  1. 不要在模块作用域使用 runes。资料说明,adapter-static 会把组件预渲染为 HTML,模块作用域的 runes 无法序列化/反序列化,水合后状态会变成惰性/冻结,响应式完全失效。解决方案是全局状态使用传统 writable() store。
  2. 不要在 $derived 内使用 $ 自动订阅。runes 模式禁用了 $ 自动订阅语法,需改为在 $effect() 中手动 subscribe,把值写入 $state,再在 $derived() 中使用。
  3. 不要用带 getter 的 store 工厂。getter 不会建立响应式连接,应直接导出 store 与 derived store。

技能还给出推荐的混合模式:全局状态用 writable()/derived(),组件本地状态与逻辑用 runes,并通过桥接模式把 store 值同步到 rune state。

使用方式

资料提供了多段可直接参考的代码模式,包括:

  • 全局 store 定义(user、theme、isAuthenticated 等)。
  • 组件内使用 $props() 接收 props,用 $state 保存本地状态,用 $effect 订阅 store 并返回取消订阅函数。
  • Store → Rune → Derived 的完整桥接链:先订阅多个 store 写入 $state,再用 $derived 做过滤与计数。
  • SSG/SSR 安全写法:load 函数中 fetch 数据;使用 $app/environment 的 browser 判断,仅在客户端初始化 WebSocket、localStorage 等;用 {#if browser} 条件渲染客户端专属内容,避免 hydration 不匹配。
  • TypeScript 集成:用接口定义 Props 与 StoreShape,类型化 props、类型化 store 桥接。
  • 常见模式:$bindable 可绑定组件状态、表单状态管理与校验、基于 derived store 的防抖搜索。
  • 迁移清单:从 Svelte 4 迁移到 Svelte 5 时,把组件级 $: 换成 $derived(),把 export let 换成 $props(),保留全局 store,增加 store→rune 桥接,替换 $store 语法,并用 npm run build 验证预渲染与水合。
  • 测试模式:使用 svelte 的 mount、tick 与 vitest 测试 runes 组件和 store 桥接。
  • 性能注意事项:避免过度响应式,按需计算;对昂贵计算使用传统 derived store 再桥接到 rune。
  • 故障排查:状态水合后不更新、$derived 中报 “$ is not defined”、SSG 后读取 undefined、hydration mismatch 警告,均给出原因与修复方式。

适用场景

  • 使用 SvelteKit adapter-static 做预渲染的静态优先应用。
  • 需要全局共享状态且要跨 SSG/SSR 存活的项目。
  • 组件本地需要 runes 响应式逻辑,同时又要消费全局 store 的场景。
  • 需要从 Svelte 4 迁移到 Svelte 5 并保持静态部署兼容的项目。
  • 需要为 Svelte 5 runes 与 store 桥接编写 Vitest 单元测试的项目。

限制

资料明确列出若干“不可做”的约束:模块作用域 runes 在 adapter-static 下不可用;runes 模式不支持 $ 自动订阅;store 工厂使用 getter 会破坏响应式。此外,客户端专属代码必须用 browser 判断或条件渲染保护,否则会出现 hydration 不匹配。资料未提供该技能的安装命令、收费方式、平台支持范围或具体版本要求,这些信息暂未提供。