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

Token을 설정했는데 왜 여전히 404 Not Found가 발생하는 걸까요?

회사에 여러 팀과 여러 패키지(예: @frontend, @backend)가 있을 때, .npmrc를 어떻게 우아하게 관리할 수 있을까요?

.npmrc의 두 가지 미신 타파

.npmrc를 이해하려면 먼저 그것이 어떻게 작동하는지 이해해야 합니다.

간단히 말해, 핵심 로직은 단 두 가지입니다: Scope 매핑과 인증.

1. Scope 매핑 (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에 있는 두 개의 서로 다른 Scope(예: @team-a와 @team-b)가 있을 때, .npmrc는 매우 복잡해지고 유지 관리가 어려워집니다. 게다가 서로 다른 Registry에는 서로 다른 Token이 필요할 수 있어서, 이러한 환경 변수를 관리하는 것만으로도 지치게 됩니다.

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

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

왜 이렇게 해야 할까요?

설정 실전

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

Token 보호 작업은 환경 변수에 맡기고, 코드에 Token을 직접 하드코딩하지 마십시오!

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

# GitLab npm registry 인증 설정
# 공통 gitlab.com auth token 사용 (모든 group 및 project 레벨 요청 커버)
//gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
# 프로젝트 registry를 사용하여 패키지 게시
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}


# 기타 공개 패키지는 공식 레지스트리로
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는 회사 개발 프로세스에서 강력한 도우미가 될 것입니다!