VitePress 学习指南

主题

多语言支持 ​

VitePress 内置了国际化（i18n）支持，可以轻松创建多语言站点。

基础配置 ​

目录结构 ​

docs/
├── .vitepress/
│   └── config.mts
├── zh/                    # 中文文档
│   ├── guide/
│   │   └── index.md
│   └── index.md
├── en/                    # 英文文档
│   ├── guide/
│   │   └── index.md
│   └── index.md
└── index.md               # 默认语言首页

配置文件 ​

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

export default defineConfig({
  // 默认语言
  lang: 'zh-CN',
  
  // 国际化配置
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN',
      themeConfig: {
        nav: [
          { text: '首页', link: '/' },
          { text: '指南', link: '/guide/' }
        ],
        sidebar: {
          '/guide/': [
            {
              text: '入门指南',
              items: [
                { text: '介绍', link: '/guide/' }
              ]
            }
          ]
        },
        editLink: {
          pattern: 'https://github.com/user/repo/edit/main/docs/:path',
          text: '在 GitHub 上编辑此页'
        },
        footer: {
          message: '基于 MIT 许可发布',
          copyright: 'Copyright © 2026'
        },
        docFooter: {
          prev: '上一页',
          next: '下一页'
        },
        outline: {
          label: '页面导航'
        },
        lastUpdated: {
          text: '最后更新于'
        }
      }
    },
    en: {
      label: 'English',
      lang: 'en-US',
      link: '/en/',
      themeConfig: {
        nav: [
          { text: 'Home', link: '/en/' },
          { text: 'Guide', link: '/en/guide/' }
        ],
        sidebar: {
          '/en/guide/': [
            {
              text: 'Getting Started',
              items: [
                { text: 'Introduction', link: '/en/guide/' }
              ]
            }
          ]
        },
        editLink: {
          pattern: 'https://github.com/user/repo/edit/main/docs/:path',
          text: 'Edit this page on GitHub'
        },
        footer: {
          message: 'Released under the MIT License.',
          copyright: 'Copyright © 2026'
        },
        docFooter: {
          prev: 'Previous',
          next: 'Next'
        },
        outline: {
          label: 'On this page'
        },
        lastUpdated: {
          text: 'Last updated'
        }
      }
    }
  }
})

语言选择器 ​

语言选择器会自动显示在导航栏：

ts
locales: {
  root: {
    label: '简体中文',
    lang: 'zh-CN'
  },
  en: {
    label: 'English',
    lang: 'en-US',
    link: '/en/'
  },
  ja: {
    label: '日本語',
    lang: 'ja-JP',
    link: '/ja/'
  }
}

翻译策略 ​

方式一：每个语言独立配置 ​

ts
export default defineConfig({
  locales: {
    root: {
      lang: 'zh-CN',
      themeConfig: {
        nav: [
          { text: '首页', link: '/' }
        ]
      }
    },
    en: {
      lang: 'en-US',
      link: '/en/',
      themeConfig: {
        nav: [
          { text: 'Home', link: '/en/' }
        ]
      }
    }
  }
})

方式二：提取共享配置 ​

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

const sharedConfig = {
  logo: '/logo.svg',
  socialLinks: [
    { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
  ]
}

export default defineConfig({
  locales: {
    root: {
      lang: 'zh-CN',
      themeConfig: {
        ...sharedConfig,
        nav: [
          { text: '首页', link: '/' }
        ]
      }
    },
    en: {
      lang: 'en-US',
      link: '/en/',
      themeConfig: {
        ...sharedConfig,
        nav: [
          { text: 'Home', link: '/en/' }
        ]
      }
    }
  }
})

首页翻译 ​

docs/
├── index.md          # 中文首页
└── en/
    └── index.md      # 英文首页

docs/index.md:

markdown
---
layout: home

hero:
  name: VitePress
  text: 学习指南
  tagline: 从零开始学习 VitePress
  actions:
    - theme: brand
      text: 开始学习
      link: /guide/
---

docs/en/index.md:

markdown
---
layout: home

hero:
  name: VitePress
  text: Learning Guide
  tagline: Learn VitePress from scratch
  actions:
    - theme: brand
      text: Get Started
      link: /en/guide/
---

访问当前语言 ​

在组件中获取当前语言：

vue
<script setup>
import { useData } from 'vitepress'

const { lang, localeIndex } = useData()

const translations = {
  'zh-CN': {
    greeting: '你好'
  },
  'en-US': {
    greeting: 'Hello'
  }
}

const text = translations[lang]
</script>

<template>
  <p>{{ text.greeting }}</p>
</template>

处理缺失翻译 ​

当某语言的页面不存在时，可以配置回退：

ts
export default defineConfig({
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN'
    },
    en: {
      label: 'English',
      lang: 'en-US',
      link: '/en/'
    }
  }
})

注意

如果英文页面 /en/guide/advanced.md 不存在，访问时会显示 404。建议保持各语言页面同步。

重定向 ​

配置默认语言重定向：

ts
// docs/.vitepress/config.mts
export default defineConfig({
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN'
    }
  }
})

根路径 / 会自动使用 root 语言配置。

完整示例 ​

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

export default defineConfig({
  title: 'VitePress 学习指南',
  
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN',
      themeConfig: {
        logo: '/logo.svg',
        siteTitle: 'VitePress 学习指南',
        nav: [
          { text: '首页', link: '/' },
          { text: '入门指南', link: '/guide/' },
          { text: '基础功能', link: '/basics/' }
        ],
        sidebar: {
          '/guide/': [
            {
              text: '入门指南',
              items: [
                { text: '什么是 VitePress', link: '/guide/what-is-vitepress' },
                { text: '安装与环境配置', link: '/guide/installation' }
              ]
            }
          ]
        },
        editLink: {
          pattern: 'https://github.com/user/repo/edit/main/docs/:path',
          text: '在 GitHub 上编辑此页'
        },
        footer: {
          message: '基于 MIT 许可发布',
          copyright: 'Copyright © 2026'
        },
        docFooter: {
          prev: '上一页',
          next: '下一页'
        },
        outline: {
          label: '页面导航'
        },
        lastUpdated: {
          text: '最后更新于'
        },
        returnToTopLabel: '返回顶部',
        sidebarMenuLabel: '菜单',
        darkModeSwitchLabel: '主题'
      }
    },
    en: {
      label: 'English',
      lang: 'en-US',
      link: '/en/',
      themeConfig: {
        logo: '/logo.svg',
        siteTitle: 'VitePress Guide',
        nav: [
          { text: 'Home', link: '/en/' },
          { text: 'Guide', link: '/en/guide/' },
          { text: 'Basics', link: '/en/basics/' }
        ],
        sidebar: {
          '/en/guide/': [
            {
              text: 'Guide',
              items: [
                { text: 'What is VitePress', link: '/en/guide/what-is-vitepress' },
                { text: 'Installation', link: '/en/guide/installation' }
              ]
            }
          ]
        },
        editLink: {
          pattern: 'https://github.com/user/repo/edit/main/docs/:path',
          text: 'Edit this page on GitHub'
        },
        footer: {
          message: 'Released under the MIT License.',
          copyright: 'Copyright © 2026'
        },
        docFooter: {
          prev: 'Previous',
          next: 'Next'
        },
        outline: {
          label: 'On this page'
        },
        lastUpdated: {
          text: 'Last updated'
        },
        returnToTopLabel: 'Return to top',
        sidebarMenuLabel: 'Menu',
        darkModeSwitchLabel: 'Theme'
      }
    }
  }
})

下一步 ​

学习 搜索功能 来为站点添加搜索支持。

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南