白嫖党 YYDS: GitHub Pages 配置介绍

GitHub Pages 是 GitHub 平台提供的一个强大而灵活的静态网站托管服务, 它为开发者和项目团队提供了一个无需额外成本的方式来创建和托管自己的网站, 本节将简单介绍如何将现有的项目发布到 GitHub Pages

前言

是什么: GitHub Pages 是 GitHub 平台提供的一个强大而灵活的静态网站托管服务, 它为开发者和项目团队提供了一个无需额外成本的方式来创建和托管自己的网站。该服务允许您将您的代码仓库转变为一个在线可访问的网站!!

优点:

与 GitHub 仓库直接关联, 可使用 git 实现版本控制, 可与其他人一起构建您的网站, 轻松地跟踪更改和协作
完全免费, 无须自己购买云服务进行搭建, 相较其他的同类产品, 他能替你省下一笔服务费
与 GitHub 仓库直接关联, 可通过 GitHub Actions 来完成网站的构建
GitHub Pages 还提供免费的 HTTPS 支持
可以使用自己的个性域名

可以用来做啥:

个人博客: 可以使用 GitHub Pages 创建自己的个人博客, 分享您的知识、见解和经验
项目文档: 如果您是一个开源项目的维护者, GitHub Pages 可以用来托管项目文档, 让用户更容易了解和使用您的项; 通过将文档与代码仓库关联, 您可以确保文档与代码同步更新, 提供更好的用户体验
个人简历和作品集: GitHub Pages 是一个展示您的个人简历、作品和项目的理想平台; 您可以创建一个专业而有吸引力的在线简历, 向潜在雇主或客户展示您的技能和成就

下面我们将简单介绍下 GitHub Pages 的配置流程、以及如何通过 GitHub Acitons 完成项目的构建和发布至 GitHub Pages

一、GitHub Pages 配置

本节我们从零来演示下 GitHub Pages 的配置步骤

GitHub Pages 是与 GitHub 仓库直接关联的, 所以我们得先创建一个 GitHub 仓库

GitHub Pages 是基于某个分支来进行部署的, 所以这里我创建了一个新的分支 gh-pages 作为 GitHub Pages 的源分支

默认情况下, 仓库是没有开启 GitHub Pages 配置的, 我们需要进入仓库配置页面进行简单的配置: Settings -> Pages -> Branch -> save

补充: 上面 👆🏻 GitHub Pages 配置中, 我们设置了分支 gp-pages, 目录 /(root) 也就是说, GitHub 会将对应分支(gp-pages)、根目录下的所有内容作为静态资源进行发布; 当然目录这边我们还有一个选择是 /docs, 也就是说 GitHub 只会将指定分支下的 docs 目录中的内容作为静态资源进行发布, 这样有个好处就是我们可以不用创建新的分支, 可以直接基于主分支中的 docs 目录来发布, 在每次 build 时只要将资源输出到 docs 即可

上面我们完成了 GitHub Pages 基本配置(分支 gp-pages, 目录 /(root)), 那么我们只需要将要发布的内容上传(push)到对应分支上, 那么 GitHub 就会触发 GitHub Pages 的构建和部署, 会将分支下对应目录的内容作为资源创建一个静态服务; 下面我们开始测试....

拉取项目: 先将项目 clone 到本地, 并切换到对应分支(gh-pages)

sh 复制代码

git clone git@github.com:MoYuanJun/blog-gh-pages.git
git checkout gh-pages

创建资源: 创建 index.html 以及 404.html 文件

html 复制代码

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
  index
</body>
</html>

html 复制代码

<!-- 404.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
  Not Find
</body>
</html>

上传代码: 将新增的代码, 上传到对应分支(gh-pages)

sh 复制代码

git add .
git push
git commit -m 'ddd index.html 404.html'

如下图, 当我们设置的分支(gh-pages)有新的代码提交, 那么就会触发默认 GitHub Acitons 进行 GitHub Pages 的构建发布

如下图, 当 GitHub Acitons 完成 GitHub Pages 发布后, 通过点击任务查看具体的构建流程, 就可以找到项目发布的地址, 也就是本次 GitHub Pages 的地址

补充: 其实每个仓库的 GitHub Pages 地址的格式是固定的, https://{GitHub 用户名}.github.io/{仓库名}

测试: 下面是我们分别访问 blog-gh-pages、以及 blog-gh-pages/xxx 的截图

访问 GitHub Pages 首页

访问 GitHub Pages 不存在资源, 将展示 404 页面

二、自动构建

上文讲解并演示了 GitHub Pages 的配置以及构建发布的流程也可以说是原理...

下面我们将演示如果基于主分支(main)通过 GitHub Actions 来构建 GitHub Pages 服务, 其大致工作流程如下...

2.1 搭建「React」项目

这里我使用我个人的一个脚手架(KunLunXu-CC/create-react-app) 在主分支下快速搭建了一个 React 项目(仓库地址点击这里), 至于项目搭建过程不会做过多的演示、也不是本文的重点; 当然这里我只是为了演示, 这边您可以选择任何自己熟悉的技术栈来搭建一个项目!!!

项目最后搭建完后, package.json 会有两个 npm 脚本:

json 复制代码

"scripts": {
  "start": "react-script start",
  "build": "react-script build"
}

start 脚本, 用于开发环境下启动项目, 运行后项目界面如下:

build 脚本, 用于打包编译项目, 打包后产物如下:

2.2 配置 GitHub Actions

有关 GitHub Actions 详细内容可以直接看看官方文档(actions/managing-workflow-runs), 这里将直接给出配置方法, 以及完整的 workflows 配置, 具体每行配置内容以及介绍可以看注释

配置方法: 项目根目录下创建 .github/workflows/gh-page.yml 文件, 并添加如下内容!! 而下面配置需要调整的可能就是倒二行的部署分支、以及最后一行的打包静态资源输出的目录

yml 复制代码

# 1. 为工作流定义名字
name: 「GitHub Pages」Build & Deploy 

# 2. 触发条件修改为: 当 main 或 master 分支, 有 push 的时候, 执行任务
on:
  push:
    branches:
      - master
      - main

# 3. 创建工作流
jobs:
  build:                      # 工作流名称
    runs-on: ubuntu-latest    # 依赖环境

    steps:                    # 工作流步骤
      # step 1. 获取源码, 拉取仓库代码
      - name: Chekcout 🛎️             # 步骤名
        uses: actions/checkout@master # 使用插件 => https://github.com/actions/checkout

      # step 2. 使用指定版本 node
      - name: Use Node  📦              # 步骤名
        uses: actions/setup-node@master # 使用插件 => https://github.com/actions/setup-node
        with: # 插件携带参数
          node-version: '16' # 指定 node 版本

      # step 3. 安装依赖并打包
      - name: Install and Build 🔧
        run: |
          npm install
          npm run build

      # step 4. 项目部署, 将打包后的产物合并到指定的分支上
      - name: Deploy 🚀                                   # 步骤名
        uses: JamesIves/github-pages-deploy-action@v4.2.2 # 使用插件 => https://github.com/JamesIves/github-pages-deploy-action
        with:
          BRANCH: gh-pages  # 部署分支
          FOLDER: build     # 打包, 静态资源输出的目录

最近将上面 workflows 提交到远程仓库, 提交成功将会触发 GitHub Actions, 但是最终你会发现, GitHub Actions 并没有执行成功

这里主要原因是因为, GitHub Actions 默认情况下 只有读取 远程仓库代码的 权限, 而不具有写入权限, 也就是 workflows 在第四步项目部署阶段是无权限将打包后的静态资源合并到远程仓库对应的分支中....

下面我们来配置下, GitHub Actions 对远程仓库的操作权限: Settings -> Actions -> General -> Read and write permissions -> Save

设置完 GitHub Actions 权限后, 为了触发 GitHub Actions 需要简单修改点代码并提交到远程(修改内容随意), 最后 GitHub Actions 执行情况如下:

2.3 测试

最后可以访问下构建、发布完成后的 GitHub Pages 服务: blog-gh-pages

效果如下: