PHP 編譯添加 --with-iconv 時常遇 undefined reference to libiconv_open 鏈接錯誤。本文提供兩套完整解決方案：① 官方源碼編譯 libiconv（標準解法），② Makefile 手動鏈接（快速修補），並解析根本原因與驗證步驟。
ext/iconv/.libs/iconv.o: In function `zif_iconv_mime_encode': /php-5.2.0/ext/iconv/iconv.c:1017: undefined reference to `libiconv_open' /php-5.2.0/ext/iconv/iconv.c:1031: undefined reference to `libiconv_open' ... collect2: ld returned 1 exit status make: *** [sapi/cli/php] Error 1
libiconv 可能為舊版、不完整、或僅有動態庫無靜態庫iconv.h 但鏈接階段找不到 libiconv.acd /usr/local/src wget https://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.17.tar.gz tar -zxvf libiconv-1.17.tar.gz cd libiconv-1.17 ./configure --prefix=/usr/local/libiconv make && make install
cd /path/to/php-src make clean # 重要：清除舊配置緩存 ./configure \ --with-mysql=/usr/local/mysql \ --with-freetype-dir \ --with-jpeg-dir \ --with-png-dir \ --with-zlib \ --with-curl \ --with-gd \ --enable-gd-native-ttf \ --with-apxs2=/usr/local/apache/bin/apxs \ --enable-sockets \ --with-iconv=/usr/local/libiconv # 關鍵：指定編譯安裝的路徑 make && make install
php -m | grep iconv
php -r "var_dump(iconv('UTF-8', 'GBK', '測試'));"
適用場景：系統已有 libiconv.so 但 configure 未正確鏈接，不想重新編譯 libiconv。
# 找到 EXTRA_LIBS 行（約第 77 行） EXTRA_LIBS = ... -lcrypt # 在末尾添加 -liconv EXTRA_LIBS = ... -lcrypt -liconv
make make install
-liconv 告訴鏈接器搜尋 libiconv.so / libiconv.a/usr/lib、/usr/lib64 通常已有 libiconv.so（glibc 或 GNU 提供）| 場景 | 解決方案 |
|---|---|
| CentOS 7/8 預設 glibc iconv | 通常無需額外操作，直接 --with-iconv 即可 |
| Ubuntu 缺 libiconv-dev | apt-get install libiconv-dev 後重新 configure |
| PHP 7.4+ 配置參數變更 | --with-iconv 改為 --with-iconv[=DIR]，DIR 為可選 |
| 交叉編譯/嵌入式 | 需交叉編譯 libiconv，配置 --host、--build 參數 |
| 多 PHP 版本共存 | 各版本獨立編譯，指定各自 --prefix 與 --with-iconv |
<?php
// 檢查模組載入
if (!extension_loaded('iconv')) {
die("iconv 模組未載入\n");
}
// 基礎轉換測試
$str = "中文測試";
$gbk = iconv('UTF-8', 'GBK//IGNORE', $str);
$utf8 = iconv('GBK', 'UTF-8', $gbk);
echo "原始: $str\n";
echo "GBK: " . bin2hex($gbk) . "\n";
echo "回轉: $utf8\n";
// MIME 編碼測試
$subject = "=?UTF-8?B?" . base64_encode("中文主旨") . "?=";
echo "MIME: $subject\n";
// 列支援編碼
print_r(iconv_get_encoding('all'));
?>
PHP iconv 擴充依賴 GNU libiconv 庫，**方案一（源碼編譯指定路徑）最標準、最穩定**，解決根因；**方案二（Makefile 手動鏈接）適合緊急修補**。現代 Linux 發行版通常預裝完整 libiconv，PHP 7.4+ 配置邏輯改進後問題大幅減少。建議編譯 PHP 時統一採用方案一，並將 --with-iconv=/usr/local/libiconv 納入標準編譯腳本，一勞永逸。
