VitePress 升级到最新版本

当前官方包：vitepress，配套 @vitepress/theme 已经内置在 vitepress 包里，不再需要单独安装。

1. 先看当前版本

npm list vitepress
# 或者
npx vitepress --version

2. npm 升级

npm

# 升级到最新稳定版
npm install vitepress@latest

升级到最新测试版

# 升级到最新测试版
# 比如当前最新测试版是2.0.0-alpha.20
# 最新测试版本号，可以在github或官网查到
npm install vitepress@2.0.0-alpha.20

pnpm（推荐vitepress项目用pnpm）

pnpm up vitepress --latest

yarn

yarn upgrade vitepress@latest

3. 升级后重要操作

# 删除缓存、lock、node_modules
rm -rf node_modules
rm -f package-lock.json # or pnpm-lock.yaml / yarn.lock

# 重新安装依赖
npm install

4. 破坏性变更检查（重点）

大版本跨版本升级经常会踩坑：

1. config 配置文件 旧版：.vitepress/config.ts 新版仍然兼容，但部分配置项废弃：

• 侧边栏、导航栏配置参数
• themeConfig 的部分字段（搜索、socialLinks、footer等）

打开运行，控制台看警告，废弃字段会提示替换成什么。

2. 主题

⚠️ 新版本 @vitepress/theme 不需要手动安装，它是 vitepress 的内置依赖。 不要写 import DefaultTheme from '@vitepress/theme' 安装语句，会报重复依赖。 正确写法：

import { DefaultTheme } from 'vitepress/theme'

3. 首页 Hero、Feature 类型 部分字段改名，例如 image 类型 ThemeableImage 行为微调，旧的首页 yaml 如果报错对照官方文档修正。

4. 搜索相关 本地搜索 localSearch 配置在新版有改动；如果你用 Pagefind / Algolia，升级后要校验搜索组件。

5. 验证是否升级成功

npx vitepress --version

输出版本号即为最新。再跑本地服务：

npm run docs:dev

6. 如果升级完出现奇怪报错

• 检查 import 是否还在引用 @vitepress/theme 包（删掉这个包的安装）
• ts 类型报错：重启 VSCode TS服务
• markdown 模块 MIME 报错：清空浏览器缓存，删除 .vitepress/cache 文件夹

---

package.json 参考脚本示例

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}