第五十九天

飞书机器人开发踩坑总结
近期落地飞书Webhook+机器人对接项目，踩满各类协议、部署、接口规范深坑，整理成可复用踩坑备忘录，后续新项目开工优先翻阅，大幅减少重复试错成本。

一、逐项踩坑复盘

1. Schema版本混用（Webhook v1 / OpenAPI v2 格式不兼容）

问题：Webhook回调是v1规范（ elements 在JSON顶层字段），业务调用飞书API使用v2版本，v2要求数据嵌套在 body.elements ，同时报文必须携带 schema:"2.0" 标识，混用直接解析报错。
解决方案：做数据格式中转适配，收到Webhook原始数据后做字段层级转换，区分回调入参、主动调用API两套Schema规范。

2. 接口返回400错误：返回content格式不达标

问题：机器人回复接口直接传JSON对象触发参数非法，平台校验要求 content 字段只能是JSON.stringify序列化后的字符串，不能裸对象。
固定写法： content: JSON.stringify({text:"内容"}) ，统一封装返回工具函数。

3. Bot Not Enabled 机器人未启用报错

根因：代码配置已添加机器人权限，但后台应用未勾选对应机器人能力，且未发布应用新版本，权限不生效。
处理流程：开发者后台开启机器人能力 → 发布应用新版本 → 重启服务。

4. 收不到任何事件回调

高频失误：回调配置填写 localhost 本地地址，飞书云端无法访问内网地址推送事件。
规范：回调域名/IP必须为公网可访问地址，本地调试用内网穿透。

5. 本地调试localhost连接超时

解决：放弃原生localhost直连调试，使用ngrok做内网穿透，生成公网临时地址填入飞书回调配置。

6. 服务重启丢失配置

问题：配置数据仅内存存储，进程重启参数全部清空。
规范：关键配置落地持久化（文件/数据库），启动时从本地文件加载配置。

7. 第三方请求导致服务器崩溃

诱因：axios请求无超时限制、异步异常未捕获，接口阻塞+未捕获Promise报错导致进程宕机。
优化：axios统一配置timeout超时时间；所有async异步代码包裹 try-catch 捕获异常。

二、项目落地使用建议

新项目开发第一步：先打开这份文档逐项核对规范，从源头规避80%经典坑位。

1. 开发前期：区分飞书Webhook版本与OpenAPI版本，提前定义数据转换中间层；
2. 本地联调：固定使用ngrok穿透，杜绝localhost填回调；
3. 上线前：校验机器人能力+应用版本已发布、配置持久化落地、全链路异常捕获与超时配置。