Electron Forge 项目中 ESM 与 TypeScript 配置文件的兼容性问题解析

问题背景

在 Electron Forge 项目中，当开发者尝试使用 TypeScript 编写的 ESM 模块作为配置文件（forge.config.ts）时，会遇到一系列兼容性问题。这个现象在 Electron Forge 7.4.0 及以上版本中尤为明显，特别是在 Windows、macOS 和 Linux 不同平台上的表现存在差异。

核心问题表现

主要问题表现为当 package.json 中设置了 "type": "module" 时，系统会抛出以下两类错误：

1. ESM 模块加载错误：系统提示必须使用 import 语句加载 ES 模块，而当前使用的是 require() 方式
2. 文件扩展名识别问题：系统无法识别 .ts 文件扩展名

这些问题源于 Electron Forge 内部依赖的 rechoir 模块对 ESM 的支持不足，特别是在处理 TypeScript 配置文件时的局限性。

解决方案汇总

经过社区探索，目前有以下几种可行的解决方案：

方案一：使用 esbuild-register 替代 ts-node

1. 移除项目中现有的 ts-node 依赖
2. 安装 esbuild 和 esbuild-register
3. 确保 forge.config.ts 文件使用正确的模块语法

这个方案利用了 esbuild 更现代的模块解析机制，能够更好地处理 ESM 格式的 TypeScript 文件。

方案二：直接调用 Forge CLI 源码

修改 package.json 中的脚本，直接通过 tsx 调用 Forge CLI 的源码：

"scripts": {
  "start": "tsx node_modules/@electron-forge/cli/src/electron-forge-start",
  "package": "tsx node_modules/@electron-forge/cli/src/electron-forge-package",
  "make": "tsx node_modules/@electron-forge/cli/src/electron-forge-make",
  "publish": "tsx node_modules/@electron-forge/cli/src/electron-forge-publish"
}

这种方法绕过了传统的配置文件加载机制，但需要注意在不同操作系统上的兼容性差异。

方案三：使用 CommonJS 格式

1. 将配置文件重命名为 forge.config.cts
2. 在 tsconfig.json 中设置 "module": "CommonJS"
3. 确保其他配置与 CommonJS 规范兼容

虽然这不是最理想的解决方案，但在某些情况下可能是最稳定的选择。

技术原理分析

这些问题的根本原因在于 Node.js 生态系统中 ESM 和 CommonJS 模块系统的过渡期兼容性问题。Electron Forge 内部使用的 rechoir 模块在设计时主要考虑 CommonJS 场景，对 ESM 的支持有限。当项目设置为 ESM 模式时，.ts 文件会被自动视为 ESM 模块，而 rechoir 仍尝试用 require() 加载它们，导致冲突。

最佳实践建议

1. 评估项目需求：如果项目不强制要求 ESM，可以考虑暂时使用 CommonJS
2. 保持依赖更新：Electron Forge 新版本可能会改善这一问题
3. 跨平台测试：特别是在 Linux 环境下需要额外验证方案的有效性
4. 监控官方进展：关注 Electron Forge 官方对 ESM 支持的改进

未来展望

随着 Node.js 22.13+ 版本的普及，这一问题有望得到根本解决。新版 Node.js 对 ESM 的支持更加完善，配合 Electron Forge 的后续更新，将提供更流畅的 TypeScript 和 ESM 集成体验。开发者应保持对 Electron 和 Node.js 版本更新的关注，及时调整项目配置。