Composer zip解压失败主因是PHP zlib/zip扩展配置不兼容、缓存复用损坏、临时空间不足或proc_open被禁用，需按顺序排查ZipArchive可用性、zlib_decode错误、extractTo权限/空间及unzip命令fallback能力。
Composer zip解压失败，90%不是网络或权限问题，而是 PHP 的 zlib 或 zip 扩展配置不兼容、损坏缓存复用、或临时空间不足——直接按顺序排查这四点，比重装 PHP 或换镜像快得多。
确认 ZipArchive 类是否真可用
报错含 Class 'ZipArchive' not found 或 zip extension is missing，说明 PHP 根本没加载 zip 扩展。别只看 php -m | grep zip 有输出就以为完事了——它可能只是模块名在列表里，但类并不可用。
- 必须验证：
php -r "new ZipArchive();"不报错才算通过 - 再跑：
php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"，能输出数字（如1）才代表 ABI 兼容、libzip 库版本够新 - 重点检查 CLI 使用的
php.ini：php --ini查路径，确保其中含extension=zip（Linux/macOS）或extension=php_zip.dll（Windows） - Docker 用户注意：
php:8.2-cli-alpine这类精简镜像默认不带zip，得手动加RUN apk add --no-cache zlib-dev && docker-php-ext-install zip
zlib_decode(): data error 怎么绕过
这个错误出现在下载完成后解压阶段，典型现象是卡在 Downloading 后立即崩，错误堆栈里带 zlib_decode()。它不是 ZIP 文件损坏，而是 PHP 的 zlib 扩展对某些 ZIP 流（比如含数据描述符、ZIP64）解析不稳定，尤其在 PHP 8.2+、WSL 或 Windows 下高频发生。
-
composer clear-cache && composer install --no-cache—— 缓存里坏 ZIP 会反复复用 - 关掉干扰项：
zlib.output_compression = Off（必须是Off，不是0或空字符串），zlib.encode = ""（PHP 8.0+），改完后重启 CLI PHP（不用动 Web 服务） - 最稳方案：换 7-Zip 解压。Windows/WSL 下装好
7z.exe并加入PATH，然后运行：COMPOSER_UNZIP=7zip composer install - 临时应急（不推荐）：
COMPOSER_DISABLE_ZLIB=1 composer install，但速度极慢且不解决根本问题
ZipArchive::extractTo(): failed to open stream 怎么修
这个错表面是“打不开文件”，实际多因权限、磁盘空间或临时目录不可写导致。Composer 解压时会在系统 /tmp（Linux/macOS）或 %TEMP%（Windows）建临时目录，再把 ZIP 拷进去解，最后挪到 vendor/。中间任一环节卡住都会报这个。
- 查磁盘和 inodes：
df -h && df -i，/tmp分区满是隐形杀手 - 设大分区临时目录：
export TMPDIR="/mnt/bigdisk/tmp" && mkdir -p "$TMPDIR" && chmod 777 "$TMPDIR" - 确认
proc_open没被禁用：php -i | grep "disable_functions"，若含proc_open，需在 CLI 版本php.ini中删掉它 - 不要只改
COMPOSER_CACHE_DIR：不改TMPDIR，解压阶段仍会撞上/tmp空间不足
unzip 命令缺失时 Composer 怎么 fallback
错误信息含 Unzip with unzip command failed, falling back to ZipArchive class，说明 Composer 尝试调用系统 unzip 失败，转而依赖 PHP 的 ZipArchive——但如果你的 ZipArchive 本身不可用，就会直接报错。
- Linux（Ubuntu/Debian）：
sudo apt install -y unzip - Linux（CentOS/RHEL 8+）：
sudo dnf install -y unzip - Alpine（Docker 常见）：
apk add --no-cache unzip - macOS：
brew install unzip - Windows：从 7-Zip 官网下载安装，并确保
7z.exe在PATH中；然后用COMPOSER_UNZIP=7zip composer install强制走 7z 解压（比原生unzip更稳）
光装 unzip 不够？还得确认 ZipArchive 真可用：php -r "var_dump(class_exists('ZipArchive'));" 输出 bool(true) 才算过关。很多问题表面是 “unzip 缺失”，实际是 ZipArchive 被悄悄禁用了——尤其是 proc_open 被禁用时，new ZipArchive() 可能不报错，但 extractTo() 一定失败。
