hreflang-check

/digital-marketing-pro:hreflang-check

用途

审查 hreflang 标签的实现情况，确保多语言和多地区 SEO 配置正确。Hreflang 注释会告知搜索引擎应向哪些受众展示页面的哪个语言和地区版本。实现有误时，搜索结果中可能会显示错误的语言版本，多个页面会针对相同查询相互竞争，国际自然流量也会因内容投放错误而流失。此命令会全面审查 hreflang 的技术实现，检查所有语言版本是否通过正确的注释相互交叉引用、每个页面是否引用自身、引用是否双向（如果页面 A 指向页面 B，页面 B 也必须指回页面 A）、语言-地区代码是否有效、是否配置了 x-default 回退，以及是否存在指向不存在页面的孤立引用。

对于任何经营多语言或多地区网站的品牌而言，这项审查都至关重要。Hreflang 错误是国际 SEO 中最常见的问题之一：用户无法察觉、人工 QA 很少能发现，而且会悄然损害所有受影响市场的搜索表现。即使只缺少一条双向引用，也可能导致搜索引擎无法正确关联不同语言版本，使错误页面获得排名，或让重复内容信号同时压制两个版本。此命令会列出每个实现错误，并提供具体的修复说明和更正后的代码片段。

所需输入

用户必须提供（或系统会提示提供）：

• 网站 URL 或站点地图 URL：审查的起点。可以是单个页面 URL（审查该页面上的 hreflang 以及其引用的备用页面）、站点地图 URL（审查站点地图中列出的所有页面），或要检查的页面 URL 列表。注意：此插件不会直接抓取网站；如果提供了 URL，系统会引导用户提供 HTML 源码或 hreflang 数据以供分析。用户也可以直接粘贴 HTML 源码、hreflang 标签集或导出的 hreflang 数据
• 要检查的特定页面 URL（可选）：指定审查的页面子集；适用于审查某个特定版块（例如所有产品页面或所有博客文章），而不是整个网站。如果未提供，则会审查所提供数据中所有带有 hreflang 注释的页面
• 预期语言-地区代码（可选）：应出现在 hreflang 注释中的语言-地区代码集合（例如 en-US、de-DE、fr-FR、es-ES、ja-JP）。默认采用 profile.json 中语言配置所设定的品牌语言。此项用于标记缺失的语言版本：如果品牌面向 de-DE 市场，但页面上没有 de-DE 的 hreflang，就会将其标记为缺漏

流程

1. 加载品牌背景信息：读取 ~/.claude-marketing/brands/_active-brand.json 获取当前激活的 slug，然后加载 ~/.claude-marketing/brands/{slug}/profile.json。加载语言配置，以确定预期语言：主要语言、次要语言和内容语言。这些语言构成了每个页面理想情况下都应引用的预期 hreflang 集合。针对目标市场应用合规规则（skills/context-engine/compliance-rules.md）和行业背景。同时检查 ~/.claude-marketing/brands/{slug}/guidelines/_manifest.json 中是否有指南；如果有，加载其中的国际 SEO 指南。检查 ~/.claude-marketing/sops/ 中是否有代理机构 SOP。如果不存在品牌，询问：“请先设置品牌（/digital-marketing-pro:brand-setup）？”——或者使用默认设置继续。
2. 获取 hreflang 数据：如果用户提供了 URL，请说明实际抓取网站需要外部工具——该插件不会向任意网站发送 HTTP 请求。引导用户通过以下任一格式提供 hreflang 数据：(a) 含有 <link rel="alternate" hreflang="..." href="..."> 标签的页面原始 HTML 源码，(b) HTTP 标头中的 hreflang 注解，(c) 含有 xhtml:link hreflang 条目的 XML 网站地图，(d) SEO 工具（Screaming Frog、Sitebulb、Ahrefs）导出的结构化数据，其中按 URL 列出 hreflang 注解，或 (e) 手动整理的 URL 与语言映射列表。如果用户已在消息中提供 HTML 或 hreflang 数据，直接开始解析。
3. 解析所有 hreflang 注解：从所提供的数据中提取每条 hreflang 注解。为每个页面建立映射，包含：页面自身的 URL，以及每个 hreflang 属性和对应的 href URL。记录每条注解的来源（HTML <link> 标签、HTTP 标头或 XML 网站地图），因为实现方式会影响修复方法。建立完整的交叉引用矩阵：对每个页面，记录其引用了哪些其他页面，以及这些页面对应的语言。
4. 检查每个页面的 hreflang 是否正确：对所有带有 hreflang 注解的页面执行以下检查：
   • (a) 存在自指标签：每个页面都必须包含一条指向自身、使用其自身语言-地区代码的 hreflang 注解。缺少自指标签是最常见的 hreflang 错误，会导致搜索引擎忽略该页面的整个 hreflang 集合。严重程度：严重。
   • (b) 双向引用：如果 en-US 页面 A 引用 de-DE 页面 B，那么页面 B 也必须引用 en-US 页面 A。检查每一对引用是否保持双向一致。搜索引擎会将单向引用视为错误，并可能忽略整个注解集合。严重程度：严重。
   • (c) 有效的语言-地区代码：验证每个 hreflang 值中的语言部分是否符合 ISO 639-1，且可选的地区部分是否符合 ISO 3166-1 Alpha-2。常见错误：使用 en-UK 而非 en-GB，使用 eng 等三字母代码而非 en，或只使用国家代码（如 US）而不加语言前缀。代码无效时严重程度为严重（搜索引擎会忽略）；代码非标准但可解析时严重程度为警告。
   • (d) 存在 x-default 标签：检查是否存在 x-default hreflang 注解，并指向语言与任何特定 hreflang 都不匹配的用户所使用的后备页面。通常指向英文版本或语言选择页面。缺少 x-default 可能导致目标区域以外的用户看到任意语言版本。严重程度：警告。
   • (e) 不存在重复语言代码：检查每个页面是否有多个使用相同语言-地区代码、但指向不同 URL 的 hreflang 注解。重复代码会造成歧义，搜索引擎可能忽略该语言的所有注解。严重程度：严重。
   • (f) URL 为绝对 URL：确认 hreflang 注解中的所有 href 值都是绝对 URL（以 https:// 或 http:// 开头），而非相对路径。根据规范，hreflang 中的相对 URL 无效。严重程度：严重。
   • (g) URL 一致性：检查所有引用的 URL 是否使用一致的协议（全部为 HTTPS 或全部为 HTTP，不得混用）、一致的 www/非 www 前缀，以及一致的尾部斜杠规则。不一致可能导致搜索引擎将引用视为指向不同页面。严重程度：警告。
5. 与品牌语言配置交叉核对：将 hreflang 注解中的语言-地区代码集合与品牌配置的语言（来自 profile.json 的语言配置或用户提供的预期代码）进行比较。标记配置中存在、但 hreflang 注解中缺失的语言——这表示品牌正在积极面向某种语言的用户，但没有提供该语言的 hreflang 支持，因此搜索引擎无法将用户正确导向相应语言版本。还要标记不在品牌配置中的 hreflang 语言代码——这些代码可能合理（语言已在其他位置配置），也可能表示已停用语言版本的过时注解。
6. 生成按优先级排序的修复清单和代码片段：针对发现的每个问题，生成具体的修正 hreflang 代码。对于缺少自指标签的情况，提供要添加的确切 <link rel="alternate" hreflang="xx-XX" href="https://..."> 标签。对于双向引用不匹配的情况，提供需要添加到缺少反向引用的页面中的标签。对于无效代码，提供包含有效语言-地区值的修正代码。对于缺少 x-default 的情况，提供包含适当后备 URL 的推荐 x-default 标签。按页面归类修复项，以便逐页实施；同时也按问题类型归类，以便通过单个模板修复系统性问题（例如“所有 47 篇博客文章都缺少自指标签”），而不必逐一进行 47 处修正。

输出

一份结构化的 hreflang 审核报告，包含：

• Hreflang 审核评分：反映实现质量的总体评分（0-100），根据正确标注占全部标注的比例计算，并按问题严重程度加权——严重问题会大幅降低评分，警告会适度降低评分，信息项则影响最小
• 审核摘要统计数据：审核页面总数、发现的 hreflang 标注总数、检测到的唯一语言-地区代码总数、发现的问题总数（按严重、警告、信息分类），以及 hreflang 实现完全正确的页面百分比
• 按类型分类的问题：按每类检查分组列出发现的问题——缺少自引用标签（数量和受影响页面）、孤立引用（指向不存在或无响应页面的引用）、无效语言-地区代码（包括无效代码及修正建议）、缺少 x-default（未配置回退项的页面）、双向不匹配（引用仅为单向的页面对）、重复语言代码（同一语言存在冲突标注的页面）、相对 URL（标注使用非绝对路径）以及 URL 一致性问题（协议混用、www/non-www 不一致、尾部斜杠不匹配）
• 具体修复建议：针对每个问题提供准确的修正后 hreflang 代码片段，可直接实施——用户可以将修正后的 <link> 标签或站点地图条目直接复制到页面中。修复建议既按页面分组（便于在页面层面实施），也按问题类型分组（便于在整个网站范围内系统性修复）
• 语言覆盖矩阵：以页面为行、语言-地区代码为列的表格，每个单元格表示是否存在正确的 hreflang 标注（通过）、标注存在但有问题（警告）或缺少标注（缺口）。可立即直观地查看哪些页面已实现完整的 hreflang 覆盖，哪些页面存在缺漏
• 品牌语言配置对比：并列比较品牌配置的语言与 hreflang 标注中发现的语言，突出显示品牌目标市场中缺少 hreflang 支持的语言（覆盖缺口），以及不在品牌配置中的 hreflang 语言（可能已过时或未受管理）
• 实现方式说明：根据标注来源（HTML 链接标签、HTTP 标头、XML 站点地图），提供针对具体实现方式的修复指导——包括在 HTML <head> 中添加标签的位置、如何配置 HTTP 标头，或如何通过 xhtml:link 条目更新 XML 站点地图

使用的 Agent

• seo-specialist — 负责 hreflang 技术审核。解析 HTML、HTTP 标头和 XML 站点地图中的 hreflang 标注。依据国际 SEO 规范执行全部七项验证（自引用、双向关系、代码有效性、x-default、重复代码、绝对 URL、URL 一致性）。针对发现的每个问题生成修正后的 hreflang 代码片段。评估 hreflang 错误对国际搜索曝光度的 SEO 影响，并根据哪些修复对自然流量导向的影响最大提供优先级建议。参照 skills/technical-seo/international-seo.md 中的 hreflang 规范详情和最佳实践
• localization-specialist — 根据 ISO 639-1 和 ISO 3166-1 标准验证语言-地区代码，并将 hreflang 语言覆盖范围与品牌配置的语言进行交叉比对，以识别覆盖缺口；同时标记技术上有效但可能不适合品牌目标市场的语言代码（例如，针对不同的中文市场，应使用 zh-Hans 或 zh-Hant，而不是通用的 zh）。为覆盖矩阵提供语言相关背景信息，并根据品牌的市场策略建议语言-地区代码的细化程度