BreadcrumbList 的报错，九成不是 JSON 语法，是层级和页面对不上。校验工具能指出错在哪一行，但改起来得回到模板。
坑一：position 不连续
position 必须从 1 开始连续编号。模板里按数组索引写，遇到缺一级的页面就会出现 1、3、4，整条标记失效。正确做法是按面包屑的实际层级动态生成 position，别写死。
我们给客户做结构化数据审计时，第一件事是把全站的 BreadcrumbList 抽出来，用脚本比对每条 item 的 URL 和页面上真实存在的链接。这一步能捞出一半的问题，比等 GSC 报告快得多。
坑二：name 和页面可见文字不一致
item 里的 name 要和页面上面包屑显示的文字一字不差，URL 要和链接的 href 一致。常见错法：页面上写"文档中心"，标记里写"Docs"；或者 URL 末尾带斜杠、标记里不带，导致 Google 选不到对应页面。
坑三：最后一级
最后一级通常是当前页，可以不写链接，但 name 要保留。有些模板直接从数组里 pop 掉最后一项，结果只剩两级，层级关系错乱。正确做法是保留完整路径，最后一项的 item 可以省略 URL。
2026 年 1 月那次修复
一个 4000 页的文档站，GSC 报 1200 条"缺少字段 item"。查下来是模板里最后一级用当前页变量渲染，某些页面的变量为空。改模板后两周报错清零，搜索结果里开始出现带路径的展示样式。
这件事的价值不在展示样式，在于那 1200 个页面的层级关系终于被正确理解，内链和归档页的权重传递顺了一截。
怎么验证
Rich Results Test 跑单页看具体字段；GSC 的"增强功能 > 面包屑"看全站报错总数和示例 URL；Screaming Frog 用自定义提取抓 JSON-LD 里的字段做批量比对。三个一起用，通常两天能清完。
一个容易忽略的场景
多语言站的目录层不一样，比如中文是 /zh/docs/api，英文是 /en/docs/api，但面包屑的层级名称要跟着语言翻译。有些站模板写死了中文的"产品""文档"，英文页面也显示中文，用户看不懂，name 和页面文字也对不上。这类问题在 GSC 里会以"名称不匹配"的警告出现。
我们一般把每一级的名称做成语言包，模板按当前语言取，一次改完全站生效。
立场
结构化数据要和页面可见内容同时上线。只有 JSON-LD 没有可见面包屑，属于违规；只有面包屑没有标记，少一个展示机会。两件事一起做，成本多不了半小时。
元析智能
为软件公司做 SEO 和 GEO 优化