如何在Composer安装过程中跳过损坏的镜像节点

镜像节点 502 错误不是网络问题，是节点选错

Composer 报 502 Bad Gateway，下载卡在 downloading 不动了。这时候，90% 的情况不是你本地网络抽风，而是你用的镜像 URL 不幸指向了一个不太稳定的地域节点。

举个例子，https://mirrors.aliyun.com/composer/ 默认走的是华东 CDN。一旦遇到回源抖动，就可能直接给你来个 502。但要是换成华北节点，比如 https://mirrors.aliyun.com/composer-cn-beijing/，同一时间可能跑得飞起。问题就这么简单。

也别指望 Composer 能自动 fallback——它压根就不支持多源容灾。配置文件里的 repo.packagist 只接受一个字符串值，你塞两个 URL 进去，后一个会默默把前一个覆盖掉，白费力气。

正确的处理步骤很清晰：

• 先确认当前生效的镜像：执行 composer config -g repo.packagist，确保输出是一个完整的 JSON，并且 url 字段里的地址结尾必须带斜杠 /。
• 立刻清缓存：composer clear-cache。这一步不能省，否则旧的元数据会一直尝试访问那个失效节点。
• 切换到具体的地域节点。比如阿里云华北节点：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer-cn-beijing/
• 验证是否生效：跑 composer install -vvv，盯着日志的第一行，看是不是变成了 Downloading https://mirrors.aliyun.com/composer-cn-beijing/packages.json。看到这个，才算正式上路。

下载中断后怎么跳过已损坏的 ZIP 包

另一个常见场景：下载到一半断了，缓存里存了个半截 ZIP 文件。下次再跑 composer install，Composer 会傻乎乎地直接读这个不完整的文件，校验失败，然后给你报 Corrupted zip file 或 Invalid zip or corrupt data。它不会自己重下。

这时候，单纯执行 composer clear-cache 有时也不够给力——它只清 ~/.composer/cache/files/ 和 packages.json 的快照，但某些“半死不活”的损坏包可能卡在中间状态，没被清理干净。

更稳妥的做法是：

• 手动“定点清除”：rm -f $(composer config cache-dir)/files/vendor-name/package-name/*.zip
• 如果嫌麻烦，直接暴力清空整个 files 目录：rm -rf $(composer config cache-dir)/files
• 再狠一点，加 --no-cache 强制绕过所有缓存：composer install --no-cache --prefer-dist。这个命令能确保没有任何本地残留文件来干扰安装过程。
• 需要留意的是，--prefer-dist 比 --prefer-source 稳定得多，因为它能避开 git clone 操作触发的 GitHub API 限流。

为什么 composer update 会让问题更糟

遇到损坏包，很多人的第一反应是 composer update。这其实是个大坑，结果往往是暴露更多问题，甚至触发更深层的错误。

原因在于，update 在 dist 包不可用时，会 fallback 到 source，也就是执行 git clone。这一下子就引出了三个新麻烦：

• 私有仓库的 SSH 凭据可能会被直接打印在日志里，有安全风险。
• GitHub API 有调用限额，频繁 clone 很容易触发 403 rate limit exceeded，直接被锁死。
• 如果 composer.lock 里记录的 dist URL 已经被镜像移除了，update 会反复尝试、卡死，而不是聪明地跳过它。
• 一个更安全的替代方案是 composer update --lock。这个命令只重算 composer.lock 中的 dist.sha256 和 size 字段，完全不动 vendor/ 目录里的文件，相当于是“无损检测”。

缓存权限错位导致“假损坏”

还有一种情况特别容易迷惑人：报错信息里带着 failed to write 或 Permission denied。这时候别急着怀疑镜像坏了，90% 的可能性是缓存目录的属主错位了。这在 Docker、CI/CD 或者 WSL 环境里尤其常见。

排查和修复方法如下：

• 先查缓存路径：composer config --global cache-dir
• 再看当前属主：ls -ld $(composer config --global cache-dir)
• 修复权限（如果你是非 root 用户）：sudo chown -R $USER:$USER $(composer config --global cache-dir)
• 如果你是 WSL 用户，还得额外检查一下 /etc/wsl.conf 有没有启用 metadata 选项，否则 chmod 和 chown 命令是无效的。
• 顺手把整个配置目录的权限一并修了，省得以后出别的问题：sudo chown -R $USER:$USER ~/.composer

说到底，镜像节点本身并没有“跳过”错误的机制。所谓的“跳过”问题，本质上是“换一个稳定节点 + 清空所有残留 + 排除权限陷阱”这三件事同时做对了。任何一环出了纰漏，同一个错误就会像鬼打墙一样反复出现。