Composer 报 Corrupt zip 错误主因是下载中断、代理缓存污染或本地缓存含不完整文件；清缓存（composer clear-cache）并强制重试（composer install --no-cache）即可解决，无需改源或降级。
Composer 下载 Zip 包损坏（Corrupt zip）错误，绝大多数情况下不是 Zip 本身真损坏，而是下载过程被中断、代理缓存污染、或 Composer 自身的 cache 混入了不完整文件。直接删缓存 + 强制重试就能解决，不需要改源或降级。
为什么 Composer 会报 Corrupt zip？
Composer 在安装包时，默认从 Packagist 或镜像拉取 .zip 归档（尤其在 prefer-dist 模式下）。它会先下载到临时目录，再校验 SHA256 值；若下载未完成、网络抖动导致截断、或本地缓存里存了一个半途失败的 .zip，后续复用该缓存就会触发 Corrupt zip 报错。
常见诱因包括：
- 公司内网使用了透明代理或 Web 缓存设备，悄悄截断大文件
- 运行
composer install时 Ctrl+C 中断，但缓存已写入不完整文件 - 多个项目共享全局缓存，某次失败污染了整个
~/.composer/cache - 磁盘空间不足，导致解压前写入失败但没报错
快速修复：清空缓存并跳过本地 ZIP 复用
执行以下两步，90% 的 Corrupt zip 问题立刻消失：
- 运行
composer clear-cache—— 这会清掉所有已缓存的.zip和.tar文件 - 加
--no-cache参数重试安装：composer install --no-cache，强制跳过缓存，重新下载干净归档
如果仍失败，说明网络链路有问题，可临时切换回官方源验证：
composer config -g repo.packagist composer https://packagist.org
再运行 composer install --no-cache。若此时成功，基本可锁定是镜像源或本地代理的问题。
监控一个或多个 GitCode 仓库的 PR，通过 OpenClaw Gateway 自动执行 AI 审查，发布 PR 评论，并发送钉钉和企业微信通知。
避免反复踩坑的配置建议
长期开发中，这几个设置能大幅降低概率：
- 禁用
prefer-dist改用prefer-source（适合调试频繁、网络不稳定环境）：composer config --global prefer-source true - 限制并发下载数，减少代理压力：
composer config --global github-protocols ["https"]并设git clone超时：git config --global core.compression 0 - 检查磁盘空间：
df -h ~/.composer/cache，缓存目录剩余空间建议 >2GB
注意：corrupt zip 错误信息里通常带具体路径，例如 ./cache/files/vlucas/phpdotenv/...，可直接 rm -rf 对应子目录，比全量清缓更快。
当错误出现在 CI/CD 环境时
CI 流水线（如 GitHub Actions、GitLab CI）里出现此错误，大概率是 job 缓存复用了上一次失败的 vendor 或 ~/.composer/cache。解决方案很明确：
- 在
composer install前加一步：rm -rf ~/.composer/cache - 或改用无缓存模式：
composer install --no-cache --no-interaction - 不要在 CI 中启用
composer config --global cache-dir指向共享路径
某些 CI 镜像预装了旧版 Composer（如 2.2.x），升级到 2.5+ 可显著改善断点续传逻辑，但别为这问题单独升级——先清缓存，99% 不需要动版本。
真正难排查的是「偶发性 corrupt zip」，往往藏在代理层或 CDN 回源异常里。这时候盯住 composer install -v 输出里的下载 URL，用 curl -I 手动请求那个 .zip 地址，看 Content-Length 是否匹配 Content-MD5 或响应体是否被截断。
