PHP OPcache 预加载变更代码后为什么仍然是旧类

线上改完一个 PHP 类，接口却还返回旧逻辑，最容易先去调用 opcache_reset()，或者反复刷新浏览器。若项目启用了 opcache.preload，这两步可能都不解决问题：类定义是在 PHP-FPM 启动时载入的，旧符号会跟着进程继续存在。真正有效的动作是让承载请求的 PHP 进程退出并重新启动，使 preload.php 再执行一遍。

先确认旧类是不是来自预加载

先在和线上请求相同的 PHP-FPM 环境里查看配置。直接运行 CLI 的 php -i 只能说明 CLI SAPI，不能证明 FPM 使用了同一份 php.ini；而且 opcache.enable_cli 默认可能与 FPM 不同。

如果请求端点显示了 opcache.preload，并且重启前后同一个类的方法行为不变，就应优先按预加载生命周期排查。opcache_get_status() 的具体统计字段会因 PHP 版本和环境而异，不能只凭某一个统计键下结论。

普通缓存检查为什么不够

普通 OPcache 可以根据文件时间戳重新检查脚本；关闭 opcache.validate_timestamps 后，官方建议通过重置、失效指定脚本或重启 Web 服务器让文件变更生效。但预加载是在服务器启动阶段执行，类、接口、trait 和函数会进入持久内存，预加载脚本没有被重新执行时，新的类文件并不会把旧符号“覆盖”掉。

因此，opcache_reset() 适合处理普通缓存的刷新问题，却不是替换预加载类定义的部署动作。重新发起 HTTP 请求也只会复用现有 worker，无法改变它已经加载的类表。

用构建标记验证当前 worker

不要只看文件修改时间，给被预加载的类增加一个可观察的方法更可靠。这个标记可以是发布流水线写入的构建号，也可以是人工指定的短字符串。

部署前记录期望值，部署后从真实业务请求或受保护的诊断端点读取 ReleaseInfo::buildId()。如果磁盘文件已经是 v2，返回值仍是 v1，说明请求仍由旧进程提供；如果不同机器返回不同值，则还存在新旧 worker 混用。

正确的发布动作是重启承载请求的 PHP-FPM

先替换代码和 preload.php，再重启实际提供 FPM 请求的服务。服务名随发行版和 PHP 小版本不同，下面的命令只展示动作，不要机械复制服务名：

# 按服务器实际服务名重启 PHP-FPM，让 preload.php 重新执行。
sudo systemctl restart php8.3-fpm

# 重启后从 FPM 入口检查构建标记，而不是只检查磁盘文件。
curl -fsS https://internal.example.test/__release | grep '2026-09-07-preload-v2'

如果使用容器或进程管理器，重启目标应是 PHP-FPM 主进程及其 worker，而不是只重载 Nginx。滚动发布还要设置好摘流和健康检查，确认旧 worker 已退出后再把流量全部切到新 worker。开发环境通常不值得承担预加载带来的重启成本，可以关闭 opcache.preload，避免“改了文件却必须重启服务”的反馈。

常见问题

改成 opcache.validate_timestamps=1 就能解决吗？

它只影响普通脚本的时间戳检查。已经预加载的类仍应通过重启 PHP 进程清除。

重启 Nginx 后旧类会消失吗？

不会，除非 PHP-FPM 也随之重启。应确认真正承载 PHP 请求的进程已经退出并重新启动。

为什么本机没问题，线上却一直是旧类？

常见原因是本机没有启用预加载，或本机请求使用了不同的 SAPI。对比请求端的 PHP_SAPI、opcache.preload 和构建标记即可缩小范围。

把预加载当成“进程启动时建立的类环境”，发布流程就会清晰很多：文件更新只是第一步，重启 PHP-FPM 并确认新标记返回，才算这次类变更真正到达请求。