Svelte 深度知識
請將其作為可能的知識缺口索引使用。在規劃與實作期間，請依據官方 Svelte MCP 驗證相關 API。
驗證日期：2026-11-01，對應 Svelte 5.57.3、SvelteKit 3.1.1 以及 SvelteKit 2.70.3。
從已安裝的版本開始
- 檢查套件版本與 Vite 設定。根據已安裝的 Kit 主版本號與啟用的實驗性標記來比對指引。
- 呼叫 Svelte MCP 的
list-sections，然後連同get-documentation一起擷取相關章節。MCP 與 svelte.dev 提供 Kit 3 的文件。若是 Kit 2 專案，請從sveltejs/kit的version-2分支下的documentation/docs讀取對應頁面。 - 對於 Kit 3 專案以及 Kit 2 升級至 Kit 3 的遷移，請閱讀 Kit 3 參考文件。對於 Kit 2 專案，請閱讀 Kit 2 參考文件。
- 在新建立或編輯的 Svelte 元件/模組上執行
svelte-autofixer，並解決所有適用的發現。使用專案的檢查機制處理整合與型別。
如需新的 Svelte API、非同步渲染、附件與編譯器工具的範例，請閱讀 Svelte 參考文件。
遠端函式、邊界與 await
對於採用實驗性非同步功能的新的 SvelteKit 應用程式，請優先使用帶有直接 await 的遠端函式來取得元件資料，並使用精細邊界來處理載入/錯誤 UI。根據哪些內容必須在伺服器上渲染來選擇 svelte:boundary 的位置。
- 同時啟用
experimental.remoteFunctions與compilerOptions.experimental.async。官方的遠端函式設定需要這兩個標記。 load、表單動作 (form actions) 與+server路由仍然受支援，但不鼓勵使用。除非任務包含遷移工作，否則請遵循現有架構。.loading、.error與.current仍然是受支援的查詢 API。直接await是偏好的機制。- 在渲染與命令式上下文中使用
await query(args)。 {#await}仍然受支援，但不鼓勵使用，並且有其自身的 Promise 狀態行為。請使用直接 await 與邊界來協調非同步渲染；若{#await}的行為符合任務需求，則保留它。
請透過 MCP 章節 kit/remote-functions、svelte/await-expressions 與 svelte/svelte-boundary 進行驗證。
非同步渲染行為
- 元件層級的 await 在 Svelte 5.36 中引入；非同步 SSR 在 5.39 中引入。Await 在頂層 script、
$derived以及標記語言中皆受支援。 - Svelte 在非同步工作解析的同時，協調相依的 UI 更新。獨立的模板 await 表達式會並行執行。順序的 script await 仍然會產生瀑布效應；在 await 其結果之前，應先啟動獨立的工作。
- 邊界的
pending片段在初始建立時出現。對於該邊界內的後續工作，請使用$effect.pending()；其計數不包含子邊界。 - 在 SSR 期間，帶有
pending的邊界會渲染佔位符，並跳過其內容。在此類邊界之外的 await 表達式會在await render(...)完成之前解析。請相應地將需要在初始 HTML 中出現的內容放置好。此 API 尚不提供串流 SSR。 $state.eager(value)（5.41 中引入）在協調更新等待時，提供即時回饋。將其用於使用者回饋，例如活躍的導航指示器。tick()會等待待處理的狀態變更；settled()（5.36 中引入）還會等待由這些變更引起的非同步工作以及隨之而來的 DOM 更新。
錯誤邊界
<svelte:boundary>支援failed(error, reset)與onerror(error, reset)來處理渲染/效果失敗。事件處理器與分離的非同步錯誤請在其呼叫處處理。- 自 Svelte 5.53 起，
failed片段也會在 SSR 期間捕獲錯誤。在 SvelteKit 中，錯誤會先通過handleError，因此片段接收的是已清理過的App.Error。onerror在失敗的邊界進行水合（hydration）時執行。 - Kit 3 會將渲染錯誤透過
handleError發送給最近的+error.svelte，後者充當邊界。非同步的用戶端handleError需要compilerOptions.experimental.async。Kit 2.54+ 需要experimental.handleRenderingErrors來實現相同的整合。 - 邊界文件中舊的「自 5.51 起」的註記與已發布的變更日誌相衝突。請使用 5.53 作為引入版本，並在診斷 SSR/水合問題時檢查當前的修補程式。
模板功能
宣告標籤，Svelte 5.56+
- 優先使用
{let ...}與{const ...}來處理標記語言區域變數。{@const}被標記為舊版，但仍可用於較舊的專案。 - 普通宣告用於初始化值。請使用明確的 Runes 來實現響應性：
{let count = $state(0)}與{const doubled = $derived(count * 2)}。 - 遷移響應性的
{@const area = width * height}需要{const area = $derived(width * height)}。普通的{const area = width * height}不具響應性。 - 宣告在其元素/區塊內使用詞法作用域，可以遮蔽外部變數，並且應在使用前宣告。支援多個宣告式。
附件 (Attachments)
- 對於 Svelte 5.29+ 上的新元素整合，優先使用
{@attach ...}。從附件中回傳清理函式。 - 附件會追蹤響應式讀取，並在相依項目變更時重新執行。假值會使其失效。透過在子效果內部的 getter 讀取變化的選項，避免重複執行昂貴的設定。
- 元件包裝器必須將攜帶附件的 props 轉發到目標元素。
createAttachmentKey()支援在展開物件中使用附件。 fromAction(action, () => argument)保留現有動作的行為。其第二個參數是一個 getter。此輔助函式在 5.32 中引入，晚於附件本身。
類別、繫結與 HTML
- 自 5.16 起，
class接受巢狀陣列與物件。svelte/elements中的ClassValue自 5.19 起可用於包裝器 props。 - 函式繫結自 5.9 起使用
bind:value={get, set}。對於唯讀繫結，使用null作為 getter。 - 數字輸入在為空或無效時可能產生
undefined。核取方塊狀態可使用bind:checked與bind:indeterminate；選項按鈕群組使用bind:group。 - 自 5.6 起，輸入支援
defaultValue/defaultChecked。自 5.57 起，選擇框支援defaultValue，包括表單重設行為。在提供預設值時檢查繫結優先級。 - 自 5.47 起，支援可自訂的原生選擇框。在取代自訂選擇框小工具之前，請檢查瀏覽器支援情況與文件記錄的
<selectedcontent>模式。 - 自 5.53 起，屬性之間的 JavaScript 風格註解有效：
<div /* explanation */ class="card">。 - 自 5.52 起，
{@html}接受TrustedHTML。Trusted Types 支援不會清理任意輸入；請使用受信任的來源或清理政策。
Each 區塊與 Snippets
{#each items as { id, name }}解構項目。範圍迭代可使用{#each { length: 8 }, index}。- 對於其身分重要的列表，優先使用穩定的項目鍵。在編輯項目時，透過項目物件繫結其屬性，以便讓修改操作抵達來源。
- Snippets 在標記語言中宣告，並使用
{@render snippet(...)}渲染。自 5.5 起，如果頂層 snippets 不捕獲實例狀態，則可以從<script module>匯出。 - 自 5.30 起，Snippets 支援泛型。元件泛型使用
<script lang="ts" generics="T">。 - 在 Runes 模式下，元件變數會動態渲染為
<Component />。遞迴元件可以匯入自身。
Runes 與共享狀態
狀態與 Props
$state.raw在不進行深層代理的情況下追蹤重新賦值。將其用於整體替換的大型值。$state.snapshot提取純資料並尊重toJSON()。- 類別實例不會被深層代理。使用
$state欄位，或自 5.31 起使用它們的首次建構子賦值。響應式欄位變為不可列舉的存取器；將方法作為回呼傳遞時，請保留this。 - 將響應式值傳遞給函式時，傳遞的是其當前值。當函式需要未來值時，請傳遞一個 getter。解構代理也會讀取當前值。
- 使用
.svelte.js/.svelte.ts來處理共享的 rune 邏輯。當消費者需要變化的狀態時，匯出一個穩定的狀態物件或存取器；直接匯出重新賦值的 rune 狀態會受到限制。 - 在 SSR 期間，透過元件上下文來限定使用者特定狀態的作用域。共享模組狀態可能會在請求之間洩漏。
$props.id()（5.20 中引入）提供一個與 SSR 和水合匹配的元件實例 ID。$bindable()宣告一個可繫結的 prop。Props 可以在本地重新賦值；修改父元件的不可繫結代理會觸發所有權警告。回退值不會被自動代理。- 保留
$state<T>()的實際未初始化型別（包含undefined），或提供一個有效的初始值。在存取點使用型別縮小。
派生值 (Deriveds) 與效果 (Effects)
- 使用
$derived(expression)或$derived.by(fn)來處理計算值。自 5.25 起，用let宣告的派生值可以為樂觀 UI 重新賦值；相依項目的變更會重新計算它們。 - 解構的
$derived值保持響應性。回傳的物件不會自動成為深層代理。引用相等性可以跳過下游工作。 - 效果會追蹤其最新執行的同步讀取。在 await 之後的普通非同步回呼內的讀取不會自動成為相依項目。
$effect在瀏覽器中執行。同步回傳清理函式；將效果保留給外部同步，並將使用者觸發的工作放在處理器中。$effect.tracking()偵測追蹤上下文。$effect.root()建立一個手動管理的作用域並回傳一個 dispose 函式。getAbortSignal()（5.35 中引入）必須在效果或派生值內部執行。其訊號會在重新執行或銷毀時中斷。將其用於該響應式計算所擁有的 fetch 工作。untrack(fn)將讀取排除在相依性追蹤之外。$inspect(...).with(fn)接收"init"/"update"後接值。$inspect.trace(label?)（5.14 中引入）必須是所追蹤函式中的第一個陳述式。$host()用於自訂元素，並回傳其宿主 DOM 元素。
執行階段模組
createContext<T>()自 5.40 起提供型別化的上下文。自 5.57 起，它回傳[get, set, has]；has()在get()之前檢查可用性，後者在未設定時會拋出錯誤。上下文查詢包含當前元件及其祖先。在初始化期間呼叫上下文存取器，並在 script 中的第一個await之前設定上下文。自 5.57.1 起，在 SSR 期間，後續的setContext會拋出set_context_after_init錯誤。svelte/reactivity提供SvelteMap、SvelteSet、SvelteDate、SvelteURL與SvelteURLSearchParams。Map/Set 條目不會被深層響應化。- Svelte 5.57 新增
SvelteMap.getOrInsert(key, value)與getOrInsertComputed(key, key => value)。計算回呼在鍵值不存在時執行，包括正確處理現有的undefined條目。 MediaQuery與createSubscriber於 5.7 中引入。使用createSubscriber將外部事件連接到追蹤讀取，並共享訂閱設定與清理。MediaQuery接受 SSR 回退值；當 CSS 可以表達相同行為時，請使用 CSS。svelte/reactivity/window自 5.11 起提供響應式的.current值，用於尺寸、滾動位置、線上狀態、螢幕位置與像素比。請考慮 SSR 期間無法使用 window 值的情況。svelte/events中的on()保留與宣告式事件處理器的順序，並回傳清理函式。使用<svelte:window>/<svelte:document>進行宣告式的全域監聽器。flushSync(fn?)同步刷新待處理的更新。createRawSnippet支援帶有設定/清理的程序化標記。getAllContexts()提供當前上下文映射以用於程序化掛載；在初始化期間呼叫它。svelte/motion中的Spring與Tween自 5.8 起取代了已棄用的spring()/tweened()儲存。兩者都暴露.target、.current、.set()與.of(fn)。Spring.set支援preserveMomentum；prefersReducedMotion支援無障礙動畫。- 自 5.55 起，動畫匯出包含
TweenOptions、SpringOptions、SpringUpdateOptions與Updater。 hydratable(key, fn)（5.44 中引入）序列化資料以便在水合期間重用。它使用 devalue 並支援巢狀 Promise。使用命名空間鍵以避免衝突。Kit 的遠端函式已處理此層級。- 在使用 CSP 時，自訂 SSR 整合必須為
render設定每個回應的 nonce 或靜態雜湊，並將匹配值放入回應標頭。Svelte 5.46 新增了渲染 CSP 支援；5.57 從svelte/server匯出了RenderOutput、SyncRenderOutput、Csp與Sha256Source。 - 對於工具，
print()自 5.45 起將現代 Svelte AST 轉換為原始碼；parseCss()於 5.48 中引入。編譯器選項css、runes與customElement自 5.54 起可以是依檔名決定的函式。在使用這些 API 之前，請閱讀 Svelte 參考文件。
SvelteKit
新應用程式使用 Kit 3（npx sv create）。使用 npx sv migrate sveltekit-3 遷移一個 Kit 2 應用程式，然後處理生成的 TODO。Kit 2 指引僅適用於停留在 2.x 的專案。
Kit 3 基準
- Kit 3 需要 Node 22.17、TypeScript 6、Svelte 5.57.1、Vite 8.0.12 與 vite-plugin-svelte 7。
- 設定存在於
vite.config.ts內部的sveltekit({...})中，Kit 選項位於compilerOptions旁邊的頂層。Kit 3 不再讀取svelte.config.js。 #lib透過 package.json 的子路徑匯入取代$lib。請撰寫副檔名，例如#lib/server/db.ts。server檔案名稱片段，或src/routes外部的任何server目錄，將模組標記為僅限伺服器。remote檔案名稱片段（例如data.remote.ts或remote.ts）將模組標記為遠端模組。- 在
src/env.ts中使用@sveltejs/kit/env的defineEnvVars宣告環境變數。從$app/env/private與$app/env/public匯入值，並從$app/env匯入browser、building、dev、version。公開變數可以作為%sveltekit.env.NAME%出現在app.html中。$env/*與$app/environment是已棄用的別名。 $app/stores已被移除；請使用$app/state。page.url是唯讀的；使用new URL複製它
…
[為翻譯而截斷]