运行 composer install -vvv 可暴露真实失败点：cloning into... 后 permission denied → ssh 未通；could not read username → https 凭据管理器未设；curl error 22 或 401 → auth.json 路径错、权限非600、域名大小写不一致；http/2 404 含 /api/v4/projects/ → gitlab api 未启用或权限不足。
运行 composer install -vvv 观察真实失败点
composer install 默认静默降级或 fallback，看不出到底卡在哪。加
-vvv 才能暴露底层
git 命令和 HTTP 状态码。常见线索包括：
-
Cloning into bare repository... 后立即报 Permission denied (publickey) → SSH 未通，不是 Composer 配置问题，而是 ssh -T git@your-gitlab-host 没过
- 出现
could not read Username for 'https://gitlab.example.com' → HTTPS 方式下 git 凭据管理器没生效，git config --global credential.helper store 没设，或没手动跑过一次带 token 的 git clone
- 报
curl error 22 或 HTTP/1.1 401 Unauthorized → auth.json 路径错、权限不对（必须 chmod 600 ~/.composer/auth.json）、域名大小写不一致（GitLab.example.com ≠ gitlab.example.com）
- 报
HTTP/2 404 且 URL 含 /api/v4/projects/... → GitLab 实例未启用 API，或 read_api 权限没开，或 gitlab-domains 漏配
先绕过 Composer，用原生命令验证 Git 连通性
Composer 不会帮你诊断 git 层问题，它只消费结果。必须手动验证两件事是否都通：
-
ssh -T git@your-gitlab-host 成功 → 说明密钥加载、host key 已信任、SSH agent 正在运行（ssh-add -l 应有输出）
-
git ls-remote git@your-gitlab-host:group/repo.git 返回 ref 列表 → 说明 URL 格式正确（冒号分隔、以 .git 结尾）、仓库存在、权限足够
注意：如果 URL 是
git@10.0.1.5:group/repo.git，
~/.ssh/config 中的
Host 必须写成
10.0.1.5，不能写别名（除非 hosts 或 DNS 已映射）；否则
ssh -T 和
git ls-remote 都会失败。
auth.json 放错位置或字段名写错是高频坑
auth.json 必须放在
~/.composer/auth.json（Linux/macOS），Windows 是
%APPDATA%\Composer\auth.json，**项目根目录下的
auth.json 无效**。内容结构必须严格匹配：
- GitLab token 认证用
"gitlab-token" 字段，不是 "gitlab-oauth"、"token" 或 "access_token"
- 域名必须精确匹配，不带协议、全小写：
"gitlab.example.com" ✅，"https://gitlab.example.com" ❌，"GitLab.example.com" ❌
- 若非
gitlab.com，必须加 "gitlab-domains": ["gitlab.example.com"]
- 文件权限必须为
600，否则 Composer 直接忽略该文件
清除缓存再重试，避免旧失败状态干扰
Composer 缓存会记住上次失败的克隆路径或元数据，导致改完配置后仍报同样错。执行：
-
composer clear-cache 清掉全局缓存
-
rm -rf ~/.composer/cache/vcs/http---gitlab.example.com-*（Linux/macOS）或手动删 %APPDATA%\Composer\Cache\vcs\ 下对应目录
- 加
--no-cache 参数强制跳过缓存：composer install --no-cache -vvv
尤其当改了
auth.json 或
~/.ssh/config 后，不清缓存很可能继续走旧路径，掩盖真实问题。
真正卡住的地方往往不在 Composer 配置本身，而在 SSH 连通性、git 凭据缓存、或
auth.json 文件是否被真正读取——这三个环节任一失败，
composer install 都只会报一个模糊错误。
