编写整洁代码的 HTML 格式化最佳实践

你打开一个文件，映入眼帘的是一堵没有缩进的 HTML 代码墙，标签紧密地挤在一起，div 泛滥成灾，绵延数百行。想要找到一个缺失的闭合标签几乎是不可能的。我们都经历过这种痛苦，而良好的 HTML 格式化能彻底消除这类问题。

格式良好的 HTML 不仅仅是美观的问题。它直接影响你调试问题的速度、团队协作的流畅度，以及代码随时间推移的可维护性。无论你是在构建一个简单的着陆页还是一个复杂的 Web 应用程序，格式化习惯都会影响后续的一切工作。

为什么格式良好的 HTML 很重要

可读性

代码被阅读的次数远远超过被编写的次数。当你的 HTML 遵循一致的格式化规则时，团队中的任何人都能一眼扫过就理解其结构。嵌套元素变得清晰可辨，缺失的标签一目了然，整个文档的流程也变得明了。

可维护性

六个月后，你需要更新那个组件。干净的格式化意味着你可以直接进入、做出修改、继续前进——而不是花前二十分钟仅仅在理解结构上。

协作

当团队中的每个人都遵循相同的格式化规范时，代码审查就会变成关于逻辑和架构的高效对话，而不是关于空白字符的争论。格式化保持一致，合并冲突也会减少。

调试

缩进良好的 HTML 文档能即时展现其层级结构。当页面渲染出现问题时，你可以通过视觉追踪嵌套关系来定位问题。压缩过的或格式混乱的标记会隐藏这些结构关系。

缩进风格与规范

HTML 中的缩进争论在很大程度上反映了整个编程社区的讨论：空格还是制表符，以及每级缩进多少个空格。

2 个空格

两个空格的缩进是 HTML 中最流行的选择，Google 的代码风格指南、Prettier 的默认配置以及大多数现代前端框架都采用这种方式。

<main>
  <section>
    <h1>Welcome</h1>
    <p>This is a paragraph.</p>
  </section>
</main>

其优势在于代码紧凑的同时仍能清晰展示层级关系。在深度嵌套的 HTML 中——这种情况经常出现——两个空格可以防止代码行过度偏向右侧。

4 个空格

四个空格的缩进在嵌套层级之间提供了更大的视觉间距，使层级结构更加鲜明。

<main>
    <section>
        <h1>Welcome</h1>
        <p>This is a paragraph.</p>
    </section>
</main>

一些团队在嵌套较浅的 HTML 模板中倾向于使用这种方式。然而，在多层嵌套的复杂布局中，代码可能会不舒适地被推向屏幕右端。

制表符

制表符允许每位开发者在编辑器中配置自己偏好的视觉宽度。一个制表符可以在一位开发者那里显示为 2 个空格，在另一位那里显示为 4 个空格，而不会改变文件的实际内容。

选定一种并保持一致

具体选择哪种方式远没有一致性重要。配置好你的编辑器，设置 Prettier 等格式化工具，并通过 pre-commit 钩子来强制执行。关于缩进风格的讨论应该只发生一次——在你制定规则的时候——而不是在每次拉取请求时。

语义化 HTML5 元素

语义化元素向浏览器和辅助技术传达含义。它们用描述内容角色的专用标签替代了通用的 div 和 span。

文档结构元素

<body>
  <header>
    <nav>
      <a href="/">Home</a>
      <a href="https://example.com/about">About</a>
    </nav>
  </header>

  <main>
    <article>
      <h1>Article Title</h1>
      <p>Article content goes here.</p>

      <section>
        <h2>Subsection</h2>
        <p>More detailed content.</p>
      </section>
    </article>

    <aside>
      <h2>Related Links</h2>
      <ul>
        <li><a href="https://example.com/related">Related Article</a></li>
      </ul>
    </aside>
  </main>

  <footer>
    <p>&copy; 2026 Example Inc.</p>
  </footer>
</body>

何时使用各个元素

<header> — 引导性内容或导航链接。不仅可以在页面级使用，也可以出现在 <article> 或 <section> 内部。
<nav> — 主要导航区块。不要为每个链接组都使用它——仅用于主导航。
<main> — 页面的核心内容。每页只能有一个，且不能嵌套在 <article>、<aside>、<header>、<footer> 或 <nav> 内部。
<article> — 独立完整的内容，本身就有意义：博客文章、新闻报道、论坛帖子、产品卡片。
<section> — 具有主题性的内容分组，通常带有标题。当内容代表一个逻辑分区时，使用它代替 div。
<aside> — 与周围内容间接相关的内容：侧边栏、引用、相关链接。
<footer> — 其最近分区祖先的页脚信息。与 <header> 类似，它也可以出现在文章和章节内部。

`div` 与语义化元素的区别

div 没有任何语义含义。它只是一个用于样式和布局的通用容器。当你准备使用 div 时，问问自己：语义化元素是否能更好地描述这段内容？如果答案是肯定的，就使用语义化元素。

<!-- Avoid this -->
<div class="navigation">
  <div class="nav-links">
    <a href="/">Home</a>
  </div>
</div>

<!-- Prefer this -->
<nav>
  <a href="/">Home</a>
</nav>

无障碍模式

无障碍 HTML 不是一个独立的关注点——它就是编写良好的 HTML。大多数无障碍改进同时也会让你的标记更加简洁、更有意义。

标题层级结构

标题必须遵循逻辑顺序。不要为了样式目的而跳过层级——使用 CSS 来调整视觉大小。

<!-- Correct hierarchy -->
<h1>Page Title</h1>
  <h2>Major Section</h2>
    <h3>Subsection</h3>
    <h3>Another Subsection</h3>
  <h2>Another Major Section</h2>

<!-- Incorrect — skips h2 -->
<h1>Page Title</h1>
  <h3>This skips a level</h3>

图片替代文本

每个 <img> 元素都需要一个 alt 属性。描述性的替代文本能帮助屏幕阅读器用户理解内容。对于装饰性图片，使用空的 alt="" 来表示该图片不传达任何信息。

<!-- Informative image -->
<img src="chart.png" alt="Bar chart showing revenue growth from Q1 to Q4 2025">

<!-- Decorative image -->
<img src="decorative-border.png" alt="">

表单标签

每个表单输入控件都必须有一个关联的标签。标签上的 for 属性应与输入控件的 id 相匹配。

<label for="email">Email Address</label>
<input type="email" id="email" name="email" required>

避免使用占位符文本来代替标签。占位符在用户开始输入时就会消失，从而失去了该字段所期望内容的上下文信息。

ARIA 标签

当原生 HTML 语义不足以表达时，使用 ARIA 属性。然而，ARIA 的第一条规则是：如果你能使用已经具有所需语义的原生 HTML 元素，就优先使用它。

<!-- ARIA for custom components -->
<button aria-label="Close dialog" aria-expanded="false">
  <svg><!-- icon --></svg>
</button>

<!-- Better: use native semantics when possible -->
<button type="button">Close</button>

键盘导航

交互元素必须支持键盘访问。<button>、<a> 和 <input> 等原生 HTML 元素默认支持键盘访问。当你使用 div 或 span 作为交互元素时（通常应该避免这样做），需要添加 tabindex="0" 和键盘事件处理器。

属性排序规范

一致的属性排序使 HTML 更容易浏览。虽然没有严格的标准，但一种被广泛采用的规范是按重要性和功能排序属性：

<input
  type="email"
  id="user-email"
  name="email"
  class="form-input"
  placeholder="[email protected]"
  required
  aria-describedby="email-help"
  data-validate="email"
>

推荐顺序：

type — 元素或输入控件的类型
id — 唯一标识符
name — 表单提交名称
class — 样式挂钩
src、href、for — 资源引用
value、placeholder — 内容属性
required、disabled、checked — 布尔状态
aria-* — 无障碍属性
data-* — 自定义数据属性

这不是硬性规定，但在项目内保持一致性至关重要。配置你的代码检查工具来执行你所选择的顺序。

自闭合标签、空元素和布尔属性

空元素

某些 HTML 元素不能包含内容，也不需要闭合标签。这些被称为空元素（void elements）：

<br>
<hr>
<img src="photo.jpg" alt="A sunset over the ocean">
<input type="text" name="search">
<meta charset="utf-8">
<link rel="stylesheet" href="styles.css">

在 HTML5 中，你不需要用尾部斜杠来自闭合空元素（<br />）。斜杠是可选的，纯属风格偏好。但如果你的项目使用 JSX 或 XHTML，则必须使用自闭合语法。

布尔属性

布尔属性只有存在或不存在两种状态——不需要赋值。属性存在表示 true，不存在表示 false。

<!-- These are equivalent -->
<input type="text" required>
<input type="text" required="required">
<input type="text" required="">

<!-- Preferred: just the attribute name -->
<input type="text" required>
<button disabled>Submit</button>
<video autoplay muted></video>

常见的 HTML 格式化错误

1. 缩进不一致

混用制表符和空格，或每级空格数不统一，会造成视觉上的混乱。使用格式化工具来避免这个问题。

2. Div 泛滥

在语义化元素能更好地传达含义的地方，却把所有东西都包裹在 div 里。这会损害无障碍性、SEO 和代码可读性。

<!-- Div soup -->
<div class="header">
  <div class="nav">
    <div class="nav-item"><a href="/">Home</a></div>
  </div>
</div>

<!-- Clean semantic markup -->
<header>
  <nav>
    <a href="/">Home</a>
  </nav>
</header>

3. 缺少 Alt 属性

在图片上省略 alt 属性是一种无障碍性违规，会在所有 HTML 验证器中触发警告。

4. 内联样式

在 HTML 中到处使用 style 属性会混淆关注点，增加维护难度。应该使用 CSS 类来代替。

5. 过度深层嵌套

如果你的 HTML 嵌套到了六七层深，就该重新考虑你的布局了。深层嵌套通常意味着可以通过更好的组件架构来简化结构。

6. 缺少文档语言声明

始终在 <html> 元素上包含 lang 属性。屏幕阅读器会根据它来选择正确的发音规则。

<html lang="en">

7. 未使用 `<!DOCTYPE html>` 声明

始终以文档类型声明开始你的 HTML 文档。没有它，浏览器可能会以怪异模式（quirks mode）渲染页面，导致行为不一致。

自动化美化和代码检查工具

手动格式化容易出错且枯燥。自动化工具无需持续投入即可确保一致性。

Prettier

Prettier 是 Web 开发中最流行的代码格式化工具。它支持 HTML、CSS、JavaScript 等众多语言。只需配置一次，它就会自动处理缩进、属性换行和行宽。

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "htmlWhitespaceSensitivity": "css"
}

将 Prettier 作为 pre-commit 钩子运行或在编辑器中保存时运行，格式化就会完全自动化。

HTMLHint

HTMLHint 是一款专门针对 HTML 的静态分析工具。它能捕获格式化工具无法发现的问题——如缺失的 alt 属性、重复的 ID 以及已废弃的元素。

{
  "tagname-lowercase": true,
  "attr-lowercase": true,
  "attr-value-double-quotes": true,
  "tag-pair": true,
  "id-unique": true,
  "alt-require": true
}

编辑器集成

大多数现代编辑器——VS Code、WebStorm、Sublime Text——都具有内置或基于插件的 HTML 格式化功能。启用保存时自动格式化，无需刻意操心即可保持 HTML 整洁。

生产环境压缩

开发环境的 HTML 应该保持优美的格式化，而生产环境的 HTML 则可以通过压缩来减小文件体积。我们的 Code Minifier 可以去除空白、移除注释并压缩 HTML 以便部署。关键是保持源代码的格式化，只对输出进行压缩。

工具和资源

有了合适的工具，良好的格式化习惯更容易保持：

Code Minifier — 在保持源代码整洁的同时，压缩 HTML、CSS 和 JavaScript 用于生产环境
Markdown Previewer — 预览和格式化经常生成 HTML 输出的 Markdown 内容

常见问题解答

HTML 缩进应该用 2 个空格还是 4 个空格？

两个空格是现代 Web 开发中最常见的规范，也是 Prettier 的默认设置。四个空格适用于嵌套较浅的简单文档。最重要的是选定一种并通过格式化工具来执行。

语义化 HTML 和普通 HTML 有什么区别？

语义化 HTML 使用描述内容含义的元素（<article>、<nav>、<header>），而不是通用容器（<div>、<span>）。语义化标记能提升无障碍性、SEO 和代码可读性。

如果使用了语义化 HTML，还需要 ARIA 属性吗？

在大多数情况下，语义化 HTML 提供了足够的无障碍信息。当你构建没有原生 HTML 对应元素的自定义交互组件时——如自定义下拉菜单或标签面板——才需要使用 ARIA。

如何在团队中统一 HTML 格式化？

使用带有共享配置文件的 Prettier，添加 HTMLHint 配置用于代码检查，并使用 Husky 和 lint-staged 等工具将两者作为 pre-commit 钩子运行。

空元素可以用 `<br />` 这样的自闭合写法吗？

在 HTML5 中，空元素的尾部斜杠是可选的。<br> 和 <br /> 都是有效的。在 JSX（React）中，自闭合语法是必需的。请遵循你的项目或框架所期望的规范。

编写整洁代码的 HTML 格式化最佳实践

为什么格式良好的 HTML 很重要

可读性

可维护性

六个月后，你需要更新那个组件。干净的格式化意味着你可以直接进入、做出修改、继续前进——而不是花前二十分钟仅仅在理解结构上。

协作

调试

缩进风格与规范

HTML 中的缩进争论在很大程度上反映了整个编程社区的讨论：空格还是制表符，以及每级缩进多少个空格。

2 个空格

两个空格的缩进是 HTML 中最流行的选择，Google 的代码风格指南、Prettier 的默认配置以及大多数现代前端框架都采用这种方式。

<main>
  <section>
    <h1>Welcome</h1>
    <p>This is a paragraph.</p>
  </section>
</main>

其优势在于代码紧凑的同时仍能清晰展示层级关系。在深度嵌套的 HTML 中——这种情况经常出现——两个空格可以防止代码行过度偏向右侧。

4 个空格

四个空格的缩进在嵌套层级之间提供了更大的视觉间距，使层级结构更加鲜明。

<main>
    <section>
        <h1>Welcome</h1>
        <p>This is a paragraph.</p>
    </section>
</main>

一些团队在嵌套较浅的 HTML 模板中倾向于使用这种方式。然而，在多层嵌套的复杂布局中，代码可能会不舒适地被推向屏幕右端。

制表符

选定一种并保持一致

语义化 HTML5 元素

语义化元素向浏览器和辅助技术传达含义。它们用描述内容角色的专用标签替代了通用的 div 和 span。

文档结构元素

<body>
  <header>
    <nav>
      <a href="/">Home</a>
      <a href="https://example.com/about">About</a>
    </nav>
  </header>

  <main>
    <article>
      <h1>Article Title</h1>
      <p>Article content goes here.</p>

      <section>
        <h2>Subsection</h2>
        <p>More detailed content.</p>
      </section>
    </article>

    <aside>
      <h2>Related Links</h2>
      <ul>
        <li><a href="https://example.com/related">Related Article</a></li>
      </ul>
    </aside>
  </main>

  <footer>
    <p>&copy; 2026 Example Inc.</p>
  </footer>
</body>

何时使用各个元素

<header> — 引导性内容或导航链接。不仅可以在页面级使用，也可以出现在 <article> 或 <section> 内部。
<nav> — 主要导航区块。不要为每个链接组都使用它——仅用于主导航。
<main> — 页面的核心内容。每页只能有一个，且不能嵌套在 <article>、<aside>、<header>、<footer> 或 <nav> 内部。
<article> — 独立完整的内容，本身就有意义：博客文章、新闻报道、论坛帖子、产品卡片。
<section> — 具有主题性的内容分组，通常带有标题。当内容代表一个逻辑分区时，使用它代替 div。
<aside> — 与周围内容间接相关的内容：侧边栏、引用、相关链接。
<footer> — 其最近分区祖先的页脚信息。与 <header> 类似，它也可以出现在文章和章节内部。

`div` 与语义化元素的区别

<!-- Avoid this -->
<div class="navigation">
  <div class="nav-links">
    <a href="/">Home</a>
  </div>
</div>

<!-- Prefer this -->
<nav>
  <a href="/">Home</a>
</nav>

无障碍模式

无障碍 HTML 不是一个独立的关注点——它就是编写良好的 HTML。大多数无障碍改进同时也会让你的标记更加简洁、更有意义。

标题层级结构

标题必须遵循逻辑顺序。不要为了样式目的而跳过层级——使用 CSS 来调整视觉大小。

<!-- Correct hierarchy -->
<h1>Page Title</h1>
  <h2>Major Section</h2>
    <h3>Subsection</h3>
    <h3>Another Subsection</h3>
  <h2>Another Major Section</h2>

<!-- Incorrect — skips h2 -->
<h1>Page Title</h1>
  <h3>This skips a level</h3>

图片替代文本

<!-- Informative image -->
<img src="chart.png" alt="Bar chart showing revenue growth from Q1 to Q4 2025">

<!-- Decorative image -->
<img src="decorative-border.png" alt="">

表单标签

每个表单输入控件都必须有一个关联的标签。标签上的 for 属性应与输入控件的 id 相匹配。

<label for="email">Email Address</label>
<input type="email" id="email" name="email" required>

避免使用占位符文本来代替标签。占位符在用户开始输入时就会消失，从而失去了该字段所期望内容的上下文信息。

ARIA 标签

当原生 HTML 语义不足以表达时，使用 ARIA 属性。然而，ARIA 的第一条规则是：如果你能使用已经具有所需语义的原生 HTML 元素，就优先使用它。

<!-- ARIA for custom components -->
<button aria-label="Close dialog" aria-expanded="false">
  <svg><!-- icon --></svg>
</button>

<!-- Better: use native semantics when possible -->
<button type="button">Close</button>

键盘导航

属性排序规范

一致的属性排序使 HTML 更容易浏览。虽然没有严格的标准，但一种被广泛采用的规范是按重要性和功能排序属性：

<input
  type="email"
  id="user-email"
  name="email"
  class="form-input"
  placeholder="[email protected]"
  required
  aria-describedby="email-help"
  data-validate="email"
>

推荐顺序：

type — 元素或输入控件的类型
id — 唯一标识符
name — 表单提交名称
class — 样式挂钩
src、href、for — 资源引用
value、placeholder — 内容属性
required、disabled、checked — 布尔状态
aria-* — 无障碍属性
data-* — 自定义数据属性

这不是硬性规定，但在项目内保持一致性至关重要。配置你的代码检查工具来执行你所选择的顺序。

自闭合标签、空元素和布尔属性

空元素

某些 HTML 元素不能包含内容，也不需要闭合标签。这些被称为空元素（void elements）：

<br>
<hr>
<img src="photo.jpg" alt="A sunset over the ocean">
<input type="text" name="search">
<meta charset="utf-8">
<link rel="stylesheet" href="styles.css">

布尔属性

布尔属性只有存在或不存在两种状态——不需要赋值。属性存在表示 true，不存在表示 false。

<!-- These are equivalent -->
<input type="text" required>
<input type="text" required="required">
<input type="text" required="">

<!-- Preferred: just the attribute name -->
<input type="text" required>
<button disabled>Submit</button>
<video autoplay muted></video>

常见的 HTML 格式化错误

1. 缩进不一致

混用制表符和空格，或每级空格数不统一，会造成视觉上的混乱。使用格式化工具来避免这个问题。

2. Div 泛滥

在语义化元素能更好地传达含义的地方，却把所有东西都包裹在 div 里。这会损害无障碍性、SEO 和代码可读性。

<!-- Div soup -->
<div class="header">
  <div class="nav">
    <div class="nav-item"><a href="/">Home</a></div>
  </div>
</div>

<!-- Clean semantic markup -->
<header>
  <nav>
    <a href="/">Home</a>
  </nav>
</header>

3. 缺少 Alt 属性

在图片上省略 alt 属性是一种无障碍性违规，会在所有 HTML 验证器中触发警告。

4. 内联样式

在 HTML 中到处使用 style 属性会混淆关注点，增加维护难度。应该使用 CSS 类来代替。

5. 过度深层嵌套

如果你的 HTML 嵌套到了六七层深，就该重新考虑你的布局了。深层嵌套通常意味着可以通过更好的组件架构来简化结构。

6. 缺少文档语言声明

始终在 <html> 元素上包含 lang 属性。屏幕阅读器会根据它来选择正确的发音规则。

<html lang="en">

7. 未使用 `<!DOCTYPE html>` 声明

始终以文档类型声明开始你的 HTML 文档。没有它，浏览器可能会以怪异模式（quirks mode）渲染页面，导致行为不一致。

自动化美化和代码检查工具

手动格式化容易出错且枯燥。自动化工具无需持续投入即可确保一致性。

Prettier

Prettier 是 Web 开发中最流行的代码格式化工具。它支持 HTML、CSS、JavaScript 等众多语言。只需配置一次，它就会自动处理缩进、属性换行和行宽。

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "htmlWhitespaceSensitivity": "css"
}

将 Prettier 作为 pre-commit 钩子运行或在编辑器中保存时运行，格式化就会完全自动化。

HTMLHint

HTMLHint 是一款专门针对 HTML 的静态分析工具。它能捕获格式化工具无法发现的问题——如缺失的 alt 属性、重复的 ID 以及已废弃的元素。

{
  "tagname-lowercase": true,
  "attr-lowercase": true,
  "attr-value-double-quotes": true,
  "tag-pair": true,
  "id-unique": true,
  "alt-require": true
}

编辑器集成

生产环境压缩

工具和资源

有了合适的工具，良好的格式化习惯更容易保持：

Code Minifier — 在保持源代码整洁的同时，压缩 HTML、CSS 和 JavaScript 用于生产环境
Markdown Previewer — 预览和格式化经常生成 HTML 输出的 Markdown 内容

常见问题解答

HTML 缩进应该用 2 个空格还是 4 个空格？

语义化 HTML 和普通 HTML 有什么区别？

如果使用了语义化 HTML，还需要 ARIA 属性吗？

如何在团队中统一 HTML 格式化？

使用带有共享配置文件的 Prettier，添加 HTMLHint 配置用于代码检查，并使用 Husky 和 lint-staged 等工具将两者作为 pre-commit 钩子运行。

空元素可以用 `<br />` 这样的自闭合写法吗？

在 HTML5 中，空元素的尾部斜杠是可选的。<br> 和 <br /> 都是有效的。在 JSX（React）中，自闭合语法是必需的。请遵循你的项目或框架所期望的规范。

编写整洁代码的 HTML 格式化最佳实践

为什么格式良好的 HTML 很重要

可读性

可维护性

协作

调试

缩进风格与规范

2 个空格

4 个空格

制表符

选定一种并保持一致

语义化 HTML5 元素

文档结构元素

何时使用各个元素

div 与语义化元素的区别

无障碍模式

标题层级结构

图片替代文本

表单标签

ARIA 标签

键盘导航

属性排序规范

自闭合标签、空元素和布尔属性

空元素

布尔属性

常见的 HTML 格式化错误

1. 缩进不一致

2. Div 泛滥

3. 缺少 Alt 属性

4. 内联样式

5. 过度深层嵌套

6. 缺少文档语言声明

7. 未使用 <!DOCTYPE html> 声明

自动化美化和代码检查工具

Prettier

HTMLHint

编辑器集成

生产环境压缩

工具和资源

常见问题解答

HTML 缩进应该用 2 个空格还是 4 个空格？

语义化 HTML 和普通 HTML 有什么区别？

如果使用了语义化 HTML，还需要 ARIA 属性吗？

如何在团队中统一 HTML 格式化？

空元素可以用 <br /> 这样的自闭合写法吗？

相关资源

编写整洁代码的 HTML 格式化最佳实践

为什么格式良好的 HTML 很重要

可读性

可维护性

协作

调试

缩进风格与规范

2 个空格

4 个空格

制表符

选定一种并保持一致

语义化 HTML5 元素

文档结构元素

何时使用各个元素

div 与语义化元素的区别

无障碍模式

标题层级结构

图片替代文本

表单标签

ARIA 标签

键盘导航

属性排序规范

自闭合标签、空元素和布尔属性

空元素

布尔属性

常见的 HTML 格式化错误

1. 缩进不一致

2. Div 泛滥

3. 缺少 Alt 属性

4. 内联样式

5. 过度深层嵌套

6. 缺少文档语言声明

7. 未使用 <!DOCTYPE html> 声明

自动化美化和代码检查工具

`div` 与语义化元素的区别

7. 未使用 `<!DOCTYPE html>` 声明

空元素可以用 `<br />` 这样的自闭合写法吗？

`div` 与语义化元素的区别

7. 未使用 `<!DOCTYPE html>` 声明

空元素可以用 `<br />` 这样的自闭合写法吗？