Telegram Bot 消息格式化详解：MarkdownV2 与 HTML 语法指南

这是一个基于 Telegram Bot API 官方文档编写的指南，详细介绍了如何通过 Bot 发送带有格式（如加粗、链接、代码块等）的消息。

Telegram Bot API 允许开发者发送富文本消息，支持加粗、斜体、代码块、链接预览以及隐藏的“剧透”内容等。为了让客户端正确渲染这些样式，开发者需要在发送消息时指定 parse_mode 字段。

本文将详细介绍三种支持的格式化模式：MarkdownV2（推荐）、HTML 和 Markdown（旧版），以及相关的规则和注意事项。

一、 通用规则与特性

在深入具体语法之前，了解以下通用规则非常重要：

1. 支持的样式

Telegram 客户端支持以下基础样式：

• 加粗、斜体、下划线、删除线
• 剧透（Spoiler，点击后才显示内容）
• 引用块（Blockquote）及可展开的引用块
• 内联链接、内联用户提及
• 行内代码、预格式化代码块（支持语法高亮）

2. 嵌套规则

样式实体可以相互嵌套，但必须遵守以下限制：

• 层级关系：如果两个实体有重叠字符，其中一个必须完全包含在另一个内部。
• 代码限制：pre 和 code 实体内部不能包含任何其他样式。
• 通用嵌套：加粗、斜体、下划线、删除线和剧透可以包含除 pre 和 code 之外的任何内容，也可以相互包含。
• 引用块限制：blockquote 和 expandable_blockquote 彼此不能嵌套。

3. 用户提及 (Mention)

你可以使用 tg://user?id=<user_id> 格式的链接通过 ID 提及用户（无需用户名）。

• 注意：此类链接仅在内联链接或内联键盘按钮中有效。
• 隐私限制：除非该用户是当前群组成员，或者曾私聊过 Bot/通过内联按钮互动且未开启转发隐私保护，否则提及可能无法生效。

二、 MarkdownV2 样式（推荐）

这是功能最全的 Markdown 模式，如果要使用 Markdown 语法，请务必使用 MarkdownV2。

1. 语法参考

将 parse_mode 设置为 MarkdownV2。

2. 重要：转义规则 (Escaping)

MarkdownV2 对转义要求非常严格。

• 任何 ASCII 码在 1 到 126 之间的字符都可以通过前置 \ 进行转义。
• 字符 \ 本身必须转义为 \\。

必须转义的场景：

1. 在 pre 和 code 内部：只有 ` 和 \ 需要转义。
2. 在链接 (...) 部分内部：只有 ) 和 \ 需要转义。
3. 在其他所有地方，以下字符必须加 \ 转义：_, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !

3. 常见陷阱

• 下划线歧义：解析器会贪婪匹配 __ 为下划线。如果你想写“斜体紧接下划线”（如 ___italic underline___），会导致错误。解决方法是插入一个空的加粗实体进行分隔：___italic underline_**__。

三、 HTML 样式

如果你更习惯 Web 开发，HTML 模式是很好的选择。

1. 语法参考

将 parse_mode 设置为 HTML。

2. HTML 转义规则

由于使用了 < 和 > 作为标签，非标签内容的特殊字符必须替换为 HTML 实体：

• < 替换为 <
• > 替换为 >
• & 替换为 &

注意：API 仅支持上述列表中的标签，不支持其他 HTML 标签（如 h1, br 等，换行请直接使用 \n）。

四、 Markdown 样式（旧版/Legacy）

注意：这是为了向后兼容保留的模式。它不支持下划线、删除线、剧透、引用块等新特性，且不支持嵌套。建议新开发均使用 MarkdownV2。

1. 语法简述

将 parse_mode 设置为 Markdown。

• 加粗：*text*
• 斜体：_text_ (注意不能像 V2 那样用 ~ 或 __)
• 代码：`text` 或 block
• 链接：[text](url)

2. 局限性

• 不可嵌套：你不能在加粗文字里放斜体。
• 转义不同：在实体外部，只有 _, *, `, [ 需要转义。在实体内部不允许转义（这意味着你无法在斜体文字中显示下划线字符，除非先结束斜体再重新开启）。

五、 自定义 Emoji (Custom Emojis)

如果 Bot 拥有者购买了 Telegram Premium，或者 Bot 在 Fragment 购买了额外的用户名，Bot 可以在消息中使用自定义 Emoji。

• MarkdownV2: ![👍](tg://emoji?id=5368324170671202286)
• HTML: <tg-emoji emoji-id="5368324170671202286">👍</tg-emoji>

说明：必须提供一个替代的普通 Emoji（如上例中的 👍），以便在不支持自定义 Emoji 的地方（如系统通知）或非会员转发时显示。

总结建议

1. 首选 MarkdownV2：功能最强大，支持所有新特性。但要注意其严格的转义规则（尤其是标点符号 . 和 ! 等）。
2. 备选 HTML：如果你觉得 MarkdownV2 的转义太繁琐，HTML 是更稳定且易于阅读的选择，特别是对于复杂的文本结构。
3. 弃用旧版 Markdown：除非维护旧代码，否则不要使用 Legacy Markdown。