上个月有个做金融投放的团队,跳转插件部署完了,规则也照着文档配了两条,结果打开落地页地址,永远停在标准页上。他们第一反应是规则写错了,来回改了三版关键词条件,还是不动。后来把入口日志拉出来一看——请求压根没进到规则引擎,卡在Nginx转发那一层。跳转插件部署后跳转不生效,这事儿吧,问题很少出在规则本身,先确认信号走到哪一步,比改配置快得多。下面按排查顺序拆开说。
先看入口:请求到底有没有到达判定层
跳转不生效的第一层症状,说白了就是请求根本没进入判定逻辑。这时候你改任何规则都是白费劲。
检查顺序我建议固定下来:
- 到Nginx的access log里翻,确认请求已经打到配置的location,状态码是200还是被rewrite成了别的路径。
- 打开PHP-FPM的慢日志或者错误日志,看看对应脚本有没有执行记录。
- 在插件入口最前面写一行临时落盘,把请求URI和UA写进文件,看是否有内容。
这三步能区分三种情况:请求没到Nginx、到了但没转发给PHP、PHP执行了但判定结果为空。那个金融团队卡在第二步——反代的location把子路径吞掉了,插件入口根本没被执行。
顺带说一句,如果站点前面还套了CDN,先确认回源请求带着原始URI,别被CDN的路径重写规则改掉了。
条件求值没命中:先看输入快照长什么样
请求进来了,插件也跑了,但跳转还是不发生,下一步看条件求值的输入。常见症状是日志里判定结果一直走默认分支。规则引擎读的是请求快照,快照里字段缺失或口径不对,条件就永远不命中。排查时把这条请求的完整快照打出来(UA、Referer、Cookie、URL参数、IP),逐条对照规则条件。典型坑有三个:
- URL参数名大小写不一致,规则里写
utm_source,实际传的是UTM_SOURCE。 - 参数在跳转链路里被过滤了,规则读不到值。这类问题可以参考参数过滤的例外白名单里的豁免配置思路,把需要参与判定的参数放行。
- Cookie没播种成功,首访请求里没有会话标识,条件依赖Cookie的判断直接落空。
这一步的收尾验证很简单:拿一条真实请求,手动构造快照喂给判定函数,看输出是不是预期分支。
动作被覆盖:命中之后为什么还是没跳
条件命中了,日志里也能看到分支被选中,但浏览器最终停在了别的页面。这是最容易被误判成“插件没生效”的一类症状,实际是动作被后面的逻辑覆盖了。排查顺序:
- 看判定日志里动作链的完整输出,是只有一个跳转动作,还是后面又跟了一个默认落点。
- 检查默认分支和显式规则的执行顺序。默认分支如果排在显式规则后面,会把已命中的跳转动作压掉。这类顺序问题在默认分支与显式规里有完整修复路径。
- 确认插件输出的是302还是JS跳转,两种方式在响应头处理上不一样。JS方式如果输出了HTML但后面还有模板渲染,可能被整页覆盖。
修复动作通常是调整动作链顺序,让显式跳转动作最后执行,或者给默认分支加一个“仅在前面无动作时生效”的标记。
响应被缓存:修好了却像没修
配置改对了,刷新页面还是老样子,这种情况先怀疑缓存,别急着回滚。分三层看:
- Nginx层面的proxy_cache或fastcgi_cache,可能把上一次的判定结果缓存住了。检查缓存键里有没有把UA或Cookie排除在外,如果缓存键只按URL哈希,不同访客会拿到同一个版本。
- 插件自身的判定缓存,TTL设得太长,配置更新后旧结果还在生效。
- CDN边缘节点缓存,回源请求被拦在前面。
验证方法:给URL加一个随机查询参数强制绕缓存,看跳转是否恢复正常。如果加了参数就正常,说明是缓存键设计问题,参考斗篷系统缓存键设计误区调整键结构。
收尾验证:一条请求走完四个检查点
排查完不代表修好了,要有一条能重复跑的验证路径。建议固定成四步:
- 构造一条带完整参数的测试请求,确认入口日志有记录。
- 打快照,确认判定输入字段齐全。
- 看判定日志,确认命中的分支和动作链顺序符合预期。
- 清缓存后重放请求,确认响应状态码和Location头正确。
四步都过,才把临时落盘代码删掉,把缓存TTL恢复成正式值。中间任何一步对不上,回到对应小节重新查。这套顺序比“改规则—刷新—再改规则”省时间,也避免把已经正确的配置改坏。
常见问题
跳转插件装好后完全不跳,最可能是什么原因?
先看请求有没有到插件入口。多数情况是Nginx的location配置把插件路径排除在外了,或者反代规则把子路径改写了。确认入口日志有记录,再往下查条件求值。
规则条件明明命中了,页面还是停在标准页是怎么回事?
这个要看动作链。条件命中只说明分支被选中,后面如果还有默认落点或者模板渲染覆盖了跳转响应,浏览器最终看到的就是标准页。去判定日志里看动作执行顺序。
改了配置之后跳转还是老样子,是不是没生效?
大概率是缓存。Nginx层、插件自身、CDN边缘三层都可能缓存住旧结果。给URL加个随机参数试试,如果加了就正常,说明缓存键需要调整。
跳转插件部署后需要重点检查哪些配置项?
入口转发路径、条件读取的字段口径、动作链顺序、缓存键结构这四项。前三项决定跳不跳,第四项决定改动后多久生效。顺带说一句,我一般还会把临时日志的落盘路径也确认一遍,避免排查时找不到记录。
排查完之后怎么确认真的修好了?
用一条带完整参数的请求走一遍入口、快照、判定日志、响应头四个检查点。四步都过再删临时代码、恢复缓存配置。别只看一次浏览器刷新,缓存和会话状态会让结果不稳定。
延伸阅读
排查顺序理清之后,如果还卡在插件本身的安装与目录配置上,这篇安装指南把路径和权限部分讲得更细,可以对照着核一遍。