Github Actions 与 Pages 部署

[PrintzZZ]

🎉前言

博客使用了 vitepress-theme-curve 主题，原作者提供了本地部署与Vercel 部署的教程，但是本地部署需要手动压缩上传再解压，对于我这种懒人来说，还是使用 Github Actions 自动部署比较方便。

• 完成修改后的自动部署流程如下
• 一键三连提交文件，git add . && git commit -m "update" && git push origin main
• Github Actions检测到有文件提交后，会自动执行yml文件中的配置。
• Github Actions先设置GITHUB_PAGES为true，自动执行打包，部署到Github Pages，此时basePath为/你的仓库名/。
• Github Actions然后设置GITHUB_PAGES为false，再次执行打包，部署到服务器，此时basePath为/。
• 等待Actions完成，访问对应页面即可看到更新后的博客。

另外的，如果需要使用 Github Actions 自动部署，你需要掌握 Github Actions 的相关知识。你可能会遇到一系列的问题，请确保你有独立解决问题的能力。
另外的，该方案属于班门弄斧，对源码进行了修改，期待大佬们有更好的解决方案

基础路径的源码修改

由于源码中没有对base地址进行配置，而Github Pages需要使用/你的仓库名/作为base路径，不然会出现静态资源丢失404等问题，所以需要手动修改。

我们通过env配置来判断当前站点是否是GitHub Pages部署，如果为true则使用/你的仓库名/作为base路径，否则使用/作为base路径。

这样，你就可以在Github Actions中通过设置env的变量GITHUB_PAGES来实现动态设置base路径。

• 注意：GITHUB_PAGES 变量值是字符串，不是布尔值。
• 这一步修改是为了解决github pages 部署时，base 路径导致的资源丢失的问题。
• 部署成功后依然会出现跳转404的问题，这是因为源码中路由和一些静态资源的base路径没有修改。我们在下方会进行修改。

在.vitepress\config.mjs文件中，添加如下修改。

// 判断当前站点是否是 GitHub Pages 部署
const isGitHubPages = process.env.GITHUB_PAGES === 'true' || false;

// 根据环境或站点动态设置 base 路径
const basePath = isGitHubPages ? '/你的仓库名/' : '/';

export default withPwa(
  defineConfig({
    base: basePath,
    // 其他位置不用修改

Github Actions 配置

我们通过五步来实现自动打包，自动部署到 Github Pages，自动修改env配置重新打包，自动上传到服务器。

• 需要注意的是，env配置修改的GITHUB_PAGES变量值是字符串，不是布尔值。
• 我们需要再github仓库中Settings->Secrets and variables->Actions中创建两个secret变量，用于存放服务器信息。
• PRIVATE_HOST 对应服务器IP地址
• PRIVATE_KEY 对应服务器ssh连接的密钥 （注意开启ssh密钥连接）

该流程分为两个部分

• 第一二三步，会自动创建一个gh-pages分支，用于存放打包后的文件并部署到Github Pages。所以我们在Github Pages 设置中需要设置为 gh-pages 分支为根目录。
• 第四五步，会自动修改env配置，重新打包dist，并上传到指定的服务器。

你需要在代码根目录下创建 .github/workflows/deploy.yml 文件，并添加如下内容。

name: 打包并部署到阿里云  # 工作流的名称
on: [push]  # 触发条件：当有代码推送到仓库时触发
permissions:
  contents: write  # 授予工作流写入仓库内容的权限（用于部署）

jobs:
  build-and-deploy:  # 定义一个名为 build-and-deploy 的任务
    runs-on: ubuntu-latest  # 指定运行环境为最新的 Ubuntu 版本
    steps:
      # 第一步：使用 actions/checkout 动作，检出代码到工作目录
      - name: 检出代码 🛎️
        uses: actions/checkout@v4  

      # 第二步：安装依赖并构建项目
      - name: 安装依赖并构建项目 🔧
        env:
          GITHUB_PAGES: 'true'
        run: |  
          npm ci  
          npm run build  


      # 第三步：部署到 GitHub Pages
      - name: 部署到GitHub Pages 🚀
        uses: JamesIves/github-pages-deploy-action@v4  
        with:
          folder: .vitepress/dist

      # 第四步：重新构建
      - name: 重新构建 🔧
        env:
          GITHUB_PAGES: 'false'
        run: |
          npm run build

      # 第五步：利用action把dist好的文件上传到服务器/www/wwwroot/blog.xxx.com路径下,需要确认此目录已在服务端创建
      - name: 发布到阿里云服务器的宝塔面板 🚀
        uses: wlixcc/SFTP-Deploy-Action@v1.0
        with:
          username: 'root' #ssh user name
          server: '${{ secrets.PRIVATE_HOST }}' #引用之前创建好的secret
          ssh_private_key: ${{ secrets.PRIVATE_KEY }} #引用之前创建好的secret
          local_path: '.vitepress/dist/*' # 对应我们项目build的文件夹路径
          remote_path: '/www/wwwroot/blog.xxx.com' # 对应服务器上的网站路径

解决base路径导致的资源丢失与跳转404的问题

通过主题配置文件themeConfig.mjs和router.go()方法的修改，可以解决绝大部分github pages 部署时，base路径导致的资源丢失的问题。

修改themeConfig.mjs

作者提供了.vitepress\theme\assets\themeConfig.mjs文件，用于全局配置主题。
我们在此处修改base路径，这样打包时会自动根据环境动态的设置base路径，以解决github pages 部署时，base路径导致的资源丢失的问题。

• 在最顶部加入process.env.GITHUB_PAGES判断是否是github pages 部署，并设置basePath。

const basePath = process.env.GITHUB_PAGES === 'true' ? "/你的仓库名/" : "";

• 在siteMeta中，加入basePath，用于其他文件读取并设置base路径。

// 是否是 GitHub Pages 部署
basePath: basePath,

• 在所有静态资源中，加入basePath，用于设置base路径。例如：

// inject
  inject: {
    // 头部
    header: [
      // favicon
      ["link", { rel: "icon", href: basePath + "/favicon.ico" }],
// 其他静态资源

修改router.go()

1. 修改静态页的basePath
   全局搜索router.go()，但凡涉及到静态页面的跳转，都修改为router.go(basePath + '/')。

例如右键菜单：.vitepress\theme\components\RightMenu.vue

// 修改前
@click="router.go(`/pages/categories`)"

// 修改后
@click="router.go(`${basePath}/pages/categories`)"

// 通过theme 获取 basePath
const { theme } = useData();
const basePath = theme.value.siteMeta.basePath;

2. 修改文章的跳转
   作者通过.vitepress\theme\utils\getPostData.mjs文件中的getAllPosts()方法生成文章数据，并返回一个对象。

我们修改regularPath，使其返回的文章路径能够动态设置。该方法在打包时执行，所以通过process.env.GITHUB_PAGES判断是否是github pages部署，并设置basePath。

// 其他代码无需修改
const basePath = process.env.GITHUB_PAGES === "true" ? "/iceBlog/" : ""; // 修改1、获取basePath
return {
  id: generateId(item),
  title: title || "未命名文章",
  date: date ? new Date(date).getTime() : birthtimeMs,
  lastModified: mtimeMs,
  expired,
  tags,
  categories,
  description,
  regularPath: `${basePath}${item.replace(".md", ".html")}`, // 修改2、修改regularPath
  top,
  cover,
};
// 其他代码无需修改

其他源码修改

1. 关闭跳转页面时的全屏遮罩

注释掉.vitepress\theme\App.vue文件中的<Loading />标签。

2. 关闭页面跳转时的加载动画

修改.vitepress\theme\utils\initTools.mjs中changeLoading()方法,将延迟时间改为0。

// Math.floor(Math.random() * (800 - 260 + 1)) + 260, // 随机延时
0,// 固定延时

3. 修改组件的动态加载动画

组件的加载由css控制，全局搜索 fade-up 0.6，0.6表示动画延迟时间，0.6s后显示组件，可自行修改。

4. sass的import报错

全局搜索 import，将@/style/main.scss文件中的@import改为@use。

5. 右键复制本页地址undefined

.vitepress\theme\components\RightMenu.vue中行号：350,
修改为：

const pageLink = theme.value.siteMeta.site + router.route.path;

[PrintzZZ]

该流程使用了同一个仓库，导致我们的源代码与打包后的文件都存储在同一个仓库中，又因为Github Page的限制，我们必须将仓库公开，对隐私数据敏感的我们来说，这显然是不合理的。所以，我们需要将源代码与打包后的文件分开存储，并使用 Github Actions 推送到不同的仓库。

我们将源代码存储在 UserName/Example_Dev 仓库中并隐藏，将打包后的文件存储在 UserName/Example_Public 仓库中并公开。

UserName/Example_Public 仓库将作为 GitHub Pages 的根目录，域名为 https://UserName.github.io/Example_Public。

实现

仅需做两个简单的修改，在 .github/workflows/deploy.yml 文件中，配置我们要推送到哪个仓库，这里我们将JamesIves/github-pages-deploy-action@v4自动生成的gh-pages分支推送到UserName/Example_Public仓库中，他会自动的配置目标仓库的GitHub Pages并直接部署，非常方便。

这在之前我们需要github中生成一个token，并将其设置为私有仓库的secrets，可以参考将GitHub设置成Token

• 添加一个 branch 的变量，指定要推送哪个分支，这里 gh-pages。
• 添加一个 folder 的变量，指定要推送哪个文件夹，例如 .vitepress/dist。
• 添加一个 repository-name 的变量，指定要推送到哪个仓库，例如 UserName/Example_Public。
• 添加一个 token 的变量，以获取目标仓库的权限，例如 DEPLOY_TOKEN。

      # 第三步：部署到公开仓库的 GitHub Pages
      - name: 部署到GitHub Pages 🚀
        uses: JamesIves/github-pages-deploy-action@v4  
        with:
          branch: gh-pages
          folder: .vitepress/dist
          repository-name: UserName/Example_Public
          token: ${{ secrets.DEPLOY_TOKEN }}

总结

通过以上步骤，我们成功地将源代码与打包后的文件分开存储，并使用 Github Actions 一键推送到不同的仓库。实现源代码与打包后的文件分开存储。
本地源代码下执行以下命令，确保将源代码推送到 UserName/Example_Dev 仓库中。注意不是 UserName/Example_Public 仓库。

git remote -v  # 查看远程仓库
git remote set-url origin https://github.com/UserName/Example_Dev.git  # 设置远程仓库
git add .  # 添加文件
git commit -m "update"  # 提交文件
git push -f origin main  # 推送代码