使用VitePress和GitHub Actions高效搭建文档网站

长林啊
927 阅读5分钟

最终效果如上

Tasks

  • 创建新项目
  • 在 github 上创建仓库
  • 提交项目
  • 创建 github actions
  • 创建 gitworkflow
  • 自动部署到 github pages
  • 自动部署到服务器静态资源目录

本文的环境参数:

  • 项目开发平台 MacOS 11.6
  • Node.js 的版本是 v20.10.0
  • pnpm 的版本是 8.12.1
  • Git 的版本是 2.39.0

开发平台倒是无所谓，主要是要有 Node.js、pnpm 和 Git开发环境，如果没有这些环境，也可以去对应的官网下载。

创建项目

  1. 创建一个空目录 clin-notes

    $ mkdir clin-notes

  2. 使用熟悉的开发者工具打开 clin-notes 这个目录，我在这里就用 vscode 打开啦，如下图： vscode

  3. 初始化 Node.js 项目，执行命令：pnpm init 如下： image

  4. 安装 vitepress

    $ pnpm add -D vitepress

    image VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令：

    $ pnpm vitepress init

    image 上面的命令执行完成后，项目中就多了几个文件和 .vitepress 目录，这个目录就是 vitepress 的配置目录，比如网站的 title、description、icon等等的都在这个目录下的 config.mts 中。

  5. 运行刚初始化的项目，执行命令：pnpm docs:dev image 然后在浏览器中访问 http://localhost:5173，效果如下： image

  6. 初始化本地的 git，并将 node_modules 添加到 .gitignore 中

    $ git init

    通常写 .gitignore 文件都比较麻烦，可以通过一些在线工具或者使用开发者工具中的一些插件（比如vscode 中gitignore生成工具）进行提效，在线工具有 .gitignore.io 这个工具，在里面输入要添加项，比如 macOS、Node.js等等 image 点击 create 后，就会生成一个 .gitignore 的内容，接着在项目的根目录创建一个 .gitignore 的文件，然后把文件的内容复制进去 image

  7. 将项目 add 到本地暂存区

    $ git add .

  8. 将项目 commit 到本地仓库

    $ git commit -am "initial project"

创建远程仓库

可以使用读者熟悉的代码管理平台，github、gitlab、gitee 这些都可以，因为我要是用 github actions，所以我就是用 github 这个代码管理平台。

  1. 如果没有github.com的账号，可以注册一个，登录后就能创建仓库了，如下图： create respository

  2. 把仓库名和项目是否公开的选项以及描述填写完，就可以点击右下角的 Create repository 按钮，接着就会跳转到一个新页面，这个页面就是刚刚创建的仓库；如下图： cammand line

  3. 将远程仓库的地址与本地项目的 git 关联

    $ git remote add origin https://github.com/clin211/clin-notes.git

  4. 将本地项目推送到远程仓库中

    如果默认分支不是 main 分支的话，可以执行命令： git branch -M main，命令中的 -M 选项是 --move 的缩写，用于重命名分支；-M 选项用于强制重命名分支，即使新名称已存在。

    $ git push -u origin main
    • git push: 这个命令用于将本地仓库的提交推送到远程仓库。
    • -u: 这个选项是 --set-upstream 的缩写。它用于将远程分支设置为上游分支。这样可以在未指定远程分支的情况下使用 git pull。
    • origin: 这是远程仓库的名称，您要将本地更改推送到该远程仓库。origin 是常见的默认远程仓库的名称。
    • main: 这是您要推送到远程仓库的本地分支。 image

初识 GitHub Actions

GitHub Actions 是 GitHub 为托管在 github.com 站点的项目提供的持续集成服务，于 2018 年 10 月推出。

GitHub Actions 具有以下功能特性：

  • 提供原子的 actions 配置和组合 actions 的 workflow 配置两种能力。
  • 全局配置基于YAML 配置，兼容主流 CI/CD 工具配置。
  • Actions/Workflows 基于事件触发，包括 Event restrictions、Webhook events、Scheduled events、External events。
  • 提供可供运行的托管容器服务，包括 Docker、VM，可运行 Linux、macOS、Windows 主流系统。
  • 提供主流语言的支持，包括 Node.js、Python、Java、Ruby、PHP、Go、Rust、.NET。
  • 提供实时日志流程，方便调试。
  • 提供平台内置的 Actions与第三方提供的 Actions，开箱即用。

更多详细内容可以前往 github actions 官方文档查看

创建 gitworkflow

根据上面的介绍，现在来给项目创建 workflows，在项目的根目录创建 .github/workflows/deply.yml，添加以下内容：

name: Deploy GitHub Pages and remote server

# 触发条件：在 push 到 main 分支后
on:
  push:
    branches:
      - main

# 任务
jobs:
  build-and-deploy:
    # 服务器环境：最新版 Ubuntu
    runs-on: ubuntu-latest
    steps:
      # 拉取代码
      - name: Checkout
        uses: actions/checkout@v2
        with:
          persist-credentials: false

      # 1、生成静态文件
      - name: Build
        run: pnpm && pnpm docs:build

      # 2、部署到 GitHub Pages
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@releases/v3
        with:
          BRANCH: gh-pages
          FOLDER: ./src/.vitepress/dist
          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          REPOSITORY_NAME: clin211/clin211.github.io

这段代码是一个 GitHub Actions 工作流文件，用于部署一个项目到 GitHub Pages 和远程服务器。

让我逐行解释一下：

  • name: Deploy GitHub Pages and remote server：这行代码定义了工作流的名称。
  • on: push: branches: - main：这行代码定义了触发工作流的条件，即当代码 push 到 main 分支时触发工作流。
  • jobs: build-and-deploy: runs-on: ubuntu-latest：这行代码定义了一个名为 build-and-deploy 的任务，该任务在最新版的 Ubuntu 环境下运行。
  • steps:：这行代码定义了任务的步骤。
  • - name: Checkout：这行代码定义了一个名为 Checkout 的步骤，用于拉取代码。
  • - name: Build：这行代码定义了一个名为 Build 的步骤，用于生成静态文件。
  • - name: Deploy：这行代码定义了一个名为 Deploy 的步骤，用于部署到 GitHub Pages 和远程服务器。
  • uses: actions/checkout@v2：这行代码使用了 actions/checkout 操作，用于拉取代码。
  • uses: JamesIves/github-pages-deploy-action@releases/v3：这行代码使用了 JamesIves/github-pages-deploy-action 操作，用于部署到 GitHub Pages。
  • with: BRANCH: gh-pages FOLDER: ./src/.vitepress/dist ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }} REPOSITORY_NAME: clin211/clin211.github.io：这行代码定义了部署到 GitHub Pages 的参数，包括分支、目标文件夹、访问令牌和仓库名称。

在上面的 yml 中，用到了一个 ACCESS_TOKEN 的参数，这个是怎么来的呢？

ACCESS_TOKEN 参数是通过 GitHub Secrets 来提供的。在 GitHub 仓库的 Settings 页面中，可以设置 Secrets，这些 Secrets 可以在 GitHub Actions 中使用，以便在工作流中安全地存储敏感信息，如访问令牌、密码等。在这段代码中，${{ secrets.ACCESS_TOKEN }} 会使用存储在 GitHub Secrets 中名为 ACCESS_TOKEN 的值作为访问令牌，用于部署到 GitHub Pages 和远程服务器。

  1. 打开 github 并登录，然后点击右上角的头像，如下图所示： image

  2. 创建 tokens image
    image
    image image 一旦生成 token 后，就不能修改，只能重新生成！！！下图页面刷新后就看不到 token 啦！一定要及得 copy 并妥善管理。 image

  3. 将刚生成的 SCCESS_TOKEN 添加到要使用的仓库（clin-notes）中；如下图： image
    image
    image 一旦添加之后，就看不到原来的内容了，所以要谨慎，不过可以修改。

将 vitepress 网站部署到服务器

之前的部署方式就是将每次构建后的（npm run docs:build 产生的 dist 目录）资源上传到服务器的指定目录下。这个过程如果每次都手动执行，无疑会耗费大量的时间和精力。幸运的是，有许多工具可以帮助我们自动化这些过程，让我们能专注于更重要的事情，比如代码的编写和优化。这就是持续集成和持续部署的魅力所在。在本文中，我选择了 GitHub Actions 作为部署工具。

但是，我们应该如何将网站部署到个人服务器上呢？ 这就是 SSH 和 easingthemes/ssh-deploy 进场的时候。SSH 全称 Secure Shell，是一种加密的网络传输协议，可在不安全的网络中为网络服务提供安全的传输环境，让我们可以在本地和远程服务器之间进行通信。easingthemes/ssh-deploy 则是 GitHub Actions 的一个插件，它利用 SSH 的能力，帮助我们轻松地将代码部署到远程服务器。

社区还有很多其他类似的插件，比如 rsync-deploy、rsync-deploy-action 等等，它们都能完成类似的任务。但在本文中，我将主要关注如何使用 SSH 和 easingthemes/ssh-deploy 来完成我们的部署工作。下面便开启我们的部署之旅！

创建 ssh 密钥

  1. 登录远程服务器。 
    $ ssh username@ip # 如：ssh root@127.0.0.1

回车后输入密码，注意：此时输入的密码是不可见的。

  1. 创建秘钥。

    $ ssh-keygen -m PEM -t rsa -b 4096

    创建效果如下图： image

  2. 进入 .ssh 目录，查看生成的秘钥对。

    # 进入目录
$ cd .ssh

# 查看密钥对
$ ls

    上面两段代码执行后如下效果： image

  3. 将生成的 id_rsa.pub 文件中的内容追加到 ~/.ssh/ 下的 authorized_keys 文件中，否则后续会有问题；具体可以参考 stack overflow。

部署准备和脚本编写

编写脚本

下面的部分内容是根据官方示例改写，更多属性及用法请移步官方文档

 - name: Deploy to Server
   uses: easingthemes/ssh-deploy@main
   with:
     SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
     ARGS: "-rlgoDzvc -i --delete"
     # 源目录，相对于$GITHUB_WORKSPACE根目录的路径
     SOURCE: "./src/.vitepress/dist/"
     # 服务器域名/IP
     REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
     # 服务器默认用户名为root
     REMOTE_USER: root
     # 远程服务器目录（将dist目录下的所有文件拷贝到此目录）
     TARGET: "/home/www/docs/"
     # 排除 node_modules 目录
     EXCLUDE: "/node_modules/"

在 github 上配置“环境变量”

在项目的远程仓库中创建 SSH_PRIVATE_KEY 和 REMOTE_HOST 变量（要跟脚本配置的变量一致，不一致就不会生效），操作流程如下图：

创建 SSH_PRIVATE_KEY，这个就是通过 keygen 生成的秘钥，这里填写 id_rsa 文件中的内容（注意要一字不落的全部copy）：

添加秘钥

创建 REMOTE_HOST，也就是你的服务器的 IP，填写完成后点击 add secret 按钮 添加ip

最后效果如下图：

查看效果

  1. 修改项目然后 push 到远程仓库

  2. 进入远程仓库的 actions 中查看执行结果（如果有错误可以进入对应的环节进行查看具体错误） image

  3. 查看服务器和 github pages 的最终效果，本文部署到 github pages 的链接为：clin211.github.io/docs/ image image

avatar
文章
阅读
粉丝