VitePress 默认主题侧边栏（Sidebar）配置完全指南：分组、多侧边栏、折叠与路径前缀

VitePress 默认主题侧边栏Sidebar配置完全指南分组、多侧边栏、折叠与路径前缀【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress侧边栏是 VitePress 文档站点的核心导航模块它承担着让读者理解站点信息架构、快速定位目标页面的职责。本文基于 VitePress 默认主题系统讲解themeConfig.sidebar的完整配置能力从最简单的链接数组到按路由区分的多侧边栏对象、可折叠分组再到base路径前缀的自动化拼接并结合仓库源码与类型定义说明其底层解析逻辑。读完本文你将能独立为任意文档站设计出结构清晰、可折叠、可多区域切换的侧边栏。侧边栏配置入口themeConfig.sidebar侧边栏菜单在主题配置的themeConfig.sidebar字段中定义完整配置可参考 默认主题配置文档。其最基础的形式是传入一个链接数组export default { themeConfig: { sidebar: [ { text: Руководство, items: [ { text: Введение, link: /ru/introduction }, { text: Первые шаги, link: /ru/getting-started }, ... ] } ] } }从类型定义看见 types/default-theme.d.tsSidebar类型为SidebarItem[] | SidebarMulti数组形式用于单一侧边栏对象形式SidebarMulti用于按路径区分的多侧边栏每个SidebarItem可选字段包括text、link、items、collapsed、base以及docFooterText、rel、target等链接辅助属性。基础用法数组形式的侧边栏结构最简单的侧边栏形式是直接传入一个链接数组。第一层元素定义侧边栏的「分区section」它必须包含text分区标题和items实际的导航链接export default { themeConfig: { sidebar: [ { text: Заголовок секции A, items: [ { text: Пункт A, link: /item-a }, { text: Пункт B, link: /item-b }, ... ] }, { text: Заголовок секции B, items: [ { text: Пункт C, link: /item-c }, { text: Пункт D, link: /item-d }, ... ] } ] } }链接路径的书写规则每个link都必须指向以/开头的实际文件路径。如果链接以斜杠结尾VitePress 会解析为该目录下的index.mdexport default { themeConfig: { sidebar: [ { text: Руководство, items: [ // Ссылка на страницу /ru/guide/index.md { text: Введение, link: /ru/guide/ } ] } ] } }嵌套层级上限6 层侧边栏项支持从根级开始向下嵌套最多 6 层。超过 6 层的嵌套项会被忽略不会显示在侧边栏上export default { themeConfig: { sidebar: [ { text: Уровень 1, items: [ { text: Уровень 2, items: [ { text: Уровень 3, items: [ ... ] } ] } ] } ] } }从源码角度看这一限制由 VPSidebarItem.vue 中的渲染条件v-ifdepth 5实现递归组件每深入一层depth加一当depth达到 5即渲染到第 6 层时便不再继续递归与文档描述的「6 层上限」完全对应。同时该组件还根据层级动态选择标题标签h${props.depth 2}保证第 0 层分区使用h2、更深层使用h3及以下为文档站提供语义化的标题结构。多侧边栏Multiple Sidebars按路由切换当文档包含多个相互独立的内容区块例如「指南」与「配置」时可以为不同路径配置不同的侧边栏。首先将页面按区块组织到各自的目录中. ├─ guide/ │ ├─ index.md │ ├─ one.md │ └─ two.md └─ config/ ├─ index.md ├─ three.md └─ four.md然后将sidebar从数组改为对象以路径前缀作为键为每个目录定义专属侧边栏export default { themeConfig: { sidebar: { // Эта боковая панель отображается, когда пользователь находится в директории guide /guide/: [ { text: Руководство, items: [ { text: Index, link: /guide/ }, { text: One, link: /guide/one }, { text: Two, link: /guide/two } ] } ], // Эта боковая панель отображается, когда пользователь находится в директории config /config/: [ { text: Настройка, items: [ { text: Index, link: /config/ }, { text: Three, link: /config/three }, { text: Four, link: /config/four } ] } ] } } }匹配规则与源码实现多侧边栏的匹配逻辑在 support/sidebar.ts 的getSidebar函数中实现。其核心算法是将配置对象的所有键按路径段数降序排序b.split(/).length - a.split(/).length然后找出第一个与当前路径匹配的键从而保证「/multi-sidebar/nested/这样的深层路径优先于/multi-sidebar/与/」被命中。该函数对guide/与/guide/两种写法都做了归一化处理ensureStartingSlash。对应测试见tests/unit/client/theme-default/support/sidebar.test.ts分别覆盖了键顺序正常、键顺序反转以及嵌套键三种场景验证了「未命中任何键时回退到/侧边栏」的行为。若没有任何键匹配getSidebar返回空数组此时侧边栏不显示。可折叠分组Collapsible Sidebar Groups在侧边栏分组上添加collapsed选项即可为每个分区显示展开/收起切换按钮export default { themeConfig: { sidebar: [ { text: Заголовок секции A, collapsed: false, items: [...] } ] } }所有分区默认是「展开」状态。如果希望页面初次加载时分区「收起」将collapsed设为trueexport default { themeConfig: { sidebar: [ { text: Заголовок секции A, collapsed: true, items: [...] } ] } }折叠交互的源码细节折叠行为由 composables/sidebar.ts 的useSidebarItemControl组合式函数驱动collapsible判定依据是item.value.collapsed ! null——即只有显式指定了collapsed的分组才会出现折叠按钮未指定时分组不可折叠展开/收起状态通过watchEffect与item.value.collapsed保持同步collapsed.value !!(collapsible.value item.value.collapsed)当分组内任一链接处于激活状态时hasActiveLink分组会自动展开nextTick(() (collapsed.value false))确保用户通过 URL 直达或切换页面时能看到当前所在的分组内容避免「激活链接被折叠隐藏」的困惑激活状态判断依赖 support/sidebar.ts 中的hasActiveLink它会递归遍历嵌套items检测是否存在匹配当前路径的链接。在模板层面VPSidebarItem.vue折叠按钮仅在「显式设置collapsed且存在子项」时渲染并通过aria-expanded暴露折叠状态、通过aria-labeltoggle section提供无障碍语义。分区样式上level-0激活链接左侧会有主题色指示条var(--vp-c-brand-1)帮助用户定位当前位置。路径前缀base消除重复路径当文档结构包含深层目录、或多个分组同处于一个子目录时可以使用base选项为组内所有嵌套items自动拼接路径前缀从而避免为每个link重复书写相同的路径。base在多侧边栏配置与嵌套侧边栏分组中均受支持。在多侧边栏中使用base可以在某个侧边栏分区的配置根部定义baseexport default { themeConfig: { sidebar: { /guide/: { base: /guide/, items: [ // Эта ссылка будет разрешена в /guide/introduction { text: Введение, link: introduction }, // Эта ссылка будет разрешена в /guide/getting-started { text: Первые шаги, link: getting-started } ] } } } }在嵌套分组中使用basebase同样可用于嵌套分组此时它作用于该分组的直接子项。嵌套的base会覆盖父分组的路径前缀export default { themeConfig: { sidebar: [ { text: Справочник, base: /reference/, items: [ // Эта ссылка будет разрешена в /reference/site-config { text: Конфигурация сайта, link: site-config }, { text: Тема по умолчанию, // Вложенный base переопределяет префикс пути родительской группы base: /reference/default-theme-, items: [ // Эта ссылка будет разрешена в /reference/default-theme-nav { text: Навигация, link: nav }, // Эта ссылка будет разрешена в /reference/default-theme-sidebar { text: Сайдбар, link: sidebar } ] } ] } ] } }base拼接的源码实现base的解析发生在 support/sidebar.ts 的addBase函数中。它递归遍历侧边栏项遵循以下规则每个项优先使用自身的base否则继承父级传入的_base只有当项存在link且不是外部链接!isExternal(item.link)时才拼接前缀——外部链接如https://...会被原样保留拼接时处理斜杠边界如果链接以/开头而base以/结尾则去掉链接开头的斜杠以避免双斜杠若base不以/结尾则补上/拼接后的前缀会继续沿items向下传递addBase(item.items, base)实现整棵子树的前缀继承。这一行为有对应的单元测试验证见 sidebar.test.ts测试「applies base only to internal links」确认了base仅作用于站内链接——相对链接intro被解析为/en/intro以/开头的root被解析为/en/root而https://example.com/这类外部链接不受base影响。侧边栏与页面的联动激活态与分组聚合除了配置本身理解侧边栏如何「感知」当前页面有助于排查问题。getSidebar之后主题还会通过 getSidebarGroups 将「无items的平铺链接」自动聚合进前一个分组保证渲染结构的统一而 getFlatSideBarLinks 则会递归展平所有嵌套链接并保留docFooterText、rel、target元数据这些数据被「上一页/下一页」导航与搜索等功能复用。在 SSR 与客户端水合阶段useSidebarItemControl会在 setup 期间执行一次updateActiveLink(true)跳过 hash 检查以保证服务端渲染的输出中也带有正确的激活样式并在路由变化、组件挂载后重新计算精确的激活链接composables/sidebar.ts。侧边栏整体的显隐则由hasSidebar与sidebarGroups驱动见 VPSidebar.vue在窄屏下作为抽屉式导航呈现、宽屏下常驻页面左侧。小结本文完整覆盖了 VitePress 默认主题侧边栏的四种核心配置能力数组形式的单一侧边栏含 6 层嵌套上限与/结尾解析index.md的规则、对象形式的多侧边栏按路径前缀切换并支持深层键优先匹配、collapsed可折叠分组默认展开、可设置初始收起、激活时自动展开以及base路径前缀支持多侧边栏根部与嵌套分组内定义、可覆盖继承、对外部链接豁免。结合 types/default-theme.d.ts 的类型定义、support/sidebar.ts 的解析逻辑与 单元测试 的验证用例你可以放心地依据这些规则搭建出适配任意文档架构的导航体系。【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考