如何在Composer中排除损坏的中文镜像源？

排查 Composer 卡死在 "downloading" 的根本原因：中文镜像源返回乱码或空响应

很多开发者遇到 composer install 卡在“downloading”阶段，第一反应是网络慢或 PHP 版本问题。但实际上，更常见的原因是某些已下线的第三方中文镜像源（比如 phpcomposer.com 之类的老域名）返回了非标准的 HTTP 响应——可能是带 BOM 的 UTF-8 文本、HTML 错误页，甚至是一堆二进制乱码。Composer 在解析这些响应中的 JSON 时直接崩溃，表现就是卡住，或者抛出一个让人摸不着头脑的错误：file_put_contents(): Only variables should be passed by reference。这不是权限问题，而是镜像源数据本身坏了。

怎么验证？最简单的方法是运行 composer diagnose。如果输出里有 Warning: Accessing xxx.com via http://, which is deprecated 或者 JSON decode error，那基本就锁定是镜像源的问题了。更直接的办法是手动用 curl 访问对应包的 packages.json 地址，看返回的是不是一段合法 JSON。

• 临时绕过：执行 composer install --no-plugins -vvv，观察最后请求的 URL 是不是来自一个类似 https://packagist.phpcomposer.com 这种“看起来眼熟”的域名。
• 检查全局配置：运行 composer config -g repo.packagist，看里面是不是写入了已经失效的源地址，比如 https://packagist.phpcomposer.com 或 https://packagist.lara vel-china.org。
• 别被域名“看起来像中文”骗了——有些二级域名早已被回收，HTTP 302 跳转到一些你不知道的页面去了。

正确切换回官方源或可信镜像

Composer 1.x 和 2.x 对镜像的配置方式是一样的，但关键点在于：必须用 composer config 命令显式覆盖全局配置。只改项目里的 composer.json 里的 repositories 根本没用——那只是当前项目的局部配置，而损坏的源往往藏在全局配置文件里。

• 恢复官方源（最稳妥）：composer config -g repo.packagist https://packagist.org
• 切换到阿里云镜像（推荐）：composer config -g repo.packagist https://mirrors.aliyun.com/composer/
• 切换到腾讯云镜像：composer config -g repo.packagist https://mirrors.cloud.tencent.com/composer/
• 如果公司内网有私有源，一定要确保它的 packages.json 能用 curl -I 返回 200 OK，并且 Content-Type 是 application/json。

改完配置之后，删掉项目根目录下的 vendor/ 和 composer.lock，再重新运行 composer install。这个步骤不能省——如果不重建 lock 文件，它可能还在引用旧的损坏元数据，等于白费功夫。

为什么 vendor/bin/composer 自动更新后依然走坏源？

这里有一个常见的坑：Composer 的配置是分层的——命令行参数 > 项目级 composer.json > 全局 config.json。就算你把 composer.phar 更新到最新版，只要全局配置里的镜像地址没改，它依然会去读取那个坏源。更隐蔽的情况是：某些 IDE（比如 PHPStorm）或者 CI 工具会缓存 Composer 配置，或者在子 shell 里加载了错误的 HOME 环境变量，导致 composer config -g 实际写到了非预期的路径下。

• 想搞清楚真实全局配置路径：运行 composer config -g --list，看第一行 home 指向哪里。
• 强制使用一个临时路径来测试：COMPOSER_HOME=/tmp/composer-test composer config -g repo.packagist https://packagist.org，这样可以隔离问题。
• 在 CI 环境里，别在 composer self-update 后立刻 install，最好先插一句 composer config -g --list | grep repo 确认配置已生效。

composer create-project 拉取失败：模板包元数据损坏

这个命令默认从 packagist.org 拉取元数据，但如果本地的全局镜像已经损坏，它会尝试从坏镜像下载 https://xxx.com/packages.json。很可能那个地址返回的是一个 404 的 HTML 页面，导致 Composer 解析失败并无声退出。现象就是终端停在 Installing dependencies from lock file 后一动不动，ps aux | grep curl 也看不到进程——实际是 Composer 在内存里反复试图 decode 一段 HTML 字符串。

• 绕过方法：加 --repository-url=https://packagist.org 参数，强制走官方源：composer create-project lara vel/lara vel test --repository-url=https://packagist.org
• 预防措施：在所有自动化脚本里，执行 composer create-project 之前统一加一句 composer config -g repo.packagist https://packagist.org。
• 注意：有些老教程教的是 composer config repo.packagist ...（缺了 -g），那只改当前目录，对 create-project 完全无效。

真正麻烦的其实不是换源这个动作本身，而是损坏镜像留下的缓存文件和 lock 文件残留——它们不会自动失效，必须手动清理干净，才能彻底断开和坏源的关联。