PHP ZipArchive "Class not found" 徹底解決方案：Windows/Linux/Docker 全環境覆蓋

錯誤根因

Fatal error: Class 'ZipArchive' not found 表示 **PHP 未加載 zip 擴展**。ZipArchive 非核心內置，需額外編譯/安裝 php_zip (Windows) 或 zip.so (Linux)。

環境判斷命令

php -m | grep -i zip      # Linux/Mac
php -r "phpinfo();" | grep zip  # 通用
# 輸出有 zip 則已加載，無則需安裝

方案一：Windows (PHP 7.2+ / 8.x)

1. 啟用內置 DLL (推薦)

1. 打開 php.ini (用 php --ini 確認路徑)
2. 搜索 ;extension=zip 或 ;extension=php_zip.dll
3. 去掉分號：extension=zip
4. 重啟 Web 服務：net stop w3svc && net start w3svc (IIS) 或重啟 Apache/Nginx + PHP-FPM

PHP 7.2+ 將擴展名統一為 zip (無 php_ 前綴)，舊教程寫 php_zip.dll 可能不生效。

2. 手動下載 DLL (極少數精簡版 PHP)

• 去 PECL 官網 下載對應 **PHP 版本**、**TS/NTS**、**x86/x64** 的 zip 包
• 解壓 php_zip.dll 到 ext 目錄
• 按步驟 1 啟用

方案二：Linux (Ubuntu/Debian/CentOS/Alpine)

Ubuntu / Debian (apt)

# PHP 8.2 示例
sudo apt update
sudo apt install php8.2-zip   # 自動啟用並重載 php-fpm
# 或通用
sudo apt install php-zip      # 安裝默認版本

# 驗證
php -m | grep zip

CentOS / RHEL / Rocky / Alma (yum/dnf)

# 啟用 Remi 源 (獲取新版 PHP)
sudo dnf install https://rpms.remirepo.net/enterprise/remi-release-9.rpm
sudo dnf module enable php:remi-8.2
sudo dnf install php-zip php-pecl-zip  # 兩個包名嘗試

# 重載
sudo systemctl restart php-fpm

Alpine (Docker 常用)

# Dockerfile
RUN apk add --no-cache libzip-dev \
    && docker-php-ext-install zip
# 或 PECL
RUN apk add --no-cache libzip-dev \
    && pecl install zip \
    && docker-php-ext-enable zip

通用源碼編譯 (無包管理器/特殊版本)

# 1. 安裝依賴
# Ubuntu: apt install libzip-dev
# CentOS: yum install libzip-devel

# 2. 下載對應 PHP 版本源碼包中的 ext/zip 目錄，或 PECL
cd /usr/src
wget https://pecl.php.net/get/zip-1.22.1.tgz  # 版本匹配 PHP
tar xzf zip-1.22.1.tgz
cd zip-1.22.1

# 3. phpize 編譯
/usr/local/php/bin/phpize  # 指定 phpize 路徑
./configure --with-php-config=/usr/local/php/bin/php-config --with-libzip
make -j$(nproc)
sudo make install

# 4. 啟用
echo "extension=zip.so" > /usr/local/php/etc/conf.d/zip.ini
# 或編輯 php.ini
sudo systemctl restart php-fpm

方案三：Docker 環境 (最佳實踐)

# Dockerfile (官方 php:8.2-fpm 為例)
FROM php:8.2-fpm

# 安裝系統依賴 + PHP 擴展
RUN apt-get update && apt-get install -y --no-install-recommends \
        libzip-dev \
    && docker-php-ext-install -j$(nproc) zip \
    && rm -rf /var/lib/apt/lists/*

# 驗證構建時
RUN php -m | grep -q zip && echo "ZipArchive OK"

注意：docker-php-ext-install 腳本會自動處理 phpize、configure、make、make install 並啟用，是**官方推薦方式**。

方案四：共享主機/無權限環境 (Composer Polyfill)

若無法安裝擴展，可用純 PHP 實現的替代庫（功能受限、性能較差）：

composer require php-zip/php-zip
# 或 老牌
composer require chumper/zipper

<?php
use PhpZip\ZipFile;

// 建立 ZIP
$zipFile = new ZipFile();
$zipFile->addFile('content.txt', 'Hello World');
$zipFile->saveAs('demo.zip');

// 解壓
$zipFile = new ZipFile();
$zipFile->openFile('demo.zip');
$zipFile->extractTo('/target/dir');
?>

驗證代碼 (通用)

<?php
// test_zip.php
if (!class_exists('ZipArchive')) {
    die("❌ ZipArchive 未加載\n");
}
echo "✅ ZipArchive 可用\n";

$zip = new ZipArchive();
$file = __DIR__ . '/test_' . time() . '.zip';
if ($zip->open($file, ZipArchive::CREATE) !== true) {
    die("❌ 無法創建: $file\n");
}
$zip->addFromString('hello.txt', 'Hello ZipArchive @ ' . date('c'));
$zip->close();
echo "✅ 創建成功: $file\n";

// 解壓測試
$zip2 = new ZipArchive();
if ($zip2->open($file) === true) {
    $zip2->extractTo(__DIR__ . '/unzip_test');
    $zip2->close();
    echo "✅ 解壓成功\n";
}
@unlink($file);
@rmdir(__DIR__ . '/unzip_test');
?>

常見坑避雷

現代替代：使用 CLI 工具 (大文件/高性能)

PHP 進程內壓縮大文件易 OOM/超時，建議調用系統 zip/7z：

<?php
function zipDirectory(string $source, string $dest, int $compressionLevel = 6): bool
{
    $source = realpath($source);
    if (!$source || !is_dir($source)) return false;

    $cmd = sprintf(
        'cd %s && zip -r -%d %s . 2>&1',
        escapeshellarg($source),
        $compressionLevel,
        escapeshellarg($dest)
    );
    exec($cmd, $output, $code);
    return $code === 0;
}

// 解壓
function unzipFile(string $zipPath, string $dest): bool
{
    $cmd = sprintf('unzip -o %s -d %s 2>&1', escapeshellarg($zipPath), escapeshellarg($dest));
    exec($cmd, $output, $code);
    return $code === 0;
}
?>

總結： 95% 情況下，Linux 用包管理器安裝 php-zip，Windows 去掉 php.ini 分號，Docker 用 docker-php-ext-install zip 即可解決。剩下 5% 看編譯錯誤日誌補依賴。