前端 H1 标签最佳实践:用 Front-End-Checklist 规则打造单一描述性 H1
前端 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 段落,依次执行:
- 确保每个页面模板只输出一个
<h1>——从模板层面杜绝多 H1 或零 H1 的可能 - H1 文本应描述页面的具体主题,而不是只写站点名
- 将主要目标关键词自然融入 H1——不要生硬堆砌
- 若页面有多个 H1 候选段落,选定一个主主题,其余降级为 H2
- 确认 H1 在渲染后的 DOM 中可见(未被 CSS
display:none或visibility:hidden隐藏) - 在 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 查询式断言:
- 查询页面全部
<h1>元素,断言每页恰好存在一个 - 检查
innerText.trim()非空——排除空 H1 和纯空白 H1 - 将 H1 文本与页面
<title>对比——二者应共享核心主题关键词 - 标记共享布局中的 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 审计与代码评审的双重参照。