Electron 插件重编译方案整理

Electron 项目里，某些基于 C++ 的 Node Addon（原生模块、.node文件）会依赖特定的 Node.js 版本 和 Electron 版本，此时就需要对插件进行重编译以兼容适配

环境配置

• Python 环境（node-gyp 依赖）：重建原生模块通常会走node-gyp，需要 Python，推荐使用pyenv-win管理 Python 版本，或者直接安装 Python（建议 3.x），并确保python/py命令可用。

• Visual Studio C++ Build Tools：Windows 下编译 C++ Addon 需要 VS 的 C++ 生成工具（Build Tools / Desktop development with C++），建议安装 Visual Studio 社区版或 Build Tools，尽量不要改变默认安装目录，减少后续环境识别问题

Build Tools 下载地址：适用于 Windows、Mac 和 Linux 的 Visual Studio 和 VS Code 下载 下拉到最下方下载

推荐方案：使用 @electron/rebuild

@electron/rebuild（命令行通常叫electron-rebuild）对插件进行重编译

1. 安装依赖

pnpminstall@electron/rebuild --save-dev

也可以用 npm/yarn 安装，核心是把它作为 devDependency 放进项目。

2. 执行重编译

重编译全部原生模块

pnpx electron-rebuild

指定架构（例如 Windows 32 位）

pnpx electron-rebuild --arch=ia32

--arch要与你的 Electron 打包目标一致。比如你要打包 32 位，就必须用ia32。

常用操作（按需）

# 强制重建pnpx electron-rebuild -f# 只重建某个模块（减少耗时）pnpx electron-rebuild -f -w<native-module-name>

架构参数说明

arch 参数	CPU 架构	常见平台	说明
ia32	32 位 x86	Windows、Linux	适用于 32 位目标（老系统或特定分发）
x64	64 位 x86	Windows、macOS（Intel）、Linux	默认/主流架构
armv7l	32 位 ARM	Linux	适用于部分 32 位 ARM 设备
arm64	64 位 ARM	macOS（Apple Silicon）、Linux、Windows	Apple M 系列、ARM Linux、ARM Windows

手动方案：npm rebuild

通过npm rebuild走 npm 自带的编译流程完成 C++ addon 模块的重新编译。

手动编译需要识别 electron 和 node 的 node-api 版本：

• Electron 版本：process.versions.electron
• Node 版本：process.versions.node
• Node ABI（NODE_MODULE_VERSION）：process.versions.modules，也可以通过 node-abi 插件查看 node_abi 版本

你可以在 Electron 主进程里打印：

console.log({electron:process.versions.electron,node:process.versions.node,modules:process.versions.modules,napi:process.versions.napi,});

得到对应的信息后就可以开始执行重建操作

npmrebuild --runtime=electron --disturl=https://atom.io/download/atom-shell --target=<electron版本>--abi=<对应版本abi>

--disturl告诉node-gyp去哪里下载 Electron 的 headers

总结

• 优先使用@electron/rebuild，省心且更贴近 Electron 场景
• 手动方案npm rebuild/node-gyp可以作为备用重建方案
• 注意保持 Python 环境、VS C++ Build Tool 和 目标架构一致

参考内容

• @electron/rebuild（GitHub）
• npm rebuild 文档