Bạn đang cố gắng sử dụng Private Package trong dự án công ty nhưng bị kẹt ở cấu hình .npmrc?

Tại sao bạn vẫn nhận được 404 Not Found ngay cả khi đã thiết lập Token?

Khi công ty có nhiều nhóm và nhiều gói (ví dụ: @frontend, @backend), làm thế nào để bạn quản lý .npmrc một cách duyên dáng?

Giải mã hai lầm tưởng về .npmrc

Để hiểu .npmrc, trước tiên bạn cần hiểu cách nó hoạt động.

Nói một cách đơn giản, logic cốt lõi của nó chỉ là hai điều: Scope Mapping và Authentication.

1. Scope Mapping

Điều này nói với npm: Khi bạn thấy một gói bắt đầu bằng @company, đừng đến npmjs.org chính thức, hãy đến GitLab Registry được chỉ định của chúng tôi.

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

2. Authentication

Có địa chỉ rồi, bạn cũng cần một chiếc chìa khóa. Chìa khóa chính là AuthToken của bạn.

Đây là một quy tắc cực kỳ quan trọng: Registry URL và đường dẫn AuthToken phải “khớp chính xác”.

# ✅ Correct: Đường dẫn giống hệt với registry được xác định ở trên
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ Incorrect: Không khớp đường dẫn, điều này sẽ gây ra lỗi quyền
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

Nhiều người thất bại trong việc cấu hình thường là do đường dẫn có thêm một dấu gạch chéo hoặc thiếu một cấp.

Địa ngục phụ thuộc và lỗi 404

Tình huống đau đầu nhất là: Bạn cài đặt gói A, gói này phụ thuộc vào gói B (cũng là riêng tư), và sau đó npm phun ra 404 Not Found.

Tại sao điều này xảy ra? Đó là bởi vì khi npm giải quyết các phụ thuộc, nếu không có mối quan hệ chính xác, nó sẽ bị lạc.

Đặc biệt là khi bạn có hai Scope khác nhau (ví dụ: @team-a và @team-b) trong các GitLab Group khác nhau, .npmrc trở nên cực kỳ phức tạp và khó bảo trì. Thêm vào đó, các Registry khác nhau có thể cần các Token khác nhau, chỉ cần quản lý các biến môi trường này thôi cũng đủ mệt rồi.

Có cách nào thông minh hơn không?

Giải pháp được đề xuất: Unified Download Group Registry & Independent Publish Project Registry

Tại sao phải làm điều này?

Cấu hình trong thực tế

Bạn có thể sao chép trực tiếp mẫu này:

Hãy nhớ giao nhiệm vụ bảo vệ Token cho các biến môi trường, tuyệt đối không hardcode Token trong code!

# .npmrc
# @company scope sử dụng group level registry
# Tất cả các gói @company/* sẽ cài đặt từ registry này
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Cấu hình xác thực GitLab npm registry
# Sử dụng common gitlab.com auth token (bao gồm tất cả các yêu cầu cấp group và project)
//gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
# Sử dụng project registry để xuất bản các gói
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}


# Các gói công khai khác vẫn đi đến official registry
registry=https://registry.npmjs.org/

Cấu hình publishConfig trong package.json để xuất bản gói vào GitLab Project Registry tương ứng.

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

Kết luận

Thông qua chiến lược “Unified Download Group Registry” và “Independent Publish Project Registry”, chúng ta có thể giảm đáng kể chi phí bảo trì và làm cho quy trình phát triển trơn tru hơn.

Nắm vững các logic này, GitLab NPM Registry sẽ là trợ thủ đắc lực trong quy trình phát triển của công ty bạn!