Rolldown 的 package.json 解析能力与 esbuild 兼容性测试全景解析
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 官方测试快照的一个分类。
这份文档不包含一行手写的使用教程,而是以纯清单形式回答三个问题:
- 哪些用例被判定为 Failed(失败),各自的失败原因是什么;
- 哪些用例被判定为 Passed(通过),即 Rolldown 的输出与 esbuild 快照一致;
- 哪些用例被 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 特性是否可用"的第一手依据。