GitLab私有npm包安装报404错误，求排查解决

核心问题本质 #

你的404错误源于npm请求的包路径与GitLab私有仓库的实际存储规则不匹配，GitLab的npm Registry有严格的URL格式要求，不能直接按常规npm源的拼接逻辑使用。

正确配置方案 #

1. 实例级配置修正 #

你当前使用的实例级registry地址不符合GitLab规则，正确配置需包含项目级权限令牌：

@company:registry=https://gitlab.com/api/v4/packages/npm/
//gitlab.com/api/v4/packages/npm/:_authToken=<你的私有访问令牌>
//gitlab.com/api/v4/projects/<license项目ID>/packages/npm/:_authToken=<你的私有访问令牌>
//gitlab.com/api/v4/projects/<auth项目ID>/packages/npm/:_authToken=<你的私有访问令牌>

注意：令牌必须同时拥有read_api、read_repository、read_package_registry权限。

2. 包名与项目路径严格匹配 #

确保发布的包名@company/license、@company/auth与GitLab的组+项目路径完全一致：

• 组名必须是小写company（GitLab路径大小写敏感）
• 项目名必须是小写license/auth
  若包名或项目路径存在大小写差异，会直接导致404。

3. 组级配置的正确用法 #

组级registry的正确地址需包含组ID，且要同步配置令牌：

@company:registry=https://gitlab.com/api/v4/groups/<company组ID>/-/packages/npm/
//gitlab.com/api/v4/groups/<company组ID>/-/packages/npm/:_authToken=<你的组级访问令牌>

组级令牌必须拥有该组的read_package_registry权限，否则无法读取组内项目的包。

4. 令牌权限验证 #

直接排查令牌权限：

• 若用项目级令牌，需绑定到license、auth等具体项目
• 若用组级令牌，需覆盖整个company组
• 确保令牌未过期、未被撤销

额外排查步骤 #

• 确认包已成功发布到对应项目/组的Package Registry，版本号无拼写错误
• 用Postman测试正确的包获取地址：GET https://gitlab.com/api/v4/projects/<license项目ID>/packages/npm/@company%2Flicense/-/@company%2Flicense-<版本号>.tgz，能返回包文件则说明权限和路径正常，问题出在npm配置
• 执行npm cache clean --force清除缓存后重新安装

内容的提问来源于stack exchange，提问作者NVO