你是因为公司项目需要使用私有包（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 就是你公司开发流程中强大的帮手了！