从 VuePress 迁移到 VitePress：侧边栏配置与图片处理改造全指南

前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载本指南以 VitePress 官方迁移文档为主线系统讲解从 VuePress 迁移到 VitePress 时最容易踩坑的两大差异点侧边栏不再从 frontmatter 自动获取以及静态图片不再需要$withBase包裹。读完本文你将掌握 VitePress 的侧边栏手动配置与动态填充方案、base配置对静态资源路径的自动处理原理以及用正则表达式批量迁移图片语法的完整实操流程。迁移背景两者设计理念的差异VuePress 和 VitePress 虽然同源于 Vue 生态的静态站点生成器但在架构设计上有明显区别VuePress 内置了$withBase这类全局辅助函数和基于 frontmatter 的隐式行为而 VitePress 基于 Vite 构建将资源路径处理交给构建工具链强调显式配置优于隐式约定。这种差异直接体现在两个高频迁移问题上侧边栏VuePress 会自动从每篇页面的 frontmatter 中推断侧边栏结构VitePress 默认不这么做需要你在配置文件中手动声明。图片路径VuePress 部署在子路径时需要借助$withBase拼接base前缀VitePress 会根据base配置自动处理静态图片的 URL无需手动拼接。下文将逐一展开并给出可落地的改造方案。配置篇侧边栏的迁移改造差异核心侧边栏不再自动获取这是 VitePress 与 VuePress 最大的行为差异之一侧边栏不再从 frontmatter 中自动获取。在 VuePress 中你习惯在每篇文档的 frontmatter 里声明sidebar主题会自动读取并渲染在 VitePress 中这条隐式链路被移除了。VitePress 的侧边栏结构需要在主题配置的themeConfig.sidebar中统一声明由你完全掌控。这意味着迁移时你需要做两件事删除页面 frontmatter 中对侧边栏结构的依赖结构声明统一迁移到配置文件在.vitepress/config.ts或config.js的themeConfig.sidebar中手动重建侧边栏。手动配置侧边栏的基本形态VitePress 的themeConfig.sidebar支持两种基本形态按路径分组的多侧边栏以及不分组时的单一侧边栏。典型配置如下import { defineConfig } from vitepress export default defineConfig({ themeConfig: { sidebar: { // 匹配 /guide/ 前缀下所有页面 /guide/: [ { text: 入门, collapsed: false, items: [ { text: 快速开始, link: /guide/getting-started }, { text: 从 VuePress 迁移, link: /guide/migration-from-vuepress } ] }, { text: 指南, collapsed: false, items: [ { text: 资源处理, link: /guide/asset-handling }, { text: 路由, link: /guide/routing } ] } ], // 匹配 /reference/ 前缀下所有页面 /reference/: [ { text: 参考, items: [ { text: 站点配置, link: /reference/site-config }, { text: 运行时 API, link: /reference/runtime-api } ] } ] } } })键名是路径前缀必须与页面路径匹配值为分组数组items中的link指向不带动画后缀的页面路径。分组支持collapsed控制默认是否折叠便于组织大型文档。利用 frontmatter 动态填充侧边栏官方迁移文档指出你可以自行阅读 frontmatter 来动态填充侧边栏。这意味着 VitePress 并没有彻底切断 frontmatter 与侧边栏的联系而是把决策权交给了你主题层面默认主题仍会读取页面 frontmatter 中的sidebar字段来决定是否显示侧边栏。相关判断位于 layout.tsfrontmatter.value.sidebar ! false 即当页面 frontmatter 显式声明sidebar: false时该页面不渲染侧边栏否则按themeConfig.sidebar中的配置渲染。这个开关非常适合登录页、落地页等不需要侧边导航的场景。动态填充方案如果你希望像 VuePress 那样从目录结构或 frontmatter 中自动生成侧边栏可以借助 VitePress 的 数据加载Content Loader 能力在配置文件中编写createContentLoader扫描指定目录下所有 Markdown 文件的 frontmatter标题、顺序等动态组装出sidebar数组后写入themeConfig。这样既保留了frontmatter 驱动侧边栏的体验又符合 VitePress 显式配置的架构。::: tip 迁移建议 迁移初期建议直接采用themeConfig.sidebar手动声明的方式结构一目了然、便于排查当站点页面数量庞大、需要按目录自动组织时再升级为 Content Loader 动态生成方案。 :::Markdown 篇图片语法的迁移改造差异核心静态图片自动处理baseVitePress 的 Markdown 文件都会被编译成 Vue 组件并交由 Vite 处理其中的资源引用。因此与 VuePress 不同在使用静态图片时VitePress 会根据配置自动处理这些baseBase URL。换句话说base前缀的拼接不再需要你手动完成。只要你正确配置了base例如站点部署在https://foo.github.io/bar/时设置base: /bar/Markdown 中的绝对路径引用会自动适配。详细机制可参见 资源处理指南。因此现在可以在没有img标签的情况下渲染图像- img :src$withBase(/foo.png) altfoo foo直接使用 Markdown 原生图片语法[](https://link.gitcode.com/i/9e5d5e8d9c525bdb87868fe7ca1d08b0)VitePress 会负责把src处理成正确的最终 URL。上面 diff 中的foo引用的就是public目录下的资源它会按原样复制到构建输出根目录。动态图片仍需withBase::: warning 对于动态图像仍然需要withBase如 Base URL 一节 中所示。 :::所谓动态图像指的是图片的src不是写死在 Markdown 源码里而是来自运行时数据如主题配置、frontmatter 变量、组件 props的情形。典型场景是在自定义主题组件中渲染基于配置的图片路径script setup import { withBase, useData } from vitepress const { theme } useData() /script template img :srcwithBase(theme.logoPath) / /template判断该用哪种语法的简单规则场景写法Markdown 中的静态图片路径写死foo无需withBase组件中基于数据的动态路径withBase(theme.logoPath)必须withBasewithBase的底层实现为什么静态图片不需要withBase、而动态路径必须手动调用从源码可以看清两者的分工。withBase的实现位于 src/client/app/utils.tsexport function withBase(path: string) { return EXTERNAL_URL_RE.test(path) || !path.startsWith(/) ? path : joinPath(runtimeBase(), path) }其逻辑很清晰外部 URL如https://...或相对路径不以/开头原样返回以/开头的内部绝对路径则拼接上runtimeBase()即当前生效的base前缀。runtimeBase()的实现见 utils.ts会优先读取站点配置中的base在相对 base./场景下还会从页面注入的__VP_SITE_ROOT__动态解析。而 Markdown 中的静态图片走的是另一条路构建期由 Vite 处理资源引用自动注入base前缀并输出带哈希的文件名。此外VitePress 的 Markdown 图片插件 image.ts 还会自动为本地图片补充width/height属性以避免布局偏移并支持lazyLoad原生懒加载选项。这就是静态交给构建工具、动态交给withBase的完整分工。用正则表达式批量替换旧语法如果你手头有大量形如img :src$withBase(/foo.png) altfoo的旧代码不必手工逐个修改。官方迁移文档给出了现成的正则img.*withBase\((.*)\).*alt([^]*).*使用该正则匹配并替换为$2即[](https://link.gitcode.com/i/9e5d5e8d9c525bdb87868fe7ca1d08b0)形式即可将 VuePress 的$withBase图片语法一键转换为 VitePress 的原生 Markdown 图片语法查找img.*withBase\((.*)\).*alt([^]*).* 替换为$2以 VSCode / VS Code 兼容编辑器的在文件中替换功能或sed、脚本方式执行即可。批量替换后务必确认两点替换后的src路径在 VitePress 中依旧有效public目录资源用/xxx.png根绝对路径源码目录资源用相对路径遇到动态绑定的图片src来自变量时跳过手动处理保留withBase调用。迁移自检清单完成上述改造后建议按以下清单逐项核对themeConfig.sidebar已声明完整侧边栏结构页面不再依赖 frontmatter 自动推断需要隐藏侧边栏的页面通过 frontmattersidebar: false控制base已在.vitepress/config.ts中正确配置以/开头和结尾Markdown 中所有静态图片已改用[](https://link.gitcode.com/i/9e5d5e8d9c525bdb87868fe7ca1d08b0)语法并批量替换完成主题组件中的动态图片路径均通过withBase()包裹构建后检查输出页面的图片 URL 是否带上了正确的base前缀。总结从 VuePress 迁移到 VitePress本质上是接受一套更显式、更依赖构建工具链的资源与导航管理方式侧边栏从frontmatter 隐式推断变为配置文件显式声明可按需用 Content Loader 动态生成图片路径从运行时$withBase手动拼接变为构建期 Vite 自动处理 仅对动态路径保留withBase。配合官方文档给出的正则表达式你可以在很短时间内完成一次干净的批量迁移。迁移完成后建议通读 资源处理指南、站点配置参考 与 运行时 API 参考进一步掌握base、public目录与withBase的组合用法。赞分享前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载相关推荐Wan2.2-Animate-14B角色动画生成的技术范式重构Wan2.2 Animate 14B角色动画生成的技术范式重构 行业痛点剖析角色动画的最后一公里瓶颈 当前AI视频生成技术面临的核心矛盾在于通用视频模前端文档从 VuePress 迁移到 VitePress侧边栏配置与图片资源处理实战指南从 VuePress 迁移到 VitePress侧边栏配置与图片资源处理实战指南 本文是 VitePress 官方迁移指南俄文与英文版见 docs/ru/前端文档VitePress 从 VuePress 迁移指南配置项与 Markdown 图片处理要点VitePress 从 VuePress 迁移指南配置项与 Markdown 图片处理要点 本文是 VitePress 官方迁移文档的中文深度解读聚焦从 V前端文档上一篇超强Magisk日志分析3步定位Root设备疑难杂症下一篇AI驱动的macOS自动化用Open Interpreter掌控AppleScript创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考