如何解决 "failed to extract" 解压失败的 Composer 错误？

Composer报错“failed to extract”主因是目标目录文件被占用或ZIP包损坏；应关闭IDE/编辑器、禁用实时杀毒、用Process Explorer释放句柄，清缓存（composer clear-cache），或改用git安装及tar格式。

Composer 报错 “failed to extract”，通常不是网络或权限问题，而是解压过程卡在了 ZIP 文件的某个环节——最常见原因是目标目录存在同名文件/文件夹且被占用（比如正被编辑器、IDE 或杀毒软件锁定），或者 ZIP 包本身损坏、不完整。

检查并释放被占用的文件或目录

Composer 在解压前会先清空目标目录（如 vendor/package-name），如果其中某个 .php、.json 或 .git 文件正被 VS Code、PHPStorm、Windows 资源管理器预览窗格，甚至 Windows Defender 实时扫描占用，就会导致提取失败。

• 关闭可能访问 vendor/ 的 IDE、编辑器、终端（特别是开启了文件监视的）
• 临时禁用 Windows Defender 实时保护（设置 → 病毒和威胁防护 → 实时保护 → 关闭）
• 用 Process Explorer 搜索 vendor 目录路径，看哪个进程持有了句柄，右键“Close Handle”释放

清理缓存并重试安装

Composer 缓存的 ZIP 包可能已损坏（尤其断网重试后），直接复用会导致解压校验失败。

• 运行 composer clear-cache 彻底清空本地缓存
• 删掉 vendor/ 和 composer.lock（可选，若想完全重装）
• 再执行 composer install 或 composer update

换用更稳定的下载方式（跳过 ZIP 提取）

Composer 默认从 Packagist 下载 ZIP 包再解压。若反复失败，可强制改用 git 方式克隆（前提是包支持 VCS）：

CodeGeeX

智谱AI发布的AI编程辅助工具插件，可以实现自动代码生成、代码翻译、自动编写注释以及智能问答等功能

170

查看详情

• 在 composer.json 中添加配置：
  "config": { "preferred-install": { "*": "source" } }
• 或全局设置：composer config -g preferred-install source
• 这样 Composer 会直接 git clone 仓库，绕过 ZIP 解压环节

验证 ZIP 工具与系统环境

Composer 依赖系统内置的 ZIP 工具（Windows 用 PowerShell 的 Expand-Archive，Linux/macOS 用 unzip）。某些精简版系统或旧版 PowerShell 可能缺少完整 ZIP 支持。

• Windows 用户可升级到 PowerShell 7+，或在 Composer 配置中禁用原生 ZIP：
  composer config -g archive-format tar（改用 tar 格式，兼容性更好）
• Linux/macOS 用户确保已安装 unzip：
  Ubuntu/Debian：sudo apt install unzip；macOS：brew install unzip

基本上就这些。多数情况下，关掉编辑器 + 清缓存就能解决。不必急着升级 Composer 或重装 PHP，先排查文件占用和缓存这两点，90% 的 “failed to extract” 就消失了。

以上就是如何解决 "failed to extract" 解压失败的 Composer 错误？的详细内容，更多请关注php中文网其它相关文章！