本文系统性拆解监听的完整实操要点。
上个月一个客户把跳转插件编译好、扩展也写进了 php.ini,结果访问落地页始终返回静态 HTML,日志里一条判定记录都没有。他问:插件明明装上了,为什么请求根本没进到 PHP 这一层?这类问题的答案很明确——插件不接管请求,九成不是插件代码本身的问题,而是请求在到达 PHP 执行链之前就被 Nginx 或 PHP-FPM 截断了。下面按可观察症状、逐层信号、检查步骤、收尾验证的顺序走一遍。
先看症状落在哪一层:三种典型表现
同样是“跳转不生效”,请求停的位置不同,排查入口完全不同。
- 访问返回的是静态文件内容,响应头里没有 PHP 版本标识,说明请求被 Nginx 当作静态资源直接吐出去了。
- 返回 502 或 504,页面是 Nginx 默认错误页,说明请求已经转发给 PHP-FPM,但后端没在超时预算内回应。
- 返回 200 且页面正常,但插件判定日志为空,说明 PHP 执行了,只是插件没被加载或没挂上钩子。
先把这三类分开,再决定往哪查,能省掉大量盲试。关于请求从入口到版本返回的完整链路,可以先对照请求入口到版本返回链路建立整体印象。
Nginx 转发规则:location 优先级与 try_files 的截断
第一层排查集中在 server 块的 location 匹配。常见错误是插件入口路径被一个更精确的静态 location 抢走,比如 location ~* \.(js|css|html)$ 这类正则写在前面,访问 /go/xxx.html 时就直接命中静态规则,fastcgi_pass 根本没机会执行。
检查顺序建议这样排:
- 用
nginx -T导出完整生效配置,确认没有 include 进来的旧文件覆盖当前 server 块。 - 核对 location 匹配优先级:
=精确匹配 >^~前缀匹配 > 正则~,正则按出现顺序取第一个命中。把插件入口的location ~ \.php$放到静态正则之前,或给入口路径单独加^~前缀。 - 检查
try_files是否把不存在的路径兜到了静态目录,导致请求提前返回 404 而不进 PHP。 - 确认
fastcgi_pass指向的地址与 PHP-FPM 实际监听地址一致,unix socket 与 127.0.0.1:9000 混用是最常见的错配。
改完用 nginx -t 校验语法再 reload,不要直接 restart,避免把已有连接一起断掉。
PHP-FPM 侧:监听、进程池与扩展装载
请求进了 PHP-FPM 但插件不生效,问题通常在两个位置。
监听与进程池。 先看 php-fpm -t 是否通过,再看 pool 配置里的 listen、listen.allowed_clients 与 Nginx 是否对得上。进程池的 pm.max_children 设得过小、request_terminate_timeout 设得比 Nginx 的 fastcgi_read_timeout 还长,都会表现为请求排队后超时,插件逻辑压根没跑完。
扩展装载顺序。 插件以 PHP 扩展形式挂载时,extension= 行的位置很关键:依赖的基础扩展必须先加载,否则插件初始化失败但 FPM 不报致命错误,只是钩子没注册上。检查 php -m 与 php-fpm -m 的输出是否一致——CLI 加载成功不代表 FPM 进程池也加载了,两者用的是不同的 ini 扫描目录。这一点在跳转插件编译后加里有更细的依赖链拆解。
一个双行业混投团队的复盘
某团队做金融与教育双线投放,日均请求量在几十万级,服务器是 4 核 8G 的单机 LNMP。插件上线后金融线正常,教育线的落地页始终返回静态页。排查发现两个入口路径分属不同 server 块,教育线那个块是从旧配置复制来的,location ~ \.php$ 后面还跟着一段 try_files $uri $uri/ =404;,请求先被兜到静态目录就结束了。删掉这行、把 PHP location 前置后恢复。顺带把两个 server 块的公共段抽成 include,避免下次再复制出错。改完观察了半天,判定日志量与切流前的量级基本对齐,才算收尾。
收尾验证:三步确认请求真的进了执行链
改完配置不能只看页面能不能打开,要确认请求确实走到了插件判定环节。
- 在插件入口打一条临时访问日志,记录请求 URI、命中的 server 块与是否进入钩子,用一次真实访问验证日志有输出。
- 对比 Nginx access log 与插件判定日志的请求量级,两者数量级一致说明没有请求在转发层被截断。
- 做一次回放核验,把改写前的请求样本重放一遍,确认分支覆盖与预期一致,方法可参考空跑核验路径。
三步都过再撤掉临时日志,避免长期留着拖慢判定。
小结
插件不接管请求,本质是请求在 Nginx 或 PHP-FPM 某一层被提前处理掉了。排查顺序固定为:先按响应特征定位停在哪一层,再查 location 优先级与 try_files,然后核对 FPM 监听与扩展装载顺序,最后用日志量级比对和回放做收尾验证。配置改动用 nginx -t 与 php-fpm -t 双校验,reload 代替 restart,是这类环境排查的底线习惯。
常见问题
插件装好了但访问页面完全没有判定日志,先查哪里?
先看响应头里有没有 PHP 版本标识。没有就说明请求没进 PHP,去查 Nginx 的 location 匹配和 try_files。有版本标识但日志空,再查 FPM 进程池有没有加载插件扩展。
CLI 下 php -m 能看到插件,为什么线上还是不生效?
这个要看情况。CLI 和 FPM 用的 ini 扫描目录经常不是同一个,FPM 可能是独立的 pool 配置目录。分别跑一次 FPM 侧的模块列表对比,差异一眼就看出来了。
改完 Nginx 配置需要重启 PHP-FPM 吗?
只改 Nginx 侧 reload 就够了。动了 php.ini 或扩展加载顺序才需要 reload FPM。说白了,谁改了谁 reload,别图省事全量重启,正在跑的请求会被打断。
静态资源 location 写在前面一定会抢走插件入口吗?
取决于正则的匹配范围。如果静态正则能匹配到插件入口的后缀,且排在 PHP location 前面,就会命中。给入口路径加 ^~ 前缀或调整顺序都能解决,改完记得用 nginx -T 确认生效。
延伸阅读
如果排查完转发层还想把插件配置项的交接与回溯做扎实,可以接着看这份按风险信号拆解的核查清单:跳转插件配置交接核查清单