前言

当我们通过 VitePress 完成自己的一个静态站点之后，需要供他人或自己学习和访问的时候，一个最简单的方式就是部署到 GitHub Pages，通过 GitHub Actions 机制，每当我们提交代码到指定的分支，GitHub 仓库中的代码就会自动构建和部署。

部署前的准备工作

参照 Vitepress 官网的部署指南，我们应该认真核对以下注意事项：

1. VitePress 项目应该位于 docs 目录中

2. 使用的是默认的生成输出目录 .vitepress/dist

3. VitePress 作为本地依赖项安装在项目中，并且在 package.json 文件中应该至少包含以下脚本

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

本地构建与测试

我们在正式部署项目之前，可以先在本地进行构建，然后进行构建之后的项目预览，看是否符合预期。

首先，我们可以在命令行终端执行 npm run docs:build 进行本地构建，运行完此命令后就会在 docs 目录下生成一个 .vitepress 文件。

然后继续在命令行终端输入 npm run docs:preview 就可以在本地预览构建完成的项目。

这是因为 preview 命令将会启动一个本地的静态 Web 服务，该服务以 .vitepress/dist 为源文件，进行此操作是检查生产版本在本地环境中是否正常运行的一种常规行为。

运行完上述命令后，服务就会在 http://localhost:4173 启动。

可以通过修改脚本 vitepress preview docs --port 8080 通过传递 --port 作为参数来配置服务器的端口，配置完后重新执行 npm run docs:preview，项目就会在 http://localhost:8080 启动。

部署到 GitHub Pages

在项目根目录创建 .github 文件夹，然后在其中创建 workflows 目录，新建 deploy.yml 文件。

文件中应包含以下内容：

# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
name: Deploy VitePress site to Pages

on:
  # 在针对 `main` 分支的推送上运行
  # 如果是使用 `master` 分支作为默认分支，请将其更改为 `master`
  push:
    branches: [master]

  # 允许你从 Actions 选项卡手动运行此工作流程
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # 构建工作
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
      # - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消注释
      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm # 或 pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci # 或 pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  # 部署工作
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

然后进入到 GitHub 中的 Settings 页面，点击左侧的 Pages 菜单，在 Build and deployment 标题下，选择 Source 为 GitHub Actions。

最后当我们把本地代码推送到 GitHub 上的 master 分支时，就会触发 GitHub Actions 自动进入构建和部署工作流中。我们可以点击 Actions 选项，检查项目是否部署成功。

虽然显示部署成功，但值得注意的是，当我打开第一次部署完毕之后网址，样式是丢失的。

因为我部署之后的地址为 https://vaesonshu.github.io/vitepress-template，然后查看 VitePress 官网部署指南中的设定 public 根目录这一部分得知，我需要在 VitePress 配置中将 base 这一选项设置为 '/vitepress-template/'，重新提交代码之后再次部署，查看是部署成功的。

再次打开网址，样式没有丢失，测试线上的效果和本地测试的效果是一样的。

总结

项目部署是前端开发领域中一个至关重要的环节，同时也是必备技能，将 VitePress 部署到线上不仅能供他人访问和学习，还能检验项目本身的构建流程有没有问题。

本文只是参考 VitePress 官网的部署指南，将 VitePress 部署到 GitHub Pages 平台上的一个学习笔记，官网介绍了多种平台的部署指南，感兴趣的可自行查看并学习。