PHP 連接 Oracle 必須安裝 Instant Client 基礎套件與 OCI8 擴充模組。本文記錄 CentOS/RHEL 環境下從 RPM 安裝到 PHP 整合的完整流程，並釐清版本對應、路徑配置、常見坑點。
x86_64 RPM；32 位元 → i386。oci8-1.4.x，PHP 7.0~7.1 用 oci8-2.0.x，PHP 7.2+ 用 oci8-2.1.x/2.2.x。oracle-instantclient-basic-10.2.0.4-1.x86_64.rpm oracle-instantclient-devel-10.2.0.4-1.x86_64.rpm oracle-instantclient-sqlplus-10.2.0.4-1.x86_64.rpm
# 1. 安裝 Instant Client RPM
rpm -ivh oracle-instantclient-basic-10.2.0.4-1.x86_64.rpm \
oracle-instantclient-devel-10.2.0.4-1.x86_64.rpm \
oracle-instantclient-sqlplus-10.2.0.4-1.x86_64.rpm
# 安裝後庫檔通常在 /usr/lib/oracle/10.2.0.4/client64/lib/
# 2. 系統層依賴
yum install -y libaio gcc make
# 3. 下載並編譯 OCI8（PHP 5.3 範例）
cd /usr/local/src
wget https://pecl.php.net/get/oci8-1.4.10.tgz # PHP 5.3~5.6 適用
tar zxvf oci8-1.4.10.tgz && cd oci8-1.4.10
# 關鍵：phpize 必須屬於目標 PHP
/usr/local/php5/bin/phpize
# 關鍵：configure 指定 Instant Client SDK 路徑
./configure \
--with-php-config=/usr/local/php5/bin/php-config \
--with-oci8=instantclient,/usr/lib/oracle/10.2.0.4/client64/lib
make && make install
# make install 輸出會顯示模組安裝路徑，例：
# Installing shared extensions: /usr/local/php5/lib/php/extensions/no-debug-zts-20090626/
; 建立獨立擴充目錄（方便管理） extension_dir = "/usr/local/php5/lib/extensions" ; 或直接指向 make install 輸出路徑 ; extension_dir = "/usr/local/php5/lib/php/extensions/no-debug-zts-20090626" extension = oci8.so ; Oracle 環境變數（避免 ORA-12705 等字元集錯誤） ; 建議在 Apache 啟動腳本 /etc/profile.d/oracle.sh 設定 ; export NLS_LANG=AMERICAN_AMERICA.AL32UTF8 ; export LD_LIBRARY_PATH=/usr/lib/oracle/10.2.0.4/client64/lib:$LD_LIBRARY_PATH oci8.privileged_connect = On
# 建立系統級設定檔 cat > /etc/profile.d/oracle.sh <<'EOF' export ORACLE_HOME=/usr/lib/oracle/10.2.0.4/client64 export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH export NLS_LANG=AMERICAN_AMERICA.AL32UTF8 EOF chmod +x /etc/profile.d/oracle.sh source /etc/profile.d/oracle.sh # Apache 啟動腳本同步引入（或重啟前 source） echo 'source /etc/profile.d/oracle.sh' >> /usr/local/apache2/bin/envvars
/usr/local/apache2/bin/apachectl restart # 瀏覽器開啟 info.php 搜尋 "oci8" 應看到支援資訊
| 錯誤 | 原因 | 解決 |
|---|---|---|
| ORA-12154: TNS:could not resolve the connect identifier | tnsnames.ora 未設定或路徑錯誤 | 建立 $ORACLE_HOME/network/admin/tnsnames.ora 或使用 Easy Connect 字串 host:port/service |
| ORA-12705: Cannot access NLS data files | 字元集環境變數缺失 | 設定 NLS_LANG=.AL32UTF8 (注意前導點號) |
| ld.so: oci8.so: undefined symbol: OCISessionBegin | Instant Client 版本與 OCI8 編譯期不符 | 重新編譯 OCI8，確認 --with-oci8 指向正確 SDK 路徑 |
| PHP Warning: PHP Startup: Unable to load dynamic library 'oci8.so' | LD_LIBRARY_PATH 未在 Apache 啟動前生效 | 在 /usr/local/apache2/bin/envvars 或 systemd unit 加入 Environment=LD_LIBRARY_PATH=... |
若專案使用 PDO，需額外編譯 pdo_oci：
cd /usr/local/src/php-5.3.21/ext/pdo_oci /usr/local/php5/bin/phpize ./configure --with-php-config=/usr/local/php5/bin/php-config --with-pdo-oci=instantclient,/usr/lib/oracle/10.2.0.4/client64,10.2.0.4 make && make install # php.ini 加入 extension=pdo_oci.so
OCI8 安裝核心在於「版本對齊、路徑精準、環境變數早載入」。建議將上述步驟封裝為 Ansible/Shell 腳本納入基礎設施代碼，避免手動操作導致環境不一致。
