已发布的GitLab私有npm包安装时提示404问题求助

出现该问题的核心原因是npm未正确识别@<main-package-name>作用域对应的私有Registry地址，默认 fallback 到公共npm源拉取包，可按以下步骤排查修复：

• 第一步：检查.npmrc配置格式与优先级
  npm配置优先级为：项目根目录.npmrc > 用户全局.npmrc > 系统级.npmrc，优先检查项目本地.npmrc：

  1. 去掉配置项外层多余的单引号，错误的引号会导致配置不生效，修正后配置应为：

  # 作用域对应的私有源地址
  @<main-package-name>:registry=https://gitlab.<my-organisation-domain>/api/v4/packages/npm/
  # 组级源认证token
  //gitlab.<my-organisation-domain>/api/v4/packages/npm/:_authToken="<my-token>"
  # 项目级源认证token
  //gitlab.<my-organisation-domain>/api/v4/projects/<my-project-id>/packages/npm/:_authToken="<my-token>"
  

  2. 确认当前执行npm install的目录就是项目根目录，且父级目录没有冲突的.npmrc配置覆盖了作用域源地址。

• 第二步：验证作用域源配置是否生效
  执行以下命令查看当前识别的作用域源地址：

  npm config get @<main-package-name>:registry
  

  如果输出不是你的GitLab私有源地址，直接执行GitLab官方给出的配置命令写入本地配置：

  echo @<main-package-name>:registry=https://gitlab.<my-organisation-domain>/api/v4/packages/npm/ >> .npmrc
  

  执行完成后重新运行上面的get命令，确认输出正确的私有源地址。

• 第三步：检查访问令牌权限
  确认你使用的<my-token>是GitLab生成的个人访问令牌，且已勾选read_package_registry权限，若需要发布包还需额外勾选write_package_registry权限。

• 第四步：清除缓存重试安装
  执行以下命令清除旧缓存、删除锁文件后重新安装：

  npm cache clean --force
  rm -rf node_modules package-lock.json
  npm install
  

如果以上步骤操作完仍有问题，可以临时手动指定源安装验证，确认包本身可正常拉取：

npm install @<main-package-name>/<library-name> --registry=https://gitlab.<my-organisation-domain>/api/v4/packages/npm/

如果该命令可正常安装，说明还是本地配置问题，重新核对.npmrc的配置内容即可。

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