Composer下载失败主因是请求拦截、源不可达或证书/代理配置错误，需通过错误URL、状态码、composer diagnose及curl测试精准定位网络、SSL、代理或GitHub权限等具体层级问题。
Composer 下载失败（failed to download）绝大多数时候不是网络连不上，而是请求被拦截、源不可达或证书/代理配置错位。直接换镜像源或关 TLS 验证往往治标不治本，得先分清是哪一层断的。
为什么 composer install 或 composer update 报 failed to download
这个错误本质是 Composer 在尝试从仓库（默认 https://packagist.org）拉取 ZIP 包或 dist 归档时 HTTP 请求失败。常见触发点：
- 系统级网络策略拦截了
https://api.github.com或https://codeload.github.com—— 因为很多包的dist实际托管在 GitHub - PHP 的
openssl扩展缺失或 CA 证书路径未正确配置，导致 HTTPS 握手失败（尤其 Windows + WAMP/XAMPP 或 macOS Homebrew PHP） - 公司/校园网络启用了透明代理，但 Composer 没配
http-proxy或配了却没设no-proxy绕过内网域名 - 镜像源地址写错，比如把
https://mirrors.aliyun.com/composer/误写成http://（HTTP 会重定向，但某些环境下重定向失败） -
composer.json里某个包指定了私有 Git URL（如git@github.com:xxx/yyy.git），但本地没配 SSH key 或 GitHub token 权限不足
快速定位是哪类失败：看完整错误行和 URL
别只盯着 failed to download，重点看它前面那行实际请求的 URL 和状态码（如果有）。例如：
Downloading https://api.github.com/repos/symfony/console/zipball/6a12d95f8e7b47c0a8e3e1c98877e62b5f99580f Failed to download symfony/console from dist: The "https://api.github.com/repos/symfony/console/zipball/6a12d95f8e7b47c0a8e3e1c98877e62b5f99580f" file could not be downloaded (HTTP/2 403)
这里 HTTP/2 403 明确指向 GitHub API 限流或 token 权限问题；如果是 cURL error 60 或 SSL certificate problem，就是证书问题；如果是超时（cURL error 28），才优先考虑网络或镜像。
- 运行
composer diagnose，它会检查网络连通性、CA 路径、proxy 设置等，输出比报错更早的线索 - 加
-v参数重试：composer update -v，能看到每一步 curl 请求细节 - 手动用
curl -I https://packagist.org/packages.json测试基础连通性，排除 DNS 或全站封锁
按原因对症改配置，不是盲目换源
换国内镜像（如阿里云、腾讯云）能解决部分问题，但若根本原因是 SSL 或代理，换源只是把失败从 packagist 切到镜像站而已。
- 证书问题：执行
php -r "print_r(openssl_get_cert_locations());"看default_cert_file路径是否存在；若不存在或为空，手动下载 Mozilla CA 包，再在php.ini中指定：openssl.cafile=/path/to/cacert.pem - 代理问题：用
composer config -g http-proxy http://user:pass@proxy:port配代理；如果内网有私有 Packagist，加composer config -g no-proxy "internal.example.com,192.168.0.0/16" - GitHub 限流：登录 GitHub → Settings → Developer settings → Personal access tokens → 生成一个带
public_repo权限的 token，再运行composer config -g github-oauth.github.com <your_token> - 仅临时绕过 SSL（不推荐长期用）：
composer config -g secure-http false，并确保源是http://协议（但多数镜像已不支持 HTTP）
私有包或 Git 依赖下载失败的特殊处理
当错误 URL 是 git://、ssh:// 或 https://github.com/xxx/yyy.git 时，failed to download 其实是 Git 克隆失败，和 Composer 自身无关。
- SSH 地址失败？确认
ssh -T git@github.com能通，且~/.ssh/config里没写错 Host 别名 - HTTPS Git 地址失败？可能需要 GitHub token：
composer config -g github-oauth.github.com <token>，否则 2023 年后 GitHub 已禁用密码认证 - GitLab 私有仓库？确保
composer.json中的repositories类型设为vcs，且 URL 可被git clone直接拉取 - 想强制走 ZIP 下载而非 Git 克隆？在
composer.json加"preferred-install": {"*": "dist"}，并确认包有dist配置
最常被忽略的是：错误看起来像网络问题，实际是 PHP 的 OpenSSL 扩展没加载，或者 php.ini 里 allow_url_fopen 被关了。跑一遍 php --ini 和 php -m | grep openssl 比反复换源快得多。
