Composer报错zlib_decode(): data error处理与排查指南

zlib_decode(): data error 根本原因是 PHP zlib 扩展对 ZIP64 或含数据描述符的 ZIP 流解析失败，非网络或磁盘问题；应优先清对应包缓存、关 zlib.output_compression=Off、改 zlib.encode=""，或用 COMPOSER_UNZIP=7zip 绕过内置解压。

zlib_decode(): data error 这个报错，看着像是网络超时或者磁盘写不动了，但实际压根不是那回事。它是 Composer 在调用 PHP 内置的 zlib_decode 函数解压 ZIP 包时，发现输入的数据流本身坏了或者格式不兼容——直接硬拒绝。最坑的是，你删缓存、换镜像、重试好几遍，往往还是同一张脸，因为罪魁祸首是 PHP 自己的 zlib 扩展在处理某些 ZIP 流（尤其带数据描述符或 ZIP64 结构的包）时，解析逻辑上就翻车了。

删缓存只是绕过损坏 ZIP，不是根治

Composer 默认会把下载好的 ZIP 文件缓存到 ~/.composer/cache/files/ 下面。一旦某个包的 ZIP 被截断或者校验失败，后面每次 composer install 或 composer update 都会反复加载这个坏文件，一路撞到 zlib_decode(): data error 上。

• 跑 composer clear-cache 能清空整个缓存，但代价是全部重新下载，耗时又波及范围广。
• 更精准的做法：加 -v 参数运行一遍，找到报错时具体是哪个 .zip 解压失败，然后手动删掉对应路径。比如 rm -rf ~/.composer/cache/files/lara vel/framework/，只清这一个包。
• 临时跳过缓存：加 --no-cache 强制走网络重新下载，用来验证是不是缓存文件本身损坏了。

zlib.output_compression 必须为 Off

PHP 的 zlib.output_compression 配置如果被设成了 On、1 或 "1"，Composer 内部收到的 HTTP 响应流就会被 PHP 额外压缩一次。结果传给 zlib_decode 的是一段被嵌套压缩的乱码，不报错才怪。

• 先检查当前值：php -i | grep "zlib.output_compression"，确认输出显示的是 Off（注意不是 0 也不是空字符串）。
• 修改 php.ini（注意是 CLI 的配置，不是 Web 的），把 zlib.output_compression = Off 写进去。
• 如果用了 zlib.encode（PHP 8.0+ 的新特性），也建议设成空值：zlib.encode = ""，或者直接注释掉这行。
• 改完必须重启 CLI 环境——比如关掉当前终端再新开一个。用 php -v 看不出来，得用 php -i 再确认一遍。

用 7-Zip 替代 PHP zlib 解压（Windows / WSL 最稳方案）

Composer 2.2 及以上版本支持通过 COMPOSER_UNZIP 环境变量指定外部解压工具，这样就能彻底绕过 PHP 的 zlib_decode。对 Windows 和 WSL 用户来说尤其管用——PHP zlib 在这些平台上对 ZIP64 的支持一直不太稳定。

• Windows：安装 7-Zip，确保 7z.exe 在系统 PATH 里（cmd 下运行 7z 有响应才行）。
• 执行命令：set COMPOSER_UNZIP=7zip && composer install（Windows CMD）或 COMPOSER_UNZIP=7zip composer install（WSL/Linux/macOS）。
• 这个设置只对本次命令生效；如果需要持久化，可以写到 shell 配置（比如 ~/.bashrc）或 Windows 系统环境变量里。
• 注意：环境变量值必须是 7zip，不能写成 7z 或 7za——Composer 内部硬编码匹配的。

别盲目禁用 COMPOSER_DISABLE_ZLIB=1

有人可能会遇到 COMPOSER_DISABLE_ZLIB=1 这个选项，设了以后 Composer 会放弃 ZIP 压缩传输，改用未压缩的 TAR 格式。虽然能避开 zlib_decode，但副作用相当明显：

• 下载体积直接翻 3–5 倍，国内镜像下很容易因为超时中断。
• 它并不修复根本问题，只是把症状压下去了；换个环境照样可能复现。
• 部分私有仓库或自定义 installer 不支持 TAR 格式，会直接报错。
• 而且这个选项绕过的是网络压缩（HTTP Content-Encoding: gzip），和本地解压的 zlib_decode 是两层逻辑，很多人容易搞混。

所以真正要动的是 PHP 的 zlib 行为本身，而不是让 Composer “不用 zlib”。