PHP OPcache 更新代码后不生效怎么办：缓存验证、FPM 重载与回滚排查

PHP 文件明明已经上传，接口却还返回旧字段，最常见的原因不是代码存放路径错了，而是 PHP-FPM 进程里的 OPcache 继续复用旧脚本。先用文件修改时间和缓存配置确认，再按「清理缓存、平滑重载、版本核对」的顺序处理，不要一上来直接删除整个缓存目录。

排查先从真实请求命中的脚本路径、文件修改时间两个实据入手，优先用 PHP-FPM 平滑重载机制加载新代码，不要直接操作全局缓存目录，避免触发大面积性能波动。

接口返回旧代码时，先看三个证据

这类问题通常出现在发布窗口：部署脚本提示成功，浏览器仍看到旧响应；或者同一台机器上，部分请求已经是新版本，部分请求还是旧版本。这里先别急着改 php.ini，先把「文件是否更新落盘」和「请求由哪个进程处理」两个问题分开排查。

建议在应用响应里暂时返回一个短版本值，例如 release-20260721-a，只用于灰度核对，不要把完整构建信息和敏感配置直接暴露给公网。若文件时间已经更新、版本值仍旧，才进入 OPcache 和进程复用的排查。

用配置判断：PHP 是否会自动重新检查脚本

OPcache 是否重新读取文件，主要看两个配置。opcache.validate_timestamps 开启时，PHP 会按 opcache.revalidate_freq 的间隔检查脚本时间；关闭时，文件更新不会自动让缓存失效，发布后必须有明确的重载或缓存刷新动作。

php --ini
php -i | grep -E 'opcache.validate_timestamps|opcache.revalidate_freq|opcache.enable'

不同发行版的命令行 PHP 和 PHP-FPM 可能读取不同的配置文件，所以只看 php -i 还不够。更稳妥的做法是在 FPM 的诊断入口或同一运行用户下确认配置，并记录配置文件存储路径。若线上关闭了时间戳检查，发布流程就应该把「平滑重载 PHP-FPM」作为固定步骤，而不是依赖等待几秒自动生效。

处理步骤：先平滑重载，再用真实请求验收

确认是旧脚本复用后，先做可回退的平滑重载。服务名按机器实际情况替换，重载前先确认当前进程和配置无误：

sudo systemctl reload php-fpm
sudo systemctl is-active php-fpm
tail -n 80 /var/log/php-fpm/www-error.log

有些系统的服务名包含版本号，例如 php8.3-fpm；如果重载返回「Unit not found」，不要连续尝试多个服务名，先用服务管理器列出当前 PHP-FPM 单元，再对正确的单元操作。重载成功后，访问一条无缓存的健康接口，检查版本标记是否变成新值。

如果应用前面还有 Nginx FastCGI 缓存、容器副本或多台 FPM 主机，单台机器生效并不能代表整体完成。把请求固定到每个副本，或在响应中加入副本标记逐台验证，直到所有节点都返回同一发布版本。

回滚路径：新版本异常时恢复代码和进程状态

旧代码不生效的问题，最危险的处理方式是直接清空生产缓存目录。这样既可能影响其他站点，也很难解释某个请求为什么突然变慢。更稳的回滚顺序是：切回上一版代码目录、恢复软链接、平滑重载 FPM，再用上一版版本标记验证。

ln -sfn /srv/app/releases/20260720 /srv/app/current
sudo systemctl reload php-fpm
curl -fsS https://example.test/health.php

如果上一版也无法加载，查看 FPM 错误日志中的语法错误、扩展缺失和权限错误。OPcache 只能复用已经成功编译的脚本，不能修复新版本本身的运行错误；把「缓存问题」和「代码回滚」分别记录，后续排查时才能判断真正的触发点。

告警确认和复盘：别只看发布脚本退出码

发布完成后至少复查四项：真实接口返回新版本、PHP-FPM 进程状态正常、错误日志没有新增致命错误、5 分钟内的请求错误率和响应时间没有异常。发布脚本退出码为 0，只能证明文件复制或命令执行完成，不能证明所有 FPM 副本已经加载了新脚本。

• 给每个发布包写入短版本标记，并让健康检查返回它。
• 当 validate_timestamps 关闭时，把 FPM 平滑重载放进发布门禁。
• 多副本部署按副本核对，不用单个节点的结果代表全站。
• 保留上一版目录，确认新版本稳定后再清理，给回滚留出时间。

相关问题

为什么改了 PHP 文件，过一会儿才生效？

通常是时间戳检查开启，但 opcache.revalidate_freq 设有检查间隔。生产发布不要依赖这个等待窗口，应把平滑重载纳入发布动作。

重载 PHP-FPM 会不会中断正在处理的请求？

平滑重载的目标是让旧进程完成已有请求，再由新进程加载配置和脚本；具体行为仍需结合发行版的服务单元和维护窗口验证。

清空 OPcache 能彻底解决旧代码吗？

它可能暂时绕过脚本缓存，但解决不了上传目录错误、软链接未切换或多副本未同步。先核对路径和版本标记，再决定是否刷新缓存。

为什么命令行看到的 OPcache 配置和网站不一样？

CLI 与 FPM 可能加载不同的 php.ini 和扩展配置。应在 FPM 实际运行环境中确认，不能把命令行结果直接当成网站进程的配置。

小结

PHP 更新后仍返回旧结果，排查重点是「文件是否更新、请求命中哪个副本、FPM 是否重新加载脚本」。用版本标记建立实据，按平滑重载和真实请求验收推进，既能解决 OPcache 复用旧脚本的问题，也能把回滚和多副本核对纳入日常发布流程。