Rolldown JSX Transform 注释保留行为解析:基于 esbuild 兼容性测试 diff 的逐行对比

原创2026-09-14 23:13:141,668 阅读
文章标签:前端构建构建工具开发工具CLI

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 重建中面临丢失风险。

六、如何复现与进一步验证

若要在本地复现该差异快照,可按仓库常规测试流程操作:

  1. 确认 Rust 工具链就绪(仓库根目录的 rust-toolchain.toml 会锁定版本);
  2. 运行 esbuild 对比测试套件:
    cargo test -p rolldown --test integration esbuild
    
    或单独运行该用例(夹具路径为 crates/rolldown/tests/esbuild/default/comment_preservation_transform_jsx);
  3. 测试执行后,diff.md 会依据最新构建结果重新生成,可直接对比当前 Rolldown 与 esbuild 的行为是否发生变化。

产物快照同样可以直接查看:crates/rolldown/tests/esbuild/default/comment_preservation_transform_jsx/artifacts.snap 中记录了 Rolldown 生成的 entry.js,其内容与上文 Rolldown 输出完全一致。

七、对使用者的启示

从当前仓库快照可以得出如下实践结论(基于本用例,不代表其他场景):

  1. 语义等价但注释不保:在 JSX transform(classic runtime)场景下,Rolldown 与 esbuild 生成的 React.createElement 调用在参数语义上等价,但属性值、展开属性、children 表达式位置的单行/块注释在 Rolldown 产物中会丢失。若你的项目依赖构建产物中的注释(如基于注释的代码分析、license 头、@__PURE__ 等标记的保留),需要关注此差异;
  2. @__PURE__ 注释不受影响:两组输出都正确输出了 /* @__PURE__ */ 标记,说明 tree-shaking 相关的纯函数注释标记在 transform 路径上是受保护、被完整保留的;
  3. 优化形态不同:Rolldown 会将 {x: x} 压缩为简写 x,把纯展开 props 直接内联为参数({...x} → x),esbuild 在未压缩模式下则保持书写形态——这是产物大小与可读性上的权衡差异;
  4. 验证方法成熟:esbuild 兼容性测试套件通过 _config.json 驱动、diff.md 落盘的方式,为跟踪此类行为差异提供了低成本的回归观测手段。

最后提醒:diff.md 是当前仓库状态下的行为快照,它记录的是"现状"而非"缺陷定论"。随着 Rolldown 对 JSX transform 与注释保留逻辑的持续演进,重新运行测试后该 diff 可能缩小甚至归零,建议以仓库最新测试结果为准。

登录后查看全文
rolldown