Rolldown JSX Transform 注释保留行为解析:基于 esbuild 兼容性测试 diff 的逐行对比
Rolldown JSX Transform 注释保留行为解析:基于 esbuild 兼容性测试 diff 的逐行对比
导读
本文围绕 Rolldown 仓库中 esbuild 兼容性测试套件的一个具体快照 crates/rolldown/tests/esbuild/default/comment_preservation_transform_jsx/diff.md,剖析 Rolldown 与 esbuild 在 JSX 转换为经典运行时(classic runtime)调用时对源码注释的保留策略差异。你将了解该测试的 fixture 机制与输入构造方式、两类构建器在同一段 JSX 源码下的输出形态差异,以及这些差异对实际迁移 esbuild 工作流到 Rolldown 时的参考意义。全文以仓库内真实快照、源码与测试配置为依据,可直接对照复现。
一、测试背景:esbuild 兼容性测试与 fixture 机制
Rolldown 的测试目录 crates/rolldown/tests/esbuild/ 下按场景类别(default、dce、glob、importstar、loader、lower、splitting、ts 等)组织了一大批与 esbuild 行为对标的用例。每个用例目录通常包含四个文件:
entry.jsx(或.js):测试输入源码;_config.json:构建配置;artifacts.snap:Rolldown 实际构建产物的快照;diff.md:esbuild 输出、Rolldown 输出及二者 diff 的自动生成对比文档。
这套机制的驱动入口是 crates/rolldown/tests/integration/esbuild.rs,核心只有几行:
use rolldown_testing::fixture::Fixture;
use testing_macros::fixture;
#[fixture("./tests/esbuild/**/_config.json")]
fn test(path: PathBuf) {
Fixture::new(path.parent().unwrap()).run_integration_test();
}
#[fixture] 宏会递归遍历 tests/esbuild/ 下所有 _config.json,对每个用例执行一次集成测试。测试结果会与 esbuild 的参考输出做对比,并落盘为 diff.md。因此,本文分析的 diff.md 并非手写文档,而是当前仓库状态下 Rolldown 与 esbuild 行为差异的真实快照,具有可复现、可追踪的特点。
二、测试输入与配置:六类 JSX 注释场景
用例输入位于 crates/rolldown/tests/esbuild/default/comment_preservation_transform_jsx/entry.jsx,它在 console.log 中罗列了六类带注释的 JSX 写法:
console.log(
<div x={/*before*/x} />, // ① 属性值表达式前的块注释
<div x={/*before*/'y'} />,
<div x={/*before*/true} />,
<div {/*before*/...x} />, // ② 展开属性前的块注释
<div>{/*before*/x}</div>, // ③ children 表达式前的块注释
<>{/*before*/x}</>, // ④ Fragment children 中的注释
// Comments on absent AST nodes // ⑤ 注释位于"不存在的 AST 节点"位置
<div>before{}after</div>,
<div>before{/* comment 1 *//* comment 2 */}after</div>,
<div>before{
// comment 1
// comment 2
}after</div>,
<>before{}after</>,
<>before{/* comment 1 *//* comment 2 */}after</>,
<>before{
// comment 1
// comment 2
}after</>,
)
其中第 ⑤ 组专门考察一个边界问题:当注释出现在 JSX 表达式容器({})内部、而该位置并没有真正的 AST 表达式节点(空表达式,或只有注释没有表达式)时,构建器如何处理这些"悬空"注释。
用例配置在 crates/rolldown/tests/esbuild/default/comment_preservation_transform_jsx/_config.json:
{
"expectExecuted": false,
"config": {
"input": [
{
"name": "entry",
"import": "entry.jsx"
}
],
"transform": {
"jsx": {
"runtime": "classic"
}
}
}
}
要点:
transform.jsx.runtime: "classic":使用经典运行时,JSX 会被转换为React.createElement(...)调用(而非自动运行时jsx/jsxs),这与本 diff 中输出里的React.createElement形态直接对应;expectExecuted: false:产物不需要实际执行验证;input[0].name: "entry":入口模块名为entry,这也解释了产物注释//#region entry.jsx的命名来源。
三、输出对比:esbuild 与 Rolldown 的完整快照
以下是 diff.md 中记录的完整对比(原文照录),先看 esbuild 输出:
// entry.jsx
console.log(
/* @__PURE__ */ React.createElement("div", { x: (
/*before*/
x
) }),
/* @__PURE__ */ React.createElement("div", { x: (
/*before*/
"y"
) }),
/* @__PURE__ */ React.createElement("div", { x: (
/*before*/
true
) }),
/* @__PURE__ */ React.createElement("div", {
/*before*/
...x
}),
/* @__PURE__ */ React.createElement(
"div",
null,
/*before*/
x
),
/* @__PURE__ */ React.createElement(
React.Fragment,
null,
/*before*/
x
),
// Comments on absent AST nodes
/* @__PURE__ */ React.createElement("div", null, "before", "after"),
/* @__PURE__ */ React.createElement("div", null, "before", "after"),
/* @__PURE__ */ React.createElement("div", null, "before", "after"),
/* @__PURE__ */ React.createElement(React.Fragment, null, "before", "after"),
/* @__PURE__ */ React.createElement(React.Fragment, null, "before", "after"),
/* @__PURE__ */ React.createElement(React.Fragment, null, "before", "after")
);
再看 Rolldown 输出(与 artifacts.snap 中 entry.js 的内容一致):
//#region entry.jsx
console.log(/* @__PURE__ */ React.createElement("div", { x }), /* @__PURE__ */ React.createElement("div", { x: "y" }), /* @__PURE__ */ React.createElement("div", { x: true }), /* @__PURE__ */ React.createElement("div", x), /* @__PURE__ */ React.createElement("div", null, x), /* @__PURE__ */ React.createElement(React.Fragment, null, x), /* @__PURE__ */ React.createElement("div", null, "before", "after"), /* @__PURE__ */ React.createElement("div", null, "before", "after"), /* @__PURE__ */ React.createElement("div", null, "before", "after"), /* @__PURE__ */ React.createElement(React.Fragment, null, "before", "after"), /* @__PURE__ */ React.createElement(React.Fragment, null, "before", "after"), /* @__PURE__ */ React.createElement(React.Fragment, null, "before", "after"));
//#endregion
两者最终的 React.createElement 调用序列完全一致(12 个调用、参数语义相同),差异集中在注释的保留与否与输出排版上。diff.md 中的 diff 块如下:
===================================================================
--- esbuild /out/entry.js
+++ rolldown entry.js
@@ -1,9 +1,7 @@
console.log(React.createElement("div", {
- x: x
+ x
}), React.createElement("div", {
x: "y"
}), React.createElement("div", {
x: true
-}), React.createElement("div", {
- ...x
-}), React.createElement("div", null, x), React.createElement(React.Fragment, null, x), React.createElement("div", null, "before", "after"), React.createElement("div", null, "before", "after"), React.createElement("div", null, "before", "after"), React.createElement(React.Fragment, null, "before", "after"), React.createElement(React.Fragment, null, "before", "after"), React.createElement(React.Fragment, null, "before", "after"));
+}), React.createElement("div", x), React.createElement("div", null, x), React.createElement("div", null, "before", "after"), React.createElement("div", null, "before", "after"), React.createElement("div", null, "before", "after"), React.createElement(React.Fragment, null, "before", "after"), React.createElement(React.Fragment, null, "before", "after"), React.createElement(React.Fragment, null, "before", "after"));
四、差异逐项分类:注释保留、优化与排版
把 diff 展开为语义层面,可以归纳出四类差异:
4.1 JSX 属性值表达式前的注释:esbuild 保留,Rolldown 丢弃
对于 <div x={/*before*/x} /> 这类写法:
- esbuild 输出为
{ x: ( /*before*/ x ) },/*before*/被完整保留并单独成行; - Rolldown 输出为
{ x },注释被移除,同时把x: x简写为属性简写x(这是 diff 中第一处- x: x / + x的来源)。
'y' 与 true 两个属性值同理:esbuild 保留 /*before*/ 且展开为多行,Rolldown 保留字面量语义但删除注释。
4.2 展开属性前的注释:esbuild 保留对象展开,Rolldown 直接传 props
对于 <div {/*before*/...x} />:
- esbuild 输出
React.createElement("div", { ...x }),即保留对象字面量展开形态与注释; - Rolldown 输出
React.createElement("div", x),即当 props 仅由一个展开表达式构成时,直接把x作为 props 参数传入,并丢弃注释。
从产物看,Rolldown 在此处应用了"单展开属性直接传递"的优化路径,而 esbuild 在未压缩模式下保持字面量展开的书写形态。由于注释附着在该展开节点上,两种策略对注释的处理结果也不同。
4.3 children 表达式前的注释:esbuild 保留,Rolldown 丢弃
<div>{/*before*/x}</div> 与 <>{/*before*/x}</> 对应的输出分别为:
- esbuild:
React.createElement("div", null, /*before*/ x)与React.createElement(React.Fragment, null, /*before*/ x),注释保留在 children 参数前; - Rolldown:
React.createElement("div", null, x)与React.createElement(React.Fragment, null, x),注释消失。
4.4 "不存在的 AST 节点"上的注释:仅 esbuild 保留了行注释
第 ⑤ 组是本文最有代表性的边界用例。源码在 <div>before{}after</div> 等结构中,表达式容器 {} 内部要么为空、要么只含注释({/* comment 1 *//* comment 2 */} 或跨行 // 注释),这些注释并不附着在任何真实 AST 表达式节点上。观察两组输出:
- esbuild 保留了源码中的
// Comments on absent AST nodes这一行注释(它位于一个表达式容器的位置,被作为独立注释行输出),而{}内的/* comment 1 */、// comment 1等注释同样被丢弃,最终只输出"before", "after"两个字符串参数; - Rolldown 的输出中,
// Comments on absent AST nodes同样没有出现,与 esbuild 的差异点仅在于行注释的处理:esbuild 会保留容器位置的整行注释,Rolldown 则一并移除。
换言之,esbuild 对"附着在不存在 AST 节点上的注释"采用部分保留策略,Rolldown 在该用例下未保留任何此类注释。这正是 diff.md 中 esbuild 侧出现 // Comments on absent AST nodes 注释行、而 Rolldown 侧缺失的原因。
4.5 输出排版差异:多行美化 vs 单行紧凑
除注释外,两类产物在排版上也有明显差异:
- esbuild 默认输出会为每个
React.createElement调用做多行展开(参数换行、注释独立成行),可读性更强; - Rolldown 将整个
console.log(...)输出为单行紧凑形式,且用//#region entry.jsx///#endregion标记模块代码区域(这来自 Rolldown 产物中保留的模块边界标记)。
diff 头部 @@ -1,9 +1,7 @@ 正反映了这一行数差异:esbuild 输出 9 行,Rolldown 输出 7 行。
五、横向对比:同一主题的兄弟测试用例
comment_preservation_transform_jsx 并非孤例,tests/esbuild/default/ 下还有一组围绕注释保留的相邻用例,可对照阅读:
comment_preservation/:不涉及 JSX transform 的通用注释保留测试。其输入 crates/rolldown/tests/esbuild/default/comment_preservation/entry.js 覆盖了动态import()、require()、require.resolve()参数位置注释,数组/对象解构中的/*foo*/与//注释,return/throw后注释,三元表达式、for/if/while/switch等控制语句括号内注释等大量场景,用于检验非 transform 路径下注释的保留一致性;comment_preservation_preserve_jsx/:JSX 保留模式(runtime: preserve)下的注释保留测试;comment_preservation_import_assertions/:import()断言参数中的注释处理。
三者的差异在于 JSX 处理模式(transform vs preserve)与语言特性(JS vs JSX)不同,而本文的用例专攻 transform 模式下注释随 JSX 转换流程的走向,属于其中语义变化最大的路径——JSX 节点一旦被重写为函数调用,注释的"附着点"就会在 AST 重建中面临丢失风险。
六、如何复现与进一步验证
若要在本地复现该差异快照,可按仓库常规测试流程操作:
- 确认 Rust 工具链就绪(仓库根目录的
rust-toolchain.toml会锁定版本); - 运行 esbuild 对比测试套件:
或单独运行该用例(夹具路径为cargo test -p rolldown --test integration esbuildcrates/rolldown/tests/esbuild/default/comment_preservation_transform_jsx); - 测试执行后,
diff.md会依据最新构建结果重新生成,可直接对比当前 Rolldown 与 esbuild 的行为是否发生变化。
产物快照同样可以直接查看:crates/rolldown/tests/esbuild/default/comment_preservation_transform_jsx/artifacts.snap 中记录了 Rolldown 生成的 entry.js,其内容与上文 Rolldown 输出完全一致。
七、对使用者的启示
从当前仓库快照可以得出如下实践结论(基于本用例,不代表其他场景):
- 语义等价但注释不保:在 JSX transform(classic runtime)场景下,Rolldown 与 esbuild 生成的
React.createElement调用在参数语义上等价,但属性值、展开属性、children 表达式位置的单行/块注释在 Rolldown 产物中会丢失。若你的项目依赖构建产物中的注释(如基于注释的代码分析、license 头、@__PURE__等标记的保留),需要关注此差异; @__PURE__注释不受影响:两组输出都正确输出了/* @__PURE__ */标记,说明 tree-shaking 相关的纯函数注释标记在 transform 路径上是受保护、被完整保留的;- 优化形态不同:Rolldown 会将
{x: x}压缩为简写x,把纯展开 props 直接内联为参数({...x}→x),esbuild 在未压缩模式下则保持书写形态——这是产物大小与可读性上的权衡差异; - 验证方法成熟:esbuild 兼容性测试套件通过
_config.json驱动、diff.md落盘的方式,为跟踪此类行为差异提供了低成本的回归观测手段。
最后提醒:diff.md 是当前仓库状态下的行为快照,它记录的是"现状"而非"缺陷定论"。随着 Rolldown 对 JSX transform 与注释保留逻辑的持续演进,重新运行测试后该 diff 可能缩小甚至归零,建议以仓库最新测试结果为准。