支撑系统：响应式工具类、迁移工具、开发者工具与测试

编译器和响应式引擎是 Svelte 的核心，但一个框架的实际体验，很大程度上取决于围绕这个核心构建的生态系统。本篇将介绍各个支撑子系统：基于信号机制扩展 JavaScript 内置类型的公共响应式工具类、Svelte 4 store 的向后兼容桥接层、自动化升级路径的迁移工具、开发模式工具链、过渡动画运行时，以及确保一切正常运转的测试基础设施。

公共响应式工具类：svelte/reactivity

svelte/reactivity 模块为 JavaScript 内置类型提供了具备信号感知能力的封装。这些类从 reactivity/index-client.js 导出：

export { SvelteDate } from './date.js';
export { SvelteSet } from './set.js';
export { SvelteMap } from './map.js';
export { SvelteURL } from './url.js';
export { SvelteURLSearchParams } from './url-search-params.js';
export { MediaQuery } from './media-query.js';
export { createSubscriber } from './create-subscriber.js';

每个类都封装了对应的原生类型，并将所有变更方法接入信号图。以 SvelteSet 为例，它继承自 Set，并重写了 add()、delete() 和 clear()，在这些方法中调用内部 source 信号的 set()。而 has()、forEach() 等读取方法以及 .size 属性则调用 get() 来注册依赖关系。

所有工具类遵循一致的模式：

1. 继承原生类（或代理原生实例）
2. 为可追踪的状态创建 source 信号
3. 重写变更方法，在其中写入信号
4. 重写读取方法和 getter，在其中读取信号

MediaQuery 有所不同——它封装了 window.matchMedia()，并暴露一个响应式的 .current 属性，在媒体查询匹配状态发生变化时自动更新。createSubscriber 则是更底层的构建块：它创建一个 source 信号，可供外部（非 Svelte）响应式系统订阅。

classDiagram
    class SvelteSet~T~ {
        -#source: Source~number~
        +add(value: T): this
        +delete(value: T): boolean
        +has(value: T): boolean
        +size: number
    }
    class SvelteMap~K,V~ {
        -#source: Source~number~
        +set(key: K, value: V): this
        +get(key: K): V
        +delete(key: K): boolean
    }
    class SvelteDate {
        -#source: Source~number~
        +setTime(ms: number): number
        +getTime(): number
    }
    class MediaQuery {
        -#source: Source~boolean~
        +current: boolean
    }
    SvelteSet --|> Set : extends
    SvelteMap --|> Map : extends
    SvelteDate --|> Date : extends

提示： 当你需要对内置类型实现细粒度响应式时，可以使用这些工具类。$state(new Map()) 会通过 proxy 封装整个 Map，而 new SvelteMap() 则提供了基于 key 的精确响应式，省去了 proxy 的开销。

Store 兼容层：连接 Svelte 4 与 Svelte 5

Svelte 4 的 store 契约——即具有 .subscribe() 方法的对象——在 svelte/store 模块中仍然得到完整支持。客户端版本 store/index-client.js 从共享实现中重新导出了经典的 writable、readable 和 derived store，同时新增了一个桥接函数 toStore()，用于将 Svelte 5 信号转换为 store 契约：

export function toStore(get, set) {
    var init_value = get();
    const store = writable(init_value, (set) => {
        // Subscribe to signal changes via render_effect
        // ...
    });
    return store;
}

$ 前缀自动订阅语法（$storeName）在 Svelte 5 组件中依然有效。编译器会识别 store 引用，并生成内部客户端运行时的 $.store_get() / $.store_set() 调用。当项目中存在 Svelte 4 组件时，legacy_mode_flag（详见第 1 篇）会在运行时启用额外的兼容代码路径。

与主包入口一样，svelte/store 在 package.json 中也区分了客户端和服务端版本：

"./store": {
    "worker": "./src/store/index-server.js",
    "browser": "./src/store/index-client.js",
    "default": "./src/store/index-server.js"
}

迁移工具：从 Svelte 4 到 Svelte 5

从 svelte/compiler 导出的 migrate() 函数，可以自动将 Svelte 4 组件转换为 Svelte 5 语法。它复用了编译器的解析和分析阶段，然后通过 MagicString 在文本层面进行精准转换——MagicString 是一个支持保留 source map 的字符串操作库。

处理流程如下：

flowchart TD
    Source["Svelte 4 source"] --> Parse["parse() → AST"]
    Parse --> Analyze["analyze_component() → metadata"]
    Analyze --> Walk["walk AST with migration visitors"]
    Walk --> Magic["MagicString transforms"]
    Magic --> Output["Svelte 5 source"]

主要迁移内容包括：

• export let prop → let { prop } = $props()
• $: derived = expr → const derived = $derived(expr)
• $: { sideEffect() } → $effect(() => { sideEffect() })
• <slot> → {@render children()}
• on:click={handler} → onclick={handler}
• CSS :global() 用法更新

迁移工具定义了一个 MigrationError 类，用于处理无法自动迁移的情况（例如，模式过于模糊、无法安全转换）。遇到这类情况时，工具会插入 TODO 注释，说明开发者需要手动修改的内容。

MagicString 的关键优势在于它直接操作原始源字符串，而非 AST。这意味着它可以精确地将 export let 替换为 let { ... } = $props()，同时保留那些在 AST 往返转换中会丢失的空白字符、注释和格式。.snip()、.overwrite() 和 .appendLeft() 等方法可以在不影响周围代码的前提下进行定点编辑。

开发模式功能

当编译器选项设置 dev: true 时，Svelte 会在输出中注入额外的检查和调试支持。

Rune 全局变量

客户端入口 index-client.js 会在开发模式下为全局对象安装 $state、$effect、$derived、$inspect 和 $props 的 getter。当 rune 在 .svelte 文件之外被使用时，这些 getter 会抛出友好的错误信息：

if (DEV) {
    function throw_rune_error(rune) {
        if (!(rune in globalThis)) {
            Object.defineProperty(globalThis, rune, {
                get: () => { e.rune_outside_svelte(rune); }
            });
        }
    }
    throw_rune_error('$state');
    throw_rune_error('$effect');
    // ...
}

所有权追踪

内部客户端索引中导出的 create_ownership_validator，可以检测子组件是否修改了不属于自己的 props。在开发模式下，每个 effect 会追踪创建它的组件函数，从而在响应式状态被错误上下文修改时发出警告。

信号追踪

当使用 $inspect.trace() 且启用了 tracing_mode_flag 时，运行时会为 source 信号附加创建和更新时的调用栈。tag 和 tag_proxy 函数会为信号添加调试标签（取自源码中的变量名），使其在开发者工具中可被识别。

HMR 支持

hmr 导出提供了热模块替换支持。在开发过程中，当组件源码发生变更时，HMR 系统可以原地更新组件，无需完整刷新页面。组件函数会被包裹在一个支持 HMR 的容器中，从而实现实现的热替换。

flowchart TD
    subgraph "Dev Mode Features"
        Runes["Rune Globals<br/>Helpful errors outside .svelte"]
        Ownership["Ownership Tracking<br/>Prop mutation detection"]
        Tracing["Signal Tracing<br/>$inspect.trace() stack traces"]
        HMR["HMR Support<br/>Hot component replacement"]
    end
    DEV["DEV flag<br/>(esm-env)"] --> Runes
    DEV --> Ownership
    Tracing_Flag["tracing_mode_flag"] --> Tracing
    DevOption["dev: true<br/>(compiler option)"] --> Ownership
    DevOption --> HMR

过渡动画运行时

Svelte 的 transition:、in:、out: 和 animate: 指令，在编译后会生成对内部客户端运行时中 transition() 和 animation() 的调用。

过渡系统负责将 CSS 动画与 effect 生命周期协调起来。当一个 block effect 创建新的 DOM 节点（进入阶段）时，运行时调用过渡函数，生成 CSS 动画配置——包括关键帧、时长和缓动函数。当一个分支 effect 被暂停（离开阶段）时，运行时会先播放退出过渡动画，再将 DOM 节点移除。

过渡动画会在目标元素上派发自定义事件（introstart、introend、outrostart、outroend），让组件能够感知过渡状态。dispatch_event 函数使用 without_reactive_context() 来执行派发，防止过渡事件处理函数意外创建响应式依赖。

过渡函数本身（如 svelte/transition 中的 fade、fly、slide）返回一个包含 CSS 或 tick 函数的 AnimationConfig。当返回的是 CSS 过渡时，运行时使用 Web Animations API（Element.animate()）来执行动画，并通过 css_property_to_camelcase() 将属性名转换为关键帧所需的驼峰格式。

animate: 指令用于 FLIP 动画，工作方式有所不同——它会在元素重排前后分别捕获其位置，然后在两个状态之间创建动画。这也是为什么 animate: 只能用于带 key 的 {#each} 块中的元素。

sequenceDiagram
    participant Block as Block Effect
    participant Transition as transition()
    participant Element as DOM Element
    participant WAA as Web Animations API

    Block->>Element: Branch created (entering)
    Block->>Transition: transition(element, config, TRANSITION_IN)
    Transition->>Transition: Get keyframes + duration
    Transition->>WAA: element.animate(keyframes, options)
    Transition->>Element: dispatch 'introstart'
    WAA-->>Transition: Animation complete
    Transition->>Element: dispatch 'introend'

    Note over Block: Later: condition changes
    Block->>Transition: transition(element, config, TRANSITION_OUT)
    Transition->>Element: dispatch 'outrostart'
    Transition->>WAA: element.animate(keyframes, options)
    WAA-->>Transition: Animation complete
    Transition->>Element: dispatch 'outroend'
    Block->>Element: Remove from DOM

提示： TRANSITION_GLOBAL 标志决定过渡动画的触发范围——是仅在直接父级 block 变化时播放（局部），还是在任意祖先 block 变化时都播放（全局）。这正是 transition:fade 与 transition:fade|global 的本质区别。

测试基础设施与贡献指南

Svelte 的测试套件使用 Vitest，配置文件位于 vitest.config.js。配置中的自定义解析器至关重要——它根据测试上下文将 svelte/* 导入映射到正确的源文件，模拟条件导出的行为。

测试按类别组织在 packages/svelte/tests/ 下：

目录	测试内容
runtime-runes/	Svelte 5 组件行为（默认模式）
runtime-legacy/	Svelte 4 兼容模式
compiler-errors/	预期的编译失败——每个样例包含一个 .errors.json
compiler-warnings/	预期的诊断警告
hydration/	SSR 输出与客户端 hydration 的一致性
signals/	底层响应式（source、derived、effect）
snapshot/	通过快照文件验证编译输出的稳定性
css/	CSS 作用域、裁剪与输出

大多数测试类别遵循样例模式：每个测试用例是一个目录，包含一个 .svelte 组件、一个带有断言的 _config.js 文件，以及可选的预期输出文件。_config.js 导出一个测试函数，负责挂载组件、模拟交互并断言 DOM 状态。

flowchart LR
    Sample["tests/runtime-runes/samples/my-test/"]
    Sample --> Component["main.svelte<br/>The component under test"]
    Sample --> Config["_config.js<br/>Mount, interact, assert"]
    Sample --> Expected["_expected.html (optional)<br/>Expected DOM output"]
    Vitest["vitest"] --> Sample
    Sample --> Result["Pass / Fail"]

贡献指南

新增错误或警告时，工作流会利用第 1 篇介绍的 Markdown 消息处理流水线：

1. 在 messages/ 中的对应文件里添加消息内容
2. 运行 node scripts/process-messages 生成 JavaScript 代码
3. 在编译器或运行时中调用生成的函数（例如 e.my_new_error(node)）
4. 在对应的测试类别中添加测试用例

新增编译器功能时，通常需要修改三个阶段：

1. Parser——如果涉及新语法，添加对应的状态处理
2. Analysis visitor——验证用法并收集元数据
3. Transform visitor——生成对应的运行时调用（客户端和服务端均需处理）
4. Runtime function——在 internal/client/ 或 internal/server/ 中实现具体行为

tests/snapshot/ 中的快照测试尤为有价值：它们捕获了各种组件模式的精确编译输出。每次修改编译器后，运行这些测试可以直观地看到变更对生成代码的影响。在确认 diff 无误后，可以用 vitest --update 更新快照。

系列总结

历经五篇文章，我们完整走过了 Svelte 5 代码库的全貌：

1. 架构——编译器与运行时的双层设计、条件导出机制，以及内部 ABI
2. 编译器——三个阶段（解析 → 分析 → 转换）如何生成优化后的 JavaScript
3. 响应式——基于拉取模型的信号系统、位标志、惰性 derived 与批量调度
4. DOM 渲染——模板克隆、控制流 block、hydration 协议与 SSR
5. 支撑系统——响应式工具类、迁移工具、开发者工具、过渡动画与测试

Svelte 代码库在其复杂度下保持着令人称道的清晰组织。编译器与运行时的明确分离、一致的模块级状态模式、由 Markdown 驱动的错误消息流水线，以及完善的测试套件，无不体现出这个代码库在性能与可维护性上的精心设计。无论你是在贡献修复、构建工具链，还是单纯对现代框架的底层机制感到好奇，你现在已经拥有了探索这片领域的完整地图。