mcpField
3
30x-seo-hreflang

30x-seo-hreflang

github.com/norahe0304-art营销与增长5666 次安装33 周前更新
代码仓库

关于 30x-seo-hreflang

用于验证现有 hreflang 配置并为多语言、多地区网站生成标签，支持 HTML、HTTP 标头和 XML 站点地图，并检查双向链接、代码及规范 URL。

主要功能

  1. 01验证自引用标签和返回标签
  2. 02检查语言和地区代码
  3. 03核对规范 URL 是否一致
  4. 04支持 HTML、HTTP 标头和站点地图
  5. 05生成 hreflang 实现内容

适用场景

  1. 01审查不同语言版本的 hreflang
  2. 02查找缺失的双向备用链接
  3. 03为新的地区网站生成标签
  4. 04将大型 hreflang 集迁移到站点地图

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/norahe0304-art/30x-seo --skill 30x-seo-hreflang

安装后在 Claude Code 中输入/30x-seo-hreflang确认已加载。

详细介绍

Hreflang 与国际 SEO

验证现有的 hreflang 实现，或为多语言和多地区网站生成正确的 hreflang 标签。支持 HTML、HTTP 标头和 XML 站点地图实现。

验证检查项

1. 自引用标签
  • 每个页面都必须包含指向自身的 hreflang 标签
  • 自引用 URL 必须与页面的规范 URL 完全一致
  • 缺少自引用标签会导致 Google 忽略整组 hreflang 标签
2. 返回标签
  • 如果页面 A 通过 hreflang 链接到页面 B，页面 B 必须链接回页面 A
  • 每种 hreflang 关系都必须是双向的（A→B 且 B→A）
  • 缺少返回标签会使两个页面的 hreflang 信号都失效
  • 检查所有语言版本是否彼此引用（全连接）
3. x-default 标签
  • 必需：指定用于匹配不到的语言或地区的备用页面
  • 通常指向语言选择页面或英文版本
  • 每组备用页面中只能有一个 x-default
  • 所有其他语言版本也必须有返回标签
4. 语言代码验证
  • 必须使用 ISO 639-1 双字母代码（例如 en、fr、de、ja）
  • 常见错误：
    • 用 eng 代替 en（这是 ISO 639-2，不适用于 hreflang）
    • 用 jp 代替 ja（日语代码错误）
    • 使用不带地区限定符的 zh（含义不明确，应使用 zh-Hans 或 zh-Hant）
5. 地区代码验证
  • 可选的地区限定符使用 ISO 3166-1 Alpha-2 代码（例如 en-US、en-GB、pt-BR）
  • 格式：language-REGION（语言代码小写，地区代码大写）
  • 常见错误：
    • 用 en-uk 代替 en-GB（UK 不是有效的 ISO 3166-1 代码）
    • 使用 es-LA（拉丁美洲不是国家，应使用具体国家代码）
    • 地区代码前缺少语言代码
6. 规范 URL 一致性
  • hreflang 标签只能出现在规范 URL 上
  • 如果页面的 rel=canonical 指向其他位置，该页面上的 hreflang 标签会被忽略
  • 规范 URL 和 hreflang URL 必须完全一致（包括结尾斜杠）
  • 非规范页面不应出现在任何 hreflang 集合中
7. 协议一致性
  • hreflang 集合中的所有 URL 必须使用相同协议（HTTPS 或 HTTP）
  • hreflang 集合中混用 HTTP/HTTPS 会导致验证失败
  • 迁移到 HTTPS 后，请将所有 hreflang 标签更新为 HTTPS
8. 跨域支持
  • hreflang 支持不同域名之间的关联（例如 example.com 和 example.de）
  • 跨域 hreflang 要求两个域名上都包含返回标签
  • 确认两个域名都已在 Google Search Console 中通过验证
  • 跨域设置建议使用基于站点地图的实现

常见错误

问题严重程度修复方法
缺少自引用标签严重添加指向同一页面 URL 的 hreflang 标签
缺少返回标签（A→B，但没有 B→A）严重为所有备用页面添加匹配的返回标签
缺少 x-default高添加指向备用页面或选择页面的 x-default
语言代码无效（例如 eng）高使用 ISO 639-1 双字母代码
地区代码无效（例如 en-uk）高使用 ISO 3166-1 Alpha-2 代码
hreflang 出现在非规范 URL 上高仅将 hreflang 移至规范 URL
URL 中 HTTP/HTTPS 不一致中将所有 URL 统一为 HTTPS
结尾斜杠不一致中严格匹配规范 URL 格式
HTML 和站点地图中都包含 hreflang低选择一种方式；大型网站优先使用站点地图
需要地区限定符时未填写低为面向特定地区的内容添加地区限定符

实现方式

方式 1：HTML 链接标签

适用场景：每个页面包含少于 50 个语言/地区版本的网站。

<link rel="alternate" hreflang="en-US" href="https://example.com/page" />
<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />

放置在 <head> 部分。每个页面都必须包含所有备用页面，包括自身。

方式 2：HTTP 标头

适用场景：非 HTML 文件（PDF、文档）。

Link: <https://example.com/page>; rel="alternate"; hreflang="en-US",
      <https://example.com/fr/page>; rel="alternate"; hreflang="fr",
      <https://example.com/page>; rel="alternate"; hreflang="x-default"

通过服务器配置或 CDN 规则设置。

方式 3：XML 站点地图（大型网站推荐）

适用场景：包含大量语言版本、采用跨域设置或拥有 50 个以上页面的网站。

请参阅下方的 Hreflang 站点地图生成部分。

方法比较
方法最适用于优点缺点
HTML 链接标签小型网站（<50 个变体）易于实现，在源代码中可见会使 <head> 臃肿，规模扩大后难以维护
HTTP 标头非 HTML 文件适用于 PDF、图像服务器配置复杂，在 HTML 中不可见
XML 站点地图大型网站、跨域网站易于扩展，集中管理页面上不可见，需要维护站点地图

Hreflang 生成

流程
  1. 检测语言：扫描网站中的语言指示（URL 路径、子域名、顶级域名、HTML lang 属性）
  2. 映射页面对应关系：匹配不同语言或地区的对应页面
  3. 验证语言代码：根据 ISO 639-1 和 ISO 3166-1 验证所有代码
  4. 生成标签：为每个页面创建 hreflang 标签，包括自引用标签
  5. 验证返回标签：确认所有关系均为双向
  6. 添加 x-default：为每组页面设置回退选项
  7. 输出：生成实现代码（HTML、HTTP 标头或站点地图 XML）

Hreflang 站点地图生成

带 Hreflang 的站点地图
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/page</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
    <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
  </url>
  <url>
    <loc>https://example.com/fr/page</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
    <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
  </url>
</urlset>

关键规则：

  • 包含 xmlns:xhtml 命名空间声明
  • 每个 <url> 条目都必须包含所有语言的替代页面（包括其自身）
  • 每个替代页面都必须作为单独的 <url> 条目出现，并包含其自身的完整条目集
  • 每个站点地图文件最多包含 50,000 个 URL

输出

Hreflang 验证报告
摘要
  • 扫描页面总数：XX
  • 检测到的语言变体：XX
  • 发现的问题：XX（严重：X，高：X，中：X，低：X）
验证结果
语言URL自引用返回标签x-default状态
en-UShttps://...✅✅✅✅
frhttps://...❌⚠️✅❌
dehttps://...✅❌✅❌
生成的 Hreflang 标签
  • HTML <link> 标签（如果选择 HTML 方法）
  • HTTP 标头值（如果选择标头方法）
  • hreflang-sitemap.xml（如果选择站点地图方法）
建议
  • 添加缺失的实现
  • 修正错误的代码
  • 方法迁移建议（例如，为便于扩展，将 HTML 迁移到站点地图）

[PROTOCOL]：更改此标头后请更新，然后检查 CLAUDE.md

评论

支持 Markdown