构建 API

VitePress 提供了一组构建相关的 API，用于配置站点、编程式构建和创建开发服务器。

defineConfig

类型安全的配置定义函数，支持智能提示和类型检查。

类型签名

function defineConfig(config: UserConfig): UserConfig
function defineConfig(config: Promise<UserConfig>): Promise<UserConfig>
function defineConfig(config: (env: ConfigEnv) => UserConfig): UserConfig

基础用法

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

export default defineConfig({
  title: 'My Site',
  description: 'A VitePress site'
})

异步配置

当配置依赖异步数据时，返回 Promise：

export default defineConfig(async () => {
  const posts = await fetchPosts()
  return {
    themeConfig: {
      sidebar: generateSidebar(posts)
    }
  }
})

环境感知配置

根据运行环境动态调整配置：

export default defineConfig(({ mode, command }) => {
  return {
    // 生产环境使用子路径部署
    base: mode === 'production' ? '/docs/' : '/',

    // 仅开发时启用调试
    vite: {
      logLevel: command === 'serve' ? 'info' : 'warn'
    }
  }
})

配置拆分与组合

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

export const shared = defineConfig({
  title: 'My Site',
  description: 'A VitePress site',
  lastUpdated: true,
  cleanUrls: true
})

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

export const theme = defineConfig({
  themeConfig: {
    nav: [...],
    sidebar: {...}
  }
})

// .vitepress/config.mts
import { defineConfig } from 'vitepress'
import { shared } from './config/shared'
import { theme } from './config/theme'

export default defineConfig({
  ...shared,
  ...theme
})

build

编程式构建站点，用于 CI/CD 流水线或自定义构建脚本。

类型签名

function build(root?: string): Promise<void>

参数

参数	类型	默认值	说明
`root`	`string`	`process.cwd()`	VitePress 项目根目录（包含 `.vitepress/` 的目录）

基础用法

import { build } from 'vitepress'

// 构建当前目录
await build()

// 构建指定目录
await build('docs')

CI/CD 集成

// scripts/build.ts
import { build } from 'vitepress'

async function main() {
  try {
    console.log('开始构建...')
    await build('docs')
    console.log('构建完成！')
  } catch (error) {
    console.error('构建失败:', error)
    process.exit(1)
  }
}

main()

构建选项

构建行为由配置文件控制，主要选项：

选项	类型	默认值	说明
`srcDir`	`string`	项目根目录	文档源目录
`srcExclude`	`string[]`	`[]`	排除的源文件
`outDir`	`string`	`.vitepress/dist`	输出目录
`cacheDir`	`string`	`.vitepress/cache`	缓存目录
`cleanUrls`	`boolean`	`false`	清洁 URL（无 `.html` 后缀）
`metaChunk`	`boolean`	`false`	将页面元数据拆分为独立 chunk

createServer

创建开发服务器实例，用于自定义开发工作流。

类型签名

function createServer(
  root?: string,
  options?: ServerOptions
): Promise<ViteDevServer>

参数

参数	类型	默认值	说明
`root`	`string`	`process.cwd()`	项目根目录
`options`	`ServerOptions`	—	服务器选项

ServerOptions

interface ServerOptions {
  port?: number            // 端口号，默认 5173
  host?: string | boolean  // 主机地址
  open?: boolean           // 自动打开浏览器
  base?: string            // 公共基础路径
  cors?: boolean           // 启用 CORS
  strictPort?: boolean     // 端口被占用时报错
}

基础用法

import { createServer } from 'vitepress'

const server = await createServer('docs')
await server.listen()

console.log(`Server running at ${server.resolvedUrls?.local}`)

自定义开发服务器

import { createServer } from 'vitepress'

const server = await createServer('docs', {
  port: 3000,
  host: true,
  open: true
})

// 监听文件变化
server.watcher.on('change', (file) => {
  console.log(`File changed: ${file}`)
})

// 监听新增文件
server.watcher.on('add', (file) => {
  console.log(`File added: ${file}`)
})

await server.listen()

serve

预览构建结果的服务器，用于构建后验证。

类型签名

function serve(
  root?: string,
  options?: ServeOptions
): Promise<void>

参数

参数	类型	默认值	说明
`root`	`string`	`process.cwd()`	项目根目录
`options`	`ServeOptions`	—	预览服务器选项

ServeOptions

interface ServeOptions {
  port?: number            // 端口号，默认 4173
  host?: string | boolean  // 主机地址
  open?: boolean           // 自动打开浏览器
  outDir?: string          // 预览的输出目录
}

基础用法

import { serve } from 'vitepress'

await serve('docs', {
  port: 4173,
  host: true
})

构建并预览

import { build, serve } from 'vitepress'

// 先构建
await build('docs')

// 再预览
await serve('docs', {
  port: 8080,
  open: true
})

resolveConfig

解析配置文件，返回完整的配置对象，用于构建工具和插件开发。

类型签名

function resolveConfig(
  root?: string,
  command?: 'serve' | 'build',
  mode?: string
): Promise<SiteConfig>

参数

参数	类型	默认值	说明
`root`	`string`	`process.cwd()`	项目根目录
`command`	`'serve' \| 'build'`	`'build'`	运行命令
`mode`	`string`	`'production'`	运行模式

基础用法

import { resolveConfig } from 'vitepress'

const config = await resolveConfig('docs')

console.log(config.site.title)
console.log(config.userConfig)
console.log(config.outDir)

插件开发中使用

import { resolveConfig } from 'vitepress'

async function myPlugin() {
  const config = await resolveConfig('docs')

  // 读取站点配置
  const title = config.site.title
  const description = config.site.description

  // 读取主题配置
  const nav = config.site.themeConfig.nav
  const sidebar = config.site.themeConfig.sidebar

  return { title, description, nav, sidebar }
}

UserConfig 接口

完整的用户配置类型定义，涵盖站点、路由、构建、Markdown、国际化和主题配置：

interface UserConfig {
  // === 站点配置 ===
  title?: string                       // 站点标题
  titleTemplate?: string | boolean     // 标题模板，false 禁用
  description?: string                 // 站点描述（SEO）
  head?: HeadConfig[]                  // 全局 head 标签
  lang?: string                        // 站点语言，默认 'en-US'

  // === 路由配置 ===
  base?: string                        // 基础路径，用于子路径部署
  cleanUrls?: boolean                  // 启用清洁 URL
  rewrites?: Record<string, string>    // 路由重写规则
  srcDir?: string                      // 文档源目录
  srcExclude?: string[]                // 排除的源文件 glob

  // === 外观配置 ===
  appearance?: boolean | 'dark' | 'force-dark' | 'force-auto' // 深色模式
  lastUpdated?: boolean | LastUpdatedOptions                    // 最后更新时间

  // === 构建配置 ===
  outDir?: string                      // 输出目录
  cacheDir?: string                    // 缓存目录
  ignoreDeadLinks?: boolean | string[] | IgnoreDeadLinksConfig  // 忽略死链接
  metaChunk?: boolean                  // 元数据独立 chunk
  mpa?: boolean                        // MPA 模式
  sitemap?: SitemapOptions             // Sitemap 配置
  robots?: RobotsOptions               // robots.txt 配置

  // === Markdown 配置 ===
  markdown?: MarkdownOptions           // Markdown 渲染配置

  // === 国际化 ===
  locales?: Locales                    // 多语言配置

  // === 主题配置 ===
  themeConfig?: ThemeConfig            // 主题配置对象

  // === 构建钩子 ===
  transformHead?: (ctx: TransformContext) => Awaitable<HeadConfig[]>
  transformPageData?: (pageData: PageData, ctx: TransformPageContext) => Awaitable<void>
  transformHtml?: (code: string, id: string, ctx: TransformContext) => Awaitable<string | void>
  buildEnd?: (siteConfig: SiteConfig) => Awaitable<void>
  postBuild?: (siteConfig: SiteConfig) => Awaitable<void>

  // === Vite 配置 ===
  vite?: ViteConfig                    // 传递给 Vite 的配置
}

UserConfig 逐字段详解

字段	类型	默认值	说明
`title`	`string`	—	站点标题，显示在导航栏和页面标题中
`titleTemplate`	`string \| boolean`	—	标题后缀模板，如 `'- My Site'`，设为 `false` 禁用
`description`	`string`	—	站点描述，用于 SEO 和社交分享
`head`	`HeadConfig[]`	—	全局 `<head>` 标签，如 favicon、meta 等
`lang`	`string`	`'en-US'`	站点语言，影响 `<html lang>` 属性
`base`	`string`	`'/'`	基础路径，用于 GitHub Pages 等子路径部署
`cleanUrls`	`boolean`	`false`	是否启用清洁 URL（移除 `.html` 后缀）
`rewrites`	`Record<string, string>`	—	路由重写映射，如 `{ 'old/path.md': 'new/path.md' }`
`srcDir`	`string`	项目根目录	文档源目录，如 `'./docs'`
`srcExclude`	`string[]`	`[]`	排除的源文件 glob 模式
`appearance`	`boolean \| 'dark' \| 'force-dark' \| 'force-auto'`	`true`	深色模式配置
`lastUpdated`	`boolean \| LastUpdatedOptions`	`false`	是否显示最后更新时间
`outDir`	`string`	`.vitepress/dist`	构建输出目录
`cacheDir`	`string`	`.vitepress/cache`	构建缓存目录
`ignoreDeadLinks`	`boolean \| string[] \| IgnoreDeadLinksConfig`	`false`	死链接处理策略
`metaChunk`	`boolean`	`false`	将页面元数据拆分为独立 chunk 以减小首屏体积
`mpa`	`boolean`	`false`	启用 MPA（多页面应用）模式，不使用客户端路由
`sitemap`	`SitemapOptions`	—	自动生成 sitemap 配置
`robots`	`RobotsOptions`	—	生成 robots.txt 配置
`markdown`	`MarkdownOptions`	—	Markdown 渲染选项（主题、行号、数学公式等）
`locales`	`Locales`	—	多语言站点配置
`themeConfig`	`ThemeConfig`	—	主题配置（导航、侧边栏、搜索等）
`vite`	`ViteConfig`	—	传递给 Vite 的配置选项

ConfigEnv 接口

传递给 defineConfig 函数的环境对象：

interface ConfigEnv {
  mode: 'development' | 'production'  // 运行模式
  command: 'serve' | 'build'          // 当前命令
  isServer?: boolean                   // 是否为 SSR 构建
}

ConfigEnv 逐字段详解

字段	类型	说明
`mode`	`'development' \| 'production'`	当前运行模式，`vitepress dev` 为 `'development'`，`vitepress build` 为 `'production'`
`command`	`'serve' \| 'build'`	当前执行的命令，`dev` 和 `preview` 为 `'serve'`，`build` 为 `'build'`
`isServer`	`boolean`	是否为服务端渲染构建

环境感知配置示例

export default defineConfig(({ mode, command }) => {
  // 开发环境配置
  if (command === 'serve') {
    return {
      vite: {
        server: {
          open: true,
          proxy: {
            '/api': 'http://localhost:3001'
          }
        }
      }
    }
  }

  // 生产构建配置
  return {
    base: '/docs/',
    vite: {
      build: {
        chunkSizeWarningLimit: 1500,
        rollupOptions: {
          output: {
            manualChunks: {
              'vue': ['vue', 'vue-router']
            }
          }
        }
      }
    }
  }
})

SiteConfig 接口

resolveConfig 解析后返回的完整站点配置对象：

interface SiteConfig {
  // 用户配置
  userConfig: UserConfig              // 原始用户配置

  // 站点数据
  site: SiteData                      // 解析后的站点数据

  // 路由配置
  rewrites: { map: Record<string, string> }  // 路由重写映射

  // 构建配置
  root: string                        // 项目根目录
  srcDir: string                      // 源目录
  outDir: string                      // 输出目录
  cacheDir: string                    // 缓存目录
  tempDir: string                     // 临时文件目录

  // 额外信息
  configPath: string                  // 配置文件路径
  configDeps: string[]                // 配置依赖文件列表
}

SiteConfig 逐字段详解

字段	类型	说明
`userConfig`	`UserConfig`	用户原始配置对象（未经解析）
`site`	`SiteData`	解析后的站点数据，包含 `title`、`description`、`lang`、`themeConfig` 等
`rewrites`	`{ map: Record<string, string> }`	解析后的路由重写映射
`root`	`string`	项目根目录的绝对路径
`srcDir`	`string`	文档源目录的绝对路径
`outDir`	`string`	构建输出目录的绝对路径
`cacheDir`	`string`	缓存目录的绝对路径
`tempDir`	`string`	临时文件目录的绝对路径
`configPath`	`string`	配置文件的绝对路径
`configDeps`	`string[]`	配置依赖文件的路径列表（用于 HMR）

构建钩子

VitePress 提供了多个构建钩子，允许在构建过程的不同阶段执行自定义逻辑。

transformHead

在构建时为每个页面注入自定义 <head> 标签。

interface TransformContext {
  pageData: PageData     // 页面数据
  siteConfig: SiteConfig // 站点配置
  siteData: SiteData     // 站点数据
  title: string          // 页面标题
  description: string    // 页面描述
  head: HeadConfig[]     // 当前 head 标签
  content: string        // 页面内容
}

export default defineConfig({
  transformHead({ pageData, siteData }) {
    return [
      ['meta', { name: 'author', content: pageData.frontmatter.author || siteData.title }],
      ['meta', { property: 'og:title', content: pageData.title }]
    ]
  }
})

transformPageData

在构建时修改页面的 frontmatter 或页面数据。

interface TransformPageContext {
  siteConfig: SiteConfig
}

export default defineConfig({
  transformPageData(pageData, { siteConfig }) {
    // 为所有页面设置默认布局
    pageData.frontmatter.layout ??= 'doc'

    // 自动生成描述
    if (!pageData.frontmatter.description) {
      pageData.frontmatter.description = pageData.content?.slice(0, 160)
    }
  }
})

transformHtml

在构建完成后修改 HTML 输出。

export default defineConfig({
  transformHtml(code, id, { pageData }) {
    if (id.endsWith('.html') && !id.includes('404.html')) {
      // 注入自定义脚本
      return code.replace(
        '</head>',
        '<script>console.log("page loaded")</script>\n</head>'
      )
    }
  }
})

buildEnd

在构建完成时执行，可用于生成额外文件或发送通知。

export default defineConfig({
  async buildEnd(siteConfig) {
    const pages = Object.keys(siteConfig.site.pages)
    console.log(`构建完成，共 ${pages.length} 个页面`)

    // 生成自定义 JSON 数据
    const data = JSON.stringify({ pages })
    fs.writeFileSync(path.join(siteConfig.outDir, 'search-index.json'), data)
  }
})

postBuild

在所有构建任务（包括 sitemap 等）完成后执行。

export default defineConfig({
  async postBuild(siteConfig) {
    // 上传到 CDN
    // 发送构建通知
    // 触发部署流程
    console.log(`站点输出在: ${siteConfig.outDir}`)
  }
})

HeadConfig 类型

head 字段和 transformHead 钩子使用的标签配置格式：

type HeadConfig =
  | [string, Record<string, string>]              // 标签名 + 属性
  | [string, Record<string, string>, string]       // 标签名 + 属性 + 内联内容

// 示例
const head: HeadConfig[] = [
  // <link rel="icon" href="/favicon.ico" />
  ['link', { rel: 'icon', href: '/favicon.ico' }],

  // <meta name="theme-color" content="#6366f1" />
  ['meta', { name: 'theme-color', content: '#6366f1' }],

  // <script async src="/analytics.js"></script>
  ['script', { src: '/analytics.js', async: '' }],

  // <script type="application/ld+json">{...}</script>
  ['script', { type: 'application/ld+json' }, JSON.stringify({ '@type': 'WebSite' })]
]

IgnoreDeadLinksConfig 类型

ignoreDeadLinks 的详细配置：

type IgnoreDeadLinksConfig =
  | boolean                    // true = 忽略所有死链接
  | 'localhostLinks'           // 仅忽略 localhost 链接
  | string[]                   // 忽略匹配的 URL 列表
  | ((url: string) => boolean) // 自定义判断函数

// 示例
export default defineConfig({
  // 忽略特定域名
  ignoreDeadLinks: ['/api/', '/legacy/'],

  // 使用函数过滤
  ignoreDeadLinks: (url) => {
    return url.startsWith('http://localhost') || url.includes('example.com')
  }
})

最佳实践

配置文件组织

// .vitepress/config.mts
import { defineConfig } from 'vitepress'
import { sharedConfig } from './shared'
import { themeConfig } from './theme'

export default defineConfig({
  ...sharedConfig,
  ...themeConfig,

  // 环境特定配置
  vite: {
    build: {
      chunkSizeWarningLimit: 1500
    }
  }
})

类型安全

import { defineConfig, type DefaultTheme } from 'vitepress'

export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' }
    ]
  } satisfies DefaultTheme.Config
})

编程式构建脚本

// scripts/build-all.ts
import { build, resolveConfig } from 'vitepress'

async function buildAll() {
  // 先解析配置
  const config = await resolveConfig('docs')
  console.log(`构建站点: ${config.site.title}`)

  // 执行构建
  await build('docs')
  console.log('构建完成！')
}

buildAll().catch(console.error)

参考链接

站点配置 - 完整配置选项
Frontmatter 配置 - 页面级配置
CLI 命令 - 命令行工具
运行时 API - 运行时 API
VitePress 官方文档

构建 API ​

defineConfig ​

类型签名 ​

基础用法 ​

异步配置 ​

环境感知配置 ​

配置拆分与组合 ​

build ​

类型签名 ​

参数 ​

基础用法 ​

CI/CD 集成 ​

构建选项 ​

createServer ​

类型签名 ​

参数 ​

ServerOptions ​

基础用法 ​

自定义开发服务器 ​

serve ​

类型签名 ​

参数 ​

ServeOptions ​

基础用法 ​

构建并预览 ​

resolveConfig ​

类型签名 ​

参数 ​

基础用法 ​

插件开发中使用 ​

UserConfig 接口 ​

UserConfig 逐字段详解 ​

ConfigEnv 接口 ​

ConfigEnv 逐字段详解 ​

环境感知配置示例 ​

SiteConfig 接口 ​

SiteConfig 逐字段详解 ​

构建钩子 ​

transformHead ​

transformPageData ​

transformHtml ​

buildEnd ​

postBuild ​

HeadConfig 类型 ​

IgnoreDeadLinksConfig 类型 ​

最佳实践 ​

配置文件组织 ​

类型安全 ​

编程式构建脚本 ​

参考链接 ​

📖 相关文章推荐

贡献者

构建 API

defineConfig

类型签名

基础用法

异步配置

环境感知配置

配置拆分与组合

build

类型签名

参数

基础用法

CI/CD 集成

构建选项

createServer

类型签名

参数

ServerOptions

基础用法

自定义开发服务器

serve

类型签名

参数

ServeOptions

基础用法

构建并预览

resolveConfig

类型签名

参数

基础用法

插件开发中使用

UserConfig 接口

UserConfig 逐字段详解

ConfigEnv 接口

ConfigEnv 逐字段详解

环境感知配置示例

SiteConfig 接口

SiteConfig 逐字段详解

构建钩子

transformHead

transformPageData

transformHtml

buildEnd

postBuild

HeadConfig 类型

IgnoreDeadLinksConfig 类型

最佳实践

配置文件组织

类型安全

编程式构建脚本

参考链接