深入解析 Oxc transform 的 CommonJS 输出行为：为何它保留 ESM 而不做 ESM→CJS 转换

深入解析 Oxc transform 的 CommonJS 输出行为：为何它保留 ESM 而不做 ESM→CJS 转换

【免费下载链接】tsx⚡️ TypeScript Execute | The easiest way to run TypeScript in Node.js项目地址: https://gitcode.com/gh_mirrors/ts/tsx

导读

本文聚焦 tsx 项目研究笔记中 Oxc transform 的 CommonJS 输出专题，核心回答一个问题：Oxc 的 NAPI transform 在什么条件下会产生 CommonJS 输出？结论是：Oxc 的 NAPI transform 没有暴露"输出模块格式"选项，内部模块选项恒为Preserve，因此它只保留 ESM 语法；sourceType: "commonjs"只改变解析规则，并不会把 ESM 降级为 CJS。读完本文，你将理解 Oxc transform 与 esbuild 在 CJS 输出上的能力边界、TypeScript module pass 实际降级的语法子集（仅import = require()与export =），以及这一差异如何决定了 tsx 当前仍以 esbuild 作为通用转换后端、而将 Oxc 标记为"模块输出被阻塞"的候选后端。

Oxc NAPI transform 的模块输出：没有 output-module 选项

要理解 CommonJS 输出行为，首先看 Oxc NAPI transform 暴露了什么。从 notes/oxc-transform/README.md 可知，Oxc 的 NAPI transform 是 tsx 研究中的候选后端之一，其转换能力覆盖 TypeScript 转换、语义引用分析和生成 helper 行为。

关键事实来自关联文档的第一句话：NAPI transform 暴露了源语言/模块分类能力，但没有暴露"输出模块"（output-module）选项。也就是说，你可以在调用时告诉 Oxc "输入按什么语言/模块类型解析"，却无法告诉它 "请把结果输出为 CommonJS 或 AMD 格式"。这与 esbuild 的format: 'cjs'/format: 'esm'形成了鲜明对比——esbuild 的转换 API 直接支持指定输出格式（tsx 正是在transformSync()中设置format: 'cjs'，在transform()中设置format: 'esm'，见 src/utils/transform/index.ts 与 src/utils/transform/index.ts）。

既然没有公开的 output-module 选项，NAPI 转换内部会怎么做？文档指出：NAPI 转换层把内部模块选项留在其默认值Preserve上。Preserve意味着转换器不会主动把模块语法改写为其他模块系统——输入的模块形态被"原样保留"。因此，即便你把sourceType指定为"commonjs"，也不会得到 ESM→CJS 的输出转换，原因见下一节。

sourceType: "commonjs"的真实作用：只改解析规则，不产生 CJS 输出

sourceType是 Oxc 解析器层面的选项。文档明确指出：sourceType: "commonjs"改变的是解析器规则（parser rules），而不是 ESM 到 CJS 的输出转换。

这句话需要展开理解。在 notes/oxc-transform/configuration.md 中可以看到 Oxc 的模块分类机制：文件名后缀（如.ts、.tsx、.mts、.cts）决定默认语言分类，而lang选项可以单独恢复 TS/TSX 语言分类，sourceType则单独覆盖解析器的模块类型。换言之，Oxc 把"语言分类"（TypeScript / JavaScript）与"模块分类"（ESM / CommonJS / script）解耦为两个维度：

• lang：决定是否按 TypeScript/TSX 语法解析（类型注解、import =等）；
• sourceType：决定解析器允许哪些顶层语法——"commonjs"意味着按 CommonJS/script 规则解析，例如会拒绝某些仅 ESM 合法的语法。

因此sourceType: "commonjs"是一个输入侧的约束：它让解析器以 CommonJS 的规则去理解源码，但输出侧仍然由内部默认的Preserve模块选项决定，即保留源码原有的模块语法。两者一组合，结论就很清晰：用sourceType: "commonjs"解析一份含 ESM import/export 的代码，Oxc 不会把它降级成require()/module.exports，而是要么报解析诊断（如import.meta在 script/CommonJS 解析下的报错），要么原样保留 ESM 语法输出。

TypeScript module pass：仅降级import = require()与export =

既然 NAPI 不做完整 ESM→CJS 输出，那么 Oxc 的 TypeScript 转换管线里到底有没有处理模块语法的地方？文档给出的答案是：TypeScript module pass 只降低import = require()和export =这两种 TypeScript 专属的导入导出形式。

这是非常重要的边界。import x = require('pkg')和export = x是 TypeScript 语法中显式表达 CommonJS 语义的形式，把它们降级为require()调用 /module.exports赋值是 TypeScript 编译的基础职责。Oxc 的crates/oxc_transformer/src/typescript/module.rs实现了这一小段降级逻辑，并且文档特别注明：通用 CommonJS 插入（general CommonJS insertion）属于未来插件的工作范畴，当前版本并不包含。

由此可以归纳出 Oxc transform 对各类模块语法的处理矩阵：

其中最后一行值得单独说明：在 CommonJS/script 解析规则下，顶层await属于非法语法，Oxc 解析器能够报告这一诊断（这就是"CommonJS source classification can diagnose top-level await"的含义）；但诊断归诊断，转换器并不会因此把代码改写成 Promise 链或回调形式——降级能力根本不存在。也就是说，Oxc 能告诉你"这段代码在 CJS 下不合法"，却无法帮你把它变成合法的 CJS。

一个值得警惕的组合：CJS 解析下的import.meta与残留诊断

保留 ESM 语法 + 按 CommonJS 规则解析，这两件事叠加会引出一个实际工程陷阱，相关的细节记录在 notes/oxc-transform/diagnostics.md 中：

• Oxc 的transformSync()/transform()不会因转换失败直接抛异常，而是返回结构化诊断（structured diagnostics）与代码并存；
• 解析器在 script/CommonJS 解析下遇到import.meta会报告一个解析错误（severity 为Error）；
• 但如果后续某个转换步骤（例如 define 替换）把import.meta替换掉了，最终输出的代码里就可能同时存在"已被替换的产物"与"一条过期的 severity=Error 解析诊断"。

这意味着在 tsx 这类运行时代码转换场景中，不能简单地把"存在 Error 级别诊断"等同于"输出不可用"，而必须先厘清 source-type/预解析行为，再决定如何把剩余的 Error 诊断转换为致命失败。这也是 notes/tsx/transform-backend.md 中"Diagnostics"这条 gate 被标记为Blocked before adapter的原因之一。

与 esbuild 的对比：为什么 tsx 的 CJS 输出依赖 esbuild

将 Oxc 与 esbuild 并排看，能力差异立刻显现。tsx 当前的通用转换后端是 esbuild，其 CommonJS 输出路径有两点 Oxc 目前不具备的能力：

1. 完整的 ESM→CJS 降级：在 src/utils/transform/index.ts 的同步转换路径中，tsx 向esbuildTransformSync()传入format: 'cjs'，esbuild 会把 ESM 语法完整改写为require()/module.exports形式，并用 banner/footer 包裹以注入__filename/__dirname语义（banner中写入__filename=${JSON.stringify(filePath)}，并以 IIFE 形式包裹代码）。

2. 可被静态词法分析器识别的 CJS 导出注解：根据 notes/esbuild/commonjs-output.md，当 esbuild 面向 Node 生成已知导出的 CommonJS 输出时，会附带一段死代码module.exports注解，供 Node 的静态 CommonJS 导出词法分析器识别导出形状——这正是 tsx 的 ESM loader 实现 CJS 互操作（CJS interop）时依赖的机制。

而 Oxc 侧，正如前文所述，普通 ESM 语法会被原样保留，连import.meta在 CJS 解析下的残留诊断问题都尚未收敛，更谈不上产出带导出注解的 CJS 代码。两者的差距是结构性的，而非参数调优可以弥合。

tsx 视角：CommonJS 输出能力缺失如何阻塞 Oxc 成为通用后端

tsx 的研究文档 notes/tsx/transform-backend.md 明确把 Oxc transform 列为"被阻塞的通用后端候选"（Blocked general-backend candidate），其中"Module output" 正是阻塞 gate 之一：

Module output | Blocked | Public NAPI preserves ordinary ESM and exposes no complete ESM-to-CJS output（公共 NAPI 保留普通 ESM 且不暴露完整的 ESM→CJS 输出）。

这背后是 tsx 的硬性运行时契约：tsx 需要同时支持 CommonJS 与 ESM 两条执行路径（CJS loader 与 ESM loader），对每个文件要么产出可运行的 CJS、要么产出可运行的 ESM。而 Oxc 无法为普通 ESM 文件产出 CJS，就无法满足 CJS 路径的转换需求。tsx 的"Re-verification matrix"中对应地列出了 "Module output" 契约：需要覆盖Async ESM、sync ESM、sync CJS、import.meta、动态 import五类形态的测试，且任何后端替换都必须重新验证——这正是因为模块输出行为是整个运行时正确性的基石。

从更宏观的视角看，tsx 对后端的约束（见 notes/tsx/transform-backend.md 的 Invariants）还包括：必须按 per-file 外部模块模式求值（bundle-only 输出不能证明 loader 兼容性）、目标为运行中的 Node 版本、不得为自包含函数添加游离的 helper 依赖等。Oxc 在模块输出这一项上的缺口，使得它在其他维度（如 import elision 的级联类型擦除、结构化诊断）即使表现更好，也无法整体替换 esbuild。

实操验证：如何在本地观察 Oxc 与 esbuild 的输出差异

仓库本身不包含可直接运行的 Oxc 二进制，但你可以通过两份研究笔记与 tsx 源码交叉验证上述结论：

1. 观察 tsx 的 esbuild CJS 输出：阅读 src/utils/transform/index.ts，注意transformSync()中format: 'cjs'、platform: 'node'与 banner/footer 的组合，理解 tsx 的 CJS 转换契约；对应的 ESM 路径见同文件 src/utils/transform/index.ts。

2. 观察 esbuild 的导出注解行为：对照 notes/esbuild/commonjs-output.md 中关于死代码module.exports注解的说明，再用任意含 ESM 导出的小文件执行npx esbuild input.ts --format=cjs，即可在输出尾部看到用于导出识别的注解代码。

3. 对照 Oxc 的能力边界：依次阅读 notes/oxc-transform/README.md（文档索引）、notes/oxc-transform/configuration.md（lang/sourceType 解耦与默认值）、notes/oxc-transform/diagnostics.md（结构化诊断与残留 Error 问题），最后回到 notes/tsx/transform-backend.md（Oxc 候选 gates 表），即可把"模块输出被阻塞"这一结论与每个底层机制一一对上。

结论

Oxc transform 的 CommonJS 输出行为可以用三句话概括：

• NAPI 无 output-module 选项：内部模块选项恒为默认值Preserve，公共 API 只暴露源语言/模块分类，不暴露输出格式控制；
• sourceType: "commonjs"是解析器规则而非输出开关：它只约束输入侧语法合法性（如拒绝 ESM-only 语法、诊断顶层 await 与import.meta），不会把 ESM 改写为 CJS；
• TypeScript module pass 只降级import = require()与export =：普通 ESM 的 import/export、重导出、实时绑定与顶层 await 全部保留 ESM 形态，通用 CommonJS 插入留待未来插件。

正是这一能力边界，决定了 tsx 当前继续以 esbuild（具备format: 'cjs'完整降级与可识别的导出注解）作为通用转换后端，而将 Oxc 视为模块输出 gate 阻塞的候选后端。理解这一差异，有助于在评估任何"TypeScript 转译器/剥离器"作为运行时后端时，第一优先检查其 ESM→CJS 输出能力是否真实存在——而非被sourceType: "commonjs"之类的解析选项名称所误导。

【免费下载链接】tsx⚡️ TypeScript Execute | The easiest way to run TypeScript in Node.js项目地址: https://gitcode.com/gh_mirrors/ts/tsx