写了三年 SvelteKit，每次升级 major 配置迁移都要重写一遍——今天这件事被 sv migrate 彻底变了

SvelteKit 3 正式进入 Release Candidate 阶段。这意味着稳定版就在眼前，升级准备工作现在就该开始了。

这次最大的变化不是新功能——而是迁移方式本身变了。

痛苦在哪

SvelteKit 3 的 breaking changes 涉及面相当广：

配置文件迁移：svelte.config.js 整块搬进 vite.config.ts，files.lib 字段直接删掉。

导入别名颠覆：$lib 彻底废除，改用 Node.js 原生的 #lib 子路径导入。这意味着项目里每一个 $lib/xxx 都要改成 #lib/xxx，包括所有相对路径里的引用。

TypeScript 配置重构：tsconfig.json 不再 extends ./.svelte-kit/tsconfig.json，改为 extends $app/tsconfig。

$app 模块大面积改写：$app/stores 被 $app/state 取代，$app/env 的路径和结构全变了，$app/paths 的 base/assets/resolveRoute 全部移除，ORIGIN 环境变量在 adapter-node 里直接废除。

Vite 8 强制升级：Rolldown 成为默认 bundler，旧的 Vite 插件大量不兼容。

这些改动放在以前，靠人肉 grep + sed 能跑通，但很容易漏、很难 review、出了错也不好回溯。

一条命令做了什么

sv@1.0.0-next.0 内置了 sveltekit-3 迁移任务，执行：

npx sv@next migrate sveltekit-3 --tasks all --confirm

它做了四件事：

1. 依赖升级：自动把 package.json 里的 @sveltejs/kit、vite、svelte 抬到所需最低版本
2. $lib → #lib 重写：扫描全项目，把所有 $lib/ 开头的导入改成 #lib/，并补上文件扩展名（Node.js 子路径导入要求显式扩展名）
3. $app/stores → $app/state：替换 $app/state 相关引用，去掉 $ 前缀（因为 state 模块基于 Svelte 5 runes）
4. 生成 TODO 清单：对于无法自动处理的改动——比如 TypeScript 配置的手动调整、CSRF 设置的迁移、含 test/spec/stories 的文件名不再成为路由——迁移工具会在代码里插入 @migration 注释，列出一份清单供人工处理

根据实际项目规模，这一步能处理掉 70%~90% 的机械改动。

建议的操作顺序

不要直接跑。先做这一步：

# 1. 保持在 SvelteKit 2.x 最新 patch 版
npm install @sveltejs/kit@latest

这一步很关键。SvelteKit 2.x 最新版会触发有针对性的 deprecation warnings，每个 warning 对应一条需要迁移的代码。这些 warning 能让 TODO 清单变得更短。

# 2. 在副本上跑迁移
sv migrate sveltekit-3 --tasks all --confirm

# 3. 逐条处理 TODO 清单
# 有 @migration 注释的地方需要手动处理

# 4. 确认 Vite 8 插件兼容性
# Rolldown 替代了 esbuild + Rollup
# 审计 node_modules 里所有 Vite 插件

# 5. 安装 RC 并测试
npm install @sveltejs/kit@next

一个值得注意的地方

SvelteKit 3 的 Svelte 团队在 RC 公告里明确说了：Remote Functions（服务端-客户端通信的新模式，替代传统的 load 函数）仍然是 experimental，稳定版发布前 API 可能还会变。这意味着如果你的项目重度依赖服务端数据加载，不要在生产环境激进跟进——但可以在开发环境跑起来摸清楚。

为什么这值得现在做

SvelteKit 在 State of JS 调查里连续多年保持 93% 以上的满意度，不是因为它从来不 break，而是因为它 break 之后给了足够好的迁移工具。这次 sveltekit-3 任务比以往任何一次 major 升级的自动化程度都高。

RC 意味着团队已经进入收尾阶段，稳定版会以周计而不是月计地发布。等稳定版出来了再动手，就等于要在真实压力下完成迁移。现在在副本上跑一遍，心里有数，稳定版一出直接动手——这才是正确姿势。

官方迁移文档在 next.svelte.dev/docs/kit/migrating-to-sveltekit-3，sv migrate CLI 的完整参数在 sv.dev/docs。