前端 H1 标签最佳实践:用 Front-End-Checklist 规则打造单一描述性 H1

原创2026-09-18 15:41:373,775 阅读

前端 H1 标签最佳实践:用 Front-End-Checklist 规则打造单一描述性 H1

导读

本文以 Front-End-Checklist 开源仓库中的 h1 规则为核心,系统讲解页面主标题 <h1> 的正确用法:每页恰好一个、包含目标关键词、与 <title> 主题一致。你将掌握完整的问题检查清单、修复步骤、React/Next.js 场景下的落地方法,以及仓库源码中自动化校验 H1 的底层实现逻辑,可直接用于站点审计与代码评审。

规则背景:什么是"单一描述性 H1"

<h1> 是页面中最醒目的标题元素,也是强烈的站内排名信号。Google 依靠 H1 理解页面的核心主题。缺少 H1、出现多个 H1、或 H1 不含关键词,都会削弱页面主题清晰度,进而损害目标关键词的排名表现。

在 Front-End-Checklist 仓库中,该规则被定义为 h1(slug),归类于 SEO 规则下的 meta-tags 子类,优先级为 medium(中等),难度为 intermediate,预计耗时 10 分钟。完整规则内容位于 packages/content/rules/en/seo/h1.mdx,并以 Agent 可用技能的形式封装在 skills/h1/SKILL.md 及 skills/h1/references/rule.md 中。

核心规则(TL;DR)

  • 每个页面应恰好有一个 <h1> 标签,用相关关键词描述页面的主要主题
  • H1 不必与 <title> 标签完全一致,但二者应在主题上保持一致
  • 空的 <h1>、一个页面出现多个 <h1>、或 H1 只包含品牌名,都属于需要修复的问题

为什么 H1 如此重要

站内 SEO(On-page SEO)

搜索引擎使用标题(heading)来理解页面结构和主题相关性,其中 H1 的权重最高。需要说明的是,H1 单独来看并非最强的排名因素,但它贡献了页面主题相关性信号:一个页面存在多个 H1 会稀释主主题信号;缺少 H1 则留下结构空缺,降低搜索引擎对"页面在讲什么"的置信度。

可访问性(Accessibility)

屏幕阅读器会把 H1 播报为页面的主标题,让使用辅助技术的用户能立即理解页面上下文。

用户体验(User Experience)

清晰的 H1 锚定页面内容,帮助读者确认自己找到了搜索想要的东西,也能避免多个页面复用相同标题时产生的歧义。

如何检查:五类需要标记的问题

根据 skills/h1/SKILL.md 的 Check 段落,检查方式是解析每个页面渲染后的 DOM,统计所有 <h1> 元素,并标记以下五类问题:

问题 具体表现
没有 <h1> Google 没有任何清晰的标题信号可用
多个 <h1> 稀释页面的主主题信号
空 <h1> 只有结构、没有内容
仅含品牌名的 H1 未体现具体主题,错失排名机会
H1 与页面主内容主题不符 标题与内容脱节,主题信号混乱
H1 被 CSS 隐藏 Google 可能直接忽略该元素

其中"被 CSS 隐藏"指的是通过 display:none 或 visibility:hidden 隐藏的 H1,这类元素虽然存在于 DOM 中,但搜索引擎可能不予采信。

如何修复:六步操作指南

按照 skills/h1/SKILL.md 的 Fix 段落,依次执行:

  1. 确保每个页面模板只输出一个 <h1>——从模板层面杜绝多 H1 或零 H1 的可能
  2. H1 文本应描述页面的具体主题,而不是只写站点名
  3. 将主要目标关键词自然融入 H1——不要生硬堆砌
  4. 若页面有多个 H1 候选段落,选定一个主主题,其余降级为 H2
  5. 确认 H1 在渲染后的 DOM 中可见(未被 CSS display:none 或 visibility:hidden 隐藏)
  6. 在 Next.js/React 中:H1 必须放在页面组件里,而不是共享布局(layout)中

正反示例对照

❌ 错误——页面没有 H1:

<main>
  <h2>Welcome to Acme Corp</h2>
  <!-- No H1 — Google has no primary heading to use -->
  <p>We build enterprise software...</p>
</main>

❌ 错误——页面出现多个 H1(且第一个只含品牌名):

<main>
  <h1>Acme Corp</h1>  <!-- Brand name only -->
  <article>
    <h1>Project Management Software for Teams</h1>  <!-- Second H1! -->
  </article>
</main>

❌ 错误——H1 只含品牌名:

<h1>Acme Corp</h1>
<!-- Does not tell Google or users what this specific page is about -->

✅ 正确——单一描述性 H1,子主题使用 H2 及以下:

<main>
  <h1>Project Management Software for Enterprise Teams</h1>
  <p>Acme Corp helps teams of 50+ manage projects with Kanban,
     time tracking, and automated reporting.</p>

  <h2>Key Features</h2>
  <!-- H2 and below for sub-topics -->
</main>

✅ 正确——H1 与 title 主题一致但不必相同:

<head>
  <!-- Title includes brand; H1 is content-focused -->
  <title>Project Management Software — Acme Corp</title>
</head>
<body>
  <h1>Project Management Software for Enterprise Teams</h1>
</body>

注意:上述对比正是原文档中的完整示例(Before:<h1>Acme Corp</h1>,After:<h1>Project Management Software for Enterprise Teams</h1>),实践中可直接作为模板参考。

仓库源码级的 H1 自动化检查

Front-End-Checklist 不仅给出规则文档,还在 packages/mcp/src/tools/review-code.ts 中实现了真实的 H1 校验逻辑,可用于代码评审自动化。从源码结构看,其核心检查思路如下:

const h1Count = (lowerCode.match(/<h1/g) || []).length

if (h1Count > 1) {
  return { hasIssue: true, issue: 'Multiple <h1> elements found (should have only one per page)' }
}
// h1-require: a full page (has <body>) must have exactly one <h1>
if (lowerCode.includes('<body') && h1Count === 0) {
  return { hasIssue: true, issue: 'Page has no <h1> element — every page needs exactly one main heading' }
}
if (fullDocument && h1Count === 0 && lowerCode.includes('<h2')) {
  return { hasIssue: true, issue: 'Found <h2> without <h1> (heading hierarchy issue)' }
}

这段实现(对应 review-code.ts)揭示了几条值得注意的判定细节:

  • 判定对象是渲染后的完整页面:只有当代码被识别为完整 HTML 文档(含 <body>)时才强制执行"必须有 H1";而 JSX/TSX 组件源码并不反映最终渲染的标题树,因此组件源码会跳过检查(componentSource && !fullDocument 时直接返回无问题),这与规则中"必须检查渲染后的 DOM 而非源码"的建议一脉相承;
  • 多 H1 与缺 H1 是两个独立问题:h1Count > 1 判定多 H1;<body 存在且 h1Count === 0 判定缺 H1;
  • 层级检查联动:完整文档中若存在 <h2> 却没有 <h1>,会被视为标题层级问题,这与仓库中另一条规则 heading-order(标题不得跳级,如 H1→H3 而无 H2)相互呼应;
  • slug 别名机制:源码中 h1 作为 slug 别名被直接映射到同一套检查逻辑(见 review-code.ts),说明该检查同时服务于 h1 与 heading-hierarchy 两条规则。

这意味着,无论你是手动审计还是接入 MCP 代码评审工具,检查目标都应该是渲染后的 DOM——JavaScript 框架可能在运行时改变标题结构,只查看源码可能产生误判。

代码评审清单(Code Review)

在代码评审阶段,skills/h1/SKILL.md 建议执行以下 DOM 查询式断言:

  1. 查询页面全部 <h1> 元素,断言每页恰好存在一个
  2. 检查 innerText.trim() 非空——排除空 H1 和纯空白 H1
  3. 将 H1 文本与页面 <title> 对比——二者应共享核心主题关键词
  4. 标记共享布局中的 H1——若 H1 位于所有页面共享的 <header> 元素内(通常是站点 logo 的 alt 文本),说明它并非页面内容专属标题,需要修复

React / Next.js 中的正确落地

规则特别强调:在 Next.js/React 架构中,H1 必须位于页面组件内,而不是共享布局中。这与仓库自身站点的实现完全一致——Front-End-Checklist 的规则详情页将 H1 放在页面专属组件里:

// apps/web/app/(site)/rules/[category]/[slug]/rule-page-sections.tsx
export function RulePageHeader({ rule, hasPrompts }: RuleHeaderProps) {
  return (
    <header className="mb-6">
      <div className="space-y-6">
        ...
        <h1 className="font-heading font-medium text-6xl ...">
          {rule.title}
        </h1>
        ...
      </div>
    </header>
  )
}

关键点(对应 rule-page-sections.tsx/rules/[category]/[slug]/rule-page-sections.tsx#L37-L50)):虽然 H1 位于 <header> 元素内,但这个 header 是该页面专属的规则页头组件(RulePageHeader),只在单个规则详情页渲染,并不跨页面共享,因此 H1 文本就是该页面的主题(规则标题),符合"H1 必须页面专属"的要求。这提醒我们在自己的项目中区分两类 header:全站共享的站点导航 header 与页面专属的内容 header,H1 只能属于后者。

相关规则与联动审计

H1 不是孤立存在的,Front-End-Checklist 在 h1.mdx 中明确列出了它的关联规则(relatedRules),审计时应一并检查:

  • heading-order:标题层级(H1→H2→H3)属于同一结构性关注点,H1 之后不能直接跳到 H3
  • meta-title:<title> 与 H1 应主题对齐
  • meta-description:当 H1、标题、描述三者主题一致时,搜索结果摘要效果最佳
  • title-unique:与 h1 同属 seo/meta-tags 区域,常被一起审查

异常情况(Exceptions)

并非所有页面都适用同一套内容深度标准:

  • 必要的工具页或合规页面(如隐私政策、条款页)可以刻意简短,不应以排名型内容的编辑深度标准来衡量
  • AI 辅助起草本身不是问题;需要标记的是缺乏支撑的主张、缺失人工审校或低原创性输出
  • 当页面同时存在信任信号问题和抓取/索引问题时,应优先让页面具备可排名资格,再提升内容质量信号

验收标准与验证方法

验收标准(Standards)

  • 以 Google Search Central 关于标题与 heading 标签的官方指南作为最终搜索可见 HTML、元数据与抓取行为的标准
  • 在处理规则视为通过之前,需同时对照 MDN 关于 HTML 章节标题元素的说明核对实现

自动化验证(Automated Checks)

  • 检查渲染后的 HTML 与 HTTP 响应头,确认预期的元数据或可抓取性信号存在
  • 使用 Google Search Console 或等效工具测试受影响的 URL
  • 部署后对代表性页面集重新抓取

手动验证(Manual Checks)

  • 确认改动不会与 canonical URL、robots 元数据或结构化数据信号产生冲突
  • 使用浏览器 DevTools 或站点爬虫定位 0 个或 2+ 个 H1 的页面,修复后再次检查渲染后的 DOM

总结

H1 是页面主题的第一陈述者。以"每页恰好一个、描述具体主题、自然包含关键词、与 title 主题一致"为基准,配合渲染后 DOM 检查与仓库源码中的自动化校验逻辑,即可系统性消除缺 H1、多 H1、空 H1、品牌名 H1 等问题。Front-End-Checklist 既提供了可读的规则文档(h1.mdx、SKILL.md、rule.md),也提供了可执行的源码实现(review-code.ts),是日常 SEO 审计与代码评审的双重参照。

登录后查看全文
Front-End-Checklist