Electron-Vite 项目中 ESM 模式下的资源路径处理问题解析

问题背景

在使用 Electron-Vite 构建 Electron 应用程序时，开发者在 ESM (ECMAScript Modules) 模式下遇到了一个关于资源路径处理的常见问题。当导入静态资源（如图片、图标等）时，构建工具生成的代码中使用了 __dirname 变量，而这个变量在纯 ESM 环境中是不可用的。

问题现象

开发者通过以下方式导入资源：

import trayIconPath from '../../../assets/logoTemplate.png?asset';

构建后生成的代码为：

const trayIconPath = join(__dirname, "./chunks/logoTemplate-IqcVkt31.png");

在运行时抛出错误：

ReferenceError: __dirname is not defined in ES module scope

技术分析

ESM 与 CommonJS 的区别

在 Node.js 环境中，传统的 CommonJS 模块系统提供了 __dirname 和 __filename 等全局变量来获取当前模块的路径信息。然而，在 ESM 模式下，这些变量不再可用，开发者需要使用 import.meta.url 结合 fileURLToPath 来获取类似的信息。

Electron-Vite 的资源处理机制

Electron-Vite 在处理静态资源时，默认会生成使用 __dirname 的路径拼接代码。这在 CommonJS 模式下工作正常，但在 ESM 模式下会导致运行时错误。

解决方案

1. 正确配置 ESM 模式

确保项目配置正确，特别是 main.publicDir 的设置。完整的配置示例如下：

export default defineConfig({
  main: {
    build: {
      rollupOptions: {
        input: {
          main: resolve(__dirname, "src/main.ts"),
        },
        output: {
          format: "es"
        }
      },
      outDir: 'dist/main',
    },
    publicDir: 'assets', // 注意这里是 main.publicDir
  }
});

2. 文件扩展名处理

在 ESM 模式下，Electron-Vite 2.x 版本会为文件生成 .mjs 扩展名。如果发现生成的是 .js 文件，可能是配置或版本问题。

3. 预加载脚本的特殊处理

对于预加载脚本（preload），由于 Electron 的限制，通常需要使用 CommonJS 格式。可以通过以下配置强制使用 CommonJS：

preload: {
  build: {
    lib: {
      entry: 'src/preload/index.ts',
      formats: ['cjs'],
      fileName: 'index'
    },
    rollupOptions: {
      output: {
        entryFileNames: '[name].js'
      }
    }
  }
}

最佳实践建议

1. 版本一致性：确保使用 Electron-Vite 2.x 版本，以获得最佳的 ESM 支持。

2. 明确模块类型：在 package.json 中明确指定 "type": "module" 来启用 ESM。

3. 路径处理替代方案：在 ESM 模式下，可以使用以下方式替代 __dirname：

   import { fileURLToPath } from 'node:url';
   import { dirname, join } from 'node:path';
   
   const __filename = fileURLToPath(import.meta.url);
   const __dirname = dirname(__filename);
   

4. 构建目标明确：为不同进程明确指定构建格式：

   • 主进程：ESM
   • 渲染进程：ESM
   • 预加载脚本：CommonJS

总结

Electron-Vite 项目在 ESM 模式下的资源路径处理需要特别注意构建配置和运行时环境的兼容性。通过正确配置构建选项、理解模块系统的差异以及采用适当的路径处理方法，可以有效地解决这类问题。对于混合使用 ESM 和 CommonJS 的 Electron 应用，合理的构建策略和明确的模块边界划分是确保项目稳定运行的关键。