跳转到主内容

Node 原生模块

原生Node.js模块由Electron支持，但由于Electron具有与给定Node.js不同的 应用二进制接口 (ABI)(由于使用Chromium的 BoringSL 而不是 OpenSSL 等 差异)，您使用的原生 模块需要为Electron重新编译。 否则，当您尝试运行您的应用程序时， 将会遇到以下的错误：

Error: The module '/path/to/native/module.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION $XYZ. This version of Node.js requires
NODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing
the module (for instance, using `npm rebuild` or `npm install`).

如何安装原生模块​

有多种不同的方法来安装原生模块：

为 Electron 安装并重新编译模块​

您可以像其他 Node 项目一样安装模块，然后用 @electron/rebuild 包重建这些模块以适配 Electron 。 这个包可以自动识别当前 Electron 版本，为你的应用自动完成下载 headers、重新编译原生模块等步骤。 如果您正在使用 Electron Forge，这个工具将在开发模式和发布时自动使用。

例如，你可以通过下面的命令来安装独立的 @electron/rebuild 工具并重新编译模块:

npm install --save-dev @electron/rebuild

# 每次你运行完“npm install”后，运行这条命令：
./node_modules/.bin/electron-rebuild

# 如果运行上述命令在 Windows 上遇到了问题，试试这条命令：
.\node_modules\.bin\electron-rebuild.cmd

关于诸如 Electron Packager 等其他工具的使用和集成的更多信息，请参阅该项目的 README。

通过 npm 安装​

只要设置一些系统环境变量，你就可以通过 npm 直接安装原生模块。

例如，要安装所有Electron的依赖：

# Electron 的版本。
export npm_config_target=1.2.3
# 你的机器架构
export npm_config_arch=x64
export npm_config_target_arch=x64
# 下载 Electron 的头文件。
export npm_config_disturl=https://electronjs.org/headers
# 告诉 node-pre-gyp 我们是在为 Electron 生成模块。
export npm_config_runtime=electron
# 告诉 node-pre-gyp 从源代码构建模块。
export npm_config_build_from_source=true
# 安装所有依赖，并缓存到 ~/.electron-gyp。
HOME=~/.electron-gyp npm install

为 Electron 手动编译​

如果你是一个原生模块的开发人员，想在 Electron 中进行测试， 你可能要手动编译 Electron 模块。 你可以 使用 node-gyp 直接编译：

cd /path-to-module/
HOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electronjs.org/headers
  • HOME=~/.electron-gyp 设置去哪找头文件
  • --target=1.2.3 设置了 Electron 的版本。
  • --dist-url=...设置了 Electron 的 headers 的下载地址。
  • --arch=x64 设置了该模块为适配64位操作系统而编译。

为Electron的自定义编译手动编译​

如果是为一个与公共发行版不匹配的Electron自定义版本编译原生Node模块，需要让npm使用你的Electron自定义版本所对应的Node版本。

npm rebuild --nodedir=/path/to/src/out/Default/gen/node_headers

故障排查​

如果您安装了本机模块并发现它无法正常工作，则需要检查以下内容：

  • 当有疑问时，请先执行 @electron/rebuild。
  • 确保原生模块与Electron应用程序的目标平台和体系结构兼容。
  • 确保在该模块的binding.gyp中win_delay_load_hook没有被设置为false。
  • 如果升级了 Electron，你通常需要重新编译这些模块。

关于win_delay_load_hook的说明​

在Windows上，默认情况下，node-gyp将原生模块与node.dll链接。 然而，在Electron 4.x和更高的版本中，原生模块需要的symbols由electron.exe导出，并且没有node.dll。 为了能在 Windows 上加载原生模块，node-gyp 安装了一个加载原生模块时会触发的延迟加载钩子，会将 node.dll 引用重定向到加载的可执行文件，而不是在库搜索路径内寻找 node.dll（这将什么都找不到）。 因此，在 Electron 4.x 及更高版本，你需要设置 'win_delay_load_hook': 'true' 来加载原生模块。

如果你遇到诸如 Module did not self-register 或者