特性

VitePress 在 Vite + Vue 的基础上提供了一系列面向文档场景的专属特性，涵盖渲染模式、构建优化、国际化、资源处理等维度。

1. SSG 与渲染模式

1.1 默认 SPA/SSG 混合模式

VitePress 默认采用 SSG（静态站点生成）+ SPA 导航 混合策略：

图表渲染中…

首屏：构建时预渲染为静态 HTML（利于 SEO 和首屏速度）
后续导航：客户端路由，无全页刷新（SPA 体验）

1.2 MPA 模式

通过 mpa: true 配置启用多页应用模式：

javascript

// .vitepress/config.js
export default {
  mpa: true
}

或通过命令行：vitepress build --mpa

MPA 模式特点：

所有页面不包含客户端 JavaScript（纯静态 HTML）
页面切换为全量刷新（无 SPA 路由）
Vue 仅作为服务端模板语言使用
需要交互时使用 <script client> 标签：

html

<script client>
document.querySelector('h1').addEventListener('click', () => {
  console.log('client side JavaScript!')
})
</script>

# Hello

何时使用 MPA

仅在站点几乎不需要客户端交互时使用（如纯文档/博客）。大多数场景推荐默认混合模式。

2. 构建优化

2.1 自动代码分割

VitePress 构建时自动按路由分割代码，每个页面只加载自身所需的 JS：

code

.vitepress/dist/
├── assets/
│   ├── app.js          ← 公共运行时
│   ├── index.md.js     ← 首页代码
│   ├── guide.md.js     ← guide 页代码
│   └── chunks/         ← 共享 chunk
└── index.html

2.2 预加载与预取

Prefetch：空闲时预取同组其他页面资源
Preload：导航时预加载目标页面关键资源

javascript

// 配置预取行为
export default {
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks(id) {
            if (id.includes('node_modules')) {
              return 'vendor'
            }
          }
        }
      }
    }
  }
}

2.3 图片懒加载

图片懒加载默认不启用，需在配置中将 markdown.image.lazyLoading 设置为 true，之后 Markdown 中的图片会自动添加 loading="lazy" 属性：

javascript

// .vitepress/config.js
export default {
  markdown: {
    image: { lazyLoading: true }
  }
}

markdown

![架构图](architecture.png)
<!-- 输出: <img src="..." loading="lazy" alt="架构图"> -->

3. 国际化（i18n）

VitePress 内置多语言支持，通过目录结构区分 locale：

code

docs/
├── index.md           ← 默认语言（en）
├── guide.md
├── zh/
│   ├── index.md       ← 中文首页
│   └── guide.md
└── .vitepress/
    └── config.ts

typescript

// .vitepress/config.ts
export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    zh: {
      label: '简体中文',
      lang: 'zh-CN',
      themeConfig: {
        nav: [
          { text: '指南', link: '/zh/guide' }
        ],
        sidebar: [
          { text: '介绍', link: '/zh/guide' }
        ]
      }
    }
  }
}

注意

每个 locale 可以独立配置 themeConfig（导航、侧边栏），但 vite 和 markdown 配置是全局共享的。

4. 资源处理

4.1 静态资源

public/ 目录下的文件原样复制到输出根目录：

code

docs/
├── public/
│   ├── logo.svg       → /logo.svg
│   └── data.json      → /data.json
└── guide.md

4.2 相对路径引用

Markdown 中引用同级资源使用相对路径，构建时自动处理 hash 和路径：

markdown

![图片](images/demo.png)
[下载 PDF](files/spec.pdf)

4.3 在 Vue 组件中引用资源

Vue SFC

<script setup>
import diagram from './assets/diagram.svg'
</script>

<template>
  <img :src="diagram" alt="架构图" />
</template>

5. 使用 Vue 组件

5.1 在 Markdown 中直接使用

VitePress 的 Markdown 文件本质是 Vue SFC，可直接使用 Vue 语法：

markdown

# 标题

{{ 1 + 1 }}  <!-- 输出: 2 -->

<div v-for="i in 3" :key="i">
  第 {{ i }} 项
</div>

5.2 注册全局组件

javascript

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyComponent from './components/MyComponent.vue'

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

然后在任意 Markdown 中使用：

markdown

<MyComponent :data="someData" />

5.3 访问站点数据

Vue SFC

<script setup>
import { useData } from 'vitepress'

const { page, frontmatter, theme, lang } = useData()
</script>

<template>
  <p>当前页面: {{ page.relativePath }}</p>
  <p>语言: {{ lang }}</p>
</template>

6. 生成 Sitemap

VitePress 提供开箱即用的 sitemap 生成：

javascript

export default {
  sitemap: {
    hostname: 'https://example.com'
  }
}

要包含 <lastmod> 标签，启用 lastUpdated 选项。

6.1 配置选项

底层由 sitemap 模块驱动，支持透传选项：

javascript

export default {
  sitemap: {
    hostname: 'https://example.com',
    lastmodDateOnly: false
  }
}

使用 base 时需追加到 hostname：

javascript

export default {
  base: '/my-site/',
  sitemap: {
    hostname: 'https://example.com/my-site/'
  }
}

6.2 transformItems Hook

在写入 sitemap.xml 前修改条目：

javascript

export default {
  sitemap: {
    hostname: 'https://example.com',
    transformItems: (items) => {
      items.push({
        url: '/extra-page',
        changefreq: 'monthly',
        priority: 0.8
      })
      return items
    }
  }
}

7. 其他内置特性

特性	说明
死链检测	构建时自动检测 404 内部链接
搜索	内置本地搜索 / Algolia DocSearch 集成
编辑链接	每页底部 "Edit this page" 跳转源码
最后更新时间	基于 Git 提交时间自动显示
大纲导航	右侧 TOC 自动跟随滚动高亮
暗色模式	跟随系统 / 手动切换，无闪烁
404 页面	自定义 SPA/MPA 模式下的 404 页

死链检测配置

javascript

export default {
  ignoreDeadLinks: [
    /^\/api\//,        // 忽略 /api/ 开头的链接
    'https://wip.com'  // 忽略特定 URL
  ]
}

特性

VitePress 在 Vite + Vue 的基础上提供了一系列面向文档场景的专属特性，涵盖渲染模式、构建优化、国际化、资源处理等维度。

1. SSG 与渲染模式

1.1 默认 SPA/SSG 混合模式

VitePress 默认采用 SSG（静态站点生成）+ SPA 导航 混合策略：

图表渲染中…

首屏：构建时预渲染为静态 HTML（利于 SEO 和首屏速度）
后续导航：客户端路由，无全页刷新（SPA 体验）

1.2 MPA 模式

通过 mpa: true 配置启用多页应用模式：

javascript

// .vitepress/config.js
export default {
  mpa: true
}

或通过命令行：vitepress build --mpa

MPA 模式特点：

所有页面不包含客户端 JavaScript（纯静态 HTML）
页面切换为全量刷新（无 SPA 路由）
Vue 仅作为服务端模板语言使用
需要交互时使用 <script client> 标签：

html

<script client>
document.querySelector('h1').addEventListener('click', () => {
  console.log('client side JavaScript!')
})
</script>

# Hello

何时使用 MPA

仅在站点几乎不需要客户端交互时使用（如纯文档/博客）。大多数场景推荐默认混合模式。

2. 构建优化

2.1 自动代码分割

VitePress 构建时自动按路由分割代码，每个页面只加载自身所需的 JS：

code

.vitepress/dist/
├── assets/
│   ├── app.js          ← 公共运行时
│   ├── index.md.js     ← 首页代码
│   ├── guide.md.js     ← guide 页代码
│   └── chunks/         ← 共享 chunk
└── index.html

2.2 预加载与预取

Prefetch：空闲时预取同组其他页面资源
Preload：导航时预加载目标页面关键资源

javascript

// 配置预取行为
export default {
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks(id) {
            if (id.includes('node_modules')) {
              return 'vendor'
            }
          }
        }
      }
    }
  }
}

2.3 图片懒加载

图片懒加载默认不启用，需在配置中将 markdown.image.lazyLoading 设置为 true，之后 Markdown 中的图片会自动添加 loading="lazy" 属性：

javascript

// .vitepress/config.js
export default {
  markdown: {
    image: { lazyLoading: true }
  }
}

markdown

![架构图](architecture.png)
<!-- 输出: <img src="..." loading="lazy" alt="架构图"> -->

3. 国际化（i18n）

VitePress 内置多语言支持，通过目录结构区分 locale：

code

docs/
├── index.md           ← 默认语言（en）
├── guide.md
├── zh/
│   ├── index.md       ← 中文首页
│   └── guide.md
└── .vitepress/
    └── config.ts

typescript

// .vitepress/config.ts
export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    zh: {
      label: '简体中文',
      lang: 'zh-CN',
      themeConfig: {
        nav: [
          { text: '指南', link: '/zh/guide' }
        ],
        sidebar: [
          { text: '介绍', link: '/zh/guide' }
        ]
      }
    }
  }
}

注意

每个 locale 可以独立配置 themeConfig（导航、侧边栏），但 vite 和 markdown 配置是全局共享的。

4. 资源处理

4.1 静态资源

public/ 目录下的文件原样复制到输出根目录：

code

docs/
├── public/
│   ├── logo.svg       → /logo.svg
│   └── data.json      → /data.json
└── guide.md

4.2 相对路径引用

Markdown 中引用同级资源使用相对路径，构建时自动处理 hash 和路径：

markdown

![图片](images/demo.png)
[下载 PDF](files/spec.pdf)

4.3 在 Vue 组件中引用资源

Vue SFC

<script setup>
import diagram from './assets/diagram.svg'
</script>

<template>
  <img :src="diagram" alt="架构图" />
</template>

5. 使用 Vue 组件

5.1 在 Markdown 中直接使用

VitePress 的 Markdown 文件本质是 Vue SFC，可直接使用 Vue 语法：

markdown

# 标题

{{ 1 + 1 }}  <!-- 输出: 2 -->

<div v-for="i in 3" :key="i">
  第 {{ i }} 项
</div>

5.2 注册全局组件

javascript

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyComponent from './components/MyComponent.vue'

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

然后在任意 Markdown 中使用：

markdown

<MyComponent :data="someData" />

5.3 访问站点数据

Vue SFC

<script setup>
import { useData } from 'vitepress'

const { page, frontmatter, theme, lang } = useData()
</script>

<template>
  <p>当前页面: {{ page.relativePath }}</p>
  <p>语言: {{ lang }}</p>
</template>

6. 生成 Sitemap

VitePress 提供开箱即用的 sitemap 生成：

javascript

export default {
  sitemap: {
    hostname: 'https://example.com'
  }
}

要包含 <lastmod> 标签，启用 lastUpdated 选项。

6.1 配置选项

底层由 sitemap 模块驱动，支持透传选项：

javascript

export default {
  sitemap: {
    hostname: 'https://example.com',
    lastmodDateOnly: false
  }
}

使用 base 时需追加到 hostname：

javascript

export default {
  base: '/my-site/',
  sitemap: {
    hostname: 'https://example.com/my-site/'
  }
}

6.2 transformItems Hook

在写入 sitemap.xml 前修改条目：

javascript

export default {
  sitemap: {
    hostname: 'https://example.com',
    transformItems: (items) => {
      items.push({
        url: '/extra-page',
        changefreq: 'monthly',
        priority: 0.8
      })
      return items
    }
  }
}

7. 其他内置特性

特性	说明
死链检测	构建时自动检测 404 内部链接
搜索	内置本地搜索 / Algolia DocSearch 集成
编辑链接	每页底部 "Edit this page" 跳转源码
最后更新时间	基于 Git 提交时间自动显示
大纲导航	右侧 TOC 自动跟随滚动高亮
暗色模式	跟随系统 / 手动切换，无闪烁
404 页面	自定义 SPA/MPA 模式下的 404 页

死链检测配置

javascript

export default {
  ignoreDeadLinks: [
    /^\/api\//,        // 忽略 /api/ 开头的链接
    'https://wip.com'  // 忽略特定 URL
  ]
}

特性

1. SSG 与渲染模式

1.1 默认 SPA/SSG 混合模式

1.2 MPA 模式

2. 构建优化

2.1 自动代码分割

2.2 预加载与预取

2.3 图片懒加载

3. 国际化（i18n）

4. 资源处理

4.1 静态资源

4.2 相对路径引用

4.3 在 Vue 组件中引用资源

5. 使用 Vue 组件

5.1 在 Markdown 中直接使用

5.2 注册全局组件

5.3 访问站点数据

6. 生成 Sitemap

6.1 配置选项

6.2 transformItems Hook

7. 其他内置特性

相关文档

特性

1. SSG 与渲染模式

1.1 默认 SPA/SSG 混合模式

1.2 MPA 模式

2. 构建优化

2.1 自动代码分割

2.2 预加载与预取

2.3 图片懒加载

3. 国际化（i18n）

4. 资源处理

4.1 静态资源

4.2 相对路径引用

4.3 在 Vue 组件中引用资源

5. 使用 Vue 组件

5.1 在 Markdown 中直接使用

5.2 注册全局组件

5.3 访问站点数据

6. 生成 Sitemap

6.1 配置选项

6.2 transformItems Hook

7. 其他内置特性

相关文档