Skip to main content

Native Node Modules原生Node模块

Native Node.js modules are supported by Electron, but since Electron has a different application binary interface (ABI) from a given Node.js binary (due to differences such as using Chromium's BoringSSL instead of OpenSSL), the native modules you use will need to be recompiled for Electron. Electron支持原生Node.js模块，但由于Electron具有与给定Node.js二进制文件不同的应用程序二进制接口（ABI）（由于使用Chromium的BoringSSL而不是OpenSSL等差异），因此需要为Electron重新编译您使用的原生模块。Otherwise, you will get the following class of error when you try to run your app:否则，当您尝试运行应用程序时，将出现以下错误：

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`).

How to install native modules如何安装原生模块​

There are several different ways to install native modules:安装原生模块有几种不同的方法：

Installing modules and rebuilding for ElectronElectron模块安装与改造​

You can install modules like other Node projects, and then rebuild the modules for Electron with the electron-rebuild package. 您可以像其他节点项目一样安装模块，然后使用electron-rebuild包为Electron重新构建模块。This module can automatically determine the version of Electron and handle the manual steps of downloading headers and rebuilding native modules for your app. 该模块可以自动确定Electron的版本，并处理下载头文件和为应用程序重建原生模块的手动步骤。If you are using Electron Forge, this tool is used automatically in both development mode and when making distributables.如果您使用的是Electron Forge，该工具将在开发模式和制作可分发文件时自动使用。

For example, to install the standalone electron-rebuild tool and then rebuild modules with it via the command line:例如，要安装独立electron-rebuild工具，然后通过命令行使用它重建模块：

npm install --save-dev electron-rebuild

# Every time you run "npm install", run this:
./node_modules/.bin/electron-rebuild

# If you have trouble on Windows, try:
.\node_modules\.bin\electron-rebuild.cmd

For more information on usage and integration with other tools such as Electron Packager, consult the project's README.有关使用和与其他工具（如Electron Packager）集成的更多信息，请参阅项目自述。

Using 使用npm​

By setting a few environment variables, you can use npm to install modules directly.通过设置一些环境变量，您可以使用npm直接安装模块。

For example, to install all dependencies for Electron:例如，要安装Electron的所有依赖项：

# Electron's version.
export npm_config_target=1.2.3
# The architecture of Electron, see https://electronjs.org/docs/tutorial/support#supported-platforms
# for supported architectures.
export npm_config_arch=x64
export npm_config_target_arch=x64
# Download headers for Electron.
export npm_config_disturl=https://electronjs.org/headers
# Tell node-pre-gyp that we are building for Electron.
export npm_config_runtime=electron
# Tell node-pre-gyp to build module from source code.
export npm_config_build_from_source=true
# Install all dependencies, and store cache to ~/.electron-gyp.
HOME=~/.electron-gyp npm install

Manually building for ElectronElectron的手动构建​

If you are a developer developing a native module and want to test it against Electron, you might want to rebuild the module for Electron manually. 如果您是开发原生模块的开发人员，并希望针对Electron进行测试，则可能需要手动为Electron重新构建模块。You can use node-gyp directly to build for Electron:您可以直接使用node-gyp构建Electron：

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 changes where to find development headers.更改查找开发标题的位置。
  • --target=1.2.3 is the version of Electron.是Electron的版本。
  • --dist-url=... specifies where to download the headers.指定下载标头的位置。
  • --arch=x64 says the module is built for a 64-bit system.表示该模块是为64位系统构建的。

Manually building for a custom build of Electron手动构建Electron的自定义构建​

To compile native Node modules against a custom build of Electron that doesn't match a public release, instruct npm to use the version of Node you have bundled with your custom build.要针对与公共版本不匹配的自定义版本的Electron编译原生节点模块，请指示npm使用与自定义版本捆绑的节点版本。

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

Troubleshooting故障排除​

If you installed a native module and found it was not working, you need to check the following things:如果您安装了原生模块，但发现它不工作，则需要检查以下事项：

  • When in doubt, run electron-rebuild first.如有疑问，请先运行electron-rebuild。
  • Make sure the native module is compatible with the target platform and architecture for your Electron app.确保原生模块与Electron应用程序的目标平台和架构兼容。
  • Make sure win_delay_load_hook is not set to false in the module's binding.gyp.确保模块的binding.gyp中的win_delay_load_hook未设置为false。
  • After you upgrade Electron, you usually need to rebuild the modules.升级Electron后，通常需要重新构建模块。

A note about win_delay_load_hook关于win_delay_load_hook的一点注记​

On Windows, by default, node-gyp links native modules against node.dll. 在Windows上，默认情况下，node-gyp将本机模块链接到node.dll。However, in Electron 4.x and higher, the symbols needed by native modules are exported by electron.exe, and there is no node.dll. 然而，在Electron 4x及更高版本中，本机模块所需的符号由electron.exe导出，并且没有node.dll。In order to load native modules on Windows, node-gyp installs a delay-load hook that triggers when the native module is loaded, and redirects the node.dll reference to use the loading executable instead of looking for node.dll in the library search path (which would turn up nothing). 为了在Windows上加载本机模块，node-gyp安装了一个延迟加载挂钩，该挂钩在加载本机模件时触发，并重定向node.dll引用以使用加载可执行文件，而不是在库搜索路径中查找node.dll（这将什么也找不到）。As such, on Electron 4.x and higher, 'win_delay_load_hook': 'true' is required to load native modules.因此，在Electron 4x及更高版本上，需要'win_delay_load_hook': 'true'来加载本机模块。

If you get an error like Module did not self-register, or The specified procedure could not be found, it may mean that the module you're trying to use did not correctly include the delay-load hook. 如果出现错误，如“模块未自注册”，或“找不到指定的过程”，则可能意味着您尝试使用的模块未正确包含延迟加载挂钩。If the module is built with node-gyp, ensure that the win_delay_load_hook variable is set to true in the binding.gyp file, and isn't getting overridden anywhere. 如果模块是使用node-gyp构建的，请确保binding.gyp文件中的win_delay_load_hook变量设置为true，并且不会在任何地方被覆盖。If the module is built with another system, you'll need to ensure that you build with a delay-load hook installed in the main .node file. 如果模块是使用另一个系统构建的，则需要确保使用安装在主.node文件中的延迟加载挂钩进行构建。Your link.exe invocation should look like this:您的link.exe调用应该如下所示：

 link.exe /OUT:"foo.node" "...\node.lib" delayimp.lib /DELAYLOAD:node.exe /DLL
     "my_addon.obj" "win_delay_load_hook.obj"

In particular, it's important that:特别重要的是：

  • you link against node.lib from Electron and not Node. 您从Electron而不是节点链接到node.lib。If you link against the wrong node.lib you will get load-time errors when you require the module in Electron.如果您链接到错误的node.lib，当您需要使用Electron模块时，会出现加载时间错误。
  • you include the flag /DELAYLOAD:node.exe. 包括标志/DELAYLOAD:node.exe。If the node.exe link is not delayed, then the delay-load hook won't get a chance to fire and the node symbols won't be correctly resolved.如果node.exe链路没有延迟，则延迟加载挂钩将没有机会触发，节点符号将无法正确解析。
  • win_delay_load_hook.obj is linked directly into the final DLL. 直接链接到最终DLL。If the hook is set up in a dependent DLL, it won't fire at the right time.如果钩子是在依赖DLL中设置的，它将不会在正确的时间触发。

See node-gyp for an example delay-load hook if you're implementing your own.如果您正在实现自己的延迟加载钩子，请参阅node-gyp。

Modules that rely on prebuild依赖于prebuild的模块​

prebuild provides a way to publish native Node modules with prebuilt binaries for multiple versions of Node and Electron.提供了一种发布原生节点模块的方法，其中包含多个版本的Node和Electron的预构建二进制文件。

If the prebuild-powered module provide binaries for the usage in Electron, make sure to omit --build-from-source and the npm_config_build_from_source environment variable in order to take full advantage of the prebuilt binaries.如果prebuild模块提供用于Electron的二进制文件，请确保省略--build-from-source和npm_config_build_from_source环境变量，以便充分利用预构建的二进制文件。

Modules that rely on node-pre-gyp依赖于node-pre-gyp的模块​

The node-pre-gyp tool provides a way to deploy native Node modules with prebuilt binaries, and many popular modules are using it.node-pre-gyp工具提供了一种使用预先构建的二进制文件部署原生节点模块的方法，许多流行的模块都在使用它。

Sometimes those modules work fine under Electron, but when there are no Electron-specific binaries available, you'll need to build from source. 有时，这些模块在Electron下工作良好，但当没有可用的特定于Electron的二进制文件时，您需要从源代码构建。Because of this, it is recommended to use electron-rebuild for these modules.因此，建议对这些模块使用electron-rebuild。

If you are following the npm way of installing modules, you'll need to pass --build-from-source to npm, or set the npm_config_build_from_source environment variable.如果您遵循npm方式安装模块，则需要将--build-from-source传递给npm，或者设置npm_config_build_from_source环境变量。