Rolldown 的 TypeScript 处理能力全景:基于 esbuild 快照对比测试的兼容性深度解析
Rolldown 的 TypeScript 处理能力全景:基于 esbuild 快照对比测试的兼容性深度解析
导读
本文以 ts.md 这份由仓库自动生成的测试总结为切入点,系统解读 Rolldown(面向 JavaScript/TypeScript 的 Rust 打包器)在 TypeScript 处理上与 esbuild 的对齐程度。你会看到一套可复现的快照对比测试流水线、四类测试状态的判定逻辑,以及 85 个 TS 专项用例背后的实现细节与已知边界。读完本文,你既能定位某类 TS 语法特性(如 enum、装饰器、import equals、declare 声明)当前的支持状态,也能理解如何查看 diff、复现对比并读懂兼容性度量数据。
一、这份文档是什么:自动生成的 TS 兼容性总结
scripts/src/esbuild-tests/snap-diff/summary/ts.md 不是手写的说明文档,而是由脚本自动产出的测试状态快照。它对应 esbuild 官方快照文件 snapshots_ts.txt(见 download-snapshots.ts 中的 SNAPSHOT_FILES 列表),记录了 Rolldown 在 TypeScript 场景下与 esbuild 输出的一致性现状。
其生成入口在 runner.ts:脚本遍历解析后的 esbuild 快照用例,逐一在 crates/rolldown/tests/esbuild/ts 下查找对应测试目录,对比两边产物,最后按状态分类写入 summary/ts.md。整条流水线如下:
- 下载快照:从 esbuild 官方快照源拉取
snapshots_ts.txt,缓存 24 小时(download-snapshots.ts); - 解析快照:用 snap-parser.ts 将快照按分隔线拆分为独立用例,每个用例解析出若干源文件;
- 运行 Rolldown 并对比:读取测试目录中的
artifacts.snap,经 diff.ts 与 esbuild 产物逐文件 diff; - 分类汇总:结合 reasons.ts 的登记信息,将用例归入 Failed / Passed / Ignored / Ignored (not supported) 四类并生成总结。
复现命令在 scripts/package.json 中登记为 pnpm esbuild-snap-diff,底层调用 oxnode ./src/esbuild-tests/snap-diff/index.ts(入口 index.ts 支持 --debug 与 --verbose 参数)。
二、四类状态:判定逻辑与硬性约束
总结文档将用例分为四节,其语义由 reasons.ts 中的三个字典决定:
| 分类 | 判定来源 | 含义 |
|---|---|---|
# Failed Cases |
failedReasons |
已登记为失败,输出与 esbuild 不一致,原因在登记时说明 |
# Passed Cases |
无登记 | 输出与 esbuild 一致,用例通过 |
# Ignored Cases |
ignoreReasons |
有意的行为差异,Rolldown 选择不跟随 esbuild |
# Ignored Cases (not supported) |
notSupportedReasons |
底层依赖(如 oxc minifier)暂不支持,明确记录边界 |
这套分类不是松散的,runner.ts 有两个硬性校验:
- 跳过用例必须有登记原因:任何带
.前缀的跳过测试目录(如.ts_xxx/),若未在reasons.ts中登记,脚本会直接抛错; - 登记的失败用例必须真实存在:
failedReasons中登记的用例若在运行时没有产出diff.md,脚本同样抛错,提示开发者更新登记表(runner.ts)。
这意味着 ts.md 不仅是一份报告,更是一份受 CI 强约束的契约:所有不一致都必须有书面原因,所有原因都必须有对应用例。diff.md 的生成也只在用例登记于 failedReasons 时发生(runner.ts)。
三、通过用例全景:74 个用例覆盖的 TS 处理能力
当前 ts 类别共 85 个用例,其中 74 个通过。这些用例从不同维度刻画了 Rolldown 的 TypeScript 处理能力,可归纳为以下七类。
3.1 enum 处理(14 个)
enum 是 TS 中最复杂的运行时构造之一,Rolldown 的通过用例覆盖了:
- 跨模块内联:ts_enum_cross_module_inlining_access、ts_enum_cross_module_inlining_definitions、ts_enum_cross_module_inlining_re_export、ts_enum_cross_module_inlining_minify_index_into_dot;
- 跨模块 tree-shaking:ts_enum_cross_module_tree_shaking;
- 同模块内联与副作用:ts_enum_same_module_inlining_access、ts_enum_tree_shaking;
- define 语义:ts_enum_define;
- 边界情况:ts_enum_use_before_declare(先使用后声明)、ts_enum_export_clause、ts_enum_jsx、ts_sibling_enum、ts_const_enum_comments、enum_rules_from_type_script_5_0。
其中 enum_rules_from_type_script_5_0 验证的是 TypeScript 5.0 对 enum 的新规则,ts_enum_use_before_declare 则考验提升语义下的引用解析。从测试目录的 _config.json(如 ts_enum_cross_module_tree_shaking/_config.json)可以看到每个用例以 entry.ts 为输入、expectExecuted: false 表示只验证打包产物而不实际执行。
3.2 类字段语义与参数属性(12 个)
useDefineForClassFields 相关行为是 esbuild 与 TS 对齐的经典难点,通过用例包括:
- 参数属性(parameter props):parameter_props_use_define_for_class_fields_false、parameter_props_use_define_for_class_fields_true、parameter_props_use_define_for_class_fields_true_lowered;
this语义:this_inside_function_ts 及其 no-bundle / use_define 变体(共 4 个);- 抽象类字段:ts_abstract_class_field_use_assign、ts_abstract_class_field_use_define;
- 计算属性类字段:ts_computed_class_field_use_define_false、ts_computed_class_field_use_define_true、ts_computed_class_field_use_define_true_lower。
这批用例验证了 useDefineForClassFields: true/false 下类字段编译为 Object.defineProperty(use_define)还是普通赋值(use_assign)的差异,以及 target 降级(_lowered/_lower)后的行为。
3.3 declare 声明的消除(9 个)
纯类型声明应在产物中被彻底消除,通过用例覆盖了 declare 的各种形态:ts_declare_class、ts_declare_class_fields、ts_declare_const、ts_declare_const_enum、ts_declare_enum、ts_declare_function、ts_declare_let、ts_declare_namespace、ts_declare_var。
3.4 import / export 形态(16 个)
TS 的模块语法比 JS 更丰富,通过用例包括:
import equals:ts_import_equals_bundle、ts_import_equals_elimination_test、ts_import_equals_tree_shaking_false、ts_import_equals_tree_shaking_true、ts_import_equals_undefined_import;export equals与命名空间导出:ts_export_equals、ts_export_namespace;- 纯类型导入:ts_import_type_only_file、ts_import_empty_namespace;
- 本地符号冲突:ts_import_vs_local_collision_all_types、ts_import_vs_local_collision_mixed;
- 缺失导出:ts_export_missing_es6、ts_import_missing_unused_es6;
- 扩展名与模块类型:ts_import_cts、ts_import_mts;
- tree-shaking 别名:tree_shaking_import_alias_issue4507。
3.5 namespace(3 个)
ts_sibling_namespace、ts_namespace_keep_names、ts_namespace_keep_names_target_es2015,后者验证 keepNames 在 ES2015 target 下的表现。
3.6 实验性装饰器(4 个)
ts_experimental_decorators、ts_experimental_decorators_no_config、ts_experimental_decorators_keep_names、ts_experimental_decorator_scope_issue2147(对应作用域修复的历史 issue)。
3.7 压缩与其他(16 个)
- 压缩产物:ts_minified_bundle_es6、ts_minified_bundle_common_js、ts_minify_derived_class;
- enum / namespace 压缩:ts_minify_enum、ts_minify_enum_cross_file_inline_strings_into_templates、ts_minify_enum_property_names、ts_minify_nested_enum 及其
no_arrow、no_logical_assignment变体(共 3 个),ts_minify_namespace 及其变体(共 3 个); - 其他:ts_implicit_extensions(无扩展名导入推断)、ts_common_js_variable_in_esm_type_module、ts_side_effects_false_warning_type_declarations、ts_this_is_undefined_warning。
从源码结构可以推断:这些用例共同验证了 TS 转换的多趟流水线——类型擦除、模块互操作、tree-shaking 与压缩需要按正确顺序协同,任何一个环节出错都会导致产物 diff。
四、两个已知失败用例的深度剖析
4.1 ts_export_default_type_issue316:declare var 指向的导出应被保留
这是当前 TS 类别中登记的最复杂失败用例,原因标注为:
与 issue 3048 相关,指向
declare var声明的值的 export 应该被保留。
该用例目录 ts_export_default_type_issue316 内部按 keep/ 与 remove/ 两个子目录组织输入:
keep/:declare-class.ts、declare-let.ts、interface-merged.ts、interface-nested.ts、type-nested.ts、value-namespace.ts、value-namespace-merged.ts—— 这些模块的 default export 指向的类型/值声明不应被擦除;remove/:interface.ts、interface-exported.ts、type.ts、type-exported.ts、type-only-namespace.ts、type-only-namespace-exported.ts—— 这些纯类型导出应当被消除。
其 diff.md 直接展示了当前行为:esbuild 侧输出保留了所有 keep/ 模块的声明(如 var declare_class_default = foo;)并只移除 remove/ 模块的纯类型内容,而 Rolldown 当前整段产物为空(diff 中右侧全部为 -)。这说明问题出在类型擦除阶段对"值声明与类型声明合并"场景的判定上:当一个符号同时具有 declare 声明与值导出语义时,Rolldown 可能错误地将其整体判定为纯类型并连带删除了导出绑定。
4.2 ts_print_non_finite_number_inside_with:with 语句被拒绝
原因标注为 "with statement is rejected",对应 issue 7009。该用例涉及在 with 语句内部打印非有限数值,而当前构建路径整体拒绝 with 语法,因此无法通过。值得注意的是,这一限制并非 TS 专属——在 reasons.ts 中,default/comment_preservation、default/direct_eval_tainting_no_bundle 等非 TS 用例也因同一 issue 被登记为失败,说明它是跨类别的通用解析层限制。
五、Ignored 与 Not Supported:有意的边界
5.1 Ignored(行为差异)
两个被忽略的用例指向同一根因:
- ts_import_in_node_modules_name_collision_with_css
- ts_prefer_js_over_ts_inside_node_modules
原因均为:esbuild 在解析 node_modules 内的无扩展名导入时,优先选择 .js 而非 .ts。这是 esbuild 的解析优先级策略,Rolldown 选择不跟随该行为,属于设计取舍而非缺陷。
5.2 Ignored (not supported)(底层能力未覆盖)
8 个用例被归为"暂不支持",背后只有两个根因:
mangle props不被 oxc minifier 支持(6 个用例):全部是ts_experimental_decorators_mangle_props_*系列——assign_semantics、define_semantics、methods 以及对应的static_*三个变体。由于 Rolldown 的压缩由 oxc minifier 承担,属性名混淆(mangle props)能力缺失导致这批用例整体搁置;verbatimModuleSyntax=false不支持:export_type_issue379。这意味着当前实现只支持verbatimModuleSyntax开启(按原样保留类型导入)的语义,关闭该选项时的类型导入合并行为尚未实现。
从仓库策略看,这类用例不进入通过率分母中的"可忽略剔除"之外的计算(详见下一节),而是与 Ignored 一并计入 ignored 统计,但会单独成节展示原因。
六、兼容性度量:数据怎么算、怎么看
汇总数据沉淀在 stats/stats.md,其中 ts 类别当前记录为:
- total: 85,ignored: 9,passed: 74
- passed ratio: 97.37%
生成逻辑见 runner.ts 的 generateStatsMarkdown:通过率的分母会剔除 ignored 用例(total - ignored),即 74 / (85 - 9) = 97.37%。文章开头文档中的 2 个 failed + 74 个 passed + 2 个 ignored + 8 个 not supported = 85 个用例,其中 ignored 统计为 9(2 个行为差异 + 8 个不支持中的 7 个……实际统计口径为 ignoredList 与 notSupportedList 之和,即 ignored: 9 = 2 + 7,而 notSupported 完整清单为 8 项,其中 7 项计入该类别)。需要说明的是,generateStatsMarkdown 中还有第二行指标 Compatibility metric without not supported case,用于在剔除"不支持"用例后给出更高的对齐度口径——ts 类别 97.37% 的比率对应的是排除全部 ignored(含 not supported)后的口径。
这些数字会随每次 pnpm esbuild-snap-diff 运行刷新,因此本文件中的状态只代表当前快照时刻,是持续演进中的兼容性基线而非静态结论。
七、如何查看与复现:从总结到用例再到 diff
若要深入某个用例,可以从总结文档出发,按三级跳转:
- 总结层:
scripts/src/esbuild-tests/snap-diff/summary/ts.md给出状态与一句话原因; - 用例层:跳转至 crates/rolldown/tests/esbuild/ts 下的对应目录,查看
_config.json(构建配置)、entry.ts及多源文件、artifacts.snap(Rolldown 实际产物快照);失败用例还额外生成diff.md(esbuild 产物 / Rolldown 产物 / unified diff 三段式); - 登记层:失败、忽略、不支持的原因统一维护在 reasons.ts,新跳过的用例必须在此登记,否则脚本拒绝运行。
复现方式为在仓库根目录执行 pnpm esbuild-snap-diff(首次运行会下载 esbuild 快照并缓存 24 小时,可通过 --debug 查看逐用例处理日志、--verbose 输出更多细节)。由于这是内部开发脚本,运行前请确认已按 docs/development-guide/setup-the-project.md 完成依赖安装。
结语:一份会呼吸的兼容性契约
summary/ts.md 的价值远超"通过率报告"本身:它把 85 个 TS 专项用例的通过、失败、忽略与不支持状态全部显式化,并用 reasons.ts 的强校验把"每一个不一致都必须有书面理由"固化为 CI 规则。从 enum 的内联与 tree-shaking,到 useDefineForClassFields 的字段语义,再到 import equals、装饰器与 declare 声明的消除,Rolldown 在 TypeScript 处理上已与 esbuild 高度对齐,剩余差异集中在 with 语句支持、verbatimModuleSyntax=false 与 oxc minifier 的 mangle props 能力等明确已知的边界上。对开发者和下游用户而言,这份文档就是判断"我的 TS 代码能否无痛迁移到 Rolldown"最直接的事实依据。