PHP zip 擴展提供底層 ZIP 讀取功能,可實現無需 Shell 執行權限的在線解壓。本文封裝一個健壯的解壓函數,支持目標目錄創建、編碼兼容、錯誤處理、進度回調。
function unzip_basic($zipPath, $destDir = '.') {
if (!extension_loaded('zip')) return ['success' => false, 'msg' => '未安裝 zip 擴展'];
if (!file_exists($zipPath)) return ['success' => false, 'msg' => 'ZIP 文件不存在'];
$zip = zip_open($zipPath);
if (!is_resource($zip)) return ['success' => false, 'msg' => '無法打開 ZIP(可能損壞或非 ZIP 格式)'];
if (!is_dir($destDir)) mkdir($destDir, 0755, true);
$results = ['success' => true, 'files' => [], 'errors' => []];
while (($entry = zip_read($zip))) {
$name = zip_entry_name($entry);
$fullPath = $destDir . DIRECTORY_SEPARATOR . $name;
// 目錄條目
if (substr($name, -1) === '/') {
if (!is_dir($fullPath)) mkdir($fullPath, 0755, true);
continue;
}
// 文件條目
$dir = dirname($fullPath);
if (!is_dir($dir)) mkdir($dir, 0755, true);
if (zip_entry_open($zip, $entry, 'r')) {
$size = zip_entry_filesize($entry);
$content = zip_entry_read($entry, $size);
if ($content !== false) {
if (file_put_contents($fullPath, $content) !== false) {
$results['files'][] = $name;
} else {
$results['errors'][] = "寫入失敗: $name";
}
} else {
$results['errors'][] = "讀取失敗: $name";
}
zip_entry_close($entry);
} else {
$results['errors'][] = "打開條目失敗: $name";
}
}
zip_close($zip);
return $results;
}
function unzip_advanced($zipPath, $destDir = '.', $options = []) {
$defaults = [
'overwrite' => true, // 覆蓋已存在文件
'encoding' => 'UTF-8', // 文件名編碼(舊 ZIP 可能為 GBK/CP437)
'password' => null, // 加密 ZIP 密碼
'callback' => null, // 進度回調 function($current, $total, $filename)
];
$opts = array_merge($defaults, $options);
if (!class_exists('ZipArchive')) return ['success' => false, 'msg' => 'ZipArchive 類不存在'];
$zip = new ZipArchive();
$res = $zip->open($zipPath);
if ($res !== true) return ['success' => false, 'msg' => "打開失敗,錯誤碼: $res"];
if ($opts['password']) $zip->setPassword($opts['password']);
if (!is_dir($destDir)) mkdir($destDir, 0755, true);
$total = $zip->numFiles;
$results = ['success' => true, 'files' => [], 'errors' => []];
for ($i = 0; $i < $total; $i++) {
$stat = $zip->statIndex($i);
$name = $stat['name'];
// 編碼轉換(舊版 ZIP 文件名可能非 UTF-8)
if ($opts['encoding'] !== 'UTF-8') {
$name = iconv($opts['encoding'], 'UTF-8//IGNORE', $name);
}
$fullPath = $destDir . DIRECTORY_SEPARATOR . $name;
// 目錄
if (substr($name, -1) === '/') {
if (!is_dir($fullPath)) @mkdir($fullPath, 0755, true);
continue;
}
// 文件存在檢查
if (file_exists($fullPath) && !$opts['overwrite']) {
$results['errors'][] = "文件已存在(跳過): $name";
continue;
}
$dir = dirname($fullPath);
if (!is_dir($dir)) @mkdir($dir, 0755, true);
$content = $zip->getFromIndex($i);
if ($content !== false) {
if (@file_put_contents($fullPath, $content) !== false) {
$results['files'][] = $name;
} else {
$results['errors'][] = "寫入失敗: $name";
}
} else {
$results['errors'][] = "讀取失敗: $name";
}
// 進度回調
if (is_callable($opts['callback'])) {
$opts['callback']($i + 1, $total, $name);
}
}
$zip->close();
return $results;
}
// 簡單調用
$result = unzip_advanced('uploads/package.zip', 'uploads/extracted/');
if ($result['success']) {
echo "解壓成功,共 " . count($result['files']) . " 個文件";
if ($result['errors']) print_r($result['errors']);
} else {
echo "失敗: " . $result['msg'];
}
// 帶進度條(AJAX 輪詢或 WebSocket 推送)
unzip_advanced('big.zip', 'out/', [
'callback' => function($cur, $total, $file) {
// 寫入 Redis/文件/數據庫供前端查詢
file_put_contents('progress.json', json_encode([
'current' => $cur, 'total' => $total, 'file' => $file, 'percent' => round($cur/$total*100)
]));
}
]);
| 問題 | 原因與解決 |
|---|---|
| 中文文件名亂碼 | 舊 ZIP (WinRAR/舊版壓縮軟件) 用 GBK/CP437 編碼文件名。用 iconv('GBK','UTF-8',$name) 或 iconv('CP437','UTF-8',$name) 嘗試轉換 |
| 大文件解壓超時/內存溢出 | 設置 set_time_limit(0)、ini_set('memory_limit','512M');或改用 shell_exec('unzip ...')(需權限) |
| 權限錯誤 | 確保 PHP 進程用戶對目標目錄有寫入權限(chown www:www、chmod 755) |
| 加密 ZIP | ZipArchive::setPassword() 支持傳統 ZipCrypto,不支持 AES-254 加密(需 PHP 7.2+ 且編譯 libzip 1.2+) |
ZipArchive 類功能更完整(支持加密、註釋、壓縮等級),是現代 PHP 解壓首選。封裝統一入口、處理編碼兼容、提供進度回調,即可構建生產級在線解壓功能。