必须运行php -r "new ZipArchive();"不报错且php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"输出数字才证明ZipArchive类真正可用；仅php -m | grep zip有输出不代表可用，常见原因是libzip ABI不兼容、php.ini未启用extension=zip或Docker/Alpine中缺失libzip-dev。
php -m 显示 zip 但 Composer 仍报错，怎么验证真可用？
看到 php -m | grep zip 有输出，不代表 ZipArchive 类能正常实例化。很多环境是“模块名加载了，但类初始化失败”，比如 libzip 库太旧、DLL 文件缺失或版本不匹配。
必须运行这句才能确认：
php -r "new ZipArchive(); echo 'OK';"
如果报 Fatal error: Uncaught Error: Class 'ZipArchive' not found，说明扩展不可用。常见原因包括：
-
php.ini里写的是extension=php_zip.dll（Windows PHP 7.x），但你用的是 PHP 8.2 —— 正确写法应是extension=zip - Linux 下
extension_dir指向的目录里没有zip.so，或文件权限为 root:root 且 CLI 用户无读取权 - macOS Homebrew 安装多个 PHP 版本时，
php命令指向的是系统自带 PHP（没 zip），而composer又调用了它
Ubuntu/Debian 上装 php-zip 总失败？注意包名和版本绑定
硬装 sudo apt install php-zip 在多数新镜像中会失败，因为该包名在 Ubuntu 22.04+ 已被弃用，实际对应的是带主版本号的包。
立即学习“PHP免费学习笔记（深入）”；
先查清楚你的 CLI PHP 版本：
php -v
再装对应包（例如输出是 PHP 8.3.6）：
sudo apt updatesudo apt install php8.3-zip- 检查是否生成启用文件：
ls /etc/php/8.3/cli/conf.d/*zip*.ini（应存在20-zip.ini）
别跳过重启步骤：如果用 FPM，跑 sudo systemctl restart php8.3-fpm；Apache 用户则需 sudo systemctl restart apache2。CLI 模式虽不强制重启，但要关掉终端重开，否则 php --ini 仍可能缓存旧配置。
Docker 或 Alpine 镜像里 zip 扩展始终不生效？libzip 是隐形瓶颈
Alpine 默认的 libzip 版本极低（如 1.5.2-r0），即使 apk add php8-zip 成功，ZipArchive::extractTo() 也会静默失败，日志只显示 Failed to extract，加 -v 才能看到真实错误：libzip version too old。
验证方式：
-
apk list | grep libzip—— 确认是否 ≥libzip-1.9.2-r0 -
php -r "echo ZIPARCHIVE::VERSION;"—— 返回值必须 ≥10900（对应 libzip 1.9.0）
修复步骤（以 Alpine 3.20 为例）：
apk add libzip-devdocker-php-ext-install zip- 确保
docker-php-ext-enable zip已执行（部分基础镜像不自动启用）
注意：libzip-dev 必须在 docker-php-ext-install 之前安装，否则编译会 fallback 到系统旧库。
Windows 下 extension=zip 不起作用？dll 文件和依赖链缺一不可
取消 php.ini 中 ;extension=zip 的注释只是第一步。真正卡住的是文件是否存在、是否匹配架构、以及依赖是否就绪。
分三步排查：
- 运行
php --ini确认 CLI 加载的是哪个php.ini，打开它检查extension_dir路径（如C:\php\ext） - 进该目录，确认存在
zip.dll（PHP 8.0+）或php_zip.dll（PHP 7.x），且文件大小 > 100KB（空文件或 0KB 表示下载损坏） - zip 依赖
zlib，必须确保extension=zlib在extension=zip之前启用，否则new ZipArchive()会直接报错
最常被忽略的是 TS（线程安全）与 NTS（非线程安全）版本 mismatch：XAMPP 默认用 TS，而某些独立 PHP 包提供的是 NTS 版 dll —— 两者混用必然失败。
