直接结论：网络波动导致的composer install报错，90%需清缓存+强制走镜像+验证真实请求地址；失败响应或损坏zip被缓存复用，不重试只报错，必须执行composer clear-cache、确认镜像url末尾有斜杠、用-vvv验证下载地址是否为镜像源，并同步清理composer.lock与缓存目录权限。
直接结论：网络波动导致的 composer install 报错，90% 不是重试就能解决，而是缓存了失败响应或损坏 ZIP 包——必须清缓存 + 强制走镜像 + 验证真实请求地址。
报错里带 “file could not be downloaded” 或卡在 “Downloading”
这不是临时断连，而是 Composer 把半截下载的 ZIP 或错误响应缓存在本地，下次 install 会直接复用它，校验失败后报错。它不重试，只报错。
- 先运行
composer clear-cache—— 这步必须做，但还不够 - Windows 用户额外删掉
%LOCALAPPDATA%\Composer\cache目录（GUI 文件管理器可能隐藏，用 CMD 进入） - 检查是否真走了镜像：运行
composer install -vvv 2>&1 | head -n 10 | grep Downloading，第一行 URL 才是真实请求地址；如果还是packagist.org，说明镜像没生效 - 确认镜像 URL 末尾有
/：比如https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会导致拼出/composerpackages.json404）
“Failed to extract” 或 “corrupted archive”
这是缓存中 ZIP 文件本身损坏的明确信号。网络波动中断下载时，Composer 不会自动丢弃残缺文件，而是留着下次继续用——结果解压失败。
- 不要只删
vendor/，要连composer.lock一起删：它记录了旧 checksum，不删就一直校验失败包 - CI/CD 中更需绕过缓存：用
COMPOSER_CACHE_DIR=/dev/null composer install --no-cache --prefer-dist - 如果仍失败，检查
$(composer config --global cache-dir)目录归属：ls -ld输出若属主是root，执行sudo chown -R $USER:$USER $(composer config --global cache-dir) - 某些杀毒软件或 IDE（如 PHPStorm）会在后台锁 ZIP 文件，CI 容器里加
--no-interaction可避免卡在解压重试
明明配了镜像，却还在访问 packagist.org
镜像配置静默失效是高频坑。Composer 2.x 不报错、不提示，直接 fallback 到官方源——你看到的 composer config -g repo.packagist 输出可能是空或旧值。
- 验证命令必须带
-g：写成composer config repo.packagist（无-g）只会改当前项目composer.json，换目录就丢 - 输出必须是完整 JSON：
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，不是字符串、不是null、不能多空格 - 项目根目录若有
"repositories": []字段，全局镜像完全被屏蔽——临时清掉：composer config --unset repositories - 宝塔或 CI 中，你用
root配的镜像，但实际运行的是www用户：得用sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
最易被忽略的点：缓存目录权限错位和 composer.lock 里硬编码的 provider 地址。一次网络波动可能留下两个隐患——损坏的 ZIP 和过期的元数据路径，二者不一起清理，重装十次也会失败。
