10分钟掌握Github Pages自动化部署

Github Pages是Github公司提供的免费的静态网站托管服务，使用Github Pages可以搭建个人博客或者Github项目使用说明文档。而学会自动部署，可以大大降低时间成本。

一、基本概念

1. workflow（工作流程）：持续集成一次运行的过程，就是一个workflow

2. job（任务）：一个workflow由一个或多个jobs构成

3. step（步骤）：每个job由多个step构成，一步步完成

4. action（动作）：每个step可以依次执行一个或多个action

二、workflow文件

1. github项目选择actions

2. 在Continuous integration中选择nodejs工作流

3. 点击Configure便会创建 .github/workflows/node.js.yml

文件名可以任意取，Github只要发现.github/workflows目录里有.yml文件，就会自动运行该文件。一个库可以有多个workflow文件

对于yml文件陌生的，可接着看第三节YAML基本语法。如果熟悉的，可跳过这一步直接看第五节-项目发布到Github Pages

三、YAML基本语法

1. 大小写敏感

2. 使用缩进表示层级关系

3. 缩进时不允许使用Tab键，只允许使用空格

4. 缩进的空格数目不重要，只要相同层级的元素左侧对齐即可

#：表示注释，从这个字符一直到行尾，都会被解析器忽略

1. 对象

对象的一组键值对，使用冒号结构表示

animal: pets

转为 JavaScript 如下

{ animal: 'pets' }

2. 数组

一组连词线开头的行，构成一个数组

- Cat
- Dog
- Goldfish

转为 JavaScript 如下

[ 'Cat', 'Dog', 'Goldfish' ]

3. 复合结构

对象和数组可以结合使用，形成复合结构

languages:
 - Ruby
 - Perl
 - Python 
websites:
 YAML: yaml.org 
 Ruby: ruby-lang.org 
 Python: python.org 
 Perl: use.perl.org 

转为JavaScript如下

{ 
    languages: [ 'Ruby', 'Perl', 'Python' ],
    websites: 
     { YAML: 'yaml.org',
       Ruby: 'ruby-lang.org',
       Python: 'python.org',
       Perl: 'use.perl.org' } 
  }

四、node.js.yml分析

#workflow名称。如果省略该字段，默认为当前workflow的文件名
name: Node.js CI

#指定触发workflow的条件
on:
  push: 
    #只有master分支push时触发
    branches: [ "master" ] 
  pull_request: 
    branches: [ "master" ]

#构建工作
jobs:
  #每一项任务的job_id
  build:
    #指定运行所需要的虚拟机环境，在最新的Ubuntu操作系统上运行
    runs-on: ubuntu-latest

    #用于配置当前workflow的参数
    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x]
    #步骤
    steps:
    #使用v3版本的checkout这个action，获取源码
    - uses: actions/checkout@v3
    #为step指定一个名称，将会在 github action 的控制台中显示
    - name: Use Node.js ${{ matrix.node-version }}
    #使用v3版本的setup-node来安装nodejs
      uses: actions/setup-node@v3
      with:
        #指定node的版本
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm install
    - run: npm run build

每个 action 都是一个独立脚本，使用uses语法引用 action。比如，actions/setup-node就表示https://github.com/actions/setup-node这个仓库，它代表一个 action，作用是安装 Node.js

actions市场：github.com/marketplace...

上述代码转为JSON为：

{
    "name": "Node.js CI",
    "on": {
        "push": {
            "branches": [
                "master"
            ]
        },
        "pull_request": {
            "branches": [
                "master"
            ]
        }
    },
    "jobs": {
        "build": {
            "runs-on": "ubuntu-latest",
            "strategy": {
                "matrix": {
                    "node-version": [
                        "14.x",
                        "16.x",
                        "18.x"
                    ]
                }
            },
            "steps": [
                {
                    "uses": "actions/checkout@v3"
                },
                {
                    "name": "Use Node.js ${{ matrix.node-version }}",
                    "uses": "actions/setup-node@v3",
                    "with": {
                        "node-version": "${{ matrix.node-version }}",
                        "cache": "npm"
                    }
                },
                {
                    "run": "npm install"
                },
                {
                    "run": "npm run build"
                }
            ]
        }
    }
}

五、示例：项目发布到Github Pages

1. 新建token

在Github个人信息中选择settings > 选择Developer Settings（最后一行）> Personal access tokens下选择Fine-grained tokens > 点击Generate new token

设置名称，过期时间，描述可任意填写。repository access选择Only select repositories，点击Select repositories选择将这个token应用于某个固定的项目

在Permissions权限中，可先将所有权限都开启 > 然后点击Generate token，将生成的token复制好

2. 使用token

项目设置settings > 选择Secrets and variables中的actions > 点击New repository secret

这里token名称为ACCESS_TOKEN（如果你不用这个名字，后面脚本里的变量名也要跟着改）

3. 设置应用发布后的根目录

（1）使用creat-react-app创建一个React项目

（2）修改package.json，加一个homepage字段

"homepage": "<https://cwjbjy.github.io/react-ts-manage>",

homepage字段的作用：

配置之前，打包后index.html中引入的js文件路径

<script defer="defer" src="/static/js/main.100c581f.js"></script>

配置之后，打包后index.html中引入的js文件路径

<script defer="defer" src="/react-ts-manage/static/js/main.100c581f.js"></script>

注意：

1. 只有使用creat-react-app的项目进行该配置，其他脚手架按需配置

2. 对于放在public文件夹下的js文件不会被编译，因此会少react-ts-manage根目录配置，会404

3. 路由使用hash模式比较方便

4. 自动化配置文件 ci.yml

新建.github/workflows/ci.yml

name: GitHub Actions Build and Deploy
on:
  push:
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Install and Build
        run: |
          npm install
          npm run build

      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: build
          branch: gh-pages
          token: ${{ secrets.ACCESS_TOKEN }}

上面这个 workflow 文件的要点如下

1.整个流程在master分支发生push事件时触发

2.只有一个job，运行在虚拟机环境ubuntu-latest

3.第一步是获取源码，使用的 action 是actions/checkout

4.第二步是编译和构建

5.第三步是部署，使用的action是JamesIves/github-pages-deploy-action

6.第三步JamesIves/github-pages-deploy-action需要进行额外的配置

folder: build 构建成果所在目录，这里使用creat-react-app脚手架打包后的文件名为build，如果是dist文件名，folder参数需要改为dist

branch: gh-pages 发布分支，构建成功后，会新建gh-pages分支

token：${{ secrets.ACCESS_TOKEN }} GitHub 密钥，因为密钥是秘密变量，所以需要写在双括号里面

5. 查看Github Pages

1. 将项目推送到远程分支，触发push

2. 在项目的setting中查看Pages，由于使用了JamesIves/github-pages-deploy-action，会自动生成，过个几分钟可看到页面生成链接，点击链接查看效果

六、结尾

源码地址：cwjbjy/github-actions-demo

demo项目展示地址：cwjbjy.github.io/github-acti...

参考文档：

Create React App：create-react-app.dev/docs/deploy...

GitHub Actions：docs.github.com/en/actions/...

GitHub Actions 入门教程：www.ruanyifeng.com/blog/2019/0...