Windows Server 下 PHP GD 庫啟用失效排查指南

現象描述

在 Windows Server（IIS + PHP CGI/FastCGI）環境中，`php.ini` 已啟用 `extension=gd`，但 `phpinfo()` 輸出的 **Configure Command** 中未顯示 GD 相關編譯參數，且 `gd_info()` 報錯「未定義函數」。

常見原因與解決

1. 擴展文件缺失或版本不匹配

• PHP 官方 Windows 包已內置 `php_gd2.dll`（PHP 7.2+ 為 `php_gd.dll`），需確認 `extension_dir` 指向的目錄下存在該文件。
• 若手動下載 DLL，必須匹配 **PHP 版本、線程安全性、VC 編譯器版本、位數**。例如：`php_gd-8.2-nts-vs16-x64.dll`。

2. 依賴庫缺失

GD 依賴外部庫：`libpng`、`libjpeg`、`freetype`、`libwebp`、`libxpm`、`libavif` 等。Windows 版 PHP 官方構建已將這些庫**靜態鏈接**進 DLL，**無需額外 DLL**。但若使用第三方構建（如 `php.net` 非官方鏡像），可能需將依賴 DLL 放入 `extension_dir` 或系統 `PATH` 目錄。

3. php.ini 未生效

• 運行 `php --ini` 確認加載的配置文件路徑。
• IIS/FastCGI 修改 `php.ini` 後**必須重啟 PHP 進程**（回收應用程序池或重啟 `php-cgi.exe` 進程）。
• 檢查 `extension=gd` 前無分號 `;`，且 `extension_dir` 正確（建議用絕對路徑 `C:/php/ext`）。

4. Configure Command 不顯示 GD 是正常現象

**Configure Command 僅反映源碼編譯時的參數**。Windows 官方二進制包是預編譯好的，GD 以共享擴展形式編譯，**不會出現在 Configure Command 中**。判斷 GD 是否啟用的標準是：

• `phpinfo()` 頁面出現 **gd** 區塊（顯示 GD Version、FreeType Support、JPEG/PNG/WebP Support 等）。
• `php -m | findstr gd` 命令行輸出 `gd`。
• `var_dump(gd_info());` 返回數組而不報錯。

快速驗證腳本

<?php
// test_gd.php
if (!extension_loaded('gd')) {
    die("GD 擴展未加載\n");
}
$info = gd_info();
echo "GD Version: {$info['GD Version']}\n";
echo "FreeType: " . ($info['FreeType Support'] ? 'Yes' : 'No') . "\n";
echo "JPEG: " . ($info['JPEG Support'] ? 'Yes' : 'No') . "\n";
echo "PNG: " . ($info['PNG Support'] ? 'Yes' : 'No') . "\n";
echo "WebP: " . ($info['WebP Support'] ? 'Yes' : 'No') . "\n";

// 實際繪圖測試
$im = imagecreatetruecolor(200, 100);
$white = imagecolorallocate($im, 255, 255, 255);
$red   = imagecolorallocate($im, 255, 0, 0);
imagefilledrectangle($im, 0, 0, 199, 99, $white);
imagestring($im, 5, 50, 40, 'GD OK', $red);
header('Content-Type: image/png');
imagepng($im);
imagedestroy($im);
?>

排查清單

1. 確認 `extension_dir` 指向正確目錄（含 `php_gd.dll`）。
2. 確認 `php.ini` 有 `extension=gd` 且無分號。
3. 重啟 IIS 應用程序池 / `php-cgi.exe` 進程。
4. 瀏覽器訪問 `test_gd.php` 或 CLI 執行 `php test_gd.php`。
5. 若仍失效，查看 PHP 錯誤日誌（`php_errors.log` 或 Windows 事件查看器）是否有 `Unable to load dynamic library 'gd'`。

總結

Windows 下 GD 啟用核心在於：**正確的 DLL + 正確的 php.ini + 進程重啟**。Configure Command 無 GD 參數**不代表未啟用**，請以 `gd_info()` 為準。