PHP7.3 Docker环境启动报错无法加载oci8.so/pdo_oci.so动态库

• 缺失核心系统依赖：Oracle Instant Client 11.2基于旧版glibc编译，新版Debian系基础镜像（PHP官方Docker镜像默认基于Debian 11/12）已将libnsl.so.1从glibc主包拆分至独立包，默认未预装；同时Instant Client运行依赖libaio1，多数精简基础镜像也未自带，直接导致扩展加载时提示共享库缺失。
• 重复后缀加载异常：PHP扩展配置规则中，extension配置项无需手动写.so后缀，PHP加载时会自动补全后缀。如果自定义ini配置里写了extension=oci8.so这类带后缀的配置，就会触发PHP拼接后查找oci8.so.so无效文件的问题。
• 多版本扩展目录残留：no-debug-non-zts-20170718是PHP 7.2的扩展API版本目录，no-debug-non-zts-20180731是PHP 7.3对应目录，出现两个目录是Docker构建缓存残留了旧版本PHP的扩展文件与扫描配置，导致PHP启动时同时扫描两个版本目录的配置，触发无效加载。
• 动态库路径配置不生效：仅通过ENV LD_LIBRARY_PATH设置库路径时，PHP-FPM进程默认不会继承该环境变量，会导致运行阶段找不到Oracle客户端的共享库，和缺libnsl的报错表现一致。
• 额外说明：启动日志里提示尝试读取不带.so后缀的oci8/pdo_oci文件是PHP扩展加载的默认探测逻辑，不属于异常，无需单独处理。

1. 预装系统依赖 #

在Dockerfile最开头安装Oracle客户端依赖的系统库，执行命令：

RUN apt update && apt install -y --no-install-recommends libnsl1 libaio1 unzip \
    && rm -rf /var/lib/apt/lists/*

如果使用Alpine基础镜像，需要安装libnsl libaio包，同时创建软链接ln -s /usr/lib/libnsl.so.2 /usr/lib/libnsl.so.1适配旧版Instant Client的依赖查找逻辑

2. 清理残留配置避免多版本扫描 #

在编译扩展前，先清理旧版本残留的扩展与配置，执行命令：

RUN rm -rf /usr/local/lib/php/extensions/no-debug-non-zts-* \
    && rm -f /usr/local/etc/php/conf.d/*oci* /usr/local/etc/php/conf.d/*pdo_oci*

禁止手动写入带.so后缀的扩展配置，统一使用docker-php-ext-enable命令启用扩展，该命令生成的配置默认不带后缀，不会触发重复后缀问题。

3. 固化动态库路径避免环境变量失效 #

不要仅依赖LD_LIBRARY_PATH传递库路径，将Oracle客户端路径写入系统动态库配置后执行ldconfig生效：

RUN echo "/opt/oracle/instantclient_11_2" > /etc/ld.so.conf.d/oracle-instantclient.conf \
    && ldconfig

# 预装系统依赖
RUN apt update && apt install -y --no-install-recommends libnsl1 libaio1 unzip \
    && rm -rf /var/lib/apt/lists/*

# 部署Oracle Instant Client
RUN mkdir /opt/oracle
ADD instantclient-basic-linux.x64-11.2.0.4.0.zip /opt/oracle
ADD instantclient-sdk-linux.x64-11.2.0.4.0.zip /opt/oracle

RUN  unzip /opt/oracle/instantclient-basic-linux.x64-11.2.0.4.0.zip -d /opt/oracle \
    && unzip /opt/oracle/instantclient-sdk-linux.x64-11.2.0.4.0.zip -d /opt/oracle \
    && ln -s /opt/oracle/instantclient_11_2/libclntsh.so.11.1 /opt/oracle/instantclient_11_2/libclntsh.so \
    && ln -s /opt/oracle/instantclient_11_2/libclntshcore.so.11.1 /opt/oracle/instantclient_11_2/libclntshcore.so \
    && ln -s /opt/oracle/instantclient_11_2/libocci.so.11.1 /opt/oracle/instantclient_11_2/libocci.so \
    && rm -rf /opt/oracle/*.zip \
    # 写入动态库配置并全局生效
    && echo "/opt/oracle/instantclient_11_2" > /etc/ld.so.conf.d/oracle-instantclient.conf \
    && ldconfig

# 清理旧版本扩展残留
RUN rm -rf /usr/local/lib/php/extensions/no-debug-non-zts-* \
    && rm -f /usr/local/etc/php/conf.d/*oci* /usr/local/etc/php/conf.d/*pdo_oci*

# 编译安装OCI扩展
RUN docker-php-ext-configure oci8 --with-oci8=instantclient,/opt/oracle/instantclient_11_2 \
    && docker-php-ext-install oci8 \
    && docker-php-ext-enable oci8

RUN docker-php-ext-configure pdo_oci --with-pdo-oci=instantclient,/opt/oracle/instantclient_11_2,11.2 \
    && docker-php-ext-install pdo_oci \
    && docker-php-ext-enable pdo_oci

• 重新构建镜像时需要加--no-cache参数，避免复用旧的错误缓存层
• 构建完成进入容器后，可执行php -m | grep -E 'oci8|pdo_oci'验证扩展是否正常加载，无启动警告即为修复成功

内容的提问来源于stack exchange，提问作者RauzerDev