天天搜TTSO机器人新手指南 Markdown与HTML富文本教程消息在解析时的转义与清洗

天天搜TTSO机器人新手指南 🧭 一、为什么富文本消息容易解析失败

在 Telegram Bot、客服系统、内容发布平台中，消息通常会经历用户输入、服务端拼接、转义处理、HTML 或 Markdown 解析、接口发送多个阶段。任何一个环节重复转义、遗漏清洗，都会造成格式错乱、接口报错，甚至引入恶意链接。

需要先明确一个核心概念：转义是保护字符不被当作语法解析，而清洗是删除或改写不允许出现的标签、属性和链接。两者目的不同，不能简单地用“删除所有特殊字符”代替。

例如，用户输入的内容是“价格 < 100 元”，如果直接放进 HTML 消息，符号可能被解析成标签的一部分；如果转义为“价格 &lt; 100 元”，解析器就会把它当成普通文本显示。

🔍 二、先区分 Telegram 的两种解析模式

1. MarkdownV2 不是普通 Markdown

Telegram 的 MarkdownV2 只支持有限的格式语法，并且对特殊字符非常敏感。下划线、星号、方括号、圆括号、反引号、波浪线、井号、加号、减号、等号、竖线、大括号、句号和感叹号等字符，在特定场景下都可能需要使用反斜杠转义。

因此，不要把用户原文直接拼接进 MarkdownV2 模板。正确做法是只转义动态数据，保留由程序员控制的格式标记，否则原本的加粗、链接和代码结构也会被一起破坏。

2. HTML 模式也不是完整浏览器 HTML

Telegram 的 HTML 解析器只允许一组有限标签，例如加粗、斜体、删除线、链接、代码和预格式化文本等。它不是浏览器 DOM，不会安全地支持任意的样式、脚本、事件属性或复杂布局。

常见的安全标签包括 <b>、<strong>、<i>、<em>、<u>、<s>、<del>、<a href="...">、<code> 和 <pre>。具体支持范围应以当前 Bot API 文档为准，不能假设网页中能显示的标签在 Telegram 中也能生效。

🧱 三、HTML 富文本的正确转义顺序

HTML 转义的重点是先处理和符号，再处理尖括号。如果先把 < 转换成 &lt;，后续又把其中的 & 转换一次，就会产生双重转义，最终用户看到的可能是“&lt;”而不是“<”。

普通文本至少应处理 &、<、> 和引号。动态内容放入链接属性时，还要额外验证 URL 协议，避免把 javascript 或其他未知协议写入 href。

function escapeHtml(value) {
  return String(value)
    .replace(/&/g, '&')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;');
}

const safeName = escapeHtml(userName);
const message = '&lt;b&gt;你好，' + safeName + '&lt;/b&gt;';

上面的示例中，代码块里的实体是为了在网页文章中安全展示，实际程序运行时应使用真正的字符。更重要的是，转义函数只能作用于普通文本，不要把已经由服务端生成的可信标签再次转义。

避免“双重转义”的实用原则

建议在系统内部明确数据状态，例如区分“原始文本”“已清洗富文本”和“已发送内容”。一个字段只允许经过一次明确的转义流程，并通过测试验证同一内容重复处理后不会不断增加实体层级。

如果消息来自数据库或第三方接口，不要因为它“看起来已经是 HTML”就直接信任。应先判断来源和可信等级，再决定是全部当作纯文本转义，还是经过白名单清洗后保留部分标签。

🧼 四、富文本清洗：白名单比黑名单更可靠

清洗的目标不是让文本“看起来正常”，而是建立一个明确的允许列表。例如只允许加粗、斜体、链接和代码标签，只允许 href 属性，并且链接协议仅接受 https、http 或业务确实需要的 tg。

不要只用正则表达式删除 <script>。正则很难正确处理嵌套标签、大小写变体、异常属性和编码绕过，容易留下危险结构，也可能误删正常内容。

在网页端项目中，可以选择成熟的 HTML Sanitizer 或经过审计的 DOMPurify，并自行配置标签和属性白名单；在服务端，则应再次执行清洗，不能把浏览器端校验当成最终防线。

允许标签：b、strong、i、em、u、s、a、code、pre
允许属性：a[href]
允许协议：https、http、tg
拒绝属性：style、class、id、onclick、onerror
拒绝结构：script、iframe、object、form

清洗后仍要检查标签是否闭合、嵌套是否符合 Telegram 解析规则，以及消息长度是否超过接口限制。解析器报错时，优先记录原始输入、清洗结果和发送模式，才能准确定位问题。

🛠️ 五、MarkdownV2 消息的转义策略

MarkdownV2 最容易出现的问题，是业务文案中包含句号、括号或下划线，发送时却被解析器当成格式语法。建议建立独立的 MarkdownV2 转义函数，并明确区分普通文本、链接地址、代码内容和自定义格式模板。

普通动态文本需要转义保留字符；链接文字和链接地址不能完全用同一套规则处理；代码块内部又有独立的反引号规则。不要使用一个全局 replace 函数解决所有区域，这是导致线上格式错乱的常见原因。

function escapeMarkdownV2(value) {
  return String(value).replace(/([_*\[\]()~`>#+\-=|{}.!\\])/g, '\\$1');
}

const title = escapeMarkdownV2(userTitle);
const text = '*标题：' + title + '*';

如果只是发送用户评论、搜索关键词或日志内容，最稳妥的做法通常是关闭 parse_mode，按纯文本发送。只有在确实需要加粗、链接或代码展示时，才使用 MarkdownV2 或 HTML。

天天搜TTSO机器人新手指南 优先考虑 Message Entities

对于复杂编辑器或高可靠性系统，可以考虑使用 Telegram 的消息实体结构表达加粗、链接和代码范围，而不是依赖一整段字符串解析。实体方式需要正确计算偏移量，尤其要注意 Telegram 文档中的 UTF-16 偏移规则。

中文、表情符号和部分合成字符可能与 JavaScript 的字符串长度概念不同，因此不能只凭 length 结果计算实体位置。涉及多语言内容时，应使用经过验证的 UTF-16 计数方法，并覆盖表情、换行和组合字符测试。

🧪 六、上线前必须进行的测试

测试用例不能只包含“你好”和普通英文。至少应覆盖尖括号、和号、引号、反斜杠、连续星号、嵌套标签、空链接、超长文本、中文表情以及恶意属性等情况。

天天搜TTSO机器人新手指南 每种 parse_mode 都要单独测试，因为同一字符串在 HTML、MarkdownV2 和纯文本模式下的含义完全不同。还要验证失败后的降级策略，例如解析失败时改发纯文本，而不是反复重试同一条错误消息。

测试输入：
价格 < 100 元 & 限时优惠
<a href="javascript:alert(1)">危险链接</a>
表情：😀🚀
Markdown：订单号_2025.06.18

验收标准：
1. 普通符号原样显示
2. 危险标签和协议被移除
3. 合法格式保持可读
4. 解析失败可以安全降级
5. 日志中不记录用户敏感信息

生产环境还应记录 Telegram 返回的错误类型，例如实体未闭合、未知标签、实体偏移错误或消息过长。日志需要脱敏，避免把手机号、Token、私聊内容和授权链接完整写入公共监控系统。

天天搜TTSO机器人新手指南 ❓ 常见问题解答（FAQ）

HTML 消息为什么会出现“can't parse entities”？

通常是标签没有闭合、嵌套顺序错误、属性引号不完整，或者使用了 Telegram 不支持的 HTML 标签。也可能是动态文本中的 <、> 或 & 没有转义，建议先输出最终发送字符串进行检查。

用户输入包含 HTML 标签时，应该保留还是删除？

如果用户只是提交评论、标题或搜索词，应全部视为普通文本并进行 HTML 转义。如果产品明确支持富文本，则必须先执行白名单清洗，再把允许的结构交给 Telegram 解析。

为什么转义一次后还会显示 &lt;？

天天搜TTSO机器人新手指南 这说明内容很可能被重复转义，第一次产生的 &lt; 中的和号又被转成了 &amp;。应在数据流中标注处理状态，并保证模板渲染层不要再次处理已经编码的内容。

HTML 和 MarkdownV2 应该选哪一个？

如果内容主要由服务端模板生成，HTML 通常更直观；如果团队已有 Markdown 编辑流程，MarkdownV2 也可以使用，但必须严格实现特殊字符转义。对不可控用户内容，纯文本模式的安全性和稳定性最高。

解析失败时最好的降级方案是什么？

先记录结构化错误和消息版本，再将经过 HTML 转义的原文按纯文本发送，并提示用户格式暂时无法解析。不要直接关闭所有安全校验，也不要为了“能发出去”而放行未知标签和不可信链接。

总结来看，稳定的 Telegram 富文本链路应遵循输入分级、白名单清洗、按模式转义、最终结果测试、失败安全降级五个原则。把转义和清洗设计成独立、可测试、可追踪的模块，才能同时获得良好的阅读效果、接口稳定性与安全保障。