使用 GitHub Actions 自动化构建

Table of contents

先决条件

完成本指南中从容器化 React.js 应用程序开始的所有先前部分。

你还必须拥有：

一个 GitHub 账户。
一个已验证的 Docker Hub 账户。

概述

在本节中，你将使用 GitHub Actions 设置一个 CI/CD 流水线，以自动执行以下操作：

在 Docker 容器中构建你的 React.js 应用程序。
在一致的环境中运行测试。
将生产就绪的镜像推送到 Docker Hub。

将你的 GitHub 仓库连接到 Docker Hub

为了启用 GitHub Actions 构建和推送 Docker 镜像，你需要安全地将你的 Docker Hub 凭据存储在新的 GitHub 仓库中。

步骤 1：将你的 GitHub 仓库连接到 Docker Hub

从 Docker Hub 创建一个个人访问令牌 (PAT)
1. 进入你的 Docker Hub 账户 → 账户设置 → 安全。
2. 生成一个具有 读/写 权限的新访问令牌。
3. 将其命名为类似 docker-reactjs-sample 的名称。
4. 复制并保存该令牌 —— 你将在步骤 4 中需要它。
在 Docker Hub 中创建一个仓库
1. 进入你的 Docker Hub 账户 → 创建仓库。
2. 对于仓库名称，请使用描述性名称 —— 例如：reactjs-sample。
3. 创建完成后，复制并保存仓库名称 —— 你将在步骤 4 中需要它。
为你的 React.js 项目创建一个新的 GitHub 仓库

将 Docker Hub 凭据添加为 GitHub 仓库机密

在你新创建的 GitHub 仓库中：

导航至： 设置 → 机密和变量 → Actions → 新建仓库机密。
添加以下机密：

名称	值
`DOCKER_USERNAME`	你的 Docker Hub 用户名
`DOCKERHUB_TOKEN`	你的 Docker Hub 访问令牌（在步骤 1 中创建）
`DOCKERHUB_PROJECT_NAME`	你的 Docker 项目名称（在步骤 2 中创建）

这些机密让 GitHub Actions 在自动化工作流期间能够安全地与 Docker Hub 进行身份验证。

将你的本地项目连接到 GitHub

通过从项目根目录运行以下命令，将你的本地项目 docker-reactjs-sample 链接到你刚创建的 GitHub 仓库：
$ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git
[!重要] 将 {your-username} 和 {your-repository} 替换为你的实际 GitHub 用户名和仓库名称。

要确认你的本地项目已正确连接到远程 GitHub 仓库，请运行：
$ git remote -v
你应该看到类似以下的输出：
origin https://github.com/{your-username}/{your-repository-name}.git (fetch) origin https://github.com/{your-username}/{your-repository-name}.git (push)
这确认了你的本地仓库已正确链接，并准备好将源代码推送到 GitHub。
将你的源代码推送到 GitHub

按照以下步骤将你的本地项目提交并推送到你的 GitHub 仓库：
1. 暂存所有文件以进行提交。
  $ git add -A
  此命令暂存所有更改 —— 包括新建、修改和删除的文件 —— 为提交做准备。
2. 提交你的更改。
  $ git commit -m "Initial commit"
  此命令创建一个提交，该提交将暂存的更改快照并附带描述性消息。
3. 将代码推送到 main 分支。
  $ git push -u origin main
  此命令将你的本地提交推送到远程 GitHub 仓库的 main 分支，并设置上游分支。

完成后，你的代码将在 GitHub 上可用，并且你配置的任何 GitHub Actions 工作流都将自动运行。

[!注意]
了解有关本步骤中使用的 Git 命令的更多信息：

Git add – 暂存更改（新建、修改、删除）以进行提交

Git commit – 保存暂存更改的快照

Git push – 将本地提交上传到你的 GitHub 仓库

Git remote – 查看和管理远程仓库 URL

步骤 2：设置工作流

现在，你将创建一个 GitHub Actions 工作流，该工作流构建你的 Docker 镜像，运行测试，并将镜像推送到 Docker Hub。

进入你在 GitHub 上的仓库，并选择顶部菜单中的 Actions 选项卡。
当提示时，选择 自行设置工作流。

这将打开一个内联编辑器以创建新的工作流文件。默认情况下，它将保存到： .github/workflows/main.yml
将以下工作流配置添加到新文件中：

name: CI/CD – React.js Application with Docker

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

jobs:
  build-test-push:
    name: Build, Test and Push Docker Image
    runs-on: ubuntu-latest

    steps:
      # 1. Checkout source code
      - name: Checkout source code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetches full history for better caching/context

      # 2. Set up Docker Buildx
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      # 3. Cache Docker layers
      - name: Cache Docker layers
        uses: actions/cache@v4
        with:
          path: /tmp/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: ${{ runner.os }}-buildx-

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

      # 5. Extract metadata
      - name: Extract metadata
        id: meta
        run: |
          echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT"
          echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

      # 6. Build dev Docker image
      - name: Build Docker image for tests
        uses: docker/build-push-action@v6
        with:
          context: .
          file: Dockerfile.dev
          tags: ${{ steps.meta.outputs.REPO_NAME }}-dev:latest
          load: true # Load to local Docker daemon for testing
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache,mode=max

      # 7. Run Vitest tests
      - name: Run Vitest tests and generate report
        run: |
          docker run --rm \
            --workdir /app \
            --entrypoint "" \
            ${{ steps.meta.outputs.REPO_NAME }}-dev:latest \
            sh -c "npm ci && npx vitest run --reporter=verbose"
        env:
          CI: true
          NODE_ENV: test
        timeout-minutes: 10

      # 8. Login to Docker Hub
      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

# 9. 构建并推送生产镜像
      - name: 构建并推送生产镜像
        uses: docker/build-push-action@v6
        with:
          context: .
          file: Dockerfile
          push: true
          platforms: linux/amd64,linux/arm64
          tags: |
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }}
          cache-from: type=local,src=/tmp/.buildx-cache

此工作流为您的 React.js 应用程序执行以下任务：

在每次针对 main 分支的 push 或 pull request 时触发。
使用 Dockerfile.dev 构建一个针对测试优化的开发 Docker 镜像。
在干净的容器化环境中使用 Vitest 执行单元测试，确保一致性。
如果任何测试失败，立即停止工作流 —— 强制执行代码质量。
缓存 Docker 构建层和 npm 依赖项，以加快 CI 运行速度。
使用 GitHub 仓库密钥安全地通过 Docker Hub 进行身份验证。
使用 Dockerfile 中的 prod 阶段构建一个生产就绪的镜像。
使用 latest 和短 SHA 标签标记并推送最终镜像到 Docker Hub，以便追踪。

Note

有关 docker/build-push-action 的更多信息，请参阅 GitHub Action README。

步骤 3：运行工作流

添加工作流文件后，是时候触发并观察 CI/CD 流程的实际运行情况了。

提交并推送您的工作流文件

在 GitHub 编辑器中选择“提交更改…”。
- 此次推送将自动触发 GitHub Actions 流水线。
监控工作流执行
1. 转到 GitHub 仓库中的 Actions 选项卡。
2. 点击进入工作流运行，以跟踪每个步骤：构建、测试，以及（如果成功）推送。
在 Docker Hub 上验证 Docker 镜像
- 工作流运行成功后，访问您的 Docker Hub 仓库。
- 您应该会在仓库中看到一个新镜像，包含：
  - 仓库名称：${your-repository-name}
  - 标签包括：
    - latest —— 代表最近一次成功的构建；非常适合快速测试或部署。
    - <short-sha> —— 基于提交哈希的唯一标识符，对版本跟踪、回滚和追踪非常有用。

Tip

为了维护代码质量并防止意外的直接推送，请启用分支保护规则：

导航到您的 GitHub 仓库 → 设置 → 分支。

在“分支保护规则”下，点击 添加规则。

指定 main 作为分支名称。

启用以下选项：

合并前需要拉取请求。

合并前需要状态检查通过。

这确保只有经过测试和审查的代码才能合并到 main 分支。

总结

在本节中，您使用 GitHub Actions 为您的容器化 React.js 应用程序设置了完整的 CI/CD 流水线。

您完成了以下工作：

为您的项目创建了一个新的 GitHub 仓库。
生成了一个安全的 Docker Hub 访问令牌，并将其作为密钥添加到 GitHub。
定义了一个 GitHub Actions 工作流，用于：
- 在 Docker 容器内构建您的应用程序。
- 在一致的容器化环境中运行测试。
- 如果测试通过，将生产就绪的镜像推送到 Docker Hub。
通过 GitHub Actions 触发并验证了工作流执行。
确认您的镜像已成功发布到 Docker Hub。

通过此设置，您的 React.js 应用程序现已准备好进行跨环境的自动化测试和部署 —— 提高信心、一致性和团队生产力。

下一步

接下来，了解如何在部署之前在 Kubernetes 上本地测试和调试您的 React.js 工作负载。这有助于确保您的应用程序在类似生产的环境中按预期运行，减少部署期间的意外情况。

Ask me about Docker

使用 GitHub Actions 自动化构建

先决条件

概述

将你的 GitHub 仓库连接到 Docker Hub

步骤 1：将你的 GitHub 仓库连接到 Docker Hub

步骤 2：设置工作流

步骤 3：运行工作流

总结

相关资源

下一步