Telegram使用MarkdownV2发送指定URL超链接失败问题求助

一、MarkdownV2 超链接的官方转义规则 #

• 超链接的标准格式为[链接文本](目标URL)，两部分的转义规则完全独立，不可混用
• 方括号内的链接文本：遵循普通MarkdownV2文本转义规则，所有特殊字符_*[]()~>#+-=|.!{}都需要加反斜杠`转义
• 小括号内的URL：不能使用反斜杠转义，需同时满足两个要求：
  • 符合RFC 3986 URL编码规范，非ASCII字符、URL非法字符需做百分编码
  • 不能包含未编码的)字符，否则Telegram会将其识别为超链接的结束标记，导致格式解析失败

二、现有代码的问题 #

• 手动替换指定字符的方式覆盖场景不全，遇到URL含空格、中文、)、$、;等特殊字符时仍会触发解析错误
• 没有区分普通文本和超链接内容的转义逻辑，容易出现误转义或者漏转义的情况

三、优化方案 #

3.1 拆分转义逻辑，单独处理超链接 #

先构造所有格式化元素（超链接、加粗、代码块等），再拼接转义后的普通文本，避免整段统一转义破坏格式化结构。

3.2 使用标准库做URL编码，避免手动遗漏 #

用Python内置的urllib.parse.quote做标准化URL编码，通过safe参数指定不需要编码的URL合法保留字符，其余字符自动转码。

3.3 参考实现代码 #

import re
from urllib.parse import quote

# 普通MarkdownV2文本转义函数
def escape_md2_text(text: str) -> str:
    return re.sub(r"([_*\[\]()~`>#+\-=|.!{}])", r"\\\1", text)

# MarkdownV2超链接URL编码函数
def encode_md2_url(url: str) -> str:
    # safe参数列出URL合法保留字符，无需编码
    return quote(url, safe=":/?=&%#@+!$'()*,;")

# 超链接构造示例
link_text = "路透社相关报道"
raw_url = "https://www.reuters.com/你的原始链接&包含特殊字符"
md_link = f"[{escape_md2_text(link_text)}]({encode_md2_url(raw_url)})"

# 拼接消息正文
final_message = f"今日资讯：{md_link}\n{escape_md2_text('其他普通正文内容')}"

四、额外注意事项 #

• URL中如果存在)字符，不要放在safe参数里，会自动编码为%29，避免被识别为超链接结束符
• 不要对URL中的字符添加反斜杠转义，Telegram会将反斜杠识别为URL的一部分，导致链接无法正常访问
• 如果需要发送纯文本链接（不做超链接包装），按普通文本规则转义即可，不需要做URL编码

内容的提问来源于stack exchange，提问作者SSC Fan