Bạn có đang bị kẹt ở cấu hình .npmrc vì dự án công ty cần sử dụng Private Package không?

Tại sao nó vẫn hiển thị 404 Not Found mặc dù Token đã được thiết lập?

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 thanh lịch?

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ó quy về hai điều: Ánh xạ phạm vi (Scope Mapping) và Xác thực (Authentication).

1. Ánh xạ phạm vi (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 tìm kiếm nó trên npmjs.org chính thức, mà 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. Xác thực (Authentication)

Với địa chỉ, bạn cũng cần một chìa khóa. Chìa khóa 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”.

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

# ❌ Sai: Đường dẫn không khớp, sẽ gây ra lỗi quyền hạ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 thừa một dấu gạch chéo hoặc thiếu một cấp trong đường dẫn.

Đị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 ném ra lỗi 404 Not Found.

Tại sao điều này xảy ra? Đó là vì npm bị lạc khi giải quyết các phụ thuộc nếu không có sự tương ứng chính xác.

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

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

Giải pháp được đề xuất: Group Registry tải xuống thống nhất & Project Registry xuất bản độc lập

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 công việc bảo vệ Token cho các biến môi trường, không bao giờ mã hóa cứng Token trực tiếp trong mã!

# .npmrc
# Mã thông báo xác thực cấp miền chung (bao gồm tất cả các yêu cầu cài đặt cấp nhóm và dự án)
//gitlab.com/:_authToken=${GITLAB_NPM_TOKEN}

# Để xuất bản: mã thông báo xác thực cấp dự án (npm publish yêu cầu khớp đường dẫn chính xác)
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

# phạm vi @company sử dụng registry cấp nhóm
# Tất cả các gói @company/* sẽ được cài đặt từ registry này
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Các gói công khai khác vẫn đi đến thư viện chính thức
registry=https://registry.npmjs.org/

Cấu hình publishConfig trong package.json để xuất bản gói lên 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 “Group Registry tải xuống thống nhất” và “Project Registry xuất bản độc lập”, 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ôi chảy hơn.

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