安装与环境配置

本章节将指导你完成 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 即可预览网站。

编辑器推荐

VS Code 插件

推荐安装以下 VS Code 插件提升开发体验：

插件	用途	说明
VitePress Snippets	代码片段	快速插入 VitePress 模板
Markdown All in One	Markdown 增强	快捷键、目录、预览
Vue - Official	Vue 支持	Vue 语法高亮和智能提示
Prettier	代码格式化	统一代码风格

推荐配置

在项目根目录创建 .vscode/settings.json：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "markdown.validate.enabled": true,
  "files.associations": {
    "*.md": "markdown"
  }
}

常见问题

端口被占用

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

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

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

热更新不生效

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

npm install 速度慢

使用国内镜像加速：

# 临时使用
npm install -D vitepress --registry=https://registry.npmmirror.com

# 永久配置
npm config set registry https://registry.npmmirror.com

权限问题（macOS/Linux）

如果遇到 EACCES 权限错误，不要使用 sudo，推荐使用 nvm 管理 Node.js：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node.js
nvm install --lts

# 使用
nvm use --lts

TypeScript 项目配置

如果需要在 VitePress 中使用 TypeScript：

npm install -D typescript

创建 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "jsx": "preserve",
    "paths": {
      "@/*": ["./docs/.vitepress/theme/*"]
    }
  },
  "include": ["docs/.vitepress/**/*.ts"]
}

下一步

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

本章检查清单

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