国内PHP开发者必须配置Composer镜像，因packagist.org受DNS污染与TLS阻塞而刚性不可达；composer config -g repo.packagist需严格满足键名、type值、URL末尾斜杠三条件，否则静默回退官方源；项目级配置更可靠，且换源后须清缓存并重生成composer.lock。
国内 PHP 开发者不用 Composer 镜像，等于没装 Composer——不是慢，是根本走不通。packagist.org 在国内基本不可用：TLS 握手卡、首字节延迟高、503/403 频发，和你本地网络无关，是物理链路与策略限制共同导致的。
composer config -g repo.packagist 命令总不生效？检查这三处硬伤
90% 的“配了还是慢”问题，根源在命令写错但不报错，静默 fallback 回官方源：
-
repo.packagist不能多一个s（repos.packagist是无效键名） - 命令中必须带
composer这个 type 值，缺了它 Composer 2.x 就不认 -
URL必须是 HTTPS 且末尾带/：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会导致路径拼接错误，返回 404）
验证是否真写进去了：运行 composer config -g repo.packagist，输出必须是完整 JSON 或至少是镜像 URL 字符串；空、null、或仍显示 https://packagist.org，说明没生效。
项目级配置比全局更可靠，尤其 CI 和宝塔环境
全局配置写在 ~/.composer/config.json，但宝塔后台以 www 用户运行、CI 容器用 runner 用户，它们根本读不到你 root 或当前用户的配置。
立即学习“PHP免费学习笔记（深入）”；
进项目根目录（含 composer.json），执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
这条命令会自动向 composer.json 的 repositories 字段安全追加，不覆盖已有私有源。优势明显：
- 配置随代码提交，新人
git clone后直接composer install - Docker 构建、GitHub Actions 等 CI 场景无需额外 setup 步骤
- 避免多用户/多角色下配置错位（比如你在终端配了，但宝塔部署时用的是 www 用户）
注意：如果 composer.json 中 repositories 是空对象 {}，命令会自动转为数组并插入；如果是数组格式 []，命令可能报错，需先手动改成对象再运行。
换镜像后 composer install 报 hash 不匹配？删 vendor 和 lock 再来
镜像只加速下载，不改变包内容，但元数据同步存在缓存或延迟。旧 composer.lock 记录的是官方源的哈希值，和镜像返回的元数据不一致，必然报错：
- 删除项目根目录下的
vendor/目录和composer.lock文件 - 运行
composer install --no-cache（强制跳过本地缓存，从镜像重新拉取元数据） - 别试图保留旧
composer.lock——它已失效，重生成才是正解
顺带一提：composer update 卡在 Resolving dependencies 和镜像无关，那是本地 PHP 内存、Xdebug、platform 版本配置等问题，得另查。
怎么确认真走镜像？别信输出，看 -vvv 日志里的域名
光看 composer config -g repo.packagist 输出还不够。最直接证据是日志里实际请求的域名：
composer show laravel/framework -vvv 2>&1 | grep "Downloading"
如果看到类似 Downloading https://mirrors.aliyun.com/composer/... 或 Downloading https://mirrors.tuna.tsinghua.edu.cn/composer/...，才算真正生效。
临时验证某个镜像是否可用，也可用 --repository-url 参数绕过所有配置：
composer create-project topthink/think tp-demo --repository-url=https://mirrors.tuna.tsinghua.edu.cn/composer/ -vvv
这种写法优先级最高，适合排查、CI 脚本隔离或团队未统一前的单次测试。
