需安装并启用 php zip 扩展：先运行 php -m | grep zip 确认缺失，ubuntu/debian 执行 sudo apt install php-zip，centos/rhel 用 sudo yum install php-zip 并检查 /etc/php.d/zip.ini，docker 或 mac m1/m2 用户需确保对应 php 版本的 zip 扩展已正确安装并启用。
composer install 报错 “ZipArchive not found” 怎么办
这是 PHP 缺少 zip 扩展导致的，不是 Composer 本身的问题，但会直接卡住依赖安装。Composer 在解压包（比如从 packagist 下载 .zip 归档）时，必须用到 ZipArchive 类——而它只在 php-zip 扩展启用后才存在。
常见错误现象：
- Class 'ZipArchive' not found
- Failed to extract vendor/package: unable to create archive
- Could not decompress the package, no zip extension loaded
- 先确认是否真没装：
php -m | grep zip，没输出就说明缺失 - 别急着重装 PHP 或换 Docker 镜像——90% 情况下只是扩展没启用或没编译进当前 SAPI
- CLI 和 Web（如 Apache/FPM）的 PHP 配置可能不同，
php -m查的是 CLI，但composer install通常也走 CLI，所以优先盯这里 - 如果用的是 Ubuntu/Debian：
sudo apt install php-zip后，一般会自动启用；CentOS/RHEL 用sudo yum install php-zip（或dnf），但需手动检查/etc/php.d/zip.ini是否存在且未被注释
php-zip 扩展装了却 still not found？检查 ini 加载路径和 SAPI 差异
装了包不等于扩展生效。PHP 的 extension_dir、extension=zip.so 加载顺序、以及 CLI/FPM 使用的 php.ini 文件可能完全不同。
- 运行
php --ini看 CLI 加载的配置文件路径，打开对应php.ini，确认有extension=zip（或extension=zip.so）且未被分号注释 - 如果用的是多版本 PHP（如通过
update-alternatives或 asdf），php命令和composer调用的可能是不同版本，执行composer run-script --no-dev show-php-version或直接php -v对齐版本 - Docker 用户注意：
php:apache和php:cli镜像默认启用项不同，php:cli通常不带 zip，得自己RUN docker-php-ext-install zip - Windows 用户：检查
php.ini中;extension=php_zip.dll是否已去掉分号，且php_zip.dll确实存在于ext/目录下
不想装扩展？临时绕过 ZipArchive 依赖（仅限开发/调试）
某些旧项目或 CI 环境里，快速验证逻辑时可跳过 zip 解压流程，但这是权宜之计，不能用于生产。
- 用
--prefer-source：强制 clone Git 仓库而非下载 zip 包，composer install --prefer-source—— 要求包有source类型定义且网络可达 - 设环境变量禁用 zip：
COMPOSER_DISABLE_XZ=1 COMPOSER_DISABLE_ZIP=1 composer install，部分版本支持，但 Composer 2.2+ 已移除该开关，慎用 - 改用
dist回退机制失败时的兜底行为不可控，不如直接装扩展来得稳 - 如果你在 GitHub Actions 或 GitLab CI 里遇到，直接在 job step 中加装扩展比绕行更可靠，例如 Ubuntu 上加一行：
sudo apt-get update && sudo apt-get install -y php-zip
Mac M1/M2 上 brew 安装 php 后 zip 扩展不工作
brew 安装的 PHP（如 php@8.2）默认不启用 zip 扩展，且扩展路径和配置位置与系统 PHP 不同，容易混淆。
- 先查扩展路径：
php -r "echo ini_get('extension_dir');"，通常是类似/opt/homebrew/lib/php/pecl/20220829的路径 - 确认 zip.so 存在：
ls /opt/homebrew/lib/php/pecl/20220829/zip.so，若无，运行brew install php@8.2-zip（版本号对齐） - 编辑 brew 的 php.ini：
$(brew --prefix php)/lib/php.ini，添加一行extension="zip"（不需要写 .so） - 注意：M1/M2 上
pecl install zip很可能失败，因为缺少 libzip 开发头文件，应先brew install libzip再重试
最常被忽略的一点：改完 php.ini 后，必须重启终端或重新加载 shell 配置，否则 php -m 仍显示旧状态。别信“改了就生效”，PHP CLI 不读缓存，但你的 shell 可能还记着旧的 alias 或 PATH。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
