遇到企微机器人 Markdown 消息发送失败或显示异常，最直接的止血方案是暂时切换为 text 类型消息，确保通知可达，再对照官方支持的标签子集逐步调整 Markdown 内容。
先说结论：格式错误通常是因为使用了不支持的 Markdown 标签、特殊字符未转义，或 JSON 结构键名错误，优先简化内容保送达。
- 先确认：检查 API 返回的 errcode 和 errmsg，区分是 JSON 结构错误还是内容格式错误。
- 先处理：移除表格、图片等不支持的语法，保留基础的加粗和链接。
- 再验证：使用 curl 或 Postman 发送最小化 payload 测试 webhook 连通性。
- 关键修正：切换类型时，不仅改 msgtype，还要将 body 中的 text 键改为 markdown 键。
快速处理思路
如果不熟悉 Markdown 语法限制，建议先用纯文本发送，确认 webhook 正常后再逐步添加格式。
{
"msgtype": "text",
"text": {
"content": "测试消息，确认机器人存活"
}
}确认文本可发送后，再将 msgtype 改为 markdown，同时将 text 键改为 markdown，格式如下：
{
"msgtype": "markdown",
"markdown": {
"content": "## 标题\n**加粗**\n[链接](url)"
}
}curl 调试命令示例
使用 curl 命令可以直接在终端验证 webhook 是否可用，避免代码封装带来的干扰。
curl -X POST "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"msgtype":"markdown","markdown":{"content":"## 测试\n正常显示"}}'典型错误响应报文
发送失败时，API 会返回具体的错误码，常见情况如下：
1. JSON 结构错误（400）：
{
"errcode": 400,
"errmsg": "invalid json data"
}2. Key 无效或过期：
{
"errcode": 40003,
"errmsg": "invalid webhook key"
}分步处理
第一步：检查 API 响应
查看 HTTP 响应体。如果 errcode 不为 0，根据 errmsg 定位。如果是 400 错误，通常是 JSON 格式问题；如果是发送成功但显示异常，则是语法不支持。
第二步：简化 Markdown 内容
只保留官方明确支持的语法，例如：
- 标题：
## 标题 - 加粗：
**bold** - 链接：
[name](url) - 引用：
> quote
移除所有表格、图片、代码块高亮语言指定（如 ```java 可能不支持，建议用 ``` 通用）。
第三步：处理特殊字符
如果内容中包含双引号、反斜杠，必须在 JSON 中进行转义。例如内容里的引号需写成 \"。
怎么验证是否生效
1. 观察 API 返回："errcode": 0 且 "errmsg": "ok"。
2. 观察企微群聊：消息正常渲染，没有显示源码标签，没有乱码。
3. 点击链接：如果有链接，确认能否正常跳转且不被拦截。
常见坑
- 表格语法：标准 Markdown 表格语法在企微中通常不支持，会显示为纯文本。
- 换行符：JSON 字符串中的换行需用
\n，且 Markdown 段落间可能需要空行才能生效。 - 内容长度：消息内容过长会被截断或发送失败，需注意官方限制。
- 特殊符号：内容中若包含
<或>可能被误认为 HTML 标签，建议转义。 - Body 键名错误：切换 msgtype 为 markdown 时，忘记将外层键名从 text 改为 markdown，导致 API 报参数错误。
参考来源
- 企业微信开发者文档 - 群机器人消息发送：https://developer.work.weixin.qq.com/document/path/91770