Что проверить первым
- Сравните
node --versionиnpm --versionлокально и в CI. Версия npm и версия Node.js — разные величины. - Сохраните полный текст первой ошибки и определите этап: установка, сборка или запуск приложения.
- На отдельном стенде проверьте scripts и источники пакетов. Разрешайте выполнение только после проверки конкретной зависимости.
| Симптом | Первая проверка | Следующий шаг |
|---|---|---|
| Установка завершилась, бинарный модуль не запускается | Заблокированные install scripts, платформа и архитектура сборки | Проверить script нужного пакета и повторить его сборку на стенде |
| Не устанавливается пакет из Git или по URL | Источник в package.json и lock-файле, политика allow-git/allow-remote | Проверить происхождение и необходимость исключения либо перейти на registry |
| npm сообщает о неизвестном флаге | Команда в CI и справка установленной версии | Заменить сокращённый или ошибочный флаг на документированный |
| Локально работает, в CI нет | Версии, образ, lock-файл, разрешения и кеш | Повторить установку в чистом окружении с теми же версиями |
npm 12 уже выпущен: что изменилось
Стабильный npm 12.0.0 вышел 8 июля 2026 года. Июньское объявление о будущем релизе теперь является историческим контекстом. Проверять нужно поведение установленной версии, а не ждать июльского обновления.
В npm 12 выполнение lifecycle scripts зависимостей по умолчанию ограничено политикой allowScripts корневого package.json. Поэтому наличие пакета в node_modules не означает, что выполнился нужный шаг установки. Для Git-зависимостей и прямых URL также изменились defaults: allow-git и allow-remote равны none. Кроме того, неизвестные и сокращённые CLI-флаги могут завершать команду ошибкой.
Эти ограничения уменьшают возможность незаметного запуска чужого кода при установке. Для старого проекта важно выяснить, на какое неявное поведение опиралась сборка, и явно описать только необходимые исключения.
Как проверить install scripts
Команды ниже предназначены для тестового контура и npm 12. Сначала прочитайте справку установленной версии; перед разрешением scripts изучите их код, версию пакета и происхождение артефакта.
node --version
npm --version
npm install-scripts --help
npm install-scripts ls
npm install-scripts ls показывает зависимости с install scripts и состояние разрешений. Официальная документация install-scripts описывает команды просмотра, одобрения и запрета. Для точечного решения используйте имя реально проверенного пакета вместо reviewed-package:
npm install-scripts approve reviewed-package
npm rebuild reviewed-package
Первая команда записывает разрешение в package.json; вторая выполняет пересборку и может запустить код пакета. Поэтому эти команды выполняют после проверки зависимости, в среде без рабочих секретов. Команда npm approve-scripts reviewed-package также описана в справке npm; не путайте одобрение с выполнением scripts.
После решения проверьте diff package.json и lock-файла. Зафиксируйте нужные изменения в репозитории и повторите чистую установку через npm ci. Одна успешная пересборка в старом node_modules ещё не подтверждает воспроизводимость релиза. Массовое разрешение всех scripts не помогает понять, какие из них нужны проекту.
Условный пример: установка прошла, native-модуль не работает
На стенде после смены npm зависимость появилась в node_modules, но тест приложения сообщил, что бинарный модуль не найден. Это пример последовательности проверки, а не результат диагностики конкретного клиента.
- Сравнили Node.js, npm, ОС и архитектуру стенда с CI: они совпали.
- В списке install scripts обнаружили пакет со сборкой бинарной части и отсутствующим разрешением.
- Проверили источник, закреплённую версию и содержимое script; разрешили только этот пакет.
- Пересобрали пакет и повторили тест, затем выполнили чистую установку из lock-файла в новом окружении.
Исправление принимают, когда чистая сборка и контрольный сценарий проходят одинаково на стенде и в CI. Если модуль всё ещё не загружается, проверяют ABI, архитектуру и наличие инструментов сборки; блокировка script — одна из гипотез, а не универсальное объяснение.
Git и remote URL: что проверить отдельно
Найдите зависимости не из обычного registry в package.json и lock-файле. Для каждой запишите источник, закреплённую версию или commit, владельца и причину использования. Затем решите, можно ли перейти на опубликованный пакет или контролируемый private registry.
Если исключение необходимо, настройте его по справке config вашей версии npm и проверьте прямые и транзитивные зависимости. Не включайте глобальное разрешение всех источников только ради зелёной сборки. Разрешение источника не заменяет проверку install scripts.
Как проверить CI и подготовить откат
Зафиксируйте одинаковые Node.js, npm и образ сборки; повторите установку из сохранённого lock-файла без старого кеша. Затем проверьте build, тесты, запуск сервиса, очереди и критичные сценарии: вход, заявку, оплату в тестовом режиме и интеграцию с тестовым получателем.
До выпуска сохраните прежние commit, lock-файл и образ, проверьте возможность вернуться к ним. Не совмещайте смену npm с обновлением фреймворка и переделкой CI: отдельное изменение проще проверить и откатить.
Результат работы — перечень разрешённых scripts и источников, воспроизводимая сборка, протокол проверки приложения и план возврата. Если команда не знает, где собирается проект и какие зависимости выполняют код, начните с поддержки сайта. OpenStart поможет определить границы первого этапа аудита и проверить обновление на тестовом контуре.