Composer报该错误是因为PHP zip扩展未启用且系统unzip命令缺失;它优先用zip扩展解压,失败后回退到unzip命令,两者皆无则报错退出。

为什么 Composer 会报 “The zip extension and unzip command are both missing”
这个错误不是 Composer 自身出问题,而是它在安装包时发现两个关键解压能力都不可用:zip PHP 扩展未启用,且系统级 unzip 命令也找不到。Composer 默认优先用 PHP 的 zip 扩展解压 ZIP 包(比如从 packagist 下载的 .zip 归档), fallback 到系统 unzip 命令;两者全缺,就直接报错退出。
检查并启用 PHP 的 zip 扩展
多数 Linux/macOS 发行版的 PHP 默认不启用 zip 扩展,Windows 的 php.ini 里它常被注释掉。先确认是否加载:
php -m | grep zip
如果无输出,说明未启用。解决方式依环境而定:
- Ubuntu/Debian:
sudo apt install php-zip,然后重启 Web 服务或 CLI PHP(无需改 php.ini) - CentOS/RHEL:
sudo yum install php-pecl-zip或dnf install php-pecl-zip - macOS(Homebrew PHP):
brew install php@8.2-zip(版本号按需替换),再检查php --ini找到配置目录,确认extension=zip.so已写入php.ini - Windows:打开
php.ini,取消;extension=zip前的分号,保存后重启 Apache/Nginx 或终端
验证系统是否有 unzip 命令并加入 PATH
即使启用了 PHP zip 扩展,某些包(尤其是含 symlink 或特殊权限的)仍依赖 unzip 命令。运行以下命令检查:
which unzip
若无输出,需安装:
- Ubuntu/Debian:
sudo apt install unzip - CentOS/RHEL:
sudo yum install unzip - macOS:
brew install unzip(或用brew install p7zip后软链,但推荐原生 unzip) - Windows:从 Info-ZIP 官网 下载
unzip.exe,放入PATH目录(如C:\Windows),或把它的路径加进系统环境变量
注意:Windows 用户容易忽略 unzip.exe 必须叫 unzip(不能是 unzip64 或带版本号),且必须能被 cmd 或 PowerShell 直接调用(即 unzip -v 能返回版本信息)。
临时绕过 zip 依赖(仅调试用,不推荐长期)
如果实在无法装 zip 扩展或 unzip,可强制 Composer 改用 tar 格式下载(packagist 多数包同时提供 .tar.gz):
composer config -g github-oauth.github.com YOUR_TOKEN # 可选,避免限流 composer config -g prefer-stable true composer config -g use-include-path false composer config -g archive-format tar
但这有局限:
- 部分私有仓库或老旧包只提供 ZIP,
archive-format tar会直接失败 - PHP
phar扩展必须启用(否则 tar 解压也会失败) - 性能略低,且非标准路径,后续升级可能意外触发 ZIP 回退
真正稳定的做法还是补上 zip 扩展和 unzip 命令——尤其在 CI/CD 环境中,漏掉任意一个都会导致构建中断,而且错误提示不指明具体缺哪个,容易反复试错。










