1. 项目概述从CommonJS到ESM的迁移之痛最近在重构一个老牌的Electron应用核心任务之一就是把整个项目的模块系统从陈旧的CommonJSCJS迁移到现代的ES模块ESM语法。这个决定背后有充分的理由ESM带来了原生的静态分析能力、更好的Tree Shaking支持以及更清晰的异步模块加载语义对于构建大型、可维护的现代前端应用至关重要。然而迁移过程远非一帆风顺尤其是在Electron这个特殊的混合环境中。当我把目光投向preload.js——这个连接渲染进程与主进程、确保安全性的关键桥梁时一个经典的报错拦住了去路Uncaught TypeError: require is not defined或者Cannot use import statement outside a module。这几乎是每一个从CJS转向ESM的Electron开发者都会遇到的“成人礼”。今天我就来详细拆解这个问题的来龙去脉分享一套完整的诊断、解决和优化方案让你不仅能解决眼前的报错更能透彻理解Electron中模块系统的运作机制。2. 核心问题解析为什么preload.js会成为迁移的绊脚石要解决问题必须先理解问题产生的根源。preload.js在Electron架构中扮演着一个独特的角色。它不是一个普通的Node.js脚本也不是一个纯粹的浏览器环境脚本而是一个在渲染进程中运行但拥有访问Node.js API部分特权的特殊脚本。它的主要使命是在渲染进程的全局作用域window对象上安全地暴露一些由主进程提供的API通过contextBridge同时隔离渲染进程防止其直接访问危险的Node.js模块如fs,child_process这是Electron安全模型的核心。2.1 CommonJS时代的“舒适区”在默认的Electron项目特别是使用electron-forge或早期electron-quick-start模板创建的项目中preload.js通常被配置为使用CommonJS。这体现在几个方面主进程配置在main.js主进程入口文件中创建浏览器窗口时webPreferences.preload路径指向的脚本默认被Electron的底层加载器以Node.js的CJS模块方式加载。脚本内容preload.js内部通常直接使用require()来引入Node.js模块或本地文件并使用module.exports或exports来导出对象给渲染进程。构建工具许多配套的构建工具链如Webpack默认也针对CJS进行配置。这种模式下一切都很“自然”因为Node.js的运行时环境天生支持CJS。2.2 向ESM迁移时的“环境错配”当我们决定将整个项目切换到ESM时问题开始浮现。ESM是ECMAScript标准而Node.js对它的支持是一个渐进的过程。在Electron中我们需要同时考虑主进程、渲染进程和preload脚本这三个部分对ESM的支持情况。主进程相对容易。我们可以在package.json中设置type: module或者将主进程入口文件后缀改为.mjs这样Node.js也就是Electron的主进程就会将其作为ESM来解析。主进程中的require需要被替换为import。渲染进程这是浏览器环境。现代Chromium内核原生支持ESM。我们可以在HTML中通过script typemodule srcrenderer.js/script来加载渲染进程的ESM脚本。这部分也相对清晰。preload.js这里正是冲突的焦点。preload.js的加载方式由主进程中的webPreferences配置和文件本身的内容共同决定。当我们把package.json设为type: module后Node.js会尝试将项目中的所有.js文件都当作ESM来解析。然而Electron在加载preload脚本时其内部机制可能仍期望一个CJS模块或者没有正确地将ESM的解析上下文传递给这个特殊的脚本执行环境。这就导致了经典的错误情景A如果preload.js里写了import语句但Electron将其加载到了一个未启用ESM的上下文中就会报错SyntaxError: Cannot use import statement outside a module。情景B如果preload.js里还保留着require()而整个项目已被视为ESM项目那么在Node.js的ESM模式下require函数默认是不可用的会报错ReferenceError: require is not defined。核心矛盾我们期望preload.js作为一个ESM模块运行但Electron默认的preload脚本加载机制可能并未为其准备好一个完整的、支持ESM的Node.js运行时环境。这本质上是项目级模块类型配置与Electron特定脚本加载器之间的不匹配。3. 解决方案全景多管齐下根治报错解决这个问题不能靠碰运气需要一个系统性的方法。下面我将从配置、脚本、构建三个层面由简到繁地给出解决方案。3.1 方案一修改文件扩展名与配置最直接这是最符合Node.js ESM规范的做法即通过文件扩展名来明确模块类型。步骤重命名preload脚本将你的preload.js文件重命名为preload.mjs。.mjs扩展名明确告诉Node.js这是一个ES模块无论package.json中的type字段如何设置。更新主进程配置在main.js或你的主进程入口文件中更新创建浏览器窗口时的preload路径。// main.js (或 main.mjs) import { app, BrowserWindow } from electron; import path from path; import { fileURLToPath } from url; const __dirname path.dirname(fileURLToPath(import.meta.url)); function createWindow() { const mainWindow new BrowserWindow({ webPreferences: { // 关键路径指向 .mjs 文件 preload: path.join(__dirname, preload.mjs), // 另一个关键配置见下文 nodeIntegration: false, contextIsolation: true, }, }); // ... 加载页面等操作 }注意在ESM中我们使用import.meta.url和fileURLToPath来模拟CommonJS中的__dirname。改造preload脚本内容在preload.mjs中使用ESM语法。// preload.mjs import { contextBridge, ipcRenderer } from electron; // 可以引入其他ESM格式的模块 import { someUtility } from ./utils.mjs; contextBridge.exposeInMainWorld(myAPI, { send: (channel, data) ipcRenderer.send(channel, data), on: (channel, func) ipcRenderer.on(channel, (event, ...args) func(...args)), // 暴露工具函数 doSomething: someUtility, });为什么有效.mjs扩展名是一个强信号。当Electron底层是Node.js去加载这个文件时Node.js的模块加载器会识别其扩展名并按照ESM的规则来解析和执行它从而正确识别import语句。这方法绕过了package.json中type字段的全局影响对preload这个特定文件进行了精准控制。注意事项确保项目中所有被preload.mjs引入的模块也都是ESM格式或兼容的否则会引发链式错误。如果你有多个preload脚本或类似的特权脚本都需要进行相同的改造。3.2 方案二调整Electron的WebPreferences配置有时仅仅改扩展名可能还不够因为渲染进程的上下文隔离contextIsolation和Node集成nodeIntegration设置会影响preload脚本的执行环境。关键配置解析contextIsolation(默认推荐为true)这是重要的安全特性。当为true时preload脚本运行在一个与渲染进程网页内容隔离的独立JavaScript上下文中。这意味着你在preload中定义的变量通过var x 不会自动泄漏到渲染进程的网页中必须通过contextBridge.exposeInMainWorld来安全传递。这个独立的上下文默认支持ESM。nodeIntegration(默认推荐为false)如果设置为true渲染进程的网页内容将拥有完整的Node.js API访问权限这是极不安全的通常应避免。当它为false时只有preload脚本能访问Node.js API。nodeIntegration的值会影响全局对象的可用性但对preload脚本自身是否是ESM影响不大。对于ESM的preload最佳安全实践配置是webPreferences: { preload: path.join(__dirname, preload.mjs), // 使用.mjs nodeIntegration: false, // 必须为false以确保安全 contextIsolation: true, // 必须为true以确保安全且此模式天然支持preload使用ESM // 在较新版本的Electron中可能还需要明确启用实验性特性但通常不需要 // sandbox: false, // 通常保持默认除非有特殊需求 }将preload脚本放在一个启用contextIsolation且禁用nodeIntegration的环境中是最安全且对ESM友好的方式。3.3 方案三使用构建工具进行转译与打包对于大型复杂项目或者你希望保持所有源文件为.js扩展名package.json中设置type: module那么使用构建工具如Webpack、Vite、esbuild来处理preload脚本是一个更强大和主流的选择。以Webpack为例安装依赖npm install --save-dev webpack webpack-cli babel-loader babel/core babel/preset-env创建Webpack配置文件(webpack.preload.config.js)// 注意此配置文件本身应是CommonJS除非你将其命名为 .cjs const path require(path); module.exports { target: electron-preload, // 关键指定目标环境为electron-preload mode: development, // 或 production entry: ./src/preload.js, // 你的ESM源码入口 output: { path: path.resolve(__dirname, dist), filename: preload.bundle.js, // 输出文件 }, module: { rules: [ { test: /\.js$/, exclude: /node_modules/, use: { loader: babel-loader, options: { presets: [ [babel/preset-env, { targets: { node: current }, // 针对当前Node版本转译 modules: commonjs, // 关键将ESM转译为CJS }] ] } } } ] }, // 如果你在preload中需要引入Node.js原生模块或Electron可能需要配置externals externals: { electron: commonjs electron, fs: commonjs fs, // ... 其他原生模块 }, };核心思路我们编写符合ESM语法的src/preload.js然后通过Webpack和Babel将其转译并打包成一个目标为electron-preload的、符合CommonJS规范的dist/preload.bundle.js。这样Electron主进程加载的最终产物是一个CJS文件完美兼容其默认加载机制而从开发者视角我们始终在编写ESM代码。更新主进程配置指向打包后的文件。preload: path.join(__dirname, dist/preload.bundle.js)更新package.json脚本scripts: { build:preload: webpack --config webpack.preload.config.js, start: npm run build:preload electron . }此方案的优势开发体验统一所有源码主进程、渲染进程、preload都可以使用ESM语法。兼容性无忧输出产物是兼容性最好的CommonJS避免环境差异问题。功能强大可以集成TypeScript、代码压缩、资源处理等。注意事项增加了构建环节的复杂性。需要正确配置externals防止将Electron或Node.js原生模块打包进bundle导致运行时错误或体积膨胀。调试源码需要配置source map。3.4 方案四动态条件导入适用于混合模块如果你的preload脚本非常简单或者你只是想临时解决一个过渡期的问题可以考虑使用Node.js的动态import()函数。这是一个在ESM和CJS中都可用的函数返回一个Promise。示例// preload.js (文件扩展名可以是.js或.mjs但package.json type不应为module) const { contextBridge } require(electron); // 动态导入一个ESM格式的工具模块 import(./utils.mjs).then((module) { const { someUtility } module; contextBridge.exposeInMainWorld(myAPI, { doSomething: someUtility, }); }).catch((err) { console.error(Failed to load ESM module:, err); }); // 原有的CJS部分保持不变 const fs require(fs); contextBridge.exposeInMainWorld(fs, { readFileSync: fs.readFileSync, });这种方法允许你在一个总体上被视为CJS的脚本中异步加载ESM模块。但它会让代码结构变得复杂且import()是异步的需要注意暴露API的时机。4. 实操步骤与迁移 checklist假设我们有一个典型的CJS Electron项目现在要全面迁移到ESM以下是一份详细的checklist第一阶段项目基础配置备份项目这是第一步也是最重要的一步。更新package.json{ name: my-electron-app, version: 1.0.0, type: module, // 新增此行声明项目为ESM main: ./src/main.js, // 确保入口文件正确 scripts: { ... }, dependencies: { ... }, devDependencies: { ... } }改造主进程入口(src/main.js)将所有require()语句改为import ... from ...。使用import.meta.url和path.dirname(fileURLToPath(import.meta.url))替代__dirname。注意引入JSON文件需要使用createRequire或直接使用fs.readFileSync然后JSON.parse因为ESM不支持直接importJSON。第二阶段处理preload脚本选择解决方案根据项目复杂度从方案一.mjs或方案三构建工具中选择一种。对于大多数项目方案一.mjs是最简单直接的。实施若选方案一将preload.js重命名为preload.mjs内容改为ESM语法并更新主进程中的路径。若选方案三配置Webpack或Vite等建立构建流程并更新主进程路径指向输出文件。验证启动应用检查开发者工具控制台确保没有模块相关的报错并且通过contextBridge暴露的API可以正常在渲染进程中使用。第三阶段处理渲染进程确保HTML中引入渲染进程脚本时使用了typemodulescript typemodule src./renderer.js/script。将渲染进程的所有脚本改为ESM语法。第四阶段处理依赖和工具检查第三方依赖有些古老的Node.js库可能不提供ESM导出。对于这些库你可能需要寻找替代的ESM原生库。使用动态import()。或者如果该库只在主进程使用可以将其保留在CJS中通过创建.cjs文件或使用createRequire。更新测试和工具脚本例如如果你的jest.config.js或某些构建脚本是.js文件在type: module下它们也会被当作ESM。可能需要将它们重命名为.cjs或在内部使用createRequire。5. 常见问题与深度排查即使按照上述步骤操作你可能还是会遇到一些棘手的问题。下面是一些常见坑点及其解决方案。问题1主进程更新后出现ERR_REQUIRE_ESM错误现象启动应用时主进程崩溃报错Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.。原因你已将某个文件改为ESM或依赖的某个库是ESM但主进程中仍有地方试图用require()去加载它。解决检查报错指向的文件。如果它是你自己的文件确保主进程中使用import而非require来引入它。如果它是某个第三方库例如node-fetchv3该库可能只提供ESM包。你有几个选择降级到该库的最后一个提供CJS的版本不推荐长期。使用动态import()来异步加载这个库const fetch (await import(node-fetch)).default;。如果这个库只在主进程使用可以考虑在ESM的主进程中用createRequire来加载它这是一种妥协。问题2preload.mjs中无法使用__dirname或__filename原因__dirname和__filename是CommonJS的全局变量在ESM中不可用。解决使用ESM的元属性import.meta.url来获取当前模块的文件URL然后通过url和path模块进行转换。import { fileURLToPath } from url; import { dirname, join } from path; const __filename fileURLToPath(import.meta.url); const __dirname dirname(__filename); const preloadPath join(__dirname, some-file.txt);问题3在preload中引入其他本地ESM模块时路径错误原因ESM的import语句中的路径是相对于当前文件的URL与CommonJS的require相对于当前文件目录行为略有不同且需要完整的文件扩展名如./utils.mjs。解决始终使用完整的相对路径import { x } from ./lib/utils.mjs;而不是from ./lib/utils。考虑使用绝对路径可以利用import.meta.url和fileURLToPath解析出绝对路径然后使用path.join来构造其他模块的绝对路径但这通常更复杂。推荐使用明确的相对路径加扩展名。问题4使用了构建工具后preload脚本中contextBridge暴露的API在渲染进程中是undefined现象打包后运行渲染进程中访问window.myAPI得到undefined。原因Webpack等工具可能会对代码进行重命名、作用域隔离导致contextBridge.exposeInMainWorld的调用被优化或包裹未能正确在全局对象上创建属性。排查与解决检查Webpack的target确保配置中设置了target: electron-preload。这个target会为Electron的preload环境提供正确的全局变量和优化预设。禁用代码混淆/压缩进行测试在开发模式下先将mode设为development并暂时关闭代码压缩插件如TerserWebpackPlugin看问题是否消失。这有助于判断是否是优化工具导致的问题。检查输出文件打开打包生成的preload.bundle.js搜索exposeInMainWorld看对应的代码是否被正确生成且位于最外层作用域。确保没有重复的暴露如果preload脚本被多次执行或存在多个实例可能会导致覆盖。问题5迁移后应用启动变慢或出现其他运行时错误可能原因动态导入阻塞如果大量使用了动态import()且未妥善处理异步可能导致启动时等待时间变长。模块循环依赖ESM对循环依赖的处理与CJS不同可能暴露出之前隐藏的问题。原生模块不兼容某些Node.js原生模块或native addons在ESM上下文中可能需要特殊处理。解决使用性能分析工具如Electron自带的DevTools Performance面板定位瓶颈。仔细检查控制台错误信息优先解决语法和模块加载错误。对于原生模块问题查阅其文档看是否提供了ESM包装或使用说明。迁移到ESM是一个系统工程尤其是像Electron这样融合了Node.js和浏览器环境的框架。preload.js的报错是一个明确的信号提醒我们关注模块系统在混合上下文中的边界行为。通过理解其原理并采用.mjs扩展名、调整配置或引入构建工具等策略可以彻底解决这个问题。整个过程不仅是一次技术升级更是对应用架构和模块化理解的一次深化。记住在Electron的世界里明确性使用.mjs和安全性contextIsolation: true是通往稳定ESM之路的两块基石。