HTML 格式化完全指南：美化、不闭合标签与实体
从接口返回的邮件模板、CMS 导出的整页源码，或「页面错位但不知哪个 div」时，把 HTML 按层级缩进摊开 往往比在压缩串里数括号更快。本指南说明美化与压缩的差异、void 标签与不闭合习惯、实体与属性换行，并对接 WebUtils 本地 HTML 工具。
核心一句话
先让嵌套可见，再谈改 class；压缩留给发布，美化留给排错。
HTML 允许一些「浏览器能忍、人眼不能忍」的写法：省略可选闭合、void 元素无结束标签、实体与真实字符混用。格式化工具用缩进把层级画出来，帮你发现少 </div> 或多包一层。它不是完整的 HTML 验证器，也不替代 DOM 标准解析在浏览器里的容错结果。可在 HTML 格式化 对照本指南操作。
1. 美化与压缩在 HTML 里意味着什么
| 动作 | 做什么 | 适合 | 风险点 |
|---|---|---|---|
| 美化 | 按标签层级缩进、可选属性换行 | 阅读、找未闭合、Code Review | 可能改变「仅依赖空白」的展示（见下） |
| 压缩 | 去注释与标签间多余空白 | 减小 HTML 体积、内联模板 | 误伤 pre/textarea 若实现不当；去注释丢说明 |
| 校验 | 对照 living standard / 模板 linter | 门禁 | 浏览器仍可能「修好」错误 HTML 让你误以为合法 |
空白敏感： 多数块级布局下，标签之间的换行不影响渲染；但在 <pre>、<textarea>、部分 display:inline 场景，文本节点里的空格是内容的一部分。本站美化逻辑会尽量把 pre/code/script/style/textarea 当作预格式区域减少折腾；压缩时也会先保护这些标签内部再去空白。
前后对照
挤在一行的片段：
<div class="card"><h2>标题</h2><p>正文 <strong>强调</strong></p><img src="/a.png" alt="示意"></div>
美化后（2 空格）：
<div class="card">
<h2>
标题
</h2>
<p>
正文
<strong>
强调
</strong>
</p>
<img src="/a.png" alt="示意">
</div>
层级一目了然：img 作为 void 元素不会凭空多出 </img>。若美化后某一深层级「只出不进」，往往就是上游少写了闭合标签。
2. 标签、实体与属性：排错时真正该懂的
Void 元素（不需要闭合标签）
常见 void（空元素）包括：area base br col embed hr img input link meta param source track wbr。
- 写成
<br>、<br/>或<br />在 HTML 序列化里都常见。 - 不要 写
</br>或给img加</img>当「更规范」——那是 XHTML 脑残记忆，现代 HTML 解析器不靠它。
本工具美化时会识别 void 列表，避免错误地增加缩进层级。
可选闭合与浏览器容错
例如 li、p、td 在特定上下文可省略结束标签。源码「能跑」不等于结构如你所想：浏览器会自动补节点，DevTools 里看到的 DOM 可能已不是源文件字节。排错时：
- 先格式化 源字符串（接口/文件里的）。
- 再与 Elements 面板对比是否被浏览器重写。
- 以 DOM 为准修 bug，以源文件为准修模板。
实体（Entity）
| 写法 | 含义 | 何时用 |
|---|---|---|
< > |
< > | 正文要显示尖括号 |
& |
& | 文本中的 &，以及容易歧义处 |
" ' |
" ' | 属性或正文 |
|
不换行空格 | 排版；勿滥用代替 margin |
数字实体 — |
Unicode 码位 | 拷贝特殊符号时 |
常见事故： 把用户输入原样拼进 HTML 未转义 → XSS；或双重转义 &lt; 显示成字面量。格式化 不会 自动做安全转义，只整理空白与标签换行。富文本入库前的转义是业务层责任。
属性换行与引号
工具提供「属性换行」：多属性时可把每个属性放到下一行并多一级缩进，便于 review class、data-*、长 srcset。属性值在美化过程中可能被规范成双引号形式——回写前确认与模板引擎引号规则不冲突（例如某些引擎外层已是双引号）。
script / style 内联
内联 JS/CSS 在美化时按预格式块处理更安全，避免把 </script> 字符串拆坏。深度格式化 JS/CSS 请分别用脚本工具与 CSS 格式化。
3. 用 WebUtils 操作逐步说明
工具页：HTML 格式化。
- 打开页面。 进入 /tools/dev/html-formatter。工具栏可见：缩进类型（空格/Tab）、缩进大小（默认 2）、「属性换行」「保留空行」。
- 粘贴 HTML。 左侧「输入 HTML 代码」；也可点「粘贴」从剪贴板读入（需浏览器权限）。
- 调选项。
- 与仓库一致：空格 + 2 或 4。
- 长属性：勾选「属性换行」。
- 需要保持段落感：保留「保留空行」（默认勾选）。
- 美化。 点「美化代码 (Beautify)」。成功 toast；右侧输出缩进结果。输入时可触发选项变更相关逻辑，最终以点击美化/压缩为准确认输出。
- 看缩进是否「一去不回」。 若某段持续比周围深一层，向上找未闭合标签。
- 压缩。 「一键压缩 (Minify)」去掉安全范围内的注释与标签间空白，并保护
pre/script/style/textarea内部；统计区显示输入/输出字符与压缩率。 - 复制。 「复制结果」带走输出。
- 清空。 清除输入输出与本地缓存的编辑状态（若页面启用了 state 持久化）。
能力边界
- 支持： 美化缩进、void 识别、属性换行、保留空行选项、压缩与字符统计、主题。
- 不宣称： 完整 HTML5 校验、自动修复所有残缺文档、与 Prettier 插件逐字节一致、执行或净化脚本（无 DOM XSS 防护套件）。
- 本地： 处理在浏览器完成；邮件里的用户隐私、未发布活动页源码仍要注意桌面共享。
需要「只压体积」的固定入口时，可用 HTML 压缩。从 Markdown 生成 HTML 则用 Markdown 转 HTML 或预览后再格式化。
4. 常见错误与处理办法
| 现象 | 常见原因 | 怎么处理 |
|---|---|---|
| 美化后层级越来越深 | 缺少闭合标签 | 从最深异常处向上补 </…> |
| 美化后某段突然回到 0 缩进 | 多写了闭合标签 | 删多余 </div> 等 |
压缩后 pre 代码乱了 |
保护逻辑未覆盖或手改破坏了标签 | 用工具压缩而非手删空格；检查标签名 |
| 页面多出巨大空白 | 内联元素间换行被 CSS 当成空格 | 调整结构或 CSS；美化时注意 inline 场景 |
& 导致后续属性消失 |
属性值未写 & 或未加引号 |
补引号与实体 |
| 中文乱码 | 源文件编码与声明不一致 | 统一 UTF-8；检查 <meta charset> |
| 组件框架的非标准标签 | MyWidget 等 |
工具按通用标签名处理；以框架文档为准 |
| 与浏览器 DOM 不一致 | 浏览器自动补全 | 以 DOM 为运行真相，源码按模板规范修 |
| 压缩率显示 0% | 已是压缩 HTML 或极短 | 正常；再优化需改结构与资源 |
| 勾选属性换行后模板炸了 | 服务端模板敏感空白 | 仅对静态片段使用；回写慎重 |
建议排查顺序
- 是源码问题还是 CSS 问题（可先隐藏 stylesheet 对比）。
- 格式化源码看标签是否闭合。
- 对比 DevTools DOM。
- 再查实体编码与脚本是否改 innerHTML。
5. 真实工作场景
场景 A：活动页「右侧栏掉到最下面」
产品截图显示布局崩了。拿到模板 HTML 美化，发现一个 section 少闭合，后面的 aside 被吃进主栏。补标签后不必先怀疑 Grid 写错。
场景 B：邮件 HTML 投递前检查
邮件 HTML 常由生成器压成一行。美化后检查是否误用 <script>、过大 base64 图、未转义的用户昵称。再压缩回投递版本。注意邮件 CSS 支持另论。
场景 C：CMS「可视化编辑」污染源码
多次保存产生无意义的 span 与 。美化后删除空 span，把 换成样式间距。提交前再压一次看体积。
场景 D：Markdown 转出的 HTML 要进站点壳
用 Markdown 转 HTML 或预览器复制 HTML 后，贴进本工具统一缩进，再嵌入布局组件。若源是 MD，长期仍应维护 MD，而不是只维护生成物。
场景 E：安全审计看「有没有把用户输入塞进属性」
美化后搜索 onclick=、未加引号的属性、javascript:。格式化提高审计速度，不替代专业扫描。
场景 F：与 CSS 一起做「class 对不上」
HTML 美化后列出 class 列表，CSS 侧用 CSS 格式化 后搜索。拼写 btn-primary vs btn_primary 是高频问题。
6. 协作与质量清单
- 仓库统一缩进（空格 2/4）与是否允许 Tab
- 模板中用户数据默认转义；富文本走白名单 sanitizer
- 图片必须有有意义的
alt（装饰图可空 alt，但要有意为之） - 压缩前确认
pre/内联脚本无依赖「被删掉的」外部空白 - 不要把美化后的巨型静态页不经 review 直接覆盖生成物
- 关键路径 HTML 保持精简；其余组件化
- 声明
<!DOCTYPE html>与lang、charset，减少怪异模式
常见问题
格式化能自动修好所有未闭合标签吗？
不能可靠地「猜」你的本意。它主要通过缩进暴露问题；自动补全是浏览器或 HTML 修复器的行为，可能补错位置。以你产品结构为准手动修。
为什么美化后视觉有细微差别？
inline 元素之间的换行可能变成空白节点。对比时用 DevTools 看文本节点；必要时把标签紧挨书写或用 Flex 消除空白影响。
XHTML 式的 `<br />` 还需要吗？
HTML 活标准下 void 元素写 <br> 即可。若工具输出带 /，一般浏览器仍接受。XML 内嵌场景另遵 XML 规则。
压缩会删除条件注释吗？
实现会去掉普通 <!-- -->，并尝试避开特定 IE 条件注释模式；老旧邮件/IE 需求请单独测试，不要假设百分之百保留。
可以把整站 index 都在线压了再上传吗？
可以当临时手段，但工程上应纳入构建（含测试）。在线工具适合片段与救急，不作唯一生产管线。
实体和 Unicode 字符哪个更好？
可见文本优先直接 UTF-8 字符；在 HTML 语法敏感处（如属性里的引号、文本中的 <）用实体或确保转义。两者混用时以「不破坏解析、可读」为准。
工具会执行我粘贴的 script 吗？
美化/压缩按文本处理输出到 textarea，不是把你的 HTML 当作当前页 DOM 执行。但「复制 HTML」到别的富文本或预览环境时仍要警惕 XSS——预览用户 HTML 必须消毒。
继续浏览
粘贴一小段含 img、div 嵌套的源码，开「属性换行」美化，再故意删掉一个 </div> 看缩进变化。需要 MD 工作流时转到 Markdown 工具。