镜像源配置生效需同时满足三条件：键名必须为单数repo.packagist、type值显式写composer、URL须HTTPS且末尾带/；否则静默回退官方源，且不报错。
镜像源配置对了 ≠ 能用，同步问题八成出在本地缓存、配置覆盖或元数据时效性上。
composer config -g repo.packagist 配置是否真生效
很多人执行完命令就以为搞定了，结果 composer update 还是走 https://packagist.org。最准的验证方式只有一条：
运行 composer config -g repo.packagist，输出必须是类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 的完整 JSON。
如果返回空、null、报错，或者仍含 packagist.org，说明没配成功。
常见失败点：
- 键名写成
repos.packagist（多一个s），静默失效 - 漏掉
composer类型参数，如composer config -g repo.packagist https://...→ 缺composer会 fallback 到官方源 - URL 少了末尾
/，请求变成/composerpackages.json直接 404 - 项目根目录有
composer.json且含"repositories"字段，会完全屏蔽全局配置
镜像站本身是否真的同步及时
阿里云、腾讯云等主流镜像同步延迟通常为 5–15 分钟，不是服务端卡死，而是轮询机制决定的。不能只看 packages.json 的 lastModified，它可能已更新，但目标包的 provider 文件还没生成。
务必手动验证两个关键点：
- 用
curl -I https://mirrors.aliyun.com/composer/packages.json看是否返回HTTP/2 200；状态码不是 200 就别往下试 - 查具体包：比如要装
monolog/monolog，访问https://mirrors.aliyun.com/composer/p/monolog/monolog.json，对比官网同地址，看Last-Modified时间差是否 ≤ 180 秒，且版本号一致 - 若镜像站返回 404，而官网已有新版，说明该镜像节点同步卡住（超 30 分钟未更新即属异常）
本地元数据缓存是否强制刷新
composer clear-cache 只删 ZIP 包和 dist 缓存，对决定“有没有这个包”的 packages.json 和 provider-*.json 几乎无效。Composer 默认 15 分钟内复用本地元数据，哪怕镜像已更新也不会重拉。
正确做法分版本：
- Composer ≥ 2.5：
composer update --refresh—— 它丢弃所有缓存的元数据文件，只重拉索引，保留 ZIP 包 - Composer ≤ 2.4：必须手动删缓存目录，先查路径：
composer config --global cache-dir，再删对应 repo 子目录，例如：rm -rf $(composer config --global cache-dir)/repo/https---mirrors-aliyun-com-composer - 临时调试加
--no-cache -v，看终端输出的真实请求 URL 是否命中你配的镜像地址
项目级 repositories 配置如何不破坏镜像逻辑
只要 composer.json 里有 "repositories" 字段，全局镜像就彻底失效。这不是 bug，是设计行为——且不报错、不提示。
安全写法是显式启用镜像并控制 fallback：
- 用命令注入（推荐）：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不带-g），它会自动在repositories数组中追加，不覆盖已有私有源 - 确保
"type": "composer"显式写出，URL 以/结尾，类型值不能省略 - 若需禁用官方源 fallback，应设
"packagist.org": false，而非删掉整个packagist.org条目；否则遇到镜像未同步的包会直接报错 - 切镜像前必须删掉
vendor/和composer.lock，否则锁文件里dist.url仍指向旧源，Composer 会绕过镜像直连 GitHub 或 Packagist
真正容易被忽略的是：元数据同步、缓存刷新、配置作用域这三者之间的耦合关系。改完配置不验证、不清缓存、不删 lock，基本等于白操作。
