Rolldown 与 esbuild 默认配置测试兼容性全景解析:从快照 diff 到失败用例治理

原创2026-09-15 12:12:191,919 阅读
文章标签:前端构建构建工具开发工具CLI

Rolldown 与 esbuild 默认配置测试兼容性全景解析:从快照 diff 到失败用例治理

本文聚焦 rolldown 仓库中「esbuild 默认配置(default 类别)兼容性测试」这一主题:它通过自动化快照对比,将 esbuild 官方 snapshots_default.txt 中的 263 个用例逐一在 Rolldown 上复现,再以 unified diff 判定输出是否一致。读完本文,你将掌握该测试体系的数据流(下载 → 解析 → diff → 生成 summary/stats)、204 个通过用例覆盖的能力范围、11 个已知失败用例与 48 个忽略/暂不支持用例的分类原因,以及如何基于 reasons.ts 维护这份兼容性清单。

背景:为什么要对 esbuild 做快照级兼容测试

Rolldown 是一个使用 Rust 编写的 JavaScript/TypeScript 打包器,对外提供 Rollup 兼容 API。而 esbuild 作为生态中最快的打包器之一,其输出形态(CommonJS 包装、import.meta 处理、top-level await 支持、JSX 转换、mangle 命名等)已成为社区的事实参照。为了衡量「默认行为」层面与 esbuild 的差距,仓库将 esbuild 官方测试快照作为对照基准,对每一类测试(dce、default、glob、importstar、loader、lower、packagejson、splitting、ts 等)逐一比对。

本文聚焦的 default 类别对应 esbuild 的 snapshots_default.txt,是覆盖面最广、最能反映「开箱即用行为」的一组用例。统计文件 stats/stats.md 显示该类别共 263 个用例,其中 204 个通过、48 个忽略,通过率 94.88%——也就是说,Rolldown 在默认配置下与 esbuild 的输出一致性已经达到较高水平,剩余差异被明确归类为「已知失败」「设计性忽略」与「暂不支持」三类,每一条都要求有据可查。

测试链路:summary 是怎么生成的

本摘要文件由快照对比运行器自动生成,核心逻辑在 snap-diff/runner.ts:

  1. 下载 esbuild 官方快照:download-snapshots.ts 按 SNAPSHOT_FILES 列表拉取 snapshots_default.txt 等文件,并以 24 小时 TTL 缓存到 scripts/tmp/esbuild-tests/snapshots/,下载失败时回退到陈旧缓存。
  2. 解析双方快照:snap-parser.ts 用 ==== 分隔符切分 esbuild 快照为单个用例,用 ---------- 切分每个用例内的输出文件;Rolldown 侧则读取每个测试目录下的 artifacts.snap,并用 remark-parse 解析 Markdown 结构取出 ## Assets 下的产物。
  3. 逐文件 diff:diff.ts 通过 defaultResolveFunction 做文件名映射(如 esbuild 的 /out.js 对位 Rolldown 的 entry.js),支持测试目录内 diff.config.js 自定义 rewrite 规则与 resolver,最后用 diff.structuredPatch 生成 unified diff。
  4. 汇总分类并输出:runner.ts 的 getSummaryMarkdownAndStats 依据 reasons.ts 中的三张表把每个用例归入 Failed / Passed / Ignored / Ignored (not supported) 四栏,写入 summary/default.md,同时把聚合统计写入 stats/stats.md。对失败用例,还会把每个输出文件的 esbuild 原文、rolldown 输出与 diff 落盘为该用例目录下的 diff.md。

这一机制保证了本文档的每条结论都有「快照比对结果 + 人工登记原因」双重依据:任何被标记为失败的用例都必须真实产生 diff,任何跳过用例都必须能在 reasons.ts 中找到理由,否则 runner 会直接抛错(见 undocumentedSkippedTests 检查逻辑)。

Failed Cases:11 个已知差异的归因分析

以下用例已产出真实 diff,且每条都登记了根因(定义于 reasons.ts 的 failedReasons)。它们可归为四类:

依赖上游 oxc 的问题

  • jsx_dev_self_edge_cases:阻塞于 oxc-project/oxc#16654。Rolldown 的 JSX 转换(jsxDev 模式下的 __self 注入)复用 oxc 的 AST 与转换器,该边界用例(如 __self 与作用域重叠)需要 oxc 侧修复。
  • comment_preservation:登记原因提到 with 语句被拒绝(关联 rolldown#7009)。该用例 diff.md 中可以看到动态 import() 参数位置的注释(/* before */、/* after */)与 assert 参数的注释排布差异。
  • comment_preservation_preserve_jsx、comment_preservation_transform_jsx:comments are not kept properly,注释保留在 JSX preserve/transform 两种模式下均有缺口。
  • direct_eval_tainting_no_bundle:同样被 with 语句拒绝问题阻塞(rolldown#7009),并且存在次优解:test4 参数位置的 eval 无需重命名。

输出形态的次优化(sub optimal)

需要重命名的语义缺口

  • false_require:当 require 出现在参数位置(非真实调用)时应被重命名,目前未处理。

失败用例对应的逐文件 diff 均可在各用例目录的 diff.md 中查看,例如 comment_preservation/diff.md 以 ## /out/entry.js、### esbuild、### rolldown、### diff 的结构呈现三份对照内容,是定位具体差异的第一手材料。

Passed Cases:204 个通过用例的能力地图

default 类别下 204 个用例与 esbuild 输出完全一致(含 rewrite 规则归一化后的等价),从源码结构看覆盖了以下能力域,是「Rolldown 默认行为 = esbuild 默认行为」的直接证据:

  • 模块格式互转:common_js_from_es6、es6_from_common_js、nested_common_js、nested_es6_from_common_js、export_forms_common_js/es6/iife、exports_and_module_format_common_js、iife_es5、to_esm_wrapper_omission、decorator_printing_cjs/esm、string_export_names_common_js/iife 等。
  • 顶层 await(TLA)系列:top_level_await_esm、top_level_await_cjs_dead_branch、top_level_await_iife_dead_branch、top_level_await_cyclic_dependencies_issue4498、top_level_await_allowed_import_without_splitting 以及整套 top_level_await_no_bundle* 变体(esm/cjs/iife、dead branch)。
  • JSX:jsx_automatic_imports_common_js/es6、jsx_constant_fragments、jsx_imports_common_js/es6、jsx_this_property_common_js/esm、jsx_this_value_common_js/esm、jsx_automatic_syntax_in_js。
  • mangle 命名混淆:mangle_props 全家族(avoid_collisions、import_export_bundled、jsx_preserve、jsx_transform、key_comment、keyword_property_minify、lowered_class_fields、lowered_optional_chain、minify、no_shorthand、optional_chain、shorthand、super_call)、mangle_no_quoted_props*、mangle_quoted_props*、reserve_props、preserve_key_comment、quoted_property。
  • minify 压缩:minified_bundle_common_js/es6、minified_bundle_ending_with_important_semicolon、minified_dynamic_import_with_expression_cjs、minified_exports_and_module_format_common_js、minified_jsx_preserve_with_object_spread、minify_arguments、minify_identifiers_import_path_frequency_analysis、minify_private_identifiers_no_bundle、minify_sibling_labels_no_bundle、char_freq_ignore_comments。
  • require 语义:require_child_dir_common_js/es6、require_parent_dir_common_js/es6、require_property_access_common_js、require_resolve、require_json、require_txt、require_with_call_inside_try、require_with_template、require_without_call(_inside_try)、require_bad_argument_count、require_main_cache_common_js、false_require 之外的全部 require 相关用例。
  • external 与解析:external_packages、auto_external、auto_external_node、external_module_exclusion_package/relative_path、external_wildcard_does_not_match_entry_point、scoped_external_module_exclusion、built_in_node_module_precedence、node_modules、outbase、many_entry_points、duplicate_entry_point、multiple_entry_points_same_name_collision。
  • import.meta / define:define_import_meta、define_this、define_assign_warning、define_optional_chain(_lowered)、define_infinite_loop_issue2407、import_meta_common_js/es6/no_bundle。
  • inject 注入:inject、inject_import_meta、inject_jsx_dot_names、inject_no_bundle、inject_with_define、inject_with_string_re_export_name_no_bundle。
  • hashbang 与 use strict:hashbang_bundle/no_bundle、hashbang_banner_use_strict_order、use_strict_directive_bundle_cjs/esm/iife_issue2264、use_strict_directive_bundle_issue1837、use_strict_directive_minify_no_bundle。
  • 导出形态与命名:export_chain、export_special_name(_bundle)、export_fs_node(_in_common_js_module)、export_wildcard_fs_node_common_js/es6、re_export_* 全家族、import_forms_with_* 系列、import_namespace_this_value、import_re_export_es6_issue149。
  • 作用域与变量处理:arrow_fn_scope、argument_default_value_scope_no_bundle、arguments_special_case_no_bundle、switch_scope_no_bundle、rename_labels_no_bundle、rename_nested_var、rename_private_identifiers_no_bundle、var_relocating_bundle/no_bundle、const_with_let(_no_bundle/_no_mangle)、avoid_tdz(_no_bundle)、nested_scope_bug、named_function_expression_argument_collision。
  • other 输出细节:source_map、output_extension_remapping_dir/file、bundling_files_outside_of_outbase、source_identifier_name_index_single/multiple_entry、runtime_name_collision_no_bundle、legal_comments_inline、legal_comments_merge_duplicates_issue4139、keep_names_* 系列、this_inside/outside_function、this_undefined_warning_esm、this_with_es6_syntax、strict_mode_nested_fn_decl_keep_names_variable_inlining_issue1552、object_literal_proto_setter_edge_cases(_minify_syntax)、dynamic_import_with_expression_cjs、dynamic_import_with_template_iife、import_then_catch、conditional_import/require、call_import_namespace_warning、duplicate_property_warning、import_abs_path_with_query_parameter、import_with_hash_in_path、indirect_require_message、non_determinism_issue2537、node_annotation_*、dot_import、nested_require_without_call、empty_export_clause_bundle_as_common_js_issue910、await_import_inside_try、top_level_await_* 其余变体、warn_common_js_exports_in_esm_bundle/convert、with_statement_tainting_no_bundle 等。

完整的 204 项清单见本摘要的 Passed Cases 一节;每个通过用例目录(如 simple_es6)内含 _config.json、entry.js 与 artifacts.snap,可直接作为复现与回归的样例。

Ignored Cases:22 个设计性忽略

这一组用例被跳过,但属于「有意为之」:Rolldown 在对应行为上选择了与 esbuild 不同的设计(登记于 ignoreReasons)。主要包括:

  • 与 @rollup/plugin-inject 对齐的 inject 行为:inject_duplicate、inject_import_order、inject_import_ts、inject_with_string_export_name_bundle/no_bundle 均因「inject 特性与 @rollup/plugin-inject 对齐,不支持直接注入源文件」被忽略;inject_jsx 则受多趟转换架构限制(需先 Define 再 Transform)。
  • 多趟转换架构(multi pass transformer)限制:jsx_import_meta_property、jsx_import_meta_value 中 JSX 转换注入的 import.meta 无法被 define 插件替换(define 先于 JSX transform 执行)。
  • resolve alias 行为差异:package_alias、package_alias_match_longest、warnings_inside_node_modules。
  • 无关选项(irrelevant):line_limit_minified、line_limit_not_minified(lineLimit 选项不会支持);entry_names_no_slash_after_dir(Rolldown 的 entryFileNames 没有 [dir] 占位符)。
  • CI 基础设施限制:entry_names_non_portable_character、import_abs_path_as_dir、import_abs_path_as_file(测试难以在 CI 稳定通过)。
  • 其他:define_import_meta_es5(target: 'es5' 不支持)、quoted_property_mangle(已由 minifier 覆盖)、legal_comments_modify_indent 与 metafile_no_bundle(CSS 打包不支持,见 rolldown#4271)。

Ignored Cases (not supported):26 个暂不支持能力

最后一组是当前明确「不支持」的功能面,每条都对应一个具体的技术债(登记于 notSupportedReasons):

  • import attributes / assertions 不支持:comment_preservation_import_assertions、metafile_import_with_type_json、output_for_assert_type_json。
  • legalComments 模式缺口:legal_comments_end_of_file、legal_comments_external、legal_comments_linked、legal_comments_many_end_of_file/linked 等十余个用例覆盖了 'eof'、'external'、'linked'、'none' 模式;legal_comments_*_avoid_slash_tag_* 系列还叠加了「CSS 中 </style> 转义不支持」。
  • oxc minifier 能力边界:mangle_props_jsx_transform_namespace、mangle_props_type_script_features(mangle props)、minify_nested_labels_no_bundle(label mangling)。
  • loader / 资源相关:metafile_various_cases、metafile_very_long_external_paths(copy loader)、require_and_dynamic_import_invalid_template(glob)、require_shim_substitution(require 第二参数)、conditional_require_resolve(条件 require.resolve 转换)、import_with_hash_parameter、import_with_query_parameter(hash/query 参数剥离)。

统计口径与如何阅读指标

stats/stats.md 给出了 default 类别的量化结论:total: 263 / ignored: 48 / passed: 204 / passed ratio: 94.88%。口径由 runner.ts 定义:通过率 = passed / (total − ignored),其中 ignored 是 ignoreReasons 与 notSupportedReasons 两条清单的总和(22 + 26 = 48),即「设计性跳过」不计入分母;与之相对的「全量兼容度」则把 notSupported 用例也视为分母的一部分。这两组数字分别回答「已覆盖范围内的一致性」与「绝对覆盖度」两个问题。

若要亲手复现:在仓库根目录运行快照对比入口 snap-diff/index.ts(支持 --debug、--verbose 参数,也可传入具体用例名过滤),即可在 summary/ 与 stats/ 下重新生成本文件;新增用例或修复差异后,需同步维护 reasons.ts 中的三张登记表,runner 会强制校验「跳过必有理由、失败必有 diff」这一治理约束。

结语

从这份 default 类别摘要可以看出,Rolldown 在默认配置下与 esbuild 的输出一致性已达 94.88%(排除设计性忽略后),204 个通过用例横跨 CJS/ESM/IIFE 互转、TLA、JSX、mangle、minify、require、external、inject 等核心场景;剩余差异被严格分为「已知失败(依赖上游修复或输出次优化)」「设计性忽略(与 Rollup 生态对齐的主动选择)」与「暂不支持(能力缺口)」三层,且每一层都有可审计的登记原因与可复现的 diff 证据。这套「快照比对 + 原因登记 + 强校验」的机制,本身就是衡量打包器行为兼容性的优秀工程实践,也为社区跟踪 Rolldown 的 esbuild 兼容进度提供了透明、可量化的窗口。

登录后查看全文
rolldown