composer 报“unzip with unzip command failed”本质是 ziparchive 失败后 fallback 也失败，需先验证并修复 php zip 扩展（如安装 php-zip、启用 extension=zip、检查 disable_functions 是否禁用 proc_open），再安装系统 unzip 命令；docker 用户须 docker-php-ext-install zip；windows/wsl 下可临时用 composer_unzip=7zip 绕过。
Composer 报 “Unzip with unzip command failed” 不是缺命令的信号，而是 ZipArchive 已经失败、再 fallback 调用系统 unzip 也失败的双重报错——你得先确认 ZipArchive 类真能用，再补 unzip。
php -r "new ZipArchive();" 报错？别装 unzip，先修 PHP 扩展
这是最常被跳过的一步。很多人看到 “unzip command failed” 就直奔 apt install unzip，结果装完还是崩。因为 Composer 默认压根不调 unzip，它优先走 ZipArchive::extractTo()；只有这个方法失败了，才会尝试 fallback。而失败原因往往在 PHP 层：
-
php -r "new ZipArchive();"报Class 'ZipArchive' not found→ 说明zip扩展根本没加载，得装php-zip包或启用extension=zip -
php -r "var_dump(class_exists('ZipArchive'));"返回bool(false)→ 同上，不是系统问题，是 PHP 配置问题 -
php -i | grep "disable_functions"显示proc_open在列表里 →ZipArchive内部依赖它，禁用即失效，删掉再重启 CLI 环境 - Docker 用户注意：
php:8.2-cli-alpine默认不带zip扩展，光apk add unzip没用，必须加RUN apk add --no-cache zlib-dev && docker-php-ext-install zip
确认 ZipArchive 可用后，再按系统装 unzip 命令
装 unzip 是为了兜底，不是主路径。它只在 ZipArchive 失效时被调用，且必须是完整版（busybox 版本、老版 Info-ZIP 或某些第三方压缩工具附带的 unzip.exe 常因缺少 ZIP64 支持被 Composer 拒绝）：
- Ubuntu/Debian：
sudo apt update && sudo apt install -y unzip - CentOS/RHEL 7：
sudo yum install -y unzip - CentOS/RHEL 8+ / Fedora：
sudo dnf install -y unzip - Alpine（Docker 常见）：
apk add --no-cache unzip（务必加--no-cache，否则镜像体积翻倍） - Windows：
unzip.exe放进C:\Windows\System32，不是改 PATH；推荐从 Info-ZIP 官网下载 Win32 二进制包，解压后复制unzip.exe过去；别用 7-Zip 自带的，Composer 不认
装完验证：unzip -v 有版本输出、which unzip（Linux/macOS）或 where unzip（Windows）返回路径才算成功。
COMPOSER_UNZIP=7zip 是 Windows/WSL 下更稳的绕过方案
即使 ZipArchive 和系统 unzip 都正常，PHP 的 zlib 解压在 WSL 或 Windows 下仍可能对 ZIP64 或数据描述符解析失败，报 zlib_decode(): data error。这时换解压引擎比修环境更快：
- 确保
7z.exe在PATH中（如 7-Zip 官网安装后默认会加） - 运行：
COMPOSER_UNZIP=7zip composer install - 它绕过
ZipArchive和系统unzip，直接调用7z，支持 ZIP64、CRC 校验更严格，失败率低得多 - 注意：这不是长期替代方案，但对 CI/CD 或临时调试非常有效
真正容易被忽略的是：CLI 和 Web SAPI 的 PHP 配置完全独立，php -m 查到的扩展不一定被 composer install 用到的那个 PHP 实例加载；php --ini 必须执行，确认 CLI 实际读的是哪个 php.ini，再检查里面是否真启用了 extension=zip。
