“requires ext-zip”报错本质是ZipArchive类不可用，因项目依赖声明了ext-zip但PHP未启用zip扩展；需验证class_exists('ZipArchive')、确认CLI与Web的php.ini路径并重启对应服务。
“requires ext-zip” 报错的本质是 ZipArchive 类不可用
Composer 报这个错，不是它自己缺 zip，而是你项目里某个包（比如 phpoffice/phpspreadsheet、maennchen/zipstream-php）在 composer.json 的 require 里声明了 "ext-zip": "*" —— 它运行时必须调用 ZipArchive 类。PHP 没加载 zip 扩展，类就不存在，Composer 在安装前就会拦截并报错。
注意：报错不等于“zip 扩展没装”，更常见的是“装了但没启用”，或 CLI 和 Web 使用的 php.ini 不同。
- 验证是否真缺失：
php -m | grep -i zip
——无输出即未启用 - 更准的验证方式（绕过模块名拼写误差）：
php -r "echo class_exists('ZipArchive') ? 'OK' : 'Missing';" - 查清楚当前 CLI 用的是哪个配置：
php --ini
，重点看 “Loaded Configuration File” 路径
Linux/macOS 下 zip 扩展启用的实操差异
Ubuntu/Debian 默认不启 zip，但装包后无需改 php.ini；macOS Homebrew 安装 PHP 时通常自带 zip.so，但可能没写进 php.ini；CentOS/RHEL 则常需手动启用扩展文件。
- Ubuntu/Debian（PHP 8.2 示例）：
sudo apt install php8.2-zip
，装完立刻生效，不用改配置，但要重启 PHP-FPM：sudo systemctl restart php8.2-fpm
- CentOS/RHEL（含 AlmaLinux）：
sudo dnf install php-pecl-zip
，装完需确认/etc/php.d/zip.ini存在且内容为extension=zip - macOS + Homebrew（PHP 8.1）：
brew install php@8.1-zip
，然后检查php.ini是否有extension="zip.so"；若没有，手动加一行（路径用brew --prefix php@8.1查）
Windows 用户最容易忽略的两个细节
不是取消 ;extension=zip 就万事大吉——XAMPP/WAMP 的 php.ini 有两个位置（Apache 和 CLI 各一份），而且 php_zip.dll 文件必须真实存在。
- 先确认 DLL 文件是否存在：
dir "%PHP_HOME%\ext\php_zip.dll"
（把%PHP_HOME%替换成你的 PHP 目录），若不存在，得重装对应版本的 PHP 或从官方二进制包里复制 - CLI 和 Apache 可能用不同
php.ini：php --ini
看 CLI 配置路径，phpinfo()页面看 Apache 加载的是哪个，两者都得改 - 改完别只点 Apache 重启按钮——关掉命令行终端再新开一个，否则
composer install还是读旧环境
临时绕过 zip 依赖只适用于调试，不能当解决方案
用 --ignore-platform-reqs 强装，或设 archive-format tar，只是让 Composer 跳过校验或换种下载方式，但运行时只要代码调用了 ZipArchive，照样报 Class 'ZipArchive' not found。
- 仅限快速验证是否真是 zip 问题：
composer install --ignore-platform-reqs
- 强制用 tar 包（需 Packagist 支持）：
composer config -g archive-format tar
，但很多私有包或 GitHub repo 不提供 tarball，会 fallback 失败 - 真正修复永远只有一条路：让
class_exists('ZipArchive')返回TRUE，其他都是障眼法
最常被卡住的地方不是不会装，而是装完没重启服务、CLI 和 Web 配置不一致、或者压根没意识到 php --ini 和 phpinfo() 显示的不是同一个 php.ini。验证务必用 php -r 命令，而不是只信 php -m 输出。
