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

前言

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

主要是不想买服务器，也不想折腾服务器，还是免费的服务比较香。^_^

静态网站（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…。

• 4）上面的地址 codercup.github.io/github-acti… 默认访问的是 index.html，如果要访问其他 html 需要加上完整的路径，如 codercup.github.io/github-acti…

完结撒花~~

别逗，未完，继续~~

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

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

点击上图的 x，出现下图：

点击上图的 Details，出现下图：

提示文件或者文件夹不存在导致部署失败，还能访问是因为浏看到的是之前部署的版本。

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

多说一句 again，可选路径除了 /(root)之外，还有一个 /docs目录，这个目录有啥特别之处？答案：因为很多开源项目，经常会有 docs 文件夹来放说明文档的（最熟悉的如 vuepress, vitepress），Github 为了用户方便，增加这个预设。

静态网站（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 文件，不然篇幅太长了，主要先能把所有情况跑起来）

# 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，达到精简效果 )：

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 文件如下即可：

# 将静态内容部署到 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，达到精简效果 )：

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处的改动，如下：

# 将静态内容部署到 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，所以是自带缓存效果的。

当然如果想加上更加强大的 actions/cache@v3 也是可以的，一个可用的参考范例如下：

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 项目 来演示：

# 将静态内容部署到 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 过去稍加修改就能用:

# 将静态内容部署到 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, 也会出现这个问题。

 - 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步：

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 ^_^)：

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 完整版：

# 将静态内容部署到 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

• 多分支部署：编写多个 yml 文件，不同的文件里面 on.push.branches 填写不同的分支即可，very 简单~

参考文档： Github Action Docs

至此，全文完，撒花~~

---

我在参加 #金石计划征文活动，如果觉得本篇文章对你有帮助，点个赞再走吧，ღ( ´･ᴗ･` )比心。

好文推荐