直接换镜像源并清缓存是解决国内Composer下载失败的最快最稳方案；80%问题源于直连packagist.org受DNS/TLS干扰，而非网速慢；必须用composer config -g repo.packagist验证配置是否生效，输出须为完整JSON，URL须HTTPS且以/结尾，中科大和腾讯云镜像是当前唯一稳定可用的两个源。
直接换镜像源 + 清缓存，比调 timeout 更快更稳。国内用户 80% 的“下载失败”根本不是网速问题，而是直连 packagist.org 被干扰或 DNS/TLS 不稳定。
确认当前用的是哪个镜像源
别信自己配过就生效了——Composer 配置极易静默失效。运行 composer config -g repo.packagist，输出必须是完整 JSON，例如：{"type": "composer", "url": "https://packagist.mirrors.ustc.edu.cn/"}。空、null、报错或显示 https://packagist.org，说明没配对。
- 常见拼写错误：
repos.packagist（多一个 s）、repositories.packagist.org（套娃式错误） - URL 必须以
/结尾，https://mirrors.aliyun.com/composer❌ 会拼出/composerpackages.json导致 404 - 项目级
composer.json中若含"repositories"字段（哪怕只是[]），全局配置会被完全忽略
换哪个镜像源现在还可用
阿里云、Laravel China、phpcomposer 镜像均已下线（2026 年实测）。目前稳定可用的只剩两个：
- 中科大镜像：
https://packagist.mirrors.ustc.edu.cn/（同步快，HTTP/2 支持好） - 腾讯镜像：
https://mirrors.cloud.tencent.com/composer/（华南延迟低，私有源兼容强）
配置命令：composer config -g repo.packagist composer https://packagist.mirrors.ustc.edu.cn/
配完立刻执行 composer clear-cache，否则仍可能从损坏缓存读取旧包。
“Content-Length mismatch” 或 “Failed to extract” 怎么办
这不是网络慢，是缓存里存了一个只写了一半的 ZIP 文件，Composer 拿它校验长度时自然失败。重试、加 timeout 都没用。
- 第一步永远是
composer clear-cache，确认~/.composer/cache/files/目录为空 - 第二步删掉
vendor/autoload.php和vendor/composer/，再跑composer dump-autoload→composer install - 如果锁文件（
composer.lock）里记录的是 packagist.org 的 dist URL，得连vendor/和composer.lock一起删，再重装
timeout 参数该不该调、怎么调
只在换镜像 + 清缓存后仍失败时才动 timeout。且必须同时设两个：
-
process-timeout：管整个安装流程总耗时（依赖解析、解压、生成 autoload 等），默认 300 秒，可设为1800 -
http-basic-timeout（Composer 2.2+）：管单次 HTTP 请求（DNS、TLS、首字节、body 传输），默认 60 秒太短，国内建议300～600 - 只改一个，大概率还是失败。临时生效：
composer install --timeout=1800 --http-basic-timeout=300
真正麻烦的从来不是“等多久”，而是中断后 vendor/ 里那些看似完整、实则校验失败的残留文件——它们不会报错，但会让后续所有命令反复卡在同一个点。
