本地构建与预览文档：使用 VitePress 的指南

在开发文档或静态网站时，本地构建与预览是不可或缺的步骤。这允许我们在将内容推送到生产环境之前，确保一切看起来和功能都符合预期。本文将介绍如何使用 VitePress，一个静态网站生成器，来本地构建和预览文档。我们还将展示如何通过配置来更改预览服务器的端口。

一、VitePress 简介

VitePress 是一个由 Vue.js 提供支持的静态网站生成器，它利用了 Vite 的快速构建和即时热重载特性。VitePress 特别适合于撰写技术文档、博客或任何需要静态网站的内容。

二、安装与准备

在开始之前，请确保你的系统上已经安装了 Node.js 和 npm（或 yarn）。然后，你可以通过 npm 安装 VitePress：

npm install -g vitepress
# 或者使用 yarn
yarn global add vitepress

接下来，在你的项目目录中初始化一个 VitePress 项目：

vitepress init

这将创建一个包含基本目录结构和配置文件的新 VitePress 项目。

三、本地构建文档

要构建你的文档，你需要运行以下命令：

npm run docs:build
# 或者如果你使用的是 yarn
yarn docs:build

这个命令将根据你的配置和 Markdown 文件生成静态 HTML、CSS 和 JavaScript 文件，并将它们放置在 .vitepress/dist 目录中。

四、本地预览文档

一旦文档构建完成，你可以通过以下命令在本地预览它们：

npm run docs:preview
# 或者如果你使用的是 yarn
yarn docs:preview

默认情况下，这个命令将启动一个本地静态 Web 服务器，该服务器会在 http://localhost:4173 上提供 .vitepress/dist 目录中的内容。你可以在浏览器中打开这个地址来查看你的文档。

五、配置预览服务器端口

如果你想要更改预览服务器的端口，你可以通过修改 package.json 文件中的 scripts 部分来实现。例如，将端口更改为 8080：

{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}

现在，当你运行 npm run docs:preview 或 yarn docs:preview 时，预览服务器将在 http://localhost:8080 上启动。

六、实例代码与解释

以下是一个完整的 package.json 文件示例，其中包含了构建和预览文档的脚本，以及更改预览服务器端口的配置：

{
  "name": "my-vitepress-docs",
  "version": "1.0.0",
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs --port 8080"
  },
  "devDependencies": {
    "vitepress": "^x.x.x" // 请替换为实际的版本号
  }
}

在这个示例中，docs:build 脚本用于构建文档，docs:preview 脚本用于在本地预览文档，并且预览服务器的端口被配置为 8080。

七、总结

通过使用 VitePress，你可以轻松地在本地构建和预览文档。这不仅提高了开发效率，还允许你在将内容推送到生产环境之前进行充分的测试和验证。希望本文能够帮助你更好地利用 VitePress 来开发你的文档或静态网站。