회사 프로젝트에서 Private Package를 사용해야 하는데 .npmrc 설정에서 막히셨나요?

Token을 설정했는데도 왜 여전히 404 Not Found가 나타날까요?

회사에 여러 팀, 여러 패키지(예: @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입니다.

여기 매우 중요한 규칙이 있습니다: Registry URL과 AuthToken 경로는 “정확히 일치"해야 합니다.

# ✅ 올바름: 경로는 위에서 정의한 registry와 완전히 동일합니다.
//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이 길을 잃기 때문입니다.

특히 서로 다른 GitLab Group에 두 개의 서로 다른 스코프(예: @team-a 및 @team-b)가 있는 경우 .npmrc는 매우 복잡하고 유지 관리하기 어려워집니다. 게다가 서로 다른 Registry에는 서로 다른 Token이 필요할 수 있으므로 이러한 환경 변수를 관리하는 것만으로도 벅찹니다.

더 현명한 방법이 있을까요?

권장 솔루션: 통합 다운로드 Group Registry & 독립 게시 Project Registry

왜 이렇게 해야 할까요?

설정 실전

이 템플릿을 직접 복사할 수 있습니다:

Token을 보호하는 작업은 환경 변수에 맡겨야 하며, 절대 코드에 Token을 직접 하드코딩해서는 안 된다는 것을 기억하세요!

# .npmrc
# 일반 도메인 수준 auth token(모든 group 및 project 수준 설치 요청 포함)
//gitlab.com/:_authToken=${GITLAB_NPM_TOKEN}

# 게시용: project-level auth token(npm publish는 정확한 경로 일치 필요)
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

# @company scope는 group 수준 registry 사용
# 모든 @company/* 패키지는 이 registry에서 설치됩니다
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# 기타 공개 패키지는 여전히 공식 라이브러리로 이동합니다
registry=https://registry.npmjs.org/

package.json에서 publishConfig를 설정하여 패키지를 해당 GitLab Project Registry에 게시합니다.

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

결론

**“통합 다운로드 Group Registry”**와 “독립 게시 Project Registry” 전략을 통해 유지 관리 비용을 크게 줄이고 개발 프로세스를 더 원활하게 만들 수 있습니다.

이러한 로직을 마스터하면 GitLab NPM Registry는 회사 개발 프로세스에서 강력한 조력자가 될 것입니다!