构建 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'
})

异步配置

export default defineConfig(async () => {
  const data = await fetchPosts()
  return {
    // 使用异步数据
  }
})

环境感知配置

export default defineConfig(({ mode }) => {
  return {
    base: mode === 'production' ? '/docs/' : '/'
  }
})

build

编程式构建站点。

类型签名

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

用法

import { build } from 'vitepress'

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

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

构建选项

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

选项	类型	说明
outDir	string	输出目录，默认 .vitepress/dist
cacheDir	string	缓存目录
cleanUrls	boolean	清洁 URL

createServer

创建开发服务器实例。

类型签名

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

用法

import { createServer } from 'vitepress'

const server = await createServer('docs')

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

编程式开发

import { createServer } from 'vitepress'

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

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

serve

预览构建结果的服务器。

类型签名

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

用法

import { serve } from 'vitepress'

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

resolveConfig

解析配置文件，返回完整的配置对象。

类型签名

function resolveConfig(root?: string): Promise<SiteConfig>

用法

import { resolveConfig } from 'vitepress'

const config = await resolveConfig('docs')

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

UserConfig 接口

完整的用户配置类型定义：

interface UserConfig {
  // 站点配置
  title?: string
  titleTemplate?: string | boolean
  description?: string
  
  // 路由配置
  base?: string
  cleanUrls?: boolean
  rewrites?: Rewrite
  
  // 构建配置
  outDir?: string
  cacheDir?: string
  
  // Markdown 配置
  markdown?: MarkdownOptions
  
  // 国际化
  locales?: Locales
  defaultLang?: string
  
  // 主题配置
  themeConfig?: ThemeConfig
  
  // 构建钩子
  transformHead?: (ctx: TransformContext) => Awaitable<HeadConfig[]>
  transformHtml?: (code: string, id: string, ctx: TransformContext) => Awaitable<string | void>
  buildEnd?: (siteConfig: SiteConfig) => Awaitable<void>
  postBuild?: (siteConfig: SiteConfig) => Awaitable<void>
  
  // Vite 配置
  vite?: ViteConfig
}

ConfigEnv 接口

传递给配置函数的环境对象：

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

SiteConfig 接口

解析后的完整站点配置：

interface SiteConfig {
  // 用户配置
  userConfig: UserConfig
  
  // 站点配置
  site: SiteData
  
  // 路由配置
  rewrites: Rewrite[]
  
  // 构建配置
  outDir: string
  cacheDir: string
  
  // 临时文件
  tempDir: string
}

最佳实践

配置文件组织

// .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
})

参考链接

• 站点配置 - 完整配置选项
• CLI 命令 - 命令行工具
• VitePress 官方文档