- 前端
- 文档
【免费下载链接】vitepress
Vite & Vue powered static site generator.
本指南以 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.ts：frontmatter.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 篇：图片语法的迁移改造
差异核心：静态图片自动处理base
VitePress 的 Markdown 文件都会被编译成 Vue 组件，并交由 Vite 处理其中的资源引用。因此：
与 VuePress 不同，在使用静态图片时，VitePress 会根据配置自动处理这些
base（Base URL）。
换句话说，base前缀的拼接不再需要你手动完成。只要你正确配置了base（例如站点部署在https://foo.github.io/bar/时设置base: '/bar/'），Markdown 中的绝对路径引用会自动适配。详细机制可参见 资源处理指南。
因此，现在可以在没有img标签的情况下渲染图像：
- <img :src="$withBase('/foo.png')" alt="foo"> + 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 :src="withBase(theme.logoPath)" /> </template>判断"该用哪种语法"的简单规则：
| 场景 | 写法 |
|---|---|
| Markdown 中的静态图片（路径写死） | foo，无需withBase |
| 组件中基于数据的动态路径 | withBase(theme.logoPath)，必须withBase |
withBase的底层实现
为什么静态图片不需要withBase、而动态路径必须手动调用？从源码可以看清两者的分工。withBase的实现位于 src/client/app/utils.ts：
export 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')" alt="foo">的旧代码，不必手工逐个修改。官方迁移文档给出了现成的正则：
<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 自动推断；- 需要隐藏侧边栏的页面通过 frontmatter
sidebar: 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的组合用法。
- 前端
- 文档
【免费下载链接】vitepress
Vite & Vue powered static site generator.
相关推荐
Wan2.2-Animate-14B：角色动画生成的技术范式重构
Wan2.2 Animate 14B：角色动画生成的技术范式重构 行业痛点剖析：角色动画的"最后一公里"瓶颈 当前AI视频生成技术面临的核心矛盾在于：通用视频模
前端文档从 VuePress 迁移到 VitePress：侧边栏配置与图片资源处理实战指南
从 VuePress 迁移到 VitePress：侧边栏配置与图片资源处理实战指南 本文是 VitePress 官方迁移指南（俄文与英文版，见 docs/ru/
前端文档VitePress 从 VuePress 迁移指南：配置项与 Markdown 图片处理要点
VitePress 从 VuePress 迁移指南：配置项与 Markdown 图片处理要点 本文是 VitePress 官方迁移文档的中文深度解读，聚焦从 V
前端文档
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
