花1天时间 vibe coding 了 vite-plugin-vitepress-auto-nav v4 版本

夏同学Xavi
0 阅读6分钟

vite-plugin-vitepress-auto-nav 是一款在 vitepress 项目中自动生成 sidebar 和 nav 两个导航配置的插件，能大幅度减少 vitepress 文档的配置维护成本。

插件之前更多是满足个人的使用需要，对于 vitepress 的国际化、路由重写、动态路由等功能均未支持，上一次更新已经是两年前了。

近期在收到网友“能否支持国际化”的提问后，我终于决定更新 V4 版本，将插件功能尽量完善。

image.png

当然更新 V4 的底气，有很大一部分来自于当下 AI 的火爆以及便利。我使用的是 CaludeCode + GPT-5.4[1m]，通过测试驱动开发的方式进行重构，全程只检查了 AI 在对话窗口中输出的信息，没有 Review 生成的代码，通过让 AI 确保测试用例完整以及 100% 覆盖率来保证质量。

最终效果还不错，我使用的中转站 GPT-5.4，虽然速度还是比较慢，但是 1m 上下文窗口减少了规划每次对话内容的心智负担，而且代码质量也比较高，最重要的是性价比算是很夯了。

欢迎大家试用新版插件，也欢迎提 Issue 或 PR。下面是同样让 AI 生成的 V4 介绍：

V4 主要升级了什么

1. 生成依据改成了 VitePress runtime pages

这是 V4 最核心的变化。

旧版本更偏向直接扫描 Markdown 文件，然后按目录结构推导 nav 和 sidebar。V4 改成基于 VitePress 的 runtime pages，再结合 rewrites、dynamic routes 和 locale 信息去生成结果。

这样做的好处很直接：去掉了 fast-glob 依赖，插件使用的就是 VitePress 实际运行时处理的页面，速度更快、体积更小。

2. 配置项更规范

V4 规范了配置项的命名与语义，让配置项更能见名知意，例如：

  • pattern -> include + exclude
  • indexAsFolderLink -> standaloneIndex
  • itemsSetting -> overrides
  • frontmatterPrefix -> frontmatterKeyPrefix
  • compareFn -> sorter
  • useArticleTitle -> perferArticleTitle
  • title -> displayName
  • hide -> visible
  • sort -> order
  • ...

这些配置既可以写在插件的配置对象里，也可以通过在页面文件中配置 frontmatter 生效。为了避免和现有 frontmatter 字段冲突，可以配置 frontmatterKeyPrefix 把字段改成类似 navDisplayName、navOrder 这种形式。

这次也顺手把开发态相关的问题补了一遍，主要包括：

  • dev.watchDebounceMs：watch 防抖
  • dev.cache：内容缓存
  • dev.logLevel：日志级别控制

这些能力平时不一定会特别在意，但到了排查“为什么没有刷新”“为什么又重算了一次”“到底是哪条路径参与了生成”的时候，会省很多时间。

本次升级还删除了对 gitbook summary 内容的兼容，但已经有了后续的调整方向：

image.png

V4 在架构上具体改了什么

如果只看使用方式，V4 像是一版功能升级；如果看代码，其实更像一次完整重构。

旧版本的主流程比较集中。功能少的时候没问题，功能一多，页面解析、配置处理、目录构建和输出合并就容易缠在一起。后面再补新场景，代码会越来越重。

V4 这次把核心流程拆成了几块职责明确的模块，大致是这样一条链路：

  1. 归一化用户配置
  2. 解析 VitePress 运行时页面来源
  3. 读取 frontmatter 和 H1 元数据
  4. 构建 locale 维度的目录树
  5. 生成 nav
  6. 生成 sidebar
  7. 合并回 themeConfig
  8. 在开发态 watch 中按需重算

对应到实现上，核心模块主要有：

  • normalizeOptions
  • pageSource
  • contentMeta
  • treeBuilder
  • navBuilder
  • sidebarBuilder
  • merger
  • watcher
  • cache

这样拆完以后，几个好处比较明显。

第一，页面来源、内容元数据、导航构建和配置合并各自独立，后面加功能不用总是牵一大片。

第二，路由处理终于和磁盘扫描解绑了。rewrites、动态路由、多语言这些场景不需要再靠零散补丁去兜。

第三，测试可以更扎实地补齐。V4 这次除了单元测试，也补了比较多集成场景，像动态路由、rewrites、i18n、index.md 处理、隐藏页面但仍参与构建这些情况，现在都有对应 example 和测试覆盖。

对外看是一个插件，对内其实已经不是过去那种“能跑就行”的结构了。

从 V3 迁移到 V4

V4 不是一版无感升级。

如果项目之前已经接了 V3，升级时需要处理一轮配置迁移。好在这次改动虽然不小，但迁移规则是清楚的。

一、手动迁移

先升级依赖：

npm install -D vite-plugin-vitepress-auto-nav@latest
# 或
pnpm add -D vite-plugin-vitepress-auto-nav@latest
# 或
yarn add -D vite-plugin-vitepress-auto-nav@latest

然后按下面的规则调整配置。

1. 顶层配置重命名

pattern -> include
itemsSetting -> overrides
frontmatterPrefix -> frontmatterKeyPrefix
compareFn -> sorter
useArticleTitle -> preferArticleTitle

2. 条目配置 / frontmatter 字段重命名

title -> displayName
sort -> order
useArticleTitle -> preferArticleTitle

3. 这两个布尔值要做语义反转

indexAsFolderLink -> standaloneIndex
standaloneIndex = !indexAsFolderLink

hide -> visible
visible = !hide

这里最好多看一眼。V4 不只是换了字段名，其中两个布尔值的语义是反过来的，不能机械替换。

4. 可以顺手补上的新配置

如果项目里有需要，这次也可以一起补上：

  • exclude
  • dev.watchDebounceMs
  • dev.cache
  • dev.logLevel

5. 迁移后建议重点检查这些场景

如果你的项目里有下面这些情况，升级完最好手动看一遍最终结果：

  • 使用了 rewrites
  • 使用了动态路由
  • 有多语言目录

V4 对这些场景都做了处理，但也正因为如此，迁移后值得花几分钟确认一下输出是否符合预期。

AI 迁移怎么用

这次 README 里我直接放了一段给 AI 用的迁移提示词。原因也很简单：有些项目的 .vitepress/config.ts 已经不短了，这种重复替换没必要全靠手工做。

如果你的项目不依赖 summary，AI 迁移是可以直接用的，提示词为：

请把这个项目从 vite-plugin-vitepress-auto-nav v3 迁移到最新版本。

先升级依赖：
- npm：`npm install -D vite-plugin-vitepress-auto-nav@latest`
- pnpm：`pnpm add -D vite-plugin-vitepress-auto-nav@latest`
- yarn：`yarn add -D vite-plugin-vitepress-auto-nav@latest`

然后按以下规则迁移配置：

顶层配置重命名如下：
- `pattern` -> `include`
- `itemsSetting` -> `overrides`
- `frontmatterPrefix` -> `frontmatterKeyPrefix`
- `compareFn` -> `sorter`
- `useArticleTitle` -> `preferArticleTitle`

条目配置 / frontmatter 字段重命名如下：
- `title` -> `displayName`
- `sort` -> `order`
- `useArticleTitle` -> `preferArticleTitle`

以下布尔值需要反转语义：
- `indexAsFolderLink` -> `standaloneIndex`，转换公式为 `standaloneIndex = !indexAsFolderLink`
- `hide` -> `visible`，转换公式为 `visible = !hide`

如有需要，可以补充这些新配置：
- `exclude`
- `dev.watchDebounceMs`
- `dev.cache`
- `dev.logLevel`

关于 summary 的重要规则：
- 如果现有配置中包含 `summary` 参数、`SUMMARY.md` 工作流，或任何基于 summary 的生成逻辑，请立即中断迁移，并明确告知：最新版本已经停止支持 summary 生成链路。

迁移规则：
1. 直接替换已重命名的字段。
2. 按上述公式处理语义反转的布尔值。
3. 与插件无关的 VitePress 配置保持不变。

输出要求：
- 只返回迁移后的配置代码。
- 尽量保留原有注释。
- 如果检测到 summary 相关配置，不要输出迁移后的代码，而是简短说明 summary 已停止支持，并要求用户补充页面结构或内容组织规则后再继续。

不过这里还是要提醒一句：AI 迁移适合处理配置替换，不适合替你决定内容组织方式。

如果项目里已经把目录结构、页面入口和导航策略写得很有历史包袱，那 AI 最多帮你完成第一步，后面的取舍还是得自己看。

avatar
文章
阅读
粉丝