PHP OPcache脚本缓存与部署重启的配合清单

PHP OPcache 的关键不在于“开不开缓存”，而在于脚本切换后谁负责让 PHP worker 看见新文件。我的做法是把配置和发布动作绑定：开发环境开启时间戳校验，生产环境如果关闭 opcache.validate_timestamps，就把 PHP-FPM 重载或重启写成发布流程的一部分。只改 Nginx、只改代码目录，不能自动替代这个动作。

先把两个配置参数放回各自的职责

PHP 手册给出的边界很明确：开启时间戳校验后，OPcache 会按照 opcache.revalidate_freq 检查脚本；关闭校验后，文件系统变化不会自动触发更新，必须通过 opcache_reset()、opcache_invalidate() 或重启 Web 服务器让变化生效。因此，把 revalidate_freq=0 当成“生产发布不用重启”的开关，是最容易出现旧代码的误解。

一张简单的环境清单可以减少误配：

生产发布清单要包含 PHP worker 重载

如果生产环境采用关闭时间戳校验的策略，发布顺序应当是“准备新目录、完成原子切换、重载 PHP 服务、观察错误日志”。服务名会随发行版和安装方式变化，下面只展示动作关系，执行前应替换成现场的 PHP-FPM 服务名：

#!/usr/bin/env bash
set -euo pipefail

# 先完成不可见目录的构建，再把 current 原子切换到新版本
ln -sfn /srv/app/releases/20260923 /srv/app/current

# PHP-FPM worker 承担 OPcache；服务名按现场安装方式替换
sudo systemctl reload php-fpm

# 只有 reload 不能满足现场策略时，才按变更窗口执行 restart
# sudo systemctl restart php-fpm

这里的重点不是命令本身，而是责任边界：Nginx 可以继续持有连接，但真正解释 PHP 脚本并持有 OPcache 的是 PHP SAPI。若只把软链接切到新目录而不触发 PHP worker 的缓存切换，旧脚本继续被命中就不奇怪了。发布失败时，先切回上一版目录，再按同一策略重载，回滚动作才是闭合的。

什么时候用 reset，什么时候用 invalidate

opcache_reset() 适合需要清空整个 OPcache 的维护动作，影响范围大；opcache_invalidate($filename, true) 更适合明确知道某个脚本需要重新编译的场景。两者都不应做成匿名公网接口，否则任何人都可能触发缓存抖动。更稳妥的做法是让服务管理器承担全量切换，单文件失效只留给受保护的运维脚本或内部维护任务。

上线后用四个检查点确认没有漏动作

1. 确认修改的是 PHP-FPM 实际加载的配置，而不是 CLI 使用的另一份 php.ini。
2. 确认代码切换发生在 worker 重载之前，避免新 worker 仍读到半成品目录。
3. 确认错误日志没有出现启动失败、权限异常或扩展加载错误。
4. 确认回滚脚本同时切回目录并重载 PHP 服务，不能只恢复软链接。

常见问题

把 revalidate_freq 设置为 0 后还需要重启吗？

如果 validate_timestamps 是 0，需要。revalidate_freq 在关闭时间戳校验时会被忽略，不能代替 reset、invalidate 或服务重启。

只重启 Nginx 能清掉 PHP OPcache 吗？

不能把它当成可靠的清缓存动作。应重载或重启实际运行 PHP 的 SAPI 服务，并把这个动作固定在发布脚本中。

开发环境也应该关闭时间戳校验吗？

通常不建议。开发时保留校验更适合频繁修改脚本；只有明确配套了每次变更后的缓存清理动作，才考虑关闭。

我更愿意把 OPcache 看成发布协议的一部分：配置决定“自动检查还是人工切换”，发布脚本决定“什么时候切换”，回滚脚本决定“旧版本如何重新可见”。三者写在同一张清单里，旧代码问题通常就能从玄学变成可定位的部署遗漏。