PHP 8 连 Oracle 失败主因是 oci8 找不到 Instant Client 库；须下载匹配版本的 basic/devel 包，解压至统一路径（如 /opt/oracle/instantclient_21_12），确保 libclntsh.so 是有效软链接，配置 LD_LIBRARY_PATH、ldconfig 注册，并启用 oci8.events=On，否则 oci_connect() 静默失败且 oci_error() 为空。
PHP 8 连接 Oracle 数据库失败，不是 PHP 版本不兼容，而是 oci8 扩展在编译或运行时根本找不到 Oracle Instant Client 库文件；常见现象包括 pecl install oci8 报 undefined symbol: OCINlsGetInfo、oci_connect() 返回 false 却无错误信息、php --ri oci8 显示 Oracle Run-time Client Library Version 为 0.0.0.0.0。
确认 Instant Client 安装路径与完整性
先下载匹配架构（x86_64 或 aarch64）和主版本（如 21、19）的 oracle-instantclient-basic 和 oracle-instantclient-devel ZIP 包，解压到统一路径，例如 /opt/oracle/instantclient_21_12。
进入该目录，执行 ls -l libclntsh* —— 必须同时看到 libclntsh.so 和 libclntsh.so.21（或对应主版本号），且前者是后者的有效软链接；若只有 .so.21 没有 .so，手动创建：ln -sf libclntsh.so.21 libclntsh.so。
这一步漏掉软链接，pecl install oci8 会静默失败，后续所有配置都白搭。
立即学习“PHP免费学习笔记（深入）”；
Linux 下编译 oci8 扩展
方法一：使用 pecl 安装（推荐）
① 确保已安装 php-dev 和构建工具：apt-get install php-dev build-essential autoconf libtool pkg-config（Debian/Ubuntu）或 yum install php-devel gcc make autoconf libtool pkgconfig（RHEL/CentOS）。
② 执行 pecl install oci8，当提示 “Please provide the path to the ORACLE_HOME directory” 时，必须输入完整路径：/opt/oracle/instantclient_21_12，不能留空、不能只填 /opt/oracle。
③ 安装完成后，检查 /etc/php/*/cli/conf.d/ 或 /usr/local/etc/php/conf.d/ 下是否生成了 oci8.ini，内容应为 extension=oci8.so。
方法二：从源码编译（适用于定制需求）
下载 oci8 源码包（如 oci8-3.3.1.tgz），解压后执行：
phpize → ./configure --with-oci8=/opt/oracle/instantclient_21_12 → make → sudo make install。
注意：configure 参数中的路径必须与 Instant Client 解压路径完全一致，大小写、末尾斜杠都不能错。
配置环境变量与系统库路径
在 CLI 环境下运行 php -r "echo getenv('LD_LIBRARY_PATH');"，输出必须包含 /opt/oracle/instantclient_21_12；若为空，说明环境变量未生效。
临时生效：export LD_LIBRARY_PATH=/opt/oracle/instantclient_21_12:$LD_LIBRARY_PATH；永久生效需写入 /etc/profile 或 ~/.bashrc，并 source 刷新。
验证系统级注册：ldconfig -p | grep clntsh。若无输出，执行：
echo "/opt/oracle/instantclient_21_12" > /etc/ld.so.conf.d/oracle.conf && ldconfig。
这一步不成功，php --ri oci8 中的 Run-time 版本永远显示 0.0.0.0.0。
启用 oci8.events 并验证错误捕获
编辑 php.ini，在 extension=oci8.so 下方添加：
oci8.events = On
oci8.default_prefetch = 100
oci8.connection_class = "WEB"
重启 PHP 服务（CLI 不需重启，但 FPM 需 systemctl restart php*-fpm）。
运行 php --ri oci8，确认输出中同时存在：
OCI8 Support => enabled
Version => 3.3.1（或对应版本）
Oracle Run-time Client Library Version => 21.12.0.0.0（与 Instant Client 主版本一致）
Eve => enabled（即 oci8.events 生效）
没有 Eve => enabled，oci_error() 就拿不到 ORA-12514、ORA-1017 等真实错误，调试将陷入盲区。
PHP 脚本连接测试与字符串写法
用 Easy Connect 格式直连，不依赖 tnsnames.ora：
$conn = oci_connect('scott', 'tiger', '//192.168.1.100:1521/XEPDB1');
如果返回 false，立即加错误捕获：
if (!$conn) {
$e = oci_error();
var_dump($e);
}
注意：database 字段不能只写 XEPDB1 或 history_162；必须带协议、IP、端口、服务名四要素，否则 OCI8 解析失败。
