TypeScript-ESLint 项目中 Node.js 23.6 环境下 tsx 的 ESM 执行问题分析

在 TypeScript-ESLint 项目的开发过程中，我们发现了一个与 Node.js 23.6 版本和 tsx 工具相关的重要兼容性问题。这个问题影响了项目构建流程的正常运行，特别是在处理 CommonJS 模块时出现了意外的 ESM 上下文执行情况。

问题现象

当开发者在 Node.js 23.6 环境下运行项目构建命令时，types/tools/copy-ast-spect.ts 脚本会执行失败。具体表现为脚本尝试访问 __dirname 变量时抛出错误，因为该变量在 ESM 模块系统中不可用。

问题的根源在于 tsx 工具在当前环境下错误地将脚本置于 ESM 执行上下文中，即使项目明确配置了 "type": "commonjs"。这种行为与预期不符，导致了 CommonJS 特有的变量访问失败。

技术背景分析

Node.js 的模块系统经历了从 CommonJS 到 ESM 的演进过程。在 Node.js 中，可以通过 package.json 的 "type" 字段指定默认模块系统：

• "commonjs": 使用传统的 require/module.exports 语法
• "module": 使用 ECMAScript 模块语法

tsx 是一个 TypeScript 运行时，它允许直接执行 TypeScript 文件而无需预先编译。在理想情况下，它应该尊重项目的模块系统配置。

解决方案探讨

项目维护团队讨论了多种可能的解决方案：

1. 完全迁移到 ESM：将所有工具脚本转换为 ESM 格式（使用 .mts 扩展名），并相应调整代码。这种方案最为直接，但需要对现有代码进行一定修改。

2. 等待 Node.js 内置类型剥离功能稳定：Node.js 23+ 版本引入了实验性的类型剥离功能，理论上可以直接执行 TypeScript 文件。但考虑到项目需要支持 Node.js 18+，且该功能在早期版本中不可用，此方案暂时不可行。

3. 继续使用 tsx 但修复上下文问题：这需要 tsx 工具本身的修复，可能不是短期内可实现的方案。

经过讨论，团队倾向于第一种方案——将相关工具脚本转换为 ESM 格式。这种方案不仅解决了当前问题，也使项目向现代模块系统靠拢，符合长期发展趋势。

实施建议

对于遇到类似问题的开发者，建议采取以下步骤：

1. 检查项目中所有工具脚本的模块系统使用情况
2. 将明确需要 ESM 特性的脚本转换为 .mts 扩展名
3. 更新相关代码，替换 CommonJS 特有的变量（如 __dirname）为 ESM 等效实现
4. 确保构建和测试流程在所有支持的 Node.js 版本上通过

总结

模块系统的过渡期总会带来一些兼容性挑战。TypeScript-ESLint 项目遇到的这个问题很好地展示了在混合模块系统环境下开发可能遇到的陷阱。通过将工具脚本明确转换为 ESM 格式，不仅解决了当前问题，也为项目未来的发展奠定了更好的基础。

对于大型 TypeScript 项目，建议尽早规划模块系统策略，并在工具链选择上充分考虑与目标 Node.js 版本的兼容性。同时，保持对 Node.js 新特性的关注，适时采用稳定的新功能来简化开发流程。