composer 不支持自动同步镜像源，仅能通过 composer update --refresh（≥2.5）强制刷新本地元数据缓存，从当前配置的镜像源重新拉取索引，保留 zip 包缓存；执行前需确认镜像地址正确。
没有“自动同步镜像源”的客户端机制——Composer 本身不提供、也不支持任何命令或配置去主动触发镜像站的后台同步。你真正能控制的，只有本地如何重新获取最新元数据。
composer update --refresh 是最直接有效的元数据刷新方式
该命令（要求 Composer ≥ 2.5）会强制丢弃本地缓存的 packages.json 和所有 provider-*.json 文件，然后从当前生效的镜像源（不是 packagist.org）重新拉取完整索引，但保留已下载的 ZIP 包缓存，不重复下载。
- 执行前务必确认
composer config -g repo.packagist输出是你期望的镜像地址（如阿里云），否则它会重拉错误源 - 若项目级
composer.json中定义了repositories，则composer config repo.packagist（无-g）才有效，且会写入该文件 - 加
--no-cache -v可在终端看到真实请求 URL，确认是否命中你配的镜像地址（例如https://mirrors.aliyun.com/composer/packages.json） - 老版本 Composer（--refresh，只能手动删除对应
repo/https---*子目录
为什么 composer diag 和 curl 看起来“矛盾”？
composer diag 默认只连 https://packagist.org，完全无视你配置的镜像地址。它报 “Connection failed” 只说明本地 PHP 环境（curl、OpenSSL、系统时间）可能异常，不代表你的阿里云镜像挂了。
- 查真实生效镜像：运行
composer config -g repo.packagist（注意是单数repo） - 验证镜像连通性：用
curl -I https://mirrors.aliyun.com/composer/packages.json，必须返回HTTP/2 200 - 如果
diag报错但curl通，问题在本地环境，不是镜像同步慢
清缓存必须删对路径，否则白忙活
composer clear-cache 只删 ZIP 包和部分 JSON，对决定“有没有这个包”的 packages.json 和 provider-*.json 几乎无效。这些关键元数据存在 ~/.composer/cache/repo/https---mirrors.aliyun.com-composer 这类路径下，名字由镜像 URL 转义生成。
- 先确认缓存位置：
composer config --global cache-dir - 再进
repo子目录看实际路径：ls -d $(composer config --global cache-dir)/repo/https---* - 删错目录（比如删了
https---packagist.org却配着阿里云镜像）就等于没操作 - Windows 用户路径类似
%APPDATA%\Composer\cache\repo\https---mirrors-aliyun-com-composer
项目级配置比全局更可靠，但写法有硬约束
全局配置 composer config -g 在多机、CI、Docker 等场景下根本不同步，因其写入各机器独立的 ~/.composer/config.json；而项目级配置可提交 Git，确保一致。
- Composer 2.2+ 必须用数组格式，且首项显式禁用官方源：
{"packagist.org": false}，不能合并到下一项 - 镜像
url末尾必须带/，否则请求变成/composerpackages.json，404 - 必须写
"type": "composer"，漏掉就静默 fallback 到官方源 - 已有私有 VCS 仓库要插在第二项之后，不能删掉第一项
镜像站之间的元数据同步节奏不同，同一时刻查到的版本可能差几个小时。与其硬等，不如在配置失效时快速切换源——比如从阿里云切到中科大源，比等待更可控。最关键的是：别把“镜像同步延迟”误判为“网络不通”或“配置失败”，先用 curl -I 验证具体 URL 是否返回 200，再动手。
