顶栏和侧边栏

顶栏导航（Nav）

顶栏就是页面最上面那一条横条。配置在 themeConfig.nav 里：

themeConfig: {
  nav: [
    { text: '首页', link: '/' },
    { text: '教程', link: '/VitePress 配置教程/' },
    {
      text: '更多',
      items: [
        { text: 'GitHub', link: 'https://github.com' },
      ]
    }
  ]
}

所有配置项

字段	类型	说明
text	string	显示的文字
link	string	点击跳转的链接
items	NavItem[]	子菜单，可无限嵌套
activeMatch	string	正则，手动控制什么时候高亮
target	string	链接打开方式，_blank 新窗口
rel	string	链接的 rel 属性

activeMatch 怎么用

默认情况下，VitePress 根据 link 自动判断当前页面来高亮导航项。但有时需要手动控制：

{
  text: '教程',
  link: '/VitePress 配置教程/',
  activeMatch: '^/VitePress 配置教程/'  // 匹配 /VitePress 配置教程/ 开头的所有页面
}

嵌套下拉菜单

{
  text: '项目',
  items: [
    {
      text: '前端项目',
      items: [
        { text: '项目A', link: '/项目A/' },
        { text: '项目B', link: '/项目B/' },
      ]
    },
    {
      text: '工具',
      items: [
        { text: '脚本工具', link: '/tools/' },
      ]
    }
  ]
}

侧边栏（Sidebar）

侧边栏配置比顶栏灵活，有两种形式：数组（单侧边栏）和对象（多侧边栏）。

方式一：单侧边栏

所有页面用同一个侧边栏，直接写数组：

sidebar: [
  {
    text: '教程',
    items: [
      { text: '快速开始', link: '/VitePress 配置教程/快速开始' },
      { text: '顶栏和侧边栏', link: '/VitePress 配置教程/顶栏和侧边栏' },
    ]
  },
  {
    text: '项目',
    items: [
      { text: '项目A', link: '/项目A/' },
      { text: '项目B', link: '/项目B/' },
    ]
  }
]

方式二：多侧边栏（推荐）

不同路径显示不同的侧边栏，对象形式：

sidebar: {
  '/VitePress 配置教程/': [
    {
      text: '教程目录',
      items: [
        { text: '快速开始', link: '/VitePress 配置教程/快速开始' },
        { text: '顶栏和侧边栏', link: '/VitePress 配置教程/顶栏和侧边栏' },
        { text: '主题配置', link: '/VitePress 配置教程/主题配置' },
      ]
    }
  ],
  '/项目A/': [
    {
      text: '项目A',
      items: [
        { text: '概述', link: '/项目A/' },
        { text: '使用指南', link: '/项目A/使用指南' },
      ]
    }
  ],
  '/项目B/': [
    {
      text: '项目B',
      items: [
        { text: '概述', link: '/项目B/' },
      ]
    }
  ],
  '/': []  // 首页不显示侧边栏
}

使用 base 简化链接

如果链接前缀都相同，可以用 { items, base } 形式省去重复：

'/VitePress 配置教程/': {
  base: '/VitePress 配置教程/',
  items: [
    { text: '快速开始', link: 'kuai-su-kai-shi' },   // 实际 → /VitePress 配置教程/快速开始
    { text: '顶栏和侧边栏', link: 'ding-lan-he-ce-bian-lan' },
  ]
}

匹配规则

• 键是路径前缀，必须以 / 结尾
• 匹配方式：path.startsWith(key)
• 更深路径优先：/项目A/指南/ 优先于 /项目A/，/项目A/ 优先于 /
• 没有匹配到任何键时，侧边栏为空

可折叠分组

每个分组都可以配置折叠行为：

{
  text: '教程目录',
  collapsed: false,    // false = 默认展开（当前章节）
  items: [...]
},
{
  text: '其他项目',
  collapsed: true,     // true = 默认折叠
  items: [...]
}

collapsed 值	行为
不设置	不可折叠，始终展开
false	可折叠，默认展开
true	可折叠，默认折叠

分组有 link 时，点击标题文字会跳转；没有 link 时点击只是展开/折叠。

多层嵌套

侧边栏支持无限嵌套：

{
  text: '教程',
  items: [
    {
      text: '基础',
      items: [
        { text: '快速开始', link: '...' },
        { text: '配置', link: '...' },
      ]
    },
    {
      text: '进阶',
      collapsed: true,
      items: [
        { text: '自定义主题', link: '...' },
      ]
    }
  ]
}

自动生成侧边栏

当项目数量多时，手动维护每个多侧边栏的条目很麻烦。写一段 JS 代码自动生成：

const projects = [
  {
    name: '🎶 超声波定向扬声器',
    path: '/超声波定向扬声器/',
    pages: [
      { text: '项目首页', link: '/超声波定向扬声器/' },
      { text: '痛点与发现', link: '/超声波定向扬声器/痛点与发现' },
      { text: '产品介绍', link: '/超声波定向扬声器/产品介绍' },
    ]
  },
  {
    name: '项目B',
    path: '/项目B/',
    pages: [{ text: '概述', link: '/项目B/' }]
  },
  {
    name: 'VitePress 配置教程',
    path: '/VitePress 配置教程/',
    pages: [
      { text: '教程首页', link: '/VitePress 配置教程/' },
      { text: '快速开始', link: '/VitePress 配置教程/快速开始' },
    ]
  },
]

function buildSidebar(projList) {
  const sidebar = { '/': [] }
  for (const proj of projList) {
    // 每个路径只显示自己的页面，项目之间完全隔离
    sidebar[proj.path] = [{
      text: proj.name,
      collapsed: false,
      items: proj.pages,
    }]
  }
  return sidebar
}

export default defineConfig({
  themeConfig: {
    sidebar: buildSidebar(projects),
  }
})

每个项目页面只显示自己的侧边栏，互不干扰；首页无侧边栏。加新项目只在 projects 数组里加一条。

侧边栏和导航的插槽

如果想在侧边栏或导航前后插入自定义内容（比如 Logo 下方的文字、侧边栏顶部的说明），可以通过主题插槽实现。详见 使用 Vue 中的全局组件部分。