Docker环境下配置opcache.preload后preload.php文件找不到问题排查

核心问题根因是：opcache预加载配置是PHP进程级的强制校验规则，只要配置被PHP加载，任何PHP进程启动时都会检查指定路径的preload.php是否存在，不管是生产环境运行的FPM进程，还是Docker构建阶段临时启动的、用来安装Composer的CLI进程。当前的问题是把预加载配置直接硬编码进了PHP的全局配置目录，在项目代码（含/app/tools/preload.php）还没被COPY进镜像的阶段，PHP只要被调用就会触发“找不到预加载脚本”的致命错误，直接中断构建流程。

• 第一步：先移除全局硬编码的预加载配置
  把原有opcache.ini里直接写入的两行预加载配置删掉，避免构建阶段被提前加载触发校验：

  # 从原有opcache.ini中删除以下两行配置
  opcache.preload=/app/tools/preload.php
  opcache.preload_user=www-data
  

• 第二步：按照Docker构建的执行顺序调整配置加载时机
  遵循“先完成无依赖的基础构建操作，等preload.php在镜像文件系统中真实存在后，再写入预加载配置”的原则调整Dockerfile，两种常用实现：

  1. 多阶段构建隔离（生产环境推荐）
     • 构建阶段：完成系统依赖安装、PHP扩展编译、Composer安装、项目依赖拉取等操作，全程不写入任何预加载配置，从根源上避免构建过程被预加载校验打断
     • 运行阶段：把完整项目代码（包含/app/tools/preload.php）全部COPY到镜像对应路径后，再把预加载配置写入PHP的自定义配置扫描目录（通常为/usr/local/etc/php/conf.d/），此时后续启动的PHP进程才能正常读取到预加载脚本。
       参考Dockerfile片段：

     # 构建阶段：无预加载配置干扰，正常完成基础安装
     FROM php:7.4-cli AS builder
     # 原有逻辑：安装系统依赖、编译opcache扩展
     RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/bin --filename=composer --quiet && rm -rf /root/.composer/cache
     
     # 运行阶段：等preload.php就位后再加载预加载配置
     FROM php:7.4-fpm AS runtime
     # 同步构建阶段安装的扩展与Composer程序
     COPY --from=builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/
     COPY --from=builder /bin/composer /bin/composer
     # 先COPY完整项目代码，确保/app/tools/preload.php存在于文件系统
     COPY ./ /app/
     # preload.php就位后，再写入预加载配置，同时修正文件权限匹配preload_user要求
     RUN echo "opcache.preload=/app/tools/preload.php" >> /usr/local/etc/php/conf.d/zz-opcache-preload.ini \
         && echo "opcache.preload_user=www-data" >> /usr/local/etc/php/conf.d/zz-opcache-preload.ini \
         && chown www-data:www-data /app/tools/preload.php
     

  2. 单阶段构建适配
     如果不使用多阶段构建，必须把「COPY项目代码」的步骤，挪到所有需要调用php命令的操作（比如安装Composer、拉取项目依赖）的前面，确保每次执行php命令时，预加载脚本已经真实存在于镜像的文件系统中。

• 第三步：临时快速验证方案
  如果需要快速打通构建流程，可在构建阶段调用php命令时，通过临时环境变量跳过自定义ini配置的加载，直接绕过预加载校验。把安装Composer的命令修改为：

  RUN PHP_INI_SCAN_DIR=":" curl -sS https://getcomposer.org/installer | php -- --install-dir=/bin --filename=composer --quiet && rm -rf /root/.composer/cache
  

  这里的PHP_INI_SCAN_DIR=":"会让PHP启动时跳过默认的自定义配置扫描路径，不加载opcache预加载规则，保证构建流程正常走完，待服务运行阶段再正常加载预加载配置即可。

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