VitePress 版本升级指南

VitePress 大版本升级时的 Breaking Changes 专题和迁移策略，帮助你安全地升级项目。

升级前的准备

1. 查看更新日志

# 查看 VitePress 版本
npx vitepress --version

# 查看可用版本
npm view vitepress versions

# 查看 CHANGELOG
npx vitepress changelog

2. 备份项目

# 创建备份分支
git checkout -b backup-before-upgrade
git push origin backup-before-upgrade

# 切回主分支继续操作
git checkout main

3. 创建测试分支

git checkout -b upgrade-vitepress

升级流程

推荐步骤

graph TD
    A[查看 CHANGELOG] --> B[创建测试分支]
    B --> C[升级依赖版本]
    C --> D[处理 Breaking Changes]
    D --> E[运行构建测试]
    E --> F{构建是否通过?}
    F -->|是| G[功能回归测试]
    F -->|否| D
    G --> H{功能是否正常?}
    H -->|是| I[合并到主分支]
    H -->|否| D

升级命令

# 升级到最新版
npm install vitepress@latest -D

# 升级到指定大版本
npm install vitepress@^2.0.0 -D

# 同时升级相关依赖
npm install vue@latest @vite-pwa/vitepress@latest -D

v1 → v2 Breaking Changes

配置文件变更

defineConfig 导入路径

// v1
import { defineConfig } from 'vitepress'

// v2（不变，但类型更严格）
import { defineConfig } from 'vitepress'

侧边栏配置

// v1
sidebar: {
  '/guide/': [
    {
      text: '入门',
      children: [  // v1 使用 children
        { text: '介绍', link: '/guide/intro' }
      ]
    }
  ]
}

// v2
sidebar: {
  '/guide/': [
    {
      text: '入门',
      items: [  // v2 使用 items
        { text: '介绍', link: '/guide/intro' }
      ]
    }
  ]
}

collapsable → collapsed

// v1
{ text: '入门', collapsable: true }

// v2
{ text: '入门', collapsed: true }

主题配置变更

搜索配置

// v1
themeConfig: {
  algolia: {
    apiKey: '...',
    indexName: '...'
  }
}

// v2
themeConfig: {
  search: {
    provider: 'algolia',
    options: {
      apiKey: '...',
      indexName: '...'
    }
  }
}

编辑链接

// v1
themeConfig: {
  editLinks: true,
  editLinkText: '编辑此页',
  repo: 'user/repo'
}

// v2
themeConfig: {
  editLink: {
    pattern: 'https://github.com/user/repo/edit/main/docs/:path',
    text: '编辑此页'
  }
}

Markdown 配置变更

语法高亮

// v1
markdown: {
  lineNumbers: true
}

// v2
markdown: {
  lineNumbers: true  // 不变，但支持更多配置
}

运行时 API 变更

useData 返回值

// v1
const { site, page, theme, frontmatter } = useData()

// v2（返回值结构更丰富）
const { site, page, theme, frontmatter, lang, localePath } = useData()

withBase

// v1 - 从 vitepress 导入
import { withBase } from 'vitepress'

// v2 - 不变
import { withBase } from 'vitepress'

已废弃的 API

v1 API	v2 替代	说明
themeConfig.algolia	themeConfig.search	搜索配置统一
themeConfig.editLinks	themeConfig.editLink	编辑链接配置
themeConfig.repo	themeConfig.editLink.pattern	仓库信息合并到编辑链接
sidebar.children	sidebar.items	侧边栏子项命名
collapsable	collapsed	拼写修正
themeConfig.nav 简单格式	对象格式	导航项统一为对象

升级检查清单

必须修改

• [ ] sidebar.children → sidebar.items
• [ ] collapsable → collapsed
• [ ] themeConfig.algolia → themeConfig.search
• [ ] themeConfig.editLinks → themeConfig.editLink
• [ ] 检查所有已废弃 API 是否已替换

建议修改

• [ ] 搜索配置使用 provider 语法
• [ ] 编辑链接使用 pattern 语法
• [ ] 导航项统一为对象格式
• [ ] 利用新增的 localePath 等运行时 API

验证测试

• [ ] npm run dev 开发服务器正常启动
• [ ] npm run build 构建成功
• [ ] 所有页面路由正常访问
• [ ] 侧边栏和导航栏显示正确
• [ ] 搜索功能正常
• [ ] 亮色/暗色模式切换正常
• [ ] 移动端响应式正常

回滚策略

如果升级后遇到无法解决的问题：

# 方案一：回退版本
npm install vitepress@1.x -D

# 方案二：回退 Git 分支
git checkout main
git branch -D upgrade-vitepress

# 方案三：使用备份分支
git checkout backup-before-upgrade

渐进式升级

对于大型项目，建议渐进式升级：

1. 先升级 Patch 版本

npm install vitepress@~1.x -D

2. 再升级 Minor 版本

npm install vitepress@^1.x -D

3. 最后升级 Major 版本

npm install vitepress@^2.0.0 -D

常见升级问题

构建报错：模块找不到

# 清除缓存重装
rm -rf node_modules package-lock.json
npm install

样式丢失

v2 可能调整了部分 CSS 变量名，检查自定义样式：

/* 检查是否有使用已废弃的变量 */
/* v1 */ --vp-c-brand
/* v2 */ --vp-c-brand-1

插件不兼容

# 检查插件兼容版本
npm view vitepress-plugin-mermaid peerDependencies

# 升级所有相关插件
npm install vitepress-plugin-mermaid@latest -D

相关资源

• VitePress 更新日志
• 从 VuePress 迁移
• 迁移专题指南
• VitePress 官方 CHANGELOG