如何解决Composer更新依赖卡住及国内镜像配置故障？

本文共计903个文字，预计阅读时间需要4分钟。

使用Composer更新依赖时，如果遇到90%以上是镜像配置未生效或被覆盖的问题，通常不是由于网络本体问题造成的。以下是简短的解决方案：

composer config -g repo.packagist 是不是真在用国内镜像

很多人以为执行过 composer config -g repo.packagist https://mirrors.aliyun.com/composer/ 就万事大吉，其实这个设置可能被项目级配置、环境变量或 Composer 插件覆盖。

• 运行 composer config -g repo.packagist 确认全局配置值（注意末尾不能带斜杠，否则部分版本会 404）
• 进到项目目录后，再运行 composer config repo.packagist —— 如果有输出，说明项目级配置优先级更高，它会覆盖全局设置
• 检查是否存在 COMPOSER_REPO_PACKAGIST 环境变量：echo $COMPOSER_REPO_PACKAGIST，它比所有 config 都高

阿里云 / 清华镜像地址写法差异导致 404 或重定向失败

不同镜像源对路径和协议要求严格，写错一个字符就会让 Composer 卡在 HTTP 重定向或超时。

• 阿里云正确地址是：https://mirrors.aliyun.com/composer/（结尾必须有斜杠，且必须是 https）
• 清华镜像正确地址是：https://packagist.phpcomposer.com（注意不是 https://mirrors.tuna.tsinghua.edu.cn/composer/，后者是旧地址，已停用）
• 如果用了 http:// 开头，某些 PHP cURL 版本会拒绝连接（尤其 macOS 自带 PHP）

更新时卡在 “Loading composer repositories with package information…”

这行日志卡住超过 30 秒，基本可断定是 DNS 解析失败或镜像域名不可达，而不是下载慢。

• 手动测试镜像连通性：curl -I https://mirrors.aliyun.com/composer/packages.json，看是否返回 200 OK
• 如果返回 302 但没内容，可能是 CDN 节点异常，换清华源试试
• 某些企业网络会拦截 composer install 的 User-Agent，临时加 -v 参数看详细请求头，确认是否被 WAF 拦截
• PHP 的 openssl.cafile 配置错误也会导致 HTTPS 握手失败，表现为无响应；可临时加 export COMPOSER_DISABLE_TLS=1 测试（仅调试用，勿长期开启）

插件或自定义脚本偷偷改了仓库配置

有些团队用的私有包管理平台（如 Satis、Private Packagist）或 CI/CD 脚本会在 composer install 前自动注入仓库配置，覆盖你设的镜像。

• 运行 composer show -p 查看当前实际生效的仓库列表
• 检查项目根目录是否有 composer.json 里写了 "repositories" 字段，尤其是 type 为 composer 的条目
• 搜索项目中是否含 Plugin::activate 或 RepositoryManager::addRepository 相关代码（常见于定制化插件）

最麻烦的情况是：镜像地址没错、网络通、配置也生效，但某个依赖包的 dist URL 仍指向 packagist.org —— 这是因为包元数据里硬编码了原始下载地址，镜像只代理 metadata，不代理 dist 文件。这时候得靠 composer config -g github-protocols https 和确保 git 配置走 HTTPS，否则 git clone 阶段照样卡住。