VitePress

简体中文

English

简体中文

English

主题

VitePress 指南 ​

VitePress 全面指南 - 由 Vite 和 Vue 驱动的现代静态站点生成器。

什么是 VitePress？ ​

VitePress 是一个静态站点生成器 (SSG)，旨在创建快速、以内容为中心的网站。它基于 Vite 和 Vue.js 构建，结合了两者的优点：Vite 的快速开发体验和 Vue 组件系统的强大功能。

主要特点 ​

  • ⚡ 闪电般速度：由 Vite 提供支持，实现即时热模块替换
  • 📝 以 Markdown 为中心：使用 Markdown 编写内容，支持 Vue 组件
  • 🎨 可定制：使用 Vue.js 的灵活主题系统
  • 🔍 内置搜索：开箱即用的本地搜索功能
  • 📱 移动优化：适用于所有设备的响应式设计
  • 🚀 生产就绪：优化构建，支持代码分割

入门指南 ​

安装 ​

bash
# 创建新项目
mkdir my-vitepress-site
cd my-vitepress-site

# 初始化 package.json
npm init -y

# 安装 VitePress
npm install -D vitepress

# 创建第一个文档
mkdir docs
echo '# Hello VitePress' > docs/index.md

基本配置 ​

创建 .vitepress/config.js：

js
export default {
  title: '我的 VitePress 站点',
  description: '由 Vite 和 Vue 驱动的 VitePress 站点',
  
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    
    sidebar: [
      {
        text: '入门指南',
        items: [
          { text: '介绍', link: '/introduction' },
          { text: '安装', link: '/installation' }
        ]
      }
    ]
  }
}

开发脚本 ​

添加到 package.json：

json
{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

启动开发服务器 ​

bash
npm run docs:dev

核心概念 ​

基于文件的路由 ​

VitePress 使用基于文件的路由。您的文件结构决定了站点的 URL 结构：

docs/
├── index.md          → /
├── guide/
│   ├── index.md      → /guide/
│   └── advanced.md   → /guide/advanced
└── api/
    └── reference.md  → /api/reference

前言 ​

使用 YAML 前言向页面添加元数据：

markdown
---
title: 自定义页面标题
description: 用于 SEO 的页面描述
layout: home
hero:
  name: VitePress
  text: 由 Vite 和 Vue 驱动的静态站点生成器
  actions:
    - theme: brand
      text: 开始使用
      link: /guide/
---

# 页面内容

您的 markdown 内容在这里。

Markdown 扩展 ​

VitePress 使用强大的功能扩展了标准 Markdown：

自定义容器 ​

markdown
::: info
这是一个信息框。
:::

::: tip
这是一个提示。
:::

::: warning
这是一个警告。
:::

::: danger
这是一个危险警告。
:::

::: details 点击我查看代码
```js
console.log('Hello, VitePress!')

:::


#### 代码组

```markdown
::: code-group

```js [config.js]
export default {
  title: 'VitePress'
}
ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'VitePress'
})

:::


#### 行高亮

```markdown
```js {2,4-6}
export default {
  title: 'VitePress', // 高亮
  description: '由 Vite 和 Vue 驱动的静态站点生成器',
  themeConfig: { // 高亮
    nav: [...] // 高亮
  } // 高亮
}

## 主题定制

### 默认主题

VitePress 自带一个漂亮的默认主题，您可以自定义：

```js
// .vitepress/config.js
export default {
  themeConfig: {
    logo: '/logo.svg',
    
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      {
        text: '下拉菜单',
        items: [
          { text: '项目 A', link: '/item-a' },
          { text: '项目 B', link: '/item-b' }
        ]
      }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: '章节 A',
          collapsed: false,
          items: [
            { text: '介绍', link: '/guide/introduction' },
            { text: '入门指南', link: '/guide/getting-started' }
          ]
        }
      ]
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: 'https://twitter.com/vuejs' }
    ],
    
    footer: {
      message: '基于 MIT 许可发布。',
      copyright: '版权所有 © 2024 Evan You'
    }
  }
}

自定义 CSS ​

使用自定义 CSS 覆盖默认样式：

css
/* .vitepress/theme/custom.css */
:root {
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
  --vp-c-brand-dark: #535bf2;
  --vp-c-brand-darker: #454ce1;
}

.custom-block {
  padding: 1rem;
  border-left: 4px solid var(--vp-c-brand);
  background-color: var(--vp-c-bg-soft);
}

自定义主题 ​

创建完全自定义的主题：

js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import CustomLayout from './CustomLayout.vue'
import './custom.css'

export default {
  extends: DefaultTheme,
  Layout: CustomLayout,
  enhanceApp({ app, router, siteData }) {
    // 注册全局组件
    app.component('CustomComponent', CustomComponent)
  }
}

高级功能 ​

多语言支持 ​

配置多种语言：

js
export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    zh: {
      label: '简体中文',
      lang: 'zh-CN',
      link: '/zh/',
      themeConfig: {
        nav: [
          { text: '首页', link: '/zh/' },
          { text: '指南', link: '/zh/guide/' }
        ]
      }
    }
  }
}

搜索集成 ​

本地搜索 ​

js
export default {
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        translations: {
          button: {
            buttonText: '搜索',
            buttonAriaLabel: '搜索'
          },
          modal: {
            noResultsText: '未找到结果',
            resetButtonTitle: '重置搜索'
          }
        }
      }
    }
  }
}

Algolia 搜索 ​

js
export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'YOUR_INDEX_NAME'
      }
    }
  }
}

PWA 支持 ​

启用渐进式 Web 应用功能：

js
export default {
  pwa: {
    mode: 'development',
    base: '/',
    scope: '/',
    includeAssets: ['favicon.ico'],
    manifest: {
      name: 'VitePress PWA',
      short_name: 'VitePressPWA',
      theme_color: '#ffffff',
      icons: [
        {
          src: 'pwa-192x192.png',
          sizes: '192x192',
          type: 'image/png'
        }
      ]
    }
  }
}

Markdown 中的 Vue 组件 ​

直接在 Markdown 文件中使用 Vue 组件：

markdown
# 我的页面

<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<div class="demo">
  <button @click="count++">计数：{{ count }}</button>
</div>

<style>
.demo {
  padding: 1rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}
</style>

常规 markdown 内容继续在这里。

全局组件 ​

全局注册组件：

js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import Badge from './components/Badge.vue'
import CodeGroup from './components/CodeGroup.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('Badge', Badge)
    app.component('CodeGroup', CodeGroup)
  }
}

然后在任何 Markdown 文件中使用它们：

markdown
# 特性

- 快速 <Badge type="tip" text="新" />
- 灵活 <Badge type="warning" text="测试版" />
- 强大 <Badge type="danger" text="已弃用" />

构建和部署 ​

生产构建 ​

bash
npm run docs:build

这会在 docs/.vitepress/dist/ 中生成静态文件。

部署选项 ​

GitHub Pages ​

yaml
# .github/workflows/deploy.yml
name: 部署 VitePress 站点到 Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4
        
      - name: 设置 Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm
          
      - name: 安装依赖
        run: npm ci
        
      - name: 使用 VitePress 构建
        run: npm run docs:build
        
      - name: 上传构建产物
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: 部署到 GitHub Pages
        uses: actions/deploy-pages@v4

Netlify ​

创建 netlify.toml：

toml
[build]
  command = "npm run docs:build"
  publish = "docs/.vitepress/dist"

[build.environment]
  NODE_VERSION = "18"

Vercel ​

创建 vercel.json：

json
{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vitepress/dist"
}

性能优化 ​

包分析 ​

bash
# 分析包大小
npx vitepress build docs --analyze

代码分割 ​

js
export default {
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['vue'],
            utils: ['lodash']
          }
        }
      }
    }
  }
}

资源优化 ​

js
export default {
  vite: {
    build: {
      assetsInlineLimit: 4096,
      cssCodeSplit: true
    }
  }
}

最佳实践 ​

内容组织 ​

  • 使用清晰、描述性的文件名
  • 在逻辑目录中组织内容
  • 保持一致的导航结构
  • 包含全面的元信息

性能 ​

  • 优化图像和资源
  • 对大型站点使用代码分割
  • 启用压缩和缓存
  • 定期监控包大小

SEO ​

  • 包含适当的元标签
  • 自动生成站点地图
  • 使用语义 HTML 结构
  • 优化核心网络指标

无障碍 ​

  • 为图像提供替代文本
  • 确保键盘导航正常工作
  • 保持适当的标题层次结构
  • 使用屏幕阅读器进行测试

故障排除 ​

常见问题 ​

构建错误

  • 检查 Node.js 版本（18+）
  • 验证配置语法
  • 确保所有依赖都已安装

路由问题

  • 验证文件结构是否与预期路由匹配
  • 检查基本 URL 配置
  • 确保正确的文件扩展名

性能问题

  • 分析包大小
  • 优化图像和资源
  • 审查第三方依赖

调试模式 ​

bash
# 启用调试日志
DEBUG=vitepress:* npm run docs:dev

# 详细构建输出
npm run docs:build -- --debug

迁移指南 ​

从 VuePress 迁移 ​

  1. 更新依赖：将 VuePress 替换为 VitePress
  2. 转换配置：更新配置格式
  3. 更新主题：调整自定义主题组件
  4. 彻底测试：验证所有功能是否正常工作

从其他 SSG 迁移 ​

  1. 内容转换：将内容转换为 Markdown
  2. 结构映射：将旧结构映射到 VitePress
  3. 功能对等：实现等效功能
  4. URL 保留：如果需要，设置重定向

社区和资源 ​

官方资源 ​

社区 ​

示例 ​

下一步 ​

VitePress 由 Vue.js 团队积极开发和维护。随时了解最新功能和改进！

vitepress开发指南

Copyright © 2025 mmwk.cn