回调收不到是最让人抓瞎的一类问题。因为消息发出去的那一刻你这边什么都看不到。这篇按请求到底走到哪一步的顺序排一段一段往前推比乱试配置快得多。第一段请求有没有到服务器先别管代码先看服务器有没有收到过请求。两个地方查Nginx access log。如果日志里连一条POST /wx-api/webhook/都没有问题在网络层代码完全没参与。往下看防火墙和端口。tcpdump抓包。在服务器上跑一条tcpdump -i any -n port 443 and host 平台出口IP有包进来就说明网络通了没包就是被挡在外面。被挡住的常见原因安全组没开 443、WAF 拦截了 POST、只放行了白名单 IP 而实际出口不在名单里、CDN 回源配置错。第二段请求到了但被什么拦了日志里有请求但你的应用没收到中间多半有东西拦着。路径对不上。回调路径是/wx-api/webhook/动作末尾有没有斜杠是两回事。Nginx 里location /wx-api/webhook和location /wx-api/webhook/匹配规则不一样配错了就是 404。方法不对。验证回调地址时平台可能会用 GET 带echostr探一下也可能直接 POST 一条测试事件。如果你的路由只写了 POST验证这一步就过不去。框架层拦截。Spring Security、CSRF 过滤、请求体大小限制、Content-Type 校验任何一个都可能把请求挡在业务代码前面。临时把安全过滤对这条路径放行验证通了再逐条加回来。返回了非 2xx。你自己返回 500 或 403平台侧看到的就是投递失败会重试几次然后放弃。查日志时别只看有没有收到要看回了什么状态码。第三段到了也进了业务但验签不过这类最隐蔽。请求进来了代码也跑了但被验签直接拒了日志里只有一行 403。三个高频原因密钥用错。验签用的是控制台生成的签名密钥不是 App Token也不是 appid。三者长得完全不一样别混。请求体被读过一次。很多框架在中间件里已经反序列化过 body业务代码再get_data()拿到的是空字节流。空 body 算出来的签名当然不对。要么在过滤器里提前缓存原始字节要么直接用框架提供的 raw body 接口。编码不一致。报文里有中文按 UTF-8 取字节算 HMAC。如果中间某层按 GBK 转了一次签名就对不上。验签不过时建议把算出来的签名和收到的签名都打日志只打前八位别打全一眼就能看出是算法不对还是body 不对。第四段验签过了但消息还是丢了最后一层是业务自己吞掉了。异常被 catch 后没往外抛。try: handle() except: pass这种写法出错了你什么都不知道。至少要记 error 日志带堆栈。处理超时。回调需要在 5 秒内返回超时平台会当成失败重投。如果你的处理里同步调了外部接口或跑了 AI很容易超。做法是先落库直接返回ok业务扔到异步队列。幂等做反了。用uin 内容做去重键客户连发两条一样的话第二条被当成重复丢掉。去重键应该用投递头里的X-Eyun-Delivery它才是投递的唯一标识。消息类型没判断对。messageType是会话类型0 单聊、1 群聊、3 系统通知不是消息内容类型。拿它当 contentType 用分支永远进不去。一套能省时间的排查顺序平台侧看投递记录有没有失败原因服务器看 access log有没有请求进来抓包确认网络通不通打一行进入回调的日志确认代码执行到哪验签的输入输出都打出来比对检查返回状态码是不是 200按这个顺序走一般两三轮就能定位。最忌讳的是反过来——先改代码改完发现请求根本没到服务器。上线前建议用一个临时脚本模拟一次投递把整条链路先跑通比等真实消息来的时候手忙脚乱强。