PHP 編譯錯誤「make: *** [sapi/cli/php] Error 1」解決方案：libiconv 連結缺失

錯誤現象

make: *** [sapi/cli/php] Error 1

發生於 make 階段建立 sapi/cli/php 時，通常為連結器找不到 libiconv 符號。

根本原因

./configure 未正確偵測 libiconv 路徑，導致 Makefile 中 EXTRA_LIBS 缺少 -liconv 參數。

解決方案一：修改 Makefile（直接但易失效）

1. 開啟 Makefile，尋找 EXTRA_LIBS 行（約第 88 行）
2. 在末尾追加 -liconv

# 修改前
EXTRA_LIBS = -lcrypt -lcrypt -lrt -lmysqlclient_r -lgd -lfreetype -lpng -lz -ljpeg -lz -lresolv -lm -ldl -lnsl -lxml2 -lz -lm -lxml2 -lz -lm -lmysqlclient_r -lz -lcrypt -lnsl -lm -lxml2 -lz -lm -lxml2 -lz -lm -lcrypt -lxml2 -lz -lm -lxml2 -lz -lm -lxml2 -lz -lm -lcrypt

# 修改後
EXTRA_LIBS = ... -lcrypt -liconv

缺點：make clean 或重新 configure 會覆蓋修改。

解決方案二：make 參數注入（推薦，持久有效）

make ZEND_EXTRA_LIBS='-liconv'

此參數會自動併入連結指令，不修改 Makefile，重新編譯依然有效。

解決方案三：configure 階段指定庫路徑（根治）

./configure \
  --with-iconv=/usr/local \
  --with-iconv-dir=/usr/local \
  LDFLAGS="-L/usr/local/lib" \
  CPPFLAGS="-I/usr/local/include" \
  ...其他參數...

確保 libiconv 開發套件已安裝：

• CentOS/RHEL：yum install libiconv-devel
• Ubuntu/Debian：apt-get install libiconv-hook-dev（或 libc6-dev 內建）
• macOS：brew install libiconv
• 源碼安裝：./configure --prefix=/usr/local && make && make install

常見衍生問題

啟動 Apache 報錯：undefined symbol: libiconv_open

原因：編譯通過但執行時找不到 libiconv 共享庫。

解決：

1. 確認 /usr/local/lib 在 /etc/ld.so.conf 或 LD_LIBRARY_PATH
2. 執行 ldconfig
3. 或編譯時靜態連結：LDFLAGS="-static -liconv"

驗證編譯結果

# 檢查 iconv 支援
php -m | grep iconv
php -r "echo iconv('UTF-8', 'BIG5', '測試');"

現代替代建議

• 使用系統套件管理器安裝 PHP：dnf install php / apt install php / brew install php
• 使用 Docker 官方映像：docker pull php:8.3-cli
• 使用預編譯二進制：php-build、phpbrew、mise
• 僅在需要極度客製化模組時才自行編譯