结论：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 三要素缺一不可——键名必须为 repo.packagist（单数）、type 值必须显式写 composer、url 末尾必须带 /，否则静默失效且无报错。
直接说结论：用 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 这条命令，三要素缺一不可——repo.packagist（单数）、composer（type 值）、URL 末尾必须带 /；否则静默失效，连报错都没有。
为什么 composer config -g repo.packagist 总不生效
命令跑完没提示错误，但 composer install 依然卡在 Loading composer repositories 或 Downloading https://packagist.org/packages.json，基本可以断定配置根本没写进去。
-
repo.packagist是唯一合法键名：写成repos.packagist、repositories、mirror都会被 Composer 完全忽略 - 中间的
composer是强制 type 值，不是可选参数，漏掉就 fallback 到官方源 - URL 必须以
/结尾：写成https://mirrors.aliyun.com/composer会导致路径拼接为/composerpackages.json，直接 404 - 验证是否真写入：运行
composer config -g repo.packagist，输出必须是完整 JSON 对象，例如{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}；如果为空、null或报Key not found，说明失败
全局配置 vs 项目级配置，到底该用哪个
全局配置省事，但项目级配置才是生产环境真正可控的选择。
- 全局配置写入用户目录下的
config.json（路径由composer config --global --list确认），只对当前用户生效；CI/CD、宝塔、GitHub Actions 里实际运行的可能是www、runner等非登录用户，根本读不到你的全局配置 - 项目级配置执行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加-g），会自动在项目composer.json的repositories字段下添加"packagist"子项，随代码一起提交，团队和流水线行为一致 - 注意前提：项目
composer.json中的"repositories"必须是对象格式（如"repositories": {}），如果是数组（"repositories": []）会报错，需先手动改为对象
换源后还是卡住？缓存和 lock 文件才是关键
镜像只加速元数据下载，但 Composer 默认优先复用本地缓存和 composer.lock 中记录的旧地址。哪怕你刚配好镜像，它也可能还在往 packagist.org 发请求。
- 必须执行
composer clear-cache清空所有缓存；也可手动删目录：~/.composer/cache/repo/https---mirrors-aliyun-com-composer/（Linux/macOS）或对应 Windows 路径 -
composer.lock里存着旧的 dist URL，不刷新就不会走镜像；最稳妥做法是删掉vendor/和composer.lock，再跑composer install - 轻量替代方案：
composer update --lock，它会重新解析依赖并更新 lock 文件中的 URL，不重装包 - 验证是否真走镜像：运行
composer install -vvv，搜索日志中GET行的域名，确认是mirrors.aliyun.com而非packagist.org
Composer 2.2+ 用户特别注意：键名已变更
如果你用的是 Composer 2.2 或更高版本，repo.packagist 已被弃用，继续用会静默忽略——必须改用新键名 repositories.packagist.org。
- 正确命令：
composer config -g repositories.packagist.org '{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}' - 注意：JSON 值必须用双引号包裹，且整个字符串要加单引号（防止 shell 解析）
- 验证命令：
composer config -g repositories.packagist.org，输出应为完整 JSON - 别信
composer diagnose输出里的Repo packagist.org:地址——它可能显示旧值；真实生效看composer install -vvv日志中的实际请求域名
最容易被忽略的其实是缓存清理和 lock 文件刷新，而不是镜像地址本身。很多人反复改 URL 却不删缓存，结果永远卡在同一个地方。
