CI/CD / 系统课时

构建应用的 Docker 镜像

构建应用的 Docker 镜像

把应用放进容器流水线时,关键不是“执行一次 build”,而是让 GitHub Actions 能稳定找到 Dockerfile、生成可追踪的镜像标签,并在后续步骤确认镜像确实存在。本课完成一条最小可验证的镜像构建链路。

学习目标

  • 在 GitHub Actions Runner 中使用 docker build 构建应用镜像
  • 使用提交 SHA 生成可追踪的镜像标签
  • 通过 docker image inspect 验证镜像构建结果

从源码到 Runner 中的镜像

典型流程包含三个对象:仓库源码、GitHub 托管 Runner 和构建后的本地镜像。actions/checkout 先把源码放到 Runner 工作目录,Docker 再读取构建上下文和 Dockerfile,最终把镜像保存在该 Job 使用的 Runner 中。

GitHub Actions 构建 Docker 镜像流程

Runner 是临时环境,因此这里构建出的镜像不会自动进入镜像仓库,也不能依赖它在另一个 Job 中继续存在。若后续需要发布,应在同一 Job 中推送 Registry,或者采用明确的跨 Job 制品方案。

编写镜像构建步骤

假设仓库根目录已经存在可用的 Dockerfile,下面的 Workflow 在每次推送到 main 时构建镜像。${{ github.sha }} 是当前触发 Workflow 的提交 SHA,用它做标签可以把镜像与源码版本对应起来。

yaml
name: Build Docker image

on:
  push:
    branches:
      - main

jobs:
  build-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Build image
        run: docker build --tag my-app:${{ github.sha }} .

      - name: Verify image
        run: docker image inspect my-app:${{ github.sha }}

这份配置属于可运行的 Workflow 片段,但依赖仓库根目录已有能够成功构建的 Dockerfile。末尾的 . 表示把当前目录作为构建上下文;如果 Dockerfile 或需要 COPY 的文件不在这个上下文中,就需要调整路径。

预期结果

text
Run docker build --tag my-app:<ID> .
...
Successfully built <ID>
Successfully tagged my-app:<ID>
...
Run docker image inspect my-app:<ID>
[
  {
    ...
  }
]

<ID> 代表实际提交 SHA、镜像 ID 等动态值,不同运行产生的值会不同。Docker/BuildKit 的具体构建日志格式也可能随 Runner 镜像和 Docker 版本变化,因此应以构建步骤退出码为主要成功依据,以 docker image inspect 成功作为镜像存在的验证。

标签为什么要可追踪

只构建 my-app:latest 虽然简单,但当流水线连续执行多次时,很难仅凭标签确认镜像来自哪次提交。使用提交 SHA 可以建立“源码提交 → Workflow Run → 镜像”的对应关系,部署或回滚时也更容易定位版本。

实际发布时通常还会增加版本号、分支名等标签,但不可变的提交标识仍然很有价值。标签只是镜像引用的一部分,并不会改变镜像内容;相同构建输入是否产生完全相同的镜像,还受基础镜像、依赖下载和构建过程等因素影响。

构建失败先检查什么

docker build 失败时,应先看错误发生在哪一层,而不是直接反复重跑。常见问题包括 Dockerfile 路径不正确、构建上下文遗漏文件、COPY 源路径不存在,以及依赖下载命令失败。

可以先在本地仓库根目录执行与流水线相同的命令:

bash
docker build --tag my-app:local-test .
docker image inspect my-app:local-test

预期输出

text
...
Successfully tagged my-app:local-test
[
  {
    ...
  }
]

若本地和 Actions 都失败,应优先修复 Dockerfile 或构建上下文;若只有 Actions 失败,再比较 Runner 的工作目录、文件大小写、架构和构建环境。这样可以把“镜像有没有成功生成”变成流水线中明确可验证的结果,而不是只依赖日志中的一句成功提示。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构建应用的 Docker 镜像

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通