Svelte 命令式组件 API 实战：mount / hydrate / render / unmount 全链路与源码解析

2026-09-04 16:57:34作者：齐冠琰

Svelte 应用的启动方式与多数框架不同：客户端通过 mount 把根组件命令式地挂载到某个 DOM 节点，服务端则通过 render 拿回可直接输出的 HTML 字符串。本文围绕 Svelte 官方文档中的 Imperative Component API（mount、unmount、render、hydrate 四个函数），结合当前仓库的实现源码，逐一讲清它们的参数、返回值、相互协作关系，以及“为什么 effects 不会在 mount 时立即执行”这类关键细节，帮助你在 SSR 项目、测试场景和动态挂载（如 tooltip 附着到悬停元素）中正确使用这套 API。

客户端与服务端的两套入口

每个 Svelte 应用都从命令式地创建一个根组件开始。在客户端，组件被挂载（mount）到页面上的某个具体元素；在服务端，你拿到的则是渲染好的 HTML 字符串，用于服务端渲染。仓库中这两个入口的物理位置也很清晰：

客户端入口聚合在 index-client.js，其中 mount、hydrate、unmount 直接转出自 internal/client/render.js；
服务端入口 server/index.js 只导出 render，它在内部委托给 Renderer.render（定义于 internal/server/renderer.js）；
反过来，如果你在服务端环境误调 mount / hydrate / unmount，index-server.js 中对应的空函数会主动抛出 lifecycle_function_unavailable 错误，从结构上杜绝跨端误用。

四个函数的职责边界如下：mount 与 hydrate 负责“让组件在浏览器里跑起来”，render 负责“在服务器上生成 HTML”，unmount 负责“把挂载过的组件干净地拆掉”。它们并不是孤立的，下文会展示 render → hydrate → unmount 这条完整的 SSR 闭环。

`mount`：把组件实例化到指定节点

mount 实例化组件并将其挂载到给定的 target 元素上：

import { mount } from 'svelte';
import App from './App.svelte';

const app = mount(App, {
	target: document.querySelector('#app'),
	props: { some: 'property' }
});

官方文档明确了两点使用特性，值得强调：

同一页面可以挂载多个组件。你也可以在应用内部动态 mount，典型场景是 tooltip 组件：在元素被悬停时挂载、附着到目标元素附近。
mount 期间 effects 不会执行。与 Svelte 4 中直接 new App(...) 不同，Svelte 5 里 effects（包括 onMount 回调和 action 函数）不会在 mount 调用时同步运行。如果需要在调用后立即让“挂起”的 effects 执行（比如写单元测试时），可以紧接着调用 flushSync()。这一行为与源码吻合：index-client.js 中 onMount 在非 legacy 模式下被注册为 user_effect，即走 effect 调度队列，而不是立即执行；flushSync 则从 internal/client/reactivity/batch.js 导出，用于强制刷新队列。

`mount` 的完整选项

从 index.d.ts 中的 MountOptions 类型定义看，mount 接受以下选项：

选项	类型	默认值	说明
`target`	`Document \| Element \| ShadowRoot`	必填	组件挂载的目标节点
`props`	组件 props 类型	可选（无默认 props 时必填）	组件属性，类型上做了条件约束：若组件有必填 props，则 `props` 为必传
`anchor`	`Node`	无	`target` 内的一个节点，组件会渲染在该节点之前
`context`	`Map<any, any>`	无	可通过组件内的 `getContext()` 读取
`intro`	`boolean`	`true`	初始渲染时是否播放 intro 过渡
`events`	`Record<string, (e) => any>`	无	已标记为 `@deprecated`，官方建议改用 callback props
`transformError`	`(error) => unknown`	恒等函数	错误边界捕获错误后、传给 `failed` snippet 前的转换函数

源码视角下的 `mount` 执行过程

render.js 中 mount 本身只有一行，真正的工作在内部的 _mount（L162-L289）中完成，关键步骤有：

调用 init_operations() 初始化 DOM 操作队列，组件的创建被包在一个 component_root effect 中执行，并用 boundary（错误边界）包裹，transformError 选项就在此处接入；
若传入了 anchor，组件渲染在 anchor 之前，否则会在 target 上追加一个文本节点作为锚点（L173）；
组件实例化后，Svelte 会在组件挂载完成之后才注册事件委托：它按“已注册事件”的引用计数，在 target 与 document 上成对挂 addEventListener（L217-L258）。同时挂 document 是为了兼容被手动移出容器的节点（如手动实现的 portal）。卸载时按引用计数成对移除，多个组件共存时不会误删仍在使用的监听器；
每个成功挂载的组件与它的清理函数存入 mounted_components WeakMap（L287-L295），这正是 unmount 能够只凭“组件返回值”就找到并拆除它的原因。

`unmount`：带过渡动画的卸载

unmount 用于拆除此前通过 mount 或 hydrate 创建的组件。当 options.outro 为 true 时，组件在从 DOM 移除前会先播放 transitions（outro 过渡）：

import { mount, unmount } from 'svelte';
import App from './App.svelte';

const app = mount(App, { target: document.body });

// later
unmount(app, { outro: true });

返回值是一个 Promise：outro 为 true 时在所有过渡完成后 resolve，否则立即 resolve。Promise 的返回形式正是为 outro 引入的——源码中的 JSDoc 注明该能力自 5.13.0 起提供，此前 unmount 返回 void（见 render.js 的注释与实现）。

实现上 unmount（L317-L330）逻辑很直白：从 mounted_components WeakMap 中取出对应的清理函数并调用；如果找不到（说明从未挂载或已经卸载过），开发模式下会触发 lifecycle_double_unmount 警告，生产模式下静默地返回一个已 resolve 的 Promise。这种设计让“重复 unmount”成为幂等的安全操作，而不是抛错。

`render`：服务端的 SSR 入口

render 只存在于服务端，且组件必须以 server 编译选项编译。它接收组件，返回一个带 body 和 head 属性的对象，用于拼装 HTML 文档：

import { render } from 'svelte/server';
import App from './App.svelte';

const result = render(App, {
	props: { some: 'property' }
});
result.body; // 放入 <body> 的 HTML
result.head; // 放入 <head> 的 HTML

返回值其实是一个“惰性 thenable”

从 internal/server/renderer.js 的 Renderer.render 实现看，render 的返回值并非立即渲染的普通对象，而是用 Object.defineProperties 构造的惰性对象：

body、head、html 都是非枚举的 getter，首次访问时才真正触发同步渲染（注释中特意说明：设为非枚举是为了避免 console.log 意外触发同步渲染）；
对象上同时挂了 then 方法，使其成为一个 thenable：当项目启用了异步 SSR（async 模式）时，await render(App, {...}) 会走异步渲染路径，支持 await 数据请求等场景；同步模式下则退化为立即 resolve；
hashes.script 用于 CSP：当传入 csp: { hash: true } 时，内联脚本（如 hydratable 序列化脚本）的 sha256 会累积在这里供你配置 nonce/hash 白名单。

`render` 的选项

结合 server/index.js 与 SSRState 的构造（renderer.js），可用选项包括：

选项	说明
`props`	组件属性（类型上剔除了 `$$slots` / `$$events` 内部字段）
`context`	服务端 context，可通过 `getContext()` 读取
`idPrefix`	生成组件内 uid 的前缀；源码会校验其不能包含 `--`（`invalid_id_prefix` 错误），最终生成的 id 形如 `<prefix>s1`、`s2`…
`csp`	`{ nonce?: string; hash?: boolean }`，`hash` 与 `nonce` 不可同时为真（`render` 入口即检查 `invalid_csp`）
`transformError`	与客户端一致，错误边界捕获错误后的转换函数

渲染过程中，<title> 与 <style> 会被分流到 head：#close_render（renderer.js）把收集到的 CSS 以 <style id="hash"> 的形式追加进 head，<title> 内容经由 SSRState 的 title 机制归并。body 部分则包含 hydration 所需的注释标记（如  边界），这些标记正是客户端 hydrate 能够“认路”的依据。

`hydrate`：复用 SSR HTML 使其可交互

hydrate 与 mount 类似，但它会复用目标节点内由 render 生成的 SSR HTML（连同其中的 hydration 注释标记），并把它们变成可交互的组件，而不是重新构建 DOM 树：

import { hydrate } from 'svelte';
import App from './App.svelte';

const app = hydrate(App, {
	target: document.querySelector('#app'),
	props: { some: 'property' }
});

两个与 mount 的关键差异：

intro 过渡默认不播放。render.js 中 hydrate 入口第一行就是 options.intro = options.intro ?? false，即 intro 默认 false（mount 默认 true）。SSR 场景下服务端已经渲染出了最终形态，客户端通常不需要再播放进场动画；如需播放，显式传 intro: true。
effects 同样不会在 hydrate 期间运行，官方文档建议：若必须立即执行，就在 hydrate 返回后马上调用 flushSync()。

hydration 标记定位与失败兜底

hydrate 的实现（render.js）展示了一个值得了解的容错流程：

从 target 的第一个子节点开始，向后查找数据为 HYDRATION_START 的注释节点作为 hydration 起点（该常量定义于 constants.js）；找不到则抛出内部的 HYDRATION_ERROR。
通过 set_hydrating(true) 进入 hydration 模式后走 _mount 创建组件，并在结束时校验 hydration 指针恰好停在 HYDRATION_END 注释上（L199-L210），否则触发 hydration_mismatch 警告并抛错。
失败兜底：若 hydration 失败，会先 console.warn 并清空 target 内容，然后自动降级为普通 mount 重新渲染整个组件。若传入 recover: false，则不降级，直接抛出 hydration_failed 错误——适合你希望“严格暴露服务端/客户端 HTML 不一致”的环境。
try/finally 中会恢复此前的 hydrating 与 hydrate_node 状态，保证嵌套或连续 hydration 不互相污染。

仓库中配套的测试用例可以进一步印证这套机制：tests/hydration 目录下有上百个覆盖 hydration 各种分支（mismatch、恢复、嵌套块等）的 sample，入口为 tests/hydration/test.ts；服务端渲染本身的输出则由 tests/server-side-rendering/test.ts 校验，SSR 渲染性能还有专门的基准脚本 benchmarking/benchmarks/ssr/index.js。

四个 API 如何协同：一条完整的 SSR 链路

把前面四节串起来，一个标准 SSR 应用的完整生命周期是：

服务端：请求到达时以 server 选项编译的组件调用 render(App, { props })，拿到 { head, body } 拼进 HTML 模板返回。body 中带有 hydration 注释标记。
客户端：浏览器加载后调用 hydrate(App, { target, props })，它定位 HYDRATION_START 标记、复用已有 DOM，把静态 HTML 变成活的组件；必要时用 flushSync() 强制 effects（onMount、actions）执行。
卸载：组件生命周期结束（如 SPA 中路由级组件销毁）时调用 unmount(app)；若有出场动画，传 { outro: true } 并 await 返回的 Promise。

几个实践要点汇总：

测试或需要同步 DOM 结果的场景，mount / hydrate 之后紧接 flushSync()；
同一 target 上可多次 mount 多个组件，事件委托按引用计数管理，不会互相干扰；
events 选项已废弃，回调类需求建议改用 callback props；
服务端代码里不要出现 mount / hydrate / unmount，构建时它们对应的桩函数会直接报错。

参考路径速查

内容	路径
本文档对应的官方说明	documentation/docs/06-runtime/04-imperative-component-api.md
`mount` / `hydrate` / `unmount` 实现	packages/svelte/src/internal/client/render.js
`MountOptions` 类型定义	packages/svelte/src/index.d.ts
服务端 `render` 入口	packages/svelte/src/server/index.js
`Renderer` / `SSRState` 实现	packages/svelte/src/internal/server/renderer.js
服务端桩函数（防止跨端误用）	packages/svelte/src/index-server.js
hydration 测试	packages/svelte/tests/hydration/test.ts
SSR 测试	packages/svelte/tests/server-side-rendering/test.ts
transitions 文档（outro 相关）	documentation/docs/03-template-syntax/14-transition.md