hreflang标签必须静态写入HTML源码，严禁JS动态插入；值需严格符合BCP 47规范（如zh-Hans、en-US、x-default）；每页须完整声明所有语言版本（含自身与x-default）；href必须为绝对URL且协议一致；内容需实质性对应，否则整组失效。
rel="alternate" hreflang 必须静态写死，别用 JS 动态加
浏览器和搜索引擎只认 HTML 源码里直接写出的 <link rel="alternate">，JS 运行时用 document.head.appendChild() 插入的标签，Google 会忽略——不是延迟识别，是根本不算数。
常见翻车点：
- SPA 项目在
useEffect或mounted里遍历语言列表生成<link>，导致每刷新一次就多一组，hreflang冲突直接失效 - 用
innerHTML +=拼接，意外覆盖掉已有的<link rel="canonical">或其他关键标签 - 服务端渲染（SSR）输出了正确标签，但前端 hydration 后又执行一遍 JS 注入，造成重复
实操建议：所有语言页的 <link rel="alternate" hreflang> 必须由后端模板或静态站点生成器（如 Hugo、Next.js getStaticProps）一次性输出；若真要 JS 控制（如微前端嵌套），先 document.querySelectorAll('link[rel="alternate"][hreflang]') 全部 remove()，再统一重写。
hreflang 值必须严格匹配 BCP 47，大小写/连字符错一个就白配
zh-cn、zh_CN、Chinese、zh-ch 全都不合法。Google 的解析器不宽容，错即弃。
立即学习“前端免费学习笔记（深入）”；
正确写法只有这些：
-
en（通用英语） -
en-US（语言小写 + 地区大写） -
zh-Hans（简体中文，注意Hans不是hans） -
zh-Hant-TW（三段式，地区在最后） -
x-default（必须是小写x，不是X或default）
还要同步检查 <html lang="zh-Hans"> 的值是否与 hreflang="zh-Hans" 完全一致——不一致会导致整组 hreflang 被静默忽略，Search Console 里查不到任何国际化报告。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
每个语言页都要声明全部版本，包括自己和 x-default
假设有英文（en-US）、简体中文（zh-Hans）、日文（ja-JP）三个版本，那么 /en/ 页面的 <head> 里必须同时有这三条：
<link rel="alternate" hreflang="en-US" href="https://example.com/en/"> <link rel="alternate" hreflang="zh-Hans" href="https://example.com/zh/"> <link rel="alternate" hreflang="ja-JP" href="https://example.com/ja/">
漏掉任意一条（比如 /en/ 页没声明指向自己的 en-US），或某条 href 返回 404，整组关系就会被降权。更隐蔽的是：x-default 不是可选补充，它得明确指向一个真实存在的兜底页（通常是英文首页），且该页也必须包含完整反向声明。
绝对 URL 是硬性要求：href="/zh/" ❌，href="https://example.com/zh/" ✅；HTTP 和 HTTPS 混用（如当前页是 HTTPS，但 href 写 HTTP）也会被当两个不同页面处理。
hreflang 和语言切换按钮完全无关，别指望它自动跳转
<link rel="alternate" hreflang="zh-Hans" href="https://example.com/zh/"> 只影响搜索引擎如何分发流量，对用户点击、页面渲染、字体加载、拼写检查零影响。
想让用户点一下切语言？你得自己写按钮，然后用 JS 跳转，或服务端根据 Accept-Language 头自动重定向。常见错误：
- 把
hreflang当成“自动语言跳转开关”，结果用户访问英文站，浏览器没反应 - 用
window.location.href = '/zh' + location.pathname硬拼路径，遇到/blog/post-1就变成/zh/blog/post-1，但实际路径是/zh/blog/post-1—— 多了个斜杠或少了个前缀，404 就来了 - 切语言时只改了
document.documentElement.lang，但没跳转，用户看到的仍是英文 HTML 文件
最常被忽略的一点：所有语言页之间内容必须实质性对应。中文页写了完整产品文档，英文页只有标题和空段落，Google 会判定 hreflang 关系不可靠，直接弃用整组配置。
