ZipArchive 类未找到的直接原因是 PHP 缺少 zip 扩展，需根据系统安装对应扩展并验证是否真正可用。
ZipArchive 类未找到报错怎么修
直接原因是 PHP 缺少 zip 扩展，不是 Composer 本身的问题，但会卡在 composer install 或 composer update 解压包阶段，报类似 Class 'ZipArchive' not found 的致命错误。
验证方式很简单：运行 php -m | grep zip，没输出就确认缺失；或者写一行 php -r "new ZipArchive();"，报错即实锤。
- Windows 用户：打开
php.ini，取消注释extension=php_zip.dll（注意路径下该文件必须存在） - macOS（Homebrew PHP）：运行
brew install php@8.2-zip（版本号按你实际用的换），然后重启 Web 服务或 CLI 环境 - Linux（Debian/Ubuntu）：执行
sudo apt install php-zip，再sudo systemctl restart apache2或sudo service php8.2-fpm restart - Docker 用户：在
Dockerfile中加RUN docker-php-ext-install zip，别漏了docker-php-ext-enable zip
composer install 卡在 extracting 阶段怎么办
这个现象常被误判为网络问题，其实大概率是 ZipArchive 不可用导致 Composer 回退到纯 PHP 解压逻辑，速度极慢且容易超时或内存溢出。
看日志里有没有 Failed to extract ... using ext-zip, falling back to plain PHP 这类提示——有就是根源。
- 临时绕过（不推荐长期用）：加
--prefer-source参数，让 Composer 克隆 Git 仓库而非下载 zip 包 - 更稳妥的临时方案：设环境变量
COMPOSER_DISABLE_EXTENSIONS=1，强制跳过所有扩展依赖检查（仅调试用） - 别手动删
vendor/后硬跑 —— 如果 zip 扩展仍缺失，重装过程一样卡住
PHP 版本和 zip 扩展的兼容性坑
PHP 8.0+ 默认启用 zip 扩展，但某些精简版容器镜像（如 php:8.2-cli-alpine）默认不带，得自己编译安装 libzip-dev 和 zip 扩展。
另一个隐形坑：libzip 库版本太低（比如系统自带的 0.10），会导致 Composer 解压失败并静默回退，错误信息藏在 verbose 模式里：composer install -v 才能看到 libzip version too old。
- Alpine Linux：先
apk add libzip-dev，再docker-php-ext-install zip - CentOS/RHEL：确保
libzip-devel已装，再pecl install zip，最后在php.ini加extension=zip.so - 别信
php -m显示 zip 就万事大吉——还得php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"能执行才算真可用
为什么 vendor 包有时能装上、有时又失败
因为不是所有包都走同一解压路径。Composer 对不同来源的包有策略差异：dist（zip/tar 包）强依赖 ext-zip；source（Git）则完全不经过它。
而 packagist.org 上多数包默认提供 dist，但如果你本地 composer.json 里写了 "minimum-stability": "dev"，或某个依赖指定了 "type": "package" + "dist"，就更容易撞上 zip 扩展缺失的边界情况。
- 查具体包用什么方式拉取：运行
composer show monolog/monolog --all，看dist type字段是zip还是git - CI 环境尤其要注意：GitHub Actions 的
setup-phpAction 默认不开 zip，得显式加extensions: [zip] - 别只测一个包成功就认为 OK——有些包 dist 文件小，PHP 回退解压勉强扛住；大包（如
symfony/symfony）必然崩
最麻烦的是扩展看似加载了，但底层 libzip 不支持 ZIP64 或 AES 加密压缩——这种问题不会报错，只会解压出空目录或损坏文件，得靠校验 vendor/autoload.php 是否可读来反推。
