必须运行php -r "new ZipArchive(); echo 'OK';"验证，报Class 'ZipArchive' not found即实锤缺失；再用php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"确认libzip版本是否达标，php --ini查CLI实际加载的php.ini路径，避免Web与CLI配置混淆。
直接装不上，因为 Composer 解压依赖包时硬依赖 ZipArchive 类，不是可选功能——没它就卡在 extracting 阶段，报 Class 'ZipArchive' not found 或 zip extension is missing。
怎么确认 zip 扩展真不可用，而不是“看着有实则废”
别信 php -m | grep zip 有输出就安心。很多环境扩展名加载了，但类初始化失败。必须运行：
php -r "new ZipArchive(); echo 'OK';"
如果报 Fatal error: Uncaught Error: Class 'ZipArchive' not found，就是实锤缺失。还可用这句验证更底层支持：
php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"
报错说明 libzip 库太旧或没编译进扩展（常见于 Alpine 或自编译 PHP）。
-
php -i | grep "zip support"返回zip support => disabled或无输出，也说明未启用 -
php --ini查清楚 CLI 模式实际加载的php.ini路径，Web 和 CLI 的配置常不一致 - 尤其 CI 环境（如 GitHub Actions 的
ubuntu-latest），默认 PHP 不带 zip，php -m里根本没这一行
Ubuntu/Debian 下安装 php-zip 的关键细节
包名必须和当前 PHP 主版本严格匹配，硬写 php-zip 基本失败：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- PHP 8.2 → 装
php8.2-zip - PHP 7.4 → 装
php7.4-zip - 装完后检查
/etc/php/*/cli/conf.d/20-zip.ini是否存在，内容应为extension=zip - CLI 模式不用重启服务，但 FPM 或 Apache 用户必须重启对应进程：
sudo systemctl restart php8.2-fpm或sudo systemctl restart apache2
如果装完仍不生效，运行 find /usr -name "zip.so" 2>/dev/null 定位文件，再在 php.ini 中写绝对路径，例如：extension=/usr/lib/php/20220829/zip.so。
CentOS/RHEL/Rocky Linux 容易踩的命名坑
这些系统没有 php-zip 这个包，正确名称是 php-pecl-zip，且依赖 EPEL 源：
- 先启用 EPEL：
sudo dnf install epel-release（RHEL 8+/Rocky 8+）或sudo yum install epel-release（旧版） - 再安装：
sudo dnf install php-pecl-zip - 装完检查
/etc/php.d/zip.ini是否存在，内容应为extension=zip；若无，手动创建 - 某些最小化镜像连系统级
unzip命令都没装，Composer fallback 时会卡住，顺手补上：sudo dnf install unzip
注意：RHEL 7 的 php-pecl-zip 实际依赖 libzip 0.11+，若系统自带 libzip 太老（如 0.10），需先升级 libzip-devel 再重装扩展。
Docker Alpine 镜像里 zip 扩展必须手动装
Alpine 默认精简到极致，php:8.2-cli-alpine 这类镜像完全不带 zip 扩展，php -m 永远看不到 zip：
- 先装依赖：
apk add libzip-dev（编译所需） - 再装扩展：
docker-php-ext-install zip（注意不是apk add php8-zip，后者在较新 Alpine 版本中已弃用） - 扩展装完必须启用：
docker-php-ext-enable zip - 确保
libzip版本 ≥ 1.6.0，否则解压大包时静默失败，加-v参数才能看到libzip version too old提示
别跳过 docker-php-ext-enable —— docker-php-ext-install 只编译不启用，很多 Dockerfile 漏掉这步，导致白装。
