配置文件详解

VitePress 的配置文件位于 docs/.vitepress/config.mts，用于配置站点的全局行为。

配置文件基础

文件位置

docs/
├── .vitepress/
│   └── config.mts    # 配置文件

基础结构

import { defineConfig } from 'vitepress'

export default defineConfig({
  // 站点配置
  title: '我的站点',
  description: '站点描述',
  
  // 主题配置
  themeConfig: {
    // ...
  }
})

站点级配置

基础信息

export default defineConfig({
  // 站点标题
  title: 'VitePress 学习指南',
  
  // 站点描述（用于 SEO）
  description: '从零开始学习 VitePress',
  
  // 站点语言
  lang: 'zh-CN',
  
  // 网站基础路径
  base: '/docs/',
  
  // 自定义 head 标签
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }],
    ['meta', { name: 'theme-color', content: '#3eaf7c' }]
  ]
})

外观设置

export default defineConfig({
  // 主题切换：true | false | 'force-dark' | 'force-light'
  appearance: true,
  
  // 最后更新时间
  lastUpdated: true,
  
  // 清理 URL 中的 .html 后缀
  cleanUrls: true
})

Markdown 配置

export default defineConfig({
  markdown: {
    // 主题配置
    theme: 'github-dark',
    
    // 行号
    lineNumbers: true,
    
    // 数学公式
    math: true,
    
    // 自定义锚点
    anchor: {
      permalink: true
    }
  }
})

主题配置

导航栏

export default defineConfig({
  themeConfig: {
    // 站点 Logo
    logo: '/logo.svg',
    
    // 站点链接（显示在导航栏标题旁）
    siteTitle: 'VitePress 学习指南',
    
    // 导航栏菜单
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      { 
        text: '参考',
        items: [
          { text: '配置', link: '/reference/config' },
          { text: 'API', link: '/reference/api' }
        ]
      }
    ]
  }
})

侧边栏

基础配置

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: '入门指南',
        items: [
          { text: '介绍', link: '/guide/' },
          { text: '安装', link: '/guide/installation' }
        ]
      }
    ]
  }
})

多侧边栏

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: '入门指南',
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '安装', link: '/guide/installation' }
          ]
        }
      ],
      '/api/': [
        {
          text: 'API 参考',
          items: [
            { text: '配置', link: '/api/config' }
          ]
        }
      ]
    }
  }
})

可折叠分组

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: '入门指南',
        collapsed: false,  // 默认展开
        items: [
          { text: '介绍', link: '/guide/' }
        ]
      }
    ]
  }
})

社交链接

export default defineConfig({
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: 'https://twitter.com/vuejs' },
      { icon: 'discord', link: 'https://discord.gg/vue' }
    ]
  }
})

页脚

export default defineConfig({
  themeConfig: {
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2026 我的站点'
    }
  }
})

编辑链接

export default defineConfig({
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
      text: '在 GitHub 上编辑此页'
    }
  }
})

文档页脚

export default defineConfig({
  themeConfig: {
    docFooter: {
      prev: '上一页',
      next: '下一页'
    }
  }
})

大纲配置

export default defineConfig({
  themeConfig: {
    outline: {
      label: '页面导航',
      level: [2, 3]  // 显示 h2 和 h3
    }
  }
})

国际化文本

export default defineConfig({
  themeConfig: {
    returnToTopLabel: '返回顶部',
    sidebarMenuLabel: '菜单',
    darkModeSwitchLabel: '主题',
    lightModeSwitchTitle: '切换到浅色模式',
    darkModeSwitchTitle: '切换到深色模式'
  }
})

搜索配置

本地搜索

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        translations: {
          button: {
            buttonText: '搜索文档',
            buttonAriaLabel: '搜索文档'
          },
          modal: {
            noResultsText: '没有找到结果',
            resetButtonTitle: '清除搜索',
            footer: {
              selectText: '选择',
              navigateText: '切换'
            }
          }
        }
      }
    }
  }
})

Vite 配置

传递 Vite 配置：

export default defineConfig({
  vite: {
    // Vite 配置
    server: {
      port: 3000
    },
    build: {
      minify: 'terser'
    }
  }
})

完整配置示例

import { defineConfig } from 'vitepress'

export default defineConfig({
  // 站点配置
  title: 'VitePress 学习指南',
  description: '从零开始学习 VitePress',
  lang: 'zh-CN',
  base: '/',
  appearance: true,
  lastUpdated: true,
  cleanUrls: true,
  
  // Head 标签
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }]
  ],
  
  // Markdown 配置
  markdown: {
    lineNumbers: true,
    math: true
  },
  
  // 主题配置
  themeConfig: {
    logo: '/logo.svg',
    siteTitle: 'VitePress 学习指南',
    
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: '入门指南',
          items: [
            { text: '介绍', link: '/guide/' }
          ]
        }
      ]
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
    ],
    
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2026'
    },
    
    outline: {
      label: '页面导航',
      level: [2, 3]
    },
    
    search: {
      provider: 'local'
    }
  }
})

下一步

接下来学习 导航栏配置 的详细设置。