Rolldown 的 package.json 解析能力与 esbuild 兼容性测试全景解析

原创2026-09-15 09:46:351,453 阅读
文章标签:前端构建构建工具开发工具CLI

Rolldown 的 package.json 解析能力与 esbuild 兼容性测试全景解析

导读:本文基于 Rolldown 仓库中自动生成的 esbuild 兼容性测试汇总文档 scripts/src/esbuild-tests/snap-diff/summary/packagejson.md,系统梳理 Rolldown 对 package.json 中 main、module、browser、exports、imports、type 等核心字段的解析与打包支持现状,结合测试目录源码与 rolldown_resolver 的底层实现,解释"通过用例"覆盖了哪些能力、"失败用例"差在何处,帮助读者快速定位 Rolldown 在包描述文件解析上的能力边界与已知缺口。

一、这份汇总文档是什么

scripts/src/esbuild-tests/snap-diff/summary/packagejson.md 是 Rolldown 仓库中 esbuild 快照对比测试(snap-diff) 针对 packagejson 分类自动生成的汇总报告。它属于同一目录下 summary/ 系列文档(另有 dce.md、default.md、glob.md、importstar.md、loader.md、splitting.md、ts.md 等)之一,每个文件对应 esbuild 官方测试快照的一个分类。

这份文档不包含一行手写的使用教程,而是以纯清单形式回答三个问题:

  1. 哪些用例被判定为 Failed(失败),各自的失败原因是什么;
  2. 哪些用例被判定为 Passed(通过),即 Rolldown 的输出与 esbuild 快照一致;
  3. 哪些用例被 Ignored(忽略)(本文档中该分类为空)。

其核心价值在于:把 esbuild 测试套件中与 package.json 语义相关的用例逐一映射到 Rolldown 的测试目录 crates/rolldown/tests/esbuild/packagejson/ 下,让维护者可以按图索骥,找到每一个具体行为点的输入、配置与产物快照。

二、汇总文档是如何生成的:snap-diff 机制

要读懂这份清单,需要先了解它背后的生成管线。入口脚本是 scripts/src/esbuild-tests/snap-diff/index.ts,它接受 --debug、--verbose 与用例名过滤参数后调用 run():

// scripts/src/esbuild-tests/snap-diff/index.ts
const args = process.argv.slice(2);
const debug = args.includes('--debug');
const verbose = args.includes('--verbose');
const caseNames: string[] = [];
run({ debug, verbose, caseNames });

核心流程在 scripts/src/esbuild-tests/snap-diff/runner.ts 中:

  • 从 esbuild 官方快照文件中解析出每个用例及其期望输出(parseEsbuildSnap);
  • 在 crates/rolldown/tests/esbuild/<分类>/<用例名> 下查找 Rolldown 对应的测试目录(若目录名以 . 开头则视为 skipped),读取其中的 artifacts.snap 作为 Rolldown 实际产物(parseRolldownSnap);
  • 调用 scripts/src/esbuild-tests/snap-diff/diff.ts 的 diffCase() 对两者做结构化 diff(diff.structuredPatch),支持通过每个用例目录下的 diff.config.js 自定义 rewrite 与 resolver,用于消除两边文件名生成规则差异导致的误报;
  • 根据 scripts/src/esbuild-tests/reasons.ts 中登记的分类(failedReasons / ignoreReasons / notSupportedReasons)对每个用例标注状态;
  • 最后按 "Failed / Passed / Ignored / Ignored (not supported)" 四段重新生成 summary/<分类>.md,并汇总到 scripts/src/esbuild-tests/snap-diff/stats/stats.md 计算整体兼容率。

值得注意的两处强约束(保证清单可信):

  • 任何被 skip(目录带 . 前缀)的用例,必须在 reasons.ts 中有登记原因,否则 runner 直接抛错;
  • failedReasons 中登记的用例必须真的生成 diff.md,若某用例实际上已经通过,runner 同样会抛错提醒更新登记。

对于失败用例,runner 会生成 diff.md 存入对应测试目录(见 updateDiffMarkdown 与 getDiffMarkdown),格式为"esbuild 期望输出 / rolldown 实际输出 / 统一 diff"三段式。

三、测试用例的标准形态

以通过用例 package_json_main 为例,其目录结构为:

crates/rolldown/tests/esbuild/packagejson/package_json_main/
├── src/entry.js        # 入口源码
├── _config.json        # 打包配置
└── artifacts.snap      # Rolldown 实际产物快照

_config.json 声明入口:

{
  "config": {
    "input": [{
      "name": "entry",
      "import": "./src/entry.js"
    }]
  }
}

而 artifacts.snap 记录了 Rolldown 在该配置下的真实输出。由于 Rolldown 与 esbuild 的产物文件名生成逻辑并不完全一致,diff.ts 内置了 defaultResolveFunction 做文件名重映射(例如 esbuild 的 /out.js 对应 Rolldown 的 entry.js),这正是上文中 diff.config.js 可定制部分的兜底逻辑。

每个通过用例本质上都是一个"可独立运行的最小复现",读者想验证某项行为时,直接查看对应目录的 src/、_config.json 与 artifacts.snap 即可。

四、通过用例:覆盖哪些 package.json 能力

汇总文档中 Passed Cases 共列出 65 个用例(详见原文档),全部可以在 crates/rolldown/tests/esbuild/packagejson/ 下找到同名目录。按功能域可归为以下几组:

4.1 main / module 字段解析

  • package_json_main:基础 main 字段解析;
  • package_json_main_fields_a / package_json_main_fields_b:main fields 顺序相关;
  • package_json_module:module 字段(ESM 入口);
  • package_json_neutral_explicit_main_fields:platform 为 neutral 时显式指定 main fields;
  • package_json_bad_main:main 字段非法时的兜底行为。

4.2 browser 字段

这是通过用例数量最多的组,覆盖 browser 字段的字符串形式与对象(map)形式:

  • 字符串形式:package_json_browser_string;
  • map 形式的各种映射:package_json_browser_map_module_to_module、package_json_browser_map_module_to_relative、package_json_browser_map_relative_to_relative、package_json_browser_map_relative_to_module;
  • 禁用(映射到 false)语义:package_json_browser_map_relative_disabled、package_json_browser_map_module_disabled、package_json_browser_map_native_module_disabled;
  • 与 main / module 的优先级:package_json_browser_over_main_node、package_json_browser_with_main_node、package_json_browser_over_module_browser、package_json_browser_with_module_browser;
  • 缺省扩展名解析:package_json_browser_index_no_ext、package_json_browser_no_ext、package_json_browser_node_modules_index_no_ext、package_json_browser_node_modules_no_ext;
  • 边界与回归:package_json_browser_map_avoid_missing、package_json_browser_matching_trailing_slash_issue4187(尾斜杠匹配,对应 esbuild issue 4187)、package_json_browser_issue2002_a / _c(issue 2002 的部分场景)。

4.3 exports 字段(条件导出)

  • 条件优先级:package_json_exports_import_over_require、package_json_exports_require_over_import、package_json_exports_default_over_import_and_require;
  • 入口点选择:package_json_exports_entry_point_import_over_require、package_json_exports_entry_point_main_only、package_json_exports_entry_point_module_over_main;
  • 条件语义:package_json_exports_neutral、package_json_exports_node、package_json_exports_custom_conditions、package_json_exports_browser;
  • 通配与模式:package_json_exports_wildcard(如 import 'pkg1/foo' 命中通配子路径)、package_json_exports_pattern_trailers、package_json_exports_not_exact_missing_extension;
  • 匹配顺序:package_json_exports_order_independent(结果与键顺序无关);
  • 告警:package_json_exports_default_warning_issue3887(对应 esbuild issue 3887)、package_json_bad_exports_default_warning_issue3867、package_json_bad_exports_import_and_require_warning_issue3867。

4.4 imports 字段(# 前缀子路径导入)与 self-reference

  • 基础:package_json_imports;
  • # + / 精确匹配:package_json_imports_hash_slash_exact_match;
  • 与 exports 对称性:package_json_imports_hash_slash_symmetric_with_exports;
  • 条件与通配:package_json_imports_hash_slash_with_conditions、package_json_imports_hash_slash_with_wildcard;
  • 重映射到其他包:package_json_imports_remap_to_other_package;
  • self-reference(包自我引用):package_json_import_self_using_import、package_json_import_self_using_require 及其 scoped 变体 package_json_import_self_using_import_scoped、package_json_import_self_using_require_scoped。

4.5 type 字段与双包危害(dual package hazard)

  • package_json_dual_package_hazard_import_only、package_json_dual_package_hazard_require_only、package_json_dual_package_hazard_import_and_require_same_file、package_json_dual_package_hazard_import_and_require_separate_files、package_json_dual_package_hazard_import_and_require_browser;
  • 强制 module 优先:package_json_dual_package_hazard_import_and_require_force_module_before_main、package_json_dual_package_hazard_import_and_require_implicit_main_force_module_before_main;
  • 隐式 main:package_json_dual_package_hazard_import_and_require_implicit_main;
  • package_json_type_should_be_types:type 字段值校验相关。

4.6 其他语义

  • confusing_name_collisions_issue4144(命名冲突,issue 4144)、package_json_node_paths_issue2752(NODE_PATH 相关,issue 2752)、package_json_subpath_import_node_builtin_issue3485(# 子路径导入映射到 Node 内建模块,issue 3485)。

这些用例全部通过,意味着 Rolldown 在这些场景下的产物与 esbuild 快照一致,可以作为"已支持能力"的权威清单引用。

五、失败用例:已知差异与原因

汇总文档的 Failed Cases 列出 3 个用例,每个链接到对应测试目录下的 diff.md,且原因登记在 scripts/src/esbuild-tests/reasons.ts 的 failedReasons 中。

5.1 common_js_variable_in_esm_type_module

  • 失败原因(原文):sub optimal: redundant __commonJS wrapper(次优:存在冗余的 __commonJS 包装)。
  • 测试位于 crates/rolldown/tests/esbuild/packagejson/common_js_variable_in_esm_type_module。
  • 含义:当包通过 type: "module" 被识别为 ESM,但内部出现 CJS 风格变量时,Rolldown 产物中会额外包裹一层 __commonJS 运行时包装,而 esbuild 认为该包装是多余的。这是产物质量(而非功能缺失)层面的差异,不影响正确性,但会造成冗余代码与运行时开销。

5.2 package_json_browser_issue2002_b

  • 失败原因(原文):sub is not resolved(sub 子路径未被解析)。
  • 测试目录 crates/rolldown/tests/esbuild/packagejson/package_json_browser_issue2002_b 中的入口只有一行:require('pkg/sub'),_config.json 中 expectExecuted 为 false。
  • 该目录下已生成 diff.md,直观展示了差异:esbuild 通过 browser 字段的映射,把 pkg/sub 解析到 src/node_modules/pkg/sub/foo.js,最终产出 require_foo() → require_bar() 的 __commonJS 链;而 Rolldown 当前输出为空,说明 sub 子路径未能解析成功。
  • 对比同系列通过用例 package_json_browser_issue2002_a 与 _c,可以推断该问题只在特定映射形态(子路径指向目录内文件)下触发,属于解析器对 browser 子路径映射的覆盖缺口。

5.3 package_json_disabled_type_module_issue3367

  • 失败原因(原文):ignored module debug name seems not correct(被忽略模块的调试名称看起来不正确)。
  • 测试位于 crates/rolldown/tests/esbuild/packagejson/package_json_disabled_type_module_issue3367。
  • 含义:当 type: "module" 被禁用/忽略时(issue 3367 场景),Rolldown 对相关模块的 debug name 生成与 esbuild 不一致。这属于日志/调试信息层面的差异,不影响最终产物执行结果。

从整体看,3 个失败用例均不涉及"完全无法打包"的阻断性问题:两个是产物质量或调试信息差异,一个是特定 browser 子路径映射的解析缺口,且 issue 编号(2002、3367)表明这些均为上游已知边界场景。

六、底层实现佐证:rolldown_resolver 的 package.json 处理

上述所有用例背后,真正承担 package.json 解析的是 crates/rolldown_resolver。在 crates/rolldown_resolver/src/resolver.rs 中可以看到与测试分类高度对应的实现痕迹:

  • 解析器维护了一个 package_json_cache: FxDashMap<PathBuf, Arc<PackageJson>>,对每个目录的 package.json 做缓存,避免重复解析(try_get_package_json_or_create / inner_try_get_package_json_or_create);
  • 解析结果会携带 package_json: Option<Arc<PackageJson>>,供上层决定模块的 ESM/CJS 语义(对应 type、exports、main 等字段的消费);
  • 提供 clear() 等方法用于 watch 场景下的缓存失效。

rolldown_resolver 还通过 resolver_config 暴露 mainFields、conditions 等配置,与测试中的 package_json_main_fields_a/b、package_json_exports_custom_conditions 等用例一一呼应。读者若想深挖某类字段的判定逻辑,可从 crates/rolldown_resolver/src/lib.rs 与 crates/rolldown_resolver/src/resolver_config.rs 继续跟进。

七、如何复现与参与

  • 查看单项用例:直接阅读 crates/rolldown/tests/esbuild/packagejson/<用例名>/ 下的 src/、_config.json 与 artifacts.snap;失败用例还附带 diff.md 显示具体输出差异。
  • 重跑整个对比测试:运行 scripts/src/esbuild-tests/snap-diff 相关脚本(通过 pnpm 脚本或 tsx 执行 index.ts),可带 --debug / --verbose 或传入用例名过滤;runner 会自动重新生成 summary/packagejson.md 与 stats/stats.md。
  • 修改状态登记:若某失败用例在新版本中已被修复,需要在 scripts/src/esbuild-tests/reasons.ts 中同步移除对应登记,否则 runner 会因"登记了失败但实际通过"而报错——这套强校验保证了汇总文档始终反映真实状态。

结语

summary/packagejson.md 虽然只是一份自动生成的清单,但它精确刻画了 Rolldown 在 package.json 语义解析上的能力边界:main/module/browser/exports/imports/type 的主流场景(65 个用例)已与 esbuild 输出对齐,剩余 3 个差异集中在冗余包装、特定子路径映射与调试命名上。对于需要在生产构建中依赖这些字段的开发者,这份清单与其背后的测试目录是判断"某个 package.json 特性是否可用"的第一手依据。

登录后查看全文
rolldown