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 中。

Runner 是临时环境,因此这里构建出的镜像不会自动进入镜像仓库,也不能依赖它在另一个 Job 中继续存在。若后续需要发布,应在同一 Job 中推送 Registry,或者采用明确的跨 Job 制品方案。
编写镜像构建步骤
假设仓库根目录已经存在可用的 Dockerfile,下面的 Workflow 在每次推送到 main 时构建镜像。${{ github.sha }} 是当前触发 Workflow 的提交 SHA,用它做标签可以把镜像与源码版本对应起来。
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 的文件不在这个上下文中,就需要调整路径。
预期结果
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 源路径不存在,以及依赖下载命令失败。
可以先在本地仓库根目录执行与流水线相同的命令:
docker build --tag my-app:local-test .
docker image inspect my-app:local-test预期输出
...
Successfully tagged my-app:local-test
[
{
...
}
]若本地和 Actions 都失败,应优先修复 Dockerfile 或构建上下文;若只有 Actions 失败,再比较 Runner 的工作目录、文件大小写、架构和构建环境。这样可以把“镜像有没有成功生成”变成流水线中明确可验证的结果,而不是只依赖日志中的一句成功提示。