ThinkPHP调用飞书消息卡片API需严格满足三点：一是显式设置Content-Type: application/json并json_encode发送；二是交互回调须用php://input读取+AES解密+验签；三是避免AppID/Webhook混用、中文标点、HTTP回调等常见错误。
ThinkPHP 6/8 中调用飞书消息卡片 API 的核心限制
飞书消息卡片（interactive 类型）必须通过 POST /open-apis/message/v4/send 接口发送，且请求体是严格校验的 JSON 结构。ThinkPHP 默认的 Http::post() 或 curl_init() 封装若未显式设置 Content-Type: application/json、未用 json_encode() 序列化 payload，或忽略 msg_type=interactive 字段，卡片会直接退为纯文本或返回 "error_code": 99991402（参数非法）。
构造合法的卡片 JSON 需绕过 ThinkPHP 的自动表单编码
ThinkPHP 的 think\facade\Http::post() 在传入数组时默认以 application/x-www-form-urlencoded 发送，这会导致飞书服务端解析失败。必须手动处理：
- 用
json_encode($cardData, JSON_UNESCAPED_UNICODE)构造原始 JSON 字符串 - 显式设置 header：
['Content-Type' => 'application/json'] - 禁用自动 form 编码：传入字符串而非数组作为 body
- 注意
config('app.app_debug')开启时，某些中间件可能拦截非标准 Content-Type 请求
示例关键代码片段：
$cardData = [
'msg_type' => 'interactive',
'card' => [
'elements' => [[
'tag' => 'div',
'text' => ['content' => '✅ 构建成功', 'tag' => 'plain_text']
]],
'header' => ['title' => ['content' => 'CI 通知', 'tag' => 'plain_text']]
]
];
$response = Http::withHeaders(['Content-Type' => 'application/json'])
->post('https://open.feishu.cn/open-apis/message/v4/send', json_encode($cardData, JSON_UNESCAPED_UNICODE));
卡片交互回调（如按钮点击）在 ThinkPHP 路由中如何安全接收
飞书对交互事件（interactive 消息中的按钮、菜单触发）会向你配置的 Request URL 发起 POST，但 Body 是加密的 encrypt 字段，不是明文 JSON。不能直接用 input() 或 request()->post() 解析。
立即学习“PHP免费学习笔记（深入）”；
- 必须先从
file_get_contents('php://input')读取原始 POST body - 再用飞书提供的 AES-256-GCM 解密逻辑还原事件对象（官方 SDK 有 PHP 实现，但 ThinkPHP 项目中需自行集成）
- 解密后验证
timestamp和nonce防重放，否则可能被伪造请求触发业务逻辑 - 响应体必须是空 JSON
{}且 HTTP 状态码为 200，否则飞书会持续重试
调试时最常踩的三个坑
飞书卡片在 ThinkPHP 环境下失败，八成卡在这三处：
-
AppID和AppSecret拿错：机器人用的是 Webhook 地址，不是开放平台应用的凭证；发卡片必须用access_token（需先用 AppID/AppSecret 换取），不是 Webhook - 卡片 JSON 中用了中文标点或不可见 Unicode 字符（如全角空格），导致签名计算不一致，报错
"error_code": 99991401 - 本地开发用
http://localhost做回调地址：飞书只接受 HTTPS，且域名需备案、能公网访问；调试建议用ngrok或localtunnel临时映射
卡片结构本身容错率极低，一个字段名拼错（比如把 tag 写成 type）、少一个必填字段（如 header.title.tag），就会静默降级为文本消息——这点和微信模板消息不同，没有明确错误提示，只能靠日志比对飞书最新 Schema 文档。
