VitePress 安装与配置教程：轻松搭建现代文档网站

VitePress 是一个基于 Vite 和 Vue 3 的静态网站生成器，特别适用于构建文档网站。它提供了快速的开发体验、即时热更新以及优秀的性能。本文将详细介绍如何安装和配置 VitePress，并通过实例代码帮助你快速上手。

一、安装前准备

在开始之前，请确保你已经安装了以下工具：

1. Node.js 版本 18 或更高。
2. 终端 用于访问 VitePress 的命令行界面（CLI）。
3. 文本编辑器 支持 Markdown 语法，推荐使用 VSCode，并安装官方 Vue 扩展。

二、安装 VitePress

VitePress 可以单独使用，也可以安装到现有项目中。无论哪种情况，你都可以通过以下包管理工具进行安装：

使用 npm:

$ npm add -D vitepress

使用 pnpm:

$ pnpm add -D vitepress

使用 yarn:

$ yarn add -D vitepress

使用 bun:

$ bun add -D vitepress

注意：VitePress 是一个 ESM（ECMAScript Module）包，不要使用 require() 来导入它。确保你的 package.json 中包含 "type": "module"，或者将相关文件的扩展名更改为 .mjs 或 .mts。

三、初始化项目

VitePress 提供了一个命令行设置向导，帮助你快速搭建基本项目。安装完成后，运行以下命令启动向导：

使用 npm:

$ npx vitepress init

使用 pnpm:

$ pnpm vitepress init

使用 yarn:

$ yarn vitepress init

使用 bun:

$ bun vitepress init

向导会询问你几个问题，例如配置文件的位置、网站标题、描述以及主题选择。根据你的需求进行选择即可。

四、项目结构

假设你选择将 VitePress 项目架构在 ./docs 目录下，生成的文件结构应如下所示：

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

docs 目录是 VitePress 站点的项目根目录，.vitepress 目录包含配置文件、开发服务器缓存、构建输出以及可选的主题定制代码。

五、配置文件

配置文件 .vitepress/config.js 允许你自定义 VitePress 站点的各个方面。最基本的配置选项包括站点的标题和描述：

// .vitepress/config.js
export default {
  title: 'VitePress',
  description: 'Just playing around.',
  themeConfig: {
    // 主题级选项
  }
}

你可以在 themeConfig 选项中配置主题的特定行为。有关所有配置选项的详细信息，请参阅配置引用。

六、源文件

.vitepress 目录之外的 Markdown 文件被视为源文件。VitePress 使用基于文件的路由：每个 .md 文件都会被编译成具有相同路径的相应 .html 文件。例如，index.md 将被编译为 index.html，并可以通过 VitePress 站点的根路径 / 访问。

七、启动开发服务器

如果允许设置向导修改你的 package.json，它会注入以下 npm 脚本：

{
  ...
  "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

开发服务器应运行在 http://localhost:5173。在浏览器中访问该 URL，即可查看你的新站点。

八、下一步

• 路由指南：了解 Markdown 文件如何映射到生成的 HTML。
• 写作指南：学习如何编写 Markdown 内容和使用 Vue 组件。
• 默认主题配置：探索默认文档主题提供的功能。
• 自定义主题：进一步定制你的站点外观。
• 部署指南：将你的文档网站部署到线上。

通过以上步骤，你已经成功安装并配置了 VitePress。现在，你可以开始撰写文档，并利用 VitePress 提供的强大功能，轻松搭建现代、高效的文档网站。