Hyperf连Oracle报错90%是oci8扩展或Instant Client路径问题：需启用oci8.events=On、验证php --ri oci8中Events为enabled，并确保LD_LIBRARY_PATH（Linux）或系统PATH（Windows）正确指向Instant Client库。
Hyperf 连 Oracle 报错，90% 是 oci8 扩展没装对，或 Instant Client 路径没被 CLI 进程识别——不是 Hyperf 本身的问题，是 PHP 运行时环境缺失关键依赖。
oci_connect() 返回 false 且 oci_error() 拿不到信息？先开 oci8.events
Hyperf 基于 Swoole，运行在 CLI 模式下，而 CLI 环境默认不加载 Web 服务器（如 Apache）里可能已配好的环境变量。此时 oci_connect() 静默失败、oci_error() 返回空数组，大概率是因为扩展没开启事件监听。
必须在 php.ini 中启用：
-
oci8.events = On（否则连 ORA-12154、ORA-12541 这类 TNS 错误都捕获不到） -
oci8.default_prefetch = 100（防大结果集阻塞协程） -
extension=oci8.so（Linux）或extension=php_oci8.dll（Windows）已取消注释且路径正确
验证是否生效：运行 php --ri oci8，输出中必须含 OCI8 Support => enabled 和 Events => enabled。若 Events 显示 disabled，改完 php.ini 后必须重启终端、Swoole Worker 进程（php bin/hyperf.php start 要重跑）。
立即学习“PHP免费学习笔记（深入）”；
PHP CLI 找不到 oci.dll 或 libclntsh.so？LD_LIBRARY_PATH 不生效是常态
Web 环境能连、CLI 连不上，典型表现是报 OCIEnvNlsCreate() failed 或 Oracle Run-time Client Library Version = 0.0.0.0.0。这不是 Hyperf 的锅，是 CLI 进程根本没看到 Instant Client 库。
Linux 下必须让系统级服务（如 Swoole Worker）能稳定读到库路径：
- 确认
libclntsh.so存在：ls /opt/oracle/instantclient_21_12/libclntsh.so* - 执行
ldconfig -p | grep clntsh，看不到就说明没注册进动态链接器缓存 - 临时修复：
export LD_LIBRARY_PATH=/opt/oracle/instantclient_21_12:$LD_LIBRARY_PATH，再跑php bin/hyperf.php start - 永久修复：把路径写入
/etc/ld.so.conf.d/oracle.conf，然后执行sudo ldconfig
Windows 下同理：Instant Client 解压路径（如 C:\oracle\instantclient_21_12）必须加入**系统级 PATH**（不是用户变量），且置于其他 Oracle 路径之前；改完后关掉所有 CMD/PowerShell 窗口再重试。
pecl install oci8 失败或扩展加载报 “undefined symbol: OCINlsGetInfo”
这个错误明确指向 Instant Client 运行时库未就位或版本错配，和编译无关。
常见原因与动作：
- 下载的是
basiclite版但漏了devel（Linux）或没装Visual C++ Redistributable（Windows） -
ORACLE_HOME指向解压根目录（如/opt/oracle/instantclient_21_12），不是.../lib子目录 - Alpine 用户用
apk add oracle-instantclient-basiclite后，仍需apk add php82-dev autoconf g++ make openssl-dev，否则pecl install oci8会卡在 configure 阶段 - PHP 8.4+ 必须用独立 oci8 扩展，
pdo_oci已废弃，强行启用只会报Driver not found
验证 Instant Client 是否真可用：在命令行直接运行 sqlplus64 /nolog（Linux）或 sqlplus /nolog（Windows），能进入 SQL> 提示符才算通过基础检测。
Hyperf 配置里 connection_class 和 charset 容易被忽略
Hyperf 的 database.php 配置中，Oracle 连接参数不能只填 host/port/database。OCI8 对连接串格式敏感，且部分选项必须靠扩展原生支持：
- 连接串推荐用 Easy Connect 格式：
"localhost:1521/XE"或完整 TNS："(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=XE)))" - 必须显式设
'charset' => 'AL32UTF8'，否则中文字段可能乱码（OCI8 默认不自动探测字符集） - 若用 DRCP（数据库驻留连接池），需提前在 Oracle 端启用，并在配置中加
'connection_class' => 'WEB'，否则连接池不生效 - Hyperf 的 PDO 封装层不透传所有 oci8 参数，像
oci8.prefetch_lob_size这类需在php.ini全局设置
最隐蔽的坑是：Hyperf 启动时会预热连接，但若首次连接失败，后续请求仍可能复用失败句柄——建议在 onWorkerStart 回调里手动 oci_close() 并重建连接，而不是全靠配置自动重连。
