你现在可能天天在用 Docker 跑服务但真到了要自己写一份 Dockerfile 的时候是不是还是有点不知从哪下手我看过很多讲 Dockerfile 的教程指令清单背得完心里对镜像构建过程却始终是一团模糊出了问题只能瞎改碰运气。这篇文章的核心就两件事Dockerfile 的文件结构怎么组织以及 docker build 构建镜像的整个过程到底发生了什么。适合刚接触容器的人快速建立框架也适合写过几个 Dockerfile 但总是踩缓存、体积、启动失败这些坑的人。要想把 Dockerfile 写得顺手最重要的不是背指令而是理解镜像本身是如何被构建出来的。指令只是操作手段层layer才是镜像的基本单位。只要把“分层”和“临时容器执行”这两个概念刻在脑子里后面所有关于缓存、体积、权限的问题都会变得清晰。1. 镜像构建的整体逻辑先弄懂 layer 再说指令1.1 镜像不是一个大文件而是一摞快照镜像在 Docker 里并不是一个巨大的单文件而是一组只读层叠放而成。每执行一次 RUN、COPY、ADD 这类会改变文件系统的指令docker build 都会在当前基础上新建一层把变更记录在这一层里。读取时这些层会按顺序合并给容器呈现出一个完整、统一的文件系统视图。这和 git 的提交记录很像。每一层就是一次“提交”保存的是和上一层的差异。假如你在某一个层里删除了某个文件下层的数据并不会被真正物理抹掉而是在上层写入一个特殊的标记让它在合并视图中“消失”。因此镜像也就有了不可变的特点从公共仓库拉取基础镜像再在它上面叠加自己的变更整个过程都可追溯。理解了这一层就能解释很多实际现象。比如你升级了基础镜像并重新构建新镜像本地磁盘上旧镜像可能还在因为它没有被任何人引用也不会自动消失只有 docker image prune 这类清理操作能回收。再比如容器和镜像的关系运行容器时Docker 会在所有只读层之上再挂一个可写层容器内任何写入都发生在这一层。容器一旦被删除这个可写层也随之消失。这也是容器不适合存业务数据的原因有状态数据应当交给数据卷或外部存储。1.2 docker build 到底干了什么docker build 的过程可以概括成四步读取构建上下文、解析 Dockerfile、在临时容器中逐条执行指令、把每步产生的文件系统差异提交成新层。先说构建上下文。你在项目目录里执行 docker build 时这个目录里的所有内容除了 .dockerignore 排除的部分都会被整体打包发送给 Docker 守护进程。上下文体积越大传输和解析的时间就越长。所以不要在有大目录、日志文件、依赖缓存的项目根目录下直接 build这就是后面为什么要精心设计 .dockerignore。接着是逐条执行。每条 RUN、COPY、ADD 指令触发时Docker 都会启动一个临时容器在容器里执行当前指令执行结束后容器退出Docker 把容器文件系统和上一层之间的差异保存成一个新层然后继续处理下一条指令。这意味着两条相邻的 RUN 指令并不是在同一台“可连续操作”的机器里执行而是各自独立的沙箱。你在前一条 RUN 里 export 一个环境变量后一条 RUN 里是读不到的同理前一条 RUN 里安装的软件包如果基础镜像层没变化后一条仍然能用到——因为安装结果已经作为新层保存下来了这也是镜像分层带来的复用能力。还有一类指令比较特殊CMD、ENTRYPOINT、EXPOSE、ENV 这些并不会创建新层它们只是往镜像的配置元数据里写入信息。所以你会在 docker history 里看到一些指令带有 missing 标记不是文件缺失而是它根本没有产生文件系统改动。2. 关键指令逐条拆解为什么这样写而不是那样写2.1 基础框架FROM WORKDIR COPY RUN大多数人写 Dockerfile 是从抄网上的模板开始的抄之前最好搞清楚最常用的四条指令各自在干什么。FROM 是整个构建的起点决定了镜像的操作系统环境和预置工具。选 FROM 有三条经验优先选官方镜像能用明确的版本标签就不用 latestlatest 会跟着上游变动三个月后重新构建很可能得到不同的结果这和“可复现”的目标背道而驰在乎体积时优先考虑 Alpine 或 slim 变体它们裁剪了大量不必要组件缺点是某些依赖需要额外编译。WORKDIR 是设置当前工作目录。很多人习惯写RUN cd /app ...但这样既啰嗦又容易在后续指令里路径混乱。直接写 WORKDIR /app后续的 RUN、COPY、CMD、ENTRYPOINT 都会默认在这个目录下执行路径一致可读性也更好。WORKDIR 不产生新层不会让镜像变大。COPY 的作用是把构建上下文里的文件复制进镜像。它的源路径是相对构建上下文的目标路径如果是相对路径则相对于 WORKDIR。最简单的用法就是COPY . .但这也最容易把不必要的东西一起装进去所以必须配合 .dockerignore 使用。RUN 在执行 shell 命令安装依赖、生成文件、设置权限都靠它。每一条 RUN 都会产生新层所以同类操作尽量合并到一条里。这里有一个非常容易踩的坑RUN 的缓存取决于命令字符串以及它依赖的上层内容命令完全没变但基础镜像更新了缓存也可能失效。后面我会专门讲缓存策略。一个最基础的 Node 服务 Dockerfile 长这样FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm install COPY . . EXPOSE 8080 CMD [node, server.js]这里的关键是先 COPY 依赖清单再执行 npm install最后才 COPY 业务代码。这样业务代码改了依赖安装层还能命中缓存构建速度会快很多。2.2 容易混淆的三对指令写 Dockerfile 时最容易纠结的三对指令我直接做成对照表来记。第一对是 COPY 和 ADD。COPY 只做复制ADD 在复制之外还支持从 URL 拉取文件、自动解压本地 tar 包。听起来更强大但 ADD 的行为不够直观你 ADD 一个本地 tar 包它会自动解压可有时候你只是想让文件原样进去还得想办法避开这个逻辑如果 ADD 源是 URL执行时需要联网拉到文件后又会直接把文件丢进镜像反而不如先用 RUN 下载再用 COPY 放进去容易控制。我的原则是能 COPY 就 COPY只有明确要解压 tar 时才考虑 ADD。第二对是 CMD 和 ENTRYPOINT。两个都不产生层但决定了容器启动时执行什么。简单来说CMD 提供默认参数和默认命令可以被 docker run 后面的命令覆盖ENTRYPOINT 固定启动命令默认情况下在 docker run 后面加的参数会追加给它。比如写ENTRYPOINT [nginx]、CMD [-g, daemon off;]容器启动时实际执行的就是nginx -g daemon off;。如果你希望容器能接收外部传入的参数优先用 CMD 写完整命令如果容器应该固定作为某个进程使用就把不可变部分放进 ENTRYPOINT把可变参数留给 CMD。还有一个小细节JSON 数组这种 exec 形式是直接启动进程字符串形式会包一层/bin/sh -c。要让进程能正确接收信号、不被额外 shell 干扰尽量用 exec 形式。第三对是 ARG 和 ENV。ARG 只在构建期有效用来接住docker build --build-arg传入的变量不会进入运行中的容器ENV 会写入镜像配置容器启动后进程里能直接读到。简单判断标准构建期需要、运行时不需要的东西用 ARG比如要替换的下载地址构建期和运行时都需要的东西用 ENV比如项目目录路径。千万不要在 ENV 里保存真正的密钥或口令任何能拿到镜像的人都能通过 docker inspect 看到。为了更好区分你可以记住这张表指令核心特点适合场景COPY只复制上下文文件绝大多数需要传文件进镜像的场景ADD复制 自动解压 URL 拉取明确要解压 tar 包时CMD默认命令可被覆盖容器启动命令需要灵活替换ENTRYPOINT固定命令默认不可覆盖容器固定作为守护进程使用ARG构建期变量不进容器构建参数、替换镜像内路径ENV写入镜像配置运行时可见应用运行环境变量、路径配置2.3 容易被忽视的 USER、EXPOSE 和 HEALTHCHECKEXPOSE 只是声明这个镜像里的进程打算监听某个端口。它不会真的映射端口也不会让进程自动监听。端口映射发生在docker run -p所以 EXPOSE 更偏向文档性质。多写几个声明没问题但不要写根本没用的端口否则会误导维护者。USER 用来切换运行用户。默认不写 USER容器里就以 root 身份运行。很多安全要求较高的环境不允许 root 跑容器所以好的习惯是在 Dockerfile 里创建一个普通用户并切换过去。Alpine 里可以用RUN addgroup -S app adduser -S app -G app然后写USER app。要注意切换用户之后之前 COPY 进来的文件属主可能还是 root如果应用需要写这些路径必须在切换用户前用 chown 改好属主。HEALTHCHECK 是给容器加健康检查指令。Docker 会按你配置的间隔在容器内执行一段命令判断进程是否存活。对于被服务编排系统管理的容器有 HEALTHCHECK 才能及时感知“进程还在但已经不能正常服务”的状态否则只能等外部探活失败。3. 从零构建一个可复现的应用镜像3.1 先设计 .dockerignore 再写 Dockerfile很多人的习惯是直接新建 Dockerfile写完才想起来是不是该忽略点什么。我更习惯反着来先设计 .dockerignore。构建上下文是 docker build 的输入集合。如果目录里有 node_modules、target、.git、日志文件这些都会被一股脑打包发送给 Docker 守护进程。最终不仅拖慢构建还有可能把本不该进镜像的配置文件一起 COPY 进去。一个相对通用的模板.git **/node_modules **/target *.log .env .idea .vscode这样写完之后再用COPY . .就不用担心把一堆垃圾复制进镜像了。注意 .dockerignore 本身会影响 COPY 层的缓存如果忽略了某个文件而这个文件之前被 COPY 使用过缓存也会失效。所以别随意改动忽略规则。3.2 一个能直接跑的 Dockerfile 长什么样还是用 Node 服务举例。假设项目里有 package.json 和 server.js目录结构大致如下myapp/ package.json server.js Dockerfile .dockerignoreDockerfile 内容FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm install COPY . . EXPOSE 8080 CMD [node, server.js]这条 Dockerfile 的逻辑顺序是刻意排过的先选基础镜像再设工作目录然后复制依赖清单、安装依赖最后复制业务代码。这样你改一次 server.js重新构建时 npm install 那一步可以直接用缓存构建时间会短很多。如果服务器上还没配置 registry mirror第一次拉取 node:20-alpine 可能等得久这属于环境问题后面单独说。如果项目里没有 package-lock.jsonCOPY package*.json ./这种通配符写法也可以正常工作它会匹配到能匹配到的文件。有锁文件时建议把 package-lock.json 也复制进去这样 npm install 会严格按锁定版本安装构建结果更可复现。3.3 构建命令、缓存行为与镜像检查镜像构建命令本身很简单复杂度大多集中在参数和调试上。最基本的构建docker build -t myapp:v1 .最后的点不能漏它表示构建上下文是当前目录。-t给镜像打标签可以理解为给镜像起一个可读的名字加版本。常用参数还有docker build --no-cache -t myapp:v1 . docker build --build-arg VERSION2.0 -t myapp:v2 . docker build --pull -t myapp:v1 .--no-cache会忽略所有已有层缓存完整执行一遍所有指令适合排查“是不是缓存了旧结果”的问题代价是构建时间明显变长。--build-arg用来给 Dockerfile 里的 ARG 传值。--pull会强制重新拉取基础镜像的最新版本适合你明确知道基础镜像有更新的时候用。构建过程中你会在输出里看到[2/5]、[3/5]这样的进度标记后面跟着指令内容。如果某个步骤后方出现 CACHED说明这一层没有重新执行直接复用了历史缓存。构建结束后可以这样检查镜像docker images myapp docker history myapp:v1 --no-truncdocker history 会列出镜像每一层对应的指令。镜像体积大得诡异时这个方法能直接定位是哪一条指令把大文件带进去了。3.4 启动容器别只盯着 docker run镜像构建出来是为了跑容器的。不少人 build 成功后就大意了结果容器启动几秒就退出然后反复 restart。先看一条常见的启动命令docker run -d -p 8080:8080 --name myapp myapp:v1-d 表示后台运行-p 做端口映射--name 给容器起名。容器起来后第一时间做两件事看日志、进容器。docker logs myapp docker exec -it myapp sh容器启动后立刻退出时docker logs 会把你需要的信息直接打出来。绝大多数“启动失败”其实是进程自己报错退出比如端口被容器内其他进程占用、启动脚本找不到文件、环境变量缺失这些都能在日志里看到。不要反复 docker restart 瞎猜。如果需要往容器里拷文件调试可以用docker cp但这个操作会改变容器可写层并不适合作为常规部署手段只是临时排查时方便。4. 构建效率与镜像体积两件最实在的事4.1 依赖层的缓存策略缓存重用可以这样理解docker build 解析到一条指令时会拿当前指令和它依赖的上层内容与历史构建记录中的层做比对。如果完全一致就直接复用旧层不再执行命令。这带来一个非常实用的结论Dockerfile 里的“易变内容”要尽量往后放。依赖清单文件requirements.txt、package-lock.json、go.mod通常很少变动应该先 COPY 进去然后执行依赖安装业务代码经常变应该放在后面。这样一来代码每次修改只会让后面的 COPY、RUN 层重建依赖层全部走缓存。反过来如果一开始就写COPY . .那么任何业务代码改动都会导致依赖安装层也失去缓存每次构建都要重新装一遍依赖。在大型项目里这种写法可以让构建时间从十几分钟锐减到一两分钟体感差距非常大。还有一个小技巧尽量不要在一条 RUN 里既安装依赖又复制代码。如果你把npm install和COPY . .写在同一条 RUN 里本质上是在抹掉 Docker 区分依赖变更和代码变更的能力。因为两个内容只要有一个变了整条 RUN 都会失效。4.2 多阶段构建把编译环境和运行环境分开镜像体积是另一个老大难问题。尤其是编译型语言如果你在一个 Dockerfile 里完成全部编译那最终镜像里会保留整套编译器、头文件、中间缓存体积轻松超过 1GB。多阶段构建的核心思想是一个 Dockerfile 里可以出现多个 FROM最终镜像只保留最后一个阶段的内容。上一个阶段里生成的东西可以用COPY --from阶段名复制过来。举个例子Go 服务的经典写法# 第一阶段编译 FROM golang:1.22-alpine AS builder WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED0 go build -o /out/app . # 第二阶段运行 FROM alpine:3.20 RUN apk add --no-cache ca-certificates WORKDIR /app COPY --frombuilder /out/app /app/app EXPOSE 8080 ENTRYPOINT [/app/app]如果项目没有 go.sum把COPY go.mod go.sum ./改成COPY go.mod ./即可。第一阶段用完整的 Go 工具链编译出静态二进制第二阶段只用一个精简的 Alpine 镜像把二进制复制进去。最终镜像里没有编译器没有源码没有中间产物。解释型语言同样可以多阶段。比如在完整 Node 镜像里完成依赖安装之后在一个精简 Node 镜像里只复制 node_modules 和业务代码也能省掉很多开发依赖和工具。多阶段构建还有一个用途当你只需要调试“构建到某一步的产物”时可以用--target参数指定只构建到某个阶段。比如docker build --target builder -t debug-builder .拿到中间镜像进去排查非常方便。4.3 用 registry mirror 解决基础镜像拉取慢的问题很多人在构建时卡住问题根本不在 Dockerfile而是基础镜像拉不下来。FROM node:20-alpine这一行需要先从公共镜像仓库拉取基础镜像。如果你所在的网络环境访问 Docker Hub 速度不理想构建一开始就会很煎熬。对这个情况最直接的解法是给 Docker 配置 registry mirror也就是镜像缓存服务。它的作用可以这样理解你仍然写FROM node:20-alpine但 Docker 在拉取公共镜像时会先去你配置的镜像缓存服务找有没有这个镜像的缓存副本有就直接用没有再去公共仓库拿一份并缓存。配置方式是在 Docker 守护进程的配置里增加 registry-mirrors 列表。一个参考格式{ registry-mirrors: [https://mirror.example.com] }把https://mirror.example.com替换成你可用的镜像缓存服务地址。不同环境的具体配置方法会有差异有些是在系统配置文件里有些是在图形化界面的设置项里。改完重启 Docker 服务重新执行 docker build基础镜像拉取速度往往会有明显提升。需要注意这个配置只作用于从公共仓库拉取的镜像不会影响你自己构建的镜像也不影响直连私有仓库的拉取。5. 实战中常见的坑现象、原因和对策5.1 构建失败先定位指令再看环境构建失败绝大多数集中在 RUN 指令。原因很简单RUN 执行的是 shell 命令任何一个环节出错都会让整条指令失败比如包名拼错、网络超时、脚本用到了镜像里不存在的命令。调试顺序我建议是先看报错输出中的ERROR或failed字段定位是哪一条 RUN再在本地或临时容器里单独执行同样的命令确认命令本身能不能通过。如果确认命令没问题但容器里缺工具就在这条 RUN 里先装上再用如果是网络超时给安装命令加超时和重试选项或者换基础镜像变体。还有一点容易被忽略如果之前构建成功过现在突然失败很可能是缓存命中了旧的不完整结果不妨用docker build --no-cache完整重跑一遍排除缓存干扰。5.2 镜像体积异常用 docker history 查层“我明明只加了一行代码镜像怎么变得这么大”是出现频率极高的疑问。答案基本都藏在层里。用docker history 镜像名 --no-trunc逐层看特别留意有没有哪一层突然多出一个大块头。最常见的体积杀手有三个COPY . . 时把无用文件复制进镜像、RUN 安装软件后没有清理包管理器缓存、编译产物和过程文件残留在最终镜像里。对策分别是写 .dockerignore、在同一条 RUN 里完成安装和清理、把编译过程挪到多阶段构建的前置阶段。以 Alpine 为例apk add不加--no-cache包索引和下载缓存会留在镜像里积少成多也很可观。Debian 系则要记得apt-get clean并清理/var/lib/apt/lists/。5.3 时区、权限和基础镜像带来的“玄学”很多官方镜像默认使用 UTC 时区容器日志时间和你的本地时间差 8 小时这不是 bug是镜像没设置时区。要么在 Dockerfile 里安装时区数据并生成对应时区链接要么通过运行时环境变量来配置。精简镜像通常不带时区数据库所以不要在精简镜像里指望它默认就有正确时区。权限问题则更容易让人抓狂。容器里用非 root 用户运行时注意之前 COPY 进来的文件属主。USER app切换用户后如果应用需要写某个目录而这个目录属主是 root运行时会直接报权限错误。解决方式是在切换用户之前显式执行RUN chown -R app:app /app。还有一种情况是宿主机挂载数据卷后容器内用户 uid 和宿主机用户 uid 不一致导致读写权限错乱这类问题通常需要显式指定一致的 uid/gid 来解决。5.4 常见问题速查表现象可能原因处理办法COPY 提示找不到文件源路径不是相对于构建上下文或 .dockerignore 把文件排除了检查执行 build 的目录和 COPY 源路径RUN 报 command not found基础镜像里没有这个命令精简镜像更常见在同一条 RUN 里先安装对应工具包容器启动后立即退出启动命令本身报错、端口冲突、文件缺失先看 docker logs 的输出镜像体积异常大无用文件被 COPY、包缓存未清理、编译产物残留用 docker history 定位异常层配合多阶段构建依赖安装缓存不生效COPY . . 放太早业务代码改动导致依赖层失效调整指令顺序先把依赖清单复制进去再装依赖日志时间差 8 小时镜像默认 UTC 时区安装时区数据并设置 /etc/localtime或运行时配置时区容器内写文件权限不足非 root 用户没有对应目录写权限COPY 后执行 chown 修改属主FROM 基础镜像拉取极慢网络环境访问公共仓库受限配置 registry mirror 加速拉取我自己的一个小习惯是每次写 Dockerfile 之前先在脑子里按“基础镜像 → 系统依赖 → 代码依赖 → 业务代码 → 运行配置”的顺序排一遍预估每一步会产生哪一层、哪些层会被频繁改动。只要这个预估能成立缓存、体积、权限问题基本都能提前规避。最后再啰嗦一句把基础镜像的版本号固定下来把 .dockerignore 和 Dockerfile 放在一起随项目保存半年后再回来重建你会发现“可复现”这件事靠的就是这些不起眼的习惯。