使用 ServBay 创建并运行 VitePress 项目

VitePress 是一个现代化的静态网站生成器，由 Vue 提供支持，专为构建快速、美观且易于维护的文档网站而设计。它基于 Vite 构建，提供了卓越的开发体验和构建性能。对于需要为项目、库或产品创建专业文档的开发者来说，VitePress 是一个极佳的选择。

在本地进行 VitePress 开发和测试时，一个稳定且易于配置的本地 Web 开发环境至关重要。ServBay 正是为此而生，它集成了多种版本的 Node.js 环境以及强大的 Web 服务器（如 Caddy 或 Nginx），可以轻松地为您的 VitePress 项目提供服务。

本文将指导您如何利用 ServBay 的集成环境，从零开始创建、配置并运行一个 VitePress 项目，包括设置开发服务器的反向代理以及生产构建的静态文件服务。

什么是 VitePress？

VitePress 是一个基于 Vite 的静态网站生成器（SSG），它利用 Vue 3 的强大功能和 Vite 的极速性能来创建静态网站，尤其擅长构建技术文档。

VitePress 的主要特性和优势

• 极速开发体验: 借助 Vite 的热模块替换（HMR），修改内容后几乎可以立即在浏览器中看到更新，开发效率极高。
• 由 Vue 驱动: 支持在 Markdown 文件中直接使用 Vue 组件，极大地增强了文档的交互性和表现力。
• 简单易用: 配置简单，开箱即用，专注于内容创作。
• 高性能: 生成的静态文件体积小，加载速度快，结合内置的客户端路由，提供了单页应用的流畅体验。
• SEO 友好: 生成的 HTML 结构有利于搜索引擎抓取，且支持自定义头部标签。
• Markdown 增强: 支持 CommonMark 和 GitHub Flavored Markdown (GFM) 的所有功能，并提供了额外的语法糖。

使用 VitePress，开发者可以轻松地构建高质量、高性能的文档网站。

使用 ServBay 创建并运行 VitePress 项目

ServBay 提供了一个便捷的方式来管理 Node.js 版本，并配置 Web 服务器来服务您的 VitePress 项目，无论是开发模式下的本地服务器还是生产模式下的静态文件。

前提条件

在开始之前，请确保您已经完成以下准备工作：

1. 安装 ServBay: 您的 macOS 系统上已经成功安装了 ServBay。如果尚未安装，请参考 ServBay 安装指南.
2. 安装 Node.js 软件包: 在 ServBay 中，确保您已经安装并启用了所需的 Node.js 软件包版本。您可以通过 ServBay 控制面板的 "软件包" 页面进行管理。请参考 使用 Node.js.

创建 VitePress 项目

1. 初始化项目目录

   首先，打开您的终端应用程序。建议在 ServBay 的默认网站根目录 /Applications/ServBay/www 下创建项目文件夹，这样便于后续 ServBay 的网站配置。

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. 安装 VitePress 并初始化配置

   在项目目录 servbay-vitepress-app 中，使用 npm 或 yarn 安装 VitePress 作为开发依赖，并运行初始化命令。

   npm add -D vitepress
   npx vitepress init

   或使用 Yarn:

   yarn add -D vitepress
   yarn vitepress init

   初始化命令会引导您完成一些基本设置，例如网站标题、描述等。按照提示输入信息：

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # 默认文档目录，按回车确认即可
    │
    ◇  Site title:
    │  ServBay VitePress Demo # 输入您的网站标题，例如 ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # 输入网站描述
    │
    ◇  Theme:
    │  Default Theme # 选择主题，默认主题即可
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # 是否使用 TypeScript 配置，根据偏好选择
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # 是否添加脚本到 package.json，推荐选择 Yes
    │
    └  Done! Now run npm run docs:dev and start writing.

   初始化完成后，VitePress 会在 servbay-vitepress-app 目录下创建一个 docs 子目录，并在其中生成默认的配置文件 (.vitepress) 和示例页面 (index.md, guide/index.md 等)。同时，package.json 文件也会被更新，添加 docs:dev 和 docs:build 等脚本。

修改 VitePress 项目内容

1. 编辑首页内容

   VitePress 的默认首页文件位于 docs/index.md。您可以使用任何文本编辑器打开此文件，修改其内容。例如，将其修改为：

   # Hello ServBay!
   
   欢迎使用 ServBay 来运行您的 VitePress 文档网站。
   
   这是一个使用 VitePress 创建的本地演示站点，通过 ServBay 提供服务。

进入开发模式

在开发 VitePress 网站时，通常会使用其内置的开发服务器，它提供了热更新功能，方便实时预览修改。然后，我们利用 ServBay 的反向代理功能，通过一个自定义域名访问这个开发服务器，同时享受 ServBay 提供的 SSL 加密。

1. 运行 VitePress 开发服务器

   在终端中，确保您位于项目根目录 /Applications/ServBay/www/servbay-vitepress-app。运行以下命令启动开发服务器，并指定一个端口（例如 8585）。

   npm run docs:dev -- --port 8585

   或使用 Yarn:

   yarn docs:dev --port 8585

   开发服务器会启动并在本地监听指定的端口（例如 8585）。终端会显示服务器运行的本地地址，通常是 http://localhost:8585。

2. 配置 ServBay 网站（反向代理）

   打开 ServBay 控制面板，进入 "网站" 页面。点击添加新的网站配置。

   • 名字: 输入一个易于识别的名称，例如 VitePress 开发站点。
   • 域名: 输入您希望在浏览器中访问的本地开发域名。为了遵循 ServBay 的品牌规范和避免冲突，建议使用 .servbay.demo 后缀，例如 vitepress-dev.servbay.demo。
   • 网站类型: 选择 反向代理。
   • IP: 填写 127.0.0.1 （表示本地主机）。
   • 端口: 填写您在步骤 1 中指定的端口，例如 8585。

   完成配置后，保存并应用 ServBay 的更改。ServBay 会自动配置 Web 服务器（如 Caddy 或 Nginx）来将 https://vitepress-dev.servbay.demo 的请求转发到 http://127.0.0.1:8585。

3. 访问开发站点

   现在，您可以在浏览器中访问您配置的域名 https://vitepress-dev.servbay.demo。您将看到 VitePress 开发服务器提供的网站内容。通过 ServBay 的配置，您不仅使用了自定义域名，还自动获得了由 ServBay User CA 签发的 SSL 证书，实现了 HTTPS 安全访问。

构建生产版本

当您的 VitePress 文档开发完成并准备发布时，您需要构建一个优化的静态版本。

1. 构建生产版本

   在终端中，确保您位于项目根目录 /Applications/ServBay/www/servbay-vitepress-app。运行以下命令构建生产版本：

   npm run docs:build

   或使用 Yarn:

   yarn docs:build

   构建过程会将您的 Markdown 文件、Vue 组件等编译打包成一系列优化的静态 HTML、CSS、JavaScript 文件。构建完成后，生成的静态文件默认位于项目目录下的 docs/.vitepress/dist 目录中。

2. 设置 ServBay 网站（静态文件服务）

   生产版本的 VitePress 网站本质上是一组静态文件，因此可以使用 ServBay 的静态文件服务功能直接提供访问。

   打开 ServBay 控制面板，进入 "网站" 页面。点击添加新的网站配置。

   • 名字: 输入一个易于识别的名称，例如 VitePress 生产站点。
   • 域名: 输入您希望用于访问生产站点的本地域名，例如 vitepress-prod.servbay.demo。
   • 网站类型: 选择 静态。
   • 网站根目录: 填写您在步骤 1 中构建生成的静态文件所在的目录的绝对路径：/Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist。

   完成配置后，保存并应用 ServBay 的更改。ServBay 会配置 Web 服务器直接从指定的根目录提供静态文件服务。

3. 访问生产站点

   现在，您可以在浏览器中访问您配置的域名 https://vitepress-prod.servbay.demo。您将看到 VitePress 生产版本网站。同样，ServBay 会为您提供自定义域名和自动的 SSL 加密。

运行在简洁 URL 模式 (cleanUrls: true)

VitePress 支持 cleanUrls: true 配置，这意味着生成的页面链接将不包含 .html 扩展名（例如 /guide/ 而不是 /guide/index.html，或 /about 而不是 /about.html）。为了让 Web 服务器正确处理这类请求，需要进行额外的配置。

ServBay 使用 Caddy 或 Nginx 作为 Web 服务器。以下是针对 Caddy 的配置示例，它利用 try_files 指令来尝试查找对应的文件（包括 .html 扩展名或目录下的 index.html）。

1. 在 VitePress 配置中启用 cleanUrls

   编辑您的 VitePress 配置文件 (docs/.vitepress/config.mts 或 docs/.vitepress/config.ts)，在 siteConfig 中添加或修改 cleanUrls 选项：

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... 其他配置
     cleanUrls: true, // 启用简洁 URL
     // ... 其他配置
   })

   重新运行 npm run docs:build 构建生产版本。

2. 配置 ServBay 网站（使用自定义 Caddy 配置）

   打开 ServBay 控制面板，进入 "网站" 页面。找到您为 VitePress 生产站点配置的网站（例如 vitepress-prod.servbay.demo）。

   • 点击编辑按钮。
   • 勾选 自定义配置 选项。
   • 在 Caddy 配置 文本区域中，输入或粘贴以下配置内容。请注意，您需要将 servbay-vitepress-test.prod 替换为您实际使用的域名，并将 /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist 替换为您的实际网站根目录路径。

   # 替换为您实际的域名，例如 vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # 启用 Brotli (zstd) 和 Gzip 压缩，提高加载速度
       encode zstd gzip
   
       # 引入 ServBay 默认日志配置，方便调试
       import set-log vitepress-cleanurl.servbay.demo
   
       # 自动处理 ServBay 的内部 SSL 证书
       tls internal
   
       # 核心配置：尝试查找文件
       # 1. 尝试直接匹配路径 (e.g., /about -> /about)
       # 2. 尝试查找路径下的 index.html (e.g., /guide/ -> /guide/index.html)
       # 3. 尝试查找路径后加 .html 的文件 (e.g., /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # 设置网站的根目录
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # 启用静态文件服务
       file_server
   }

   保存并应用 ServBay 的更改。

3. 访问简洁 URL 模式站点

   现在，访问您配置的域名（例如 https://vitepress-cleanurl.servbay.demo）。对于启用 cleanUrls 的页面，您可以使用不带 .html 扩展名的 URL 进行访问，例如访问 about.html 页面时，可以直接访问 https://vitepress-cleanurl.servbay.demo/about。

总结

通过本文的指导，您已经学会了如何在 ServBay 环境下创建、开发和部署 VitePress 文档网站。ServBay 简化了 Node.js 环境的管理以及本地 Web 服务器的配置，无论是用于开发时的反向代理，还是用于生产构建的静态文件服务，都能轻松应对，并且自动提供便捷的自定义域名和 SSL 证书支持。

利用 ServBay 和 VitePress 的强大组合，您可以更高效地构建和维护高质量的技术文档。