BreadcrumbList 面包屑结构化数据实现

用 JSON-LD 在页面 <head> 输出一段 BreadcrumbList，position 从 1 连续编号、item 全部用绝对 URL、最后一级（当前页）可以省略 item 只留 name，这段代码就能让 Google 把搜索结果里那行绿色 URL 换成一串可点击的层级路径。它不影响页面样式，也不和你在页面上画的面包屑导航冲突，二者内容一致就行。

BreadcrumbList 和页面上的面包屑导航是什么关系

结论：BreadcrumbList 是给机器读的「页面在站点层级中的位置声明」，页面上的面包屑导航是给人看的，两者是同一份信息的两套呈现，内容必须一致。

BreadcrumbList 是 Schema.org 定义的一种结构化数据类型，itemListElement 是一个有序列表，每一项包含 position（序号）、name（层级名）、item（该层级的 URL）。Google 拿到它之后，会把搜索结果里原本单纯的一行 URL 替换为「首页 › 版块 › 帖子标题」这种可点击路径，用户能直接跳到上层页面。

实现方式有两种：微数据（Microdata，写在 HTML 标签的 itemprop 属性里）和 JSON-LD（独立的一段 <script type="application/ld+json">）。推荐 JSON-LD，因为它与视图层解耦，改模板时不容易误删，一套 head 模板就能覆盖全站。

BreadcrumbList 的 JSON-LD 怎么写

结论：三级页面的标准写法如下，position 从 1 开始严格连续，item 用带域名的绝对地址。

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "首页", "item": "https://www.example.com/" },
    { "@type": "ListItem", "position": 2, "name": "技术交流", "item": "https://www.example.com/forum-3.html" },
    { "@type": "ListItem", "position": 3, "name": "BreadcrumbList 面包屑结构化数据实现" }
  ]
}
</script>

要点逐条：

1. 最后一级省略 item。它就是当前页，省略后 Google 会把它渲染成不可点击的纯文本，这是官方推荐做法；如果非要写，URL 必须是当前页自身的绝对地址。
2. position 只能是 1、2、3 连续整数，跳号（比如 1、2、4）或从 0 开始会被判为无效。
3. item 必须是绝对 URL，/forum-3.html 这种相对路径校验会报错。
4. name 是必填项，且要与页面上可见的面包屑文字一致，不要在这里塞关键词堆砌。
5. 层级控制在 2-6 级。只有一级（仅首页）没有意义，Google 不会展示；层级过深在移动端结果页会被截断。

动态生成时，写一个函数接收「层级数组」，内部把 position 按下标自增，输出前做一次 HTML 转义（json_encode 时加 JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES，避免中文变成 \uXXXX、斜杠被转义成 \/ 影响可读性）。

哪些写法会导致校验失败或富摘要不展示

结论：绝大多数「代码没错但搜索结果不显示面包屑」的情况，原因不在语法，而在于层级、可见性或抓取。

• 页面上的面包屑被 CSS 隐藏：结构化数据描述的内容必须是用户可见的。用 display:none 藏起来的面包屑，Google 会判定为不一致。
• 同一页输出多段 BreadcrumbList：一个页面只保留一段，多段会让解析器取错。
• name 与 item 指向的页面标题严重不符：比如 name 写「首页」但 URL 指向某个帖子。
• 层级路径与站点实际目录结构矛盾：面包屑声明的父子关系应当和站内链接结构对得上，凭空拼出来的路径即使语法通过也不会被展示。
• 只部署了代码没提交 sitemap：新页面需要被抓取后才会进入 Breadcrumb 报告，抓取到数据出现通常要几天，不是即时生效。

需要说明的是，本系统（Clara BBS）在后台「系统设置 → GEO 优化」中提供了结构化数据输出与单篇 GEO 体检工具，可用于核对页面结构化数据的输出情况；面包屑层级本身应按你站点的版块结构自行拼装，不要声明站点并不存在的层级。

用什么工具验证 BreadcrumbList 是否生效

结论：发布后用 Google 富媒体结果测试（Rich Results Test）确认语法，用 Search Console 的「面包屑」报告确认线上生效。

步骤：

1. 打开富媒体结果测试，粘贴 URL 或直接贴代码，检查 BreadcrumbList 是否被识别、有无「无效」项。
2. 在 Search Console 左侧「增强功能 → 面包屑」查看已抓取的有效条目数与错误明细，数据一般滞后数天。
3. 用 curl -s https://你的域名/某帖子 | grep -A20 'BreadcrumbList' 确认线上 HTML 里确实输出了这段 JSON，避免模板缓存或条件判断把它吞掉。
4. 改动模板后重新跑一次测试，尤其是改了 URL 结构（比如伪静态规则调整）之后。

收个尾：BreadcrumbList 的成本极低——一段动态拼装的 JSON-LD、五个固定字段、两项强制校验（position 连续、item 绝对地址），换来的是搜索结果里可点击的层级路径和更清晰的站点结构信号，对搜索引擎和 AI 引擎理解页面归属都有直接帮助。写完先跑测试，再等 Search Console 报告确认。