composer update 不触发元数据刷新是因为默认复用本地缓存的 packages.json（15 分钟内不过期），即使镜像站已更新；解决方法是使用 composer update --refresh（≥2.5）强制重新下载元数据。
镜像源同步延迟时，composer update 仍可能拉不到新版本——因为 Composer 默认信任本地缓存里的元数据，而不是实时查镜像站。 真正起效的操作不是换源或重试，而是切断缓存对元数据的复用，并强制重新抓取远程 packages.json。
为什么 composer update 不触发元数据刷新？
Composer 在执行 update 前，会先检查 ~/.composer/cache/repo/https---mirrors.aliyun.com-composer/（或你配置的镜像地址）下的 packages.json 文件。只要这个文件存在且未过期（默认 15 分钟），它就直接读缓存，跳过网络请求——哪怕镜像站上已有更新，本地也看不到。
- 现象：你在 packagist.org 上看到
monolog/monolog已发布3.6.0，但composer update monolog/monolog显示 “Nothing to install or update” - 原因：缓存里还存着旧版
packages.json，里面没记录3.6.0 - 注意：
composer clear-cache会清掉这个文件，但composer update下次运行时又会立刻重建并复用——除非你主动干预
composer update --refresh 是什么，能解决同步延迟吗？
composer update --refresh（Composer ≥ 2.5）专为这个问题设计：它强制丢弃所有已缓存的 packages.json，重新从配置的镜像源下载最新元数据，但不碰 ZIP 包缓存。这是最轻量、最精准的解法。
- 它不会重下任何包，只刷新“有哪些版本可用”这个信息
- 执行后立刻再跑
composer update vendor/package-name，就能看到新版本被识别出来 - 如果用了自定义镜像，确保
composer config -g repo.packagist输出的是你期望的 URL（比如https://mirrors.aliyun.com/composer/），否则--refresh会去错地方拉 - 不支持 Composer 2.4 及更早版本；老版本只能手动删缓存目录里的
repo/子目录，或改用COMPOSER_CACHE_DIR=/dev/null composer update
缓存路径不对？先确认当前生效的镜像和缓存位置
不同镜像源对应不同缓存子目录，clear-cache 虽然全清，但排查问题时得知道 Composer 实际连的是谁、存到哪了。
- 查当前镜像：
composer config -g repo.packagist - 查缓存根目录：
composer config --global cache-dir - 进缓存目录看具体 repo 子路径：
ls -l $(composer config --global cache-dir)/repo/，你会看到类似https---mirrors-tencent-com-composer这样的文件夹 - 如果你通过环境变量
COMPOSER_REPO_PACKAGIST临时指定镜像，config -g不会显示它，但缓存仍写入对应 URL 的子目录——此时--refresh依然有效，它读的就是运行时实际使用的镜像地址
CI/CD 中如何避免镜像延迟导致构建失败？
在 GitHub Actions 或 GitLab CI 中，runner 往往复用缓存目录，容易把过期元数据带进来。不能只依赖 --refresh，得双重保险。
- 加环境变量彻底隔离：
COMPOSER_CACHE_DIR=/tmp/composer-cache-$$（$$是进程 ID，保证每次唯一） - 再配合
composer update --refresh，确保元数据干净 - 如需重装包本身（不只是识别新版本），后续接
composer update --no-cache或composer install --no-cache，防止 ZIP 缓存干扰 - 别用
composer clear-cache清理 CI 缓存——它只是删本地文件，不阻止后续命令立刻重建；环境变量方式才是源头阻断
镜像同步延迟的本质是元数据缓存策略，不是网络或权限问题。最常被忽略的一点是：--refresh 不等于“重装”，它只管“看见新版本”，而“装上新版本”还得靠后续的 update 或 require 命令——这两步缺一不可，顺序也不能颠倒。
