ZipArchive类需PHP扩展真实启用并实测可用，仅php -m显示zip不够；必须执行php -r "new ZipArchive();"不报错且能输出ZIPARCHIVE常量值才算通过，否则composer解压会失败。
ZipArchive 类不是“引入”就能用的组件，它属于 PHP 内置扩展，必须在运行环境中真正加载并可用——否则 composer install 会卡在解压阶段，报 Class 'ZipArchive' not found、zlib_decode(): data error 或 ZipArchive::extractTo(): failed to open stream 这类错误，和 composer.json 里写不写 ext-zip 没关系。
确认 ZipArchive 是否真能实例化
很多人只跑 php -m | grep zip 看到输出就以为完事了，但实际 new ZipArchive() 可能仍失败。关键要实测：
-
php -r "new ZipArchive(); echo "OK\n";"—— 不报错才算通过 -
php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"—— 能输出数字，说明 libzip ABI 兼容、版本够新 - 重点检查 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 错误怎么绕过
这不是 ZIP 文件损坏，而是 PHP 的 zlib 扩展对含数据描述符或 ZIP64 的流解析不稳定，PHP 8.2+、WSL 和 Windows 下高频出现。常见现象是 Downloading 后立即崩，堆栈里带 zlib_decode()。
- 先清缓存：
composer clear-cache && composer install --no-cache（坏 ZIP 会复用） - 关掉干扰项：
zlib.output_compression = Off（必须是Off，不是0或空）、zlib.encode = ""（PHP 8.0+），改完重启 CLI PHP - 最稳方案：装好
7z.exe（Windows/WSL）或7zz（Linux），确保which 7z有输出，再运行COMPOSER_UNZIP=7zip composer install - 临时应急（不推荐）：
COMPOSER_DISABLE_ZLIB=1 composer install，但速度极慢且不治本
ZipArchive::extractTo(): failed to open stream 怎么修
这个错误表面是“打不开文件”，实际多因权限、磁盘空间或临时目录不可写导致。Composer 解压时会在系统 /tmp（Linux/macOS）或 %TEMP%（Windows）建临时目录，中间任一环节卡住都会报这个。
- 查磁盘和 inodes：
df -h && df -i，/tmp分区满是隐形杀手 - 换大分区临时目录：
export TMPDIR="/mnt/bigdisk/tmp" && mkdir -p "$TMPDIR" && chmod 777 "$TMPDIR"（注意：COMPOSER_CACHE_DIR不控制解压位置，TMPDIR才是） - 检查
proc_open是否被禁用：php -i | grep "disable_functions"，如果含proc_open，删掉它，保存后重启 CLI 环境（Docker 需重建容器） - 手动删
vendor/和composer.lock中出错包的残留目录，再重试
unzip 命令缺失时 Composer 怎么 fallback
Composer 默认优先用 ZipArchive，但该扩展不可用时会 fallback 到系统 unzip 命令。如果连这个都没有，就会报 Unzip with unzip command failed, falling back to ZipArchive class——这句日志其实是 fallback 失败的信号，不是成功提示。
- Ubuntu/Debian：
sudo apt install -y unzip - CentOS/RHEL 8+：
sudo dnf install -y unzip - Alpine（Docker）：
apk add --no-cache unzip - 装完验证：
unzip -v应输出版本号，which unzip应返回路径 - 注意：
unzip是保底手段，真正高效稳定的是ZipArchive；装了unzip仍失败，大概率是ZipArchive被悄悄禁用了（比如proc_open被禁、open_basedir限制）
真正卡住的地方往往不是 ZIP 文件本身，而是 PHP 扩展状态、CLI 环境配置、临时目录权限三者之间的隐性冲突。每次排查前，先跑一遍 php -r "new ZipArchive();"，比盲目重装 PHP 或换镜像快得多。
