Composer报Unzip解压失败_服务器解压组件安装【小白福音】

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 中。