OCI8编译失败主因是运行时找不到Oracle客户端库，需确认ldconfig能列出libclntsh.so、环境变量在PHP进程中生效、解压路径下存在该库；静默失败多因oci8.events=On未开启或库未加载。
oci8扩展编译失败：找不到libclntsh.so或OCINlsGetInfo
根本不是PHP版本问题，而是运行时压根没找到Oracle客户端库。pecl install oci8成功只说明编译通过，不代表能用。
必须确认三件事：
-
ldconfig -p | grep libclntsh能列出对应版本的共享库（如libclntsh.so.21） -
ORACLE_HOME和LD_LIBRARY_PATH环境变量在 PHP 进程中生效（CLI 下php -r 'print_r($_ENV);'查看；FPM 下需在php-fpm.conf或 pool 配置里用env[LD_LIBRARY_PATH]显式透传） - Instant Client 解压路径下确实存在
libclntsh.so（不是libclntsh.so.21的软链接缺失——某些 Alpine 或精简版 ZIP 会漏掉这个符号链接）
常见静默失败现象：oci_connect() 返回 false，oci_error() 拿不到任何信息——大概率是 oci8.events = On 没开，或 libclntsh.so 根本没加载。
ThinkPHP中连接Oracle：别碰tnsnames.ora，用Easy Connect语法
ThinkPHP 的 Db::connect() 或配置文件里写 host/port/database 字段时，database 不是 SID，也不是服务名缩写，而是完整 Easy Connect 字符串。
立即学习“PHP免费学习笔记（深入）”；
正确写法示例（直接生效，不依赖 tnsnames.ora）：
'database' => '//10.1.197.1:1521/ORCLPDB1', // 推荐，最轻量 'database' => '//db-server:1521/XE', // XE 默认实例
错误写法（除非你显式设置了 TNS_ADMIN 并验证过路径）：
-
'database' => 'history_162'（假设tnsnames.ora里定义了该别名） -
'database' => 'ORCLPDB1'（缺协议和地址，OCI8 无法解析）
如果非要用 tnsnames.ora，必须在连接前执行：putenv('TNS_ADMIN=/opt/oracle/instantclient_21_12/network/admin');，且该路径下必须有可读的 tnsnames.ora 文件。
OCI8连接类参数：connection_class 和 default_prefetch 必设
ThinkPHP 底层调用 oci_connect() 时，若不传 $connection_class，DRCP（数据库驻留连接池）就无法启用，高并发下连接数暴涨。
在 ThinkPHP 的数据库配置中，应显式补充 OCI8 特有选项：
'params' => [
'connection_class' => 'WEB',
'default_prefetch' => 100,
],
其中：
-
connection_class值必须与 Oracle 侧 DRCP 池名一致（默认是WEB），否则oci_connect()会退化为普通连接 -
default_prefetch控制每次网络往返拉取多少行，默认是 1，查大表时极易卡死；设为 100 可显著降低 round-trip 次数 - 别信
oci8.connection_class写进php.ini就全局生效——ThinkPHP 使用长连接池时，oci_connect()的第三个参数（$charset）之后才是选项数组，ini 设置不覆盖
Alpine / TRAE / phpEnv 等特殊环境：Basic Lite 是唯一可行路径
标准 RPM 或 Windows 完整版 Instant Client 在这些环境里基本必挂。原因很实在：它们要么缺 musl 兼容库，要么不提供 TS 版 DLL，要么 PATH 加载顺序错乱。
必须切换到精简版：
- Alpine：
apk add oracle-instantclient-basiclite（仅部分镜像源支持），或手动下载instantclient-basiclite-linux.x64-21*.zip，解压后确保libclntsh.so存在且ldd能解析所有依赖 - phpEnv（Windows）：必须用
instantclient-basiclite-windows.x64-*.zip，内含oraociei21.dll（不是oraociei12.dll），并确认 PHP 是-ts版本 - TRAE（Docker）：不能挂载宿主机
/opt/oracle，必须把 Instant Client 打进镜像，并在php-fpm.conf中透传ORACLE_HOME和LD_LIBRARY_PATH
最容易被忽略的一点：这些环境里 tnsping 或 sqlplus 能通 ≠ PHP 能通——因为 CLI 和 FPM 进程的环境变量隔离，FPM 往往根本看不到你配好的 LD_LIBRARY_PATH。
