VitePress 2.0 新特性专题

VitePress 2.0 是一个重要的里程碑版本，基于 Vite 6/7，带来了大量新功能、性能优化和 Breaking Changes。本专题将逐一深入每个特性，提供完整的配置示例和迁移指导。

版本概览

版本	发布时间	主要变化
2.0.0-alpha.1	2025-01-22	升级到 Vite 6
2.0.0-alpha.3	2025-02-24	Shiki v3、markdown-it-async、动态路由重构
2.0.0-alpha.5	2025-04-21	分布式配置、`useLayout`、`isHome`、Lean Chunks
2.0.0-alpha.7	2025-06-24	升级到 Vite 7、`router.replace`
2.0.0-alpha.9	2025-07-26	DocSearch v4
2.0.0-alpha.12	2025-08-20	CJK 友好 Markdown、postcssIsolateStyles 更新
2.0.0-alpha.13	2025-11-13	代码块自定义显示名、Git 时间戳优化、Nav 函数
2.0.0-alpha.16	2026-01-31	`@layer` 样式隔离、DocSearch v4.5 侧边栏
2.0.0-alpha.17	2026-03-19	text-autospace、文本片段、Hero 插槽增强

版本说明

本项目当前使用 vitepress@2.0.0-alpha.17，本文档介绍 2.0 系列的重要特性。

核心升级

1. Vite 6/7 支持

VitePress 2.0 基于 Vite 6/7，带来显著的性能提升：

指标	VitePress 1.x	VitePress 2.0	提升
冷启动	~1.2s	~0.4s	3x
热更新	~150ms	~50ms	3x
构建时间	~45s	~15s	3x

// config.mts — Vite 7 新特性全部可用
export default defineConfig({
  vite: {
    // 使用 Rolldown 构建（实验性）
    // builder: 'rolldown'
  }
})

Rolldown 支持

VitePress 2.0 已对 rolldown-vite 做了适配（alpha.6 起支持 oxc-minify、preserveEntrySignatures 等），但 rolldown-vite 仍处于早期阶段，生产环境请谨慎使用。

2. Shiki v3 升级

语法高亮引擎升级到 Shiki v3（alpha.3）：

更快的加载：语言延迟加载（1.4.x 已引入，v3 进一步优化）
更好的性能：优化的高亮算法
新特性：Twoslash 支持、v3 匹配算法
破坏性变更：shikijiSetup 重命名为 shikiSetup

export default defineConfig({
  markdown: {
    theme: {
      light: 'github-light',
      dark: 'github-dark'
    },
    // Twoslash 支持（类型悬停）
    codeTransformers: [
      // 添加 Twoslash transformer
    ]
  }
})

3. markdown-it-async

VitePress 2.0 使用 markdown-it-async 替代 markdown-it（alpha.3），移除了 synckit 依赖：

// ✅ 新写法：使用 renderAsync
const html = await md.renderAsync(content)

// ❌ 旧写法：不再支持（自定义本地搜索渲染器需迁移）
const html = md.render(content)

迁移提示

如果你在自定义本地搜索中使用了 md.render，需要改为 await md.renderAsync。对于大多数用户无需修改。

Markdown 增强

1. CJK 友好支持

VitePress 2.0 内置 markdown-it-cjk-friendly（alpha.12），优化中文排版：

export default defineConfig({
  markdown: {
    // 默认开启，可关闭
    cjkFriendlyEmphasis: true  // 注意：alpha.12 曾叫 cjkFriendly，alpha.13 重命名
  }
})

改进效果：

markdown

<!-- 旧版：以下强调语法无法正确渲染 -->
**中文**加粗**有问题**

<!-- 新版：正确处理中文强调语法 -->
**中文**加粗**没问题**

Breaking Change

此功能故意偏离了 CommonMark 规范，以更好地服务 CJK 用户。如果你之前使用了修补 scanDelims 的 hack 方案，现在可以移除了。

2. 数学公式支持

内置 MathJax 支持，无需额外配置：

markdown

行内公式：$E = mc^2$

块级公式：
$$
\frac{\partial f}{\partial x} = \lim_{\Delta x \to 0} \frac{f(x + \Delta x) - f(x)}{\Delta x}
$$

3. 代码块增强

自定义显示名（alpha.13）

支持为代码块指定自定义标签名：

markdown

```ts [config.mts]
export default defineConfig({})
```

代码组

markdown

::: code-group
```npm [npm]
npm install vitepress
```

```yarn [yarn]
yarn add vitepress
```

```pnpm [pnpm]
pnpm add vitepress
```
:::

区域引入

markdown

<!-- 从文件引入特定区域 -->
<<< @/snippets/snippet.md{1-5}
<<< @/snippets/snippet.md#region-name

<!-- 支持匹配无标签的区域结束（alpha.4） -->
<<< @/snippets/snippet.md#region-start

语言别名

export default defineConfig({
  markdown: {
    languageAlias: {
      env: 'ini',
      npm: 'bash',
      yarn: 'bash',
      pnpm: 'bash'
    }
  }
})

Shell 代码 `$` 符号不可选（alpha.14）

Shell 代码块中的 $ 提示符不再被选中，方便用户复制命令：

shell

npm install vitepress
# 用户复制时只复制 "npm install vitepress"，不会包含 "$"

4. GitHub 风格警告

支持 GitHub 风格的警告语法：

markdown

> [!NOTE]
> 这是一个提示

> [!WARNING]
> 这是一个警告

> [!TIP]
> 这是一个建议

> [!IMPORTANT]
> 这是一个重要说明

5. 代码块行操作

行号自定义：支持指定起始行号
行高亮：{1-3,5}
差异显示：// [!code --] 和 // [!code ++]
焦点高亮：// [!code focus]
错误/警告：// [!code error] 和 // [!code warning]
高亮：// [!code highlight]

markdown

```js:line-numbers {1-2} /hello/
function hello() {  
  console.log('hello')  
  return true
}
```

搜索增强

1. 本地搜索优化

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        miniSearch: {
          searchOptions: {
            fuzzy: 0.2,
            prefix: true,
            boost: { title: 4, text: 2, titles: 1 }
          }
        },
        transformItems(items) {
          return items.map(item => ({
            ...item,
            excerpt: item.excerpt?.slice(0, 200)
          }))
        }
      }
    }
  }
})

2. DocSearch v4/v4.5

Algolia DocSearch 升级到 v4（alpha.9），v4.5（alpha.16）新增侧边栏面板：

侧边栏面板：新的搜索 UI，搜索结果在侧边栏展示
AI 功能：支持 AI 搜索（需申请内测）
更好的键盘导航
确定性搜索索引（alpha.17 修复了索引顺序不确定的问题）

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'YOUR_INDEX_NAME'
      }
    }
  }
})

Breaking Change

升级到 DocSearch v4 后，如果你自定义了搜索按钮或模态框的样式，可能需要调整。AI 功能需在申请页面单独申请。

主题定制增强

1. CSS 变量系统

新增更多层级的颜色变量：

css

:root {
  /* 品牌色（3 级） */
  --vp-c-brand-1: #6366f1;
  --vp-c-brand-2: #4f46e5;
  --vp-c-brand-3: #4338ca;
  --vp-c-brand-soft: rgba(99, 102, 241, 0.14);

  /* 字体变量 */
  --vp-font-family-base: 'Inter', -apple-system, sans-serif;
  --vp-font-family-mono: 'JetBrains Mono', monospace;

  /* 布局变量 */
  --vp-layout-max-width: 1440px;
  --vp-nav-height: 64px;
  --vp-sidebar-width: 272px;
}

2. `@layer` 样式隔离（alpha.16）

默认主题的 base.css 样式现在使用 @layer __vitepress_base 包裹，提高样式优先级的可预测性：

css

/* VitePress 内部实现 */
@layer __vitepress_base {
  /* 基础样式 */
}

好处：

自定义样式不再需要 !important 即可覆盖默认主题样式
样式层叠顺序更加清晰可控

3. 新布局插槽

vue

<template>
  <Layout>
    <!-- 首页插槽 -->
    <template #home-hero-before>...</template>
    <template #home-hero-after>...</template>
    <template #home-hero-actions-before-actions>...</template>  <!-- alpha.17 新增 -->
    <template #home-features-before>...</template>
    <template #home-features-after>...</template>

    <!-- 文档插槽 -->
    <template #doc-top>...</template>
    <template #doc-bottom>...</template>
    <template #doc-before>...</template>
    <template #doc-after>...</template>

    <!-- 侧边栏插槽 -->
    <template #sidebar-nav-before>...</template>
    <template #sidebar-nav-after>...</template>
  </Layout>
</template>

4. 首页配置增强

`isHome` frontmatter（alpha.5）

显式标记首页，避免路由匹配歧义：

yaml

---
layout: home
isHome: true  # 新增：显式标记首页
---

Features 支持 details 列表（alpha.17）

首页 features 区域现在支持展开详情列表：

yaml

features:
  - icon: 🚀
    title: 极速冷启动
    details: 服务启动极快，热更新毫秒级响应
    link: /guide/getting-started
    linkText: 了解更多
  - icon: 📦
    title: 优化的构建
    details: 自动代码分割、预加载优化
    # 支持 details 列表
    items:
      - 代码分割
      - Tree Shaking
      - 预加载优化

路由与导航

1. 路由重写

export default defineConfig({
  rewrites: {
    'docs/:path': ':path',
    'en/:path': ':path'
  }
})

2. 路由器增强

import { useRoute, useRouter } from 'vitepress'

const router = useRouter()

// 新增：replace 选项（alpha.7）
router.go('/new-path', { replace: true })

const route = useRoute()
// 新增：hash 和 query 属性
console.log(route.hash)    // #section
console.log(route.query)   // { foo: 'bar' }

3. 导航增强

函数形式（alpha.13）

导航链接的 text 支持函数形式，实现动态文案：

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: () => isProd ? 'Production' : 'Development',
        link: '/'
      }
    ]
  }
})

组件插槽

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: '更多',
        items: [
          { component: 'MyCustomNavItem' }
        ]
      }
    ]
  }
})

4. 文本片段导航（alpha.17）

支持 Text Fragments 协议，可以直接链接到页面中的特定文本：

markdown

[跳转到特定文本](/guide/installation#:~:text=npm%20install%20vitepress)

浏览器会自动滚动到并高亮目标文本，无需手动添加锚点。

多语言支持

1. 语言菜单 SEO 增强（alpha.17）

语言切换菜单自动添加 rel="alternate" 和 hreflang 属性，改善多语言 SEO：

export default defineConfig({
  locales: {
    '/': { lang: 'zh-CN', label: '简体中文' },
    '/en/': { lang: 'en-US', label: 'English' },
    '/ja/': { lang: 'ja-JP', label: '日本語' }
  }
})

生成的 HTML 链接会自动包含：

html

<a rel="alternate" hreflang="en-US" href="/en/guide">English</a>

2. 文本自动间距（alpha.17）

针对 CJK 语言自动优化文本间距，启用 CSS text-autospace 和 text-spacing-trim：

css

/* VitePress 2.0 自动应用 */
.vp-doc p {
  text-autospace: ideograph-alpha;      /* 中英文之间自动加空格 */
  text-spacing-trim: trim-auto;         /* 中文标点间距优化 */
}

注意

alpha.17 修复了 \n\n 中不应启用 text-autospace 的问题。如果你的内容在换行处出现异常间距，请升级到最新版本。

配置系统

1. 分布式配置文件（alpha.5）

支持将配置拆分到多个文件，VitePress 会自动合并：

.vitepress/
├── config.mts              # 主配置
├── config/                 # 分布式配置（自动加载）
│   ├── nav.mts             # 导航配置
│   ├── sidebar.mts         # 侧边栏配置
│   └── head.mts            # Head 标签配置
└── theme/

// .vitepress/config/nav.mts
import { NavItem } from 'vitepress'

export const nav: NavItem[] = [
  { text: '指南', link: '/guide/' }
]

使用场景

大型项目的配置拆分管理
团队协作时减少配置冲突
按功能模块独立维护配置

2. `markdown.config` 支持异步（alpha.2）

export default defineConfig({
  markdown: {
    // 现在支持异步函数
    config: async (md) => {
      const plugin = await import('some-markdown-plugin')
      md.use(plugin.default)
    }
  }
})

性能优化

1. 构建优化

优化项	说明	引入版本
Lean Chunks	优化静态内容提取，减小 JS 包体积	alpha.5
并发渲染	并行处理页面，加速构建	1.0
Git 时间戳单次调用	一次 `git log` 获取所有文件时间戳（alpha.13），避免逐文件调用	alpha.13
Oxc Minify	rolldown-vite 下使用 oxc-minify 替代 esbuild	alpha.6

2. 运行时优化

更小的包体积：核心代码减少 20%
更快的页面加载：优化首屏渲染
更好的 Tree-shaking：未使用的代码自动移除
社交图标按需加载（1.5）：不再内置所有图标，按需引入

3. 按需加载

语言延迟加载：Shiki 语言包按需加载
字体优化：Inter 字体按需加载

组合式 API 变更

useLayout 替代 useLocalNav / useSidebar（alpha.5）

// ❌ 旧 API（已移除）
import { useLocalNav, useSidebar } from 'vitepress'
const { hasSidebar } = useSidebar()
const { hasLocalNav } = useLocalNav()

// ✅ 新 API
import { useLayout } from 'vitepress'
const { sidebar, localNav } = useLayout()

Breaking Change

useLocalNav 和 useSidebar 已移除，直接替换为 useLayout。DefaultTheme.DocSidebar 和 DefaultTheme.DocLocalNav 类型也已移除。侧边栏控制不再导出，如有需求可提交 issue。

其他 API 变更

import { useData, useRoute, useRouter } from 'vitepress'

// useData
const { page, frontmatter, isDark } = useData()

// useRoute — 新增 hash 和 query
const route = useRoute()
console.log(route.hash)    // #section
console.log(route.query)   // { foo: 'bar' }

// useRouter — 新增 replace 选项
const router = useRouter()
router.go('/path', { replace: true })

// 新增：cacheAllGitTimestamps 和 getGitTimestamp 导出（alpha.13）
import { cacheAllGitTimestamps, getGitTimestamp } from 'vitepress'

postcssIsolateStyles 更新（alpha.12）

用于样式隔离的 postcssIsolateStyles 工具有重大变更：

变更项	旧版	新版（alpha.12+）
`includeFiles` 默认值	`[/base\.css/]`	`[/vp-doc\.css/, /base\.css/]`
`transform` 选项	支持	已移除
`exclude` 选项	支持	已移除
幂等性	非幂等	幂等（可多次调用）

// 如果你之前只为了 vp-doc.css 设置 includeFiles，现在可以移除了
postcssIsolateStyles({
  // 不再需要：includeFiles: [/vp-doc\.css/]
  // 默认已包含 vp-doc.css 和 base.css
})

// 如需回退旧行为
postcssIsolateStyles({
  includeFiles: [/base\.css/]
})

高级用例

如果你需要更复杂的隔离逻辑，请直接使用 postcss-prefix-selector。

动态路由重构（alpha.3）

动态路由插件进行了重大重构：

支持在开发模式下即时重新生成动态路由
HMR 对监听文件（watchedFiles）的变更实时响应
修复了多个 HMR 相关 bug

// 动态路由配置保持不变
export default {
  async paths() {
    return [
      { params: { id: '1' } },
      { params: { id: '2' } }
    ]
  }
}

其他改进

1. `<<<` 代码引入错误不再静默忽略（alpha.17）

之前如果引入的文件不存在，<<< 语法会静默忽略。现在会报错：

markdown

<!-- 如果文件不存在，构建时会报错 -->
<<< @/snippets/non-existent.md

处理方式

如果你需要引用可能不存在的文件（例如文档 <<< 语法本身），可以使用 markdown.codeTransformers 的 postprocess 钩子处理。参见 VitePress 官方仓库的 docs/.vitepress/config.ts 示例。

2. 代码组标签切换事件（alpha.14）

当代码组标签切换时，会触发 vitepress:codeGroupTabActivate 自定义事件：

// 监听代码组切换
window.addEventListener('vitepress:codeGroupTabActivate', (e) => {
  console.log('Tab activated:', e.detail)
})

3. `markdown-it-attrs` 对代码块禁用（alpha.13）

markdown-it-attrs 插件对 fenced code blocks 不再生效。如需为代码块添加类名，请使用 Shiki transformers 替代。

完整 Breaking Changes 汇总

变更	引入版本	影响	迁移方式
`markdown.lineNumbers` → `markdown.code.lineNumbers`	alpha.1	配置	移动配置路径
`markdown-it-async` 替代 `markdown-it`	alpha.3	自定义搜索渲染器	`md.render` → `await md.renderAsync`
`useLocalNav` / `useSidebar` → `useLayout`	alpha.5	自定义主题	查找替换导入
`vp-code` 类名移除	alpha.5	自定义主题样式	使用 `.shiki` 或 `pre.shiki` 选择器
`vp-adaptive-theme` 逻辑变更	alpha.5	单主题样式	使用 `.shiki:not(.shiki-themes)` 选择器
`markdown-it-attrs` 代码块禁用	alpha.13	代码块类名	使用 Shiki transformers
`cjkFriendly` → `cjkFriendlyEmphasis`	alpha.13	配置	重命名配置项
`postcssIsolateStyles` 变更	alpha.12	自定义样式隔离	移除 `transform`/`exclude`，调整 `includeFiles`
`<<<` 引入错误不再静默	alpha.17	文档内容	修复不存在的文件引用
DocSearch v4	alpha.9	自定义搜索样式	调整搜索按钮/模态框样式

升级指南

1. 更新依赖

bash

# 更新 VitePress
npm install vitepress@latest

# 清除缓存
rm -rf node_modules/.vite docs/.vitepress/cache

2. 检查配置

// ❌ 旧配置
export default defineConfig({
  markdown: { lineNumbers: true }
})

// ✅ 新配置
export default defineConfig({
  markdown: {
    code: { lineNumbers: true }
  }
})

3. 更新主题

// ❌ 旧 API
import { useSidebar, useLocalNav } from 'vitepress'

// ✅ 新 API
import { useLayout } from 'vitepress'

css

/* ❌ 旧选择器 */
.vp-code { ... }
.vp-adaptive-theme { ... }

/* ✅ 新选择器 */
.shiki { ... }
.shiki:not(.shiki-themes) { ... }

4. 更新自定义搜索渲染器

// ❌ 旧写法
const html = md.render(content)

// ✅ 新写法
const html = await md.renderAsync(content)

5. 验证构建

bash

# 清除缓存后构建
rm -rf docs/.vitepress/cache
npm run build

# 检查是否有以下报错：
# - <<< 引入不存在的文件
# - markdown-it-attrs 在代码块上的使用
# - useLocalNav / useSidebar 导入错误

下一步

查看安装与环境配置开始使用 VitePress
了解版本升级指南安全升级现有项目
学习性能优化提升站点性能

VitePress 2.0 新特性专题 ​

版本概览 ​

核心升级 ​

1. Vite 6/7 支持 ​

2. Shiki v3 升级 ​

3. markdown-it-async ​

Markdown 增强 ​

1. CJK 友好支持 ​

2. 数学公式支持 ​

3. 代码块增强 ​

自定义显示名（alpha.13） ​

代码组 ​

区域引入 ​

语言别名 ​

Shell 代码 $ 符号不可选（alpha.14） ​

4. GitHub 风格警告 ​

5. 代码块行操作 ​

搜索增强 ​

1. 本地搜索优化 ​

2. DocSearch v4/v4.5 ​

主题定制增强 ​

1. CSS 变量系统 ​

2. @layer 样式隔离（alpha.16） ​

3. 新布局插槽 ​

4. 首页配置增强 ​

isHome frontmatter（alpha.5） ​

Features 支持 details 列表（alpha.17） ​

路由与导航 ​

1. 路由重写 ​

2. 路由器增强 ​

3. 导航增强 ​

函数形式（alpha.13） ​

组件插槽 ​

4. 文本片段导航（alpha.17） ​

多语言支持 ​

1. 语言菜单 SEO 增强（alpha.17） ​

2. 文本自动间距（alpha.17） ​

配置系统 ​

1. 分布式配置文件（alpha.5） ​

2. markdown.config 支持异步（alpha.2） ​

性能优化 ​

1. 构建优化 ​

2. 运行时优化 ​

3. 按需加载 ​

组合式 API 变更 ​

useLayout 替代 useLocalNav / useSidebar（alpha.5） ​

其他 API 变更 ​

postcssIsolateStyles 更新（alpha.12） ​

动态路由重构（alpha.3） ​

其他改进 ​

1. <<< 代码引入错误不再静默忽略（alpha.17） ​

2. 代码组标签切换事件（alpha.14） ​

3. markdown-it-attrs 对代码块禁用（alpha.13） ​

完整 Breaking Changes 汇总 ​

升级指南 ​

1. 更新依赖 ​

2. 检查配置 ​

3. 更新主题 ​

4. 更新自定义搜索渲染器 ​

5. 验证构建 ​

相关资源 ​

下一步 ​

贡献者

VitePress 2.0 新特性专题

版本概览

核心升级

1. Vite 6/7 支持

2. Shiki v3 升级

3. markdown-it-async

Markdown 增强

1. CJK 友好支持

2. 数学公式支持

3. 代码块增强

自定义显示名（alpha.13）

代码组

区域引入

语言别名

Shell 代码 `$` 符号不可选（alpha.14）

4. GitHub 风格警告

5. 代码块行操作

搜索增强

1. 本地搜索优化

2. DocSearch v4/v4.5

主题定制增强

1. CSS 变量系统

2. `@layer` 样式隔离（alpha.16）

3. 新布局插槽

4. 首页配置增强

`isHome` frontmatter（alpha.5）

Features 支持 details 列表（alpha.17）

路由与导航

1. 路由重写

2. 路由器增强

3. 导航增强

函数形式（alpha.13）

组件插槽

4. 文本片段导航（alpha.17）

多语言支持

1. 语言菜单 SEO 增强（alpha.17）

2. 文本自动间距（alpha.17）

配置系统

1. 分布式配置文件（alpha.5）

2. `markdown.config` 支持异步（alpha.2）

性能优化

1. 构建优化

2. 运行时优化

3. 按需加载

组合式 API 变更

useLayout 替代 useLocalNav / useSidebar（alpha.5）

其他 API 变更

postcssIsolateStyles 更新（alpha.12）

动态路由重构（alpha.3）

其他改进

1. `<<<` 代码引入错误不再静默忽略（alpha.17）

2. 代码组标签切换事件（alpha.14）

3. `markdown-it-attrs` 对代码块禁用（alpha.13）

完整 Breaking Changes 汇总

升级指南

1. 更新依赖

2. 检查配置

3. 更新主题

4. 更新自定义搜索渲染器

5. 验证构建

相关资源

下一步