SvelteKit 3 升級重點：設定遷移與工具鏈門檻

圖片：TechLab 自製資訊圖

TechLab 編輯部（譯）·2026-10-02

SvelteKit 3 正式版已發布，對使用 SvelteKit 2 的前端及全端團隊而言，這次升級的核心不在於重寫頁面開發方式，而是整理專案設定與底層工具鏈。iThome 報道指出，新版把 SvelteKit 相關設定集中至 Vite 設定檔，舊有的 svelte.config.js 在 3.0 已不再獲支援。若專案仍沿用舊設定架構，升級不能只改套件版本，必須一併處理設定檔與相關建置流程。

最直接的限制是版本門檻。按 iThome 報道，SvelteKit 3 要求 Node 22.17、TypeScript 6、Svelte 5.57.1、Vite 8.0.12 或以上，Svelte 使用的 Vite 外掛亦須升至第 7 版。這表示升級範圍會由 app 程式碼延伸至本機開發環境、持續整合流程及部署用的 runtime；只要其中一環維持舊版本，團隊便未必能順利完成建置或部署。

設定檔統一到 Vite，減少兩套入口

iThome 指出，SvelteKit 2.62 已引入以 vite.config.js 或 vite.config.ts 管理 SvelteKit 設定的做法；3.0 的分別在於正式不再支援 svelte.config.js 這種舊設定方式。新版透過 SvelteKit 的 Vite 外掛載入框架設定，讓建置工具與框架設定集中在同一個設定入口。對新專案來說，設定位置較集中；對已運行多時的專案來說，則需要把原有設定有系統地搬遷。

這項改動的風險，通常不只在設定檔本身能否載入。團隊應檢查儲存在舊設定中的選項是否已完整轉移，並確認本機開發、測試、production build 與部署環境均讀取同一份新設定。這是根據 iThome 所述設定整併作出的實務推論：當設定入口改變，僅以「可成功編譯」作為完成標準並不足夠，仍要驗證原有行為有否隨設定遺漏而改變。

`$lib` 改為 `#lib`，匯入路徑是實際工作量

另一項會廣泛觸及程式碼的改動，是共用程式匯入別名由 $lib 改為 #lib。iThome 報道指，舊有 $lib 是 SvelteKit 提供的簡寫；新版轉用 Node 的套件子路徑匯入機制，交由現有 JavaScript 工具鏈處理。這看似只是字串替換，但它會出現在元件、工具函式、測試程式及可能的設定檔之中，應視為一次全專案盤點，而非零星修補。

對有較長維護歷史的 codebase，建議先搜尋 $lib 的所有使用位置，再按編譯結果及測試覆核 #lib 轉換後的解析情況。若團隊有自行設定路徑別名，也應一併確認不會與新機制衝突。這並非 iThome 對特定專案作出的結論，而是由其指出別名處理由框架專屬方式改交工具鏈後，可合理預期需要特別留意的整合環節。

`sv migrate` 可協助改寫，但不取代審核

iThome 指出，官方提供 sv migrate 遷移工具，可自動處理部分設定與程式碼改動；工具無法決定的部分，則會留下待處理標記。因此，較穩妥的工作方式是把它視為建立改動清單的起點，而不是按一次指令便可直接合併的升級方案。自動化遷移能減少重複修改，但專案特有的設定、匯入方式和部署條件，仍需要開發者判斷。

報道亦提到，官方建議先升至最新的 SvelteKit 2.x，再遷移到 3.0，以便及早找出已標示棄用的功能。這個次序對採用框架較久的團隊尤其重要：先在 2.x 收斂既有警告及棄用項目，可將「舊功能清理」與「主版本相容性修改」拆開處理。從變更管理角度看，問題較容易定位，程式審核也較不會混入太多互不相關的改動。

升級前可把檢查重點整理如下：

範圍	升級時要核對的事項
執行環境	Node 是否至少為 22.17，部署與 CI 使用的版本是否一致
建置工具	TypeScript、Svelte、Vite 及 Svelte Vite 外掛是否符合新版最低要求
專案設定	`svelte.config.js` 的設定是否已遷移至 Vite 設定檔
程式匯入	`$lib` 引用是否已改為 `#lib`，並通過編譯及測試
自動遷移	`sv migrate` 留下的待處理標記是否已逐項完成覆核

不宜把實驗功能當成穩定升級目標

iThome 另指出，SvelteKit 3 調整了環境變數、Service Worker 與錯誤處理方式，但報道未列出各項細節。這正是升級時需要安排完整回歸測試的原因：依賴這些機制的專案，不應只驗證一般頁面能否顯示，還應按自身既有流程測試環境設定、離線相關行為及錯誤情況。沒有列明的改動，不宜自行假定其行為與舊版完全一致。

至於 Remote Functions，iThome 說明它仍屬實驗功能，讓瀏覽器端程式呼叫 server 端函式時可在開發階段檢查資料型別；使用時仍須同時開啟 Remote Functions 與非同步 Svelte 的實驗設定。對正在升級既有產品的團隊而言，這項功能較適合獨立評估，而不宜與必要的 3.0 相容性工作綁在同一個變更中，否則較難判斷問題源自遷移還是實驗功能。

整體而言，SvelteKit 3 對香港使用 SvelteKit 的網站、初創及開發團隊，影響會集中在維護成本與部署相容性，而非日常元件寫法突變。下一步值得留意的是，團隊能否先完成 2.x 的棄用項目清理，再以獨立分支核對 Vite 設定、#lib 匯入和整套工具鏈版本，避免把框架升級變成 production 環境的臨時排錯。