“failed to clone”错误根源在于composer调用系统git时协议协商失败，常见于企业封ssh端口、https被拦截或git配置不匹配；git clone成功不代表composer走相同路径，因其会按源注册规则自动重写url为ssh地址，需通过composer config -g github-protocols ["https"]强制降级并清缓存重装。
报错“Failed to clone”不是 Composer 坏了，而是它调用系统 git 时卡在协议协商上——常见于企业网络封 SSH 端口、HTTPS 被中间设备拦截，或 Git 配置没对齐远程仓库要求。
为什么 git clone 成功但 Composer 却失败？
你手动跑 git clone https://gitee.com/xxx/yyy.git 能通，不代表 Composer 也会走这条路。Composer 会根据包的 source 地址类型（SSH 或 HTTPS）和本地配置动态决定协议，且优先尝试 SSH（哪怕你复制的是 HTTPS 地址）。典型表现是：
- 终端里
git clone没问题，但composer install卡在Cloning into 'xxx'...后无响应 - 错误日志里出现
Permission denied (publickey)，但你根本没配 SSH 密钥 -
composer diagnose显示Git binary found at /usr/bin/git，却没提协议偏好
根本原因是 Composer 内部做了 URL 归一化：它会把 Packagist 上注册的 HTTPS 地址，按平台规则重写为 SSH 地址（比如 https://github.com/symfony/console → git@github.com:symfony/console.git），再调用 git clone。这个行为不受你手动复制的地址影响。
强制 Composer 使用 HTTPS 协议的实操步骤
别碰 composer config -g github-protocols https —— 这个配置只对 GitHub 生效，且 Composer 2.2+ 已弃用。真正生效的是全局 URL 重写规则：
- 运行
composer config -g gitlab-domains []（清空 GitLab 域名白名单，避免干扰） - 添加 HTTPS 强制映射：
composer config -g github-protocols ["https"] - 关键一步：设置通用重写规则，覆盖所有域名：
composer config -g repo.packagist composer https://packagist.org（仅用于触发协议降级逻辑，非镜像配置） - 验证是否生效：执行
composer config -g --list | grep -A3 protocols，输出应含github-protocols和值["https"]
注意：改完必须删掉 vendor/ 和 composer.lock，再跑 composer install --prefer-source，否则旧 lock 文件仍会沿用之前解析出的 SSH 地址。
SSH 方式失效时的快速兜底方案
如果公司网络明确禁用了 22 端口，或者 CI 环境里无法部署 SSH 密钥，硬切 SSH 只会让问题更糟。此时最稳的解法是绕过 Git 克隆本身：
- 用
--prefer-dist强制走 ZIP 包下载：composer install --prefer-dist - 确保目标包在 Packagist 上发布了 tagged 版本（dev 分支或未打 tag 的 commit 无法生成 dist 包）
- 若依赖里混有私有 VCS 包，需在
composer.json的repositories字段中显式指定"type": "package"+"dist"描述，而非"type": "vcs"
这个开关不改变协议，而是跳过 git clone 整个环节——对绝大多数公开包有效，且速度更快、失败率更低。
容易被忽略的 Git 全局配置陷阱
即使协议切换成功，git clone 仍可能因缺失基础元数据拒绝操作，尤其在 Docker 或最小化 Linux 镜像里：
-
git config --global user.name "a"和git config --global user.email "a@a"必须存在，否则某些 Git 版本（如 2.30+）会直接退出 - 检查
git config --global http.sslVersion是否为tlsv1.2；CentOS 7 默认是tlsv1.0，会导致 HTTPS 克隆握手失败 - 确认
git config --global core.autocrlf不是true（Windows 默认值），它会在克隆时触发换行符转换，偶发卡住
这些配置不会出现在 composer diagnose 里，但只要缺一个，git clone 就会在静默中失败——错误日志里只显示 “Cloning failed”，连具体原因都不吐。
