从这篇开始说明你已经不再满足于docker run拉个现成镜像跑一跑了。Dockerfile就是我们自己动手“配菜”的第一步——它是Docker构建镜像的脚本也是容器化部署里最绕不开的一份文件。这篇我按自己的理解把Dockerfile从指令到实践、从原理到踩坑一次性讲透。1. 先弄明白我们为什么需要Dockerfile很多初学者第一次接触Docker都是docker run -it ubuntu bash这样进去敲几条命令觉得挺方便。但日常开发里你不可能每次都手动进容器装环境。举个例子你花了一个下午在容器里装好了某个服务依赖配置好了环境变量测试一切正常。可一旦容器被删这些劳动成果全没了——容器本身就是临时性的它的文件系统变更不会被持久化保留。有人会想到docker commit把当前容器提交成一个新镜像。这确实是可行的当年我刚开始用Docker时也这么干过。但用一段时间你就会发现commit出来的镜像有几大问题没有任何构建过程记录别人拿到这个镜像完全不知道里面装了什么东西、怎么装的镜像体积会越来越大因为commit保存的是容器完整文件系统差异包括大量临时文件和缓存无法复现。你在容器里手动敲命令装环境换了个人在另一台机器上敲的顺序不一样、网络状况不一样最终镜像可能完全不同。Dockerfile的本质是把“如何构建一个镜像”变成一份可阅读、可版本管理、可重复执行的文本文件。镜像的分层文件系统就像是做千层蛋糕每一层指令都会生成一个只读层记录下来之后任何人拿着同一份Dockerfile在任何机器上构建得到的结果都是基本一致的。对我来说Dockerfile最值得称道的就是“可复现”和“可审查”。它像一个安装说明书写清楚每一步干什么别人拿到后能看懂、能复现能接着往下改。这比一个黑盒镜像靠谱得多。2. Dockerfile核心指令逐项拆解写Dockerfile说难也难说简单也简单。难的是有这么多指令每个的生效时机和行为都不一样组合在一起容易踩坑。我把最常用的几个指令拆开讲每个都附上我实际用过的写法。2.1 FROM一切镜像的地基FROM指定基础镜像必须是Dockerfile的第一条指令除了注释和ARG声明。FROM ubuntu:22.04这里有两个容易忽略的细节。第一基础镜像的tag要明确写。ubuntu:latest这种写法在本地没问题但放到持续集成环境里可能隔几天基础镜像更新了构建出来的结果就变了。我在生产环境一般固定到具体版本号甚至直接用镜像的digest值保证完全一致。第二基础镜像的选择直接影响构建体验。同样是Ubuntu官方的ubuntu:22.04是最小化的连curl都没有装东西得先apt-get update。而如果做Python应用直接选python:3.11-slim比从Ubuntu开始装Python省太多事。选基础镜像的原则是够用就好别为了省事选个巨大的完整版镜像。2.2 RUN构建时执行命令RUN是在构建镜像时执行的命令每一条RUN都会产生一个新层。它可以有两种写法# shell形式 RUN apt-get update apt-get install -y curl # exec形式 RUN [apt-get, update]我绝大多数时候用shell形式因为经常会用到串联、管道、变量展开等特性。exec形式更适合那些不想经过shell解析的固定参数命令。这里有个重要的“合并RUN”的实践可以显著减少镜像层数和体积# 不推荐每一条RUN是一层且中间层会保存临时状态 RUN apt-get update RUN apt-get install -y curl RUN rm -rf /var/lib/apt/lists/* # 推荐合并成一个RUN串联 RUN apt-get update \ apt-get install -y curl \ rm -rf /var/lib/apt/lists/*合并RUN不只是为了层数少更关键的是清掉apt缓存。apt-get update产生的lists文件有几十MB如果单独一个RUN这些文件会留在那一层里。合并写的时候最后一步把它删掉这一层最终不会包含这些没用的缓存。2.3 WORKDIR切换工作目录WORKDIR指定后续RUN、CMD、ENTRYPOINT、COPY的工作目录。它类似于cd但比cd更强——如果目录不存在它会自动创建。WORKDIR /app我习惯把WORKDIR放在早期紧接着基础镜像就切换后续所有操作都在这个目录下进行。有个我踩过的坑和RUN cd /app ...混用的问题。RUN cd只在当前RUN层生效下一层又回到WORKDIR或根目录了。用WORKDIR才能让目录变更持久生效。2.4 COPY与ADD把文件放进镜像COPY是把构建上下文里的文件复制到镜像里。COPY package.json /app/package.json COPY . /appADD比COPY多一点能力支持从URL拉取文件、自动解压本地压缩包。听起来很吸引人对吧我在项目里基本只用COPY原因有二ADD从URL拉文件会把下载和解压的逻辑混在镜像构建里构建时间不可控、网络失败还需要重试机制不如用RUN加curl命令更直观可控自动解压的行为是一把双刃剑如果你的确需要解压一个本地tar包它确实方便但如果你只是想复制一个压缩包进去再自己处理它可能带来预期之外的行为。具体场景可以参考这个建议普通文件复制一律用COPY确实需要解压本地tar包的用ADD需要下载远端文件的用RUN加curl。还有一个所有新手都会犯的方向性错误——上下文路径。docker build -t xxx .里的.是构建上下文Dockerfile里的COPY路径都是相对于这个上下文的而不是相对于Dockerfile文件所在位置的。比如Dockerfile在docker/目录构建命令在项目根目录执行写的是.那COPY就得写docker/xx如果构建命令在docker/目录里执行COPY直接写文件名就行。2.5 CMD与ENTRYPOINT容器启动时执行什么这两个指令最容易混淆面试也常问。我直接说结论CMD提供默认的执行命令或参数容器运行时如果没有额外指定命令就用CMDENTRYPOINT是容器启动时固定执行的入口程序不会被docker run后面的参数覆盖。它们的配合方式是这样ENTRYPOINT [python] CMD [app.py]运行时如果执行docker run myimage --help实际执行的是python --help——--help附加值会传给ENTRYPOINT。如果运行时执行docker run myimage app2.py实际执行的是python app2.py。CMD被替换了但ENTRYPOINT还是python。如果写错了比如把入口全写在CMD里CMD [python, app.py]运行时执行docker run myimage --help就会报错——因为Docker会把整个CMD换成--help它找不到--help这个程序。这就是CMD和ENTRYPOINT的核心区别所在。还有shell形式和exec形式的区别# shell形式实际是通过 /bin/sh -c 执行 CMD python app.py # exec形式直接执行不经过shell CMD [python, app.py]exec形式不会经过shell所以Docker不会解析$HOME这类环境变量。shell形式会。但shell形式有个问题程序的PID会变成/bin/sh的子进程而不是容器内PID 1这会导致容器接收不到SIGTERM信号优雅停机逻辑可能失效。生产环境我基本都用exec形式。2.6 ENV与ARG变量的两种生命周期ENV设置环境变量会写入镜像的环境变量表里容器运行时也保留。ARG只在构建期间有效不会出现在容器环境里。ARG VERSION1.0 ENV APP_VERSION$VERSION常见用法是用ARG传不同环境的版本号用ENV把ARG值固化到环境变量里。构建时可以用--build-arg VERSION2.0覆盖默认值。构建参数同样有安全和实践层面的注意点。千万不要把敏感信息数据库密码、API密钥通过ARG传进镜像——docker history可以查看到构建命令ARG值会暴露在那里。如果非要在构建期用到密钥用Docker提供的秘密挂载机制BuildKit构建完成后不落盘。3. 写好Dockerfile的工程化实践经验这一节的内容是我一次次构建镜像、一次次上生产环境踩坑后总结出来的。前面把指令讲明白了但把它们组合成一份合格的Dockerfile还需要一些工程上的章法。3.1 理解层缓存机制优化构建顺序Docker构建镜像有个缓存机制如果某条指令的基础层没变缓存就直接复用不需要重新执行。这个特性极大地影响我们的指令排序策略。我把一个典型的Node.js项目依赖安装写给你看FROM node:18-slim WORKDIR /app # 先只复制依赖清单文件 COPY package.json package-lock.json ./ # 再安装依赖 RUN npm ci # 最后复制源代码 COPY . .为什么要先复制package.json再安装依赖最后才复制源码因为源码会频繁变更而package.json相对稳定。如果一开始就把COPY . /app放在前面然后RUN安装依赖那么每次改一行代码整个依赖安装步骤都会被判定为缓存失效重复执行npm ci——一次好几分钟就没了。把依赖清单先复制进去只要依赖文件没变源码怎么改都不会触发依赖安装的重新执行。这个缓存策略对所有语言适用先把锁定文件复制进去装完依赖再COPY源码。还有一个衍生技巧用BuildKit特性--mounttypecache把包管理器缓存目录挂出来多轮构建之间可以复用# syntaxdocker/dockerfile:1 FROM node:18-slim WORKDIR /app COPY package.json package-lock.json ./ RUN --mounttypecache,target/root/.npm \ npm ci这样npm ci下载的包缓存不会随层销毁二次构建速度快非常多。3.2 用.dockerignore给构建上下文瘦身构建上下文越大发送给Docker守护进程的数据就越多构建越慢。默认情况下docker build .Docker会把当前目录整个打包发给守护进程。我见过有人把整个项目目录、node_modules、git目录、构建产物全打进去构建一次需要几十秒来传输数据。解决办法是写一份.dockerignorenode_modules .git .gitignore *.md dist build .dockerignore Dockerfile这里有个容易忽略的点.dockerignore里排除的文件不仅影响COPY指令也会减少上下文传输大小。把Dockerfile自身也排除掉可以避免文件内容变化引起不必要的缓存失效——实际上很多项目会刻意排除它。不过如果Dockerfile确实有路径引用了它那就不应该排除需要具体判断。3.3 多阶段构建让镜像瘦下来多阶段构建是我用过性价比最高的优化手段。它让Dockerfile里可以有多个FROM最后的镜像只继承最后一个阶段中间阶段的东西全被丢弃。举一个经典的Go应用例子# 阶段一构建Go二进制文件 FROM golang:1.21 AS builder WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED0 go build -o app . # 阶段二运行阶段 FROM alpine:3.19 RUN apk add --no-cache ca-certificates COPY --frombuilder /src/app /usr/local/bin/app ENTRYPOINT [app]Go官方镜像体积大约1GB级别而Alpine基础镜像只有5MB左右加上拷贝过来的二进制最终镜像只有几十MB。差距非常惊人。多阶段的核心思想每一个阶段都是可独立构建的上下文阶段之间可以用COPY --from阶段名传递产物。不仅Go能用Node.js、Java、Python全都能用。比如Java可以用一个阶段做Maven编译最终阶段用轻量运行时镜像。要写好多阶段构建有个原则是每个阶段保持职责单一第一阶段的镜像专注构建第二步专注于产物运行用到什么就拷什么。我见过有人在最终阶段还安装编译工具链那就白白浪费了多阶段设计的优势。3.4 最小权限与安全习惯镜像安全这块常被忽视等出问题再补救成本极高。我列几个基础做法# Node.js应用为例 FROM node:18-slim WORKDIR /app # 创建非root用户 RUN groupadd --system app useradd --system --gid app appuser COPY --chownappuser:appuser . /app # 切换用户 USER appuser ENTRYPOINT [node, app.js]容器内部默认是root用户而一旦容器被攻破root权限意味着这等于和宿主机root一样。创建非root用户至少有了一层隔离。COPY --chown是为了让复制的文件归这个用户所有否则普通用户没有权限读或执行。另一个安全习惯是给基础镜像打sha256指纹来保证不可变性FROM node:18-slimsha256:xxxx不过这种写法会让升级基础镜像变得麻烦我更推荐在团队里用“基础镜像版本统一管理”的方式来约束规范。细心的读者可能会问既然USER已经切换了为什么前面安装依赖还要用root这里需要理解Dockerfile中的指令执行顺序每个指令都可以指定不同的USER。可以在RUN前切换也可以在进入应用执行环节前切换。常规结构是前期用root安装必要的包后期切到非root用户执行入口。这是传统镜像的普遍习惯但如果你用BuildKit有更优雅的写法——用RUN --user控制细粒度权限。3.5 其他值得用的指令一些指令不常用但关键时刻能救命EXPOSE声明容器监听的端口纯粹是文档性质不会真正开放端口。VOLUME声明匿名卷挂载点如果运行时没指定卷Docker会自动创建一个匿名卷。它不适合在生产环境做数据管理因为匿名卷很难找回。HEALTHCHECK定义容器健康检查命令检查失败会被标记为unhealthy。很多编排平台会据此重启或下线容器。ONBUILD定义触发器当这个镜像被作为基础镜像使用时才执行。这个指令在一些基础镜像仓库里用得多但对业务团队来说用到的概率很低可以先不学。4. 完整实战从一个Node.js应用到可部署镜像怎么把这些指令组合到一起我拿一个最简单的Node.js项目从头构建一遍整个过程你可以照着操作。4.1 项目结构准备首先创建一个简单的应用目录结构如下my-app/ ├── package.json ├── package-lock.json ├── app.js └── Dockerfilepackage.json{ name: my-app, version: 1.0.0, main: app.js, scripts: { start: node app.js }, dependencies: { express: ^4.18.2 } }app.jsconst express require(express); const app express(); const port 3000; app.get(/, (req, res) { res.send(Hello from Docker); }); app.listen(port, () { console.log(App listening on port ${port}); });4.2 第一版DockerfileFROM node:18-slim WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . EXPOSE 3000 CMD [node, app.js]构建docker build -t my-app:v1 .运行docker run -d -p 3000:3000 my-app:v1打开http://localhost:3000就能看到页面内容。这一版是最基础的骨架能跑但还有一些优化空间。4.3 优化后的完整版本结合前面的经验我给出一个生产可用的版本FROM node:18-slim # 创建非root用户 RUN groupadd --system app useradd --system --gid app appuser WORKDIR /app # 依赖先装利用缓存 COPY package.json package-lock.json ./ RUN npm ci --onlyproduction \ npm cache clean --force # 改用户后复制源码 COPY --chownappuser:appuser . /app USER appuser EXPOSE 3000 CMD [node, app.js]和第一版对比多了三件事非root用户运行、npm cache清理、切换用户后再复制。这些改动都很小但确实能让镜像更健壮。如果要做多阶段构建可以把阶段拆开# 阶段一安装依赖并做编译如果需要 FROM node:18-slim AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . # 阶段二运行时 FROM node:18-slim RUN groupadd --system app useradd --system --gid app appuser WORKDIR /app COPY --frombuild --chownappuser:appuser /app/node_modules ./node_modules COPY --chownappuser:appuser app.js package.json ./ USER appuser EXPOSE 3000 CMD [node, app.js]这个版本把node_modules从构建阶段拷到运行阶段运行阶段没有多余文件干净且小。实际构建后可以对比一下两个镜像的体积差异通常能省出不少空间。4.4 构建时的细节检查如果构建过程中某个步骤特别慢先想想是不是缓存没命中。docker build默认输出里会显示每一层是CACHED还是重新执行。如果依赖装完以后源码COPY进去会覆盖依赖吗这取决于COPY的通配规则。把node_modules放在.dockerignore里防止本地node_modules覆盖镜像里的。npm ci要求必须有package-lock.json如果项目没有锁文件需要先npm install生成或者在Dockerfile里改用npm install。5. 高频报错与排查技巧实录写Dockerfile总会遇到一些奇奇怪怪的报错我把高频的问题和排查思路整理成一份速查表。5.1 常见报错速查表现象原因排查方向COPY failed: file not found路径不在构建上下文里确认构建上下文路径使用相对路径exec: xxx: executable file not found in $PATH可执行文件不存在或PATH问题确认二进制文件路径试试绝对路径standard_init_linux.go: exec user process caused no such file or directory二进制与运行镜像不兼容动态链接二进制需要带对应依赖的基础镜像检查是否为跨平台编译产物npm ERR! code ELIFECYCLE依赖安装失败查看完整日志可能是网络问题apt-get update fails基础镜像源不可达更换apt镜像源或换基础镜像docker: lstat ... no such file or directory.dockerignore误排除内容调整.dockerignore规则5.2 时会遇到的几个典型问题APK_INDEX之类的缓存问题、时区不对的问题、镜像内没有bash的问题——这些小问题看着不起眼但一旦遇到排查起来很花时间。第一个是时区问题。基础镜像默认UTC时间中国时区需要显示东八区RUN apt-get update \ DEBIAN_FRONTENDnoninteractive apt-get install -y tzdata \ ln -fs /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ dpkg-reconfigure -f noninteractive tzdata如果应用对时间敏感这条挺关键的。第二个是shell问题。Alpine默认用ash而不是bash很多bash特有语法source、数组都没法用。如果脚本依赖bash特性可以考虑直接用Debian系基础镜像。第三个是关于docker build的缓存问题。有时候你改了Dockerfile以为会重新构建但发现某些层还是CACHED。排查时可以用docker history 镜像查看分层明细看看每层实际执行了什么、大小如何。docker build --no-cache能强制全量重来但代价是慢优先还是调整指令顺序、利用好缓存。5.3 容器启动即退出的排查思路容器启动后立即退出先看日志机制。docker logs 容器名或ID日志里如果只有报错先排查应用本身。如果日志是空的可能程序本身没有输出也可能是启动就被杀掉了。常见原因是CMD写的不是前台进程。比如镜像启动后调用了一个后台执行脚本脚本退出后容器就停了。容器生命周期要绑定到前台进程上。ENTRYPOINT写错了程序路径报错后退出。依赖环境变量没配置程序初始化失败退出。排查时可以在启动命令临时覆盖入口docker run -it my-app /bin/bash这样能进入容器内部手动检查环境和依赖定位是环境问题、文件问题还是程序问题。6. 关于Dockerfile的几个常见误区最后聊几个我见过很多人踩进去的观念误区它们比具体的指令错误更值得警惕。误区一镜像内部什么都想装齐全。容器内不装调试工具、不装编辑器本来就是个临时运行环境。需要调试时可以用临时覆盖命令永久性地把工具塞进镜像只会增加攻击面、增大体积。误区二追求极致“小”失去可维护性。用distroless镜像确实能瘦到几MB但排查问题也难——里面没有shell可以进。建议按实际需求折中开发环境用完整镜像方便调试生产环境用slim版本控制体积。误区三写Dockerfile只是运维的事。开发人员自己写自己项目的Dockerfile才是最合理的方式。只有开发者最清楚自己代码需要什么样的运行环境、哪些依赖是必须的、哪些可以裁剪。误区四构建参数能随便传。之前提过ARG和ENV但过段时间重新回顾会发现还有通过环境变量给运行期传参的场景。这个不算误区只不过值得记住的是构建期、运行期是两套变量体系别混为一谈。我自己刚接触Docker时也把Dockerfile写得非常随意一条指令一行装一堆用不上的东西镜像体积2GB起步。后来在线上环境遇到一次因为基础镜像包含不必要组件引发的安全问题才下定决心按最佳实践重写。现在写Dockerfile的速度快了很多因为思路已经固定下来先定基础镜像再按依赖变化频率排指令顺序最后考虑权限和体积。熟能生巧这些都是靠一次次构建喂出来的经验。如果你想把这份文件用好多体会一下“每一层应该尽量小且职责单一”这个核心原则。Dockerfile不难但它绝对是容器化实践里最关键的一步。