根本原因是 Composer 解压 ZIP 包时在 PHP 或系统层卡住，主因包括杀软拦截 php.exe 进程、ZipArchive 扩展缺失/损坏、缓存中存在损坏 ZIP 包；需分别验证白名单、扩展可用性及清缓存。
根本原因不是网络慢，而是 Composer 在下载完成后解压 ZIP 包时卡在了 PHP 层或系统层——多数情况与杀软拦截、zip 扩展缺失/损坏、缓存复用坏包直接相关。
杀毒软件拦截 php.exe 或临时解压进程
Windows 下 360、火绒、腾讯电脑管家、Windows Defender 常把 php.exe 启动的子进程（如调用 unzip、7z 或流式解压）识别为“非法操作”，直接终止，不报具体错误，只留一行“非法操作”或控制台突然中断。
- 临时验证：关闭杀软后重试，90% 立刻成功
- 长期方案：必须给两个路径加白名单：
C:\path\to\php\php.exe和C:\Users\{username}\AppData\Roaming\Composer - 别只加目录——杀软盯的是
php.exe进程本身，它负责执行解压逻辑 - 禁用管理员权限运行 CMD/PowerShell，提权反而触发更严监控
ZipArchive 类不可用或 ABI 不兼容
报错含 Class 'ZipArchive' not found 或 zip extension is missing，不代表 php -m | findstr zip 有输出就完事——模块加载 ≠ 类可用。
- 必须验证：
php -r "new ZipArchive();"不报错才算通过 - 再跑：
php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"，能输出数字才代表 libzip 版本够新、ABI 兼容 - 重点查 CLI 使用的
php.ini：php --ini查路径，确认含extension=zip（Linux/macOS）或extension=php_zip.dll（Windows） - Docker 用户注意：
php:8.2-cli-alpine默认不带 zip，得手动装zlib-dev并docker-php-ext-install zip
缓存里存着损坏的 ZIP 包，反复复用
下载阶段看似成功，但 ZIP 文件 CRC 校验失败或含 ZIP64 / 数据描述符等边缘结构，zlib_decode() 解析出错，错误堆栈里常带该函数名。这不是网络问题，是缓存污染。
- 清缓存是第一动作：
composer clear-cache - 强制跳过缓存重下：
composer install --no-cache - 关掉干扰项：
zlib.output_compression = Off（必须是字符串"Off"，不是0），PHP 8.0+ 还要设zlib.encode = "" - 最稳解法：装好
7z.exe并加入 PATH，然后用COMPOSER_UNZIP=7zip composer install
本地 ZIP 包安装失败：路径写法和仓库类型不匹配
composer require ./xxx.zip 必然报错，因为 Composer 不支持路径式 require——它会把 ./xxx.zip 当作包名去 Packagist 查询。
- 正确做法是声明
package类型仓库：dist.url必须是file:///开头的绝对路径（Windows 为file://C:/path/xxx.zip） - 压缩包内根目录必须直接含合法
composer.json，不能多套一层文件夹 - 若批量管理多个本地 ZIP，改用
artifact类型仓库，url填目录路径（如"./packages"），且 ZIP 文件名必须严格为{vendor}/{package}-{version}.zip - 改完
composer.json后，必须composer update vendor/name，install不会重新读取新仓库定义
最容易被忽略的是：杀软白名单没加 php.exe 本身、CLI 和 Web 的 php.ini 混用、缓存目录权限混乱导致后续普通用户执行失败——这些点不排查干净，换镜像或重装 PHP 都是白忙。
