Rolldown 与 esbuild 默认配置测试兼容性全景解析:从快照 diff 到失败用例治理
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:
- 下载 esbuild 官方快照:download-snapshots.ts 按 SNAPSHOT_FILES 列表拉取
snapshots_default.txt等文件,并以 24 小时 TTL 缓存到scripts/tmp/esbuild-tests/snapshots/,下载失败时回退到陈旧缓存。 - 解析双方快照:snap-parser.ts 用
====分隔符切分 esbuild 快照为单个用例,用----------切分每个用例内的输出文件;Rolldown 侧则读取每个测试目录下的artifacts.snap,并用remark-parse解析 Markdown 结构取出## Assets下的产物。 - 逐文件 diff:diff.ts 通过 defaultResolveFunction 做文件名映射(如 esbuild 的
/out.js对位 Rolldown 的entry.js),支持测试目录内diff.config.js自定义 rewrite 规则与 resolver,最后用diff.structuredPatch生成 unified diff。 - 汇总分类并输出: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)
- export_forms_with_minify_identifiers_and_no_bundle:不应生成重复的 export binding。
- external_es6_converted_to_common_js:ESM 转 CJS 后出现冗余
import语句(外部模块声明未完全收敛)。 - mangle_props_import_export:
__require的 diff 源于缺少ModePassThrough直通模式。 - no_warn_common_js_exports_in_esm_pass_through:缺少 pass-through 模式,目前仅在特定分支下与 esbuild 输出一致。
- top_level_await_allowed_import_with_splitting:开启代码分割后产生空 chunk,应被移除。
需要重命名的语义缺口
- 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 兼容进度提供了透明、可量化的窗口。