快速开始

欢迎来到 VitePress 学习指南！本指南将帮助您在 5 分钟内创建第一个 VitePress 网站。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

Node.js 版本要求

VitePress 需要 Node.js 18 或更高版本：

# 检查 Node.js 版本
node --version
# 应该显示 v18.0.0 或更高版本

# 检查 npm 版本
npm --version

推荐使用 Node.js LTS 版本

建议使用 Node.js 的长期支持版本（LTS），以确保最佳的稳定性和兼容性。

包管理器选择

VitePress 支持多种包管理器：

• npm - Node.js 默认包管理器
• yarn - Facebook 开发的包管理器
• pnpm - 高性能的包管理器

创建第一个 VitePress 项目

方法一：使用脚手架工具

最简单的方式是使用 VitePress 官方脚手架：

# 使用 npm
npm create vitepress@latest my-vitepress-site

# 使用 yarn
yarn create vitepress my-vitepress-site

# 使用 pnpm
pnpm create vitepress my-vitepress-site

脚手架会询问几个配置问题：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs (recommended)
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme + Customization
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run npm install and npm run docs:dev

方法二：手动创建项目

如果您喜欢手动控制每个步骤：

# 1. 创建项目目录
mkdir my-vitepress-site
cd my-vitepress-site

# 2. 初始化 npm 项目
npm init -y

# 3. 安装 VitePress
npm install -D vitepress

# 4. 创建文档目录
mkdir docs

# 5. 创建第一个页面
echo '# Hello VitePress' > docs/index.md

项目结构

创建完成后，您的项目结构应该如下：

my-vitepress-site/
├── docs/
│   ├── .vitepress/
│   │   └── config.ts          # 配置文件
│   ├── index.md               # 首页
│   └── getting-started.md     # 其他页面
├── package.json
└── node_modules/

核心文件说明

• docs/ - 存放所有文档内容的目录
• docs/.vitepress/config.ts - VitePress 配置文件
• docs/index.md - 网站首页
• package.json - 项目依赖和脚本配置

基础配置

创建配置文件

在 docs/.vitepress/config.ts 中添加基础配置：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '我的 VitePress 网站',
  description: '使用 VitePress 构建的现代化文档网站',
  
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/getting-started' }
    ],
    
    sidebar: [
      {
        text: '开始使用',
        items: [
          { text: '快速开始', link: '/getting-started' },
          { text: '配置', link: '/config' }
        ]
      }
    ],
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/your-username/your-repo' }
    ]
  }
})

创建首页

编辑 docs/index.md 创建一个漂亮的首页：

---
layout: home

hero:
  name: "我的项目"
  text: "现代化文档网站"
  tagline: "使用 VitePress 构建的快速、简洁的文档站点"
  actions:
    - theme: brand
      text: 快速开始
      link: /getting-started
    - theme: alt
      text: 在 GitHub 查看
      link: https://github.com/your-username/your-repo

features:
  - title: 🚀 极速开发
    details: 基于 Vite 的即时热重载，让文档编写更高效
  - title: 📝 Markdown 增强
    details: 支持 Vue 组件、自定义容器等丰富功能
  - title: 🎨 主题定制
    details: 灵活的主题系统，轻松定制网站外观
---

启动开发服务器

添加 npm 脚本

在 package.json 中添加开发脚本：

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

启动服务器

# 启动开发服务器
npm run docs:dev

# 或者直接使用 VitePress 命令
npx vitepress dev docs

成功启动后，您会看到类似的输出：

  vitepress v1.6.4

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

现在打开浏览器访问 http://localhost:5173/，您就能看到您的第一个 VitePress 网站了！

添加更多内容

创建新页面

在 docs 目录下创建新的 Markdown 文件：

# 创建配置指南页面
echo '# 配置指南\n\n这里是配置相关的内容。' > docs/config.md

# 创建 API 文档页面
echo '# API 文档\n\n这里是 API 相关的文档。' > docs/api.md

更新导航和侧边栏

在 config.ts 中更新导航配置：

export default defineConfig({
  // ... 其他配置
  
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/getting-started' },
      { text: '配置', link: '/config' },
      { text: 'API', link: '/api' }
    ],
    
    sidebar: [
      {
        text: '开始使用',
        items: [
          { text: '快速开始', link: '/getting-started' },
          { text: '配置指南', link: '/config' }
        ]
      },
      {
        text: 'API 参考',
        items: [
          { text: 'API 文档', link: '/api' }
        ]
      }
    ]
  }
})

使用 Markdown 增强功能

VitePress 提供了许多 Markdown 增强功能：

自定义容器

::: tip 提示
这是一个提示容器
:::

::: warning 警告
这是一个警告容器
:::

::: danger 危险
这是一个危险警告容器
:::

::: info 信息
这是一个信息容器
:::

代码块增强

// 支持语法高亮和行号
function hello(name: string) {
  console.log(`Hello, ${name}!`)
}

hello('VitePress') 

在 Markdown 中使用 Vue

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

<!-- 计数器示例 -->

当前计数：{{ count }}

<button @click="count++">点击增加</button>

构建和部署

构建生产版本

# 构建静态文件
npm run docs:build

# 预览构建结果
npm run docs:preview

构建完成后，静态文件会生成在 docs/.vitepress/dist 目录中。

部署到 GitHub Pages

1. 在项目根目录创建 .github/workflows/deploy.yml：

name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm
          
      - name: Install dependencies
        run: npm ci
        
      - name: Build with VitePress
        run: npm run docs:build
        
      - name: Upload artifact
        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: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

2. 在 GitHub 仓库设置中启用 Pages 功能
3. 推送代码到 main 分支，自动部署

常见问题

开发服务器启动失败

检查 Node.js 版本是否满足要求（≥18），并确保端口 5173 未被占用。

页面样式显示异常

确保 config.ts 配置正确，特别是 base 路径配置。

图片无法显示

将图片放在 docs/public 目录下，然后使用 /image.svg 的方式引用。

如何添加自定义 CSS

创建 docs/.vitepress/theme/style.css 文件，并在主题配置中引入。

下一步

恭喜！您已经成功创建了第一个 VitePress 网站。接下来可以：

1. 学习站点配置 - 深入了解配置选项
2. 探索主题定制 - 定制网站外观
3. 查看实战案例 - 学习实际项目经验

---

如果遇到问题，欢迎查看 常见问题 或在 GitHub 上提问。