26.3 原生模块编译与版本适配：electron-rebuild

Electron 底层使用的是定制版的 Node.js 和 Chromium，其原生模块接口（N-API / node-addon-api）的二进制格式与官方 Node.js 不完全兼容。因此，当你需要引入包含 C++ 代码的 npm 包（如 sqlite3、better-sqlite3、node-pty、canvas 等）时，直接安装的预编译二进制文件通常无法在 Electron 中正常使用。你需要针对当前 Electron 版本重新编译这些模块，这就是 electron-rebuild 解决的核心问题。

26.3.1 为什么需要重新编译

npm 上的原生模块通常会提供针对官方 Node.js 版本的预编译二进制文件，但 Electron 的 Node.js 版本是特定定制的（例如 Electron 28 内部使用 Node.js 18.x，但 ABI 可能略有差别）。如果直接使用针对 Node.js 编译的二进制，启动时会遇到类似这样的错误：

Uncaught Error: The module '...'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 108. This version of Node.js requires
NODE_MODULE_VERSION 114.

这时就需要用 electron-rebuild 重新编译，使其与当前 Electron 的 V8 引擎和 Node.js ABI 对齐。

26.3.2 一次性使用

最直接的用法是全局安装 electron-rebuild，然后在项目目录下执行一次命令：

npm install -g electron-rebuild
electron-rebuild

也可以不全局安装，直接使用 npx：

npx electron-rebuild

该命令会自动检测项目的 package.json 中依赖的原生模块，并针对当前 Electron 版本重新编译它们。编译完成后，这些模块就可以在 Electron 主进程或渲染进程（若启用了 Node.js 支持）中正常加载了。

26.3.3 集成到项目构建流程

更推荐的做法是将 electron-rebuild 作为开发依赖，并在 package.json 中配置脚本，以便每次安装依赖后自动执行：

npm install --save-dev electron-rebuild

然后在 package.json 中添加：

{
  "scripts": {
    "postinstall": "electron-rebuild"
  }
}

这样，每次执行 npm install 后，都会自动触发原生模块的重编译，确保团队成员和 CI 环境都能得到正确编译的模块。对于同时开发 Electron 和 Web 端的项目，可以利用环境变量进行条件控制：

{
  "scripts": {
    "postinstall": "if [ $ELECTRON_BUILD ]; then electron-rebuild; fi"
  }
}

26.3.4 指定 Electron 版本

如果你的项目依赖了多个 Electron 版本（比如同时维护多个大版本分支），或者 electron 没有直接安装在当前项目中（例如使用 electron-forge 等工具套件），可以通过 --version 参数明确指定目标版本：

npx electron-rebuild --version 28.0.0

也可以在项目根目录创建 .electron-rebuild.json 配置文件：

{
  "electronVersion": "28.0.0"
}

26.3.5 仅重建特定模块

当一个项目依赖的原生模块较多时，全量重建会耗时较长。你可以通过 --only 参数指定需要重建的模块名称（支持多个，空格分隔）：

npx electron-rebuild --only sqlite3,better-sqlite3

26.3.6 与 node-gyp 的关系与常见问题

electron-rebuild 底层调用的是 node-gyp，因此你的系统必须满足 node-gyp 的编译环境要求：

• Windows：需要安装 Visual Studio Build Tools（或完整的 Visual Studio）以及 Python；
• macOS：需要 Xcode Command Line Tools（xcode-select --install）；
• Linux：一般需要 make、gcc、python 等基础工具链。

常见问题及解决办法：

1. 编译时报“找不到 Python”

确保 Python 2.7 或 3.x 已安装并加入 PATH，推荐设置 npm config set python python3。

1. Windows 下缺少 Windows SDK

重新运行 Visual Studio Build Tools 安装程序，注意勾选“Windows 10 SDK”组件。

1. 某些模块无法并行编译

可以尝试增加 --serial 参数强制串行编译，避免竞态条件：

   npx electron-rebuild --serial
   

1. 编译时间过长或被防火墙拦截

electron-rebuild 可能需要下载 Electron 头文件，可通过设置环境变量使用镜像（例如中国大陆常用 ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"）。

26.3.7 替代方案：重建单独模块

如果不想全项目重建，也可以直接进入目标模块目录手动执行 node-gyp rebuild，但需要手动指定 Electron 头文件路径和 ABI 版本。相比之下，electron-rebuild 自动完成了这一繁琐过程，极大降低了出错概率。

26.3.8 实际案例：让 sqlite3 工作在 Electron 中

假设你的项目依赖 better-sqlite3（一个常用的 SQLite 原生绑定）。在 Electron 中正确使用它的步骤：

1. 安装依赖：

   npm install better-sqlite3
   npm install --save-dev electron-rebuild
   

1. 添加 postinstall 脚本：

   "scripts": {
     "postinstall": "electron-rebuild"
   }
   

1. 执行一次安装/重编译：

   npm install
   

完成后，主进程中即可正常使用：

// main.js
const Database = require('better-sqlite3');
const db = new Database('app.db');
db.prepare('CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, content TEXT)').run();

如果没有经过 electron-rebuild 处理，require 时就会抛出开篇提到的 NODE_MODULE_VERSION 错误。

electron-rebuild 是 Electron 开发中处理原生模块依赖的必备工具。它的使用非常简单，通常只需一条命令集成到安装流程中，就能确保所有 C++ 模块与 Electron 环境兼容。养成配置 postinstall 脚本的习惯，可以避免大量因模块版本不匹配而引起的诡异崩溃，让你的 Electron 工程更稳健。