手把手教你github actions 部署 pages，动态网页，静态网页，缓存优化，多分支部署等

Burt2024-02-16 10:42

前言

通过本文您将学会，如何部署 静态网站 + 动态网站 + npm 构建 & 缓存 + pnpm 构建 & 缓存 + 多分支部署 等，让你的网站直接白嫖 github.io, 免费服务器，无需翻墙，网速还不差。

比如我的 unibest 就不会太慢，codercup.github.io/unibest/#/

主要是不想折腾服务器，更不想买服务器，还是免费的服务比较香。/手动狗头

静态网站（Deploy from a branch）

  • 1）创建一个仓库，填写
    • 项目名，这里是 github-actions-deploy ( 必填，其他几个步骤都是选填 ）
    • 描述
    • 选择 Public (注：Private 仓库无法发布 pages)
    • 勾选 Add a README file
    • Add .gitignore 选择 Node
    • Choose a license 选择 MIT License
  • 2）在根目录新增2个 html 文件:
    • index.html
    • bar.html (作为对比用）
  • 3）打开 Settings - Pages， 出现的页面进行如下操作：
    • Source 选择 Deploy from a branch (默认值）
    • Branch 默认为 None 要选择 main, 右侧会默认出现 /root，再点击右侧的 Save

刷新本页面，就会出现部署出去的网址，如下图 红框区域 ，我的网址是 codercup.github.io/github-acti...。

完结撒花~~

别逗，未完，继续~~

  • 5）地球人都知道，部署的根路径有2个选择：一个是/(root)，一个是 /docs，这个时候部署根路径改为 /docs 会怎样呢？

刷新页面，好像还是能访问的，好生奇怪是不是？其实是部署失败了，多个地方可以看出来，如下3张图：

提示文件或者文件夹不存在。

部署失败，访问的之前的正常部署出去的，所以浏览器看到的是之前部署的版本（所以还能正常访问）。

多说一句，其他目录的html文件一样可以访问得到，比如 /a/foo.html，就在原本的 链接后面加上 a/foo.html 即可。

多说两句，为啥除了 /(root)之外，还有一个 /docs目录，这个目录有啥特别之处？因为很多开源项目，经常会有 docs 文件夹来放说明文档的（最熟悉的如 vuepress, vitepress），既然常用，那就增加这个预设选项。

静态网站（Github Actions)

地球人都知道 github pages 目前有2种部署方式，除了上面小试牛刀里面经典的的 Deploy from a branch 之外，还有功能更加强大的 Github Actions，不仅可以完全替代 Deploy from a branch，还有非常强大的功能！

点击切换之后，会出现如下图，让你选择或者配置 github actions, github actions 通过 github workflow 触发，所以其实是创建 github workflow 文件。

如上图点击 Static HTML 卡片的 Configure ，跳转页面，并自动生成一个 yml 文件： .github/workflows/static.yml （暂时先不讲解这个 yml 文件，不然篇幅太长了，主要先能把所有情况跑起来）

yml 复制代码 
# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

右上角点击提交 commit changes

点击 Actions 可以看到所有的跑的 workflow，可以看到之前的经典版跑的的也在这里有，最新的 Create static.yml 才是 github actions 触发的。（其实严格来说都是 github actions 触发)

点击进去，能看到详情，并且能看到部署出去的地址，如下图。codercup.github.io/github-acti...

点击访问codercup.github.io/github-acti...，可以看到页面效果，与之前的一模一样。

  • 简单讲解一下 yml 文件，一图胜千言
  • 要部署非根目录怎么办，比如 /docs，可以在 yml 文件里面配置，把 . 改为 ./docs，同时新增 /docs/index.html

提交后，会自动触发部署，打开codercup.github.io/github-acti...，看到部署出去已经生效了，如下图：

  • github actions 相比 Deploy from a branch 还有一个好处就是代码推上去就可以自动触发部署，不用手动去 Settings - Pages 里面点点点，自动化能力提高10个档次。

小结

这个 static.yml 的 steps 里面主要有4步 (全部去除了 name，达到精简效果 )：

yml 复制代码 
steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: '.'
      - id: deployment
        uses: actions/deploy-pages@v4

上面第7行的 id: deployment 建议加上，否则出现如下提示（虽然无伤大雅）：

正常的如下：

动态网址

上面的静态网址无需构建(build)，直接部署(deploy)就行。我把无需构建的项目叫做 静态网址，需要构建的叫做 动态网址，不知道这样命名是否正确，但是绝对是最好理解的，手动狗头~

要演示动态网址，我们要新开一个仓库，就在上面的仓库名字后面加上 dynamic 作为仓库名，即 github-actions-deploy-dynamic。（我懒，还是不创建了，下面的代码更加精简直观，YYDS）

演示一：vue 项目

我们知道 vue 项目执行构建 npm run build 之后会在 /dist 文件夹生成构建后的文件，那么其 deploy.yml 文件如下即可：

yml 复制代码 
# 将静态内容部署到 GitHub Pages 的简易工作流程
name: Deploy static content to Pages

on:
  # 仅在推送到默认分支时运行。
  push:
    branches: ['main']

  # 这个选项可以使你手动在 Action tab 页面触发工作流
  workflow_dispatch:

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

# 允许一个并发的部署
concurrency:
  group: 'pages'
  cancel-in-progress: true

# ----分割线：上面的内容与静态网址是一样的，一般不用改-----

jobs:
  # 单次部署的工作描述
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # Upload dist repository
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

仔细观察可以发现，是在静态网址的基础上加上了额外 3 个step，通过 diff 来对比一下(全部去除了 name，达到精简效果 )：

diff 复制代码 
steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v4
+     - uses: actions/setup-node@v3
+       with:
+         node-version: 18
+         cache: 'npm'
+     - run: npm install
+     - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'
      - id: deployment
        uses: actions/deploy-pages@v4

是不是发现很简单~~

演示二：uniapp 项目

接着演示 uniapp 项目，与 vue 项目 作为对照，这里使用 diff 方式来展示代码。

uniapp 项目 发布 web 使用 npm run build:h5 命令，最终生成的产物在 /dist/build/h5，所以只有2处的改动，如下：

diff 复制代码 
# 将静态内容部署到 GitHub Pages 的简易工作流程
name: Deploy static content to Pages

on:
  # 仅在推送到默认分支时运行。
  push:
    branches: ['main']

  # 这个选项可以使你手动在 Action tab 页面触发工作流
  workflow_dispatch:

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

# 允许一个并发的部署
concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  # 单次部署的工作描述
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Build
-        run: npm run build
+        run: npm run build:h5
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # Upload dist repository
-          path: './dist'
+          path: './dist/build/h5'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

演示三：cache 缓存

如果要缓存，可以使用 setup-xx，如下图 npm, yarn, pnpm 都使用 setup-node，而上面的 yml 文件已经用了这个 action，所以是自带缓存效果的。

缓存效果还可以配置，比如一个可用的范例如：（通常我们不需要这么写）

yml 复制代码 
name: Caching with npm
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Cache node modules
        id: cache-npm
        uses: actions/cache@v3
        env:
          cache-name: cache-node-modules
        with:
          # npm cache files are stored in `~/.npm` on Linux/macOS
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
            ${{ runner.os }}-build-
            ${{ runner.os }}-

      - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
        name: List the state of node modules
        continue-on-error: true
        run: npm list

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Test
        run: npm test

演示四：使用 pnpm 而不是 npm

现在很多人都喜欢 pnpm 而不是 npm，比如我就是一个 pnpm 重度使用者，基本上项目能用 pnpm 就用 pnpm 绝不用别的。

那么要怎么写呢？这里还是通过 diff 对比 vue 项目 来演示：

diff 复制代码 
# 将静态内容部署到 GitHub Pages 的简易工作流程
name: Deploy static content to Pages

on:
  # 仅在推送到默认分支时运行。
  push:
    branches: ['main']

  # 这个选项可以使你手动在 Action tab 页面触发工作流
  workflow_dispatch:

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

# 允许一个并发的部署
concurrency:
  group: 'pages'
  cancel-in-progress: true

# ----分割线：上面的内容与静态网址是一样的，一般不用改-----

jobs:
  # 单次部署的工作描述
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
         node-version: 18
-         cache: 'npm'
+         cache: 'pnpm'
      - name: Install dependencies
-        run: npm install
+        run: pnpm install
      - name: Build
-        run: npm run build
+        run: pnpm run build
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # Upload dist repository
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

其实最主要也就是多了个 uses: pnpm/action-setup@v2， 然后把 npm 改为 pnpm 即可。

完整版(非 diff )如下，可以直接 copy 过去稍加修改就能用:

yml 复制代码 
# 将静态内容部署到 GitHub Pages 的简易工作流程
name: Deploy static content to Pages

on:
  # 仅在推送到默认分支时运行。
  push:
    branches: ['main']

  # 这个选项可以使你手动在 Action tab 页面触发工作流
  workflow_dispatch:

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

# 允许一个并发的部署
concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  # 单次部署的工作描述
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'pnpm'
      - name: Install dependencies
        run: pnpm install
      - name: Build
        run: pnpm run build
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # Upload dist repository
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

成功构建如下图：

注意 vite 项目部署到非根目录，需要配置 base, 如下图，否则页面显示空白。

注意事项（构建失败原因）

1） 找不到 lock 文件导致构建失败

找不到 lock 文件导致构建失败，如下图，需要 package-lock.json,npm-shrinkwrap.json,yarn.lock。

如果是 pnpm 则需要 pnpm-lock.yaml。

2) ERR_PNPM_FROZEN_LOCKFILE_WITH_OUTDATED_LOCKFILE  Cannot perform a frozen installation because the version of the lockfile is incompatible with this version of pnpm

当设置版本与本地生成 pnpm-lock.yaml 时的 pnpm 版本不一致时，也会报上述错误。什么意思呢？就是本地使用 pnpm@v7 执行 pnpm i 生成 pnpm-lock.yaml, 需要在下面第3行写上 7，写成 8，会导致这个问题，如果不写，会默认使用最新的 pnpm 版本就是 8, 也会出现这个问题。

yml 复制代码 
 - uses: pnpm/action-setup@v2
        with:
          version: 7

3）Get Pages site failed. Please verify that the repository has Pages enabled and configured to build using GitHub Actions, or consider exploring the enablement parameter for this action.

一个新仓库，直接写 workflow 部署网页会出现这个错误。

解决方法：

  • 2-1 点击 Settings - Pages 里面 source 里面的 Github Actions 即可触发。
  • 2-2 使用上上图中绿色箭头里面的那个配置：enablement。目前查了一圈资料，也没查清楚怎么设置。有懂的人指点一下~~

总结

  • 静态网站（Deploy from a branch），直接在 Settings - Pages 里面点点点即可。
  • 静态网站（Github Actions)，核心4步：
yml 复制代码 
steps:
     - uses: actions/checkout@v4
     - uses: actions/configure-pages@v4
     - uses: actions/upload-pages-artifact@v3
       with:
         path: '.'
     - id: deployment
       uses: actions/deploy-pages@v4
  • 动态网站（Github Actions)，核心7步（比前面加了3步而已：setup-node + npm install + npm run build，easy ^_^)：
yml 复制代码 
steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v4
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'npm'
      - run: npm install
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'
      - id: deployment
        uses: actions/deploy-pages@v4
  • 动态网站（Github Actions) pnpm 完整版：
yml 复制代码 
# 将静态内容部署到 GitHub Pages 的简易工作流程
name: Deploy static content to Pages

on:
  # 仅在推送到默认分支时运行。
  push:
    branches: ['main']

  # 这个选项可以使你手动在 Action tab 页面触发工作流
  workflow_dispatch:

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

# 允许一个并发的部署
concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  # 单次部署的工作描述
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'pnpm'
      - name: Install dependencies
        run: pnpm install
      - name: Build
        run: pnpm run build
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # Upload dist repository
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

至此，全文完，撒花~~

好文推荐

🔥2024年最好用的 uniapp 开发模板，近一个月 star 数飙升！🔥 - 点赞数：245， 收藏数：515

相关推荐
学习路上_write11 分钟前
FPGA/Verilog,Quartus环境下if-else语句和case语句RT视图对比/学习记录
单片机·嵌入式硬件·qt·学习·fpga开发·github·硬件工程
shitian08111 小时前
用轻量云服务器搭建一个开源的商城系统，含小程序和pc端
服务器·小程序·开源
修复bug3 小时前
npm完整发包流程（亲测可验证）
前端·npm·开源
IT规划师11 小时前
开源 - Ideal库 - 常用枚举扩展方法（二）
开源·c#·.net core·ideal库·枚举转换
_xaboy11 小时前
开源项目低代码表单设计器FcDesigner扩展组件分组
低代码·开源·动态表单·formcreate·低代码表单·可视化表单设计器
亥时科技12 小时前
相亲小程序（源码+文档+部署+讲解）
java·小程序·开源·源代码管理
油泼辣子多加13 小时前
2024年11月12日Github流行趋势
github
wayuncn13 小时前
IDC机房服务器托管的费用组成
运维·服务器·github
OpenBayes16 小时前
OpenBayes 一周速览丨VASP 教程上线！HPC 助力材料计算；AllClear 公共云层去除数据集发布，含超 23k 个全球分布的兴趣区域
人工智能·深度学习·机器学习·自然语言处理·开源·数据集·大语言模型
热门推荐
01软件工程从理论到实践客观题汇总(头歌第一章至第八章)02【HarmonyOS】HUAWEI DevEco Studio 下载地址汇总03组基轨迹建模 GBTM的介绍与实现（Stata 或 R）04VSCode插件 —— Cody AI （免费AI助手！）05全面解析：构建基于深度学习的安全帽检测系统（UI界面+YOLO代码+数据集）06Windows10安装PCL1.14.0及点云配准07Ubuntu 20.04使用Livox mid 360 测试 FAST_LIO08文件或文件夹名称中有空格如何批量去除09基于YOLOv10深度学习的CT扫描图像肾结石智能检测系统【python源码+Pyqt5界面+数据集+训练代码】深度学习实战、目标检测10【QuikGraph】C#调用第三方库实现迪杰斯特拉(Dijkstra)算法功能