上周帮一个朋友排查构建脚本同一个代码仓库、同一台机器他构建出来的镜像 1.2G我这边构建出来 340M容器跑起来功能完全一致。他第一反应是基础镜像选得不一样结果两边的FROM写的是同一行。差别全在中间那二十几行 Dockerfile 里合并与不合并的RUN、有没有清包管理器缓存、COPY把哪些不该进镜像的目录也塞了进去、多阶段构建有没有真正用上。这类问题在团队里极其普遍——Dockerfile 的语法十分钟就能翻完但把它写到生产可用靠的不是背指令而是对分层、缓存、构建上下文这三个概念的直觉。这篇就围绕 Dockerfile 展开从指令背后的分层机制讲到多阶段构建的落地写法再到构建缓存突然失效时怎么一层层定位。适合已经能跑通docker build、但镜像体积和构建时间一直不太理想的人也适合刚开始接触容器化、想把地基打扎实的同学。示例以一个典型的前后端项目为背景你可以直接对着自己的仓库改。1. 三个镜像体积差四倍问题从来不出在语法上1.1 一个几乎每个团队都遇到过的现场某项目组做过一次小统计让四位同事各自为同一个服务写 Dockerfile都能构建成功、都能跑起来最后镜像体积分别是 210MB、480MB、760MB 和 1.3GB。这四个人写的语法全对没有一条指令报错。体积差距的来源分别是基础镜像选了带完整工具链的版本、RUN没有合并导致中间产物被固化进层、构建上下文把node_modules和.git一起传了进去、以及没有使用多阶段构建。这件事说明一个道理Dockerfile 的正确有两个层次。第一层是能构建成功、容器能启动这叫语法正确第二层是镜像尽可能小、构建尽可能快、运行时尽可能安全这叫工程正确。绝大多数教程只教第一层而真正吃经验的是第二层。1.2 镜像的本质是一摞只读层的叠加要理解为什么中间产物会固化得先搞清楚镜像的构成。一个镜像由若干只读层layer自下而上叠加而成每条会修改文件系统的指令RUN、COPY、ADD都会生成一个新层。关键是层一旦生成就不可修改。这意味着如果你这么写RUN apt-get update RUN apt-get install -y curl RUN apt-get clean第三条apt-get clean确实删掉了缓存文件但删除动作发生在第四层而缓存文件实实在在躺在第二层里。镜像体积按所有层的总和计算第四层的删除只是一个白障whiteout标记并不会让第二层瘦下来。正确写法是把更新、安装、清理塞进同一条RUNRUN apt-get update \ apt-get install -y --no-install-recommends curl \ rm -rf /var/lib/apt/lists/*这个道理用生活类比很好理解往笔记本上写字写错了不能擦只能贴一张修正贴。修正贴看着是空白但底下的字还在纸的总厚度只增不减。1.3 能跑就行的代价会在什么时候显现有人会说镜像大点就大点反正服务器硬盘够。真正的代价不在硬盘而在三个地方。第一是分发时间每次滚动发布每个节点都要拉一遍镜像1.3G 和 340M 在几十台节点的规模下差的是分钟级第二是攻击面镜像里多出来的编译器、包管理器缓存、甚至.git目录都是潜在的暴露点第三是构建反馈速度一次构建八分钟谁都不愿意在本地频繁验证团队会退化成改完直接推到 CI 上碰运气。我在实际项目里的判断标准是一个纯运行时镜像比如 Java 或 Node 服务如果超过 500MB就要逐层盘一次docker history基本总能找到一层是多余的。2. FROM 那一行决定了后面所有优化的天花板2.1 基础镜像的三档选择与各自适用面FROM是整份 Dockerfile 的地基选错了后面再怎么精简都事倍功半。常见的选择大致分三档类型典型特征体积量级适用场景完整发行版镜像带包管理器、常用命令行工具数百 MB构建阶段、需要在线调试的环境精简发行版镜像去掉文档、部分工具保留包管理器几十到一百多 MB生产运行时需要装少量系统依赖极简/静态镜像无包管理器、无 shell 或仅极简 shell几 MB 到几十 MB静态编译产物、Go/Rust 等自包含二进制新手最容易犯的错是用完整发行版做运行时基础镜像因为装东西方便。但运行时的容器里其实不需要gcc、不需要vim、不需要curl——真要排查问题用docker exec进容器或者临时跑一个调试容器都行没必要把它们长期塞在镜像里。构建阶段用完整镜像、运行阶段用精简镜像这正是多阶段构建要解决的问题后面第 6 节会详细拆。2.2 tag 漂移昨天能构建今天突然失败FROM node:18这种写法很省事但它指向的是一个会移动的标签。上游哪天推送了新补丁版本你下次构建就可能在完全没改代码的情况下出现依赖行为变化。我遇到过最典型的一次是某个小版本更新后默认的 OpenSSL 配置变了导致一个 TLS 握手相关的测试开始随机失败排查了半天才发现是基础镜像变了。稳妥的做法有两个层次。日常开发可以固定到次版本号比如node:18.19比node:18稳。对可复现性要求高的生产构建直接固定到 digestFROM node:18.19-bookwormsha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxdigest 长得丑、换版本时麻烦换来的是今天构建和三个月后构建拉到的字节完全一致。什么时候需要这个级别的严格合规审计、线上事故回溯、多团队共享基础镜像这几种场景我认为是必须的。2.3 一条容易被忽略的构建平台参数在多架构环境下FROM的解析结果还跟构建平台有关。如果你的开发机是 ARM 架构、部署目标是 x86 服务器不显式指定平台时构建出来的镜像架构可能跟目标环境对不上表现为部署时报 exec format error。这时需要在FROM上加参数FROM --platformlinux/amd64 eclipse-temurin:17-jre更常见的做法是在构建命令里指定--platform让整份 Dockerfile 保持一致同时只解析一次基础镜像。需要注意交叉构建时如果RUN里有编译动作性能会明显下降通常要配合构建器builder来加速这部分属于构建环境的配置范畴本文不展开但值得知道有这个性能拐点。3. RUN 的分层账本合并、清理与缓存命中的连锁反应3.1 每条 RUN 都是一次独立的事务RUN是所有指令里最重的一条因为它在构建时真正执行命令并把整个文件系统的变化打包成新层。前面说过层不可改所以要建立一个心智模型每写一条RUN就当自己开了一个新的、永久保存的快照。基于这个模型几条实操原则自然就出来了。第一相关的操作尽量合并成一条。把apt-get update和install放在不同的RUN里是经典错误缓存命中的时候update那层可能用的是几周前的索引导致安装到过时的包甚至安装失败索引里的版本已经下架。合并之后两者同生共死要么都命中要么都重跑。第二长命令用反斜杠续行配合set -eux之类的开关让失败尽早暴露SHELL [/bin/bash, -o, pipefail, -c] RUN set -eux; \ groupadd -r app; \ useradd -r -g app -d /app -s /sbin/nologin app; \ mkdir -p /app; \ chown -R app:app /apppipefail这一项特别值得加。默认情况下cmd1 | cmd2的退出码只看cmd2前面管道挂了也不会让构建失败问题会被默默地构建成功掩盖掉。3.2 包管理器清理的正确姿势逐个说清不同语言的包管理器清理方式差异很大我按实际用到的顺序列一下都是在同一条RUN里收尾Debian/Ubuntu 系rm -rf /var/lib/apt/lists/*这是收益最大的一条通常能省几十 MB。apt-get clean只清/var/cache/apt/archives别只写一个就以为完事。Alpineapk add --no-cache参数本身就抑制了索引缓存比事后清理更干净。Pythonpip install --no-cache-dir不加这个参数下载的 wheel 会留在用户缓存目录里。Nodenpm ci --omitdev之外配合npm cache clean --force或者直接用多阶段构建把依赖单独装在一个阶段。Maven/Gradle把本地仓库目录指向可丢弃的位置或者干脆在多阶段构建里让构建层留在前一阶段。这里有个细节--no-install-recommends这个参数在 Debian 系上值得默认加上。很多推荐包比如某些字体、文档工具会被顺带装上体积往往比主包还大而运行时多数情况下用不到。3.3 缓存失效是从第一条不匹配的指令开始的构建缓存的工作机制是从上往下逐条比对每条指令的指纹包括指令文本本身以及它依赖的上一层的内容。一旦某条指令的指纹不匹配它和它之后的所有指令都会重新执行。这个机制的实践含义是把变化频率低的部分放前面变化频率高的放后面。一个典型的 Node 项目正确的顺序是先COPY package.json package-lock.json再RUN npm ci最后才COPY . .。这样改业务代码时依赖安装那层始终命中构建时间能从几分钟降到十几秒。反过来写每次改一行代码都要重装依赖团队会疯。有一次我改了一份 Dockerfile把COPY挪到了RUN前面自以为顺序更自然结果构建时间从 40 秒涨到 6 分钟CI 上的缓存命中率从 90% 掉到接近零。这类顺序问题不看构建日志里的 CACHED 标记根本发现不了我后来的习惯是构建完扫一眼输出确认该命中的层都标了 CACHED。4. COPY、ADD 与 .dockerignore最容易吃亏的地方4.1 构建上下文到底传了什么执行docker build时客户端会把指定的目录默认是当前目录打包发给构建器这个目录就是构建上下文。很多人以为只有被COPY引用的文件才会传实际上整个上下文都会被打包除非被.dockerignore排除。后果很直接仓库里有一个 800MB 的测试数据集、一堆.git历史、本地虚拟环境目录全都会被打进传输包。我在一次构建里观察过光是传输上下文就花了 50 秒而真正编译只花了 20 秒。更麻烦的是有些人把源码目录放在上级目录docker build .直接扫了一遍家目录那个体验相当酸爽。所以第一条硬性建议构建上下文目录尽量小、尽量干净。如果确实需要构建上下文之外的文件用docker build -f单独指定 Dockerfile 的路径而不是把上下文放大。4.2 ADD 与 COPY 的边界能用 COPY 就别用 ADDADD比COPY多了两个能力自动解压本地 tar 包、支持 URL 作为源。这两个能力听起来方便实际是坑从 URL 拉取文件不会走构建缓存且无法校验完整性上游内容变了你也感知不到自动解压行为对压缩格式有特定要求某些格式不解压也不报错容易造成文件是有的但内容不对对 tar 包解压后的权限、时间戳处理有隐式行为排查起来很费劲。我的经验是给团队定一条规则只要不是必须一律用COPY。需要下载文件就用RUN curl -fsSLO配合校验和需要解压就显式tar -xf。多写一行命令换来的是行为可预期。另外COPY本身就支持--chown和--chmod很多人不知道还在 COPY 之后补一条RUN chown白白多一层COPY --chownapp:app --chmod755 ./entrypoint.sh /app/entrypoint.sh4.3 一份可以直接抄的 .dockerignore 骨架.dockerignore的语法跟.gitignore类似但有两个区别要记住!开头的例外规则在忽略规则之后生效匹配是基于上下文根目录的相对路径。下面这份是我常用骨架按项目类型增删# 版本控制 .git .gitignore # 本地依赖与构建产物 node_modules dist build target __pycache__ *.pyc .venv venv # 编辑器与系统文件 .idea .vscode .DS_Store # 日志与临时文件 *.log tmp .cache # 敏感文件这一条最重要 .env .env.* *.pem *.key最后那类敏感文件必须排除。我见过不止一次镜像里躺着.env里面是数据库密码和第三方密钥镜像推到私有仓库后被下游多个环境拉走密钥的扩散面完全不可控。这种事一旦发生只能全量轮换密钥成本极高。5. CMD 和 ENTRYPOINT容器停不下来往往栽在这5.1 shell 形式与 exec 形式差的不只是一个方括号CMD和ENTRYPOINT都有两种写法shell 形式CMD npm start和 exec 形式CMD [npm,start]。很多人觉得两者等价其实差别巨大。shell 形式实际执行的是/bin/sh -c npm start真正的应用进程是 shell 的子进程。这带来两个后果一是 shell 成为容器的 1 号进程它会吞掉大部分信号docker stop发送的 SIGTERM 到不了应用只能等超时后 SIGKILL 强杀表现为停止容器要等十秒二是应用收不到优雅退出信号正在进行的事务、连接池、临时文件清理全都来不及做。exec 形式下应用直接是 1 号进程信号能收到优雅退出才成立。所以结论很直白除非确实需要 shell 展开变量或组合多条命令一律用 exec 形式。需要环境变量展开的场合可以套一层轻量入口脚本并在脚本里用exec $把 PID 1 交还给应用。ENTRYPOINT [/app/entrypoint.sh] CMD [node, server.js]entrypoint.sh里最后一行必须是exec $否则又回到子进程模式。5.2 两者的组合关系用一张表说清CMD和ENTRYPOINT同时存在时的行为经常被记混直接列表ENTRYPOINTCMD实际执行无CMD [a,b]a bENTRYPOINT [x]无xENTRYPOINT [x]CMD [a,b]x a bENTRYPOINT [x]CMD [a,b]运行时docker run img c dx c dCMD 被完全覆盖ENTRYPOINT [x,a]CMD [b]x a b核心记忆点CMD 提供默认参数运行时命令行参数会整体替换 CMD而 ENTRYPOINT 始终保留。所以做可配置的服务时把不变的启动器和固定参数写进 ENTRYPOINT把可变参数交给 CMD用法最顺手。还有一条容易踩的坑同一个 Dockerfile 里写多个CMD只有最后一个生效前面的会被静默丢弃构建时不报任何警告。这在我看过的存量脚本里出现过好几次属于典型的改了没生效但看不出来。5.3 1 号进程还要处理僵尸进程回收除了信号1 号进程还承担子进程回收的职责。普通应用没有实现这个逻辑长期运行后可能积累僵尸进程。有两种解法一是用docker run --init让一个极小的 init 进程接管这个参数不改 Dockerfile部署时加上就行二是在镜像里装一个轻量 init 并作为 ENTRYPOINT比如ENTRYPOINT [/sbin/tini, --, /app/entrypoint.sh]我的实践是短生命周期的批处理任务不折腾长期驻留的服务统一加--init。这样 Dockerfile 保持干净部署侧的编排文件里加一个参数就行。6. 多阶段构建把编译器留在上一站6.1 一个前后端项目的最小可复现三段式多阶段构建的核心思路是一份 Dockerfile 里可以出现多个FROM每个FROM开启一个新阶段阶段之间用COPY --from拷贝产物。只有最后一个阶段会成为最终镜像前面的阶段全部丢弃。以前端项目为例一个能直接用的三段式长这样# 阶段一装依赖单独拆出来最大化缓存命中 FROM node:18.19-bookworm AS deps WORKDIR /src COPY package.json package-lock.json ./ RUN npm ci --omitdev # 阶段二构建 FROM node:18.19-bookworm AS builder WORKDIR /src COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build # 阶段三运行时 FROM nginx:1.25-alpine AS runtime COPY --frombuilder /src/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80把依赖安装单独拆成一个deps阶段是因为构建工具和运行依赖可以并行准备也因为后续如果要做依赖审计可以单独针对这个阶段跑命令。有些团队会把它省掉直接两段式也没问题取决于构建时长。6.2 跨阶段拷贝的几个细节COPY --from的源写法有三种阶段名、镜像名、阶段索引。用阶段名最清晰改起来也方便。需要注意的是跨阶段只能拷贝文件系统里的内容不能拷环境变量。所以前一个阶段ENV设置的变量在后一个阶段读不到必须重新声明。这一点我在第一次用多阶段构建时踩过在 builder 阶段设了NODE_ENV运行时阶段发现它不存在。另外从外部镜像拷单个文件是很好用的技巧比如只需要某个工具的二进制的场景COPY --frombusybox:1.36 /bin/busybox /usr/local/bin/busybox但这种方式会让构建依赖一个你没在自己控制的基础镜像版本稳定性要自己盯住我不建议在核心业务镜像里滥用。6.3 用缓存挂载把反复下载这件事彻底解决多阶段构建解决了体积问题但没解决每次构建都要重新下载依赖的问题——只要package-lock.json变了npm ci就得从头跑。这时候可以用构建缓存的挂载能力把包管理器的缓存目录挂进来RUN --mounttypecache,target/root/.npm \ npm ci --omitdev这个写法的意思是这个目录的内容不进入镜像层但构建器会保留它下次构建时复用。效果是依赖没变时缓存直接命中依赖变了也只下载增量的部分。我实测过一个中型项目冷构建到热构建的时间差从 4 分多钟缩到 30 秒出头。需要注意缓存挂载依赖于较新的构建器旧版本环境可能不支持上生产前先在 CI 里验证一遍。另外缓存目录是共享的多项目并发构建时可能互相干扰给不同项目配不同的id参数就能隔离。7. 构建缓存突然失效的完整排查链路7.1 现象什么都没改构建却全量重跑有一次 CI 上的构建时间从 90 秒突然涨到 7 分钟代码没有任何相关改动。日志里npm ci那一层的 CACHED 标记消失了但COPY package.json package-lock.json那层还是 CACHED。这个组合本身就是一个强信号指令文本和输入文件都没变那问题一定出在层的指纹之外——基础镜像。7.2 逐层定位从 docker history 到 build 输出排查我一般按这个顺序走从粗到细看构建日志找到第一条没有标 CACHED 的指令。这是分界线它之前的一切都是命中的问题就在这条指令或其上的基础镜像。对已有镜像跑docker history --no-trunc image看每一层的大小和创建指令。如果发现某层体积异常大基本能定位到是哪条RUN的锅。用docker build --progressplain重新构建一次输出信息比默认的进度条详细得多能看到每一层的缓存比对细节。如果怀疑基础镜像变了用docker pull拉一次并比对 digestdocker inspect --format{{index .RepoDigests 0}}能直接看到当前 digest。那次排查的结果是基础镜像的 tag 被上游重新推了一次虽然 tag 名没变但 digest 变了导致它之后的所有层全部失效。这也印证了第 2 节说的tag 是会移动的。7.3 修复与验证把偶发变成可控修复分两步。短期是固定 digest让构建恢复稳定长期是调整流水线把基础镜像更新变成一个显式的、有计划的动作而不是被动接受。具体做法是在 CI 里加一个定时任务每周检查一次基础镜像是否有新版本有的话自动提一个变更申请走正常评审流程。这样更新是可控的出了问题的回滚路径也清晰。验证方式很简单连续两次构建确认第二次的绝大多数层都是 CACHED且整体耗时不高于预期阈值。我一般会在 CI 里加一条热构建耗时的检查超过阈值就报警能把缓存失效这类问题在第一时间抓出来。7.4 其他几种常见的缓存玄学及其归因除基础镜像外还有几类高频原因值得记下来现象常见原因处理方式只改了 README全部重跑COPY . .位置太靠前把依赖安装提到 COPY 源码之前依赖没变但安装层失效锁文件里有本地路径或时间戳变化检查锁文件生成方式固定生成环境同一份代码在两台机器上命中率不同上下文里有被忽略的差异文件统一.dockerignore用--progressplain对比构建参数变化导致全量重跑ARG参与到了依赖安装指令中只把必需参数放前面其余后置最后一行值得展开ARG的值参与缓存指纹计算。如果某个经常变动的构建参数比如版本号出现在靠前的指令里那它一变后面全废。解决方法要么是把参数的使用位置尽量后移要么干脆在构建脚本层做替换不进 Dockerfile。8. 生产可用的 Dockerfile 还差哪几块8.1 非 root 运行不是可选项容器默认以 root 运行这在很多团队里是默认状态但它带来的风险是实打实的一旦容器内有进程被利用攻击者拿到的就是 root 权限配合内核漏洞或挂载配置不当可以扩散到宿主机。所以只要是生产镜像创建专用用户并以它运行应该成为硬性规范。写法上要注意顺序先创建用户和目录、改好属主再切用户最后拷业务文件时带上--chownRUN groupadd -r app useradd -r -g app -d /app -s /sbin/nologin app WORKDIR /app COPY --chownapp:app ./dist /app USER app有个细节容易忽略USER之后的所有指令包括RUN都以该用户身份执行如果后面还有需要 root 的操作就会失败。所以USER要尽量放在靠后的位置。另外某些基础镜像预置了非 root 用户比如常见镜像里的node用户可以直接USER node省去自己创建。8.2 健康检查与启动顺序的配合HEALTHCHECK的作用是让编排系统知道容器内部是否真的可用而不只是进程还活着。写法上要注意超时和重试次数的配合HEALTHCHECK --interval30s --timeout3s --start-period40s --retries3 \ CMD wget -qO- http://127.0.0.1:8080/healthz || exit 1start-period这个参数很关键。应用启动需要时间如果健康检查从容器启动那一刻就开始判定会在应用还没起来时连续失败导致容器被反复重启形成启动风暴。设一个覆盖实际启动耗时的宽限期能避免这种问题。我给的经验值是start-period设成实测启动时间的 1.5 倍左右。另外健康检查的命令要足够轻。用curl检查/healthz是最常见的做法但精简镜像里往往没有curl只有wget甚至什么都没有。这时候可以写一个用应用自身语言实现的探测脚本或者干脆在编排层做健康检查把 Dockerfile 保持干净。8.3 时区、locale 与那几个上线才发现的小配置有几个配置在开发环境完全无感上了生产才暴露日志时间戳差 8 小时、中文文件名乱码、数字格式化不符合预期。它们都源于容器内默认的时区和 locale 设置。时区方面最省事的做法是装tzdata并设置TZ环境变量。但tzdata本身有十几 MB如果基础镜像支持更好的做法是直接从宿主或镜像里拷贝时区文件ENV TZAsia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime echo $TZ /etc/timezonelocale 方面如果应用需要处理中文或做字符串排序LANG和LC_ALL建议显式设置成C.UTF-8比生成一套完整的 locale 便宜得多。这个设置对 Python 的默认编码、Java 的字符集推断都有实际影响值得在项目模板里固定下来。8.4 镜像元数据为三个月后的自己留线索LABEL这条指令很少有人认真写但它在排查时价值很高。至少把源码版本、构建时间、对应仓库提交写进去LABEL org.opencontainers.image.revision${GIT_COMMIT} \ org.opencontainers.image.created${BUILD_TIME} \ org.opencontainers.image.sourcehttps://example.invalid/repo这些值通过--build-arg传入。有了它们线上容器出问题时docker inspect一下就知道这个镜像对应哪次提交不用再去翻 CI 记录对时间戳。我现在的习惯是把它做成组织级模板所有项目统一带这几个标签省去每次从零写。最后分享一个我在实际项目中养成的小习惯把 Dockerfile 当成代码一样做 review重点关注四件事——RUN有没有合并、COPY顺序对不对、有没有切非 root、基础镜像的 tag 是否固定。这四条过了剩下的细节可以慢慢优化。比起一次性写出一份完美的 Dockerfile我更相信把这几条变成团队约定长期看收益更大。