PHP OPcache preload 为什么修改代码后必须重启进程

修改了被 opcache.preload 载入的类或函数后，必须重启对应的 PHP 常驻进程，因为预加载脚本只在服务器进程启动时执行一次，解析后的类、接口、Trait 和函数会保留在该进程的持久内存中，直到进程退出。后续请求不会按磁盘上的新文件重新定义这些实体。

官方文档：PHP Preloading；配置项说明可参考 OPcache Runtime Configuration。

预加载实体跟着服务器进程生存

PHP 官方文档把 preload 描述得很明确：从 PHP 7.4 起，可以在引擎启动时把脚本载入 OPcache；其中的函数、类、接口和 Trait 会直接对后续请求可用。配置通常放在 php.ini，例如：

; 在服务器进程启动时执行该预加载脚本
opcache.preload=/var/www/app/preload.php

; 让预加载阶段以实际运行应用的低权限用户执行
opcache.preload_user=www-data

preload.php 可以用 require、include 或 opcache_compile_file() 载入文件。关键不是“文件被缓存过一次”，而是类和函数已经进入当前服务器进程的持久内存。PHP 不能在同一进程中用新版类定义无缝覆盖旧版同名类，因此磁盘文件改变并不会替换已经预加载的实体。

为什么 reset 和时间戳校验不够

最常见的误判，是把 preload 与普通脚本缓存混为一谈。普通 OPcache 条目仍围绕“某个文件的编译结果”工作：开启 opcache.validate_timestamps 后，OPcache 会按 opcache.revalidate_freq 检查脚本是否变化；关闭时间戳校验时，可以在发布过程中显式失效普通缓存，或者重启 Web 服务。

预加载实体更靠前。它们在服务器启动阶段就已定义，并在该进程存活期间持续可用。即使某个缓存管理接口让普通脚本下次重新编译，也不能安全地把同一进程中已经存在的类定义替换掉。因此，下面这段代码适合说明普通缓存维护，但不能把它当成 preload 热更新方案：

先记录发布前的基线指标

preload 的目标通常是减少请求期间的文件解析与类加载开销，但收益会随应用、部署方式和预加载范围变化。不要为文章或发布流程编造一组“提升百分比”，而应在自己的环境记录同一批指标。一个最小基线可以包含：

• 版本探针返回的构建号或提交号；
• 固定路由前 30 次请求的延迟分布，用于观察进程重建后的冷启动阶段；
• PHP-FPM 主进程与工作进程的 RSS；
• 发布窗口内的 HTTP 5xx、PHP fatal error 与 preload 错误；
• preload 开启前后的相同压测脚本、并发数和持续时间。

# 保存当前 PHP 配置来源，避免重启后使用了不同 php.ini
php --ini

# 核对目标 SAPI 是否读取到 preload 配置；生产环境还应从 FPM 使用的配置入口复查
php -i | grep -E '^opcache.preload|^opcache.validate_timestamps'

# 连续请求版本探针，把输出保存为发布前基线
for i in $(seq 1 30); do curl -fsS https://example.com/internal/version; done

这组命令不会给出通用性能结论，它只把“发布前是什么状态”固定下来。正式对比时，应保持机器规格、PHP 配置、路由、数据集和并发模型一致。

发布时必须跨过进程边界

安全顺序是先部署完整代码，再校验 PHP 配置和 preload 脚本，最后重建服务进程。不要让新 preload.php 指向尚未落盘的版本，也不要只重启 Nginx 而保留旧 PHP-FPM 进程。

# 检查 PHP 配置文件语法和 FPM 配置；服务名与二进制路径需按发行版调整
php-fpm -t

# 单独解析预加载脚本，尽早发现语法错误和缺失文件
php -l /var/www/app/preload.php

# 通过服务管理器重建 PHP-FPM 进程；实际单元名需与服务器安装版本一致
sudo systemctl restart php-fpm

# 重启后再次读取版本探针，确认新进程加载了本次构建
curl -fsS https://example.com/internal/version

如果业务不允许一次性重启全部实例，可以在负载均衡后逐台摘流、重建进程、健康检查再挂回。重点仍然是旧进程最终退出；仅把流量切走但不重建进程，挂回后仍可能继续提供旧预加载定义。

如何判断新代码真的生效

重启命令返回成功只是一个中间状态。至少要用四类证据闭环：

1. 版本一致：所有实例的版本探针都返回本次构建号，而不是一半新、一半旧。
2. 启动正常：FPM 日志中没有 preload 文件不存在、权限不足、重复声明或依赖顺序错误。
3. 业务正确：命中本次修改的接口返回预期结果，且错误率没有异常抬升。
4. 容量可接受：工作进程 RSS、启动耗时和吞吐没有超出既定阈值。

若新预加载集合导致启动失败或内存明显上升，回退不能只把代码目录指回旧版本，还要再次重建 PHP 进程，让旧版 preload 重新执行。代码回滚但进程不重建，内存里依然可能保留失败版本的类与函数定义。

哪些情况下不要启用 preload

PHP 官方文档明确提醒，preloading 要求每次修改预加载脚本后重启 PHP 进程，因此它更适合生产环境，不适合频繁改代码的开发环境。还要注意：

• preload 只有在请求之间保持常驻进程时才有实际意义；普通短生命周期 CLI 命令通常没有收益。
• 预加载全部代码最省配置，但会增加基线内存，未必是最佳取舍。
• 预加载不支持 Windows。
• 以 root 启动后再降权的服务器，需要正确设置 opcache.preload_user；不要为了省事扩大运行权限。

相关问题

只重启 Nginx 能让 preload 更新吗？

通常不能。Nginx 与 PHP-FPM 是不同进程，预加载实体位于 PHP 服务器进程中，应重建实际承载 PHP 请求的进程。

opcache_reset 能替代 PHP-FPM 重启吗？

不能把它当成已预加载类和函数的热替换机制。预加载实体持续到服务器进程关闭，修改后应重建进程。

reload 是否一定等于所有旧进程立即退出？

不应只凭命令名称判断。服务管理器、发行版和进程管理方式可能不同，应通过进程、版本探针和流量结果确认旧实例已经退出、新实例已接管。

为什么开发环境不推荐 preload？

因为频繁编辑代码时，每次修改预加载文件都要重启 PHP 进程，反馈循环会变慢；开发环境通常更适合普通 OPcache 配置或直接关闭 preload。