修复Docusaurus面包屑Schema中item字段无效URL的SEO问题

问题定位 #

从你提供的HTML代码来看，Google Search Console检测到的两个问题是：

1. 首页面包屑项未纳入BreadcrumbList的itemListElement集合，缺少ListItem类型标记与position属性
2. 中间层级的「Formula Editor」项使用<span>而非可跳转链接，没有item属性指向对应页面，且所有层级的position数值偏移1（正确逻辑应为首页=1，Formula Editor=2，当前页=3）

修复方案 #

Docusaurus该版本的默认面包屑组件存在Schema标记不完整问题，需自定义组件替换默认实现：

1. 创建自定义面包屑组件 #

在项目src/theme目录（无则新建）下创建Breadcrumbs.js，代码如下：

import React from 'react';
import { Link, useLocation } from '@docusaurus/router';
import { useDocsSidebar } from '@docusaurus/theme-common/internal';

const Breadcrumbs = () => {
  const location = useLocation();
  const sidebar = useDocsSidebar();
  if (!sidebar) return null;

  // 构建完整面包屑路径，先添加首页
  const breadcrumbPaths = [{ label: '首页', url: '/', position: 1 }];

  // 从侧边栏递归匹配当前页面的层级链
  const traverseSidebar = (items, currentPath) => {
    for (const item of items) {
      if (item.href === currentPath) return [item];
      if (item.items) {
        const matched = traverseSidebar(item.items, currentPath);
        if (matched) return [item, ...matched];
      }
    }
    return null;
  };

  const currentItemChain = traverseSidebar(sidebar.items, location.pathname);
  if (currentItemChain) {
    currentItemChain.forEach((item, idx) => {
      breadcrumbPaths.push({
        label: item.label,
        url: item.href,
        position: idx + 2 // 首页占了position 1，后续层级依次递增
      });
    });
  }

  return (
    <ul 
      className="breadcrumbs" 
      itemScope 
      itemType="https://schema.org/BreadcrumbList"
    >
      {breadcrumbPaths.map((path, idx) => {
        const isActive = idx === breadcrumbPaths.length - 1;
        return (
          <li 
            key={path.url}
            itemScope 
            itemProp="itemListElement" 
            itemType="https://schema.org/ListItem"
            className={`breadcrumbs__item ${isActive ? 'breadcrumbs__item--active' : ''}`}
          >
            {isActive ? (
              <span className="breadcrumbs__link" itemProp="name">
                {path.label}
              </span>
            ) : (
              <Link className="breadcrumbs__link" itemProp="item" to={path.url}>
                <span itemProp="name">{path.label}</span>
              </Link>
            )}
            <meta itemProp="position" content={path.position} />
          </li>
        );
      })}
    </ul>
  );
};

export default Breadcrumbs;

2. 同步样式（可选） #

如果自定义组件样式与原有面包屑不一致，在src/css/custom.css中补充样式以匹配原设计：

.breadcrumbs {
  display: flex;
  list-style: none;
  padding: 0;
  margin: 1rem 0;
}

.breadcrumbs__item {
  margin-right: 0.5rem;
}

.breadcrumbs__item::after {
  content: '/';
  margin-left: 0.5rem;
}

.breadcrumbs__item--active::after {
  content: '';
}

.breadcrumbs__link {
  text-decoration: none;
  color: #007bff;
}

.breadcrumbs__item--active .breadcrumbs__link {
  color: #6c757d;
  pointer-events: none;
}

3. 验证修复 #

部署修改后，在Google Search Console使用「网址检查工具」重新抓取目标页面，确认面包屑Schema标记符合以下要求：

• 所有层级均纳入itemListElement
• position从1开始依次递增
• 非当前页的层级有有效item链接
• 当前页层级使用<span>且无跳转链接

内容的提问来源于stack exchange，提问作者SoftTimur