答案是“failed to download metadata”主因是镜像源失效（如阿里云镜像已下线）或本地元数据缓存污染，需先验证镜像有效性、手动删除~/.composer/cache/repo/目录并清缓存，再切至仍在维护的镜像源（如https://packagist.phpcomposer.com）或官方源。
Composer install 报错“Failed to download metadata” 是镜像源失效或缓存污染
这不是网络连不通，而是 Composer 本地缓存里存了过期的镜像元数据（比如 packagist.org 的 packages.json），而当前配置的镜像源（如阿里云、腾讯云）已下线或接口变更，导致 composer install 尝试读缓存 + 回源时失败。
先确认当前镜像源是否还有效
运行 composer config -g repo.packagist 查看全局镜像配置。如果返回类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，注意：阿里云 Composer 镜像已于 2024 年底正式下线，该 URL 现返回 404，但 Composer 仍会尝试加载缓存并失败。
- 国内仍在维护的可靠镜像只有：
https://packagist.phpcomposer.com（PHP Composer 官方代理）、https://packagist.proxy.fossi.dev（开源社区维护） - 更稳妥的做法是临时切回官方源：
composer config -g repo.packagist composer https://packagist.org - 若公司内网有私有源，确保其
packages.json可被curl -I直接访问且返回 200
清理缓存不能只靠 composer clear-cache
composer clear-cache 只清 ~/.composer/cache/ 下的 dist 和 zip 包，不删元数据缓存（即 ~/.composer/cache/repo/ 里的 https---packagist.org/ 或镜像路径下的 packages.json 文件）。这些过期元数据才是报错根源。
- 手动删除整个 repo 缓存目录：
rm -rf ~/.composer/cache/repo/ - Windows 用户对应路径是：
%APPDATA%\Composer\Cache\repo\ - 执行后运行
composer install -vvv，观察日志里是否出现Loading https://packagist.org/packages.json—— 若出现且后续无 404，说明缓存已重置成功
避免下次再踩坑：锁定镜像源 + 禁用自动 fallback
Composer 默认在镜像失败后会自动 fallback 到官方源，但这个过程可能因缓存干扰失败。显式禁用 fallback 并固定可用源，能更快暴露问题。
- 设置镜像并关闭 fallback：
composer config -g repo.packagist composer https://packagist.phpcomposer.com --disable-tls - 项目级配置优先于全局，建议在项目根目录加
composer.json片段：{"repositories": [{"type": "composer", "url": "https://packagist.phpcomposer.com"}]} - CI/CD 中务必加
composer clear-cache前置步骤，并确保~/.composer/cache/repo/不被缓存（GitLab CI 的 cache: key 要排除该路径）
真正卡住人的从来不是“没网”，而是缓存里躺着一个上周还能用、今天已 404 的 packages.json —— 它不报错，只静默失效，直到你手动掀开 ~/.composer/cache/repo/ 看一眼。
