Composer解压ZIP报zlib_decode()错误主因是PHP zlib扩展与ZIP格式兼容性问题，非网络或权限故障；应优先清缓存+--no-cache重试，检查zlib.output_compression关闭、zlib.encode置空，或设COMPOSER_UNZIP=7zip绕过zlib。
Composer install/update 报 zlib_decode(): data error
这是 Composer 在解压 ZIP 包时 zlib 扩展解析失败的典型错误，不是网络问题、权限问题或磁盘满，而是压缩流本身被截断或损坏——但更大概率是 PHP 的 zlib 扩展与 Composer 下载的 ZIP 数据不兼容（尤其在 Windows + WSL 或某些 PHP 8.2+ 环境下）。
常见触发场景：composer install 卡在 “Downloading …” 后报错；composer update 某个包下载完成后解压失败；使用国内镜像（如阿里云、腾讯云）时更频繁。
- 不要盲目重试或清空
~/.composer/cache—— 缓存里的损坏 ZIP 文件会反复复用 - 别急着换 PHP 版本 —— 多数情况是 zlib 解压逻辑对部分 ZIP 格式（如 ZIP64、含数据描述符的流式 ZIP）处理不稳
- 临时禁用压缩（非推荐）：
COMPOSER_DISABLE_ZLIB=1 composer install，但会显著拖慢速度且不解决根本问题
强制跳过缓存并重新下载 ZIP 包
Composer 默认会复用 ~/.composer/cache/files/ 下已下载的 ZIP，哪怕它已损坏。绕过缓存是最直接有效的验证和修复方式。
- 运行前先删掉对应包的缓存目录（路径形如
~/.composer/cache/files/vender/package-name/xxx.zip），或干脆清空整个 files 缓存：composer clear-cache - 加上
--no-cache参数强制走网络下载：composer install --no-cache - 如果仍失败，加
-v查看具体哪个包出问题，再针对性删其缓存后重试
检查并切换 PHP 的 zlib 配置（关键）
PHP 的 zlib 扩展在不同版本中对 ZIP 流的兼容性有差异。重点检查两个配置项：
Handsfree Windows Control
下载
通过 handsfree-windows CLI控制 Windows 本机应用 (UIA) 和浏览器 (Playwright) 的引导技能，用于自动化或测试桌面应用。
-
zlib.output_compression必须为Off（不是0或""）—— 开启会导致 Composer 内部流被二次压缩，引发解码错乱 -
zlib.encode（PHP 8.0+）若设为gzip或deflate，可能干扰 Composer 自身的解压流程，建议设为""（空字符串）或直接注释掉 - 确认
extension=zlib已启用（php -m | grep zlib），但不要额外加载zlib_filter类扩展
修改后重启 CLI PHP（不需要重启 Web 服务），再运行 php -i | grep -i zlib 确认生效。
换用 7zip 替代内置 ZIP 解压（Windows / WSL 可行）
Composer 从 2.2 起支持通过环境变量指定外部解压工具，绕过 PHP zlib —— 这是目前最稳定、副作用最小的方案。
- Windows：安装 7-Zip 并把
7z.exe加入 PATH，然后运行：set COMPOSER_UNZIP=7zip && composer install - WSL/Linux：安装 p7zip：
sudo apt install p7zip-full，再运行：COMPOSER_UNZIP=7zip composer install - 该方式完全跳过
zlib_decode()，且 7z 对 ZIP64 和损坏容忍度更高；注意路径中不能有空格，否则 7z 调用会失败
这个坑的本质不是 Composer 本身的问题，而是 PHP zlib 在流式 ZIP 解析上的历史遗留行为 —— 尤其当包发布者用新版 zip 工具打包、而你的 PHP 用老 zlib 解压时，就容易卡在最后一字节校验上。
