参考
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.js
、package.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 迁移
- 更新依赖
bash
npm uninstall vuepress
npm install -D vitepress
- 更新配置
js
// 之前(VuePress)
module.exports = {
title: '我的站点',
themeConfig: {
nav: [...]
}
}
// 之后(VitePress)
export default {
title: '我的站点',
themeConfig: {
nav: [...]
}
}
- 更新主题结构
// 之前
.vuepress/
├── config.js
└── theme/
└── Layout.vue
// 之后
.vitepress/
├── config.js
└── theme/
├── index.js
└── Layout.vue
从 VuePress 2.x 迁移
- 配置变更
js
// VuePress 2.x
import { defineUserConfig } from 'vuepress'
export default defineUserConfig({
// 配置
})
// VitePress
import { defineConfig } from 'vitepress'
export default defineConfig({
// 配置
})
- 插件系统差异
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 文档。