超级管理员
楼主
项目从 SvelteKit 2 迁到 3.0，记录一下实际耗时和注意点。
环境要求先拉齐
- Node 22+
- TypeScript 6
- Svelte 5.56.4+
- Vite 8
- @sveltejs/vite-plugin-svelte v7
这一步不通过，后面所有报错都没意义。我们卡在这里最久，因为 TypeScript 6 需要同步改一批类型配置。
$lib 改 #lib
全局替换本身不复杂，麻烦的是两点：
第一，模块导入需要写显式扩展名。原本 $lib/utils 现在要写成 #lib/utils.js 或 .ts。批量替换后要逐个文件确认，尤其是有 index 文件的目录。
第二，动态导入的路径拼接会失效。用变量拼路径的地方要单独处理，静态替换覆盖不到。
被移除的模块
- $app/stores：用新的状态 API 替代。
- $service-worker：PWA 相关项目要重写这部分。
- handleValidationError：校验错误现在以 kind: 'validation' 进入 handleError。
- CSRF 的 checkOrigin 选项被移除。
安全默认值造成的意外
默认禁止外部重定向这条，直接影响了我们的第三方登录回调。原本跳转外部域名的逻辑现在被拦。
解决方式是在 hooks 里显式处理重定向白名单，但要注意别开得太宽。
另外「拒绝没有 Content-Type 头的跨源表单提交」这条也挡住了一个老接口——第三方系统回传数据没带 Content-Type。这种问题测试环境不容易发现，因为内部调用一般都带了头。
cookie 的两个变化
- path 默认为 /。
- 名称必须 ASCII。
我们有个用了中文名的 cookie，直接报错。
version 轮询改成一小时
前端感知新版本的速度变慢。我们的发布流程依赖用户快速切到新版本，最后手动调了这个间隔。
整体感受
迁移工作量集中在机械替换和回归测试，逻辑改动不多。但安全默认值的收紧需要逐个场景验证，这部分最花时间。
建议预留比预期多一倍的时间给回归，尤其是涉及跳转、表单、第三方回调的部分。
本文由奇幻维度内容助手整理发布，欢迎在评论区交流你的看法。