VitePress实战：从零到一构建高效技术文档与个人博客

1. 为什么选择 VitePress？从“能用”到“好用”的体验升级

如果你和我一样，是个喜欢折腾技术、又有点“懒”的开发者，那你肯定也受够了搭建文档和博客的繁琐。几年前，我还在用 Hexo、VuePress，虽然它们也不错，但每次启动开发服务器要等好几秒，改个配置还得手动刷新，那种等待的感觉，就像在等一壶烧开的水，急人。后来，我遇到了 VitePress，说实话，第一次用的时候，那种“秒开”的体验真的让我惊到了。我敲下 npm run docs:dev，几乎是命令回车的同时，浏览器页面就加载好了，而且修改 Markdown 文件后，热更新快得几乎无感。这种流畅感，就是 Vite 带来的核心优势。

VitePress 本质上是一个静态网站生成器，但它和那些老牌工具最大的不同在于它的“心脏”——Vite。Vite 是下一代前端构建工具，它利用浏览器原生 ES 模块导入，彻底改变了开发服务器的启动方式。这意味着，无论你的项目有多少个页面，启动速度都极快，而且热更新（HMR）的效率极高。对于写技术文档和博客这种需要频繁预览的场景，这个优势被无限放大。你不再需要分心去等待构建，可以完全沉浸在内容创作里。

除了速度，VitePress 另一个让我爱不释手的功能是“Vue 增强的 Markdown”。这听起来有点抽象，我举个实际的例子你就明白了。有一次，我需要在我的项目文档里嵌入一个可交互的 Vue 组件，用来演示一个 API 的调用效果。在传统的静态站点里，这几乎不可能，或者需要非常复杂的 hack。但在 VitePress 里，这变得异常简单。我直接在 Markdown 文件里写了一个 <script setup> 标签，引入了我的 Vue 组件，然后像在普通 .vue 文件里一样使用它。最终生成的页面，不仅展示了我的说明文字，还完美运行了那个交互式组件。这让技术文档的“表现力”上了一个大台阶，读者不再是看枯燥的文字，而是能动手试一试，理解起来快多了。

当然，VitePress 的生态也足够成熟。Vue 3、Vite、Pinia、Vite 这些我们耳熟能详的顶级开源项目的官方文档，清一色都是用 VitePress 构建的。这本身就是一种强大的背书。跟着“大佬”们用同一个工具，意味着你踩的坑，大概率他们已经踩过并填平了；你需要的功能，很可能官方主题或者社区插件已经提供了。这种站在巨人肩膀上的感觉，能让你的搭建过程事半功倍。

2. 十分钟快速上手：创建你的第一个 VitePress 站点

光说不练假把式，咱们直接动手。我保证，即使你之前没接触过 VitePress，跟着我的步骤，十分钟内也能看到一个本地运行的站点。

首先，你需要一个 Node.js 环境，版本建议在 16 或以上。这个应该大家都有。然后，找一个你喜欢的目录，打开终端，我们开始初始化项目。这里有两种主流方式，我都介绍一下，你可以选你顺手的。

方法一：使用官方脚手架（推荐给新手） 这是最无脑的方式，一行命令搞定所有初始化工作。

npm create vitepress@latest

运行这个命令后，它会问你几个问题，比如项目目录叫什么名字（默认是 vitepress-project），是否使用 TypeScript，要不要初始化 Git 等等。你一路按回车用默认值，或者根据自己喜好选择就行。整个过程非常快，完成后，它会提示你进入项目目录并安装依赖。

方法二：手动初始化（推荐给喜欢掌控一切的你） 我更偏爱这种方式，因为结构更清晰。我们先创建一个空目录，并初始化 package.json。

mkdir my-vitepress-site && cd my-vitepress-site
npm init -y

然后，安装 VitePress 和 Vue 作为依赖。注意，VitePress 是开发依赖。

npm install -D vitepress vue

安装完成后，我们需要创建最基本的项目结构。在项目根目录下，创建一个 docs 文件夹，这将是存放我们所有文档和博客内容的地方。然后在 docs 里创建第一个 Markdown 文件 index.md，这就是网站的主页。同时，我们还需要一个配置文件 docs/.vitepress/config.mjs（注意是 .mjs 后缀，这是为了支持 ES 模块）。

现在，你的目录结构应该看起来像这样：

my-vitepress-site/
├── docs/
│   ├── .vitepress/
│   │   └── config.mjs
│   └── index.md
└── package.json

接下来，我们来写点内容。打开 docs/index.md 文件，输入以下内容：

# 你好，VitePress！

这是我的第一个 VitePress 站点。

- **快**：由 Vite 驱动。
- **简单**：用 Markdown 写作。
- **强大**：支持 Vue 组件。

然后，打开 docs/.vitepress/config.mjs，写入最基本的配置：

export default {
  title: '我的技术空间', // 网站标题
  description: '一个记录技术与思考的地方', // 网站描述
  themeConfig: {
    nav: [ // 导航栏
      { text: '首页', link: '/' },
      { text: '博客',