Electron Forge 中 ESM 模式下 TypeScript 配置文件加载问题解析

问题背景

Electron Forge 是一个流行的 Electron 应用程序打包和分发工具。随着 JavaScript 生态系统中 ESM (ECMAScript Modules) 的普及，许多开发者希望在 Electron 项目中使用 ESM 模块系统。然而，当开发者尝试在 ESM 模式下使用 TypeScript 编写的 forge.config.ts 配置文件时，会遇到一系列加载问题。

问题现象

当项目 package.json 中设置了 "type": "module" 时，Electron Forge 无法正确加载 forge.config.ts 文件，主要出现以下两类错误：

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

根本原因分析

经过深入分析，这个问题主要由以下几个因素共同导致：

1. rechoir 依赖限制：Electron Forge 内部使用的 rechoir 依赖目前不完全支持 ESM 模块系统
2. TypeScript 加载机制：在 ESM 模式下，传统的 require() 方式无法正确加载 TypeScript 文件
3. 模块解析冲突：当项目设置为 ESM 模式时，所有 .ts 文件默认被视为 ES 模块，与 CommonJS 加载机制产生冲突

解决方案比较

开发者社区提出了多种解决方案，各有优缺点：

1. 使用 esbuild-register 替代 ts-node

yarn remove ts-node
yarn add --dev esbuild esbuild-register

优点：

• 完全支持 ESM 模式
• 编译速度快
• 与现有工具链兼容性好

缺点：

• 需要额外安装 esbuild 作为 peer dependency
• 某些特定 TypeScript 功能支持可能不如 ts-node 完整

2. 直接调用 Forge CLI 脚本

修改 package.json 中的 scripts 部分：

"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"
}

优点：

• 完全绕过模块加载问题
• 适用于大多数平台

缺点：

• 在 Linux 平台上可能出现 Vite 相关模块加载问题
• 直接调用内部脚本可能导致未来版本兼容性问题

3. 使用 CommonJS 模式

将配置文件重命名为 forge.config.cts 并在 tsconfig.json 中设置：

{
  "compilerOptions": {
    "module": "commonjs"
  }
}

优点：

• 简单直接
• 无需额外依赖

缺点：

• 与项目整体 ESM 架构不一致
• 可能导致类型系统混乱

最佳实践建议

根据实际项目需求和环境，推荐以下方案：

1. 新项目：使用 esbuild-register 方案，这是目前最稳定和面向未来的解决方案
2. 现有大型项目：如果已经深度使用 ts-node，可以考虑直接调用 CLI 脚本的方案
3. 简单项目：如果对 ESM 需求不强烈，可以使用 CommonJS 模式作为临时解决方案

未来展望

随着 Node.js 生态对 ESM 支持的不断完善，特别是 Node.js 22.13 及以上版本对 ESM 的改进，这个问题有望在 Electron Forge 的未来版本中得到根本解决。开发者可以关注 Electron Forge 的更新日志，及时获取官方对 ESM 的完整支持。

总结

Electron Forge 在 ESM 模式下加载 TypeScript 配置文件的问题反映了 JavaScript 生态系统从 CommonJS 向 ESM 过渡期的典型挑战。通过理解问题的根本原因和各种解决方案的优缺点，开发者可以根据项目实际情况选择最合适的解决路径，确保开发流程的顺畅。