SvelteKit 3.0 迁移清单：别名改了、安全默认收紧、三个 API 被移除

SvelteKit 3.0.1 已于 10 月 6 日发布，是 3.0 大版本之上的第一个补丁。补丁本身只修了生成类型（让相对导入在 nodenext 模块解析下可用），真正要关心的是 3.0 的迁移。

先对环境

• Node 22+
• TypeScript 6
• Svelte 5.56.4+
• Vite 8
• @sveltejs/vite-plugin-svelte v7

这几项不满足就别开始，会卡在莫名其妙的地方。

被移除的 API

• $app/stores
• $service-worker
• handleValidationError——校验错误现在会带着 kind: validation 进入 handleError
• CSRF 的 checkOrigin 选项

别名变更 $lib 变成 #lib，模块导入需要写显式扩展名。这个改动在全项目里涉及面很广，建议用编辑器的全局替换加逐个复核，别指望一次替换就干净。

安全默认值收紧（最值得看的部分）

• 默认禁止外部重定向。
• 没有 Content-Type 头的跨站表单提交会被拒绝。
• 以 x-sveltekit- 开头的查询参数会被拒绝。

这三条每一条都可能让现有代码「突然不工作」。特别是第一条，如果你的应用有跳转中间件或者 OAuth 回调逻辑，一定要专门测。

行为变化

• cookie 的 path 默认为 /。
• cookie 名称必须是 ASCII。
• 版本轮询默认间隔改为一小时。

cookie 名称这条容易被忽略——如果项目里用了中文或者带特殊字符的 cookie 名，升级后会直接报错。

建议的迁移顺序

1. 先把环境问题（Node / TS / Vite / Svelte）全部对齐，跑通构建。
2. 处理被移除的 API，尤其是 $app/stores 的替换。
3. 全局替换 $lib 到 #lib，补扩展名。
4. 专门测跳转和表单这两块，这是安全默认收紧的主要影响面。
5. 最后再处理 cookie 相关的行为差异。

一个判断标准 如果你的项目大量依赖 $app/stores 和外部重定向，这次迁移的工作量会明显大于平均水平，建议预留专门的回归测试时间。

本文由奇幻维度内容助手整理发布，欢迎在评论区交流你的看法。

别名改动是全量替换，用编辑器的结构化重构比正则安全。安全默认收紧后本地开发可能出现新的跨域或内容策略报错，先把这些跑一遍再评估工作量，别按小版本估算。