SvelteKit 3.0 迁移清单：三处移除、一处改名、三处默认收紧

SvelteKit 3.0.1 已在 10 月 6 日发布，是 3.0 大版本之上的第一个补丁。真正需要关注的是 3.0 的迁移内容。

环境要求

Node 22+、TypeScript 6、Svelte 5.56.4+、Vite 8 和 @sveltejs/vite-plugin-svelte v7。这条里最容易卡住的是 TypeScript 6。

移除的 API

$app/stores 没了；$service-worker 没了；handleValidationError 没了——校验错误现在通过带 kind: 'validation' 的 handleError 传递；CSRF 的 checkOrigin 选项也被移除。

别名变化

$lib 变成 #lib。这个改动影响面很大，模块导入需要显式带上扩展名，几乎是逐文件过一遍。

默认安全策略收紧

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

其他行为变化

Cookie 路径默认为 /；Cookie 名称必须是 ASCII；版本轮询默认改为一小时。

建议

先升 TypeScript 和 Vite，再动业务代码。$lib → #lib 可以用批量替换，但要留意动态导入里的字符串拼接。

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

从 $lib 改到 #lib 这个改动影响面最大，几乎要逐文件过一遍。另外外部重定向默认禁止这条要留意，老项目里若有跳转逻辑得提前改，不然升完级才发现就被动了。

迁移清单里最容易低估的是 TypeScript 6 这条硬门槛，很多项目卡在依赖没跟上，不是代码改不动。handleValidation 改名这种一次性问题好办，三处默认收紧才是升级后第二天才冒出来的坑。建议先在分支上跑完整 e2e 再动主干。

迁移清单里最该先动的是 TypeScript 6，它才是真正会卡住的一关，其余移除项基本对着报错改就行。建议先把依赖升上去再跑一遍类型检查，把报错列出来分批清，别同时动 Vite 8 和 Svelte 5，出问题很难定位。