Composer通过SSH拉取GitLab私有仓库配置失效问题排查

两次报错分别对应两个配置逻辑问题：

• 配置vcs类型源时，Composer内置的GitLab驱动默认优先调用GitLab HTTP API拉取包元数据，不会直接走你配置的SSH地址克隆。你手动执行git clone能用SSH不代表Composer请求API有权限，所以才会出现请求GitLab API返回404、弹出凭证输入框的情况——它从一开始就没走SSH通道拉元数据，甚至路径解析还错把路径里的the-vendor识别成了joij，自然找不到对应项目。
• 改成git类型源时报找不到包，一是本地残留了之前拉取失败的Composer缓存，二是默认prefer-dist配置下Composer会优先尝试拉取发行压缩包而非git源，加上没显式指定走源码拉取，导致没识别到git源里的包配置。

方案一：vcs类型源强制走SSH（最稳定，推荐） #

不需要配置GitLab token，直接复用你本地已经验证可用的SSH密钥即可：

1. 修改项目根目录composer.json的repositories配置，给vcs源添加no-api参数，彻底禁用GitLab API拉取逻辑：

"repositories": [
  {
     "type": "vcs",
     "url": "git@gitlab.com:the-vendor/dashboard-api.git",
     "no-api": true
  }
]

no-api: true是核心配置，加完后Composer不会再发HTTP请求到GitLab API，会直接通过git命令走SSH通道拉取代码、解析分支标签和包元数据，完全绕开API鉴权、路径解析错误的问题。

2. 确认项目根目录composer.json的稳定性配置和目标包对齐，避免dev分支被稳定性过滤掉：

"minimum-stability": "dev",
"prefer-stable": true

3. 清除本地Composer缓存后重新执行更新，加verbose参数可以看到拉取过程确认走SSH：

composer clear-cache
composer update the-vendor/dashboard -vvv

方案二：git类型源正确配置 #

如果方案一仍有异常，可以用git类型源，修正之前的配置疏漏：

1. 先确认远端仓库确实存在你要拉取的orchestrate、main分支，不要写错分支名。
2. 把repositories配置改成git类型：

"repositories": [
  {
     "type": "git",
     "url": "git@gitlab.com:the-vendor/dashboard-api.git"
  }
]

3. 清缓存后强制走源码拉取，跳过压缩包拉取逻辑：

composer clear-cache
composer require the-vendor/dashboard:dev-orchestrate --prefer-source

--prefer-source参数会强制Composer走git克隆流程拉取代码，适配SSH协议场景，不会尝试请求HTTP接口下载压缩包。

如果上述步骤执行后仍有问题，逐一检查以下配置：

• 如果你本地配置了多个GitLab账号的SSH密钥，编辑~/.ssh/config文件，确保访问gitlab.com时使用的是有权限访问目标私有仓库的私钥，参考配置：

Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/对应GitLab账号的私钥文件路径
  IdentitiesOnly yes

• 确认目标私有仓库的composer.json文件存放在仓库根目录，不要放在子目录下，否则Composer拉取代码后找不到包配置也会报找不到包的错误。
• 不要在composer.json的config项里配置错误的gitlab-domains参数，避免Composer误触发GitLab API驱动逻辑。

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