Telegram机器人发送Markdown格式消息完整教程：从基础到避坑指南

在Telegram机器人开发中，消息格式化是提升用户体验的重要方式。通过Markdown语法，你可以让消息中的文字加粗、斜体、显示代码块或链接，使内容层次分明、阅读更加舒适。然而，不少开发者在实际调用Bot API时，常常因为转义规则而遇到消息发送失败的问题。本教程将为你系统讲解Telegram机器人发送Markdown格式消息的全部知识点，从基础用法到进阶避坑，助你一次掌握。

什么是Telegram机器人的Markdown解析模式？

Telegram Bot API支持在发送消息时通过parse_mode参数指定文本解析模式。该参数可以设置为以下三种值之一：

• Markdown：传统Markdown解析器，支持常用格式，但语法较为宽松。
• MarkdownV2：Markdown的升级版，功能更丰富，支持更多实体类型，但对特殊字符的转义要求非常严格。
• HTML：使用HTML标签解析，格式稳定，适合复杂嵌套。

本教程重点讲解Markdown和MarkdownV2的使用方法。注意，解析模式需要在每次调用sendMessage等方法时显式指定，官方没有提供全局设置接口，但你可以通过代码封装来统一设置默认值。

发送Markdown格式消息的基本步骤

下面以发送一条包含加粗文字的普通消息为例，演示调用Bot API的具体过程。

步骤1：获取机器人令牌

通过@BotFather创建机器人后，你将获得一个访问令牌（Token），格式类似123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。所有API请求都需要携带此令牌。

步骤2：调用sendMessage接口

使用GET或POST请求发送到https://api.telegram.org/bot<token>/sendMessage，参数包括chat_id、text和parse_mode。下面给出两种常用语言的示例。

示例1：curl命令

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage" \
     -H "Content-Type: application/json" \
     -d '{"chat_id":"@username","text":"*加粗文字* 和 _斜体文字_","parse_mode":"Markdown"}'

示例2：Python requests库

import requests

url = f"https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage"
payload = {
    "chat_id": "@username",
    "text": "*加粗文字* 和 _斜体文字_",
    "parse_mode": "Markdown"
}
requests.post(url, json=payload)

将chat_id替换为实际聊天ID或频道用户名，运行后机器人就会发送带格式的消息。

传统Markdown与MarkdownV2的区别

支持的格式元素

传统Markdown支持以下常见格式：

• 加粗：*text*
• 斜体：_text_
• 内联代码：\`text\`
• 代码块：```text```
• 链接：[text](URL)

而MarkdownV2在此基础上增加了更多元素，例如删除线（~text~）、下划线（__text__）、引用（>text）、自定义实体等，同时还支持嵌套格式（如加粗+斜体）。

转义规则差异

这是开发者最容易踩坑的地方。Markdown仅需对_、*、\`、[等少数字符进行转义，而MarkdownV2要求对以下字符必须使用反斜杠\进行转义：

_ * [ ] ( ) ~ ` > # + - = | { } . !

注意，如果文本中出现了这些字符，但你没有正确转义，API将返回400错误：Bad Request: can't parse entities。

示例对比

假设要发送文字：注意：100美元 * 特价！

使用Markdown时，可以这样写：注意：100美元 \* 特价！（不需要转义*？实际上*是格式字符，需要转义，否则会错误解析）。为了避免歧义，更推荐使用MarkdownV2：注意：100美元 \* 特价！，或者将*转义为\*。

总之，MarkdownV2的转义规则更严谨，但处理不当时也更容易出错。

常见错误与解决方法

错误1：MarkdownV2未转义特殊字符

现象：消息无法发送，返回400 Bad Request。

原因：文本中包含了_、.、-等需要转义但未转义的字符。

解决：在发送前对特殊字符进行转义。例如在Python中，可以使用re.escape()，但要注意它默认转义所有特殊字符，你需要只转义MarkdownV2规定的集合。更稳妥的方式是手写一个替换函数，仅对_、*、[、]等做处理。

错误2：使用传统Markdown时实体未正确闭合

现象：消息能发送，但部分格式未生效或显示为乱码。

原因：例如加粗符号*数量不对称，或者嵌套格式冲突。

解决：仔细检查标记符号的配对，不要在有格式的文本内包含未转义的标记符号。

错误3：MarkdownV2中链接格式错误

现象：链接无法点击或报错。

原因：[text](url)中的括号和URL必须正确转义。

解决：确保URL中的.、:等不需要转义？实际上MarkdownV2规定URL中的.和-不需要转义，但]和)在URL中需要转义（比如路径中的括号）。最好将URL放在实体中。

实用技巧与最佳实践

• 优先使用MarkdownV2：虽然转义繁琐，但它支持更多格式且更稳定，强烈建议新项目直接采用。
• 封装转义函数：在代码中编写一个escape_markdown_v2(text)函数，在发送前统一处理，避免重复踩坑。
• 用HTML模式处理复杂格式：如果你的消息结构复杂（如代码块内包含特殊字符），HTML解析模式往往更简单，只需使用<b>、<i>等标签，无需转义字符（但要转义HTML本身）。
• 测试驱动开发：在将机器人部署到生产环境前，先创建一个测试群组或和机器人私聊，验证所有格式和转义是否正确。
• 使用实体参数代替字符串：Telegram Bot API支持通过entities参数直接指定文本格式，虽然操作复杂，但完全避开转义问题，适合追求极致稳定性的场景。

总结

掌握Telegram机器人发送Markdown格式消息的技巧，可以显著提升机器人的交互体验。本教程从基础概念讲起，对比了传统Markdown和MarkdownV2的差异，并给出了常见错误的排查方法。记住，MarkdownV2虽多了一道转义门槛，但只要封装好转义函数，使用起来一样顺畅。如果你对格式要求不高，也可以直接使用简洁的Markdown模式。希望这份指南能帮助你快速上手，打造更专业的Telegram机器人。