解决Composer提示“The zip extension and unzip command are both missing”的错误

14次阅读

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

解决Composer提示“The zip extension and unzip command are both missing”的错误

为什么 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 扩展,windowsphp.ini 里它常被注释掉。先确认是否加载:

php -m | grep zip

如果无输出,说明未启用。解决方式依环境而定:

  • ubuntu/debiansudo apt install php-zip,然后重启 Web 服务或 CLI PHP(无需改 php.ini)
  • centos/RHEL:sudo yum install php-pecl-zipdnf 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 环境中,漏掉任意一个都会导致构建中断,而且错误提示不指明具体缺哪个,容易反复试错。

text=ZqhQzanResources