メインコンテンツにスキップ

ネイティブ Node モジュール

Electron はネイティブ Node.js モジュールをサポートしていますが、Electron は特定の Node.js バイナリとは異なる アプリケーションバイナリインターフェース (ABI) を持っているため (Chromium の BoringSSL を 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 のバージョンを自動的に判別し、ヘッダーのダウンロードとアプリのネイティブモジュールの再構築を手動で行う手順を処理できます。Electron Forge を使用している場合、このツールは開発モードと配布物の作成の両方で自動的に使用されます。

たとえば、スタンドアロンの @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

Electron Packager などの他のツールとの使用方法と統合の詳細については、プロジェクトの README を参照してください。

npm の使用​

いくつかの環境変数を設定することで、npm を使用してモジュールを直接インストールできます。

たとえば、Electron のすべての依存関係をインストールするには、次のようにします。

# Electron's version.
export npm_config_target=1.2.3
# The architecture of your machine
export npm_config_arch=x64
export npm_config_target_arch=x64
# Download headers for Electron.
export npm_config_disturl=https://electron.dokyumento.jp/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

Electron 用の手動ビルド​

ネイティブモジュールを開発している開発者で、Electron に対してテストしたい場合は、Electron 用にモジュールを手動で再構築することができます。node-gyp を使用して Electron 用に直接ビルドできます。

cd /path-to-module/
HOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electron.dokyumento.jp/headers
  • HOME=~/.electron-gyp は、開発ヘッダーを見つける場所を変更します。
  • --target=1.2.3 は Electron のバージョンです。
  • --dist-url=... はヘッダーをダウンロードする場所を指定します。
  • --arch=x64 は、モジュールが 64 ビットシステム用にビルドされていることを示します。

カスタムビルドの Electron 用の手動ビルド​

公式リリースと一致しないカスタムビルドの Electron に対してネイティブ Node モジュールをコンパイルするには、カスタムビルドにバンドルされている Node のバージョンを使用するように npm に指示します。

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 以降では、ネイティブモジュールに必要なシンボルは electron.exe によってエクスポートされ、node.dll は存在しません。Windows でネイティブモジュールを読み込むために、node-gyp はネイティブモジュールが読み込まれたときにトリガーされる 遅延ロードフック をインストールし、ライブラリ検索パスで node.dll を探す代わりに (何も見つかりません)、読み込み実行可能ファイルを使用するように node.dll 参照をリダイレクトします。そのため、Electron 4.x 以降では、ネイティブモジュールを読み込むために 'win_delay_load_hook': 'true' が必要です。

Module did not self-register や The specified procedure could not be found などのエラーが発生した場合、使用しようとしているモジュールに遅延ロードフックが正しく含まれていない可能性があります。モジュールが node-gyp でビルドされている場合は、binding.gyp ファイルで win_delay_load_hook 変数が true に設定されており、どこでも上書きされていないことを確認してください。モジュールが別のシステムでビルドされている場合は、メインの .node ファイルにインストールされている遅延ロードフックを使用してビルドする必要があります。link.exe の呼び出しは次のようになります。

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

特に、次のことが重要です。

  • Node ではなく、*Electron* の node.lib にリンクすること。間違った node.lib にリンクすると、Electron でモジュールを要求したときにロード時エラーが発生します。
  • フラグ /DELAYLOAD:node.exe を含めること。node.exe リンクが遅延されない場合、遅延ロードフックが起動する機会がなくなり、ノードシンボルが正しく解決されません。
  • win_delay_load_hook.obj が最終的な DLL に直接リンクされていること。フックが依存 DLL で設定されている場合、適切なタイミングで起動しません。

独自に実装する場合は、node-gyp を遅延ロードフックの例として参照してください。

prebuild に依存するモジュール​

prebuild は、複数のバージョンの Node と Electron 用にプリビルドされたバイナリを使用してネイティブ Node モジュールを公開する方法を提供します。

prebuild を使用するモジュールが Electron での使用に対応したバイナリを提供している場合は、プリビルドバイナリを最大限に活用するために、--build-from-source と npm_config_build_from_source 環境変数を省略してください。

node-pre-gyp に依存するモジュール​

node-pre-gyp ツール は、プリビルドされたバイナリを使用してネイティブ Node モジュールをデプロイする方法を提供し、多くの人気モジュールがそれを使用しています。

これらのモジュールは Electron で正常に動作する場合がありますが、Electron 固有のバイナリがない場合は、ソースからビルドする必要があります。このため、これらのモジュールには @electron/rebuild を使用することをお勧めします。

モジュールのインストールに npm 方式に従っている場合は、--build-from-source を npm に渡すか、npm_config_build_from_source 環境変数を設定する必要があります。