你是因為公司專案需要使用私有套件（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 在解析依賴時，如果沒有正確的對應關係，它會迷路。

特別是當你有兩個不同的 Scope（例如 @team-a 和 @team-b）分別在不同的 GitLab Group 時，.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 就是你公司開發流程中強大的幫手了！