排障中心

先排最常见的配置问题，再看代码。

拿不到 Update

  • 确认 `bot_token` 正确，没有多余空格。
  • 确认是否已启用 Webhook；启用后 Polling 可能返回空数组。
  • 确认你真的给 Bot 发了消息，且消息满足投递条件。
  • 群聊里确认是否 @ 了 Bot；默认不是全量监听。

Webhook 已配置但没有回调

  • 确认你的 Webhook URL 是公网 HTTPS，不是本地地址。
  • 确认回调路径和你实际启动的服务路径一致。
  • 确认隧道、反向代理或 CDN 没有吞掉请求体和关键 header。

群里不触发

  • 群聊默认 mention_only。
  • 只有 @Bot 或命令形式的消息会触发投递。
  • 不要把“群聊不触发”直接当成系统故障，先确认监听模式。

重复回消息

  • 确认你有推进 Polling 的 offset。
  • 确认你给发送接口传了稳定的 client_msg_id。
  • Webhook 路径要自己做去重，不能假设平台只投一次。

消息发送失败

  • 私聊目标用户可能未满足通信门禁。
  • to_user_id 和 group_id 只能二选一。
  • 建议每次发送都带 client_msg_id，避免重复重试造成混乱。
  • 如果你在群聊里回消息，请确认使用的是群 ID，而不是用户 ID。

Webhook 验签失败

  • 确认使用的是原始请求体，而不是解析后重新序列化的 JSON。
  • 确认服务端时间与标准时间没有严重偏差。
  • 确认使用了正确的密钥或验签参数。

建议的排查顺序

  1. 先检查 token 和接入模式。
  2. 再检查事件是否满足投递条件。
  3. 再检查请求参数和幂等字段。
  4. 最后检查签名、网络和服务端日志。

常见症状对照表

症状优先排查
Polling 一直空数组是否已启用 Webhook；是否真的有新事件；offset 是否过大。
Webhook 一直 401 / 403验签逻辑、时间戳窗口、密钥来源。
群里只有部分消息触发是否命中了 mention_only 规则。
消息重复发送offset 是否推进；client_msg_id 是否稳定。

FAQ

问题回答
为什么 Polling 返回空数组先确认 Bot 是否已切到 Webhook，再确认是否真的有新事件，以及当前 offset 是否推进过头。
为什么群里发消息不触发 Bot默认是 mention_only；只有 @Bot 或指定命令才会触发投递。
为什么消息会重复回复通常是 Polling 的 offset 没有持久化，或发送侧没有稳定使用 client_msg_id。
为什么 Webhook 签名一直失败优先检查是否对解析后的 JSON 重新序列化、服务端时间是否漂移、以及 secret 是否正确。
为什么拿到的是 file_url 而不是可下载直链平台默认返回受控资源地址；下载前需要通过 s/bot/files/batch_access 换取短期访问 URL。
为什么 batch_access 返回 null常见原因是 file_url 无权限、资源不存在、资源已过治理策略，或你传入的并不是平台受控 file_url。
为什么 parse_mode 看起来可用但文档不建议依赖因为当前更稳定的对外契约是显式传 data.entities；如果你需要富文本，优先按实体数组构造。