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 文档
