站点配置

VitePress 配置文件的完整 API 参考。

快速导航： 站点配置 | 主题配置 | 构建钩子 | Vite 配置 | 完整配置示例

站点配置

基础配置

interface SiteConfig {
  // 站点标题
  title: string
  
  // 标题模板
  titleTemplate?: string | boolean
  
  // 站点描述
  description: string
  
  // 站点语言
  lang?: string
  
  // 基础路径
  base?: string
  
  // 主题切换
  appearance?: boolean | 'dark' | 'force-dark' | 'force-light'
  
  // 清理 URL
  cleanUrls?: boolean
  
  // 最后更新时间
  lastUpdated?: boolean | LastUpdatedOptions
  
  // 忽略死链接
  ignoreDeadLinks?: boolean | string[] | IgnoreDeadLinksConfig
}

Head 配置

export default defineConfig({
  head: [
    // Favicon
    ['link', { rel: 'icon', href: '/favicon.ico' }],
    
    // Meta 标签
    ['meta', { name: 'theme-color', content: '#fff' }],
    ['meta', { name: 'viewport', content: 'width=device-width, initial-scale=1' }],
    
    // Open Graph
    ['meta', { property: 'og:title', content: 'My Site' }],
    ['meta', { property: 'og:description', content: 'Description' }],
    
    // 脚本
    ['script', { src: '/analytics.js', async: true }]
  ]
})

Markdown 配置

export default defineConfig({
  markdown: {
    // 语法高亮主题
    theme: 'github-dark' | 'github-light' | {
      light: 'github-light',
      dark: 'github-dark'
    },
    
    // 行号
    lineNumbers: boolean,
    
    // 数学公式
    math: boolean | MathOptions,
    
    // 自定义配置
    config: (md) => {
      // 使用 markdown-it 插件
      md.use(require('markdown-it-plugin'))
    },
    
    // 锚点配置
    anchor: {
      permalink: true
    },
    
    // 目录配置
    toc: {
      level: [1, 2, 3]
    }
  }
})

主题配置

导航配置

interface NavItem {
  text: string
  link?: string
  items?: NavItem[]
  activeMatch?: string
  target?: string
  rel?: string
}

export default defineConfig({
  themeConfig: {
    // Logo
    logo: string | { light: string, dark: string },
    
    // 站点标题
    siteTitle: string | false,
    
    // 导航栏
    nav: NavItem[]
  }
})

侧边栏配置

interface SidebarItem {
  text?: string
  items?: SidebarItem[]
  link?: string
  collapsed?: boolean
  base?: string
}

export default defineConfig({
  themeConfig: {
    sidebar: SidebarItem[] | Record<string, SidebarItem[]>
  }
})

搜索配置

export default defineConfig({
  themeConfig: {
    search: {
      // 本地搜索
      provider: 'local',
      options: {
        detailedView: boolean,
        miniSearch: {
          searchOptions: {
            fuzzy: number
          }
        }
      }
    } | {
      // Algolia 搜索
      provider: 'algolia',
      options: {
        appId: string,
        apiKey: string,
        indexName: string
      }
    }
  }
})

文档配置

export default defineConfig({
  themeConfig: {
    // 大纲配置
    outline: {
      label: string,
      level: number | [number, number]
    },
    
    // 文档页脚
    docFooter: {
      prev: string,
      next: string
    },
    
    // 编辑链接
    editLink: {
      pattern: string,
      text: string
    },
    
    // 最后更新
    lastUpdated: {
      text: string,
      formatOptions: Intl.DateTimeFormatOptions
    }
  }
})

社交链接

export default defineConfig({
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com' },
      { icon: 'twitter', link: 'https://twitter.com' },
      { 
        icon: { svg: '<svg>...</svg>' },
        link: 'https://custom.com'
      }
    ]
  }
})

国际化配置

export default defineConfig({
  locales: {
    '/': {
      lang: 'zh-CN',
      label: '简体中文',
      title: '标题',
      description: '描述',
      themeConfig: {
        // 语言特定的主题配置
      }
    },
    '/en/': {
      lang: 'en-US',
      label: 'English',
      title: 'Title',
      description: 'Description'
    }
  }
})

构建钩子

transformHead

export default defineConfig({
  transformHead({ pageData, siteConfig }) {
    return [
      ['meta', { name: 'author', content: 'Author Name' }]
    ]
  }
})

transformPageData

export default defineConfig({
  transformPageData(pageData, { siteConfig }) {
    pageData.frontmatter.layout ??= 'doc'
    pageData.frontmatter.lastUpdated ??= new Date().toISOString()
  }
})

transformHtml

export default defineConfig({
  transformHtml(code, id, { pageData }) {
    if (id.endsWith('.html')) {
      // 修改 HTML
      return code.replace('</head>', '<!-- custom -->\n</head>')
    }
  }
})

Vite 配置

export default defineConfig({
  vite: {
    // Vite 配置
    server: {
      port: 3000
    },
    build: {
      minify: 'esbuild'
    },
    plugins: [
      // Vite 插件
    ]
  }
})

完整配置示例

import { defineConfig } from 'vitepress'

export default defineConfig({
  // 站点元数据
  title: 'VitePress 学习指南',
  description: '从零开始学习 VitePress',
  lang: 'zh-CN',
  base: '/',
  
  // 外观
  appearance: true,
  cleanUrls: true,
  lastUpdated: true,
  
  // Head 标签
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }],
    ['meta', { name: 'theme-color', content: '#6366f1' }]
  ],
  
  // Markdown 配置
  markdown: {
    lineNumbers: true,
    theme: 'github-dark'
  },
  
  // 主题配置
  themeConfig: {
    logo: '/logo.svg',
    siteTitle: 'VitePress 学习指南',
    
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: '入门指南',
          items: [
            { text: '介绍', link: '/guide/' }
          ]
        }
      ]
    },
    
    search: {
      provider: 'local'
    },
    
    outline: {
      label: '页面导航',
      level: [2, 3]
    },
    
    editLink: {
      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
      text: '编辑此页'
    },
    
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2026'
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
    ]
  },
  
  // 构建钩子
  transformPageData(pageData) {
    pageData.frontmatter.lastUpdated = new Date().toISOString()
  }
})

其他配置选项

srcDir

类型：string
默认值：项目根目录

指定文档源目录，允许将配置文件放在项目根目录而文档放在子目录。

export default defineConfig({
  srcDir: './docs'  // 文档在 docs/ 目录下
})

srcExclude

类型：string[]
默认值：[]

排除指定的源文件，不参与构建。

export default defineConfig({
  srcExclude: ['**/drafts/**', '**/private/**']
})

outDir

类型：string
默认值：.vitepress/dist

构建输出目录。

export default defineConfig({
  outDir: '../public'  // 输出到上级 public 目录
})

cacheDir

类型：string
默认值：.vitepress/cache

构建缓存目录。

ignoreDeadLinks

类型：boolean | 'localhostLinks' | string[] | IgnoreDeadLinksConfig
默认值：false

忽略死链接检查。

export default defineConfig({
  // 忽略所有死链接
  ignoreDeadLinks: true,
  
  // 仅忽略 localhost 链接
  ignoreDeadLinks: 'localhostLinks',
  
  // 忽略特定路径
  ignoreDeadLinks: ['/api/', '/legacy/'],
  
  // 高级配置
  ignoreDeadLinks: (url) => {
    return url.startsWith('http://localhost')
  }
})

metaChunk

类型：boolean
默认值：false

将页面元数据拆分为独立 chunk，有助于减小首屏加载体积。

export default defineConfig({
  metaChunk: true
})

sitemap

类型：SitemapOptions
默认值：{ hostname: site URL }

生成 sitemap 配置。

export default defineConfig({
  sitemap: {
    hostname: 'https://example.com',
    lastmodDateOnly: true,
    changefreq: 'weekly',
    priority: 0.7
  }
})

robots

类型：RobotsOptions
默认值：无

生成 robots.txt 配置。

export default defineConfig({
  robots: {
    allow: ['/'],
    disallow: ['/private/', '/draft/']
  }
})

postBuild

类型：(siteConfig: SiteConfig) => Awaitable<void>

构建完成后的回调，用于执行后续操作。

export default defineConfig({
  async postBuild(siteConfig) {
    // 生成额外的 JSON 数据
    // 发送构建通知
    // 上传到 CDN
  }
})

站点配置

站点配置

基础配置

Head 配置

Markdown 配置

主题配置

导航配置

侧边栏配置

搜索配置

文档配置

社交链接

国际化配置

构建钩子

transformHead

transformPageData

transformHtml

Vite 配置

完整配置示例

相关链接

其他配置选项

srcDir

srcExclude

outDir

cacheDir

ignoreDeadLinks

metaChunk

sitemap

robots

postBuild

贡献者

站点配置 ​

站点配置 ​

基础配置 ​

Head 配置 ​

Markdown 配置 ​

主题配置 ​

导航配置 ​

侧边栏配置 ​

搜索配置 ​

文档配置 ​

社交链接 ​

国际化配置 ​

构建钩子 ​

transformHead ​

transformPageData ​

transformHtml ​

Vite 配置 ​

完整配置示例 ​

相关链接 ​

其他配置选项 ​

srcDir ​

srcExclude ​

outDir ​

cacheDir ​

ignoreDeadLinks ​

metaChunk ​

sitemap ​

robots ​

postBuild ​

📖 相关文章推荐

贡献者

站点配置

站点配置

基础配置

Head 配置

Markdown 配置

主题配置

导航配置

侧边栏配置

搜索配置

文档配置

社交链接

国际化配置

构建钩子

transformHead

transformPageData

transformHtml

Vite 配置

完整配置示例

相关链接

其他配置选项

srcDir

srcExclude

outDir

cacheDir

ignoreDeadLinks

metaChunk

sitemap

robots

postBuild