Svelte 5 模板语法实战：深入理解 {@render} 渲染标签与 Snippet 调用机制

{@render ...} 是 Svelte 5 模板语法中用于渲染 snippet（代码片段）的专属标签。它是 Svelte 5 用 Snippet 取代传统 slot 方案的核心组成部分：你先用 {#snippet ...} 声明一段可复用的标记，再用 {@render ...} 在任意位置"调用"它——既可以在当前组件内渲染，也可以作为 props 传给子组件渲染。读完本文，你将掌握 {@render} 的完整用法（含可选 snippet 与回退内容），并能从编译器源码层面理解它在解析、分析、客户端/服务端转换各阶段的处理方式，以及常见编译错误与运行时错误的成因。

基本用法：调用一个 snippet

要渲染一个 snippet，就使用 {@render ...} 标签。标签内必须是一个调用表达式：

{#snippet sum(a, b)}
	<p>{a} + {b} = {a + b}</p>
{/snippet}

{@render sum(1, 2)}
{@render sum(3, 4)}
{@render sum(5, 6)}

渲染结果就是三段 <p>，分别为 1 + 2 = 3、3 + 4 = 7、5 + 6 = 11。

表达式可以是标识符，也可以是任意 JavaScript 表达式

{@render ...} 里的表达式既可以是像 sum 这样的标识符，也可以是任意 JavaScript 表达式。例如用三元表达式在两个 snippet 之间动态切换：

{@render (cool ? coolSnippet : lameSnippet)()}

从解析器源码看，这个"只接受调用表达式"的限制是在 tag.js 中强制的：解析 {@render ...} 时，读到的表达式必须是 CallExpression，或者是内部包裹着 CallExpression 的 ChainExpression（即可选链形式，下文会讲），否则直接抛出编译错误：

• {@render ...} 只能包含调用表达式 —— 对应 错误定义 中的 render_tag_invalid_expression；
• 不能使用 call / apply / bind 来间接调用 snippet 函数（render_tag_invalid_call_expression）；
• 不能使用展开（spread）参数（render_tag_invalid_spread_argument）。

后两条规则由分析阶段的访问器 RenderTag.js 负责检查：它遍历 arguments，遇到 SpreadElement 即报错；若 callee 是形如 xxx.call / xxx.apply / xxx.bind 的 MemberExpression，也会报错。

可选 snippet：?. 与回退内容

当 snippet 可能是 undefined —— 典型场景是它来自父组件传入的 prop —— 有两种处理方式。

方式一：可选链短路。用可选链（optional chaining），仅在 snippet 已定义时渲染它：

<script>
	let { children } = $props();
</script>

{@render children?.()}

方式二：{#if ...} + :else 渲染回退内容。

<script>
	let { children } = $props();
</script>

{#if children}
	{@render children()}
{:else}
	<p>fallback content</p>
{/if}

客户端转换阶段对这两种写法有专门的处理逻辑，见 client RenderTag.js：当表达式被判定为"动态"（即无法在编译期确定指向哪个具体 snippet 声明）且原文是 ChainExpression 时，编译器会生成 snippet_function ?? $.noop 这样的代码——也就是说，children?.() 在运行时如果解析出 null/undefined，会被兜底成一个空操作函数，从而什么都不渲染而不报错。

对比之下，如果直接用 {#if children} 判断，则由普通条件块来决定走哪条渲染路径，还能附带 :else 回退内容。两种方式按需选择：无内容时"静默跳过"用 ?.，需要展示默认 UI 用 {#if}。

源码视角：{@render} 在编译器中的三个处理阶段

理解 {@render} 的编译过程，可以完整回答"为什么它比直接插值 {children} 正确"这个问题。

1. 解析阶段：生成 RenderTag AST 节点

解析器 遇到 {@render 时读取整个表达式，校验其为调用表达式后，生成一个携带 metadata 的 RenderTag AST 节点。metadata 中的 snippets 集合和 dynamic 标志会在后续阶段被填充，分别用于 CSS 作用域分析（决定哪些 snippet 的标记应匹配本组件的样式）和客户端代码生成。

2. 分析阶段：静态解析 vs 动态调用

分析访问器 会尝试将 callee 解析到具体的声明：

• 若 callee 是标识符，且作用域内能查到它绑定到一个 SnippetBlock（即 {#snippet} 声明），则该 render tag 被视为静态，metadata.snippets 记录对应的 snippet 块；
• 若无法无歧义地解析（如三元表达式、prop 传入的 snippet），则标记为 dynamic，编译器会保守地"假设最坏情况"，把该 render tag 关联到作用域内所有 snippet 做后续处理。

这一区分直接影响生成的代码形态。

3. 客户端与服务端转换

客户端（client/visitors/RenderTag.js）：

• 每个实参先被构建为表达式，再包成 thunk（惰性求值），避免在不需要时重复计算；
• 静态调用（能确定指向本地 snippet 声明）直接生成 snippet_function(...args) 的调用语句；
• 动态调用则生成 $.snippet(node, () => snippet_function, ...args) 的通用运行时调用，由 reactivity 运行时 负责解析与渲染，并对可选链形式补上 ?? $.noop 兜底。

服务端（server/visitors/RenderTag.js）：逻辑更直接——把调用改写为 snippet_function($$renderer, ...args)，即 snippet 的函数体在 SSR 时接收渲染上下文 $$renderer，把标记写入字符串输出；非独立渲染的 render tag 还会追加一个空注释占位，用于保持 hydration 时的 DOM 结构对齐。

典型陷阱：{children} 与 {@render children()}

一个常见且真实的运行时错误被定义在 shared-errors 中（snippet_without_render_tag）：如果你写了 {children} 而不是 {@render children()}，snippet 函数会被当作普通值插值到文本中——结果是输出函数源码字符串而非渲染出 DOM。Svelte 在开发模式下会检测到"把一个 snippet 当普通值渲染"并抛出明确错误，提示你改用 {@render snippet()}。这也解释了为什么模板中凡是渲染 snippet，一律必须走 {@render} 标签。

结合 snippet 文档的完整心智模型

{@render} 与 {#snippet} 文档中的其他能力组合使用，构成 Svelte 5 的内容复用体系：

• 作用域：snippet 声明在组件内部任何位置，遵循词法作用域可见规则；snippet 可以相互引用，也可以递归引用自身，例如 countdown(n) 内部 {@render countdown(n - 1)}；
• 作为 props 传递：snippet 在模板中就是普通的值，可显式 {header} {row} 传给组件，也可以由"组件标签内直接声明的 snippet"隐式成为 prop；组件标签内的非 snippet 内容则隐式构成 children snippet，在子组件中 {@render children()} 即可渲染；
• TypeScript 类型：snippet props 使用从 svelte 导入的 Snippet 接口描述，泛型参数为元组，如 Snippet<[T]>；
• 与 legacy slot 的关系：Svelte 5 中 slot 已被废弃（见 legacy-slots 文档），snippet + {@render} 是推荐且更灵活的替代方案。

小结

{@render ...} 的使用面很窄但约束很明确：标签内只允许调用表达式（可选链形式除外），不允许 spread 参数与 call/apply/bind 间接调用；snippet 可能缺省时用 children?.() 静默跳过，或配合 {#if ... :else} 渲染回退内容。从源码看，编译器会对能静态解析的调用生成直接函数调用，对动态调用统一收敛到 $.snippet 运行时入口（客户端）或 $$renderer 上下文传递（服务端），这也是理解 Svelte 5 snippet 渲染性能特征的关键入口。