PHP代码更新后OPcache为何仍返回旧内容?如何检查缓存失效与进程配置
PHP文件已经替换,浏览器或接口却仍然返回旧结果,通常不是“文件没有上传成功”这么简单。OPcache缓存的是PHP脚本编译后的字节码;当opcache.validate_timestamps关闭、PHP-FPM仍使用旧进程、请求实际到达另一台服务器,或者部署切换了软链接而缓存路径没有重新识别时,磁盘上的新代码和正在执行的代码就可能不一致。
排查时不要一开始就删除缓存目录或反复重启服务器。先确认旧内容来自浏览器、CDN、Nginx、错误的后端节点,还是PHP-FPM自身;再核对Web请求实际使用的PHP配置,最后才进行FPM重启或缓存重置。下面按低风险到高风险的顺序展开。
先确认“旧内容”究竟来自哪一层
对比响应头和后端节点
先使用一个确定会返回动态内容的页面或接口进行测试,避免把静态CSS、JS或图片缓存误认为PHP代码问题:
curl -sS -D /tmp/php-response.headers \
-H 'Cache-Control: no-cache' \
'https://www.example.com/health-check' \
-o /tmp/php-response.body
cat /tmp/php-response.headers
cat /tmp/php-response.body
Cache-Control: no-cache只能要求中间层重新验证,不能替代CDN刷新,也不能绕过所有反向代理缓存。如果响应头中出现以下字段,应先检查HTTP缓存链路:
Age:响应在缓存中保留的时间。X-Cache、CF-Cache-Status或类似字段:表示是否命中代理或CDN缓存。Via:表示请求经过了中间代理。ETag、Last-Modified:可能导致客户端或代理继续使用旧响应。X-Backend、X-Server:如果站点主动添加,可用于判断请求落到了哪台后端。
如果应用允许在响应中输出版本号,建议使用发布批次号或代码提交标识,而不是直接输出服务器路径。例如响应中出现release-20250308-01,可以快速判断旧内容来自应用版本还是缓存层。
在负载均衡环境中,连续请求可能被分配到不同节点。可以临时连续请求并观察后端标识:
for i in $(seq 1 10); do
printf '%02d ' "$i"
curl -sS -H 'Cache-Control: no-cache' \
-D - 'https://www.example.com/health-check' \
-o /tmp/health.body 2>/dev/null |
grep -iE '^(HTTP/|X-Backend:|Age:|X-Cache:)'
done
如果同一个URL有时返回新版本、有时返回旧版本,优先检查后端节点是否使用了不同代码目录或不同PHP-FPM服务。此时清理某一台机器上的OPcache并不能解决整体问题。

PHP-FPM是否持续执行旧脚本,既与进程配置和缓存状态有关,也与请求实际落到的服务器节点有关。A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器,可承载网站、业务后台、数据库与接口服务;不同地区及产品系列有多种CPU、内存、NVMe或SSD存储和网络线路方案,为多节点部署及不同负载的PHP业务提供硬件与网络资源基础。
确认请求使用的代码目录
在每一台提供PHP服务的服务器上检查当前发布目录。下面的路径只是示例,需要替换为实际应用路径:
APP=/var/www/example/current
readlink -f "$APP"
stat -c '%n %y %s' "$APP/public/index.php"
sha256sum "$APP/public/index.php"
需要重点比较三项:
readlink -f解析出的真实目录是否一致。- 文件修改时间和文件大小是否符合本次发布。
- 文件哈希是否一致。
如果使用了类似current -> releases/20250308-01的软链接,不能只检查current这个目录名。某些部署方式只切换了软链接,但PHP进程仍然按照旧路径或旧缓存键执行脚本。还要确认Nginx的root和PHP入口文件确实指向该软链接:

sudo nginx -T 2>/dev/null |
grep -E '^\s*root\s|^\s*fastcgi_pass\s|^\s*fastcgi_param SCRIPT_FILENAME'
如果服务器使用容器,宿主机上的/var/www/example/current不一定是PHP进程看到的路径。此时必须进入实际运行PHP-FPM的容器或服务实例内检查:
docker ps
docker exec -it <php-container> sh
容器名称、运行时和路径应以实际环境为准。宿主机文件哈希正确,不代表容器内挂载的文件已经更新。
核对Web请求的PHP配置,而不是只看CLI
CLI和PHP-FPM可能不是同一套配置
很多排查误区来自下面的命令:
php -i | grep -E 'opcache.enable|opcache.validate_timestamps|opcache.revalidate_freq|opcache.preload'
这条命令检查的是命令行CLI配置,不一定是网站请求使用的PHP-FPM配置。服务器上可能同时存在PHP 8.1、PHP 8.2和PHP 8.3,也可能存在多个FPM池。CLI显示“已开启”或“已关闭”,都不能直接证明Web请求的实际状态。
先记录CLI环境,作为对照信息:
php -v
php --ini
php -i | grep -E 'Loaded Configuration File|Scan this dir for additional .ini files'
然后通过一个受保护的内部诊断页面,或者应用自身的管理诊断功能,读取实际Web请求的配置。诊断页面至少应输出以下信息:
<?php
declare(strict_types=1);
/*
* 仅用于内网或受认证保护的临时诊断路由。
* 不要将PHP版本、服务器路径和OPcache状态直接暴露给公众。
*/
header('Content-Type: text/plain; charset=utf-8');
echo 'PHP_VERSION=' . PHP_VERSION . PHP_EOL;
echo 'PHP_SAPI=' . PHP_SAPI . PHP_EOL;
echo 'DOCUMENT_ROOT=' . ($_SERVER['DOCUMENT_ROOT'] ?? '') . PHP_EOL;
echo 'SCRIPT_FILENAME=' . ($_SERVER['SCRIPT_FILENAME'] ?? '') . PHP_EOL;
$items = [
'opcache.enable',
'opcache.enable_cli',
'opcache.validate_timestamps',
'opcache.revalidate_freq',
'opcache.revalidate_path',
'opcache.preload',
'opcache.file_cache',
'opcache.file_cache_only',
];
foreach ($items as $item) {
echo $item . '=' . var_export(ini_get($item), true) . PHP_EOL;
}
if (function_exists('opcache_get_status')) {
$status = opcache_get_status(false);
echo 'opcache_status=' . ($status === false ? 'false' : 'available') . PHP_EOL;
if (is_array($status)) {
echo 'opcache_enabled=' . var_export($status['opcache_enabled'] ?? null, true) . PHP_EOL;
echo 'cache_full=' . var_export($status['cache_full'] ?? null, true) . PHP_EOL;
echo 'restart_pending=' . var_export($status['restart_pending'] ?? null, true) . PHP_EOL;
}
} else {
echo 'opcache_status=unavailable' . PHP_EOL;
}
该页面应放在临时路由、内网地址或已有管理认证之后,验证完成后删除。不要在公开站点长期保留,因为它可能暴露PHP版本、目录结构和缓存状态。
重点查看的配置项
| 配置项 | 作用 | 排查时的判断 |
|---|---|---|
opcache.enable | 是否为当前SAPI启用OPcache | Web请求为0时,不存在OPcache导致的旧字节码问题 |
opcache.enable_cli | 是否为CLI启用OPcache | 只影响CLI,不能代表PHP-FPM |
opcache.validate_timestamps | 是否检查PHP文件的修改时间 | 为0时,代码更新后通常需要重启或显式重置缓存 |
opcache.revalidate_freq | 两次时间戳检查之间的间隔,单位为秒 | 为2时,文件刚更新后可能短暂返回旧代码 |
opcache.revalidate_path | 是否重新确认包含文件的真实路径 | 软链接、include_path和多版本目录部署时需要重点关注 |
opcache.preload | PHP启动时预加载的脚本 | 修改预加载类或函数后通常需要完整重启FPM |
opcache.file_cache | 是否启用磁盘文件缓存 | 需要结合file_cache_only和重启结果进一步判断 |
opcache.validate_timestamps检查的是文件时间戳,而不是每次比较文件内容哈希。如果部署工具保留了旧修改时间,或者通过复制操作产生了与旧文件相同的时间戳,即使内容已经改变,OPcache也可能认为脚本没有更新。因此,文件哈希和修改时间要一起核对。
如果配置为:
opcache.validate_timestamps=0
那么opcache.revalidate_freq不会让它自动恢复检查。该模式常用于变更频率较低的生产环境,但它要求每次发布都执行明确的缓存失效动作,例如重启PHP-FPM或在受控条件下调用opcache_reset()。
如果配置为:
opcache.validate_timestamps=1
opcache.revalidate_freq=2
文件修改后通常会在下一次时间戳检查时失效,但不能把“2秒”理解为所有请求都严格延迟2秒。请求是否到达同一节点、文件时间戳是否更新、FPM进程是否读取了相同路径,都会影响最终表现。
判断OPcache是否真的保留了旧脚本
查看共享内存和重启状态
通过受保护的Web诊断路由读取opcache_get_status(false),重点观察以下字段:
opcache_enabled:当前Web进程是否启用了OPcache。cache_full:缓存空间是否已满。缓存已满通常会导致新脚本无法正常缓存,但它本身不一定是“旧内容”的直接原因。restart_pending:是否有等待中的OPcache重启请求。restart_in_progress:是否正在执行缓存重启。memory_usage:已用、空闲和浪费的共享内存。opcache_statistics:命中数、未命中数、缓存脚本数和重启统计。
例如,下面这类输出可以作为判断参考,属于示例格式,不代表任何特定服务器的实际结果:
opcache_enabled=true
cache_full=false
restart_pending=false
restart_in_progress=false
used_memory=73400320
free_memory=198180864
num_cached_scripts=1268
num_cached_keys=1491
hits=582104
misses=1327
oom_restarts=0
manual_restarts=1
如果Web诊断页面显示opcache_enabled=false,就应转向检查应用缓存、HTTP缓存或实际执行路径,而不是继续清理OPcache。如果CLI显示开启、Web诊断显示关闭,则说明两个SAPI配置不同,不能用CLI的结果替代FPM判断。
检查FPM主进程和服务名称
先确定请求使用的是哪个FPM实例:
ps -ef | grep '[p]hp-fpm'
systemctl --type=service --no-pager | grep -Ei 'php.*fpm'
如果使用Unix Socket,还可以查看Nginx或Apache连接的Socket:
sudo nginx -T 2>/dev/null | grep -E 'fastcgi_pass|proxy_pass'
sudo ss -lxnp | grep -E 'php|fpm'
可能存在以下情况:
- Nginx连接的是PHP 8.2,但管理员检查的是PHP 8.3的CLI配置。
- Nginx连接的是另一个FPM Socket。
- 修改的是某个FPM池的配置,实际流量使用了另一个池。
- 重启了旧版本FPM服务,但请求仍由容器或另一台节点处理。
- FPM池中使用了
php_admin_value覆盖全局配置。
确认服务后,再检查对应FPM二进制的配置。命令名称因发行版和PHP版本不同,需要先核验:
FPM_BIN="$(command -v php-fpm8.2 || command -v php-fpm)"
printf '%s\n' "$FPM_BIN"
如果输出了正确的FPM程序,可以读取其配置:
sudo "$FPM_BIN" -i |
grep -E 'Loaded Configuration File|Scan this dir|opcache.enable|opcache.validate_timestamps|opcache.revalidate_freq|opcache.preload'
这仍然不如实际Web诊断结果直接,因为FPM池配置和容器环境可能继续覆盖全局配置。最终判断应以请求实际到达的FPM进程为准。
按结果选择处理方式
下面的结果分支可以帮助确定下一步,而不是盲目重启。
| 观察结果 | 更可能的原因 | 处理方向 |
|---|---|---|
| 不同后端返回不同版本 | 发布未同步、负载均衡节点不一致 | 先统一代码目录和发布版本 |
| 文件哈希不一致 | 文件未上传完整或部署目标错误 | 修复发布流程,不必先清理OPcache |
| CLI是新配置,Web是旧配置 | SAPI、FPM版本或FPM池不同 | 检查fastcgi_pass、FPM服务和池配置 |
validate_timestamps=0 | OPcache不会自动识别文件变化 | 使用受控重置或重启FPM |
validate_timestamps=1且刚刚发布 | 尚未到时间戳检查周期 | 等待一个检查周期后复测 |
| 诊断路由已是新代码,业务页面仍旧 | 应用缓存、模板缓存、HTTP缓存或业务数据 | 检查框架缓存和代理缓存 |
| FPM重启后仍旧 | 请求没有到达被重启的实例,或存在预加载/其他缓存 | 重新确认节点、Socket、容器和预加载配置 |
| 只有软链接切换后的文件异常 | 真实路径或缓存键未重新识别 | 检查readlink -f、revalidate_path,发布时重启FPM |
先处理HTTP和应用层缓存
如果响应头表明请求命中了CDN、Nginx fastcgi_cache或应用页面缓存,应先按对应系统的标准方式刷新缓存,并使用源站地址或内部入口进行对比。刷新公共缓存可能影响大量请求,操作前应确认缓存键、域名范围和刷新范围,避免进行不必要的全站清理。
OPcache只缓存PHP脚本的编译结果,不负责缓存以下内容:
- Redis、Memcached或数据库中的配置数据。
- 框架生成的配置、路由和模板缓存。
- 应用生成的整页HTML。
- Nginx、CDN或浏览器保存的HTTP响应。
- 常驻队列进程、定时任务进程已经加载到内存中的类和配置。
如果诊断页面能够返回新的发布标识,而业务页面仍返回旧HTML,应优先检查这些层次。对于常驻PHP进程,还需要单独重启对应的队列或任务服务,FPM重启不会自动终止其他进程。
使用受控的opcache_reset()
在确认请求确实到达目标FPM实例后,可以通过受保护的管理动作调用opcache_reset()。该操作会使缓存脚本重新构建,下一批请求可能出现缓存预热带来的CPU升高。它不应被做成公开URL,也不应允许任意GET请求触发。
示例逻辑如下,实际使用时应接入现有认证、权限和审计机制:
<?php
declare(strict_types=1);
/*
* 仅作为受保护的管理动作示例。
* 不能直接以公开URL部署。
*/
if (!function_exists('opcache_reset')) {
http_response_code(503);
exit('OPcache is unavailable');
}
$result = opcache_reset();
header('Content-Type: application/json; charset=utf-8');
echo json_encode(
[
'reset' => $result,
'sapi' => PHP_SAPI,
'time' => date(DATE_ATOM),
],
JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
);
如果配置了opcache.restrict_api,调用可能被拒绝。命令行执行php -r 'var_dump(opcache_reset());'也通常只作用于CLI环境,不能据此清理PHP-FPM的缓存。预加载脚本中的类和函数还可能需要完整重启FPM,不能把opcache_reset()当作所有场景的替代方案。
必要时重启PHP-FPM
当validate_timestamps=0、启用了预加载、软链接切换后路径识别异常,或者缓存状态无法确认时,重启对应FPM服务通常比删除缓存目录更可靠。
重启前先确认服务和配置:
systemctl --type=service --no-pager | grep -Ei 'php.*fpm'
sudo systemctl status php8.2-fpm --no-pager
服务名不能照抄。如果实际服务不是php8.2-fpm,应替换为上一步确认的名称。配置文件有修改时,先进行语法检查:
sudo "$FPM_BIN" -t
预期结果应表示配置测试通过。如果检查失败,不要继续重启;应根据报错修复配置,或者恢复最近一次备份。单节点网站执行重启可能造成短暂连接失败或502;多节点环境应先摘除一台节点,重启并验证健康检查,再按批次处理其他节点。
sudo systemctl restart php8.2-fpm
sudo systemctl status php8.2-fpm --no-pager
reload和restart不要混为一谈。reload通常用于重新读取配置并平滑处理工作进程,但不同发行版和服务脚本的行为可能不同,不能默认它一定清空了旧OPcache。需要确定缓存已经失效时,应使用经过维护窗口评估的完整FPM重启。
重启后如果服务无法启动,可查看日志:
sudo journalctl -u php8.2-fpm --since '10 minutes ago' --no-pager
如果只是修改了OPcache配置,应保留修改前的配置副本。配置备份、语法测试和服务状态检查都通过后,再进行恢复操作。例如:
sudo cp -a /etc/php/8.2/fpm/conf.d/10-opcache.ini \
/etc/php/8.2/fpm/conf.d/10-opcache.ini.bak
sudo "$FPM_BIN" -t
实际配置路径需要使用php --ini、FPM配置或发行版目录确认。不要在未确认路径的情况下执行覆盖或删除命令,也不要直接使用rm -rf清理OPcache文件缓存目录。若怀疑opcache.file_cache中存在异常,应先停止相关FPM服务、备份或改名缓存目录,确认权限和回滚方式后再处理;这属于后置手段,不是第一步操作。
修复后如何验证缓存已经失效
修复不能只看“重启命令执行成功”。至少完成以下验证:
- 重新检查活动代码目录和文件哈希,确认运行节点使用的是目标发布版本。
- 通过实际业务域名访问受保护诊断路由,确认
PHP_SAPI为预期的FPM环境。 - 再次读取
opcache.validate_timestamps、opcache.preload和opcache_get_status()。 - 访问业务接口,确认响应中的发布标识已经变化。
- 在多节点环境中重复请求,确认所有节点返回一致版本。
- 观察FPM日志、CPU、请求延迟和缓存命中变化,确认缓存预热没有造成异常。
可以使用下面的方式记录多次响应,具体字段以站点实际响应头为准:
for i in $(seq 1 10); do
curl -sS -D - \
-H 'Cache-Control: no-cache' \
'https://www.example.com/health-check' \
-o /tmp/health.body 2>/dev/null |
grep -iE '^(HTTP/|X-Backend:|X-Release:|Age:|X-Cache:)'
done
如果所有请求都返回同一发布标识,且源文件哈希、FPM配置和Web诊断状态一致,说明这次缓存失效已经完成。若仍然偶发旧版本,应继续沿着后端节点、容器实例、FPM Socket和HTTP缓存方向排查,而不是继续增加重启次数。
后续发布可以把“发布标识、活动目录真实路径、入口文件哈希、目标FPM服务、缓存失效动作和复测结果”写入发布记录。对于关闭时间戳检查的生产环境,应把FPM重启或受控OPcache重置作为发布流程的一部分;对于频繁开发环境,则可以保留时间戳检查,并根据性能和更新频率设置合理的revalidate_freq。这样能把一次偶发的旧代码问题,转化为每次发布都可验证的流程。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/7103.html



