“failed to download”错误主因是Packagist官方源国内访问不稳定，导致DNS慢、TLS超时或CDN返回503/504；403多因GitHub API限流而非权限问题，cURL 7或timeout则属网络连通性问题。
Composer install/update 报错 “failed to download” 是什么情况
这通常不是你本地网络完全断了，而是 Composer 默认的 Packagist 镜像（https://packagist.org）在国内访问不稳定，DNS 解析慢、TLS 握手超时、或 CDN 节点返回 503/504，导致 composer install 或 composer update 卡在下载包阶段，报类似这样的错误：
Failed to download monolog/monolog from dist: The "https://api.github.com/repos/Seldaek/monolog/zipball/..." file could not be downloaded (HTTP/2 403)
注意：403 不一定是权限问题，更可能是 GitHub API 限流 + 镜像未缓存导致的级联失败；而 000、cURL error 7、Operation timed out 则大概率是网络连通性问题。
切换国内镜像源的三种可靠方式（按推荐顺序）
优先用全局配置，避免每个项目重复操作；若项目有特殊要求（比如必须走官方源测试），再局部覆盖。
-
全局替换（推荐）：运行
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（阿里云）或composer config -g repo.packagist composer https://packagist.phpcomposer.com（已停用，不建议）；目前稳定可用的是清华、腾讯、阿里三选一 -
仅当前项目生效：进项目根目录，执行
composer config repo.packagist composer https://mirrors.tuna.tsinghua.edu.cn/composer/（无需-g） -
临时指定（调试用）：加
--repository-url参数，例如composer update --repository-url https://mirrors.cloud.tencent.com/composer/
镜像地址别手敲，直接复制官网最新链接——清华镜像首页明确标注“已支持 HTTPS + HTTP/2”，阿里镜像对私有 GitLab 仓库兼容更好；腾讯镜像在华南地区延迟略低。
为什么换源后还是 failed to download？检查这几个点
换源只是解决 Packagist 元数据拉取，但很多包实际从 GitHub/GitLab/Bitbucket 下载 ZIP 或克隆 Git，这部分不受 Composer 镜像控制。
- 确认是否启用了
fxp/composer-asset-plugin（老项目常见）：它会绕过镜像直连 GitHub，建议升级到composer/installers+yiisoft/yii2-composer等现代方案 - 检查
composer.json中是否有硬编码的repositories，比如写了"type": "vcs", "url": "https://github.com/xxx"，这种会跳过镜像，改用"type": "package"或删掉自定义仓库 - 某些包被作者设为
"archive": {"exclude": ["tests"]}，但镜像未同步该字段，可临时加"dist": {"url": "..."}手动指定 ZIP 地址（不推荐长期用） - 运行
composer diag查看 DNS、HTTPS、CA 证书是否正常；如果提示curl error 60，需更新 CA 包或加composer config -g cafile /path/to/cacert.pem
附：验证镜像是否生效 & 快速回退方法
执行 composer config --list | grep repo.packagist，输出应为类似 repo.packagist composer [https://mirrors.tuna.tsinghua.edu.cn/composer/]；若显示 repo.packagist { ... } 带大括号，说明你之前手动写过复杂仓库配置，可能覆盖了镜像设置。
想快速恢复官方源，运行 composer config -g --unset repo.packagist（全局）或 composer config --unset repo.packagist（当前项目）即可。注意：不要删整个 ~/.composer/config.json，里面可能还有 auth tokens 等关键配置。
真正卡住的往往不是换源本身，而是 vcs 类型仓库、GitHub Token 权限、或公司防火墙拦截了 zipball 域名（如 codeload.github.com）——这些得单独处理，镜像解决不了。
