根本原因是composer调用系统git命令时认证失败，涉及https凭据过期、ssh密钥未加载、github token权限不足或api限流等多层独立认证机制冲突。
Composer拉取私有仓库时提示“Failed to clone”或“Could not read from remote repository”
根本原因不是 Composer 本身出错，而是它调用系统 git 命令时被拒绝——通常因为凭证过期、缺失或协议不匹配。HTTPS 地址走的是 Git 的 credential helper，SSH 地址依赖本地密钥，两者都可能“静默失效”。
- 先确认
git --version能正常输出，否则连基础环境都没配好 - 如果是 HTTPS 仓库（如
https://github.com/user/repo.git），检查是否还在用旧密码或过期 PAT：Windows 看「凭据管理器」，macOS 看「钥匙串访问」，Linux 运行git credential reject并输入host=github.com和protocol=https - 如果是 SSH 仓库（如
git@github.com:user/repo.git），运行ssh -T git@github.com；失败就说明密钥没加载、公钥没上传，或权限不对（比如私钥文件权限是 755） - 别忽略
git config --global user.name和user.email—— 某些 Git 服务（尤其是自建 GitLab）会校验这个，缺了直接拒
Composer 认证失败但 git clone 成功？查 auth.json 和作用域
这是典型“环境错位”：你手动 git clone 成功，不代表 Composer 能复用同一套认证。Composer 只认自己的凭据链，且优先级很明确。
-
auth.json文件如果存在于项目根目录，它会**完全覆盖**全局配置（~/.composer/auth.json）；用composer config --list查实际生效位置 - GitHub 的 token 必须带
repo权限（不是public_repo），否则访问 fork 库或组织内私有库时会静默失败 - Linux/macOS 下，
~/.composer/auth.json权限必须是600，否则 Composer 直接忽略该文件：chmod 600 ~/.composer/auth.json - CI 环境里常见陷阱：用
root执行composer config --global，但构建跑在www-data或runner用户下——凭证对不上
为什么配了 GitHub Token 还卡在 “API rate limit exceeded”？
因为 Composer 在解析分支名（如 dev-main）、拉取源码（--prefer-source）、或处理未收录到 Packagist 的包时，会直连 https://api.github.com/。这个请求走的是 GitHub API 限流通道，和 git clone 完全无关。
Conventional Git
下载
Conventional Commits v1.0.0 分支、工作树命名及提交信息规范，适用于 GitHub 与 GitLab 项目，用于创建分支和命名工作树等场景。
- 必须用
composer config --global github-oauth.github.com <token></token>，少一个字符、多一个空格都不行 - 验证是否真启用：运行
composer install -v，日志里出现Using GitHub token from configuration才算成功 - 单独测试 token 是否有效：
curl -H "Authorization: token <your_token>" https://api.github.com/rate_limit</your_token>，返回的rate.limit应为5000，不是60 - 公司代理若过滤或剥离
Authorization请求头，token 根本发不出去——此时只能换网络或联系运维放行
Git 凭证更新后 Composer 仍失败？注意缓存和协议混用
很多人清完 Git 凭据、重配了 Composer token，但 composer install 还报错，问题常出在“协议混用”和“缓存残留”上。
- 清除 Composer 缓存：
composer clear-cache，或直接删掉~/.composer/cache目录 - 检查
composer.json里的repositories地址：HTTPS 和 SSH 不能混用；如果用了git@github.com:user/repo.git，就别指望github-oauth生效 - 临时绕过问题：加
--prefer-dist参数强制下载 ZIP 包（跳过git clone），能快速验证是不是纯 Git 凭证问题 - 最隐蔽的坑：项目里存在破损的
vendor/{package}/.git目录（比如上次克隆中断），Composer 会尝试复用它并失败；删掉整个vendor重来更干净
真正麻烦的从来不是配错哪一行，而是多个认证层（Git credential helper、Composer auth.json、GitHub API token、SSH agent）各自独立又相互影响。每次出问题，先盯住 composer install -v 输出里第一个失败点，它几乎总在告诉你：到底是 git 拒了，还是 curl 被限了，还是 json 解析崩了。
