详解github workflows流

Workflows允许你在 GitHub(文章以此为例) 仓库中自动化构建、测试、部署等软件开发流程

1. 什么是Workflows

GitHub Actions 是 GitHub 提供的 CI/CD（持续集成/持续部署）平台，可以自动化执行软件开发工作流。基本上代码管理都支持actions，百用不赖
Workflow 是 Actions 中的一个可配置的自动化过程，由一个或多个 job 组成，由特定事件触发。每个 workflow 是一个独立的 YAML 文件，存放在仓库的 .github/workflows 目录下。

2. 基本概念

概念	说明
Workflow	一个自动化流程，由一个 YAML 文件定义。
Event	触发 workflow 运行的特定活动，如 `push`、`pull_request`、`schedule` 等。
Job	workflow 中的一个任务，由多个 step 组成。一个 workflow 可以包含多个 job，它们可以并行或串行运行。
Step	job 中的单个任务，可以是 shell 命令或一个 action。
Action	可复用的最小单元，可以封装常用操作（如检出代码、设置 Node.js 环境等）。
Runner	运行 workflow 的服务器。GitHub 提供托管运行器（如 `ubuntu-latest`、`windows-latest`），也可自托管。

3. 简单示例

在仓库根目录下创建 .github/workflows 目录，然后放入一个或多个 .yml 或 .yaml 文件实例如下

yaml 复制代码

name: CI  # 名称

on:  # 触发条件
  push:
    branches: [ main ]

jobs: # 定义作业
  build:
    runs-on: ubuntu-latest  # 运行环境
    steps:
      - name: Checkout code
        uses: actions/checkout@v4  # 使用官方 checkout action
      - name: Run a one-line script
        run: echo Hello, world!

4. 触发事件 (on)

on 字段定义 workflow 何时运行。可以是单个事件、事件列表，或带有条件的事件。

4.1 基本事件

push 代码推送时触发
pull_request PR 相关事件
workflow_dispatch 手动触发（需要在 GitHub 界面点击按钮）
schedule 定时触发（cron）
其他事件：如 release、issues、watch、fork见 👉🏻 详细文档地址

下面是详细的事件类型，贯穿仓库管理中的各个过程和节点。

4.2 多事件与条件过滤

可以组合多个事件，并利用 branches、paths、tags 等过滤器。

yaml 复制代码

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
    paths-ignore:
      - 'docs/**'

5. Jobs 与 Steps

Jobs: 定义一个任务

Steps: 每个 step 可以是一个 run （执行 shell 命令）或 uses（引用一个 action）。

yaml 复制代码

jobs:
  job1: 
    runs-on: ubuntu-latest # 指定运行器镜像。常用值：`ubuntu-latest`, `windows-latest`, `macos-latest`，也可以指定版本如 `ubuntu-22.04`。
    steps:
      - name: Step 1 # 可选，显示在日志中，推荐使用。
        if: github.ref == 'refs/heads/main'  # 使用 `if` 条件，支持表达式。
        run: echo "Step 1"
        with:
            node-version: '22'
  job2:
    runs-on: windows-latest
    needs: job1   # job2 在 job1 完成后运行；（定义依赖关系，默认所有 job 并行运行，加 `needs` 后变为串行）
    steps:
      - name: Step 2
        run: echo "Step 2"

6. Actions 的使用

Actions 是可复用的代码单元，可以从 GitHub Marketplace 获取或自定义。

6.1 使用官方或第三方 Action

格式：{owner}/{repo}@{ref} 或 {owner}/{repo}/{path}@{ref}

yaml 复制代码

- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: my-artifact
    path: dist/

6.2 自定义 Action

可以创建 Docker 容器 Action 或 JavaScript Action，放在仓库中本地引用：

yaml 复制代码

- name: My custom action
  uses: ./.github/actions/my-action

7. 环境变量与 Secrets

7.1 环境变量

可以在 workflow、job 或 step 级别设置环境变量。

yaml 复制代码

env:
  NODE_ENV: production

jobs:
  build:
    env:
      API_URL: https://api.example.com
    steps:
      - name: Use env
        run: echo ${{ env.API_URL }}

7.2 Secrets

敏感信息如密码、token 应存储在 GitHub 仓库的 Settings → Secrets and variables → Actions 中，然后在 workflow 中通过 ${{ secrets.SECRET_NAME }} 引用。

yaml 复制代码

- name: Deploy
  run: npm run deploy -- --token ${{ secrets.DEPLOY_TOKEN }}

注意：Secrets 不会出现在日志中，但需小心避免将 secret 作为命令行参数输出（如 echo ${{ secrets.TOKEN }} 会暴露）。

8. 矩阵策略 (Matrix)

矩阵允许你使用变量组合并行运行多个 job，常用于测试多个操作系统、Node.js 版本等。

yaml

yaml 复制代码

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [16, 18, 20]
      fail-fast: false  # 是否在某个组合失败时取消所有
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

matrix：定义变量组合。
include/exclude：可以添加或排除特定组合。

9. 缓存依赖

通过 actions/cache 可以缓存依赖，加速构建。

yaml 复制代码

- name: Cache npm
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

更常见的是使用针对特定生态的缓存 action，如 actions/setup-node 已内置缓存：

yaml 复制代码

- uses: actions/setup-node@v4
  with:
    node-version: '18'
    cache: 'npm'

10. 工件 (Artifacts) 与部署

10.1 上传/下载工件

可以在 job 间传递文件。

yaml 复制代码

- name: Upload build
  uses: actions/upload-artifact@v4
  with:
    name: build
    path: dist/

- name: Download build
  uses: actions/download-artifact@v4
  with:
    name: build
    path: dist/

10.2 部署到 GitHub Pages

yaml 复制代码

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./dist

GITHUB_TOKEN 是 GitHub 自动提供的临时 token，具有仓库写入权限。

11. 条件判断与上下文

11.1 条件执行

使用 if 条件，支持表达式。

yaml 复制代码

- name: Only on main branch
  if: github.ref == 'refs/heads/main'
  run: echo "Deploying..."

11.2 上下文

GitHub Actions 提供丰富的上下文变量，如 github、env、secrets、matrix 等。

yaml 复制代码

- name: Print event name
  run: echo ${{ github.event_name }}

常用上下文：

github：包含仓库信息、触发者等。
runner：运行器信息。
env：环境变量。
secrets：仓库机密。
steps：上一步的输出。

12. 工作流嵌套与复用

12.1 调用其他 workflow

使用 workflow_call 事件，可以在一个 workflow 中调用另一个 workflow。

被调用的 workflow 需定义 on: workflow_call，并可定义输入和输出。

yaml 复制代码

# .github/workflows/build.yml
name: Build
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
    secrets:
      npm_token:
        required: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
      - run: npm run build

调用方：

yaml 复制代码

name: Main Workflow
on: push
jobs:
  call-build:
    uses: ./.github/workflows/build.yml
    with:
      node-version: '18'
    secrets:
      npm_token: ${{ secrets.NPM_TOKEN }}

13. 运行器组与自托管运行器

如果不想使用 GitHub 托管运行器，可以添加自托管运行器（Self-hosted runner）。

yaml 复制代码

jobs:
  build:
    runs-on: self-hosted

可以为自托管运行器指定标签，如 runs-on: [self-hosted, linux]。

14. 调试与日志

启用 step 调试：在 workflow 中设置 ACTIONS_STEP_DEBUG secret 为 true，会输出更详细的日志。
启用 runner 调试：设置 ACTIONS_RUNNER_DEBUG secret 为 true，会输出 runner 级别的调试信息。
手动重试：在 GitHub Actions 页面，可以重新运行失败的 job。

15. 安全最佳实践

最小权限原则 ：使用 permissions 字段限制 workflow 的 token 权限。
yaml 复制代码
```
permissions:
  contents: read
  issues: write
```
避免在日志中打印 secrets。
使用环境 (Environment) ：对部署等敏感操作，可配置环境并设置保护规则。
yaml 复制代码
```
environment: production
```
审查第三方 Action：优先使用官方或经过验证的 Action，固定版本 tag 或 commit SHA。

参考资料：