为什么企业微信机器人发送 markdown 消息渲染失败

企业微信机器人发送 Markdown 消息渲染失败，主要原因是请求参数中 msgtype 未指定为 markdown 或内容包含了平台不支持的语法元素。最推荐的处理方向是核对 API 请求体结构并剔除图片、表格等不支持标签，风险边界在于部分特殊字符转义可能导致内容显示异常。

先说结论：渲染失败通常由消息类型配置错误或语法超出官方支持范围导致，需优先检查 JSON payload 结构。

先确认：请求头 Content-Type 是否为 application/json 且 key 参数有效
先处理：将 msgtype 字段显式设置为 markdown 并移除图片链接
再验证：观察 API 返回 errmsg 字段是否为 ok 且客户端显示富文本

快速处理思路

若需立即恢复消息发送，可暂时切换为 text 类型消息，随后再排查 Markdown 语法兼容性。以下是一个可直接参考的最小化 Markdown 消息请求体示例，确保结构完全一致：

{
    "msgtype": "markdown",
    "markdown": {
        "content": "## 测试消息\n> 这是一段引用文本\n**加粗内容**"
    }
}

复制上述 JSON 替换原有请求体，若发送成功则证明原内容存在语法错误。

为什么会这样

企业微信机器人接口仅支持 Markdown 语法的子集，不完全兼容标准 CommonMark 规范。平台出于安全合规和渲染性能考虑，主动过滤了图片、表格、复杂 HTML 标签等元素，当请求中包含这些 unsupported 元素时，消息可能无法发送或直接显示为源码。

分步处理

按照以下顺序排查配置与内容，每步操作后需观察 API 响应状态：

步骤 1：核对请求地址与参数
确认 Webhook 地址格式为 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY，URL 中 key 参数必须与机器人配置一致。检查 HTTP 请求头 Content-Type 是否设置为 application/json，缺少该 header 会导致服务端无法解析 body。

步骤 2：检查 msgtype 字段
打开发送代码，查找 JSON 根节点下的 msgtype 字段。确保该字段值为字符串 "markdown"，若值为 "text" 则内容会被当作纯文本处理，不会触发渲染引擎。

步骤 3：清洗 Markdown 内容
遍历 markdown.content 字段内容，删除所有图片语法 ![alt](url) 和表格语法 |head|。保留支持的标题 #、加粗 **、列表 -、引用 > 和代码块 ```。若内容中包含 < 或 & 符号，建议进行 HTML 实体转义以防解析冲突。

步骤 4：检查内容长度
确认 content 字段总字符数未超过接口限制，过长的消息会被截断或拒绝。若不确定长度，可先发送短文本测试连通性。

怎么验证是否生效

发送请求后，检查 HTTP 响应 body 中的 errmsg 字段。若返回 "ok" 且 enterprise WeChat 客户端消息气泡显示加粗、标题等样式，则修复生效。若客户端仍显示纯文本，需再次确认 msgtype 是否被代码逻辑覆盖。

常见坑

图片链接无法渲染：企业微信 Markdown 消息不支持图片展示，强行插入会导致消息发送失败或忽略该部分
特殊字符转义遗漏：内容中包含双引号 " 时未在 JSON 中转义为 \"，会导致 JSON 解析错误
混用 HTML 标签：在 Markdown 内容中直接嵌入
或标签通常会被过滤或显示为源码
Key 参数泄露：Webhook key 具有发送权限，避免提交到公共代码仓库

常见问题

消息发送成功但显示为纯文本怎么办

检查请求体中 msgtype 字段是否被错误设置为 text，或客户端版本过低不支持 Markdown 渲染。

API 返回 errcode 40004 代表什么

通常表示消息类型不支持或参数格式错误，需确认 msgtype 值是否拼写正确且位于根节点。

支持发送超链接吗

支持，使用标准 Markdown 链接语法 [文本](URL) 即可，但 URL 必须是 https 开头且域名可信。

参考来源

企业微信官方文档：自建应用 - 机器人消息发送接口，https://developer.work.weixin.qq.com/document/path/91770
企业微信官方文档：消息类型说明，https://developer.work.weixin.qq.com/document/path/90236