Вы пытаетесь использовать приватные пакеты (Private Package) в проекте своей компании, но застряли на настройке .npmrc?

Почему вы все еще получаете 404 Not Found даже после настройки токена (Token)?

Когда в компании есть несколько команд и несколько пакетов (например, @frontend, @backend), как элегантно управлять .npmrc?

Разрушение двух мифов о .npmrc

Чтобы понять .npmrc, вам сначала нужно понять, как он работает.

Проще говоря, его основная логика — это всего две вещи: Сопоставление области (Scope Mapping) и Аутентификация (Authentication).

1. Сопоставление области (Scope Mapping)

Это говорит npm: когда вы видите пакет, начинающийся с @company, не ходите на официальный npmjs.org, идите в наш указанный GitLab Registry.

@company:registry=https://gitlab.com/api/v4/groups/100/-/packages/npm/

2. Аутентификация (Authentication)

С адресом вам также нужен ключ. Ключ — это ваш AuthToken.

Вот супер важное правило: URL реестра и путь AuthToken должны «точно совпадать».

# ✅ Правильно: Путь точно такой же, как у реестра, определенного выше
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ Неправильно: Несоответствие пути, это приведет к ошибке доступа
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

Многие люди терпят неудачу в настройке часто потому, что в пути есть лишняя косая черта или не хватает уровня.

Ад зависимостей и ошибки 404

Самая болезненная ситуация: вы устанавливаете пакет A, который зависит от пакета B (тоже приватного), и затем npm выдает 404 Not Found.

Почему это происходит? Это потому, что когда npm разрешает зависимости, если нет правильной связи, он теряется.

Особенно когда у вас есть две разные области (например, @team-a и @team-b) в разных группах GitLab, .npmrc становится чрезвычайно сложным и трудным для поддержки. Кроме того, разным реестрам могут потребоваться разные токены, просто управление этими переменными среды утомляет.

Есть ли более умный способ?

Рекомендуемое решение: Unified Download Group Registry и Independent Publish Project Registry

Зачем это делать?

Настройка в действии

Вы можете скопировать этот шаблон напрямую:

Не забудьте передать задачу защиты токена переменным среды, абсолютно не прописывайте токен в коде!

# .npmrc
# @company scope использует реестр уровня группы
# Все пакеты @company/* будут устанавливаться из этого реестра
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Конфигурация аутентификации GitLab npm registry
# Использовать общий токен аутентификации gitlab.com (покрывает все запросы уровня группы и проекта)
//gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
# Использовать реестр проекта для публикации пакетов
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}


# Другие публичные пакеты по-прежнему идут в официальный реестр
registry=https://registry.npmjs.org/

Настройте publishConfig в package.json, чтобы публиковать пакет в соответствующий GitLab Project Registry.

{
  "name": "@company/my-package",
  "publishConfig": {
    "@company:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
  }
}

Заключение

Благодаря стратегии «Unified Download Group Registry» и «Independent Publish Project Registry» мы можем значительно снизить затраты на обслуживание и сделать процесс разработки более плавным.

Освоив эти логики, GitLab NPM Registry станет мощным помощником в процессе разработки вашей компании!