解决electron-builder中preload.ts打包问题的技术指南

问题背景

在electron-builder项目中，开发者经常遇到preload脚本在开发环境运行正常但在生产环境无法加载的问题。这个问题特别常见于TypeScript编写的preload脚本，当结合Angular或Next.js等前端框架使用时尤为突出。

典型错误表现

1. 开发环境运行正常，但生产构建后应用卡在加载页面
2. 控制台报错"Cannot find module 'preload.js'"
3. 当尝试加载预编译的preload.js时出现ESM模块错误

根本原因分析

问题的核心在于electron-builder打包机制与模块系统的兼容性：

1. 路径问题：生产环境下应用资源被打包到app.asar文件中，路径引用方式与开发环境不同
2. 模块系统冲突：TypeScript编译后的CommonJS模块与Electron的ESM要求不兼容
3. 构建配置缺失：未正确配置electron-builder处理preload脚本

解决方案

方案一：使用.mjs扩展名

1. 将preload.ts重命名为preload.mjs
2. 在electron-builder配置中添加extraResources确保文件被包含：

extraResources:
  - from: './src-electron'
    to: src-electron
    filter:
      - '**/*'

3. 在主进程中正确引用路径：

preload: path.join(appPath,'../src-electron/preload.mjs')

方案二：保持TypeScript但调整配置

1. 确保tsconfig.json配置正确：

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ESNext",
    "moduleResolution": "node"
  }
}

2. 在electron-builder配置中显式包含preload文件：

files: [
  "build/**/*",
  "!**/*.ts"
]

3. 使用条件路径引用：

preload: app.isPackaged 
  ? path.join(appPath, "build/preload.js") 
  : path.join(__dirname, 'preload.ts')

调试技巧

1. 检查app.asar内容：使用npx asar e app.asar extracted解包查看文件结构
2. 启用开发者工具：运行生产版本时添加--inspect参数调试主进程
3. 日志输出：在preload脚本开始处添加console.log确认是否执行

最佳实践建议

1. 统一模块系统：整个项目统一使用ESM或CommonJS，避免混用
2. 路径处理：使用app.getAppPath()动态获取应用路径
3. 构建验证：在CI流程中添加解包验证步骤，确保关键文件被正确包含
4. 版本兼容：注意Electron版本对ESM的支持程度，32.x版本已全面支持ESM

总结

electron-builder项目中preload脚本的问题主要源于路径和模块系统的差异。通过合理配置构建过程和统一模块规范，可以确保preload脚本在开发和生产环境都能正常工作。对于TypeScript项目，建议要么使用.mjs扩展名明确模块类型，要么仔细配置TypeScript编译选项和electron-builder包含规则。