Composer 2.2+ 镜像配置失效主因是键名、JSON结构、URL格式三处敏感且静默降级，常见问题包括键名错误、URL缺斜杠、漏"type":"composer"、未加-g、项目级repositories屏蔽全局源及缓存未清理。
composer config -g repositories.packagist.org 配置为什么没生效
不是命令没运行，而是 Composer 2.2+ 对键名、JSON 结构和 URL 格式三处极其敏感，任意一个出错就静默 fallback 到 packagist.org —— 不报错、不提示，只悄悄走慢源。
常见失效点：
-
repositories.packagist.org写成repos.packagist.org或repo.packagist：前者多一个s，后者在 2.2+ 中已被弃用 - URL 缺末尾斜杠：
https://mirrors.aliyun.com/composer→ 拼出/packages.json变成/composerpackages.json，直接 404 - JSON 中漏掉
"type": "composer"字段：Composer 认不出这是镜像源，降级回官方源 - 没加
-g参数：配置只写入当前项目composer.json，换目录就失效
元数据本地化 ≠ 包文件本地化
很多人以为切了镜像源就“全本地化”了，其实只是元数据（packages.json、provider-laravel.json 等）走国内 CDN；真正的 ZIP 包（dist）是否也走镜像，取决于镜像站是否代理 dist 域名。
阿里云、清华源已实现全链路代理（metadata + dist + packages.all），但腾讯云偶尔延迟同步新包的 dist URL，导致 composer install 仍会 fallback 到境外下载 ZIP。
验证方式：
- 跑
composer update -vvv，看日志里Downloading行的域名是不是你配的镜像域名 - 检查
composer.lock中某个包的dist.url字段，应为https://mirrors.aliyun.com/composer/dists/...而非https://api.github.com/...
项目级 repositories 会完全屏蔽全局镜像
只要项目根目录的 composer.json 含 "repositories" 字段（哪怕只是空数组 [] 或 {"packagist": false}），Composer 就无视所有全局镜像配置，包括 repositories.packagist.org。
排查命令：
-
cat composer.json | grep repositories—— 确认字段是否存在 -
composer config -g repositories.packagist.org—— 查全局是否真写入 -
composer diagnose—— 看 “Repo:” 行显示的实际源地址
若需保留私有源又想用阿里云镜像，必须把 packagist 官方源显式写进 repositories 数组，并设 "packagist": true：
"repositories": [
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
},
{
"packagist": false
}
]
缓存不清理，元数据永远不更新
composer clear-cache 不是可选项，是必做动作。Composer 本地缓存元数据（~/.composer/cache/repo/ 下的 JSON 文件），即使你改了全局配置，旧缓存仍会让请求发往 packagist.org。
特别注意：
- Windows 下 Git Bash 用户，
COMPOSER_HOME可能未生效，实际缓存路径是%APPDATA%\Composer\Cache\，得手动清或用composer clear-cache全局执行 - 宝塔面板或 Docker 容器中，PHP 进程可能以
www用户运行，而你用root配的镜像 —— 必须也对www用户执行一遍composer config -g ...和clear-cache - CI 脚本里建议每次构建前都加
composer clear-cache，避免缓存污染
真正麻烦的从来不是换源本身，而是元数据和 dist URL 的一致性、缓存生命周期、以及项目级配置对全局策略的无声覆盖 —— 这些细节不盯住，再快的镜像也白搭。
