使用Composer中文镜像，让PHP安装过程更流畅！-composer-PHP中文网

composer中文镜像失效的三大硬性要求是：键名必须为repo.packagist（非repos）、type值必须为composer（不可省略或替换）、url须为https且末尾带斜杠；任一错误均导致静默直连官方源。

使用composer中文镜像，让php安装过程更流畅！

配了中文镜像还卡在 Downloading 或 Loading composer repositories，大概率不是网络问题，而是镜像根本没生效——三处硬性要求错一个就静默失效。

这条命令看着简单，但漏掉任意一项都会让 Composer 继续直连 packagist.org，且不报错：

repo.packagist 是固定键名，不能写成 repos.packagist（多一个 s 就失效）
中间的 composer 是 type 值，不是可选参数，也不能省略或替换成其他字符串
URL 必须是 HTTPS 且末尾带斜杠：https://mirrors.aliyun.com/composer/ ✅，https://mirrors.aliyun.com/composer ❌（少斜杠会拼出 404 路径）

正确写法：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

执行完配置命令，必须立刻验证输出是否符合预期：

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

运行 composer config -g repo.packagist
输出必须是完整 JSON 对象，例如：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
如果输出为空、null、https://packagist.org，说明配置失败，composer install 仍在走海外源

CI 或宝塔面板中尤其要注意：你在终端用 root 配的，但构建脚本以 www 或 runner 用户运行，读的是各自家目录下的 .composer/config.json。

镜像只加速下载，不兼容旧锁文件里的哈希值：

旧 composer.lock 记录的是 packagist.org 的包签名，和镜像返回的元数据不一致
直接删掉 vendor/ 和 composer.lock，再跑 composer install
别保留旧 composer.lock —— 它会反复 fallback 到官方源校验，卡在 TLS 握手或 DNS 解析
如果项目已有 "repositories": []（数组格式），composer config repo.packagist ... 会报错；得先手动改成对象 "repositories": {} 再执行

全局配置容易被覆盖或权限错位，而写进 composer.json 的配置可 Git 提交、行为一致：

进项目根目录，运行 composer config repo.packagist composer https://mirrors.tuna.tsinghua.edu.cn/composer/（去掉 -g）
该命令会安全追加到 repositories 字段，不覆盖已有私有源
Docker 或 CI 构建时，~/.composer 是干净的，但 composer.json 每次都会被读取
别手动写 "packagist.org": false —— 这会彻底关掉官方源，镜像临时不可用时直接失败

真正卡点不在下载速度，而在元数据同步一致性；哪怕镜像 URL 正确，只要 composer.lock 和当前镜像元数据不匹配，就会反复失败。