全局配置一条命令就能生效，但必须严格满足三要素：-g参数不可省略、键名为repo.packagist（单数）、type值显式写为composer且URL须为HTTPS并以/结尾。
直接上手配镜像，不是为了“学 Composer”，而是为了不让 composer install 卡在 Loading composer repositories 一动不动——这一步没走通，后面所有依赖管理都只是纸上谈兵。
composer config -g repo.packagist 必须写对三处
这条命令看着简单，但错一个字符就静默失效，且不报错：
-
-g不能省：缺了就只改当前项目composer.json，换目录就失效 -
repo.packagist是固定键名（注意是repo单数，不是repos） -
composer是type值，必须显式写出，不是注释或可选参数
正确写法（以阿里云为例）：
composer config -g repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9
常见错误写法：
-
composer config -g repos.packagist composer <a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>（多一个 s） -
composer config -g repo.packagist <a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>（漏掉composer类型） -
composer config -g repo.packagist composer <a href="https://www.php.cn/link/9d3c8a28bff4572cbe0221dcc6b489cc">https://www.php.cn/link/9d3c8a28bff4572cbe0221dcc6b489cc</a>（HTTP 被 Composer 2.0+ 拒绝）
验证镜像是否真生效，别信“命令执行成功”
执行完命令，立刻验证，而不是直接跑 composer install：
-
运行
composer config -g repo.packagist，输出必须是完整 JSON 对象，例如：{"type": "composer", "url": "https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9"}如果返回空、null、报错，或只输出 URL 字符串（旧版行为），说明配置失败 -
再跑一次
composer install -vvv，最后几行要看到类似：Reading packages.json from cache at /https---mirrors-aliyun-com-composer/
如果还出现packagist.org/packages.json，就是 fallback 到官方源了
项目级配置比全局更可靠，尤其适合团队和 CI
全局配置在宝塔、Docker、GitHub Actions 等环境里常因用户权限失效（比如 www 用户读不到 root 的 ~/.composer/config.json），项目级配置写进 composer.json，可提交 Git，所有人行为一致：
- 进项目根目录，运行（注意不带
-g）：composer config repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9
- 它会自动在
composer.json顶层写入"repositories"字段，key 固定为"packagist" - 如果项目已有
"repositories": []数组结构，该命令会追加而非覆盖；如果手动编辑，务必保留 JSON 合法性（引号、逗号、括号） - 改完建议删掉
vendor/和composer.lock，再跑composer install，避免 hash 校验失败
换源后仍卡在 Resolving dependencies？和镜像无关
镜像只加速元数据拉取和 ZIP 包下载，不解决依赖解析慢的问题。如果你发现 composer update 卡在 Resolving dependencies 几十秒甚至几分钟：
- 检查
composer.json中的 PHP 版本约束是否太宽，比如"php": "^7.4 || ^8.0" - 避免大量使用未锁定的
dev-分支（如"monolog/monolog": "dev-main"） -
require-dev里塞太多工具包也会拖慢解析速度
这些和镜像源完全无关，调错地方只会浪费时间。
