ZipArchive 扩展缺失导致 Composer 无法解压依赖，需验证 class_exists('ZipArchive') 返回 false 后，按系统分别安装：Alpine 用 apk add php7-zip，Ubuntu/Debian 安装 php-zip，macOS 用 brew install php@x.x-zip，Windows 确保 php_zip.dll 和 zlib1.dll 均存在并启用。
Composer 安装包时提示 ZipArchive 扩展缺失，本质是 PHP 缺少对 ZIP 文件的原生解压能力，导致 composer install 或 composer update 在下载完 ZIP 包后无法解压依赖，直接报错中断。
确认 ZipArchive 是否真的未启用
别急着装扩展，先验证问题根源。运行：
php -m | grep zip
如果无输出，说明 zip 扩展没加载；但即使有 zip，也不代表 ZipArchive 类可用——它需要单独编译支持（尤其在 Alpine、CentOS 等精简环境）。更可靠的检查方式是：
php -r "var_dump(class_exists('ZipArchive'));"
返回 bool(false) 就坐实了问题。
- 常见错误信息形如：
Class 'ZipArchive' not found或Failed to extract ...: class ZipArchive not found - 不是所有 PHP 安装都默认启用该类，哪怕
extension=zip.so已写入php.ini - Docker 中用
php:alpine镜像时，默认不带zip扩展，必须手动apk add php7-zip（注意版本号匹配）
Linux（Debian/Ubuntu）下启用 ZipArchive
需同时安装 PHP ZIP 扩展及其依赖库，仅改 php.ini 无效。
- 运行
sudo apt update && sudo apt install php-zip（PHP 8.x）或php7.4-zip（具体版本查php -v） - 扩展名通常是
zip.so，安装后一般自动写入/etc/php/*/cli/conf.d/20-zip.ini，内容为extension=zip.so - 执行
php --ini确认 CLI 使用的php.ini路径，再检查对应conf.d/下是否有 zip 配置 - 重启 CLI 无需重启 Web 服务，但若在 Apache/FPM 中运行 Composer（如 CI 环境），需确保对应 SAPI 的配置也生效
macOS（Homebrew PHP）启用 ZipArchive
Homebrew 安装的 PHP 默认不含 zip 扩展，需重装或单独添加。
- 若用
php@8.2：运行brew install php@8.2-zip（Homebrew 从 4.0+ 支持扩展包语法） - 旧版 Homebrew 可能需
brew reinstall php@8.2 --with-zip（但该参数已弃用，不推荐） - 安装后检查
$(brew --prefix php@8.2)/lib/php/pecl/是否存在zip.so，并在php.ini中加extension="zip"（无需路径，PHP 会自动查找） - 注意：MAMP、XAMPP 等集成环境自带 PHP，其
php.ini和扩展路径独立，不能依赖系统 brew 配置
Windows（WAMP/XAMPP）启用 ZipArchive
Windows 下最常被忽略的是 php_zip.dll 依赖的 zlib1.dll 缺失或版本不匹配。
- 打开
php.ini，取消注释;extension=php_zip.dll→ 改为extension=php_zip.dll - 确认
php_zip.dll文件真实存在于ext/目录下（路径由extension_dir指定） - 检查
php.ini中是否已启用extension=php_zlib.dll（ZipArchive依赖 zlib） - 若仍报错，把 PHP 安装目录下的
zlib1.dll复制到Windows/System32（64 位系统）或Windows/SysWOW64（32 位 PHP）——这是 Windows DLL 加载路径机制导致的典型坑
ZipArchive 不是“开了扩展就万事大吉”的模块，它对底层 zlib 库、PHP 编译选项、操作系统 ABI 兼容性都有隐式要求。尤其在容器和跨平台部署中，务必用 class_exists('ZipArchive') 做最终验证，而不是只看 php -m 输出。
