Dockerfile 生产级实践：构建缓存、多阶段构建与镜像安全

很多做容器化改造的朋友，对 Dockerfile 的第一印象往往是“不就是把部署步骤写成文件嘛”。实际用起来才发现，写得随意的 Dockerfile 和写得讲究的 Dockerfile，在构建速度、镜像体积、安全性和可维护性上的差距能相差十倍。这篇“Docker 专题(七)”我就把 Dockerfile 从指令细节到构建原理、从踩坑记录到生产级模板完整过一遍，适合已经会用 Docker 基本命令、正在尝试自己写 Dockerfile 的开发者，也适合想在团队里推行镜像交付规范的读者。

1. 写 Dockerfile 之前：先想清楚你要交付的是“镜像”还是“环境”

先纠正一个普遍误区：Dockerfile 不是简单的“部署步骤说明”，它描述的是镜像层的构建过程，而镜像的最终形态是一套包含操作系统文件、运行时、依赖和应用代码的只读模板。所以写 Dockerfile 之前，心里要有两张图：第一张是最终镜像运行起来之后，容器里的文件系统长什么样；第二张是构建过程中，哪些文件会进入镜像、哪些不会。

1.1 镜像的本质：三层结构

你可以把一个镜像拆成三个部分：底层操作系统基础层、中间依赖层、顶层应用代码层。

底层基础层一般来自FROM指定的基础镜像，比如系统发行版、官方运行时镜像；中间依赖层负责把应用所需的库、包管理器和配置文件“安装”进去；顶层应用层则是最容易变化的业务代码。这三层里的任何一层发生变化，都会导致该层以及它之上的所有层重新构建，这点后面讲缓存时会反复用到。

所以在动手写 Dockerfile 之前，先回答三个问题：

• 应用是什么类型？是常驻服务（Web 服务、消息消费者）、一次性任务（批处理脚本、数据迁移），还是定时任务？不同类型的应用决定了基础镜像选择、启动命令写法都不一样。
• 构建产物是否需要编译？有些语言（Go、C++）需要编译出二进制，有些语言（Python、Node）直接把源码和依赖拷进镜像即可。这直接决定你需不需要“多阶段构建”。
• 运行镜像时需要哪些配置变量？哪些是构建期就固定的，哪些是运行期由外部传入的？这决定了你用ARG还是ENV。

把这几个问题想清楚，再往下写，你的 Dockerfile 才不会只是在“碰运气式”地把命令堆在一起。

1.2 开始前确认两件事

第一，确认 Docker 版本支持 BuildKit。现在 Docker 20.10 以上默认就开启了 BuildKit，新语法如COPY --link、RUN --mount=type=cache都依赖它。你可以在构建时加上DOCKER_BUILDKIT=1，或者直接在 Docker 配置里开启。

第二，确认.dockerignore文件存在。就算你的 Dockerfile 只写了三行，没有.dockerignore也会把构建上下文里一堆无关文件打包发送给守护进程，拖慢构建速度，还容易把敏感文件带进镜像。后面专门有一章说这个。

2. FROM 指令的三个隐藏约束：基础镜像决定“血统”

FROM是 Dockerfile 的第一条有效指令，它指定了基础镜像镜像。看似简单，但这里很值得多花心思，因为基础镜像直接决定了镜像的攻击面、体积上限和可维护性。

2.1 不用 latest，要用明确版本标签

FROM ubuntu:latest这种写法非常危险。latest是个移动标签，它会随着发行方更新而悄悄变成新版本。今天构建没问题，三个月后构建的时候基础镜像可能已经换了大版本，导致系统包源变了、运行时行为变了，容器里跑的应用就莫名其妙出问题。

更稳妥的做法是锁定标签，比如ubuntu:22.04、node:20-bookworm-slim，甚至更进一步直接固定到 digest，如ubuntu:22.04@sha256:xxxx。锁定 digest 的缺点是每次升级基础镜像都要手动更换哈希值、重新验证，日常项目锁标签就够了，做严肃交付的场景才需要锁 digest。

2.2 基础镜像不是越小越好

很多人一看到alpine体积小就无脑用，但 alpine 的优点是“小”，代价是使用了 musl libc 而不是 glibc。很多预编译的二进制依赖 glibc，在 alpine 上直接跑不起来；还有些 Python 包在 alpine 上需要现场编译，反而比在 Debian 上耗时更久。

我的个人经验是：

不要为了“小”而牺牲“稳”。镜像体积的优化更多应该靠多阶段构建，而不是在基础镜像上纠结几十兆。

2.3 架构匹配问题

在 Apple 芯片的 Mac（ARM64）上构建的镜像，传到 x86_64 服务器上默认是跑不起来的（除非配置了多架构 manifest）。如果你团队里有多种开发机，构建时可以用docker buildx build --platform linux/amd64,linux/arm64同时打出多架构镜像，再推到仓库。这样拉取时 Docker 会按当前平台自动选择对应的架构。这块属于 CI 配置层面的内容，Dockerfile 本身要保证的是——你的依赖包有没有分架构版本。

3. RUN、COPY 与 ADD 的职责边界：别把一切都塞进一条 RUN

Dockerfile 里最常用的三条指令是RUN、COPY、ADD。它们的职责其实非常清晰：COPY负责把本地文件放进镜像，ADD是COPY的增强版（支持解压、支持远程 URL），RUN负责在镜像内执行命令、生成新的层。但在实际项目里，我见过太多把这三者混用的写法，尤其是把“下载依赖+编译+清理”全部塞进一条超长RUN的。

3.1 RUN 指令的两种执行形式

RUN有两种写法：

# Shell 形式，等价于 /bin/sh -c "apt-get update && apt-get install -y curl" RUN apt-get update && apt-get install -y curl # Exec 形式，直接执行命令，不走 shell RUN ["apt-get", "update"]

推荐使用 Shell 形式，因为你在一条RUN里往往要做“更新索引、安装、清理”等多个连续操作。

但注意 Exec 形式有个经典坑：如果命令里有环境变量替换，Exec 形式不会经过 shell 解析，所以RUN ["echo", "$HOME"]输出的是字面量$HOME而不是/root。遇到这类需求，老老实实用 Shell 形式。

3.2 为什么建议把一条长 RUN 拆成多条

先看一个反面例子：

RUN apt-get update && apt-get install -y build-essential libpq-dev && pip install --no-cache-dir -r requirements.txt && rm -rf /var/lib/apt/lists/*

这个写法把安装系统依赖、安装 Python 依赖、清理缓存放在一起，优点是一个层搞定、镜像层数少。但缺点是——只要requirements.txt有改动，或者任何一个系统包版本变了，整条 RUN 全部重跑，连带的系统包安装也要重新执行。

更合适的拆分方式是：

# 第一层：安装系统级依赖和清理，除非依赖列表变了，否则不会重跑 RUN apt-get update && apt-get install -y --no-install-recommends build-essential libpq-dev && rm -rf /var/lib/apt/lists/* # 第二层：安装 Python 依赖 COPY requirements.txt /tmp/requirements.txt RUN pip install --no-cache-dir -r /tmp/requirements.txt

这样拆完之后，requirements.txt一变，只重跑第二层，第一层直接从缓存里取。构建速度提升非常明显。

3.3 ADD 的三个坑

ADD比COPY多了解压和远程 URL 能力，但越是能力多，越要克制：

• ADD xxx.tar.gz /app/会自动解压，有时你本意只是想把压缩包作为文件放进镜像做备份，结果被解压了，容易踩坑。
• ADD支持从远程 URL 拉文件，但构建时拉远程文件无法利用缓存且不稳定，而且拉下来的文件没有校验机制，不如先curl下载再COPY。
• ADD会自动改变目标目录下文件的权限模式（比如 tar 包里的 owner 信息会保留），这经常造成后续容器启动时遇到权限问题。

所以我的准则是：本地文件进镜像用COPY，需要解压现场才用ADD，远程下载一律不用ADD。

4. 构建缓存失效的完整逻辑：重新认识“层”这个概念

Dockerfile 的每条指令都会产生一个镜像层，而构建缓存效验的规则，决定了镜像的重建效率。很多人只知道“改文件会失效缓存”，但具体怎么失效、怎么利用缓存，需要理解底层的匹配逻辑。

4.1 缓存匹配的原理

Docker 守护进程在做缓存匹配时，会计算当前指令和“这条指令对应的镜像层”的 cache key。对COPY指令，cache key 包含了原文件的校验和（checksum）；对RUN指令，cache key 是命令字符串本身，根据上一层缓存结果去判断。

这意味着：

• 如果一条COPY拷入的文件内容变化了，这一层失效，后续所有层都失效。
• 如果一条RUN的字符串发生变化（即使只是多了一个空格），这一层也失效。
• 如果上层失效了，下层即使指令完全没变，也无法使用缓存，必须重新执行。

4.2 经典的错误顺序

新手最常见的写法是：

COPY . /app # 整个项目代码，包括源码、配置文件、测试 RUN apt-get update && apt-get install -y python3-dev RUN pip install -r /app/requirements.txt

只要任意一行代码有改动，第一条COPY . /app的校验和就变了，一次小小的提交就会导致后面系统依赖、全部 Python 包重新安装。构建速度慢到怀疑人生。

正确顺序是：把变化频率最低的文件放最前面，变化最频繁的放最后面。

# 稳定层：基础系统依赖 RUN apt-get update && apt-get install -y --no-install-recommends python3-dev && rm -rf /var/lib/apt/lists/* # 较稳定层：依赖声明文件 COPY requirements.txt /tmp/requirements.txt RUN pip install --no-cache-dir -r /tmp/requirements.txt # 最不稳定层：业务代码 COPY . /app

这样改业务代码时，前面三层全部走缓存，构建时间能压缩到几秒钟。

4.3 利用 BuildKit 特性：挂载缓存

即便你把文件顺序排对了，像apt-get install、npm install这种操作在层缓存失效之后，还是要重新联网安装。为了进一步提速，BuildKit 支持在RUN执行期间挂载临时缓存：

# syntax=docker/dockerfile:1 FROM node:20-alpine AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm \ npm ci --prefer-offline COPY . . RUN npm run build

这里--mount=type=cache,target=/root/.npm会把 npm 的缓存目录挂到宿主机缓存空间，即使镜像层整体失效，已下载的包也不会重新下载。Debian/Ubuntu 的apt缓存、Go 的模块缓存、Python 的pip缓存都可以用同样的方式处理。

4.4 什么时候强制不走缓存

更新系统包索引、拉取新版本元数据时，旧缓存反而会干扰结果。比如：

RUN apt-get update && apt-get install -y ...

如果缓存命中，apt-get update不会重新执行，而包索引过期会导致后续安装报错。此时你需要用docker build --no-cache强制重建，或者定期主动让这条指令失效（比如在命令后面追加#注释和日期）。

5. ARG 与 ENV 的正确分工：构建期与运行期的变量边界

ARG和ENV都用于设置变量，但作用范围完全不同。很多人一开始没分清，导致构建出的镜像要么少了配置、要么把敏感信息写进了镜像。

5.1 两者的作用域差异

• ARG只在构建阶段有效，容器运行时不存在。
• ENV是环境变量，既可以在构建阶段被RUN指令引用，也会保留在最终镜像的环境配置中，容器启动时自动生效。

举个例子：

ARG APP_VERSION=1.0.0 ENV APP_ENV=production RUN echo "$APP_VERSION" > /app/version.txt # 可以正常写入 RUN echo "$APP_ENV" >> /app/env.txt # 也可以正常写入，但容器启动后 APP_ENV 依然存在

5.2 典型的敏感信息事故

最常见的坑是：把密码、API Key 写进ENV，构建阶段用来做认证，然后打进镜像层里。即使后来你在镜像里把文件删了，删除动作本身只是新加一层，原来的层仍然存在于镜像历史中。别人只要docker history一下就能把密钥翻出来。

正确做法：

• 构建期用于认证的凭据用ARG，并且尽量配合 BuildKit 的--secret挂载方式，避免把密钥值直接写在 Dockerfile 里。
• 运行期需要的密钥用--env或env_file在容器启动时注入，不要写死在镜像里。

5.3 给 ARG 设置默认值还是不设置

ARG可以设默认值，也可以不设。不设默认值时，如果构建命令没传--build-arg，这个变量就是空字符串。经典报错场景：Dockerfile 里写了ARG APP_PORT，但构建时忘了传，最后EXPOSE $APP_PORT变成了EXPOSE空值，导致端口映射不生效。给默认值可以降低出错率，但也会掩盖“构建参数缺失”的问题。

我的习惯是：必须由外部注入的参数不设默认值，并在启动前后做校验；纯优化项、版本号这类参数才设默认值。

5.4 ARG 和 ENV 配合使用的场景

有时候一个版本号既要在构建期用来下载指定版本依赖，又要在运行期显示在应用日志里。这时可以：

ARG APP_VERSION=2.8.0 ENV APP_VERSION=$APP_VERSION

ENV的值可以在构建期引用ARG，实现一次传参全程可用。注意这种写法里ARG声明必须放在ENV之前。

6. 多阶段构建：一次编译产物如何优雅瘦身

多阶段构建是 Dockerfile 里最能体现工程水平的一个设计。它的核心思想是：构建过程借用“肥”环境（包含完整编译工具链、源码、依赖缓存），最终产物只把“瘦”的运行时文件拷贝进镜像。这样镜像里既没有编译器，也没有源码和中间文件。

6.1 一个 Java 项目的实战拆解

假设我们要打包一个 Spring Boot 应用。单阶段写法：

FROM maven:3.9-eclipse-temurin-17 WORKDIR /app COPY . . RUN mvn package CMD ["java", "-jar", "target/app.jar"]

这个镜像体积有多大？它包含 Maven、JDK、全部源码和本地仓库依赖，动辄 1GB 以上。用多阶段构建：

# 阶段一：构建 FROM maven:3.9-eclipse-temurin-17 AS build WORKDIR /app COPY . . RUN mvn -B package -DskipTests # 阶段二：只保留运行时 FROM eclipse-temurin:17-jre WORKDIR /app COPY --from=build /app/target/app.jar ./app.jar EXPOSE 8080 USER nobody ENTRYPOINT ["java", "-jar", "app.jar"]

第二阶段的基础镜像是纯 JRE，不含 Maven、不含源码，只有target/app.jar。镜像体积能缩减 60% 以上，安全攻击面也大幅减少。

6.2 不同语言的多阶段构建参照

Go 应用：第一阶段用golang:1.22编译，第二阶段可以直接用scratch或者gcr.io/distroless/static。不过注意，如果应用内部做证书校验、解析域名，scratch里没有 CA 证书，需要额外从构建阶段 COPY 一份/etc/ssl/certs/ca-certificates.crt。

Python 应用：第一阶段用完整工具链编译带 C 扩展的依赖，第二阶段用python:slim只拷贝 site-packages 和应用代码。实际操作时要注意 Python 的 .so 依赖动态库，所以第二阶段镜像最好和第一阶段是同一个系统发行版系列，避免 glibc 版本不一致。

6.3 多阶段构建的额外优势

除了缩小镜像体积，多阶段构建还有个隐性好处——每条阶段都可以拥有完全不同的基础镜像。前端项目可以这样优化：

FROM node:20-alpine AS build WORKDIR /app COPY package.json ./ RUN npm install COPY . . RUN npm run build FROM nginx:alpine COPY --from=build /app/dist /usr/share/nginx/html

构建阶段用 Node.js，运行阶段用 Nginx。最终镜像里没有 Node 运行时，只有一个静态资源服务器，非常干净。

6.4 命名阶段的技巧

每个FROM可以用AS起一个语义化名字，在后续阶段通过COPY --from=build引用。阶段名建议用build、deps、runtime这种可读名字。如果多阶段之间还有需要共享的中间文件，更优雅的方式是用COPY --from=busybox:latest /some/file /dest直接引用外部镜像做数据提取，这在制作证书、编译静态资源时很常用。

7. 构建上下文与 .dockerignore：几乎人人踩过的“镜像膨胀”坑

有一次帮同事排查一个奇怪的问题：明明 Dockerfile 里只COPY app.py，但构建上下文要传几十秒，生成的镜像也有 800MB。原因很简单——构建上下文目录里放着一个几十 MB 的.git目录和虚拟环境目录，COPY指令虽然没把它们加进镜像，但构建上下文在指令执行前就已经全部打包发送给了 Docker 守护进程。

7.1 构建上下文是什么

执行docker build -t myapp:v1 .时，Dockerfile所在目录下的所有文件都会被搜集进构建上下文，发送给 Docker daemon。COPY只能访问构建上下文范围内的文件，不能访问外部路径（COPY ../xxx这种写法会直接报错）。

.dockerignore的作用就是在发送之前排除指定文件。它的语法和.gitignore基本一致，但很多人经常忘了加。

一个合理的 Node 项目.dockerignore长这样：

node_modules npm-debug.log .git .gitignore .DS_Store Dockerfile .dockerignore dist coverage .env

注意这里我把Dockerfile也排除掉了。很多人会奇怪：Dockerfile 不是必须的吗？实际上 Dockerfile 是单独发送给 daemon 的，不需要通过构建上下文传进去。把Dockerfile写进.dockerignore可以减少上下文体积，也能避免某些场景下文件拷贝的奇怪行为。

7.2 排除 .env 真的很重要

.env文件里存放着密钥，如果不加排除，它会进入构建上下文，之后如果在 Dockerfile 里有执行docker build --no-cache时留下的层里被读取，就会泄露。更麻烦的是，即使后来你在镜像里删掉它，层历史里依然存在。所以.dockerignore里必须加.env、*.key、*.pem等敏感文件模式。

7.3 COPY 的权限处理：chown 和 chmod

当你的应用以非 root 用户运行时（下文会说），COPY把文件拷进镜像时默认是 root:root 权限。启动容器时应用没权限读。解决办法有两种：

COPY --chown=appuser:appuser ./app /app

如果要拷贝的是压缩包并希望自动解压，ADD同样支持--chown。还有一种情况是可执行权限：本地开发时你的.sh脚本可能没有可执行位，COPY不会改变权限，需要在RUN里显式执行chmod +x。

7.4 WORKDIR 的隐藏作用

WORKDIR的作用不只是切换目录，它还会影响后续RUN、CMD、COPY的相对路径基准。如果 Dockerfile 里没有WORKDIR，后续所有COPY都依赖当前工作目录，一旦你修改了FROM镜像的默认工作目录，Dockerfile 里的相对路径就会全部失效。

规范化写法是在FROM之后立即设置一次WORKDIR /app，后续路径全部基于它。同时，WORKDIR不存在时会被自动创建，不需要先RUN mkdir。

7.5 USER 指令：别让容器跑在 root 下

默认情况下，容器里的进程以 root 身份运行。对应用容器来说这个问题很大——一旦应用出现远程代码执行或文件上传漏洞，攻击者获得的就是容器内 root 权限，配合一些逃逸漏洞就能影响宿主机器。

标准做法是在 Dockerfile 末尾切换到非特权用户：

FROM golang:1.22 AS build WORKDIR /src COPY . . RUN CGO_ENABLED=0 go build -o /app/bin/app FROM gcr.io/distroless/static-debian12 WORKDIR / COPY --from=build /app/bin/app /app USER nonroot ENTRYPOINT ["/app"]

distroless 镜像内置了nonroot用户，可以直接用。Debian/Ubuntu 基础镜像可以自己创建用户：

RUN groupadd -r appuser && useradd -r -g appuser appuser USER appuser

注意切换到非 root 用户后，如果应用需要写文件（日志、临时目录），目标目录必须提前给这个用户授权，用RUN chown appuser:appuser /app/logs解决。

8. 给生产仓库准备一份 Dockerfile 模板与实测踩坑备注

最后给出一份可以直接放进生产项目里参考的 Dockerfile，配合每一条的“为什么这么做”。这个模板结合了前面几章涉及的所有要点，实测下来在构建时间、镜像体积和可维护性上都比较均衡。

# syntax=docker/dockerfile:1 FROM node:20-alpine AS build WORKDIR /app # 依赖安装层单独做，利用层缓存 COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm \ npm ci --prefer-offline # 业务代码放最后 COPY，高频变更不破坏前面缓存 COPY . . ARG APP_VERSION=dev ENV APP_VERSION=$APP_VERSION RUN npm run build # 运行阶段：用 Nginx 托管静态产物 FROM nginx:1.25-alpine WORKDIR /usr/share/nginx/html COPY --from=build /app/dist ./ RUN rm -rf /etc/nginx/conf.d/default.conf # 健康检查：容器编排平台会定时探测 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD wget -q --spider http://127.0.0.1/ || exit 1 # 降低运行权限 RUN sed -i 's#listen 80;#listen 8080;#; s#/usr/share/nginx/html;#/usr/share/nginx/html;#' /etc/nginx/conf.d/default.conf \ && sed -i '2i user nginx;' /etc/nginx/conf.d/default.conf EXPOSE 8080 USER nginx CMD ["nginx", "-g", "daemon off;"]

8.1 模板里的几个细节解释

npm ci而不是npm install，因为npm ci严格按照package-lock.json安装，不会动态升级依赖，保证构建一致性。--prefer-offline配合挂载缓存，能大幅降低无缓存重建时的耗时。

运行阶段切换USER nginx前，我把 Nginx 监听端口从 80 改到了 8080。这主要是考虑无特权端口：用 80 端口需要绑定低端口权限，容器内可能受NET_BIND_SERVICEcapability 限制；用 8080 这类高位端口更省事，也方便在编排平台上直接映射。

8.2 实测中经常翻车的几个点

• 忘记拷贝 CA 证书：用scratch或 distroless 镜像跑 Go 应用，应用里用https请求就失败。第一次遇到这个问题时排查了很久，最后发现就是镜像里没有/etc/ssl/certs。必须在编译阶段COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/。
• 时区问题：很多应用在日志里要打印本地时间。基础镜像默认时区是 UTC，需要额外加RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime。但因为镜像里不带tzdata包，有些精简镜像里根本没有/usr/share/zoneinfo，遇到这种情况要先apk add tzdata或apt-get install -y tzdata。
• 依赖缓存没有清理：RUN apt-get install之后如果不清理/var/lib/apt/lists/*，每一层都会带着大量索引文件，一个镜像能悄悄多出上百 MB。同理，pip install之后记得加--no-cache-dir，npm install用npm ci --prefer-offline而非直接install。
• 备份文件打进镜像：有些编辑器会在目录里生成*.bak、*.orig、*.swp文件。.dockerignore漏了这些模式，路径不深但是恶心，经常莫名踩到。

8.3 一条值得知道的跟进技巧：docker history 是排查利器

看镜像到底为什么这么大，别凭感觉猜。构建之后执行：

docker history 镜像名 --no-trunc --format "table {{.ID}}\t{{.Size}}\t{{.CreatedBy}}"

Size列会列出每一层的增量大小。哪个层大、命中哪个RUN或COPY，一眼就能定位。有时候你会在清理之后发现镜像是空的目录层，根源还是与COPY把整个目录拷进去了。用这个命令排查，比反复改 Dockerfile 猜效率高很多。

8.4 构建的固化与验证

如果你的项目要做 CI 接入，建议在 Dockerfile 构建完成之后顺手做一次容器内验证：

docker build -t demo-app:v1 . docker run --rm --entrypoint="" demo-app:v1 sh -c "test -f /app/config.yaml && echo config ok"

--entrypoint=""可以绕过镜像的默认启动命令，只跑一条测试命令来验证关键文件是否存在于镜像里。这个技巧我在排查“为什么镜像起不来”的时候几乎每次都用，因为很多问题在构建时不会暴露，只有到容器启动阶段才炸。

写在最后

回顾我自己从“能写出一个能跑的镜像”到“能写出一个长期可维护、构建快、体积小、权限安全的镜像”，最关键的转变不是背下更多 Dockerfile 指令，而是理解了镜像层的机制：文件顺序影响缓存、基础镜像决定血统、多阶段构建负责瘦身、USER 和 .dockerignore 负责安全。

顺手再说一个实用习惯：每次修改 Dockerfile 之后，我都会把完整构建命令贴在项目 README 的“本地构建”小节里，并注释上“如果构建失败，先试docker build --no-cache”。因为团队里总有新同事遇到旧缓存导致的疑难杂症，一句注释能省下很多无效沟通时间。容器化这件事，说白了就是把“环境即代码”落到每一条指令里，你的 Dockerfile 写得越克制，交付的镜像就越稳定。