在 linux 上安装 php oci8 扩展时，若出现 “oracle instant client sdk header files not found” 错误，根本原因是仅安装了基础运行时库（basic package），而未安装配套的开发包（devel package），后者提供编译所需的头文件（如 `oci.h`、`oratypes.h` 等）。
该错误与 oracle_HOME 设置无关——OCI8 的 pecl install 过程依赖的是 Instant Client 的 SDK 头文件路径，而非传统 Oracle 数据库的 $ORACLE_HOME。系统在 /usr/lib/oracle/19.11/client64/lib 找到了基础库，但默认不会在此目录下放置头文件；它们实际位于 devel 包解压后的 sdk/include/ 子目录中。
✅ 正确解决步骤如下：
-
确认已安装的 Instant Client 版本（例如 19.11）：
ls -l /usr/lib/oracle/ # 输出示例：19.11/client64/ -
下载并安装严格匹配的 devel 包（必须与 basic 版本完全一致，包括 Release Update 小版本）：
✅ 推荐使用最新 RU（Release Update），如 19.14（比 19.11 更新且兼容），从 Oracle 官方下载页 获取：- oracle-instantclient19.14-basic-19.14.0.0.0-1.x86_64.rpm
- oracle-instantclient19.14-devel-19.14.0.0.0-1.x86_64.rpm
-
安装 RPM 包（以 RHEL/centos/Almalinux 为例）：
sudo rpm -ivh oracle-instantclient19.14-basic-19.14.0.0.0-1.x86_64.rpm sudo rpm -ivh oracle-instantclient19.14-devel-19.14.0.0.0-1.x86_64.rpm⚠️ 注意：devel 包会自动将头文件软链接至 /usr/include/oracle/19.14/client64/，这是 pecl configure 默认查找路径。
-
验证头文件是否存在：
ls -l /usr/include/oracle/*/client64/oci.h # 应输出类似：/usr/include/oracle/19.14/client64/oci.h -
重新安装 OCI8（无需手动指定路径，pecl 会自动探测）：
pecl install oci8 # 或显式指定 SDK 路径（当自动探测失败时）： pecl install oci8-3.3.0 # 推荐使用较新稳定版 # 若仍需强制路径，运行： # yes '' | pecl install oci8-3.3.0 # 并在提示时输入：instantclient,/usr/lib/oracle/19.14/client64/lib
? 关键注意事项：
- ❌ 不要尝试复制头文件或修改 –with-oci8 参数指向 lib/ 目录——lib/ 下没有头文件；
- ✅ basic 和 devel 必须同版本号（如均为 19.14.0.0.0），混合版本（如 basic=19.11 + devel=19.14）会导致符号不兼容或编译失败；
- ✅ ubuntu/debian 用户请使用 .deb 包（oracle-instantclient19.14-basic 和 oracle-instantclient19.14-dev），安装后头文件位于 /usr/include/oracle/19.14/client64/；
- ✅ 安装完成后，在 php.ini 中添加 extension=oci8.so，并重启 Web 服务（如 apache 或 PHP-FPM）。
完成上述步骤后，pecl install oci8 将成功通过 configure 阶段，并完成编译安装。