2026-10-02 — SvelteKit 3 發布：設定搬進 vite.config，$lib 改為 #lib

SvelteKit 3 發布：設定搬進 vite.config，$lib 改為 #lib

Svelte 官方部落格 · 2026-10-01

SvelteKit 3 把專案設定從 svelte.config.js 搬進 vite.config.js 的 sveltekit() 外掛，並把 $lib 別名換成 Node 標準的 subpath imports #lib。官方將它描述為「同一個框架，多一點打磨、多一點型別安全、少一點雜物」，但遷移指南列出的 breaking changes 不少，升級前要逐項檢查。

Svelte 團隊於 2026-10-01 發布 SvelteKit 3.0，並附上自動遷移工具 migrating-to-sveltekit-3。

原本的問題

SvelteKit 2 的專案同時有 svelte.config.js 與 vite.config.js 兩份設定，而 SvelteKit 其實跑在 Vite 之上。設定分散在兩處，別名 $lib 又是 SvelteKit 自己的特例，Node 與其他工具鏈不認得，需要額外對應。

另外，錯誤處理、goto() 選項、cookie 預設路徑等 API 長年累積了各自的慣例。v3 趁大版本一次整理。

核心改動

設定與別名是日常最先撞到的兩項。adapter 等 kit 選項改傳給 sveltekit()，別名改由 package.json 的 imports 欄位宣告。

// before: svelte.config.js
export default { kit: { adapter: adapter() } };

// after: vite.config.js
export default defineConfig({
  plugins: [sveltekit({ adapter: adapter() })]
});

// before
import { foo } from '$lib/foo';
// after（package.json 需有 "#lib/*": "./src/lib/*"）
import { foo } from '#lib/foo.js';

模組搬家：$app/stores 移除，改用 $app/state，$page.url 變成 page.url，且 page.url 現在是唯讀，要改 query 得自己 new URL(page.url.href)。$service-worker 也移除，改從 $app/env、$app/manifest、$app/paths 取值。

環境變數走新的明確宣告：在 src/env.ts 用 defineEnvVars 定義，搭配 valibot 之類的 schema 驗證，再從 $app/env/private 或 $app/env/public 匯入。文件指出 $env/* 在 v3 已棄用、預計 v4 移除，這套機制自 SvelteKit 2.62 起以實驗性功能提供。

Service worker 的文件現在以 src/service-worker/index.ts（或 .js）為入口，檔案存在就會被打包並自動註冊，且只在 production 打包、開發模式不打包。它改從 $app/service-worker、$app/env、$app/manifest 取得 self、version、immutable 與 assets。型別設定需在該目錄另放一份 tsconfig.json，並在根目錄的 tsconfig 排除 src/service-worker，舊的 $service-worker 匯入要一併改掉。

文件中的預設註冊程式碼也考慮了 Trusted Types：若瀏覽器支援，會先建立名為 sveltekit-trusted-url 的 policy 再註冊腳本。有啟用 CSP 的站台要確認這個 policy 名稱沒有被 trusted-types 指令擋掉；文件未說明 CSP 要如何設定，請自行實測。

其他會讓程式行為改變的項目

下面幾項不會在編譯期報錯，卻會改變執行結果，需要主動檢查：

cookies.set() 的 path 預設改為 /，過去預設是目前請求路徑。依賴舊行為的子路徑 cookie 要明確傳 { path }。
enhanced form 回傳 fail() 指定的 HTTP 狀態碼，不再一律 200。前端若以 status 判斷成功與否要跟著看。
handleError 現在也接收用 error() 建立的預期錯誤；error() 的第二個參數必須是字串，額外欄位移到第三個參數。
導向外部網址的 redirect() 必須加 { external: true }。
CSRF 設定的 checkOrigin: false 換成 trustedOrigins 清單；跨來源表單提交需帶 Content-Type 標頭，或把來源加入該清單。

// before
error(404, { message: 'Not found', code: 'E001' });
// after
error(404, 'Not found', { code: 'E001' });

導航 API 也調整：pushState／replaceState 改為 goto(url, { shallow: true, state })，invalidateAll() 改名 refreshAll()，keepFocus 加 noScroll 合併成 reset: false。參數 matcher 從 src/params/ 多檔案改為單一 src/params.ts，用 defineParams 定義。

影響範圍

最先被擋下的是環境版本。遷移指南要求 Node v22.17、TypeScript v6、Svelte v5.57.1、Vite v8.0.12、@sveltejs/vite-plugin-svelte v7 為最低版本，CI 映像與本機 Node 若停在較舊版本，要先升級才能裝得起來。

部署端也有變動，依 adapter 分別是：

adapter-node：改用 rolldown 打包，ORIGIN 環境變數移除，ETag 改用內容雜湊。靠 ORIGIN 設定反向代理後來源的部署要改設定。
adapter-cloudflare：改從 cloudflare:workers 匯入 env、waitUntil。
adapter-netlify：需要 Netlify CLI v17.31.0 以上。
adapter-vercel：不再支援 edge runtime，仍跑 edge 的路由要改用其他 runtime。

HTML 裡的 data-sveltekit-preload-data="off" 這類屬性值也改成 "false"，用字串搜尋全專案即可找到。

官方提供自動遷移指令，既有專案執行後再逐項比對上面的行為變更即可：

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

發布文章另提到 Remote Functions 仍在開發中，使用 Async Svelte 需要實驗性旗標；遷移工具是否涵蓋行為層級的改動（例如 cookie path），release 文章與遷移指南均未說明。

原始來源：SvelteKit 3 is here、Migrating to SvelteKit 3、Environment variables

End of article