Composer 报 unzip 解压失败，90% 不是缺 unzip 命令，而是 PHP 的 ZipArchive 类根本不可用 —— 别急着装系统工具，先验证扩展是否真就绪
怎么确认 ZipArchive 真能用（不是只显示在 php -m 里）
很多人习惯性地运行 php -m | grep zip，看到输出就以为万事大吉，结果一执行 composer install 还是崩。这其实说明，扩展可能只是“注册了”，但类根本没加载成功，或者底层库存在ABI兼容性问题。
真正的验证，得靠这两条命令：
- 必须运行
php -r “new ZipArchive();”—— 只要不报错，才算初步通过。 - 再运行
php -r “echo ZIPARCHIVE::CHECKSUM_CRC32;”—— 如果能输出一个数字（比如1），那才代表底层的 libzip 库版本够新、ABI 兼容。如果报错Undefined class constant，基本可以断定是底层库太老，这在 CentOS 7 自带的 libzip 0.10 上很常见。
另外，别忘了检查 CLI 实际读取的配置：运行 php --ini，确认对应的 php.ini 里确实有 extension=zip（Linux/macOS）或 extension=php_zip.dll（Windows）。
Docker 用户要特别注意：像 php:8.2-cli-alpine 这类精简镜像，默认是不带 zip 扩展的，需要手动在 Dockerfile 里加上 RUN apk add --no-cache zlib-dev && docker-php-ext-install zip。
unzip 命令缺失时 Composer 怎么 fallback
如果错误信息里包含 Unzip with unzip command failed, falling back to ZipArchive class，这就很清楚了：Composer 先是尝试调用系统的 unzip 命令，失败了，才转而依赖 PHP 的 ZipArchive 类。但问题在于，如果你的 ZipArchive 本身也不可用，那就会直接报错。
所以，安装系统级的 unzip 命令只是解决了第一步，并不能替代 PHP 扩展的问题：
- Linux（Ubuntu/Debian）：
sudo apt install unzip - Linux（CentOS/RHEL）：
sudo yum install unzip或sudo dnf install unzip - macOS（Homebrew）：
brew install unzip - Windows：可以从 7-Zip 官网下载安装，并确保
7z.exe在系统PATH中。然后，可以用COMPOSER_UNZIP=7zip composer install强制 Composer 使用 7z 来解压，这通常比依赖原生unzip更稳定。
proc_open 被禁用导致 ZipArchive 失效
这是一个相当隐蔽的坑。ZipArchive::extractTo() 这个方法在内部其实依赖 proc_open() 来启动子进程，用于做校验或解压后的处理。如果 proc_open 被禁用，那么即使 new ZipArchive() 不报错，后续的 extractTo() 操作也一定会失败，错误堆栈里常常能看到 proc_open is disabled，或者直接静默回退。
排查和解决步骤如下：
- 检查禁用函数列表：运行
php -i | grep “disable_functions”，看看输出里是否包含proc_open。 - 修改对应的
php.ini文件（注意，一定是 CLI 版本 PHP 读取的那个！），从disable_functions配置行里删除proc_open，保存后重启 CLI 环境（Docker 需要重建容器，WSL 可能需要重新打开终端）。 - 使用宝塔面板的用户，可以进入【软件管理】→【PHP 设置】→【禁用函数】页面，找到并删除
proc_open。
需要警惕的是，别以为“我只用 Web 环境，CLI 配置不重要”。Composer 只走 CLI 模式的 PHP，Web 环境的配置改得再对，也影响不了它。
临时空间不足引发 extractTo 失败（最隐蔽的坑）
报错信息 ZipArchive::extractTo(): failed to open stream 看起来像是权限问题，但实际上，大概率是临时目录出了状况。可能是 /tmp 分区满了，也可能是 inodes 耗尽，或者 TMPDIR 环境变量指向的路径不可写。因为 Composer 在解压时，会先将 ZIP 包拷贝到临时目录，解压完成后再移动到最终的 vendor/ 目录。
可以按这个思路排查：
- 检查空间和 inodes：运行
df -h && df -i，重点查看/tmp分区，或者sys_get_temp_dir()函数返回的路径所在分区。 - 修改临时路径（立即生效）：
export TMPDIR=“/path/to/big/disk/tmp” && mkdir -p “$TMPDIR” && chmod 777 “$TMPDIR”。 - 验证修改是否生效：运行
php -r “echo sys_get_temp_dir();”，应该输出你设置的新路径。
这里有个常见的误区：只修改 COMPOSER_CACHE_DIR 是没用的。缓存目录不影响解压阶段，真正关键的是 TMPDIR 这个环境变量。
说到底，真正卡住人的，往往不是“要不要装 unzip”这个表面问题。而是 php -r “new ZipArchive()” 这一行命令背后隐藏的扩展状态，或者是 proc_open 被悄悄禁用、TMPDIR 指向了一个只剩 3 个 inodes 的分区这类环境细节。这些细节，都藏在 CLI PHP 的真实配置里，而不是你以为的那个“应该没问题”的 php.ini 中。
