Skip to main content

Modules natifs de 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. Sinon, vous obtiendrez l'erreur de classe suivante lorsque vous essaierez d'exécuter votre application :

Erreur : Le module '/path/to/native/module.node'
a été compilé avec une version de Node.js différente en utilisant
NODE_MODULE_VERSION $XYZ. Cette version de Node.js nécessite
NODE_MODULE_VERSION $ABC. Veuillez essayer de re-compiler ou de réinstaller
le module (par exemple, en utilisant `npm rebuild` ou `npm install`).

Comment installer des modules natifs

Il y a plusieurs façons d'installer des modules natifs :

Installation et compilation de modules pour Electron

Vous pouvez choisir d'installer les modules comme les autres projets Node, puis recompiler les modules pour Electron avec le paquet electron-rebuild. Ce module peut automatiquement obtenir la version d'Electron et gérer les étapes manuelles de téléchargement des en-têtes, compiler les modules natifs pour votre application. If you are using Electron Forge, this tool is used automatically in both development mode and when making distributables.

For example, to install the standalone electron-rebuild tool and then rebuild modules with it via the command line:

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.

À l'aide de npm

En définissant quelques variables d’environnement, vous pouvez utiliser npm pour installer des modules directement.

Par exemple, pour installer toutes les dépendances d'Electron :

# Version d'Electron.
export npm_config_target=1.2.3
# L'architecture d'Electron, consultez
https://electronjs.org/docs/tutorial/support#supported-platforms
# pour les architectures prises en charge.
export npm_config_arch=x64
export npm_config_target_arch=x64
# Télécharge les en-têtes pour Electron.
export npm_config_disturl=https://electronjs.org/headers
# Indique à node-pre-gyp que l'on compile pour Electron.
export npm_config_runtime=electron
# Indique à node-pre-gyp de compiler les modules depuis leur code source.
export npm_config_build_from_source=true
# Installe toutes les dépendances, et met en cache à ~/.electron-gyp.
HOME=~/.electron-gyp npm install

Compilation manuelle pour Electron

Si vous êtes un développeur développant un module natif et que vous voulez le tester avec Electron, vous pouvez recompiler le module pour Electron manuellement. Vous pouvez utiliser node-gyp directement pour compiler pour 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 indique où trouver les en-têtes pour le développement.
  • --target=1.2.3 est la version d'Electron.
  • --dist-url=... indique où télécharger les en-têtes.
  • --arch=x64 spécifie que le module est prévu pour un système 64 bits.

Compilation manuelle pour une compilation personnalisée d'Electron

Pour compiler des modules Node natifs avec une compilation personnalisée d'Electron qui ne correspond pas à une release publique, utilisez la commande npm pour utiliser la version de Node que vous avez empaquetée avec votre compilation personnalisée.

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

Résolution de problème

Si vous avez installé un module natif et trouvé que cela ne fonctionnait pas, vous devez vérifier ces éléments suivants :

  • En cas de doute, exécutez d'abord electron-rebuild.
  • Assurez-vous que le module natif est compatible avec la plateforme cible et l'architecture pour votre application Electron.
  • Assurez-vous que win_delay_load_hook n'est pas défini comme false dans le module binding.gyp.
  • Après avoir mise à jour Electron, vous devez habituellement recompiler les modules.

Une remarque sur win_delay_load_hook

Sur Windows, par défaut, node-gyp relie les modules natifs à node.dll. Cependant, dans Electron 4.x et supérieur, les symboles nécessaires aux modules natifs sont exportés par electron.exe, et node.dll n'existe pas. Afin de charger les modules natifs sous Windows, node-gyp installe un delay-load hoook qui déclenche lorsque le module natif est chargé, et redirige le noeud. la référence ll pour utiliser l'exécutable de chargement au lieu de rechercher node.dll dans le chemin de la recherche de bibliothèque (qui n'afficherait rien). Ainsi, sur Electron 4.x et supérieur, 'win_delay_load_hook' : 'true' est requis pour charger les modules natifs.

Si vous obtenez une erreur comme Module ne s'est pas auto-enregistré, ou La procédure spécifiée n'a pas pu être trouvée, cela peut signifier que le module que vous essayez d'utiliser n'a pas inclus correctement le crochet de chargement de retard. Si le module est construit avec node-gyp, assurez-vous que la variable win_delay_load_hook est définie à true dans la liaison . fichier yp et ne se fait pas écrasé partout. Si le module est construit avec un autre système, vous devrez vous assurer que vous construisez avec un crochet de chargement tardif installé dans le principal. fichier ode. Votre invocation link.exe devrait ressembler à ceci :

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

En particulier, il est important que :

  • you link against node.lib from Electron and not Node. If you link against the wrong node.lib you will get load-time errors when you require the module in Electron.
  • vous incluez le drapeau /DELAYLOAD:node.exe. Si le noeud. Le lien xe n'est pas retardé, alors le crochet de chargement de temps n'aura pas de chance de tirer et les symboles du noeud ne seront pas correctement résolus.
  • win_delay_load_hook.obj is linked directly into the final DLL. If the hook is set up in a dependent DLL, it won't fire at the right time.

Voir node-gyp pour un exemple de Hook de chargement à retardement si vous implémentez le vôtre.

Les modules s'appuyant sur prebuild

prebuild permet de publier facilement des modules natifs Node avec des binaires précompilés pour plusieurs version de Node et d'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.

Les modules s'appuyant sur node-pre-gyp

node-pre-gyp tool fournit un moyen de déployer des modules natifs Node avec des binaires précompilés, beaucoup de modules populaires l'utilisent.

Sometimes those modules work fine under Electron, but when there are no Electron-specific binaries available, you'll need to build from source. Because of this, it is recommended to use electron-rebuild for these modules.

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.