ZipArchive::extractTo() 是 PHP 原生解压 ZIP 的核心方法，需确保目标目录存在且有写权限，手动校验路径防穿越，并检查 open() 返回值与错误码。
ZipArchive::extractTo() 是解压 ZIP 的核心方法
PHP 原生解压 ZIP 文件，最可靠的方式是用 ZipArchive 类的 extractTo() 方法。它不依赖外部命令，跨平台稳定，且能精确控制解压路径和文件过滤。
关键前提是：目标目录必须已存在且 PHP 有写权限；否则 extractTo() 会静默失败（返回 false），不会自动创建父级目录。
-
open()成功后必须检查返回值，ZIPARCHIVE::ER_NOZIP、ZIPARCHIVE::ER_READ等错误码要单独处理 - 解压前建议用
getFromName()或遍历statIndex()预检文件名，避免路径穿越（如../etc/passwd） - PHP 8.0+ 默认禁用相对路径解压，但旧版本仍需手动过滤含
../的getNameIndex()结果
完整可运行的解压代码示例
以下代码包含基础解压、错误判断、路径安全校验三要素，适用于 PHP 7.4+：
$zip = new ZipArchive();
$res = $zip->open('/path/to/archive.zip');
if ($res !== true) {
throw new RuntimeException("无法打开 ZIP 文件，错误码: $res");
}
// 创建目标目录（仅当不存在时）
$destDir = '/path/to/extract/';
if (!is_dir($destDir)) {
if (!mkdir($destDir, 0755, true)) {
throw new RuntimeException("无法创建解压目录: $destDir");
}
}
// 遍历并安全解压每个文件
for ($i = 0; $i < $zip->numFiles; $i++) {
$filename = $zip->getNameIndex($i);
// 拒绝含 ../ 或以 / 开头的路径（防路径穿越）
if (str_starts_with($filename, '/') || str_contains($filename, '../')) {
continue;
}
$fullPath = $destDir . ltrim($filename, '/');
$dir = dirname($fullPath);
if (!is_dir($dir)) {
mkdir($dir, 0755, true);
}
}
$zip->extractTo($destDir);
$zip->close();
常见错误：extractTo() 返回 false 却没报错
这是最常被忽略的问题——extractTo() 失败只返回 false，不抛异常，也不输出具体原因。
立即学习“PHP免费学习笔记（深入）”；
minimax-mcp-docker版（适配极空间）
下载
MiniMax 图片理解 + 网络搜索 MCP 工具。适配 Docker 环境（极空间等），支持图片 OCR 识别、图像内容理解、网络搜索。API Key 安全存储在本地 credentials 文件，不暴露在代码中。
排查顺序应为：
- 检查
$zip->open()返回值是否为true（不是0） - 确认
$destDir路径末尾**没有斜杠**（extractTo('dir/')在某些系统下会失败） - 用
is_writable($destDir)显式验证写权限，而非仅靠is_dir() - Windows 下注意路径分隔符，统一用
/或DIRECTORY_SEPARATOR，不要混用\
替代方案：shell_exec('unzip') 为什么通常不推荐
虽然 shell_exec('unzip ' . escapeshellarg($file)) 看似简单，但它引入了三个硬伤：
- 依赖系统安装
unzip命令，Docker 容器或精简版 Linux 可能缺失 - 无法捕获 ZIP 内部结构（比如想跳过某个子目录），只能全量解压
- 错误信息藏在
stderr里，需额外重定向和解析，exec()超时或权限拒绝时行为不可控
除非你明确需要 unzip -j 扁平化解压，或处理超大 ZIP（ZipArchive 内存占用较高），否则坚持用原生类更稳妥。
路径校验和权限检查这两步，线上环境漏掉任何一个，都可能让解压变成静默丢包。
