创建第一个站点

跟随本教程，15分钟内创建你的第一个 VitePress 站点。

环境准备

检查 Node.js 版本

node --version
# 应该显示 v18.x 或更高

如果未安装，访问 nodejs.org 下载安装。

步骤 1：创建项目

创建项目目录

mkdir my-docs
cd my-docs

初始化项目

npm init -y

安装 VitePress

npm install -D vitepress

步骤 2：创建文档结构

创建目录结构

mkdir docs

my-docs/
├── docs/
│   └── index.md
├── package.json
└── node_modules/

创建首页

创建 docs/index.md：

---
layout: home
hero:
  name: 我的文档
  text: 第一个 VitePress 站点
  tagline: 开始你的文档之旅
  actions:
    - theme: brand
      text: 开始阅读
      link: /guide/
    - theme: alt
      text: GitHub
      link: https://github.com
features:
  - title: 🚀 简洁至上
    details: 以 Markdown 为中心的项目结构
  - title: 🎨 主题定制
    details: CSS 变量覆盖，轻松定制外观
  - title: ⚡ 极速体验
    details: 基于 Vite，毫秒级热更新
---

步骤 3：添加配置文件

创建配置目录

mkdir docs/.vitepress

创建配置文件

创建 docs/.vitepress/config.mts：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '我的文档',
  description: '第一个 VitePress 站点',
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    sidebar: {
      '/guide/': [
        {
          text: '开始',
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '安装', link: '/guide/installation' }
          ]
        }
      ]
    },
    socialLinks: [
      { icon: 'github', link: 'https://github.com' }
    ]
  }
})

步骤 4：添加更多页面

创建指南页面

创建 docs/guide/index.md：

# 介绍

欢迎使用 VitePress！

## 什么是 VitePress？

VitePress 是一个基于 Vue 和 Vite 的静态站点生成器。

## 为什么选择 VitePress？

- 🚀 极速的开发体验
- 🎨 灵活的主题定制
- 📦 开箱即用的功能

## 下一步

查看 [安装指南](/guide/installation) 开始使用。

创建安装页面

创建 docs/guide/installation.md：

# 安装

## 系统要求

- Node.js 18 或更高版本
- npm、yarn 或 pnpm

## 创建项目

\`\`\`bash
# 创建目录
mkdir my-docs
cd my-docs

# 初始化
npm init -y

# 安装 VitePress
npm install -D vitepress
\`\`\`

## 启动开发服务器

\`\`\`bash
npx vitepress dev docs
\`\`\`

## 构建生产版本

\`\`\`bash
npx vitepress build docs
\`\`\`

步骤 5：配置脚本

更新 package.json

{
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  },
  "devDependencies": {
    "vitepress": "^1.0.0"
  }
}

步骤 6：启动开发服务器

npm run dev

访问 http://localhost:5173 查看你的站点！

最终项目结构

my-docs/
├── docs/
│   ├── .vitepress/
│   │   └── config.mts
│   ├── guide/
│   │   ├── index.md
│   │   └── installation.md
│   └── index.md
├── package.json
└── node_modules/

下一步

• 添加导航和侧边栏 - 完善站点导航
• 自定义主题颜色 - 美化站点外观
• 部署到线上 - 发布你的站点

进阶挑战

完成基础教程后，尝试以下挑战来巩固知识：

挑战 1：添加一个「关于」页面

创建 docs/about.md，包含站点介绍和作者信息，并在导航栏添加链接。

查看提示

在 config.mts 的 nav 数组中添加 { text: '关于', link: '/about' }，然后创建对应的 Markdown 文件。

挑战 2：自定义站点主题色

通过 CSS 变量将站点的主色调从默认蓝色改为绿色。

查看提示

在 .vitepress/theme/index.ts 中导入自定义 CSS 文件，覆盖 --vp-c-brand 相关变量：

:root {
  --vp-c-brand: #42b883;
  --vp-c-brand-light: #42d392;
  --vp-c-brand-lighter: #35eb94;
  --vp-c-brand-dark: #33a06f;
  --vp-c-brand-darker: #2c8e62;
}

挑战 3：添加搜索功能

为站点启用本地搜索。

查看提示

在 config.mts 中添加：

themeConfig: {
  search: {
    provider: 'local'
  }
}

学习检查清单

完成以下任务，确认你已经掌握基础用法：

• [ ] 成功安装 VitePress
• [ ] 创建了首页并配置 Hero 区域
• [ ] 添加了配置文件（title、description、nav、sidebar）
• [ ] 创建了多个页面并验证路由正常
• [ ] 启动了开发服务器并访问站点
• [ ] 完成至少一个进阶挑战

常见问题

安装速度慢怎么办？

使用国内镜像加速：

npm config set registry https://registry.npmmirror.com
npm install -D vitepress

端口被占用如何处理？

VitePress 会自动尝试下一个可用端口。也可以手动指定：

npx vitepress dev docs --port 3000

首页没有显示 Hero 区域？

检查 docs/index.md 是否设置了 layout: home，且 hero 配置格式正确。

侧边栏没有显示？

确保 sidebar 配置中的 link 路径与实际文件路径匹配，路径不需要 .md 后缀。