PHP OPcache preload判断预加载代码与部署重启边界的实现方法

PHP OPcache preload 的关键边界只有一句话：preload.php 在 PHP 进程启动时执行，预加载的类、接口、trait 和函数进入持久内存；要让新的预加载代码生效，必须重启承载它的 PHP 进程。因此，改完普通业务文件可以按 OPcache 的时间戳策略处理，但改了 preload.php、预加载文件或相关全局配置时，不能只调用 opcache_reset() 就认为部署完成。

官方文档：https://www.php.net/manual/en/opcache.preloading.php

PHP OPcache preload的适用压力与生命周期

preload 适合长驻 PHP 进程：应用反复使用的一组类、接口、trait 和函数可以在启动时放入持久内存，后续请求不必再次显式加载这些声明。它换来的代价是常驻内存和更严格的发布边界。PHP 官方文档还特别提醒，CLI 进程通常不会持续复用，因此在普通 CLI 脚本里启用 preload 的收益很有限。

这也解释了两个常见误判。第一，普通 OPcache 命中不等于 preload 已经生效；第二，文件已经修改也不等于预加载的声明已经被替换。预加载脚本会在服务器启动时运行，旧的预加载声明要等 PHP 进程被清掉后才会离开内存。

preload.php应该预加载什么

入口文件应当像一张稳定的依赖清单：引用确定的源码文件，让类和函数声明在启动时可用。下面的示例只表达配置结构，文件路径应替换成项目真实目录；代码中的 require_once 会执行被引用文件，这一点和只编译文件的方式不同。

把配置写在全局 php.ini 中，并让运行 PHP 的用户能够读取入口和被引用文件：

; 中文注释：启用 OPcache 后，指定启动期执行的预加载入口。
opcache.enable=1
opcache.preload=/srv/app/preload.php
; 中文注释：按部署环境指定预加载时使用的系统用户，避免权限错配。
opcache.preload_user=www-data

常量不会因为 preload 自动变成所有请求都可用的预加载符号；需要常量时仍应保留清晰的正常加载路径。另一个边界是副作用：把连接池初始化、临时目录创建、环境变量快照等动作放进入口，会把启动期状态错误地延长到多个请求。

部署重启如何让新预加载代码生效

可以把发布对象分成三类。普通业务脚本受 opcache.validate_timestamps 和 opcache.revalidate_freq 影响；preload 入口或被预加载文件改变时，需要重建 PHP 进程；php.ini 的全局配置改变时，则要按服务管理方式重启对应 PHP 服务。不要把三种对象混成一个“清缓存”动作。

部署顺序上，先把新文件放到可回滚的发布目录，再检查入口路径、属主和语法，随后重启 PHP-FPM。若启动失败，优先回滚入口或关闭 preload，让服务先恢复；不要在旧 worker 仍存活时反复修改同一个入口，造成“文件已更新但进程仍用旧声明”的错觉。

# 中文注释：以下是发布检查示意，服务名按发行版和项目实际情况替换。
php -l /srv/app/preload.php
php --ini
sudo systemctl reload php-fpm
sudo systemctl restart php-fpm

这里的命令只表达检查与服务边界，不代表某台机器已经执行。生产环境应记录实际服务名、worker 切换结果和回滚点。

反例、代价与排查清单

最危险的反例是把“每次部署都会变化”的逻辑塞进 preload：例如按环境拼接类定义、连接数据库后缓存结果，或者在入口里写入初始化记录。它们会让启动时状态和请求时状态纠缠，重启频率越低，旧数据存活越久。另一个反例是只执行 opcache_reset()，却没有重启 PHP 进程；普通缓存可能被清掉，但预加载声明的生命周期并没有因此缩短。

• 旧类或旧函数仍出现：确认承载请求的 worker 是否已经全部重启。
• 启动时报权限错误：检查 opcache.preload 指向文件及其上级目录的读取权限。
• 修改入口后行为不一致：核对不同机器的 php.ini、PHP SAPI 和发布目录是否一致。
• 收益不明显：确认应用是否使用长驻进程，再评估常驻内存成本，不要只看单次请求。

判断清单可以收敛为四项：预加载哪些声明、由谁启动、何时重启、如何回滚。四项都能在发布记录中找到答案时，preload 才是可维护的架构选择；否则先关闭它，把普通 OPcache 和应用加载路径理顺，再做小范围灰度。

常见问题

修改 preload.php 后只重启 Nginx 可以吗？

通常不行。preload 由 PHP 进程启动时执行，应该重启 PHP-FPM、Apache mod_php 或实际承载 PHP 的长驻服务。

preload 能替代 Composer 自动加载吗？

不能简单替代。它可以提前放入稳定声明，但动态类、常量和运行期依赖仍需要正常的自动加载与包含路径。

开发环境适合一直开 preload 吗？

一般不适合。每次修改预加载代码都要清理并重启 PHP 进程，反馈慢且容易掩盖普通代码变更；它更适合有长驻进程的生产场景。