SvelteKit 3 升級指南：設定檔、#lib 與登入流程怎麼驗收

開始前，把本機與 CI 的條件對齊#

官方遷移文件列出的最低版本是 Node.js 22.17、TypeScript 6、Svelte 5.57.1、Vite 8.0.12，以及 @sveltejs/vite-plugin-svelte 7。先檢查本機、CI、Docker image 與部署平台的 runtime，不能只更新開發電腦。

在 SvelteKit 專案根目錄讀取目前版本：

1
node --version
2
pnpm list @sveltejs/kit svelte vite typescript @sveltejs/vite-plugin-svelte --depth 0
3
git status --short

先保存目前可部署版本的 commit、lockfile 與部署產物，並記錄既有 check、build 與測試結果。若升級前就有失敗，之後要能區分原有問題與遷移造成的變化。使用其他套件管理工具時，保留原工具與 lockfile，不要把換工具混進框架升級。

接著先升到最新 SvelteKit 2.x，讓棄用提示指出專案仍使用哪些舊 API。這一步有助於把一次大改分成兩次可審查的差異。

遷移指令完成後，先看它改了哪些檔案#

在工作目錄乾淨、已建立升級分支的前提下，執行：

1
npx sv migrate sveltekit-3

Svelte 官方公告也提供 --tasks all --confirm 的自動化用法。第一次遷移可以先保留互動選擇，知道哪些任務會執行，再決定是否使用自動確認；不要把自動確認理解成遷移工具替你完成了驗收。

執行完後依序讀取工具的 TODO、git diff 和套件版本變化。若設定、alias、業務功能與大批格式化同時改動，先整理成能逐項審查的差異，再開始除錯。

設定移到 Vite，不是只換檔名#

SvelteKit 3 不再支援 svelte.config.js。設定改傳給 Vite 的 sveltekit() plugin，原本的 kit 選項要放到 plugin 的頂層。下面是使用 adapter-auto 的最小設定示意：

1
import adapter from '@sveltejs/adapter-auto';
2
import { sveltekit } from '@sveltejs/kit/vite';
3
import { defineConfig } from 'vite';
4

5
export default defineConfig({
6
  plugins: [sveltekit({ adapter: adapter() })],
7
});

已有 Node、Cloudflare 或其他 adapter 的專案，保留與部署平台相符的 adapter，不要因為範例使用 auto 就一起更換。preprocess、compiler options、路徑和額外 Vite plugin 也要逐項對照官方設定文件。

設定驗收可以分成兩個問題：開發伺服器是否找到正確的頁面與資產？build 產物是否仍是部署平台預期的形式？前者通過不代表後者也通過。

#lib 要同時檢查 import 與 package.json#

$lib 改成 Node.js subpath imports 的 #lib。除了取代程式碼中的 alias，還需要在 package.json 宣告對應：

1
{
2
  "imports": {
3
    "#lib": "./src/lib/index.js",
4
    "#lib/*": "./src/lib/*"
5
  }
6
}

這是需合併到既有 package.json 的片段，不要覆蓋其他欄位。官方文件也要求補上 import 的模組副檔名；請依實際來源檔與工具解析方式改寫，不能只做全域字串替換。

例如原本的 import { format } from '$lib/format'，JavaScript 檔案可改成 import { format } from '#lib/format.js'。若根本沒有 src/lib/index.js，就先建立對應入口或調整 #lib 指向，不能留下不存在的路徑。

遷移後可用搜尋找殘留引用：

1
rg -n '\$lib|\$app/stores|\$app/environment|\$service-worker' src

搜尋結果是待審查清單，註解中的命中不等於執行錯誤。除了 $lib，$app/stores 已移除、$app/environment 更名為 $app/env，service worker 的舊模組也有調整，應依各自用途處理。

登入、表單與 service worker 需要單獨驗收#

cookie 未指定 path 時，SvelteKit 3 預設使用 /。這讓它適用整個站點；如果某個 cookie 原本刻意限制在子路徑，請繼續明確寫出範圍。升級後實際檢查登入、登出、重新整理和子路徑存取，不只看登入 API 回傳 200。

使用 use:enhance 提交到另一頁 action 時，新版會導向該頁，行為更接近原生表單。請檢查錯誤訊息是否仍顯示在預期頁面、成功後是否回到正確位置，以及返回上一頁時的狀態。

若站點有 service worker，依新版 service worker 文件審查資產與版本來源，並測「舊分頁開著時部署新版本」的情境。只在無快取的新視窗開一次首頁，無法發現舊快取與新資產混用的問題。

Remote functions 在這次正式版公告中仍需要實驗性功能條件。遷移既有應用程式時，先讓原流程穩定，再決定是否導入新功能，避免同時改變框架與資料互動方式。

依這個順序決定能不能部署#

1. 版本、plugin 設定與 alias 檢查通過後，跑專案既有的型別檢查和 build。
2. 以實際 adapter 啟動預覽或測試部署，確認 SSR 頁面、靜態資產、登入及表單。
3. 有反向代理或子路徑時，使用接近正式環境的 URL 驗收導向與 cookie。
4. 測舊分頁遇到新部署、錯誤頁與離線快取，再與升級前的紀錄比較。

若只有 build 通過、登入或表單仍異常，就先維持舊部署。回復時使用升級前那組程式碼、lockfile 和 runtime；只把 Kit 版本降回去，卻留下新版設定與 import，不能視為完整回復。

這篇針對 SvelteKit 應用程式，不適用於只在 Astro 中使用 Svelte 元件的專案。Astro 本身升級可參考 Astro 7 遷移檢查；若安裝後卡在依賴預打包，可再查 Vite error while updating dependencies，不要先把所有問題歸因於新框架。

參考資料：

Svelte：SvelteKit 3 is here

SvelteKit：Migrating to SvelteKit v3

Svelte CLI：sv migrate

SvelteKit：Service workers