Vitepress 入门指南：从零开始构建文档网站

Vitepress 入门指南：从零开始构建文档网站

什么是 Vitepress？

Vitepress 是基于 Vue.js 和 Vite 的静态站点生成器，专为构建高性能文档网站而设计。它继承了 Vue 生态系统的优势，提供了开箱即用的 Markdown 支持、响应式主题和极快的热更新开发体验。

在线体验

无需安装任何环境，您可以直接在浏览器中体验 Vitepress 的功能。许多在线代码平台都支持 Vitepress 的即时预览功能，这是快速了解 Vitepress 特性的好方法。

环境准备

系统要求

• Node.js 18 或更高版本
• 终端命令行工具
• 支持 Markdown 的文本编辑器（推荐 VSCode 配合 Vue 官方插件）

安装方式

Vitepress 支持多种包管理器安装方式：

# npm
npm add -D vitepress

# pnpm
pnpm add -D vitepress

# yarn
yarn add -D vitepress

# bun
bun add -D vitepress

关于 ESM 的注意事项

Vitepress 是一个纯 ESM 模块，使用时需要注意：

• 不能使用 require() 导入
• 确保最近的 package.json 中包含 "type": "module"
• 或者将配置文件后缀改为 .mjs/.mts

项目初始化

Vitepress 提供了便捷的命令行向导帮助初始化项目：

# 使用 npm
npx vitepress init

# 使用 pnpm
pnpm vitepress init

# 使用 yarn
yarn vitepress init

# 使用 bun
bun vitepress init

初始化过程中会询问几个基本问题：

• 项目目录（默认为当前目录）
• 站点标题
• 站点描述
• 主题选择
• 是否自动添加 npm 脚本

关于 Vue 依赖

如果您计划使用 Vue 组件或 API 进行自定义开发，需要额外安装 Vue 作为项目依赖：

npm add vue

项目结构解析

典型的 Vitepress 项目结构如下：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

关键目录说明：

1. .vitepress 目录：包含配置、缓存和构建输出

   • config.js：主配置文件
   • cache：开发服务器缓存（建议加入.gitignore）
   • dist：生产构建输出（建议加入.gitignore）

2. Markdown 文件：作为内容源文件，会被编译为 HTML

配置文件详解

.vitepress/config.js 是 Vitepress 的核心配置文件，支持多种自定义选项：

export default {
  // 站点级配置
  title: '我的文档站',
  description: '使用Vitepress构建的文档网站',
  
  // 主题配置
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    sidebar: [
      {
        text: '指南',
        items: [
          { text: '介绍', link: '/guide/introduction' },
          { text: '快速开始', link: '/guide/getting-started' }
        ]
      }
    ]
  }
}

开发与构建

初始化后，package.json 会自动添加以下脚本：

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

开发模式

npm run docs:dev

启动开发服务器，默认访问地址为 http://localhost:5173。Vitepress 提供了极快的热模块替换(HMR)体验。

生产构建

npm run docs:build

构建后的静态文件默认输出到 .vitepress/dist 目录。

预览生产版本

npm run docs:preview

本地预览生产构建结果，用于最终检查。

Markdown 扩展功能

Vitepress 扩展了标准 Markdown 语法，支持：

1. Frontmatter：用于定义页面元数据

   ---
   title: 页面标题
   description: 页面描述
   ---
   

2. 代码块增强：

   ```js {1,3-5}
   // 高亮指定行
   

3. Vue 组件：可直接在 Markdown 中使用 Vue 组件

4. 自定义容器：

   ::: tip
   这是一个提示框
   :::
   

主题定制

Vitepress 提供了灵活的定制方案：

1. 扩展默认主题：覆盖默认主题的样式和组件
2. 完全自定义主题：从头开始创建专属主题
3. 布局组件：使用内置的 Layout、Home 等组件构建独特布局

部署建议

Vitepress 生成的静态站点可以部署到各种平台：

• 静态网站托管服务
• 传统 Web 服务器
• CI/CD 自动化部署流程

构建前确保：

• 正确配置了 base URL（针对非根部署）
• 测试了所有路由链接
• 验证了移动端显示效果

学习路径建议

1. 先熟悉基本 Markdown 编写
2. 了解路由和导航配置
3. 探索默认主题功能
4. 尝试简单定制（颜色、布局等）
5. 进阶学习自定义主题开发

Vitepress 结合了简单性和强大功能，无论是个人博客还是企业级文档，都能提供出色的解决方案。通过本指南，您应该已经掌握了 Vitepress 的基本使用方法，接下来可以深入探索其高级特性了。