根本原因是git clone被阻断（dns污染、超时、ssh失效或防火墙拦截），需先测试连通性，再根据https/ssh可用性切换url格式、配置token或强制--prefer-dist走zip下载。
Composer install卡在 github.com 的 git clone 阶段
根本原因不是 Composer 本身出错，而是 git clone 试图从 github.com 拉取包时被阻断（DNS污染、连接超时、SSH key 失效或企业防火墙拦截）。错误通常表现为：Cloning into '.../vendor/some/package'... 后长时间无响应，或直接报 fatal: unable to access 'https://github.com/...': Failed to connect to github.com port 443。
- 先执行
git ls-remote -h -- https://github.com/composer/composer.git测试基础连通性；失败则确认网络是否能访问 GitHub - 若 HTTPS 不通但 SSH 可用，把
composer.json中的"repositories"里 type=package 或 vcs 的 URL 全部从https://改成git@github.com:格式，并确保本地已配置有效 SSH key（ssh -T git@github.com能返回 Hi xxx!） - 临时绕过 Git，强制走 ZIP 包下载：运行
composer config --global prefer-source false，再加--prefer-dist参数重试
启用 GitHub API Token 后仍提示 rate limit exceeded
Composer 默认每小时最多 60 次未认证 GitHub API 请求。即使设置了 token，若没正确绑定到 Composer 配置，仍会触发限流，表现为：Could not fetch https://api.github.com/...: 403 rate limit exceeded。
- 生成 Personal Access Token 时必须勾选
repo权限（仅public_repo不够，私有库或 fork 依赖会失败） - 设置方式必须用
composer config --global github-oauth.github.com <your_token></your_token>，注意域名是github.com，不是api.github.com - 检查是否被代理或镜像覆盖：运行
composer config --global --list | grep github，确认输出包含github-oauth.github.com且值非空
国内环境推荐的稳定替代方案
不依赖 GitHub 域名解析和直连，本质是换源 —— 把 Packagist.org 的镜像 + GitHub Release ZIP 镜像组合使用，而非简单改 packagist.org 地址。
- 全局启用阿里云镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 同时启用 GitHub ZIP 加速（关键）：
composer config --global github-protocols https（强制走 HTTPS ZIP，避开 git clone） - 若项目含大量私有 repo，建议在
composer.json中显式指定"github-domains": ["github.com"]并配合github-protocols使用，避免协议协商失败
vendor 目录残留导致反复失败
前一次失败的 composer install 可能留下半成品 vendor 子目录（比如只有 autoload.php 没有 composer/installed.php），下次运行时 Composer 会尝试复用，结果校验失败或路径冲突。
- 不要手动删
vendor/autoload.php单个文件 —— 应该整个删掉vendor/目录，再清缓存：composer clear-cache - 检查是否有
composer.lock被修改过：如果 lock 文件里的 commit hash 对应的 GitHub repo 已删或改名，install必然失败，此时需composer update --lock重新解析依赖 - CI 环境下务必加
--no-interaction --no-progress，避免因交互式提示（如 auth token 输入）卡住
实际中，多数人卡在第二步——token 设置了但域名写错，或者用了只读 token。GitHub 限流错误不报具体 token 问题，容易误判为网络问题。
