从 VuePress 迁移

如果你有 VuePress 项目，本指南将帮助你迁移到 VitePress。

为什么迁移？

特性	VuePress	VitePress
构建工具	Webpack	Vite
开发启动	较慢（秒级）	极快（毫秒级）
热更新	较慢	即时
Vue 版本	Vue 2	Vue 3
打包体积	较大	更小

主要差异

配置文件

VuePress (config.js)：

module.exports = {
  title: '我的站点',
  description: '站点描述',
  themeConfig: {
    nav: [...],
    sidebar: {...}
  }
}

VitePress (config.mts)：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '我的站点',
  description: '站点描述',
  themeConfig: {
    nav: [...],
    sidebar: {...}
  }
})

目录结构

VuePress：

docs/
├── .vuepress/
│   ├── config.js
│   └── theme/
└── README.md

VitePress：

docs/
├── .vitepress/
│   ├── config.mts
│   └── theme/
└── index.md        # README.md 改为 index.md

迁移步骤

1. 重命名文件

# 重命名配置目录
mv docs/.vuepress docs/.vitepress

# 重命名配置文件
mv docs/.vitepress/config.js docs/.vitepress/config.mts

# 重命名首页
mv docs/README.md docs/index.md

2. 更新配置语法

导航栏

VuePress：

themeConfig: {
  nav: [
    { text: '指南', link: '/guide/' }
  ]
}

VitePress：基本相同，支持更多功能：

themeConfig: {
  nav: [
    { text: '指南', link: '/guide/', activeMatch: '/guide/' }
  ]
}

侧边栏

VuePress：

sidebar: {
  '/guide/': [
    {
      title: '入门',
      collapsable: true,
      children: [
        '/guide/intro',
        '/guide/getting-started'
      ]
    }
  ]
}

VitePress：

sidebar: {
  '/guide/': [
    {
      text: '入门',
      collapsed: true,  // 注意拼写变化
      items: [          // children 改为 items
        { text: '介绍', link: '/guide/intro' },
        { text: '开始', link: '/guide/getting-started' }
      ]
    }
  ]
}

3. 更新主题配置

VuePress：

// .vuepress/theme/index.js
module.exports = {
  extend: '@vuepress/theme-default'
}

VitePress：

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import './style.css'

export default {
  extends: DefaultTheme
}

4. 更新 Markdown 语法

自定义容器

VuePress：

::: tip
提示内容
:::

VitePress：语法相同，但支持更多类型：

::: tip
提示内容
:::

::: info
信息内容
:::

代码块

VitePress 使用 Shiki 进行语法高亮，支持更多语言和主题：

export default defineConfig({
  markdown: {
    theme: 'github-dark',
    lineNumbers: true
  }
})

5. 更新插件

VuePress 插件不兼容 VitePress，需要寻找替代方案：

VuePress 插件	VitePress 替代方案
@vuepress/plugin-back-to-top	内置支持
@vuepress/plugin-search	内置本地搜索
@vuepress/plugin-pwa	vite-plugin-pwa
@vuepress/plugin-google-analytics	直接配置 head

常见问题

找不到模块

VuePress 使用 CommonJS，VitePress 使用 ESM：

// 修改导入方式
import { defineConfig } from 'vitepress'

样式不生效

VitePress 使用 CSS 变量，需要更新样式：

/* VuePress */
.theme-container { ... }

/* VitePress */
:root {
  --vp-c-brand-1: #your-color;
}

组件注册

VuePress：

module.exports = {
  enhanceAppFiles: path.resolve(__dirname, 'enhanceApp.js')
}

VitePress：

export default {
  enhanceApp({ app }) {
    app.component('MyComponent', MyComponent)
  }
}

迁移检查清单

• [ ] 重命名 .vuepress 为 .vitepress
• [ ] 重命名 config.js 为 config.mts
• [ ] 重命名 README.md 为 index.md
• [ ] 更新 themeConfig 配置
• [ ] 更新 sidebar 配置（children → items）
• [ ] 更新主题入口文件
• [ ] 替换不兼容的插件
• [ ] 更新自定义样式
• [ ] 测试所有页面和功能
• [ ] 更新构建脚本

下一步

迁移完成后，建议阅读 配置文件详解 了解 VitePress 的完整配置选项。