Пусть npm выбирает реестр по области пакета, а не по VPN

Подключение к VPN не должно означать правку настройки реестра npm дважды в день. Запись области в файле конфигурации на уровне проекта может отправлять пакеты компании в один реестр, а всё остальное — в публичный, без переключений и без переопределения, забытого в пятницу вечером. Загвоздка в том, что это решает только именование; маршрутизация, учётные данные и приоритет конфигурации — три отдельные вещи, каждая из которых ломается по-своему.

Два имени, два пункта назначения

Имя пакета npm либо имеет область, либо нет. Имя с областью начинается со знака @ и идентификатора области, и именно этот идентификатор конфигурация может сопоставить. Ничто другое в пакете для сопоставления не важно. Реестр никогда не видит запрос, исходя из того, внутренний пакет или публичный; он видит только имя.

Поэтому файл ниже выражает два намерения в трёх строках: публичные пакеты идут в публичный реестр, а пакеты под областью компании идут в реестр компании с токеном для этого хоста.

registry=https://registry.npmjs.org/
@acme:registry=https://packages.corp.example/
//packages.corp.example/:_authToken=${NPM_TOKEN}

Замените область, хост и имя переменной на то, что организация действительно предоставляет. Важна структура, а не примерные значения. Две строки конфигурации несут всю политику, поэтому их стоит понимать, а не копировать.

Держите сопоставление и сеть в отдельных отсеках в голове. Запись области не может сделать недоступный хост доступным, а работающий туннель не может сказать npm, к какому реестру относится пакет.

Пишите файл в правильном порядке

Поставьте файл проекта первым в своих рассуждениях, хотя npm читает несколько файлов. .npmrc в каталоге проекта — это тот, который коллеги наследуют через репозиторий, поэтому он должен выражать общую политику, а не ваш личный токен. Этот же файл будет читать рецензент. Держите его достаточно малым, чтобы просмотреть одним взглядом.

Оставьте строку registry по умолчанию указывающей на публичный реестр, если организация не решила иначе. Её удаление делает машину зависимой от того, что говорит файл уровня пользователя, и это именно та неявная зависимость, которая даёт разные результаты на двух ноутбуках.

Строка области — не подстановочный знак. Имя вне области продолжает использовать значение по умолчанию, и это то поведение, которое нужно для каждой зависимости, написанной не вами.

Проверьте, во что разрешается файл, прежде чем фиксировать его, используя одноразовое имя пакета вместо настоящей установки, чтобы ошибка ничего не стоила.

Учётные данные принадлежат хосту, а не проекту

Записи аутентификации привязаны к хосту реестра и, где реестру это нужно, к пути. Поэтому строка токена начинается с двойной косой черты и хоста, а не с области. Как только вы увидите хост на этом месте, остаток строки перестаёт выглядеть произвольной пунктуацией. Это адрес, и токен прикреплён к нему.

Использование переменной окружения держит буквальный токен вне файла в репозитории. Это не делает токен невидимым везде; он всё ещё появляется в окружении процесса, и команда, печатающая конфигурацию, может его раскрыть.

Предоставьте переменную через любой локальный или CI-механизм учётных данных, который одобряет организация, и никогда не вставляйте настоящий токен в пример, который может быть скопирован в документацию.

Если в игре два реестра, каждый получает свою запись. Одна неквалифицированная настройка токена в лучшем случае неоднозначна, а в худшем отправлена не тому хосту.

Когда побеждает неправильный реестр

Конфигурация слоистая, и действующее значение не обязательно является значением в файле, который вы только что правили. Настройки проекта, настройки пользователя, глобальные настройки и переменные окружения участвуют все. Эта слоистость — причина, по которой исправление работает на вашей машине и не работает в контейнере коллеги. Она же причина того, что действующее значение стоит напечатать, прежде чем спорить о нём.

Переменная окружения — обычный виновник в CI, где задание задаёт реестр один раз и каждый следующий шаг наследует его. Второй по частоте — файл уровня пользователя на машине разработчика, который переопределяет то, что говорит репозиторий.

Напечатайте действующую конфигурацию и разрешённый реестр для одного имени с областью и одного без области, прежде чем отлаживать что-либо ещё. Если эти два ответа совпадают с ожиданием, проблема в сети; если нет, проблема в конфигурации и никакая работа с VPN не поможет.

Контрольный список перед фиксацией

Убедитесь, что имя области соответствует фактически опубликованным пакетам, что реестр по умолчанию указан явно и что строка токена называет правильный хост. Опечатка в области даёт самый странный сбой из всех, потому что пакет разрешается из публичного реестра и возвращает чужой модуль с тем же именем. Проверьте имя, прежде чем отлаживать токен.

Убедитесь, что приватный реестр доступен с машины в том контексте, который выполняет установку, а не только из вашего браузера. Это различие важно, когда у прокси или контейнера маршрутизация отличается от вашей оболочки.

Затем убедитесь в поведении на чистой выгрузке без кэшированных пакетов. Свежая установка — единственный тест, показывающий, что испытает новый коллега.