速查表

VitePress 常用配置和语法的快速参考。

配置速查

基础配置

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '站点标题',
  description: '站点描述',
  lang: 'zh-CN',
  base: '/',           // 部署路径
  appearance: true,    // 主题切换
  cleanUrls: true,     // 清理 URL
  lastUpdated: true    // 显示更新时间
})

导航栏

themeConfig: {
  nav: [
    { text: '首页', link: '/' },
    { text: '指南', link: '/guide/' },
    {
      text: '更多',
      items: [
        { text: 'API', link: '/api/' },
        { text: 'GitHub', link: 'https://github.com' }
      ]
    }
  ]
}

侧边栏

themeConfig: {
  sidebar: {
    '/guide/': [
      {
        text: '入门',
        collapsed: false,
        items: [
          { text: '介绍', link: '/guide/' },
          { text: '安装', link: '/guide/installation' }
        ]
      }
    ]
  }
}

搜索

// 本地搜索
themeConfig: {
  search: { provider: 'local' }
}

// Algolia
themeConfig: {
  search: {
    provider: 'algolia',
    options: {
      appId: 'xxx',
      apiKey: 'xxx',
      indexName: 'xxx'
    }
  }
}

Markdown 语法

Frontmatter

---
title: 页面标题
description: 页面描述
layout: doc          # doc | page | home
sidebar: true
outline: [2, 3]
---

自定义容器

::: tip
提示信息
:::

::: warning
警告信息
:::

::: danger
危险信息
:::

::: details 标题
折叠内容
:::

代码块

```javascript {2-3}
function hello() {
  console.log('Hello')  // 高亮
  return true           // 高亮
}
```

```typescript [filename.ts]
const a: string = 'hello'
```

代码组

::: code-group

```bash [npm]
npm install package

yarn add package

pnpm add package

:::

### 表格

```markdown
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容 | 内容 | 内容 |

目录

[[toc]]

组件使用

内置组件

<!-- 徽章 -->
<Badge type="tip" text="新功能" />

<!-- 客户端渲染 -->
<ClientOnly>
  <div>{{ window.innerWidth }}</div>
</ClientOnly>

访问数据

<script setup>
import { useData, useRoute, useRouter } from 'vitepress'

const { page, frontmatter, isDark } = useData()
const route = useRoute()
const router = useRouter()
</script>

主题定制

CSS 变量

:root {
  /* 品牌色 */
  --vp-c-brand-1: #6366f1;
  --vp-c-brand-2: #4f46e5;
  --vp-c-brand-3: #4338ca;
  
  /* 首页渐变 */
  --vp-home-hero-name-background: linear-gradient(120deg, #6366f1, #818cf8);
}

.dark {
  --vp-c-brand-1: #818cf8;
}

布局插槽

<template>
  <Layout>
    <template #doc-before>
      内容前
    </template>
    <template #doc-after>
      内容后
    </template>
  </Layout>
</template>

常用命令

命令	说明
vitepress dev docs	启动开发服务器
vitepress build docs	构建生产版本
vitepress preview docs	预览构建结果

路由映射

文件	URL
index.md	/
guide.md	/guide
guide/index.md	/guide/
guide/start.md	/guide/start

常用插件

插件	用途
vitepress-plugin-mermaid	Mermaid 图表
markdown-it-mathjax3	数学公式
vite-plugin-pwa	PWA 支持
medium-zoom	图片缩放

部署平台

平台	配置文件
GitHub Pages	.github/workflows/deploy.yml
Vercel	vercel.json
Netlify	netlify.toml

环境变量

# 定义
VITE_API_URL=https://api.example.com

# 使用
const url = import.meta.env.VITE_API_URL

常见问题解决

问题	解决方案
图片不显示	放在 public/ 目录，使用 /image.png
端口被占用	配置 vite.server.port
链接 404	检查 base 配置
样式不生效	检查 CSS 变量选择器
构建失败	清除 .vitepress/cache 重试

目录结构

docs/
├── .vitepress/
│   ├── config.mts      # 配置文件
│   ├── theme/          # 主题目录
│   │   ├── index.ts
│   │   └── style.css
│   └── cache/          # 缓存目录
├── public/             # 静态资源
│   └── images/
├── guide/              # 文档目录
│   └── index.md
└── index.md            # 首页

---

提示

将此页面加入书签，方便随时查阅！