必须运行php -r "new ZipArchive();"不报错才算ZipArchive类真正可用，再执行php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"输出数字才代表libzip ABI兼容；仅php -m | grep zip有输出不等于可用。
ZipArchive 类不可用是绝大多数 Composer 解压失败的根因，不是网络、权限或磁盘满——先验证它，再动其他。
怎么确认 ZipArchive 真能用（不是只在 php -m 里）
很多人看到 php -m | grep zip 有输出就以为搞定了，结果 composer install 还是崩。这说明扩展只是注册了，但类没加载成功，或底层 libzip ABI 不兼容。
- 必须运行：
php -r "new ZipArchive();"—— 不报错才算通过 - 再跑：
php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"—— 能输出数字（比如1）才代表 libzip 版本够新、ABI 兼容；若报Undefined class constant，大概率是系统自带的 libzip 太老（如 CentOS 7 的 0.10） - 查 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中删掉它，保存后重启 CLI 环境 - 确认当前用户对项目根目录和
vendor/有写权限：chmod -R 755 vendor/或sudo chmod +w vendor/
unzip 命令缺失时 Composer 怎么 fallback
错误信息含 Unzip with unzip command failed, falling back to ZipArchive class，说明 Composer 尝试调用系统 unzip 失败，转而依赖 PHP 的 ZipArchive——但如果你的 ZipArchive 本身不可用，就会直接报错。
- Linux（Ubuntu/Debian）：
sudo apt install unzip - Linux（CentOS/RHEL 8+）：
sudo dnf install unzip - Alpine（Docker 常见）：
apk add --no-cache unzip - macOS（Homebrew）：
brew install unzip - Windows：从 7-Zip 官网下载安装，并确保
7z.exe在PATH中；然后用COMPOSER_UNZIP=7zip composer install强制走 7z 解压（比原生unzip更稳）
真正容易被忽略的是：装了 unzip 只是保底手段，真正高效稳定的是 PHP 原生 ZipArchive；很多问题表面是 “unzip 缺失”，实际是 ZipArchive 被悄悄禁用了——务必先验证 php -r "new ZipArchive();" 和 proc_open 可用性。
