企业微信 Markdown 消息渲染失败通常是因为 JSON payload 中的特殊字符未转义或使用了不支持的 Markdown 语法。调试时优先检查 API 返回码，确认 content 字段符合官方支持的标签子集，并验证换行符是否正确编码。
先说结论：大部分渲染失败源于 JSON 转义遗漏或 Markdown 语法超出了企业微信 API 支持的范围。
- 先确认：检查 HTTP 响应状态码及 errcode 是否为 0
- 先处理：对 content 内容中的双引号、反斜杠和换行符进行标准 JSON 转义
- 再验证：发送测试消息到个人聊天窗口，观察实际渲染效果
命令速用版
使用 curl 命令可以快速构造并发送测试请求，便于隔离代码逻辑问题。
curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' -H 'Content-Type: application/json' -d '{"msgtype":"markdown","markdown":{"content":"# 标题\n你好，世界"}}'注意：命令中的换行符 \n 在 JSON 字符串中必须保留为两个字符反斜杠加 n。
为什么会这样
企业微信机器人接口对 Markdown 语法的支持是子集，且消息内容必须包裹在合法的 JSON 结构中。
API 服务端在解析请求时，会先解码 JSON payload，再解析 content 字段中的 Markdown。如果 JSON 层转义错误，服务端无法读取 content 内容；如果 Markdown 语法不支持，服务端会忽略标签或显示源码。常见原因包括未在 JSON 层转义双引号导致解析截断，或使用了表格、代码块等未完全支持的语法。
分步处理
按照以下顺序排查，每一步确认无误后再进行下一步。
步骤 1：检查 API 响应
查看发送请求后的 HTTP 响应 body。如果 errcode 不为 0，根据 errmsg 提示修改。如果 errcode 为 0 但渲染失败，说明请求合法但内容格式有问题。
步骤 2：验证 JSON 转义
确保 content 字段内的特殊字符符合 JSON 标准。双引号 " 必须转义为 \"，反斜杠 \ 必须转义为 \\，换行符必须写作 \n 而不是实际回车。
步骤 3：简化 Markdown 语法
移除所有复杂语法，只保留标题（#）、加粗（**）和链接（[]()）。如果简化后能正常渲染，说明是特定语法不支持导致的。
怎么验证是否生效
发送消息后，在企业微信客户端查看消息卡片。
正常渲染时，标题会加粗变大，链接可点击，换行符合预期。如果看到源码（如 **bold** 直接显示），说明 Markdown 解析未生效，需检查 content 字段是否被正确识别为 markdown 类型。
常见坑
- 换行符错误：在代码字符串中直接按回车而不是使用 \n，导致 JSON 格式非法。
- 特殊字符冲突：content 内容中包含双引号未转义，截断了 JSON 字符串。
- 语法支持误区：以为支持所有 Markdown 语法，实际仅支持部分常用标签。
常见问题
消息发送成功但显示为纯文本
msgtype 参数可能错误设置为 text 而非 markdown，或者 content 中的 Markdown 符号被额外转义。
链接无法点击或显示异常
企业微信对链接域名可能有安全限制，或 Markdown 链接语法 []() 中间包含了空格。
content 长度有限制吗
公开资料中没有看到可靠的量化数据，建议参考企业微信官方开发者文档的最新说明，通常建议控制在合理范围内。
参考来源
- 企业微信开发者文档 - 群机器人：https://developer.work.weixin.qq.com/document/path/91770