尧图网站建设 
Rolldown CJS 输出与 cjs-module-lexer 兼容性指南让 CommonJS 产物被 Node.js 原生识别【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown本篇技术指南围绕 Rolldown 仓库中crates/rolldown/tests/rolldown/topics/cjs_module_lexer_compat这一专门测试主题展开讲解 Rolldown 为何要保证其 CommonJSCJS输出与 Node.js 内置的cjs-module-lexer解析器完全兼容以及通过哪几类测试用例来验证这种兼容性。读完本文你将理解 Node.js 通过静态import加载 CJS 模块时的导出检测机制掌握 Rolldown 在format: cjs输出下命名导出、特殊字符导出名、export *转发等场景的产物形态并能够自己阅读和运行这些兼容性测试。一、背景Node.js 如何解析 CJS 模块的导出在现代 Node.js 生态中ESMECMAScript Modules代码可以通过静态import语句直接引入一个 CommonJS 模块。但 CommonJS 模块本身并没有静态的export声明它只有module.exports这种动态赋值语义。为了在加载阶段就能知道“这个 CJS 模块暴露了哪些命名导出”Node.js 使用了cjs-module-lexer这一词法分析工具它不执行模块代码而是通过解析源码静态地扫描出模块的导出exports与再导出reexports。这一机制带来两个关键推论Node.js 使用cjs-module-lexer解析通过静态import引入的 CommonJS 模块被检测出的导出可以被 ESM 侧通过命名导入named import方式直接使用例如import { readFileSync } from node:fs。这意味着如果一个打包器把 ESM 源码编译成 CJS 产物那么该产物的导出写法必须足够“可被词法扫描识别”——如果产物里用cjs-module-lexer无法静态分析的动态方式暴露导出Node.js 就无法正确提供命名导入甚至可能整体失败。这正是本仓库中cjs_module_lexer_compat测试主题存在的根本原因。二、测试主题定位为什么 Rolldown 需要这套兼容性测试关联文档 crates/rolldown/tests/rolldown/topics/cjs_module_lexer_compat/README.md 明确了该目录的定位This folder contains tests for compatibility with thecjs-module-lexerpackage.其目标可以概括为三句话对齐 Node.js 的真实解析行为Node.js 使用cjs-module-lexer解析静态import的 CJS 模块因此 Rolldown 的 CJS 输出必须以该解析器能够识别的方式生成保障命名导入可用被检测出的导出应能被 ESM 侧通过命名导入引用而不是只能整体require让 CJS 产物对 Node.js 友好这是 Rolldown CJS 输出的质量底线之一直接关系到打包结果在 Node.js 运行时中的可用性。一句话概括Rolldown 输出的 CJS 代码必须能被cjs-module-lexer静态识别出与源码语义一致的导出集合。三、测试的组织方式与验证手段该目录下的每个子用例都遵循同一套测试布局cjs_module_lexer_compat/ ├── README.md # 主题说明本文依据 ├── export_star_from_external/ # 用例export * 转发外部模块 │ ├── _config.json # 打包配置 │ ├── _test.mjs # 断言脚本调用 cjs-module-lexer 解析产物 │ ├── artifacts.snap # 打包产物快照 │ └── main.js # 输入源码 ├── exports/ # 用例各类命名导出 └── import_and_reexport/ # 用例导入后再导出每个用例由三部分组成main.jsESM 风格的输入源码被测对象_config.jsonRolldown 打包配置决定产物格式_test.mjs真正的“考官”——它用cjs-module-lexer的parse函数解析生成的dist/main.js产物并用assert.deepStrictEqual断言解析出的exports与reexports与期望值完全一致。_test.mjs的通用骨架如下以exports用例为例const require (await import(node:module)).createRequire(import.meta.url); const fs require(node:fs); const assert require(node:assert); const path require(node:path); const { parse } require(cjs-module-lexer); const parsed parse(fs.readFileSync(path.resolve(import.meta.dirname, dist/main.js), utf8)); parsed.exports.sort(); assert.deepStrictEqual(parsed, { exports: [a, b, , default].sort(), reexports: [], });要点说明测试在 ESM.mjs环境中运行通过createRequire获得require从而同时加载 Node 内置模块与cjs-module-lexer包产物固定输出到每个用例目录下的dist/main.js断言的是parse返回对象的完整结构exportsreexports两个字段排序后再比对避免顺序敏感。这套测试相当于把“Node.js 视角”直接搬进了 CI不是看产物“长得好不好看”而是看它在真实 Node.js 解析器眼里暴露出了什么。四、三个测试用例逐一解析4.1 用例一exports —— 常规命名导出、特殊字符导出名与默认导出输入源码exports/main.jsexport const a a; export const b b; const devil devil; export { devil as }; export default default;该用例刻意覆盖了几个容易出问题的点两个常规命名导出a、b一个非标识符字符的导出名emoji 作为导出别名一个export default默认导出。打包配置exports/_config.json{ config: { format: cjs, esModule: always, exports: named } }配置含义format: cjs产物为 CommonJS 格式esModule: always总是为产物标记__esModule即使源码中没有默认导出也会标记从而让 Node.js/其他打包器能识别出“这是一个由 ESM 编译而来的 CJS 模块”exports: named以命名导出的方式暴露每个导出而不是合并成一个默认对象。产物快照exports/artifacts.snap 展示了 Rolldown 实际生成的 CJS 代码Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: Module } }); //#region main.js const a a; const b b; const devil devil; var main_default default; //#endregion exports.a a; exports.b b; exports.default main_default; exports[] devil;分析这段产物为什么能被cjs-module-lexer识别exports.a a;、exports.b b;是标准的静态属性写入是cjs-module-lexer最擅长识别的模式exports[] devil;用字符串字面量键写入导出cjs-module-lexer同样能静态提取出导出名exports.default main_default;把默认导出映射为default命名导出开头的Object.defineProperties(exports, { __esModule: ..., [Symbol.toStringTag]: ... })是 ESM→CJS 产物的标准“模块身份标记”不影响exports/reexports的解析结果。断言脚本exports/_test.mjs 最终断言assert.deepStrictEqual(parsed, { exports: [a, b, , default].sort(), reexports: [], });即cjs-module-lexer必须从产物中识别出全部 4 个导出名——包括 emoji 导出名且不得有再导出。4.2 用例二export_star_from_external —— 透传转发外部模块输入源码export_star_from_external/main.jsexport * from node:fs; export * from node:path;打包配置export_star_from_external/_config.json{ config: { format: cjs, external: [node:fs, node:path] } }两个 Node 内置模块被声明为external——它们不会被打包进产物而是在产物中以require(node:fs)的形式保留。断言脚本export_star_from_external/_test.mjsparsed.reexports.sort(); assert.deepStrictEqual(parsed, { exports: [], reexports: [node:fs, node:path].sort(), });这个用例验证的是export *转发场景当 Rolldown 把export * from node:fs编译进 CJS 产物时产物必须通过可被静态识别的再导出方式即reexports数组能检测出node:fs、node:path告诉 Node.js“这个模块转发了哪些外部模块的导出”而不是把这些导出展开成无法追踪的动态赋值。4.3 用例三import_and_reexport —— 导入并再次导出输入源码import_and_reexport/main.jsimport { readFileSync } from external; export * from external; export { readFileSync };打包配置import_and_reexport/_config.json{ config: { format: cjs, external: [external] } }断言脚本import_and_reexport/_test.mjsassert.deepStrictEqual(parsed, { exports: [readFileSync], reexports: [external], });这是一个更混合的场景既从外部模块external导入了readFileSync并显式再导出因此exports中应有readFileSync又对external做了export *整体转发因此reexports中应有external。它同时覆盖了“具名再导出”与“星号再导出”两条路径确保两者在产物中都能被cjs-module-lexer正确区分。五、从源码看 CJS 输出的生成逻辑兼容性测试背后是 Rolldown 在 CJS 输出生成与识别上的刻意设计。仓库中 crates/rolldown/src/ast_scanner/cjs_export_analyzer.rs 是一个很好的印证Rolldown 在处理 CommonJS 输入时会识别module.exports.__esModule true、Object.defineProperty(module.exports, __esModule, { value: true })等典型的__esModule标记写法并区分不同的 CJS AST 形态如CommonJsAstType::ExportsPropWrite(__esModule.into())。这表明__esModule标记在 Rolldown 的 AST 分析中是一等公民无论是从输入 CJS 中识别还是在输出 CJS 时生成都有对应的处理路径产物开头的Object.defineProperties(exports, { __esModule, [Symbol.toStringTag] })与输入识别逻辑形成闭环保证“ESM 编译而来”的模块在 Node.js 侧被当作 ESM 兼容模块对待。由此可以推断Rolldown 在生成 CJS 导出语句时刻意选择了exports.name value、exports[string-literal] value这类cjs-module-lexer可静态分析的形式并保留了require(...)形式的再导出调用以配合reexports检测。六、这套测试的实际价值产物可移植性任何被 Node.js 静态import的 CJS 产物只要通过了本套测试就能保证命名导入可用——这是打包结果“开箱即用”的关键回归防线cjs-module-lexer对导出写法的识别是模式化的一旦产物生成逻辑重构例如调整导出语句的生成方式这类测试会立即在 CI 中暴露兼容性回退可读的失败信号测试直接断言parse结果与期望值deepStrictEqual失败时能清晰看到“解析出了什么 vs 期望什么”定位成本低。七、如何本地运行这些测试仓库的测试体系基于 crates/rolldown_testing/src/integration_test.rs 构建artifacts.snap快照的source字段即指向该文件。如需本地验证确保 Node.js 环境可用并在测试依赖中安装cjs-module-lexer包_test.mjs中require(cjs-module-lexer)执行对应的测试命令仓库整体测试入口可参考 CONTRIBUTING.md 与 docs/development-guide/testing.md测试框架会依次完成读取_config.json→ 对main.js执行打包 → 生成dist/main.js→ 运行_test.mjs断言若要新增用例只需按既有布局新建目录main.js_config.json_test.mjs并保证产物被cjs-module-lexer解析出符合预期的exports/reexports。八、小结cjs_module_lexer_compat测试主题回答了一个非常实际的问题当 Rolldown 把 ESM 打包成 CJS 时产物能否被 Node.js 的原生 CJS 解析机制cjs-module-lexer正确理解。通过exports、export_star_from_external、import_and_reexport三个用例它覆盖了命名导出、特殊字符导出名、默认导出、外部模块星号转发、具名再导出等全部关键路径用真实解析器做断言把“对 Node.js 友好”从一句口号变成了可验证的工程约束。这也是 Rolldown 在 CJS 输出质量上的一个具体落点产出规范的、可被静态分析的、与 Node.js 生态互通的 CommonJS 代码。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rolldown CJS 输出与 cjs-module-lexer 兼容性指南：让 CommonJS 产物被 Node.js 原生识别
Rolldown CJS 输出与 cjs-module-lexer 兼容性指南让 CommonJS 产物被 Node.js 原生识别【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown本篇技术指南围绕 Rolldown 仓库中crates/rolldown/tests/rolldown/topics/cjs_module_lexer_compat这一专门测试主题展开讲解 Rolldown 为何要保证其 CommonJSCJS输出与 Node.js 内置的cjs-module-lexer解析器完全兼容以及通过哪几类测试用例来验证这种兼容性。读完本文你将理解 Node.js 通过静态import加载 CJS 模块时的导出检测机制掌握 Rolldown 在format: cjs输出下命名导出、特殊字符导出名、export *转发等场景的产物形态并能够自己阅读和运行这些兼容性测试。一、背景Node.js 如何解析 CJS 模块的导出在现代 Node.js 生态中ESMECMAScript Modules代码可以通过静态import语句直接引入一个 CommonJS 模块。但 CommonJS 模块本身并没有静态的export声明它只有module.exports这种动态赋值语义。为了在加载阶段就能知道“这个 CJS 模块暴露了哪些命名导出”Node.js 使用了cjs-module-lexer这一词法分析工具它不执行模块代码而是通过解析源码静态地扫描出模块的导出exports与再导出reexports。这一机制带来两个关键推论Node.js 使用cjs-module-lexer解析通过静态import引入的 CommonJS 模块被检测出的导出可以被 ESM 侧通过命名导入named import方式直接使用例如import { readFileSync } from node:fs。这意味着如果一个打包器把 ESM 源码编译成 CJS 产物那么该产物的导出写法必须足够“可被词法扫描识别”——如果产物里用cjs-module-lexer无法静态分析的动态方式暴露导出Node.js 就无法正确提供命名导入甚至可能整体失败。这正是本仓库中cjs_module_lexer_compat测试主题存在的根本原因。二、测试主题定位为什么 Rolldown 需要这套兼容性测试关联文档 crates/rolldown/tests/rolldown/topics/cjs_module_lexer_compat/README.md 明确了该目录的定位This folder contains tests for compatibility with thecjs-module-lexerpackage.其目标可以概括为三句话对齐 Node.js 的真实解析行为Node.js 使用cjs-module-lexer解析静态import的 CJS 模块因此 Rolldown 的 CJS 输出必须以该解析器能够识别的方式生成保障命名导入可用被检测出的导出应能被 ESM 侧通过命名导入引用而不是只能整体require让 CJS 产物对 Node.js 友好这是 Rolldown CJS 输出的质量底线之一直接关系到打包结果在 Node.js 运行时中的可用性。一句话概括Rolldown 输出的 CJS 代码必须能被cjs-module-lexer静态识别出与源码语义一致的导出集合。三、测试的组织方式与验证手段该目录下的每个子用例都遵循同一套测试布局cjs_module_lexer_compat/ ├── README.md # 主题说明本文依据 ├── export_star_from_external/ # 用例export * 转发外部模块 │ ├── _config.json # 打包配置 │ ├── _test.mjs # 断言脚本调用 cjs-module-lexer 解析产物 │ ├── artifacts.snap # 打包产物快照 │ └── main.js # 输入源码 ├── exports/ # 用例各类命名导出 └── import_and_reexport/ # 用例导入后再导出每个用例由三部分组成main.jsESM 风格的输入源码被测对象_config.jsonRolldown 打包配置决定产物格式_test.mjs真正的“考官”——它用cjs-module-lexer的parse函数解析生成的dist/main.js产物并用assert.deepStrictEqual断言解析出的exports与reexports与期望值完全一致。_test.mjs的通用骨架如下以exports用例为例const require (await import(node:module)).createRequire(import.meta.url); const fs require(node:fs); const assert require(node:assert); const path require(node:path); const { parse } require(cjs-module-lexer); const parsed parse(fs.readFileSync(path.resolve(import.meta.dirname, dist/main.js), utf8)); parsed.exports.sort(); assert.deepStrictEqual(parsed, { exports: [a, b, , default].sort(), reexports: [], });要点说明测试在 ESM.mjs环境中运行通过createRequire获得require从而同时加载 Node 内置模块与cjs-module-lexer包产物固定输出到每个用例目录下的dist/main.js断言的是parse返回对象的完整结构exportsreexports两个字段排序后再比对避免顺序敏感。这套测试相当于把“Node.js 视角”直接搬进了 CI不是看产物“长得好不好看”而是看它在真实 Node.js 解析器眼里暴露出了什么。四、三个测试用例逐一解析4.1 用例一exports —— 常规命名导出、特殊字符导出名与默认导出输入源码exports/main.jsexport const a a; export const b b; const devil devil; export { devil as }; export default default;该用例刻意覆盖了几个容易出问题的点两个常规命名导出a、b一个非标识符字符的导出名emoji 作为导出别名一个export default默认导出。打包配置exports/_config.json{ config: { format: cjs, esModule: always, exports: named } }配置含义format: cjs产物为 CommonJS 格式esModule: always总是为产物标记__esModule即使源码中没有默认导出也会标记从而让 Node.js/其他打包器能识别出“这是一个由 ESM 编译而来的 CJS 模块”exports: named以命名导出的方式暴露每个导出而不是合并成一个默认对象。产物快照exports/artifacts.snap 展示了 Rolldown 实际生成的 CJS 代码Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: Module } }); //#region main.js const a a; const b b; const devil devil; var main_default default; //#endregion exports.a a; exports.b b; exports.default main_default; exports[] devil;分析这段产物为什么能被cjs-module-lexer识别exports.a a;、exports.b b;是标准的静态属性写入是cjs-module-lexer最擅长识别的模式exports[] devil;用字符串字面量键写入导出cjs-module-lexer同样能静态提取出导出名exports.default main_default;把默认导出映射为default命名导出开头的Object.defineProperties(exports, { __esModule: ..., [Symbol.toStringTag]: ... })是 ESM→CJS 产物的标准“模块身份标记”不影响exports/reexports的解析结果。断言脚本exports/_test.mjs 最终断言assert.deepStrictEqual(parsed, { exports: [a, b, , default].sort(), reexports: [], });即cjs-module-lexer必须从产物中识别出全部 4 个导出名——包括 emoji 导出名且不得有再导出。4.2 用例二export_star_from_external —— 透传转发外部模块输入源码export_star_from_external/main.jsexport * from node:fs; export * from node:path;打包配置export_star_from_external/_config.json{ config: { format: cjs, external: [node:fs, node:path] } }两个 Node 内置模块被声明为external——它们不会被打包进产物而是在产物中以require(node:fs)的形式保留。断言脚本export_star_from_external/_test.mjsparsed.reexports.sort(); assert.deepStrictEqual(parsed, { exports: [], reexports: [node:fs, node:path].sort(), });这个用例验证的是export *转发场景当 Rolldown 把export * from node:fs编译进 CJS 产物时产物必须通过可被静态识别的再导出方式即reexports数组能检测出node:fs、node:path告诉 Node.js“这个模块转发了哪些外部模块的导出”而不是把这些导出展开成无法追踪的动态赋值。4.3 用例三import_and_reexport —— 导入并再次导出输入源码import_and_reexport/main.jsimport { readFileSync } from external; export * from external; export { readFileSync };打包配置import_and_reexport/_config.json{ config: { format: cjs, external: [external] } }断言脚本import_and_reexport/_test.mjsassert.deepStrictEqual(parsed, { exports: [readFileSync], reexports: [external], });这是一个更混合的场景既从外部模块external导入了readFileSync并显式再导出因此exports中应有readFileSync又对external做了export *整体转发因此reexports中应有external。它同时覆盖了“具名再导出”与“星号再导出”两条路径确保两者在产物中都能被cjs-module-lexer正确区分。五、从源码看 CJS 输出的生成逻辑兼容性测试背后是 Rolldown 在 CJS 输出生成与识别上的刻意设计。仓库中 crates/rolldown/src/ast_scanner/cjs_export_analyzer.rs 是一个很好的印证Rolldown 在处理 CommonJS 输入时会识别module.exports.__esModule true、Object.defineProperty(module.exports, __esModule, { value: true })等典型的__esModule标记写法并区分不同的 CJS AST 形态如CommonJsAstType::ExportsPropWrite(__esModule.into())。这表明__esModule标记在 Rolldown 的 AST 分析中是一等公民无论是从输入 CJS 中识别还是在输出 CJS 时生成都有对应的处理路径产物开头的Object.defineProperties(exports, { __esModule, [Symbol.toStringTag] })与输入识别逻辑形成闭环保证“ESM 编译而来”的模块在 Node.js 侧被当作 ESM 兼容模块对待。由此可以推断Rolldown 在生成 CJS 导出语句时刻意选择了exports.name value、exports[string-literal] value这类cjs-module-lexer可静态分析的形式并保留了require(...)形式的再导出调用以配合reexports检测。六、这套测试的实际价值产物可移植性任何被 Node.js 静态import的 CJS 产物只要通过了本套测试就能保证命名导入可用——这是打包结果“开箱即用”的关键回归防线cjs-module-lexer对导出写法的识别是模式化的一旦产物生成逻辑重构例如调整导出语句的生成方式这类测试会立即在 CI 中暴露兼容性回退可读的失败信号测试直接断言parse结果与期望值deepStrictEqual失败时能清晰看到“解析出了什么 vs 期望什么”定位成本低。七、如何本地运行这些测试仓库的测试体系基于 crates/rolldown_testing/src/integration_test.rs 构建artifacts.snap快照的source字段即指向该文件。如需本地验证确保 Node.js 环境可用并在测试依赖中安装cjs-module-lexer包_test.mjs中require(cjs-module-lexer)执行对应的测试命令仓库整体测试入口可参考 CONTRIBUTING.md 与 docs/development-guide/testing.md测试框架会依次完成读取_config.json→ 对main.js执行打包 → 生成dist/main.js→ 运行_test.mjs断言若要新增用例只需按既有布局新建目录main.js_config.json_test.mjs并保证产物被cjs-module-lexer解析出符合预期的exports/reexports。八、小结cjs_module_lexer_compat测试主题回答了一个非常实际的问题当 Rolldown 把 ESM 打包成 CJS 时产物能否被 Node.js 的原生 CJS 解析机制cjs-module-lexer正确理解。通过exports、export_star_from_external、import_and_reexport三个用例它覆盖了命名导出、特殊字符导出名、默认导出、外部模块星号转发、具名再导出等全部关键路径用真实解析器做断言把“对 Node.js 友好”从一句口号变成了可验证的工程约束。这也是 Rolldown 在 CJS 输出质量上的一个具体落点产出规范的、可被静态分析的、与 Node.js 生态互通的 CommonJS 代码。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考