PHP CLI环境缺zip扩展，需按php -v版本精确安装（如php8.2-zip），检查php --ini确认CLI配置路径，手动添加extension=zip到对应conf.d/ini文件并重启服务，最后用php -m | grep zip和composer diagnose验证。
不是 Composer 本身坏了，是 PHP CLI 环境缺 zip 扩展 —— 装完 php-zip 包后，还得确认它真被 CLI 模式加载了。
为什么 php -m | grep zip 没输出？
这说明 CLI 模式下的 PHP 根本没加载 zip 扩展。常见原因有三个：
• 安装的是 Web 版 PHP 扩展（比如 Apache 下的 php-zip），但命令行用的是另一个 PHP 实例
• 扩展已安装，但对应配置文件（如 /etc/php/*/cli/conf.d/20-zip.ini）没生成或被注释
• PHP 是编译安装的，zip.so 文件存在，但 php.ini 里没写 extension=zip
先查清楚你终端里跑的是哪个 PHP：
• php -v 看版本
• php --ini 看 CLI 加载的配置路径
• php -i | grep "Loaded Configuration File" 再核对一次
Ubuntu/Debian 上怎么装 zip 扩展？
别直接 sudo apt install php-zip 就完事。要按当前 CLI 的 PHP 版本精确安装：
• 运行 php -v，假设输出是 PHP 8.2.15
• 就执行 sudo apt install php8.2-zip（不是 php-zip）
• 装完检查：php -m | grep zip 应该有输出
• 如果仍无输出，手动创建配置：echo "extension=zip" | sudo tee /etc/php/8.2/cli/conf.d/20-zip.ini
注意：php-zip 在较新 Ubuntu 中会自动适配默认 PHP 版本，但多版本共存时极易错配 —— 必须盯住 php -v 输出的版本号。
CentOS/RHEL 7 和 8+ 安装命令不同
CentOS/RHEL 7 默认源里没有 php-zip，要用 PECL 包：
• sudo yum install php-pecl-zip
• 装完可能需手动启用：检查 /etc/php.d/zip.ini 是否存在，内容是否为 extension=zip.so
CentOS/RHEL 8+ 或 AlmaLinux：
• sudo dnf install php-zip
• 通常自动启用，但仍要跑 php -m | grep zip 验证
别跳过验证步骤 —— dnf install 成功不等于扩展就绪，有些镜像会把扩展放到 /etc/php.d/ 但没加 .ini 后缀，导致 PHP 忽略。
装完还是报 Class 'ZipArchive' not found？
这时问题不在扩展安装，而在运行环境：
• 别用 sudo composer install —— sudo 会切换到 root 用户，加载的是 root 的 PHP 配置，和你日常用的不是同一套
• 检查是否在 Docker 或 CI 中运行：基础镜像（如 php:8.2-cli）只带核心扩展，zip 得显式安装
• 运行 composer diagnose，看输出里有没有 The zip extension is missing 这一行 —— 这是最终判决依据，不是 php -v 或 composer --version 能代替的
最容易被忽略的是：某些宝塔面板或自建环境，CLI 和 FPM 用的是两份 php.ini（php-cli.ini 和 php-fpm.ini），改错文件等于白干。
