主题模式

VitePress 侧边栏 Sidebar 自动生成食用指南（双模式版） ​

发布于: 2026-05-30
更新于: 2026-05-30
字数: 0
时长: 0 分钟
阅读量: -

本文主要作用是为了防止自己忘记，毕竟年纪大了容易忘事，主要记录下如何使用 generateSidebar.mjs 脚本为 VitePress 站点自动生成侧边栏，支持两种工作模式。

前置准备 ​

  • 项目结构如下（根据官方流程部署的 VitePress 文档源目录为 docs/）：
项目根目录/
├── docs/
│ ├── .vitepress/
│ │ ├── config.mts
│ │ └── utils/
│ │ └── generateSidebar.mjs # 脚本放置位置
│ ├── 02.Notes/ # 顶级目录
│ ├── 03.HamCQ/ # 顶级目录
│ ├── 09.About/ # 另一个顶级目录
│ └── index.md
├── package.json
└── ...
  • 已安装依赖：vitepress-plugin-permalink、vitepress-plugin-setfrontmatter（若需要自动写入 permalink，毕竟我是需要的）。
  • 脚本 generateSidebar.mjs 的内容已准备好（见最后，请自行复制粘贴）。

模式一：生成静态文件 ​

这种方式需要手动执行生成命令，将侧边栏写入 .vitepress/sidebar.mts 文件，然后在 config.mts 中静态导入。

1. 放置脚本 ​

将 generateSidebar.mjs 放入 docs/.vitepress/utils/ 目录。

2. 修改 package.json ​

添加 gen:sidebar 命令，并修改 docs:dev 和 docs:build 使其先执行生成：

json
"scripts": {
"gen:sidebar": "node docs/.vitepress/utils/generateSidebar.mjs",
"docs:dev": "npm run gen:sidebar && vitepress dev docs",
"docs:build": "npm run gen:sidebar && vitepress build docs"
}

如果是使用 Cloudflare Workers 部署，需要在 workers.json 中添加构建命令为 npm run gen:sidebar && npm run docs:build 命令。

3. 修改 config.mts ​

在配置文件中静态导入生成的侧边栏文件：

ts
import { defineConfig } from 'vitepress';
import sidebar from './sidebar.mts';   // 导入生成的侧边栏

export default defineConfig({
  // ... 其他配置
  themeConfig: {
    sidebar,   // 直接使用
    // ...
  }
});

4. 运行 ​

  • 首次运行或每次增删文档后，执行 npm run docs:dev（会自动先执行 gen:sidebar，然后启动开发服务器）。
  • 也可以单独运行 npm run gen:sidebar 只生成侧边栏文件，不启动服务器。

模式二：动态导入函数（当前使用） ​

这种方式不需要生成静态文件，在 config.mts 中直接调用脚本导出的函数，每次启动服务器或构建时实时扫描文件系统生成侧边栏。

1. 放置脚本 ​

同样将 generateSidebar.mjs 放入 docs/.vitepress/utils/ 目录。

2. 修改 package.json ​

简化脚本命令，不再需要 gen:sidebar，所以将 package.json 中的 scripts 恢复如下：

"scripts": {
  "docs:dev": "vitepress dev docs",
  "docs:build": "vitepress build docs"
}

3. 修改 config.mts ​

导入 generateSidebar 函数并调用：

ts
import { defineConfig } from 'vitepress';
import { generateSidebar } from './utils/generateSidebar.mjs';

export default defineConfig({
  // ... 其他配置
  themeConfig: {
    sidebar: generateSidebar(),   // 动态生成
    // ...
  }
});

4. 运行 ​

直接执行 npm run docs:dev 或 npm run docs:build，侧边栏会在启动时自动生成。

TIP

新增/删除文件夹/文档后，需要重启服务才能更新侧边栏（因为启动时只扫描一次），这是由 createRewrites 机制决定的，无法热更新。

如何切换模式？ ​

从模式一切换到模式二：删除 package.json 中的 gen:sidebar 相关命令，按模式二修改 config.mts 导入方式。

从模式二切换到模式一：按模式一修改 package.json 和 config.mts 导入方式（静态导入 sidebar.mts），并确保先运行 npm run gen:sidebar 生成该文件。

两种模式可以共存于项目中，通过不同的 npm script 名称区分（例如 docs:dev:static 和 docs:dev:dynamic），但通常只选用一种。

附录：generateSidebar.mjs 脚本内容 ​

将以下脚本完整复制到 docs/.vitepress/utils/generateSidebar.mjs 中，脚本实现了：

  • 扫描 docs/ 下所有 .md 文件；

  • 利用 vitepress-plugin-permalink 生成永久链接映射；

  • 构建树形侧边栏，支持数字前缀去除、自定义折叠深度、标题优先级（frontmatter.title > 文件名去除序号 > H1）；

  • 支持双模式：直接运行生成静态文件，或导出函数供动态调用。

脚本内容太长了，这里就不贴了，从仓库去下载就行。

优先级title → 文件名 → H1（H1永远不可能出现，只是作为无用的备选）.

常见问题 ​

Q1：新增文档后侧边栏不出现？ ​

模式一： 重新运行 npm run gen:sidebar 或 npm run docs:dev（自动生成）。

模式二： 重启 npm run docs:dev（因为启动时只扫描一次）。

Q2：侧边栏链接是 /pages/xxxx 形式，但点击后 404？ ​

确保 config.mts 中配置了 rewrites: createRewrites({ srcDir: 'docs' })。

检查 vitepress-plugin-permalink 是否正确安装并工作。

Q3：脚本报错 Cannot find module？ ​

确认脚本路径与 package.json 中的命令一致。

确认已安装依赖：npm install vitepress-plugin-permalink

Q4：Windows 下路径分隔符导致映射找不到？ ​

脚本中已包含 relPath = relPath.replace(/\\/g, '/')，确保使用正斜杠。