本文系统性拆解第一层的完整实操要点。
上个月一个做教育投放的团队把跳转插件部署到新服务器后,后台日志显示规则已加载,但真实请求始终停在默认页。问题不在插件代码,而在Nginx到PHP-FPM的请求链路里,某个环节静默截断了跳转信号的传递。跳转不生效的排查,成败取决于你是否按请求流经的顺序逐层验证,而不是一上来就翻插件日志。
这篇文章按一个真实请求从进入服务器到返回响应的路径,把排查拆成四个层:入口转发、PHP执行、插件判定、响应输出。每一层先讲你会看到什么症状,再讲原因和检查步骤,最后给出收尾验证方法。
第一层:入口转发——请求有没有真正到达PHP
症状信号
浏览器访问测试URL,返回的是Nginx默认欢迎页、404页面,或者一个静态HTML文件的内容,而不是插件输出的跳转逻辑。检查PHP-FPM的slow log,发现根本没有对应的请求记录。
原因定位
这层最常见的原因是Nginx的location匹配规则把请求交给了错误的handler。比如一个location ~ \.php$块只匹配以.php结尾的URI,但你的跳转入口是一个伪静态路径如/go/abc,Nginx找不到匹配规则就会落到默认的root目录去找静态文件。另一个常见原因是try_files指令的fallback顺序写错了,请求被重定向到了一个不存在的静态路径。
检查步骤
- 在Nginx配置中确认跳转入口路径有对应的location块,且
fastcgi_pass指向正确的PHP-FPM监听地址(Unix socket或127.0.0.1:9000)。 - 用
curl -I请求跳转URL,观察返回的Server头和Content-Type。如果Content-Type是text/html且没有X-Powered-By头,说明请求没进PHP。 - 临时在location块里加一行
add_header X-Debug-Handler "php";,重新加载Nginx后请求,看响应头里是否出现这个标记。
收尾验证
确认请求进入PHP后,去掉调试头,用curl -v完整看一次请求和响应,确认状态码是200或302而非404。
第二层:PHP执行——脚本有没有跑完
症状信号
请求返回了PHP的输出,但内容是空白页、半截HTML,或者一个PHP Fatal error的报错信息。PHP-FPM的error log里有对应时间点的记录。
原因定位
这层的问题分两类。一类是执行超时:跳转判定逻辑里如果有同步等待外部接口的调用,而request_terminate_timeout设得太短,脚本会在判定完成前被FPM杀掉。另一类是依赖缺失:插件依赖的某个PHP扩展(如curl、json、mbstring)没装,脚本在初始化阶段就挂了。
检查步骤
- 查看PHP-FPM的error log和slow log,确认是否有“execution timed out”或“child exited on signal”的记录。
- 写一个临时的
phpinfo()探针文件放在同目录下,访问它确认所有必需扩展已加载。 - 检查
php.ini里的max_execution_time和FPM池配置里的request_terminate_timeout,确保后者大于前者。
收尾验证
用一个最小化的测试脚本,只输出一行固定文本,确认PHP能正常执行。然后逐步加回插件依赖,定位到具体哪一步中断。
第三层:插件判定——规则有没有命中
症状信号
PHP正常执行,页面也返回了,但返回的是默认页而非预期页面。插件的调试日志里能看到请求进来了,但判定结果始终是“无匹配规则”。
原因定位
这层的问题出在判定逻辑的输入上。常见原因有三个:请求头里的关键字段(如User-Agent、Referer)被上游代理或CDN改写或清空了;规则配置里的匹配条件写得太窄,比如同时要求UA包含某关键词且IP落在某网段,实际请求只满足一个;缓存里存了旧的判定结果,新规则没生效。
检查步骤
- 在插件入口处打印完整的请求头快照,确认判定所依赖的字段确实存在且值符合预期。
- 检查规则配置里的条件组合是AND还是OR关系,逐条单独测试每个条件的命中情况。
- 清空判定结果缓存,或者确认缓存TTL是否已过期。参考访客判定先读缓存中的缓存优先策略,确认你的缓存键是否包含了所有影响判定的字段。
收尾验证
用一条最宽松的规则(比如只匹配一个固定参数值)测试,确认判定链路本身是通的。然后逐步收紧条件,找到导致不命中的那个条件。
第四层:响应输出——跳转动作有没有发出
症状信号
判定日志显示规则已命中,但浏览器没有跳转,或者跳转到了错误的URL。
原因定位
这层的问题在输出阶段。如果是302跳转,检查header('Location: ...')之前有没有任何输出(包括BOM头、空格、调试echo),这些会导致header发送失败。如果是JS跳转,检查输出的HTML里script标签是否被模板引擎转义了。另外,如果URL参数在拼接时没有做urlencode,特殊字符会截断目标地址。
检查步骤
- 在发送跳转header之前,确认没有任何echo、print或HTML输出。
- 用
curl -I看响应头里的Location字段,确认目标URL完整且参数未被截断。 - 如果用的是JS跳转,查看页面源码里script标签的内容是否被转义成了
<script>。
收尾验证
用一个带特殊字符参数的测试URL,确认跳转后的目标地址参数完整。再跑一遍斗篷系统上线三阶段核验里的核验项,确认所有配置项都处于预期状态。
常见问题
跳转插件部署后不生效,最该先查哪个日志?
这个要看情况。如果请求根本没到PHP,Nginx的access log里会有记录但PHP-FPM的log是空的,那就先查Nginx的location配置。如果PHP-FPM的log里有报错,那就先看error log里的超时或扩展缺失记录。说白了,先确认请求走到了哪一层,再决定看哪个日志。
Nginx配置改完后跳转还是不生效,需要重启PHP-FPM吗?
Nginx的location和fastcgi_pass改动只需要nginx -s reload就能生效,不需要动PHP-FPM。但如果你改的是PHP-FPM池配置里的环境变量或进程数,那就必须重启FPM。顺带说一句,我一般还会在reload之后用nginx -t确认配置语法没问题,避免reload失败后旧配置还在跑。
跳转判定日志显示命中但浏览器没反应,是什么原因?
大概率是输出阶段出了问题。检查跳转header发送之前有没有意外的输出,哪怕是一个空格或UTF-8 BOM都会导致header失败。如果是JS跳转,看看script标签是不是被模板引擎转义了。另外确认一下浏览器有没有缓存之前的302响应,用无痕窗口再试一次。
延伸阅读
排查完跳转链路后,如果你正准备从零搭建一套完整环境,这篇部署指南把服务器初始化到插件联调的每一步都拆开了,可以作为实施时的对照参考。