PHP OPcache 预加载与部署重启的生效关系

PHP OPcache 预加载的关键不在“文件有没有上传”，而在“承载预加载实体的服务进程有没有重新启动”。opcache.preload 指向的脚本会在服务器启动时被编译并执行，其中定义的类、函数等实体会一直提供给请求，直到服务器关闭。因此，部署新代码后只做 nginx reload，通常不能让 PHP-FPM 主进程重新建立预加载状态。

先分清普通缓存与预加载的生命周期

开启时间戳校验时，普通脚本缓存会按 opcache.revalidate_freq 检查文件变化；关闭 opcache.validate_timestamps 后，则需要 opcache_reset()、opcache_invalidate() 或重启承载它的服务。预加载又多了一层：预加载脚本在服务器启动阶段执行，已定义的实体属于这次服务生命周期。

这就是部署中最容易混淆的地方：上传了新的 PreloadedContainer.php，并不等于已经替换了正在运行进程里的类定义；清空普通缓存也不自动等于重新执行 preload.php。可以把生效链理解为“发布文件 → 读取配置 → PHP-FPM 主进程启动 → 预加载脚本执行 → worker 处理请求”。

配置时把 preload 当作启动契约

PHP 官方文档将 opcache.preload 定义为服务器启动时编译并执行的 PHP 脚本；opcache.preload_user 用于指定预加载执行时的系统用户。生产配置要同时考虑路径、读取权限、启动用户和回滚后的文件结构：

; 这些是 php.ini 或独立 OPcache 配置片段，分号是 PHP 配置注释
opcache.enable=1
opcache.preload=/srv/app/config/preload.php
; 让预加载使用非特权服务用户，避免以 root 读取应用文件
opcache.preload_user=www-data
; 关闭时间戳校验后，代码发布必须配合明确的重启或 reset 策略
opcache.validate_timestamps=0
opcache.revalidate_freq=0

preload.php 不应依赖只在某个请求里才存在的状态。它可以通过 require_once 或 opcache_compile_file() 纳入文件，但文件路径和类依赖要在服务启动阶段可读；否则 PHP-FPM 启动日志会比业务请求更早暴露问题。

官方地址：https://www.php.net/manual/en/opcache.configuration.php

部署时把 PHP-FPM 重启放在发布边界内

一个稳妥的发布顺序是：先把新版本完整写入临时目录，检查 preload.php 和它引用的文件，再切换应用目录，最后重启实际承载请求的 PHP-FPM 服务。服务名会随发行版和 PHP 版本变化，下面只是命令形态示例：

# 先检查待发布版本的预加载脚本语法，失败时不要切换流量
php -l /srv/app/config/preload.php

# 切换代码目录后，重启 PHP-FPM 主进程，让 preload 在新生命周期执行
sudo systemctl restart php-fpm

# 读取服务状态；这里只确认服务管理器的状态，不代替业务验收
sudo systemctl status php-fpm --no-pager

如果环境使用版本化服务名，应把 php-fpm 换成实际单元名。不要只重载 nginx：nginx 负责把请求转给 FastCGI，预加载脚本由 PHP 服务启动阶段处理。若发布系统采用多台机器或多个 FPM pool，应让每个实际承载流量的 pool 都执行相同的生命周期动作。

按变更类型选择处理方案

opcache_reset() 适合处理普通 opcode 缓存的主动清理，但不能把它当作“重新启动服务并重跑 preload”的通用替代品。对于预加载类、函数和配置变更，重启边界更清晰，也更容易和发布回滚记录对应。

部署前后的三个检查点

第一，检查新版本的预加载入口和依赖是否同时存在，避免主进程启动时引用旧目录。第二，检查 PHP-FPM 的启动日志和 OPcache 错误日志，重点看权限、路径和重复定义。第三，在一台实例完成切换后，再观察请求是否由新 worker 接管，再扩大到其他实例。

我更倾向于把“预加载变更 + PHP-FPM restart”做成同一个发布步骤，并把服务名、pool 范围和回滚命令写进部署清单。这样排障时可以回答两个具体问题：这次发布是否启动过新的 FPM 生命周期，以及启动时读取的到底是哪一份预加载文件。

常见问题

只执行 opcache_reset() 能让 preload.php 重新执行吗？

不要把它作为默认结论。reset 主要解决 opcode 缓存清理；若目标是让启动阶段的预加载脚本按新版本重新建立实体，完整重启 PHP-FPM 更直接。

为什么重启 nginx 后 PHP 类还是旧的？

因为 nginx reload 不等于 PHP-FPM 主进程重启。应检查请求实际连接的 FPM pool，并在对应 pool 的服务生命周期上执行重启，再查看启动日志。

参考资料：https://www.php.net/manual/en/opcache.configuration.php、https://www.php.net/manual/en/install.fpm.php