PHP OPcache 预加载怎样评估启动边界

如果你把 OPcache 预加载理解成“把更多 PHP 文件放进缓存”，上线后最容易遇到的误判就是：改了源码却要重启 PHP-FPM 才生效，或者把预加载开在多个应用共用的进程里后出现类名冲突。评估它的关键不是“能不能加速”，而是确认代码是否适合在 PHP 进程启动时进入持久内存。

先给结论：预加载适合有稳定常驻进程、代码发布会明确重启进程、且能控制加载集合的生产环境。它不适合作为开发环境的即时刷新机制，也不适合把多个版本应用的用户态类混在同一个共享进程中。

官方地址：https://www.php.net/manual/en/opcache.preloading.php

影响面：它改变的是启动边界，不只是缓存命中率

普通 OPcache 主要保存预编译后的字节码，预加载则在 PHP 引擎启动时执行一个指定的 preload.php，把其中引用到的函数、类、接口或 trait 放进持久内存，后续请求可以直接使用这些符号。它带来的收益是减少重复加载和解析，代价是占用一部分长期内存，并把发布动作和进程重启绑定起来。

因此，评估时先问三个问题：服务是不是跨请求常驻；发布时能不能可靠重启 PHP-FPM 或对应 SAPI；被预加载的代码是否稳定且不会依赖请求级状态。只要其中一项答不上来，就先保持普通 OPcache，而不是继续扩大预加载集合。

时间线：源码修改为什么不会自动替换预加载符号

把一次发布拆成三个边界就清楚了。第一段是 PHP-FPM 等服务启动，引擎读取 opcache.preload 指向的脚本；第二段是 preload.php 被执行，它可以用 include 或 opcache_compile_file() 载入其他文件；第三段才是请求进入应用。预加载发生在第一、二段，普通请求发生在第三段。

这解释了两个常见现象：一是改动已被预加载的类文件后，正在运行的进程仍然保留旧符号；二是仅调用 opcache_reset() 不能把预加载内容重新载入。正式发布应该把“更新文件”和“重启承载进程”视为同一个变更单元，并给回滚保留同样的重启动作。

触发条件：include 和 opcache_compile_file 不是同一种加载

两种方式都能把文件纳入预加载，但边界不同。include 会执行文件代码，并继续处理嵌套引用，适合本来就需要手动加载且依赖顺序明确的文件；opcache_compile_file() 只编译并缓存文件，不执行其中的代码，且对类依赖的文件顺序更灵活。选择时不要只看文件数量，要看启动阶段是否允许产生副作用。

如果文件包含条件声明、必须执行的注册逻辑或依赖嵌套 include，则应改用 require_once 并明确理解它会执行代码。这个选择本身就是预加载边界的一部分，不要把两种写法机械混用。

根因与修复：配置只能放在启动可见的位置

预加载由 php.ini 中的系统级配置决定，核心配置可以先保持最小：

; 由 PHP-FPM 启动阶段读取，路径相对当前 PHP 配置环境解析
opcache.enable=1
opcache.preload=/var/www/app/preload.php

; PHP-FPM 以 root 启动后切换用户时，指定预加载执行用户
opcache.preload_user=www-data

改完配置后要重启实际承载请求的 PHP 进程，再观察应用的启动日志和运行状态。不要把这项配置当成普通请求级参数，也不要只重载 Web 服务器而遗漏 PHP-FPM。PHP 官方手册还明确说明预加载不支持 Windows；CLI 中即使能看到配置，也不代表它能替代生产常驻进程的验证方式。

防复发清单：先判断适用场景，再扩大加载集合

我会把上线前的判断压缩成四项：第一，只给常驻生产进程启用；第二，预加载集合只放稳定、低副作用的公共代码；第三，发布和回滚都必须包含 PHP 进程重启；第四，多应用共用进程时优先避免加载用户态同名类。若内存预算、重启流程或代码边界不清晰，普通 OPcache 往往是更稳妥的基线。

这也是预加载的正确定位：它不是“缓存越多越快”的按钮，而是一个把代码生命周期提前到服务启动阶段的工程取舍。先用小集合观察内存和启动行为，再决定是否扩大范围。

相关问题

• 修改了预加载文件为什么请求仍然读旧代码？ 因为预加载符号跟随当前 PHP 进程生命周期，发布后需要重启承载进程。
• opcache_reset() 能代替重启吗？ 不能把已预加载的代码重新载入，不能把它当成预加载回滚方案。
• 开发环境要不要打开预加载？ 通常不建议，开发环境需要频繁刷新，而预加载的设计更适合稳定的常驻生产进程。