Skip to content

参考

VitePress 的完整 API 参考和配置选项。

配置参考

站点配置

基本选项

ts
interface SiteConfig {
  /**
   * 站点标题。将显示在导航栏中。
   * 除非定义了 `titleTemplate`,否则也用作所有页面标题的后缀。
   */
  title?: string

  /**
   * 站点描述。这将在页面 HTML 中渲染为 <meta> 标签。
   */
  description?: string

  /**
   * 站点将部署的基本 URL。
   * @default '/'
   */
  base?: string

  /**
   * 站点的语言。这将在页面 HTML 中渲染为 lang 属性。
   * @default 'en-US'
   */
  lang?: string

  /**
   * 作为源目录的目录。
   * @default 'docs'
   */
  srcDir?: string

  /**
   * 保存构建文件的目录,相对于项目根目录。
   * @default '.vitepress/dist'
   */
  outDir?: string

  /**
   * 保存缓存文件的目录。
   * @default '.vitepress/cache'
   */
  cacheDir?: string

  /**
   * 是否为每个页面包含最后更新的时间戳。
   * @default false
   */
  lastUpdated?: boolean

  /**
   * 是否启用干净的 URL。
   * @default false
   */
  cleanUrls?: boolean
}

高级选项

ts
interface AdvancedSiteConfig {
  /**
   * 页面的自定义标题模板。
   * @example ':title - 自定义后缀'
   */
  titleTemplate?: string | boolean

  /**
   * 外观模式。
   * @default 'auto'
   */
  appearance?: 'dark' | 'light' | 'auto'

  /**
   * 要渲染的自定义头部标签。
   */
  head?: HeadConfig[]

  /**
   * 多语言站点的区域设置配置。
   */
  locales?: Record<string, LocaleConfig>

  /**
   * Markdown 配置。
   */
  markdown?: MarkdownConfig

  /**
   * Vite 配置。
   */
  vite?: ViteConfig

  /**
   * 构建钩子。
   */
  buildEnd?: (siteConfig: SiteConfig) => void | Promise<void>
  postRender?: (context: SSGContext) => void | Promise<void>
  transformHead?: (context: TransformContext) => void | Promise<void>
  transformHtml?: (code: string, id: string, context: TransformContext) => void | Promise<void>
  transformPageData?: (pageData: PageData, context: TransformContext) => void | Promise<void>
}

主题配置

默认主题配置

ts
interface DefaultThemeConfig {
  /**
   * Logo 文件路径。
   */
  logo?: string

  /**
   * 自定义站点标题。如果未设置,将使用 `config.title`。
   */
  siteTitle?: string | false

  /**
   * 导航菜单项。
   */
  nav?: NavItem[]

  /**
   * 侧边栏配置。
   */
  sidebar?: Sidebar

  /**
   * 要在导航栏末尾显示的社交链接。
   */
  socialLinks?: SocialLink[]

  /**
   * 页脚配置。
   */
  footer?: Footer

  /**
   * 编辑链接配置。
   */
  editLink?: EditLink

  /**
   * 最后更新文本配置。
   */
  lastUpdated?: LastUpdatedOptions

  /**
   * 搜索配置。
   */
  search?: SearchConfig

  /**
   * Carbon 广告配置。
   */
  carbonAds?: CarbonAdsConfig

  /**
   * 文档页脚配置。
   */
  docFooter?: DocFooter

  /**
   * 大纲配置。
   */
  outline?: Outline

  /**
   * 返回顶部标签。
   */
  returnToTopLabel?: string

  /**
   * 外部链接图标配置。
   */
  externalLinkIcon?: boolean
}

导航配置

ts
interface NavItem {
  /**
   * 项目的文本标签。
   */
  text: string

  /**
   * 项目的链接。
   */
  link?: string

  /**
   * 项目的子项。
   */
  items?: NavItem[]

  /**
   * `activeMatch` 应该是一个正则表达式字符串。我们不能在这里使用实际的
   * RegExp 对象,因为它不可序列化
   */
  activeMatch?: string

  /**
   * 链接的 `rel` 属性。
   */
  rel?: string

  /**
   * 链接的 `target` 属性。
   */
  target?: string
}

侧边栏配置

ts
type Sidebar = SidebarItem[] | SidebarMulti

interface SidebarItem {
  /**
   * 项目的文本标签。
   */
  text?: string

  /**
   * 项目的链接。
   */
  link?: string

  /**
   * 项目的子项。
   */
  items?: SidebarItem[]

  /**
   * 如果未指定,组不可折叠。
   * 如果为 `true`,组可折叠且默认折叠
   * 如果为 `false`,组可折叠但默认展开
   */
  collapsed?: boolean
}

interface SidebarMulti {
  [path: string]: SidebarItem[]
}

Markdown 配置

ts
interface MarkdownConfig {
  /**
   * 在代码块中启用行号。
   * @default false
   */
  lineNumbers?: boolean

  /**
   * Markdown-it 配置函数。
   */
  config?: (md: MarkdownIt) => void

  /**
   * 语法高亮主题。
   * @default 'material-theme-palenight'
   */
  theme?: 
    | string
    | { light: string; dark: string }

  /**
   * 自定义容器配置。
   */
  container?: {
    tipLabel?: string
    warningLabel?: string
    dangerLabel?: string
    infoLabel?: string
    detailsLabel?: string
  }

  /**
   * 数学支持配置。
   */
  math?: boolean

  /**
   * 代码转换器。
   */
  codeTransformers?: CodeTransformer[]
}

API 参考

useData()

在 Vue 组件中访问页面和站点数据。

ts
interface VitePressData {
  /**
   * 站点级元数据
   */
  site: Ref<SiteData>

  /**
   * 来自 .vitepress/config.js 的 themeConfig
   */
  theme: Ref<DefaultTheme.Config>

  /**
   * 页面级元数据
   */
  page: Ref<PageData>

  /**
   * 页面前言数据
   */
  frontmatter: Ref<PageData['frontmatter']>

  /**
   * 动态路由参数
   */
  params: Ref<PageData['params']>

  /**
   * 当前页面标题
   */
  title: Ref<string>

  /**
   * 当前页面描述
   */
  description: Ref<string>

  /**
   * 当前页面语言
   */
  lang: Ref<string>

  /**
   * 页面是否为 404
   */
  isDark: Ref<boolean>

  /**
   * 当前页面目录
   */
  dir: Ref<string>

  /**
   * 当前区域路径
   */
  localeIndex: Ref<string>
}

用法:

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

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

<template>
  <h1>{{ site.title }}</h1>
  <p>{{ page.title }}</p>
  <p>{{ frontmatter.description }}</p>
</template>

useRouter()

访问路由实例进行导航。

ts
interface Router {
  /**
   * 当前路由位置
   */
  route: Route

  /**
   * 导航到不同的位置
   */
  go: (to?: string) => Promise<void>

  /**
   * 注册一个在每次路由变更前调用的回调
   */
  onBeforeRouteChange?: (to: string) => void

  /**
   * 注册一个在每次路由变更后调用的回调
   */
  onAfterRouteChanged?: (to: string) => void
}

用法:

vue
<script setup>
import { useRouter } from 'vitepress'

const router = useRouter()

const navigateToGuide = () => {
  router.go('/guide/')
}
</script>

Content 组件

在 Vue 组件中渲染 Markdown 内容。

vue
<template>
  <div class="custom-layout">
    <aside class="sidebar">
      <!-- 自定义侧边栏 -->
    </aside>
    <main class="content">
      <Content />
    </main>
  </div>
</template>

前言参考

页面前言

yaml
---
# 页面标题(覆盖 h1)
title: 自定义页面标题

# 用于 SEO 的页面描述
description: 这是一个自定义页面描述

# 用于此页面的布局
layout: home | page | doc

# 是否在侧边栏中显示页面
sidebar: true | false

# 是否显示编辑链接
editLink: true | false

# 是否显示最后更新时间
lastUpdated: true | false

# 是否显示上一页/下一页链接
prev: true | false | string | { text: string, link: string }
next: true | false | string | { text: string, link: string }

# 页面特定的头部标签
head:
  - - meta
    - name: description
      content: 自定义描述
  - - meta
    - name: keywords
      content: 关键词1, 关键词2

# 此页面的大纲配置
outline: false | [number, number] | 'deep'

# 自定义页面类
pageClass: custom-page-class
---

首页布局前言

yaml
---
layout: home

hero:
  name: VitePress
  text: 由 Vite 和 Vue 驱动的静态站点生成器
  tagline: 简单、强大且高性能。满足您一直想要的现代 SSG 框架。
  image:
    src: /logo-with-shadow.png
    alt: VitePress
  actions:
    - theme: brand
      text: 开始使用
      link: /guide/what-is-vitepress
    - theme: alt
      text: 在 GitHub 上查看
      link: https://github.com/vuejs/vitepress

features:
  - icon: 📝
    title: 专注于您的内容
    details: 只需使用 Markdown 即可轻松创建美观的文档站点。
  - icon: 🎨
    title: 享受 Vue 开发体验
    details: 在 Markdown 中直接使用 Vue 语法和组件,或使用 Vue 构建自定义主题。
  - icon: 🚀
    title: 快速站点
    details: 快速的开发服务器启动。闪电般的热更新。优化的构建输出。
---

CLI 参考

命令

bash
# 启动开发服务器
vitepress dev [root]

# 构建生产版本
vitepress build [root]

# 预览生产构建
vitepress preview [root]

# 在当前目录初始化 VitePress
vitepress init

选项

bash
# 开发服务器选项
vitepress dev --port 3000 --host 0.0.0.0 --open

# 构建选项
vitepress build --outDir dist --base /my-site/

# 预览选项
vitepress preview --port 4173 --host localhost

环境变量

构建时变量

bash
# Node 环境
NODE_ENV=production

# 部署的基本 URL
VITE_BASE_URL=/my-site/

# API 端点
VITE_API_URL=https://api.example.com

# 功能标志
VITE_FEATURE_ANALYTICS=true

运行时访问

js
// 在组件中访问环境变量
const apiUrl = import.meta.env.VITE_API_URL
const isDev = import.meta.env.DEV
const isProd = import.meta.env.PROD

文件约定

目录结构

.
├── docs/
│   ├── .vitepress/
│   │   ├── config.js          # 配置文件
│   │   ├── theme/             # 自定义主题
│   │   │   ├── index.js       # 主题入口
│   │   │   ├── Layout.vue     # 布局组件
│   │   │   └── style.css      # 自定义样式
│   │   └── dist/              # 构建输出
│   ├── guide/
│   │   ├── index.md
│   │   └── getting-started.md
│   ├── api/
│   │   └── reference.md
│   ├── public/                # 静态资源
│   │   ├── favicon.ico
│   │   └── logo.png
│   └── index.md               # 首页
└── package.json

文件命名

  • Markdown 文件:使用 kebab-case(getting-started.md
  • Vue 组件:使用 PascalCase(MyComponent.vue
  • 资源:使用描述性名称(hero-image.png
  • 配置:使用标准名称(config.jspackage.json

TypeScript 支持

配置

ts
// .vitepress/config.ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'VitePress',
  description: '由 Vite 和 Vue 驱动的静态站点生成器'
})

主题开发

ts
// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app, router, siteData }) {
    // 类型安全的主题定制
  }
} satisfies Theme

组件类型

vue
<script setup lang="ts">
import { useData } from 'vitepress'
import type { DefaultTheme } from 'vitepress/theme'

interface Props {
  title: string
  items: DefaultTheme.NavItem[]
}

const props = defineProps<Props>()
const { site, theme } = useData()
</script>

迁移指南

从 VuePress 1.x 迁移

  1. 更新依赖
bash
npm uninstall vuepress
npm install -D vitepress
  1. 更新配置
js
// 之前(VuePress)
module.exports = {
  title: '我的站点',
  themeConfig: {
    nav: [...]
  }
}

// 之后(VitePress)
export default {
  title: '我的站点',
  themeConfig: {
    nav: [...]
  }
}
  1. 更新主题结构
// 之前
.vuepress/
├── config.js
└── theme/
    └── Layout.vue

// 之后
.vitepress/
├── config.js
└── theme/
    ├── index.js
    └── Layout.vue

从 VuePress 2.x 迁移

  1. 配置变更
js
// VuePress 2.x
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  // 配置
})

// VitePress
import { defineConfig } from 'vitepress'

export default defineConfig({
  // 配置
})
  1. 插件系统差异
js
// VuePress 2.x 使用插件数组
export default {
  plugins: [
    ['@vuepress/plugin-search'],
    ['@vuepress/plugin-pwa']
  ]
}

// VitePress 使用 Vite 插件
export default {
  vite: {
    plugins: [
      // Vite 插件
    ]
  }
}

性能提示

包优化

js
// .vitepress/config.js
export default {
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['vue'],
            utils: ['lodash', 'date-fns']
          }
        }
      }
    }
  }
}

资源优化

js
export default {
  vite: {
    build: {
      assetsInlineLimit: 4096,
      cssCodeSplit: true,
      sourcemap: false
    }
  }
}

代码分割

vue
<script setup>
// 使用动态导入加载重量级组件
const HeavyComponent = defineAsyncComponent(() => 
  import('./HeavyComponent.vue')
)
</script>

故障排除

常见问题

构建错误

  • 检查 Node.js 版本(18+)
  • 验证配置语法
  • 清除缓存:rm -rf .vitepress/cache

路由问题

  • 验证文件结构是否与路由匹配
  • 检查基本 URL 配置
  • 确保正确的文件扩展名

性能问题

  • 分析包大小:npm run build -- --analyze
  • 优化图像和资源
  • 审查第三方依赖

调试模式

bash
# 启用调试日志
DEBUG=vitepress:* npm run dev

# 详细构建输出
npm run build -- --debug

资源

官方文档

社区

工具


本参考指南涵盖了最常用的 API 和配置。有关最新更新,请始终参考官方 VitePress 文档。

vitepress开发指南