PHP OPcache 怎样查看脚本缓存命中状态

PHP OPcache 的“命中”要分成两类看：一类是整个缓存实例的累计统计，另一类是某个脚本当前是否已经进入缓存。前者用 opcache_get_status(false)，后者用 opcache_is_script_cached()。如果服务器还启用了 OPcache 文件缓存，不能只拿内存缓存的结果下结论。

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

最小判断路径是：先在承载真实请求的 SAPI 中确认 OPcache 已启用，再读取 opcache_statistics，最后用目标文件的绝对路径检查单脚本状态。CLI 显示未启用，并不代表 FPM 也未启用。

先确认查询的是正确的 PHP 运行实例

OPcache 是按 PHP 运行环境工作的。你在终端执行的 php 命令，和 Nginx 后面的 PHP-FPM 进程可能使用不同的 php.ini、不同的 SAPI 配置，甚至不是同一套 PHP 二进制。因此排查“线上脚本没有命中”时，优先把诊断代码放在与业务请求相同的 FPM 应用中，或从同一个 FPM 池执行。

官方配置中，opcache.enable 控制常规请求的 OPcache，opcache.enable_cli 单独控制 CLI。后者默认值为关闭，所以直接运行 CLI 脚本看到 false 很常见。先确认扩展和 SAPI，再看命中数字，避免把环境差异当成缓存故障。

用 opcache_get_status 读取总体命中统计

opcache_get_status(false) 返回内存缓存实例的状态汇总，并且不带出每个脚本的清单。这样既能看到命中统计，也能减少诊断接口暴露的路径信息。返回值为 false 时，不要继续读取数组，应先处理扩展未启用、访问受限或调用失败的情况。

 0) {
    $hitRate = $hits / $total * 100;
}

printf("enabled=%s\n", !empty($status['opcache_enabled']) ? 'yes' : 'no');
printf("hits=%d misses=%d hit_rate=%s%%\n", $hits, $misses,
    $hitRate === null ? 'n/a' : number_format((float)$hitRate, 2));
printf("cached_scripts=%d\n", (int)($statistics['num_cached_scripts'] ?? 0));
?>

重点看这几个字段：

• opcache_enabled：当前实例是否启用 OPcache。
• opcache_statistics.hits 与 misses：累计命中与未命中次数。
• opcache_statistics.opcache_hit_rate：PHP 给出的命中率。
• opcache_statistics.num_cached_scripts：当前缓存的脚本数量。
• memory_usage：已用、可用、浪费内存和浪费比例。

命中率是当前缓存实例自启动或重置后的累计视图，不是某个接口一次请求的实时指标。发布、重启或清空缓存后，计数可能重新开始；因此应把它和时间点、实例标识一起记录。

用绝对路径检查某个 PHP 文件

如果问题是“这个入口文件是否已经预热”，不要只看全局命中率。opcache_is_script_cached(string $filename) 接收脚本路径，返回该文件是否在 OPcache 的内存缓存中。路径要和运行进程看到的路径一致，容器内路径、软链接路径或发布目录切换都可能让你检查错文件。

 %s\n", $target, $cached ? 'cached' : 'not-cached');
?>

返回 false 不等于 PHP 一定没有执行过这个文件。可能的原因包括：文件刚部署还没有被请求、查询进程与业务进程不是同一个 SAPI、文件在黑名单中、路径不一致，或者当前只启用了文件缓存而没有内存缓存。先固定路径和运行实例，再做判断。

分清内存缓存和文件缓存

opcache_get_status() 官方说明针对的是内存缓存实例，不会返回文件缓存信息。配置了 opcache.file_cache 后，文件缓存是第二层缓存，不能把“内存里没有”直接翻译成“完全没有缓存”。

PHP 8.5 及更高版本提供 opcache_is_script_cached_in_file_cache()，它只检查指定脚本是否在文件缓存中；而 opcache_is_script_cached() 只检查内存缓存。两者的结果需要并列记录：

把诊断入口收紧，再做一次发布检查

OPcache 状态里可能包含脚本路径、配置和运行信息，不建议把完整 opcache_get_status() 输出直接放在公开 URL。诊断脚本更适合只在 CLI 执行，或者放在已有认证、内网访问和最小权限控制之后。生产环境可以默认使用 false 参数，只输出必要的汇总字段；需要脚本清单时再临时开启，并在排查结束后移除。

发布前可以按下面顺序记录一次检查结果：

1. 确认查询进程的 SAPI、PHP 版本和配置文件与真实流量一致。
2. 确认 opcache_enabled=true，并记录 hits、misses、命中率和缓存脚本数量。
3. 对关键入口使用绝对路径调用 opcache_is_script_cached()。
4. 如果启用了 opcache.file_cache，在 PHP 8.5+ 额外检查文件缓存函数。
5. 发布或重启后重新记录时间点，不把重启前后的累计计数直接横向比较。

这样得到的不是一个脱离环境的“命中百分比”，而是一条可复查的状态链：哪个 PHP 实例、哪个缓存层、哪个脚本、哪个时间点。遇到命中率异常时，先沿这条链定位，再决定是调整配置、等待预热，还是检查发布路径。

相关问题

为什么 CLI 的 OPcache 命中率一直是 0？

常见原因是 CLI 的 opcache.enable_cli 没有启用，或者 CLI 与 FPM 使用的配置不同。直接查询线上请求对应的 SAPI，不能用 CLI 结果替代。

opcache_get_status 返回 false 怎么办？

先检查扩展是否加载，再确认 opcache.restrict_api 是否限制了当前脚本路径。官方函数在失败时返回 false，不要对结果直接使用数组下标。

为什么单脚本显示未缓存但总体命中率很高？

总体统计是实例累计数据，单脚本检查是当前路径的即时判断；目标文件可能刚发布、路径不一致，或处于另一个 PHP 进程的缓存实例中，两者并不矛盾。

官方资料：

• https://www.php.net/manual/en/function.opcache-get-status.php
• https://www.php.net/manual/en/function.opcache-is-script-cached.php
• https://www.php.net/manual/en/function.opcache-is-script-cached-in-file-cache.php
• https://www.php.net/manual/en/opcache.configuration.php