Модули Node.js нативных

Модули Node.js нативные поддерживаются Electron, но поскольку Electron имеет другой интерфейс прикладного программирования (ABI) по сравнению с заданным бинарником Node.js (из-за таких различий, как использование BoringSSL от Chromium вместо 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 с помощью пакета electron-rebuild. Этот модуль может автоматически определять версию 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 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

Ручная сборка для 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://electronjs.org/headers

• HOME=~/.electron-gyp указывает, где найти заголовки разработки.
• --target=1.2.3 — версия Electron.
• --dist-url=... указывает, где загрузить заголовки.
• --arch=x64 указывает, что модуль скомпилирован для 64-битной системы.

Ручная сборка для пользовательской сборки Electron​

Чтобы скомпилировать нативные модули Node.js для пользовательской сборки Electron, которая не соответствует публичному релизу, укажите npm использовать версию Node, включенную в вашу пользовательскую сборку.

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

Отладка​

Если вы установили нативный модуль и он не работает, проверьте следующее:

• В случае сомнений, сначала выполните electron-rebuild.
• Убедитесь, что нативный модуль совместим с целевой платформой и архитектурой вашего приложения Electron.
• Убедитесь, что win_delay_load_hook не установлено на false в файле binding.gyp модуля.
• После обновления 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, убедитесь, что переменная win_delay_load_hook установлена на значение true в файле binding.gyp, и её не перезаписывают в других местах. Если модуль собран с другой системой, вам нужно убедиться, что вы собрали его с установленным механизмом отложенной загрузки в основной файл .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.lib из Electron, а не из Node. Если вы ссылаетесь на неправильный node.lib, при попытке require модуля в Electron будут возникать ошибки загрузки.
• включить флаг /DELAYLOAD:node.exe. Если ссылка node.exe не отложена, то механизм отложенной загрузки не успеет сработать, и символы node не будут правильно разрешены.
• win_delay_load_hook.obj связан непосредственно в итоговый DLL. Если механизм установлен в зависимом DLL, он не сработает в нужное время.

См. node-gyp для примера механизма отложенной загрузки, если вы реализуете свой собственный.

Модули, которые полагаются на prebuild​

prebuild предоставляет способ публикации нативных модулей Node.js с предварительно скомпилированными бинарными файлами для нескольких версий Node и Electron.

Если модуль, поддерживаемый prebuild, предоставляет бинарные файлы для использования в Electron, убедитесь, что вы опустили --build-from-source и переменную среды npm_config_build_from_source, чтобы полностью использовать преимущества предварительно скомпилированных бинарных файлов.

Модули, которые полагаются на node-pre-gyp​

Инструмент node-pre-gyp предоставляет способ развертывания нативных модулей Node.js с предварительно скомпилированными бинарными файлами, и многие популярные модули используют его.

Иногда эти модули работают нормально в Electron, но если бинарных файлов, специфичных для Electron, нет, вам придётся собирать их из исходного кода. По этой причине рекомендуется использовать electron-rebuild для этих модулей.

Если вы используете способ установки модулей npm, вам нужно передать --build-from-source в npm или установить переменную среды npm_config_build_from_source.