PHP GD 擴展處理圖片（驗證碼、縮略圖、水印、圖表）需要底層庫支持：**FreeType (字體)、libpng (PNG)、libjpeg (JPEG)、zlib (壓縮)**。本文記錄 CentOS/Linux 環境下從源碼編譯安裝完整依賴鏈的標準流程。
| 庫 | 推薦版本 | 下載源 |
|---|---|---|
| FreeType | 2.13.2 | https://download.savannah.gnu.org/releases/freetype/ |
| libpng | 1.6.40 | https://sourceforge.net/projects/libpng/files/libpng16/ |
| JPEG (libjpeg-turbo) | 3.0.0 | https://sourceforge.net/projects/libjpeg-turbo/files/ |
| zlib | 1.3.1 | https://zlib.net/ |
| GD (libgd) | 2.3.3 | https://github.com/libgd/libgd/releases |
# 建議安裝到 /usr/local 以便管理
export PREFIX=/usr/local
export PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig:$PREFIX/lib64/pkgconfig
export LD_LIBRARY_PATH=$PREFIX/lib:$PREFIX/lib64
export PATH=$PREFIX/bin:$PATH
cd /usr/src
wget https://zlib.net/zlib-1.3.1.tar.gz
tar xzf zlib-1.3.1.tar.gz
cd zlib-1.3.1
./configure --prefix=$PREFIX --shared
make -j$(nproc) && make install
cd /usr/src
wget https://downloads.sourceforge.net/libpng/libpng-1.6.40.tar.gz
tar xzf libpng-1.6.40.tar.gz
cd libpng-1.6.40
./configure --prefix=$PREFIX --enable-shared
make -j$(nproc) && make install
cd /usr/src
wget https://downloads.sourceforge.net/libjpeg-turbo/libjpeg-turbo-3.0.0.tar.gz
tar xzf libjpeg-turbo-3.0.0.tar.gz
cd libjpeg-turbo-3.0.0
cmake -G"Unix Makefiles" -DCMAKE_INSTALL_PREFIX=$PREFIX -DENABLE_SHARED=1
make -j$(nproc) && make install
cd /usr/src
wget https://download.savannah.gnu.org/releases/freetype/freetype-2.13.2.tar.gz
tar xzf freetype-2.13.2.tar.gz
cd freetype-2.13.2
./configure --prefix=$PREFIX --enable-shared --with-png=yes --with-zlib=yes
make -j$(nproc) && make install
cd /usr/src
wget https://github.com/libgd/libgd/releases/download/gd-2.3.3/libgd-2.3.3.tar.gz
tar xzf libgd-2.3.3.tar.gz
cd libgd-2.3.3
./configure --prefix=$PREFIX \
--with-freetype=$PREFIX \
--with-png=$PREFIX \
--with-jpeg=$PREFIX \
--with-zlib=$PREFIX \
--enable-shared
make -j$(nproc) && make install
cd /usr/src/php-8.2.x # 你的 PHP 源碼目錄
make clean 2>/dev/null
./configure \
--prefix=/usr/local/php \
--with-config-file-path=/usr/local/php/etc \
--enable-fpm \
--with-openssl \
--with-zlib=$PREFIX \
--with-jpeg=$PREFIX \
--with-png=$PREFIX \
--with-freetype=$PREFIX \
--enable-gd \
# ... 其他參數
make -j$(nproc) && make install
/usr/local/php/bin/php -m | grep gd
# gd
/usr/local/php/bin/php -i | grep -A 10 "gd support"
# gd support => enabled
# gd Version => bundled (2.3.3 compatible)
# FreeType Support => enabled
# FreeType Linkage => with freetype
# JPEG Support => enabled
# PNG Support => enabled
# WBMP Support => enabled
# XBM Support => enabled
# WebP Support => enabled (若配置 --with-webp)
| 錯誤 | 原因 | 解決 |
|---|---|---|
| configure: error: freetype-config not found | FreeType 未安裝或 pkg-config 路徑缺失 | 安裝 freetype-devel / 設置 PKG_CONFIG_PATH |
| configure: error: libpng not found | libpng 未安裝或版本過舊 | 安裝 libpng-devel ≥ 1.6 |
| gd.h: No such file or directory | libgd 未安裝或路徑錯誤 | 確認 --with-gd 指向正確，或依賴 libgd |
| undefined reference to `FT_New_Face` | FreeType 鏈接失敗 | 檢查 LD_LIBRARY_PATH 包含 freetype lib 目錄 |
| PHP 啟動警告: Unable to load dynamic library 'gd' | 編譯時 --enable-gd=shared 但運行時找不到 .so | 確認 extension_dir 正確，或改用 --enable-gd 靜態編譯 |
# CentOS/RHEL 7/8/9
yum install -y php-gd php-devel
# 或指定版本
yum install -y php82-php-gd # Remi 源
# Ubuntu/Debian
apt update && apt install -y php8.2-gd
# Alpine
apk add php82-gd
強烈建議生產環境使用系統包管理器：自動處理依賴、安全更新、版本兼容、協議合規。
本文記錄了 Linux 下手動編譯 PHP GD 完整依賴鏈（zlib → libpng → JPEG → FreeType → libgd → PHP）的標準流程。對於學習原理、特殊版本需求、離線環境有參考價值；生產環境請優先使用發行版官方 PHP GD 包。
