直接结论：换镜像必须配对才生效，90%问题源于配置写法错误或作用域错位；正确命令为composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，需严格满足键名repo.packagist、type值composer、URL以/结尾三要素，缺一即静默失效。
直接结论：换镜像不是“配了就快”，而是“配对才生效”——90% 的卡顿、失败、不走镜像，问题不在网络，而在配置写法或作用域错位。
composer config -g repo.packagist 命令必须严格满足三要素
这条命令看似简单，但漏掉任意一个细节就会静默失效，且不报错：
-
repo.packagist是唯一合法键名（注意是repo单数，不是repos；也不能写成packagist.org） -
composer是type值，不是可选参数——省略后 Composer 2.0+ 会 fallback 到官方源 -
https://mirrors.aliyun.com/composer/必须用 HTTPS，且末尾斜杠/不能少（少斜杠会拼出/composerpackages.json导致 404）
正确写法：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
验证是否生效：composer config -g repo.packagist，应输出类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。如果返回空、null 或报 Key 不存在，说明没写进去。
项目级配置比全局更可靠，尤其适合团队和 CI
全局配置写在 ~/.composer/config.json，但「谁在跑命令」决定读哪个文件：
- 你在终端用
root执行了composer config -g，但宝塔后台以www用户运行，它读的是/home/www/.composer/config.json，根本看不到你的配置 - CI 脚本里用了
sudo composer config -g，结果写进了root配置，而构建容器里实际用的是runner用户，照样失效 - 项目已存在
"repositories": []（数组格式），composer config repo.packagist ...会直接报错；需先手动改成"repositories": {}（空对象）再运行
推荐做法：进项目根目录，运行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/。它会安全追加到 composer.json 的 repositories 字段，不覆盖已有私有源——前提是原 repositories 是对象结构。
立即学习“PHP免费学习笔记（深入）”；
换源后仍卡在 “Loading composer repositories”？先查配置层级
这不是镜像没响应，而是请求根本没发过去。常见原因：
- 项目级
repositories配置覆盖了全局设置（项目级优先级更高） -
composer.json里写了"packagist.org": false或"packagist": false，彻底关源 - 镜像服务本身不可达（比如阿里云镜像临时维护）
排查步骤：
- 运行
composer config -g repo.packagist和composer config repo.packagist（无-g），分别看哪一层在起作用 - 检查
composer.json是否存在"repositories"字段，尤其留意有没有禁用语句 - 临时验证镜像是否可达：
curl -I https://mirrors.aliyun.com/composer/packages.json，返回200 OK才算服务正常
换源不解决 Resolving dependencies 卡顿
镜像只加速包下载，不参与依赖解析。如果你发现 composer update 卡在 Resolving dependencies 几十秒甚至几分钟，基本和镜像无关：
-
php版本约束太宽，例如"php": "^7.4 || ^8.0"，导致解析器穷举大量组合 -
require-dev里塞了太多未锁定版本的工具链（如phpunit、phpcs） - 本地 PHP 版本与
composer.json中声明的不匹配，触发 fallback 行为
这类问题换任何镜像都无效，得收紧约束、锁定 dev 包版本，或升级 Composer 到 2.9.6（该版本优化了依赖解析算法）。
最常被忽略的点：改完镜像后，vendor/ 和 composer.lock 里的 hash 可能和新镜像元数据不一致，必须删掉重装；还有人手写 "packagist": false 后才发现基础包全拉不到——这种写法等于主动断网，不是加速，是自锁。
