钉钉群机器人 Markdown ：颜色渲染 + 链接跳转 + 图片嵌入的正确实现

在企业办公场景中，钉钉群机器人是推送业务通知的常用工具，但很多开发者会遇到类似问题：link类型消息无法添加字体颜色、Markdown消息不知道如何集成链接 / 图片 。本文结合实际开发场景，讲解如何用Markdown消息实现 "颜色渲染 + 链接跳转 + 图片嵌入" 的整合，并避开所有常见坑点。

一、先理清：钉钉机器人 2 种消息类型的核心差异

在动手改造前，先明确link和Markdown这两种常用消息类型的格式支持范围（这是很多人踩坑的根源）：

消息类型	支持的格式	适用场景
`link`	仅纯文本，不支持任何 HTML/Markdown 标签；支持`picUrl`（左侧小图片）+`messageUrl`（跳转链接）	简单通知（需左侧图片 + 跳转）
`Markdown`	支持`<font>`颜色标签、文本链接、图片链接；不支持`picUrl`（需用图片链接替代）；仅`text`字段支持格式	需颜色渲染、复杂排版的通知

二、Markdown 消息：字体颜色的正确写法（避 3 个坑）

很多开发者用标签却不生效，核心是没避开这 3 个坑：

坑点 & 正确语法

标签必须闭合 ：必须写结尾，否则会显示原始标签；
色值必须完整 ：用 6 位十六进制色值（如#FF0000），不能简写 / 用英文颜色名（如red仅 PC 端生效）；
引号需转义 ：Java 中需用\"替代"，避免语法错误。

代码示例：带颜色的标题

复制代码

// 正确：闭合标签+完整色值+转义引号
String coloredTitle = "<font color=\"#FF0000\">已发布</font>";

三、Markdown 消息：链接与图片的实现（替代 link 类型）

如果需要跳转链接 （替代link的messageUrl）或图片（替代link的picUrl），Markdown 提供了原生支持：

1. 文本超链接（替代 link 的 messageUrl）

语法：[链接显示文本](完整URL)，可结合标签实现带颜色的可点击链接：

复制代码

// 带颜色的跳转链接（替代link的messageUrl）
String linkText = "[<font color=\"#0088FF\">点击查看详情</font>](https://xxx.com/order/20251212)";

2. 图片链接（替代 link 的 picUrl）

语法：![图片描述](公网图片URL)，需注意图片必须是公网可访问的（内网地址无法显示）：

复制代码

// 替代link类型的picUrl
String imageLink = "![业务截图](https://p3-flow-imagex-sign.byteimg.com/tos-cn-i-a9rns2rl98/xxx.png)";

四、完整改造：从 link 类型到 Markdown 类型

以用户原有的link类型代码为例，改造为支持颜色 + 链接 + 图片的 Markdown 消息：

原 link 类型代码（无法加颜色）

复制代码

// 原link类型：标题无法加颜色
String title = "<font color='#FF0000'>已发布</font>"; // 无效，会显示原始标签
MessageText message = new MessageText();
message.setMsgtype("link");
MessageLink messageLink = new MessageLink();
messageLink.setText(text);
messageLink.setTitle(title);
messageLink.setPicUrl(picUrl);
messageLink.setMessageUrl(messageUrl);
message.setLink(messageLink);

改造后的 Markdown 类型代码（支持所有格式）

复制代码

// 1. 构建带颜色+图片+链接的Markdown文本
String markdownText = String.format(
    "%s \n" + // 图片链接（替代link的picUrl）
    "%s \n" + // 带颜色的标题
    "> %s \n" + // 业务文本
    "%s", // 跳转链接（替代link的messageUrl）
    "![业务截图](" + picUrl + ")", // 图片需为公网URL
    "<font color=\"#FF0000\">已发布</font>", // 红色标题
    text, // 原业务文本
    "[<font color=\"#0088FF\">点击查看详情</font>](" + messageUrl + ")"
);

// 2. 构造Markdown类型消息
MessageText message = new MessageText();
message.setMsgtype("markdown");

MessageMarkdown messageMarkdown = new MessageMarkdown();
messageMarkdown.setTitle("已发布"); // Markdown的title仅支持纯文本（不渲染格式）
messageMarkdown.setText(markdownText); // text字段渲染所有格式
message.setMarkdown(messageMarkdown);

五、必看避坑总结

link类型天生不支持标签 ：不要尝试在link的title/text中加/ 链接，会直接显示原始字符串；
Markdown 的title字段无格式 ：仅text字段支持、链接、图片；
图片 URL 必须公网可访问：内网图片链接在钉钉中无法加载；
引号必须转义 ：Java 中用\"包裹的color属性，避免 JSON 语法错误；
色值用 6 位十六进制 ：#FF0000（红色）生效，red（仅 PC 端生效）、#F00（不生效）需避开。