Svelte 5 代码库架构：一张导览地图

大多数框架要么是编译器，要么是运行时。Svelte 两者兼具。一个 .svelte 文件经过编译器处理后生成优化过的 JavaScript，而这段 JavaScript 会调用运行时来管理响应式、DOM 更新和生命周期。理解这种双重性——以及两者之间的契约——是读懂 Svelte 代码库的关键。本文将为你建立这套心智模型。

Monorepo 结构与包布局

Svelte 的代码仓库是一个 monorepo，但与众不同的是：它只发布一个 npm 包。packages/svelte 目录包含编译器、运行时、公共 API 以及所有支撑基础设施。其余内容——演练场、文档脚手架、性能基准测试——则位于仓库根目录或同级目录中。

核心包的目录结构如下：

路径	用途
packages/svelte/src/compiler/	三阶段编译器：parse → analyze → transform
packages/svelte/src/internal/client/	客户端运行时（响应式、DOM、effects）
packages/svelte/src/internal/server/	服务端运行时（SSR 渲染器、context）
packages/svelte/src/internal/flags/	用于 tree-shaking 的特性标志
packages/svelte/src/reactivity/	公共响应式工具（SvelteDate、SvelteSet 等）
packages/svelte/src/store/	Svelte 4 store 兼容层
packages/svelte/src/index-client.js	客户端公共 API 入口
packages/svelte/src/index-server.js	服务端公共 API 入口
packages/svelte/messages/	以 Markdown 定义的错误与警告信息
packages/svelte/scripts/	构建脚本（消息处理、类型生成）

packages/svelte/package.json 将包声明为 "type": "module"，并定义了详尽的 exports 映射——正是这个机制使整个客户端/服务端的分离得以实现。

双重本质：编译器 + 运行时

Svelte 的架构可以用一句话概括：编译器生成的代码会调用运行时。当你写下 let count = $state(0) 时，编译器会将其转换为对 $.state(0) 的调用，其中 $ 是通过 import * as $ from 'svelte/internal/client' 引入的内部运行时模块。

flowchart LR
    A[".svelte file"] --> B["Compiler<br/>(parse → analyze → transform)"]
    B --> C["JavaScript module<br/>(import * as $ from 'svelte/internal/client')"]
    C --> D["Runtime<br/>($.state, $.effect, $.if, $.each, ...)"]
    D --> E["DOM"]

编译器入口 packages/svelte/src/compiler/index.js 对外暴露四个公共函数：compile()、compileModule()、parse() 和 migrate()。其中 compile() 负责编排整个三阶段流水线——parse、analyze、transform——并返回一个包含 JavaScript 代码、source map、CSS 输出和警告信息的 CompileResult。

运行时入口 packages/svelte/src/internal/client/index.js 是一个巨大的 barrel 文件，重新导出了 100 余个函数。这些就是"ABI"——编译产物所依赖的应用二进制接口。编译代码中每一个 $.if()、$.each()、$.state()、$.derived() 调用，最终都会解析到这个文件的某个导出。

提示： 当你在编译后的 Svelte 输出中看到 $.something() 时，可以在 src/internal/client/index.js 中搜索对应的导出，从而找到实际的实现。

条件导出与客户端/服务端分离

package.json 中的 exports 映射，直观地呈现了 Svelte 的环境感知设计。来看根入口的定义：

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

当 bundler 解析 import { mount } from 'svelte' 时，会根据目标环境选择对应的文件。浏览器构建使用 index-client.js，Node.js/SSR 环境则使用 index-server.js。这一模式在各子路径中同样适用：svelte/store、svelte/reactivity 和 svelte/legacy 都有各自的客户端/服务端分支。

flowchart TD
    Import["import { mount } from 'svelte'"]
    Import -->|"browser condition"| Client["index-client.js<br/>Real mount(), hydrate(), onMount()"]
    Import -->|"default condition"| Server["index-server.js<br/>Stubs: mount() throws, onMount = noop"]

服务端入口 packages/svelte/src/index-server.js 的设计颇具启发性。onMount、beforeUpdate、afterUpdate 等函数被导出为 noop，在服务端什么都不做。mount() 和 hydrate() 则会抛出错误，因为在 SSR 阶段调用它们本身就是一个 bug。与此同时，onDestroy 在服务端是真实可用的（它会挂接到 SSR 渲染器中），context 相关函数（getContext、setContext）也有完整的服务端实现。

客户端入口 packages/svelte/src/index-client.js 则展示了更微妙的一面：在 runes 模式下，onMount 会创建一个 user_effect——它是基于新的信号（signal）effect 系统实现的，而非独立的原语。

这种条件分离同样适用于内部模块。编译器会根据目标环境（客户端或服务端）生成不同的输出，分别从 svelte/internal/client 或 svelte/internal/server 导入。

内部运行时 ABI

packages/svelte/src/internal/client/index.js 是编译产物与运行时之间的契约接口。它按类别导出函数：

类别	示例	来源
控制流块	if_block, each, await_block, key	dom/blocks/*.js
模板创建	from_html, from_tree, from_svg, text	dom/template.js
响应式原语	state, derived, effect, render_effect	reactivity/*.js
DOM 操作	set_attribute, set_class, set_style	dom/elements/*.js
绑定	bind_value, bind_checked, bind_this	dom/elements/bindings/*.js
组件生命周期	push, pop, init	context.js, dom/legacy/lifecycle.js
过渡动画	transition, animation	dom/elements/transitions.js

每个编译后的组件都包含这样的核心 import：

import * as $ from 'svelte/internal/client';

这种命名空间导入方式让 bundler 可以对未使用的函数进行 tree-shaking。如果你的组件没有用到 {#each}，$.each() 的实现就会从最终产物中被移除。

graph TD
    subgraph "Compiled Component"
        A["$.state(0)"]
        B["$.template_effect(...)"]
        C["$.if(node, fn)"]
    end
    subgraph "svelte/internal/client"
        D["sources.js → state()"]
        E["effects.js → template_effect()"]
        F["blocks/if.js → if_block()"]
    end
    A --> D
    B --> E
    C --> F

特性标志与死代码消除

Svelte 5 在 packages/svelte/src/internal/flags/index.js 中定义了三个特性标志：

export let async_mode_flag = false;   // experimental.async=true
export let legacy_mode_flag = false;  // Svelte 4 compatibility
export let tracing_mode_flag = false; // $inspect.trace debugging

这些是模块级的 let 变量，默认值为 false。当需要时，编译器会生成相应的 import 语句来启用它们。例如，当项目中存在 Svelte 4 组件时，编译输出会包含 import 'svelte/internal/flags/legacy'，从而调用 enable_legacy_mode_flag()，将该布尔值置为 true。

flowchart LR
    Compiler["Compiler detects<br/>legacy component"] --> Import["Generated: import 'svelte/internal/flags/legacy'"]
    Import --> Enable["enable_legacy_mode_flag()<br/>legacy_mode_flag = true"]
    Enable --> Runtime["Runtime code paths:<br/>if (legacy_mode_flag) { ... }"]

这一设计的精妙之处在于 tree-shaking：如果 legacy_mode_flag 从未被设置为 true，bundler 就能判定所有受 if (legacy_mode_flag) 保护的分支是死代码并将其移除。这意味着纯 Svelte 5 项目完全不需要为 Svelte 4 兼容代码付出任何 bundle 体积的代价。

提示： 在研究某个运行时代码路径时，如果看到类似 if (legacy_mode_flag && ...) 的标志守卫，在学习现代 Svelte 5 行为时通常可以直接跳过该分支。

基于 Markdown 的错误与警告信息管理

Svelte 中的每一条错误和警告——无论是编译器诊断、客户端运行时错误，还是服务端错误——都在 packages/svelte/messages/ 下的 Markdown 文件中定义。例如，messages/compile-errors/template.md 中包含如下条目：

## animation_duplicate

> An element can only have one 'animate' directive

构建脚本 packages/svelte/scripts/process-messages/index.js 读取这些 Markdown 文件，并生成导出了对应函数的 JavaScript 模块。每个错误代码都会成为一个可调用的函数：e.animation_duplicate(node)。

flowchart TD
    MD["messages/compile-errors/template.md"] --> Script["scripts/process-messages/index.js"]
    Script --> JS["src/compiler/errors.js<br/>(generated)"]
    Script --> Docs["documentation/.generated/<br/>compile-errors.md"]
    JS --> Compiler["Compiler calls e.animation_duplicate()"]

这种方式带来了三个显著优势：

1. 单一数据源 — 错误信息文本、错误代码和文档均来自同一个 Markdown 文件
2. 统一格式 — 每条错误都遵循相同的结构（代码、消息、可选详情）
3. 自动生成文档 — 同一份 Markdown 会被转换为文档页面

消息分类与代码库结构保持对应：compile-errors、compile-warnings、client-errors、client-warnings、server-errors、server-warnings，以及共享的变体。

构建系统与测试概览

构建流程相对简洁。编译器通过 Rollup 打包为 CommonJS 模块（供 Node.js 以 require() 方式使用）。运行时则以原生 ES modules 形式发布，无需额外打包，由下游工具负责处理。

测试使用 Vitest，配置文件位于 vitest.config.js，其中设置了模块解析规则以模拟条件导出的行为。测试套件涵盖以下类别：

测试类别	测试内容
runtime-runes	Svelte 5 基于 runes 的组件行为
runtime-legacy	Svelte 4 兼容模式
compiler-errors	预期的编译失败场景
compiler-warnings	预期的诊断警告
hydration	客户端/服务端渲染一致性
signals	底层响应式引擎
snapshot	编译输出稳定性

flowchart LR
    Test["vitest"] --> Resolve["Custom resolver:<br/>maps 'svelte/' imports<br/>to correct client/server files"]
    Resolve --> Client["Browser tests<br/>→ src/index-client.js"]
    Resolve --> Server["SSR tests<br/>→ src/index-server.js"]

Vitest 配置中的 customResolver 会根据测试路径是否包含 _output/server，智能地将 svelte/* 的 import 路由到客户端或服务端文件。

下一步

有了这张导览地图，我们就可以跟随一个 .svelte 文件，完整走过编译器流水线的每个阶段。下一篇文章中，我们将深入探讨：Svelte 编译器如何通过手写的状态机 parser 将源代码解析为 AST，如何分析该 AST 以解析绑定关系并识别 runes，最终将其转换为调用我们刚刚梳理过的那些 $.xxx 函数的 JavaScript 输出。