安装与环境配置

本章节将指导你完成 VitePress 的安装和基本环境配置。

环境要求

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

• Node.js: 版本 18 或更高
• 包管理器: npm、yarn 或 pnpm

检查 Node.js 版本

node -v
# 输出应该 >= 18.0.0

注意

如果你的 Node.js 版本过低，请先升级。推荐使用 LTS 版本。

创建项目

方式一：手动创建（推荐学习）

手动创建可以帮助你更好地理解项目结构。

npm

# 创建项目目录
mkdir my-docs
cd my-docs

# 初始化 package.json
npm init -y

# 安装 VitePress
npm add -D vitepress

pnpm

# 创建项目目录
mkdir my-docs
cd my-docs

# 初始化 package.json
pnpm init

# 安装 VitePress
pnpm add -D vitepress

yarn

# 创建项目目录
mkdir my-docs
cd my-docs

# 初始化 package.json
yarn init

# 安装 VitePress
yarn add -D vitepress

方式二：使用脚手架

npx vitepress init

配置 package.json

添加常用的脚本命令：

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

创建目录结构

mkdir docs

创建以下文件结构：

docs/
├── .vitepress/
│   └── config.mts    # 配置文件
├── index.md          # 首页
└── about.md          # 关于页面

创建配置文件

在 docs/.vitepress/ 目录下创建 config.mts：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '我的文档站',
  description: '一个 VitePress 文档站'
})

创建首页

在 docs/ 目录下创建 index.md：

---
layout: home

hero:
  name: 我的文档
  text: 欢迎来到我的文档站
  tagline: 使用 VitePress 构建
  actions:
    - theme: brand
      text: 开始阅读
      link: /about
---

启动开发服务器

npm run docs:dev

访问 http://localhost:5173 即可预览网站。

常见问题

端口被占用

如果默认端口被占用，VitePress 会自动尝试下一个可用端口。

你也可以在配置中指定端口：

export default defineConfig({
  vite: {
    server: {
      port: 3000
    }
  }
})

热更新不生效

检查文件是否在正确的目录下，确保文件扩展名为 .md。

下一步

环境配置完成后，让我们了解 项目结构解析。

本章检查清单

0 / 8 已完成

0%

环境准备

• 确认 Node.js 版本 >= 18
• 选择并安装包管理器（npm / yarn / pnpm）

项目创建

• 手动创建项目目录和初始化 package.json
• 成功安装 VitePress 依赖
• 配置 docs:dev、docs:build、docs:preview 脚本命令

基础配置与启动

• 创建 config.mts 基础配置文件（title + description）
• 创建 index.md 首页并设置 layout: home
• 启动开发服务器并能正常访问 http://localhost:5173