npm_config_*: настройки npm через переменные окружения

Как имя настройки превращается в переменную окружения

Документация npm принимает environment variables, начинающиеся с `npm_config_`, как параметры конфигурации. Для имён с дефисами используется подчёркивание: настройка `fetch-retries` соответствует `npm_config_fetch_retries`. Имена обрабатываются без учёта регистра, но внутри lifecycle scripts npm сам устанавливает ряд lowercase-переменных, поэтому на практике лучше придерживаться lowercase `npm_config_*` и не создавать две версии одного имени. Значение environment удобно тем, что действует на процесс и его потомков, а не обязательно сохраняется на диск. Это делает метод полезным для временной настройки runner, Docker build stage или локального теста с другим registry. Но «временно» не означает «невидимо»: секреты всё равно могут утечь в логи или process environment, поэтому токены нужно передавать через защищённые механизмы CI.

Совет: Используйте одно написание — lowercase `npm_config_..`. Это уменьшает риск конфликтов с переменными, которые npm создаёт внутри scripts.

Как задать и проверить npm_config_* без путаницы

1. 1. Найдите точное имя параметра в документации npm. Для `fetch-retries` переменная будет `npm_config_fetch_retries`.
2. 2. Экспортируйте переменную только в нужной shell/CI-job. Linux/macOS: `export npm_config_fetch_retries=4`; в CI используйте механизм env платформы.
3. 3. Проверьте эффективное значение командой `npm config get fetch-retries`. Это лучше, чем предполагать, что export сработал.
4. 4. Если значение неожиданное, уберите одноимённый CLI-флаг: параметры командной строки имеют более высокий приоритет, чем environment.
5. 5. Затем проверьте project, user и global npmrc через `npm config list`/`npm config get`, учитывая, что environment перекрывает config files.
6. 6. Для одноразового эксперимента задайте переменную только на одну команду, например `npm_config_fetch_retries=4 npm install` в POSIX-shell.
7. 7. После теста удалите переменную или завершите job, чтобы настройка случайно не повлияла на следующую команду.

Важно: Диагностируйте эффективное значение через `npm config get <key>`. Проверка только файла `.npmrc` не видит более приоритетные CLI и environment.

Приоритет CLI, environment и npmrc

Для практической отладки достаточно помнить направление приоритета: command-line flags выше environment, а environment выше конфигурационных файлов npm. Среди файлов npm использует разные уровни — project, user, global и встроенные настройки — и итог зависит от конкретного ключа и контекста запуска. Это объясняет типичную ситуацию: вы исправили `.npmrc`, но `npm config get registry` всё ещё показывает старый URL, потому что runner экспортирует `npm_config_registry`. Обратная ситуация бывает в Dockerfile: ENV остался в образе и неожиданно влияет на все будущие `npm install`. Поэтому настройки, нужные только на стадии сборки, лучше ограничивать scope процесса или stage. В production-образ не стоит без необходимости переносить лишние npm-переменные, особенно связанные с приватными registry.

Если npm «игнорирует» переменную окружения

• Проверьте имя: дефисы в ключе npm должны стать подчёркиваниями после `npm_config_`.
• Выведите эффективное значение `npm config get`, а не только `echo $npm_config_..`.
• Проверьте, нет ли более приоритетного CLI-флага в npm script, shell alias или CI-шаблоне.
• Убедитесь, что переменная определена в той же job/container/process-среде, где реально запускается npm.
• В lifecycle script не создавайте одновременно uppercase и lowercase варианты одного `npm_config_*`.
• Если речь о registry auth, проверьте безопасный механизм секретов отдельно: неправильная авторизация может выглядеть как проблема config.

Когда environment лучше .npmrc, а когда хуже

Environment удобен для динамических параметров: временный registry mirror, путь к cache конкретного runner, число сетевых повторов или настройка, которая меняется между окружениями. `.npmrc` лучше для стабильной, ревьюируемой конфигурации проекта, которую должны одинаково видеть разработчики. Секреты требуют отдельной дисциплины независимо от формата: нельзя коммитить токен в project `.npmrc`, но и нельзя печатать все environment variables в CI ради диагностики. Хорошая схема отделяет публичную конфигурацию от credentials, явно задаёт приоритетные значения и умеет показать эффективную настройку без раскрытия секрета. Если команда работает только при ручном `export`, а CI нет, проблема обычно не в npm как таковом, а в scope переменной или в том, что другой слой конфигурации её перекрывает.

Build-time и runtime: не оставляйте лишнее в образе

Для контейнеров полезно различать build-time и runtime configuration. Если npm нужен только при сборке, временные config variables не должны без причины оставаться в финальном runtime-образе. Это уменьшает количество скрытых настроек и снижает риск случайно сохранить адрес внутреннего registry или чувствительные параметры там, где npm уже вообще не используется. В multi-stage build передавайте только то, что требуется конкретной стадии, а после установки зависимостей проверьте итоговое окружение. Чем меньше неочевидных override, тем проще воспроизводить сборку и расследовать её отличие от локального запуска. При переносе настроек между локальной машиной и CI составьте короткий список ключей, которые действительно должны отличаться. Registry, cache и сетевые повторы могут быть окруженческими, а часть параметров проекта лучше хранить в ревьюируемом `.npmrc`. Если всё превращено в environment, конфигурация становится невидимой для кода и её трудно воспроизвести. Если всё записано в repository config, растёт риск случайно закрепить корпоративные значения. Разделение стабильных и окруженческих параметров делает сборку предсказуемее.

Что учитывать

Условия меняются. Страница отражает состояние на 2026-09-21; при расхождении с официальной документацией приоритет у первоисточника.

Источники и проверка

Инструкция составлена редакцией N1RO на 2026-09-21. Перед действием сверьте актуальные условия на официальном сайте сервиса или производителя.

• Config (npm Docs)