自定义Docusaurus主题插件Swizzle DocNavbarItem遇文档ID未定义错误

错误根源 #

1. 组件路径错误：你目标是替换DocNavbarItem，但当前自定义组件放在theme/NavbarItem路径下，这会覆盖全局所有NavbarItem组件。普通NavbarItem没有docId属性，强制渲染DocNavbarItem时就会抛出"找不到id为undefined的文档"错误。
2. 缺少必要属性校验：DocNavbarItem必须依赖docId或to属性定位文档，你的包装组件未做校验就直接传递props，导致无效参数传入。

修复步骤 #

1. 修正组件路径 #

将自定义组件移到正确的swizzle路径：
把src/theme/NavbarItem/index.tsx重命名为src/theme/DocNavbarItem/index.tsx，这样只会替换原有的DocNavbarItem组件，不会影响普通NavbarItem。

2. 完善组件逻辑 #

更新src/theme/DocNavbarItem/index.tsx，添加属性校验并确保仅传递有效参数：

import { DocNavbarItem } from '@docusaurus/theme-classic';
import { useEffect } from 'react';
import { useDocs } from '@docusaurus/theme-common/internal';

export default function DocNavbarItemWrapper(props: { docId?: string; to?: string; label?: string }) {
  const { docs } = useDocs();
  // 提取有效文档ID：优先用docId，否则从to路径解析
  const targetDocId = props.docId || props.to?.replace(/^\/docs\//, '');

  useEffect(() => {
    console.log('useffect');
  });

  // 校验文档ID有效性
  if (!targetDocId || !docs.some(doc => doc.id === targetDocId)) {
    console.warn(`DocNavbarItem: 无效文档ID "${targetDocId}"`);
    return <span>{props.label || '无效文档链接'}</span>; // 降级渲染
  }

  return (
    <>
      test
      <DocNavbarItem {...props} />
    </>
  );
}

3. 检查导航栏配置 #

确保docusaurus.config.js中使用DocNavbarItem时提供正确的属性：

navbar: {
  items: [
    // 正确用法1：指定docId
    {
      type: 'doc',
      docId: 'intro', // 替换为你实际存在的文档ID
      position: 'left',
      label: '介绍',
    },
    // 正确用法2：指定to路径
    {
      type: 'doc',
      to: '/docs/intro',
      label: '介绍',
    },
  ],
},

4. 重启项目测试 #

执行命令重启Docusaurus：

npm run start

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