Composer 报“找不到元数据文件”，通常不是包不存在，而是它压根没拿到最新的 packages.json —— 这个文件才是所有包版本信息的总目录。缓存没刷新、镜像源配错、TLS 握手失败，都可能导致 Composer 停在旧快照上不动。
为什么 composer clear-cache 有时不解决 metadata 问题？
composer clear-cache 只清 ~/.composer/cache/ 下的压缩包和索引归档，但不会动掉真正卡住更新的三处关键缓存：
-
~/.composer/cache/repo/https---packagist.org/（或你配置的镜像路径）里的packages.json和provider-*.json—— 它们是元数据的“大脑”，默认 15 分钟不过期，哪怕镜像站已发布 v3.0.0，这里还是 v2.9.9 的快照 -
vendor/composer/installed.json—— 记录当前已装包的精确版本，composer show直接读它，不走远程；若里面没新版本记录，就显示“no matching package found” -
composer.lock—— 虽然不算缓存，但它硬编码了每个包的 commit hash 或版本号；只要它存在，composer install就完全绕过元数据查询
composer update --refresh 是什么，什么时候能用？
这是 Composer ≥ 2.5 内置的元数据刷新开关，比手动删目录更精准：
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 它只丢弃
repo/子目录下的packages.json和 provider 文件，不碰 ZIP 包缓存，也不删vendor/或composer.lock - 执行后立刻触发一次
Downloading https://.../packages.json，确保下次update看到的是镜像源当前最新索引 - 前提是
composer config -g repo.packagist输出必须是以https://开头的有效地址；如果输出是http://mirrors.aliyun.com/composer/，--refresh会去错地方拉，且可能被网络策略静默拦截 - Composer 2.4 及更早版本不识别该参数，强行运行会报错：Unrecognized option: --refresh
手动清理 metadata 缓存的最小安全操作集
不管版本新旧，以下四步组合最可靠：
- 运行
composer clear-cache清基础缓存 - 删除元数据主目录：
rm -rf ~/.composer/cache/repo/https---packagist.org/（Linux/macOS）或rd /s /q "%APPDATA%\Composer\Cache\repo\https---packagist.org"（Windows） - 删掉项目级快照：
rm -f vendor/composer/installed.json和rm -f composer.lock（后者删前确认是否真要重解依赖） - 验证是否生效：
composer update --dry-run -v，看到Downloading https://...行才表示元数据正在重拉；若仍只显示Reading from cache，说明某处缓存路径残留或镜像源配置未生效
真正容易被忽略的是：删完缓存后，第一次 composer update 必须成功拿到 packages.json，否则后续所有操作都在原地打转。这时候看 -v 输出里的真实 HTTP 状态码，比看报错文字更有用。
