在package.json中添加GitLab私有仓库时出现ENOENT错误求助

问题场景 #

在项目package.json中添加GitLab私有仓库依赖：

"dependencies": {
  "project": "git+https://myusername:gitlabTokenGenerated@gitlab.com/groupName/project.git",
  "mysql2": "^3.6.2"
}

执行npm install时触发如下错误：

npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /root/.npm/_cacache/tmp/git-cloneAfWhq/package.json
npm ERR! errno -2
npm ERR! enoent ENOENT: no such file or directory, open '/root/.npm/_cacache/tmp/git-cloneAfWhq/package.json'
npm ERR! enoent This is related to npm not being able to find a file.

移除该私有依赖后安装可正常执行，删除项目内的package-lock.json问题仍存在，怀疑是缓存导致npm未读取仓库内的package.json。

根源分析 #

缓存问题是可能原因之一，但更常见的根源包括：

• 私有仓库缺少package.json：目标仓库的默认分支（如main/master）根目录下不存在package.json，或文件被.gitignore规则排除，导致npm克隆后找不到该文件。
• GitLab Token权限不足：生成的Token未配置read_repository权限，导致克隆仓库时无法完整拉取所有文件，package.json未被下载到临时目录。
• npm缓存损坏：.npm/_cacache目录下的临时缓存文件损坏，导致npm读取克隆后的仓库文件失败。
• 依赖URL格式错误：用户名或Token包含特殊字符（如@、/）未做URL转义，导致克隆路径解析异常，无法正确获取仓库文件。

解决步骤 #

1. 验证仓库package.json存在
   登录GitLab查看目标仓库的默认分支根目录，确认package.json存在且未被.gitignore屏蔽。

2. 检查GitLab Token权限
   确保Token拥有该仓库的read_repository权限，若权限不足，重新生成具备对应权限的Token。

3. 清理npm缓存并重装
   执行以下命令彻底清理缓存后重新安装：

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

4. 修正依赖URL格式

   • 若用户名/Token含特殊字符，用URL编码转义（如@转成%40）；
   • 或改用SSH格式的依赖URL（需配置SSH密钥）：

     "project": "git+ssh://git@gitlab.com/groupName/project.git"
     

5. 指定仓库分支/标签
   在依赖URL后追加分支或标签，确保npm克隆指定版本：

   "project": "git+https://myusername:gitlabTokenGenerated@gitlab.com/groupName/project.git#main"
   

内容的提问来源于stack exchange，提问作者Jean-Loup