PHP OPcache.validate_timestamps 关闭时如何安全发布新代码

线上打开了 opcache.validate_timestamps=0 后，发布目录虽然已经换成新文件，PHP-FPM 却还可能继续执行旧代码。安全做法不是把 opcache.revalidate_freq 调成更小，而是把“版本切换”和“缓存处理”设计成一次发布动作：先准备独立版本目录，再切换 current，最后按变更范围让承载 Web 请求的 FPM 缓存失效。

官方文档：https://www.php.net/manual/zh/book.opcache.php

为什么关闭后代码不会自动更新

opcache.validate_timestamps 打开时，OPcache 会按 opcache.revalidate_freq 检查脚本时间戳；关闭后，这个自动检查链路就不再承担发布感知。于是“磁盘上是新文件”和“worker 执行的是新 opcode”变成两件事。

还要注意运行时边界：通过命令行启动的 PHP 进程与 PHP-FPM 通常使用不同的 opcode 缓存。即使下面的命令在 CLI 返回 true，也不能据此判断 Web 请求已经更新。

先用独立版本目录准备新代码

不要直接覆盖正在服务的目录。让每次发布落到类似 /srv/app/releases/20260913-01 的新目录，安装依赖、检查权限，并让健康检查读取一个能返回版本标识的接口。确认目录本身可用后，再让 current 软链接指向它。

# 新目录只读准备，避免半套文件被在线请求看到
release_dir=/srv/app/releases/20260913-01
mkdir -p "$release_dir"
rsync -a --delete ./ "$release_dir/"
chown -R www-data:www-data "$release_dir"

# 原子替换版本指针；旧目录保留，便于异常时切回
ln -sfn "$release_dir" /srv/app/current

这里的原子指针只解决“文件集合的一致性”，不会自动清理 OPcache。发布系统仍应记录当前版本、旧版本和本次缓存动作，避免只看软链接状态就判定完成。

按变更范围选择失效或重载方式

如果只是一个确定的 PHP 文件发生变化，可以在 FPM 请求上下文中调用 opcache_invalidate($file, true)，第二个参数表示立即失效该脚本。批量替换了框架、自动加载器或配置依赖时，文件级清单很容易漏项，更稳妥的是在受控维护入口调用 opcache_reset()，或者对 PHP-FPM 做平滑重载，让新 worker 建立新的运行时缓存。

不要把这个维护入口暴露给普通访客，也不要把它当成万能清缓存接口。大范围发布时，重置整池或重载 FPM 的影响更大，应安排在可观察的窗口，并让流量和进程管理策略承担平滑过渡。

发布后如何验证和回滚

验证要围绕真实 Web 请求，而不是只执行一次 CLI 命令。先访问带版本号的健康接口，再检查一个本次发布确实改变的关键行为；同时观察 PHP-FPM 错误日志、5xx 和响应延迟。如果仍返回旧版本，优先确认请求落到哪个 FPM 池、维护入口是否在同一运行时，以及重载是否真的作用于在线 worker。

# 这些命令是发布脚本示意，实际服务名按发行版和部署环境调整
current=$(readlink -f /srv/app/current)
echo "current=$current"

# 通过 Web 入口确认请求经过目标 FPM，而不是只确认 CLI 环境
curl --fail --silent --show-error https://example.com/health/version

# 平滑重载需由进程管理器执行；失败就停止后续切流并保留旧目录
sudo systemctl reload php-fpm

如果新版本报错，先把 current 切回旧目录，再按同样的 FPM 缓存策略处理，最后重新访问健康接口。旧版本目录不要在首轮验证结束前删除，这个保留窗口通常比“发布成功后立刻清理磁盘”更重要。

常见疑问

只把 revalidate_freq 设为 0 能解决吗？不能。该设置只有在 validate_timestamps 开启时才有意义；关闭后仍需手动失效、重置或重启承载请求的进程。

为什么 CLI 清缓存后网页还是旧代码？CLI 与 FPM 往往不是同一个 opcode 缓存实例。应在 FPM 的请求上下文处理，或直接使用进程管理器对在线 FPM 做受控重载。

归根结底，关闭时间戳检查换来的是更明确的性能策略，也把缓存一致性责任交给发布系统。版本目录保证文件集合可切换，缓存动作保证 worker 不再固守旧 opcode，Web 健康检查则把“已经部署”和“已经生效”区分开。