#Как проявляется неисправность
После обновления Node.js приложение может перестать загружать нативный модуль .node: часто появляется NODE_MODULE_VERSION mismatch, ERR_DLOPEN_FAILED или ошибка загрузки системной библиотеки. Причина может быть в двоичной несовместимости, а не в обычном JavaScript.
#Причины и отличительные признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Дополнение было собрано под старый ABIМодуль использует V8/Node ABI и требует пересборки после смены версии. | Сообщение сравнивает NODE_MODULE_VERSION двух версий | Пересобрать зависимости из доверенных исходников для действующего Node.js. |
| Отсутствует системная библиотекаБинарный модуль загружается, но не находит зависимые системные файлы. | В журнале dll/dlopen/cannot open shared object | Проверить официальные системные зависимости пакета и архитектуру. |
| Разные версии Node.js у службы и терминалаСлужба запускает другой исполняемый Node. | В SSH работает, в systemd падает | Согласовать ExecStart и пути среды. |
#Пошаговая диагностика и исправление
- Сохраните точный стек загрузкиВыполните исходный запуск на тестовой копии и выпишите имя
.nodeи строкуNODE_MODULE_VERSION,ERR_DLOPEN_FAILEDлибо имя отсутствующей системной библиотеки. Не удаляйтеnode_modulesна работающем сервере ради пробы.
- Узнайте исполняемый Node.js и его ABIВ том же терминале, который воспроизводит проблему, запустите команду. Вывод показывает версию, полный путь и номер ABI модулей, не требуя доступа администратора. Если служба использует другой Node, эти значения нужно получить также из её диагностического журнала.Linux · Терминал (Bash)КомандаТолько диагностика, без изменения пакетов.
node -p "JSON.stringify({node:process.version,path:process.execPath,modules:process.versions.modules,arch:process.arch,platform:process.platform})"
- Найдите дополнение и его пакетОткройте файл package.json проекта и
package-lock.json, найдите библиотеку, которая вызывает ошибку. Не пытайтесь переименовать файл .node: его двоичный формат должен соответствовать Node.js и ОС. Убедитесь, что каталог проекта действительно содержит нужный lock-файл.
- Создайте копию проекта и восстановите зависимостиСкопируйте код и оба файла package.json/package-lock.json в отдельный тестовый каталог; выполните
npm ciтолько внутри него.npm ciудаляет и заново создаётnode_modulesданного каталога, поэтому на рабочем проекте эта команда может вызвать простой. При неуспехе сохраните первую ошибку установки. - Дополнительная команда по темеLinux · Терминал (Bash)С осторожностьюТолько в копии проекта с package-lock.json; не требуются права администратора, но нужны сеть и разрешённые скрипты сборки.
npm ciКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- Проверьте возможность пересборки нативного пакетаВ копии проекта с официальным пакетом и нужными средствами компиляции выполните
npm rebuild, чтобы повторить подготовку нативных модулей для выбранного Node.js. Если разработчик публикует предварительно собранный пакет под вашу архитектуру, npm может выбрать его автоматически; при ошибке выясните требования сборки. - Дополнительная команда по темеLinux · Терминал (Bash)С осторожностьюТестовая копия; вызывает скрипты установленных пакетов, поэтому доверяйте источникам и не запускайте от root.
npm rebuildКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- Учтите стабильный Node-API и пределы пересборкиЕсли модуль реализован через Node-API и выпуск поддерживает вашу версию, пересборка может не потребоваться; для модулей напрямую на V8/NAN несовместимость встречается чаще. Решение определяется документацией конкретного пакета, не просто номером Node.
- Проверьте результат до переносаВ той же среде запустите приложение и тест функции, которая задействует нативную библиотеку. Если импорт прошёл, но приложение падает внутри вызова, сохраните стек и проверьте совместимость версии пакета и Node. Только после успешных испытаний меняйте среду рабочей службы.
#Проверка результата
Node.js загружает модуль без ERR_DLOPEN_FAILED и вызовы нативной функции работают. Путь к Node и архитектура соответствуют настройкам службы.
При повторной ошибке сравните фактическую команду запуска, журнал приложения и параметры окружения. Если изменения затронули службу, верните предыдущую конфигурацию из сохранённой копии и разберите исходное сообщение об ошибке.