页面本来应该显示 <strong>新品</strong> 这段代码，却出现了 <strong>新品</strong>；或者接口里的 & 到页面上还是 &。这类问题先查内容在哪一步被转义，以及最后是按文本还是按 HTML 显示。
- 想在页面上展示代码原文，向
textContent传入原始文本即可，不需要先手动转义。 - 模板已经自动转义时，再提前转义一次，可能让读者看到
<等实体文本。 - 排查双重转义时，每次只解码一层，并与数据来源对照；不要一直解到看不见
&为止。 - 实体解码只是还原字符，不会把内容变成可信 HTML，也不能代替 HTML 清洗。
页面显示的是标签、实体，还是加粗文字
HTML 实体是一种字符写法，例如 < 表示小于号 <，& 表示 &。也可以用数字字符引用：< 和 < 都表示 <，分别使用十进制和十六进制。参见 MDN 字符引用说明。
下面的表格专指内容被放进普通 HTML 元素、由浏览器解析一次的场景，不适用于脚本、样式或文本框等其他位置。
| HTML 源码中的内容 | 页面显示 | 适合的目的 |
|---|---|---|
<strong>新品</strong> |
加粗的"新品" | 展示可信的 HTML 排版 |
<strong>新品</strong> |
字面文本 <strong>新品</strong> |
展示代码原文 |
&lt;strong&gt;新品&lt;/strong&gt; |
字面文本 <strong>新品</strong> |
展示实体写法本身 |
第三行未必是错误。HTML 教程可能正要展示实体写法。只有读者预期的结果与实际显示不同，才需要调整处理层数。
模板自动转义后，为什么又多了一层 amp
假设接口返回原始文本：
text
<strong>新品</strong>业务代码先把它转义一次，得到：
text
<strong>新品</strong>随后模板又把其中的 & 当作普通数据转义，最终写入 HTML 的内容变成：
text
&lt;strong&gt;新品&lt;/strong&gt;浏览器解析这一层 HTML 后，页面就会显示实体文本。修复前分别保存接口响应、传给模板的字符串和最终 HTML，定位第二次转义发生的位置。若目标是显示代码原文，通常应把原始文本交给模板的自动转义机制。
不要为了消除 & 就关闭整个模板的转义。原本只是代码展示问题，关闭后可能把用户输入当作 HTML 解析。若接口约定返回的就是实体文本，应先确认这层编码属于接口契约，再在明确的边界解码。
想显示代码原文，怎样避免手动转义
下面是完整的 HTML 示例。页面会显示 <strong>新品</strong> 这段文字，strong 不会成为加粗标签：
html
<!doctype html>
<html lang="zh-CN">
<meta charset="UTF-8">
<title>代码文本展示</title>
<pre id="code-output"></pre>
<script>
document.getElementById('code-output').textContent = '<strong>新品</strong>';
</script>
</html>textContent 把赋值内容作为文本处理。若传入的是 <strong>，它也会原样显示这串字符，不会替你解码实体。相关行为见 MDN textContent 文档。
这个固定示例用来说明显示方式；业务中读取接口数据后，再把字符串赋给 textContent。不要将任意用户输入直接拼进示例的 <script> 源码，JavaScript 字符串的处理规则与 HTML 文本不同。
在线解码后为什么还剩下 lt
在 HTML 实体编解码器 中选择"解码"，粘贴：
text
&lt;strong&gt;新品&lt;/strong&gt;一次解码的输出是：
text
<strong>新品</strong>工具只扫描原输入一遍，不会继续解析这次输出中新出现的 <。同样，&lt; 一次解码后是 <，不是 <。
若已确认来源多做了两层转义，可以把第一次结果重新粘贴到输入框，仍保持"解码"，再核对第二次结果。不要用"交换输入输出"来代替这一步：该按钮会同时切换编码与解码模式。
结果只显示在文本框里。即使解码得到 <strong>新品</strong>，工具也不会将它渲染成 HTML；复制到其他系统后如何处理，取决于那个系统的显示方式。
中文、空格和未知实体怎样处理
中文不必为了正常显示而全部变成实体。先切回"编码"模式，格式和范围选项才会显示。默认"仅 HTML 特殊字符"会保留中文；选择"特殊字符与全部非 ASCII"和"十六进制数字"时，中文😀 会得到：
text
中文😀这里的非 ASCII 指常用英文字符范围之外的字符。工具按完整 Unicode 字符处理 emoji，不会把它拆成两个数字引用。
解码后是"不换行空格"，字符编号为 U+00A0；它看起来像普通空格，但与普通空格 U+0020 不同。若表单比较或字符串匹配失败，先核对字符编号，再决定是否统一空格。不要顺手替换原本用于排版的不换行空格。
HTML 实体报错怎么排查
| 现象 | 原因或边界 | 修复方向 |
|---|---|---|
输入 &，提示"实体必须以分号结尾。" |
本工具要求完整的分号结尾引用 | 对照来源确认是否漏了 ; |
输入 &unknown;，提示"未知的 HTML 命名实体。" |
名称不在工具内置表中 | 查标准名称；合法但未收录的名称可改用对应数字引用 |
| 浏览器能显示，工具却拒绝解码 | 浏览器解析规则与工具的严格校验不同，工具也不覆盖全部命名实体 | 不要仅据此判定网页不合法，核对具体引用和所在位置 |
| 解码后看着相同，比较却失败 | 可能存在不换行空格等不同字符 | 比较字符编号，再按业务规则处理 |
| 实体不见了，标签却被当作 HTML 渲染 | 解码结果被放进了 HTML 解析入口 | 若目的只是显示文本，改用文本赋值 |
排错时先确认预期显示，再定位内容来源，逐层记录字符串变化，最后检查页面接收文本的方式。只有确认是哪一层多做或少做了处理，才修改对应代码。
核验依据
2026-09-08 核对 cc-tools 0.1.0 的 HTML 实体核心实现、页面输入输出及中文错误映射；本文的双重转义、单次解码、数字引用和空格示例已运行核对。项目内可运行现有测试：
bash
pnpm test src/tools/html-entity-converter/core.test.ts