1. 把Dockerfile当成镜像的“配方”之前先理解一条核心规则一行指令 一层镜像很多朋友第一次写Dockerfile最容易产生的误解是这玩意儿就是一份“安装脚本”无非是从上到下把命令跑一遍。真正上手之后你会发现把两条指令换个位置构建时间能差好几倍把ADD改成COPY容器启动后的行为又完全是另一个样。所以在写下第一个FROM之前先搞清楚镜像的底层构建机制比背指令重要得多。Dockerfile本质上是一个纯文本文件每一行都是一条指令Docker引擎按顺序执行这些指令并在执行过程中逐步构建出镜像。这里的关键概念叫“镜像层”image layer。每执行一条指令都会产生一个新的只读层新层会叠在旧层上面。你可以把这些层想象成一摞玻璃纸每一层只记录自己相对于上一层的文件差异某个文件被新增了、某个目录被删掉了、某个环境变量被改动了。最终你在容器里看到的完整文件系统是所有这些层叠加之后的结果。这里要特别强调一点层记录的是“差异”不是“完整快照”。这个点直接决定了你对镜像体积和构建缓存的所有判断。举个例子一个基础镜像Ubuntu占了大概30MB你执行一条RUN指令装了一百多MB的开源库再执行一条COPY把项目代码复制进去。第二层和第三层都只是记录了相对上一层的改动。后续如果有一条RUN把某个大文件删掉镜像体积并不会变小因为那个文件依然躺在第二层里删除操作只是在上面盖了一张“标记纸”。这就是为什么我们在写Dockerfile时要尽量避免“装了再卸”的操作也解释了为什么清理apt缓存、删除临时文件必须和安装命令放在同一条RUN里执行否则清理根本没有意义。理解了“一层镜像对应一条指令”之后再看Dockerfile就非常直观了它不是普通的命令清单而是在定义一棵文件系统的演化树。Docker在构建时会逐层计算哈希如果某一层和上次构建的结果完全一致就直接复用之前的结果这就是所谓的构建缓存Build Cache。看似简单的机制实际上决定了你应该怎样排列指令、怎样组织文件复制、怎样选择基础镜像这些我都会在后面的章节展开。先把地基打牢你写的每一行Dockerfile不是在描述“步骤顺序”而是在层层叠加地定义目标文件系统。顺带说一句很多教程喜欢把Dockerfile比作“做菜的菜谱”。我承认这个比喻有感染力但它只说对了一半。菜谱确实能指导复现但Dockerfile更强的在于它把复现过程固化成可校验、可回滚、可审计的中间产物。任何人拿同一份Dockerfile在相同的构建条件下执行得到的镜像在功能上应当一致。这一点在团队协作和线上环境里价值巨大——环境差异不再是玄学问题而是一个可以反复验证的对象。我建议所有入门者做的第一件事找一个小项目亲手跑通最基础的指令然后打开终端盯着构建输出看几次再用docker history翻一翻镜像是怎么一层层长出来的。纸上谈兵对写Dockerfile没有帮助但“亲手看一次构建过程”绝对有奇效。2. 一个最小可复用的实例从Flask应用到第一个自建镜像2.1 先准备一个能在本地跑起来的应用为了不让例子流于形式我选一个Python Flask小应用。为什么选Flask因为它的依赖简单、启动命令直白、网上资料多适合用它来验证Dockerfile的每一条指令。项目结构如下my-flask-app/ ├── app.py └── requirements.txtapp.py内容from flask import Flask app Flask(__name__) app.route(/) def hello(): return Hello, Docker!requirements.txt内容flask3.0.0这个应用在本地跑起来后访问http://localhost:5000会显示一行文本。你可以在自己的机器上先用pip install flask或创建虚拟环境跑通它确保基础功能正常。这一步很重要因为写Dockerfile时你要知道“程序本身是好的”否则后面出问题很难判断到底是代码问题还是镜像问题。2.2 逐行写出第一版Dockerfile并说清楚每行的意图在项目根目录下新建一个名为Dockerfile的文件注意这个文件名是约定俗成的Docker默认就会去找它不需要额外配置。FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY app.py . EXPOSE 5000 CMD [python, app.py]我们来逐行解析FROM python:3.11-slim指定基础镜像。它是构建的第一层也是整座大楼的地基。选择了官方Python 3.11的slim变体体积比完整版小很多但比Alpine更“正常”不容易遇到编译依赖缺失的问题。WORKDIR /app设置工作目录。这行的意思是后续所有RUN、CMD、COPY等指令都会默认在这个目录下执行。如果目录不存在Docker会自动创建。它能避免一堆路径拼接的麻烦比如你不需要每一条指令都写cd /app。COPY requirements.txt .把依赖清单复制到镜像的/app目录下。这里先复制依赖清单而不是把整个项目复制进去是为了利用构建缓存。后面的第4节会详细解释。RUN pip install --no-cache-dir -r requirements.txt在镜像中安装Python依赖。--no-cache-dir不让pip保留缓存文件避免无谓地撑大镜像。COPY app.py .把应用源码复制进镜像。现在依赖已经装好再把代码放进去这样以后改代码时依赖层可以继续走缓存。EXPOSE 5000声明容器对外提供服务的端口是5000。它本身不发布端口只起到“告诉别人这个镜像默认监听哪个端口”的作用更像一份文档。CMD [python, app.py]指定容器启动后要运行的默认命令。使用JSON数组形式写表示不会经过Shell执行这是官方推荐的做法。2.3 构建、启动、验证三条命令打开新世界一切准备就绪后在项目根目录执行下列命令docker build -t my-flask-app .注意最后的.不能丢它表示构建上下文build context是当前目录。Docker会把这个目录下的所有文件打包发送给Docker守护进程供构建过程使用。构建完成后你可以用一条命令将其启动docker run -p 5000:5000 my-flask-app-p 5000:5000的作用是把容器内的5000端口映射到宿主机上的5000端口。然后打开浏览器访问http://localhost:5000如果看到Hello, Docker!恭喜你第一个自建镜像已经跑通了。如果想在后台运行把-p前面的启动命令改成docker run -d -p 5000:5000 --name my-flask-app my-flask-app查看日志用docker logs -f my-flask-app很多人第一次会漏掉-p结果容器起来了但宿主机根本访问不到。这不是Dockerfile的问题是你还没理解容器端口和宿主机端口是隔离的。EXPOSE只做声明-p才是真正的“接线”。理解这点后以后调试网络问题会省力很多。2.4 用 docker history 看镜像分层的真实面貌构建完成后建议立刻执行docker history my-flask-app你会看到类似这样的输出IMAGE CREATED CREATED BY SIZE a1b2c3d4e5f6 1 minute ago CMD [python app.py] 0B ab12cd34ef56 1 minute ago EXPOSE 5000 0B ...每一行对应的正是你书写的每一条Dockerfile指令。通过docker history你能直观看到层数是按你写的指令数量生成的有些指令不产生文件变化如EXPOSE、CMD所以SIZE为0只有真正改动文件系统的指令如COPY、RUN才会产生体积。这一步做完前面“一行指令 一层镜像”就不再是抽象概念而是亲眼可证的事实了。3. 核心指令逐个拆解每条指令都有它存在的理由3.1 FROM基础镜像不是越大越好FROM是Dockerfile的第一条有效指令它定义了构建的起点。你可以选择几乎任何镜像仓库里的镜像但选择本身是有讲究的。常见的Python官方镜像变体有python:3.11、python:3.11-slim、python:3.11-alpine。完整版体积大里带有很多编译工具和开发头文件slim版本精简了大部分非必需组件alpine基于musl libc体积最小但有些依赖需要编译翻车概率也更高。我的建议很简单优先考虑官方镜像优先使用slim变体等真正遇到体积瓶颈或者安全扫描要求再考虑alpine。为了省几十兆体积去踩一堆编译兼容性的坑很划不来。还有一个基础镜像的隐性风险有些镜像的tag是可变的。比如python:3.11会持续更新而python:3.11.7是固定的。如果你追求可复现构建建议锁定到具体的小版本或者至少锁定到次要版本避免某天基础镜像更新依赖编译行为变化导致镜像构建出一个“昨天还能跑今天就起不来”的情况。3.2 COPY和ADD复制文件也是一门学问COPY的作用是把构建上下文里的文件或目录复制到镜像文件系统中它是Dockerfile里最常用的指令之一。基本语法是COPY 源路径 目标路径源路径是相对于构建上下文的目标路径是相对于WORKDIR的绝对路径。ADD在功能上是COPY的超集它额外支持远程URL下载并且当源文件是本地tar压缩包时会自动解压。听起来很方便但这恰恰是最大的坑。假如你想把一个名为package.tar.gz的文件复制到镜像里而不是解压它你无法用ADD完成这个操作因为它会按自己的规则自动解开。建议新手一律用COPY等真正需要解压逻辑时再明确使用ADD。这背后有一个更普适的原则单一职责。COPY只做文件复制逻辑简单、行为可预期ADD融合了“下载”和“解压”多个行为使用它在节省编写时间的同时也把不确定性引入了构建过程。对于构建自动化来说不确定性是敌人。3.3 RUN凡是容器里要安装的东西都在这一条命令里处理RUN是你执行安装操作的主力指令。几乎所有的apt-get install、pip install、npm install都写在RUN里。但这里面的执行方式有一个重要细节——命令行的写法。很多初学者会写FROM ubuntu:22.04 RUN apt-get update RUN apt-get install -y python3 RUN rm -rf /var/lib/apt/lists/*这个写法在语法上没错但在实践中有两个问题它生成了三个层其中apt-get update和apt-get install产生的apt缓存数据被保留在了第一层和第二层。如果你只改了第三层清理缓存的命令前两层依然会被缓存但这跟前两层无关。实际上由于前两层是“变化不频繁”的反而缓存命中率很高——可问题在于它们留下的缓存文件会永远占据镜像体积。更合理的写法是FROM ubuntu:22.04 RUN apt-get update \ apt-get install -y python3 \ rm -rf /var/lib/apt/lists/*用把update、install、clean三个步骤串在同一条RUN中它们会被包含在同一层里。这样产生的镜像层既包含安装结果也不包含apt缓存垃圾。更关键的是如果以后你需要调整安装的软件包名单只需修改这一条RUN整层缓存失效后重建不会留下一堆没用的中间层。3.4 ENV与ARG构建参数和运行参数千万别混用简单说ENV设置的是容器内始终存在的环境变量它在构建阶段和运行阶段都有效会被写入镜像配置。ARG只是一个构建期参数仅存在于构建过程中镜像运行起来后它就不存在了。举个例子ARG APP_ENVdevelopment ENV APP_ENV$APP_ENV通过docker build --build-arg APP_ENVproduction -t my-app .传入构建参数然后把它固化到ENV里让最终运行的容器环境变量是production。如果你直接写ENV APP_ENVproduction也不是不行但这样你就没法在不改Dockerfile的前提下切换环境了。实际操作中我见过太多人在容器里硬编码数据库地址、密钥等环境变量。千万不要这样做。环境变量在Dockerfile里是“配置的入口”真正的值应该通过-e参数或者docker compose的environment字段注入。Dockerfile可以定义默认值但不应该成为敏感信息的存放地。3.5 CMD与ENTRYPOINT一个管“默认”一个管“固定”这是最容易混淆的一对指令我就用一句话讲清楚区别CMD是“默认启动命令”ENTRYPOINT是“固定入口程序”。如果你在Dockerfile里只写CMD那么使用者可以在docker run时附加参数来覆盖它。比如CMD [python, app.py]那么执行docker run my-flask-app --help时Docker会把--help追加到命令后面相当于实际执行python app.py --help。如果你用ENTRYPOINT指定了入口比如ENTRYPOINT [python, app.py]那么后面再传的--help会变成它的参数执行docker run my-flask-app --help就相当于执行python app.py --help两者在表面上看着相似但语义不同——ENTRYPOINT是“程序的主要入口”CMD是“额外的默认参数”。两者经常搭配使用最经典的组合是ENTRYPOINT [python] CMD [app.py]这样使用者就可以通过docker run my-flask-app other.py切换到别的Python脚本而Python解释器本身始终不会变。对可执行程序类镜像来说这种设计非常常见。为了更清晰地对比我整理了一张表指令组合运行docker run [镜像] --help的效果适用场景只有CMD执行默认命令并附加--help普通服务、可改入口的应用只有ENTRYPOINT执行固定入口并附加参数固定解释器、封装的工具ENTRYPOINT CMD入口固定CMD作为默认参数想保留灵活性又锁住主程序的镜像3.6 EXPOSE、USER、VOLUME、HEALTHCHECK那些看着不起眼但迟早要用的指令EXPOSE上面讲过了是声明端口用的。它不影响实际网络映射但会给使用镜像的人提供重要信息比如别人拿到你的镜像看EXPOSE就能知道服务默认监听哪个端口。USER用于切换运行身份。默认情况下容器以root运行这在本地开发时无感但一旦涉及到生产环境、容器逃逸风险、权限粒度授权root身份都是隐患。最佳实践是创建一个普通用户并用它启动进程RUN useradd -m appuser USER appuser这样容器内进程以非特权身份运行降低被攻破后的影响面。VOLUME用来声明挂载点。它不会真的创建匿名卷主要是写给使用镜像的人看“这些目录需要挂载数据卷否则数据无法持久化。”比如数据库镜像会声明VOLUME [/var/lib/postgresql/data]。HEALTHCHECK是镜像层面的探活指令。它允许你定义容器如何被判定存活比如HEALTHCHECK --interval30s --timeout3s --retries3 \ CMD curl -f http://localhost:5000/ || exit 1这样编排平台就能依赖健康状态自动做重启等操作。在本地写镜像时你大可以忽略但如果你想做一个能上线、能被编排系统管理的镜像HEALTHCHECK是不可或缺的。4. 为什么指令顺序会影响构建速度缓存、分层和.dockerignore4.1 构建缓存是如何命中和失效的Docker构建缓存的核心逻辑是逐层哈希。当Docker开始构建一条指令时它会检查当前的基础层是否和上一次构建一致如果一致它还会比较要执行的指令内容以及构建上下文里涉及的文件内容。只有当前一层不变、指令不变、相关文件不变它才会直接复用缓存层。这就是为什么COPY requirements.txt .在逻辑上会“碰”到文件本身的内容。如果你把依赖清单放在代码复制那一行之后才复制那么每次代码有改动即使依赖清单没变Docker也会因为无法判断新增的代码是否影响依赖安装而让后续层失效。反之先复制依赖清单安装依赖再复制代码只要依赖清单不变依赖层就能复用缓存构建速度会快非常多。4.2 经验法则把不变的内容放前面把频繁变化的内容放后面这个经验法则几乎适用于所有Dockerfile。稳定的、不怎么动的、体积大的内容放前面你的源码、配置文件这种经常变的内容放后面。这么做带来的收益在修改源代码后立刻就能体现——你改了一行代码依赖层不用重装只需重新复制源码层耗时从几分钟变成几秒。举一个反例有人把COPY . .放在最前面然后才RUN install。这等于把整个项目的文件变化都丢给了缓存判定。结果是改一行代码后续所有安装步骤全部重来。这通常发生在不熟悉缓存机制的人身上也是构建时间长的主要原因之一。4.3 .dockerignore避免把不相干的东西烤进镜像.dockerignore之于Dockerfile相当于.gitignore之于Git。它的作用是定义构建上下文的排除规则。每次构建时Docker会把当前目录的文件打包发送给守护进程如果你的项目里有node_modules、__pycache__、.git、dist这些大目录它们都会被无差别发送即使你的Dockerfile完全不复制它们。这不仅让构建上下文体积膨胀得厉害在某些场景下还会导致缓存判断异常。一个典型的.dockerignore文件.git node_modules __pycache__ *.pyc .DS_Store dist build .env编写它的原则很简单凡是Dockerfile里不需要的都尽量排除。这既是为了构建速度也是为了避免把你本地的临时文件、密钥文件等意外带进镜像。4.4 不是层越少越好而是“该拆的拆该合的合”有一种误解是“镜像层越少越高级”。因此有些人会把所有RUN全部串成一个巨型RUN。这样做的确能减少层数但代价是可读性变差、缓存粒度过大。比如你把安装操作系统依赖、安装Python依赖、安装项目依赖全部写进一条RUN以后只要改其中一个另外两个也要跟着重新执行。我的建议是按“依赖阶段”拆分而不是死抠层数。比如系统级依赖放一条RUN语言级依赖放一条RUN源码复制单独一条。这样既照顾了缓存命中率也保持了可读性。镜像层数本身不是性能问题关键是要在缓存、体积、可读性之间找到一个适合你项目的平衡点。5. 调试和发布时踩过的坑我帮你提前标记出来5.1 ADD的解压行为好用但容易失控前面提过ADD会自动解压本地tar。这个特性在某些场景下是褒义的比如你要解压一个离线安装包一条ADD就搞定ADD jdk-17.tar.gz /opt/但如果你只是想复制一个.tar.gz文件到镜像里等运行时再处理ADD就会给你带来完全无法理解的“行为偏差”——它会提前解压最终产出的目录结构和你的预期完全不一样。以我个人的经验生产环境里的新坑大多是ADD引起的。所以除非明确要做解压否则一律用COPY。5.2 容器的时区是UTC这个坑能坑你一整天容器默认时区一般是UTC而国内服务的日志和业务通常需要北京时间。如果你没有设置时区很可能会在排查日志时间时发现怎么都对不上差了8小时。解决方案很简单ENV TZAsia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime echo $TZ /etc/timezone注意时区文件的路径需要基础镜像里有tzdata包有些精简镜像没有需要先安装。这是一个典型的环境差异问题不写Dockerfile的人根本不会意识到。5.3 用非root用户启动进程安全上线前必做的事默认情况下容器内进程以root身份运行。这在一台隔离的本地开发机上可能没什么问题但在生产环境里容器一旦被突破攻击者就拿到了宿主机的root权限当然这取决于容器配置、内核版本等但风险真实存在。自动化审计和安全管理工具通常也会对“容器以root运行”发出警告。我的建议是在Dockerfile里显式创建用户并用USER指令切换。比如FROM python:3.11-slim RUN groupadd -r appuser useradd -r -g appuser appuser WORKDIR /app COPY --chownappuser:appuser . . USER appuser CMD [python, app.py]这里还用到了--chown参数把复制文件的所有者切换为普通用户。否则即使你USER改成appuser文件还是root所有应用可能没有写权限。5.4 缓存的另一面什么时候必须 --no-cache 强制重建构建缓存会减少构建时间但它也会在某些场景下变成陷阱。比如你的Dockerfile里有一条RUN从网上拉取最新版本的工具包因为指令内容从来没变过Docker会复用它之前构建时的层即使网上已经出新版本了。这会导致你“永远在用旧版本”。遇到这类需求我有两个办法在依赖清单文件层面触发变化比如更新requirements.lock、package-lock.json。在关键位置引用构建参数比如ARG RELEASE_VERSION1.0.0然后通过--build-arg RELEASE_VERSION2.0.0来强制改变这一层的哈希值。至于docker build --no-cache它适合做CI上的定期无缓存构建验证“从零构建也能成功”但不建议每次开发都使用否则你会丢掉缓存带来的效率收益。5.5 镜像瘦身从哪几刀下手最有效镜像瘦身几乎是所有人都会碰到的需求但下手顺序错了容易白忙活。我一般按以下顺序来换更小的基础镜像。把python:3.11换成python:3.11-slim往往能立竿见影。清理包管理器的缓存文件。pip的--no-cache-dir、apt的rm -rf /var/lib/apt/lists/*、npm的npm cache clean --force都按需加上。RUN中合并安装与清理保证缓存垃圾不残留在任何层中。多阶段构建把编译器和源码从最终镜像里剥离出去。这个我在下一节专门讲。瘦身的效果往往不是某一个操作带来的而是多个操作叠加的。如果你做好前三点体积通常已经比一开始小30%以上了。6. 进阶分水岭多阶段构建把编译工具和运行环境彻底分离6.1 以Go程序为例看多阶段构建的全过程多阶段构建是Dockerfile里最有含金量的特性之一。它的核心思路是允许一个Dockerfile里出现多个FROM前面的阶段负责编译、依赖安装后面的阶段只拷贝最终产物运行一个精简镜像。以Go语言为例编译一个静态可执行文件需要安装Go工具链、拉取依赖最终产物只有一个二进制文件。如果单阶段构建最终镜像里还要带着Go工具链和源码体积很大。多阶段构建可以这样写FROM golang:1.21 AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED0 go build -o myapp . FROM alpine:3.19 WORKDIR /app COPY --frombuilder /app/myapp . EXPOSE 8080 ENTRYPOINT [./myapp]第一个阶段builder负责完成所有编译工作第二阶段只把编译好的myapp二进制拷贝过来基础镜像换成了极小的alpine。这两阶段在同一次构建中完成构建结果却只有一个体积小得多的运行时镜像。COPY --frombuilder是阶段之间传递文件的桥梁这是多阶段构建的关键语法。6.2 多阶段构建的语法细节和变量传递多阶段构建的语法要点包括用AS给阶段命名名字可以随便取但是要有语义比如builder、runtime。复制其他阶段的文件时用COPY --from阶段名 源路径 目标路径。ARG可以通过--build-arg传入但只作用于当前阶段。如果想在多阶段中共享构建参数可以在每个阶段里都声明同一个ARG。如果你担心Alpine基础镜像里缺少glibc兼容可以在第二阶段选择ubuntu或debian-slim这样体积会大一些但兼容性更稳。这里没有绝对的标准答案取决于你的程序运行方式和依赖。6.3 什么时候该用什么时候其实不需要多阶段构建并不是银弹它不是所有项目的必选项。如果项目本身就是解释型语言比如Python、Node.js非编译型二进制产物那么多阶段构建能提供的帮助主要是“分阶段安装依赖、减小最终镜像”依然有效。比如在一个阶段里安装编译所需的依赖在另一个阶段只复制运行所需的依赖和代码但逻辑确实比Go等编译型语言复杂一些。如果项目只是一个小工具、一个可执行脚本、或者一份静态页面单阶段构建完全够用。强行引入多阶段只会让Dockerfile变得更短不了、甚至更难维护。要学会判断什么时候需要复杂什么时候保持简单。以我的个人习惯来说我会先用最简单的单阶段把功能跑通再在优化体积时引入多阶段构建而不是一上来就写复杂模板。毕竟Dockerfile的终极目标是让构建结果可靠、让维护者一看就懂。复杂度只有在真正能换取价值时才值得引入。最后分享一个小窍门写Dockerfile时我会把docker build的缓存利用作为默认思维把安全非root、时区、敏感信息不固化作为习惯把体积优化作为迭代任务。每次构建后都看一眼docker history和docker images长此以往你对镜像的掌控力会不知不觉提升很多。
1. 把Dockerfile当成镜像的“配方”之前先理解一条核心规则一行指令 一层镜像很多朋友第一次写Dockerfile最容易产生的误解是这玩意儿就是一份“安装脚本”无非是从上到下把命令跑一遍。真正上手之后你会发现把两条指令换个位置构建时间能差好几倍把ADD改成COPY容器启动后的行为又完全是另一个样。所以在写下第一个FROM之前先搞清楚镜像的底层构建机制比背指令重要得多。Dockerfile本质上是一个纯文本文件每一行都是一条指令Docker引擎按顺序执行这些指令并在执行过程中逐步构建出镜像。这里的关键概念叫“镜像层”image layer。每执行一条指令都会产生一个新的只读层新层会叠在旧层上面。你可以把这些层想象成一摞玻璃纸每一层只记录自己相对于上一层的文件差异某个文件被新增了、某个目录被删掉了、某个环境变量被改动了。最终你在容器里看到的完整文件系统是所有这些层叠加之后的结果。这里要特别强调一点层记录的是“差异”不是“完整快照”。这个点直接决定了你对镜像体积和构建缓存的所有判断。举个例子一个基础镜像Ubuntu占了大概30MB你执行一条RUN指令装了一百多MB的开源库再执行一条COPY把项目代码复制进去。第二层和第三层都只是记录了相对上一层的改动。后续如果有一条RUN把某个大文件删掉镜像体积并不会变小因为那个文件依然躺在第二层里删除操作只是在上面盖了一张“标记纸”。这就是为什么我们在写Dockerfile时要尽量避免“装了再卸”的操作也解释了为什么清理apt缓存、删除临时文件必须和安装命令放在同一条RUN里执行否则清理根本没有意义。理解了“一层镜像对应一条指令”之后再看Dockerfile就非常直观了它不是普通的命令清单而是在定义一棵文件系统的演化树。Docker在构建时会逐层计算哈希如果某一层和上次构建的结果完全一致就直接复用之前的结果这就是所谓的构建缓存Build Cache。看似简单的机制实际上决定了你应该怎样排列指令、怎样组织文件复制、怎样选择基础镜像这些我都会在后面的章节展开。先把地基打牢你写的每一行Dockerfile不是在描述“步骤顺序”而是在层层叠加地定义目标文件系统。顺带说一句很多教程喜欢把Dockerfile比作“做菜的菜谱”。我承认这个比喻有感染力但它只说对了一半。菜谱确实能指导复现但Dockerfile更强的在于它把复现过程固化成可校验、可回滚、可审计的中间产物。任何人拿同一份Dockerfile在相同的构建条件下执行得到的镜像在功能上应当一致。这一点在团队协作和线上环境里价值巨大——环境差异不再是玄学问题而是一个可以反复验证的对象。我建议所有入门者做的第一件事找一个小项目亲手跑通最基础的指令然后打开终端盯着构建输出看几次再用docker history翻一翻镜像是怎么一层层长出来的。纸上谈兵对写Dockerfile没有帮助但“亲手看一次构建过程”绝对有奇效。2. 一个最小可复用的实例从Flask应用到第一个自建镜像2.1 先准备一个能在本地跑起来的应用为了不让例子流于形式我选一个Python Flask小应用。为什么选Flask因为它的依赖简单、启动命令直白、网上资料多适合用它来验证Dockerfile的每一条指令。项目结构如下my-flask-app/ ├── app.py └── requirements.txtapp.py内容from flask import Flask app Flask(__name__) app.route(/) def hello(): return Hello, Docker!requirements.txt内容flask3.0.0这个应用在本地跑起来后访问http://localhost:5000会显示一行文本。你可以在自己的机器上先用pip install flask或创建虚拟环境跑通它确保基础功能正常。这一步很重要因为写Dockerfile时你要知道“程序本身是好的”否则后面出问题很难判断到底是代码问题还是镜像问题。2.2 逐行写出第一版Dockerfile并说清楚每行的意图在项目根目录下新建一个名为Dockerfile的文件注意这个文件名是约定俗成的Docker默认就会去找它不需要额外配置。FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY app.py . EXPOSE 5000 CMD [python, app.py]我们来逐行解析FROM python:3.11-slim指定基础镜像。它是构建的第一层也是整座大楼的地基。选择了官方Python 3.11的slim变体体积比完整版小很多但比Alpine更“正常”不容易遇到编译依赖缺失的问题。WORKDIR /app设置工作目录。这行的意思是后续所有RUN、CMD、COPY等指令都会默认在这个目录下执行。如果目录不存在Docker会自动创建。它能避免一堆路径拼接的麻烦比如你不需要每一条指令都写cd /app。COPY requirements.txt .把依赖清单复制到镜像的/app目录下。这里先复制依赖清单而不是把整个项目复制进去是为了利用构建缓存。后面的第4节会详细解释。RUN pip install --no-cache-dir -r requirements.txt在镜像中安装Python依赖。--no-cache-dir不让pip保留缓存文件避免无谓地撑大镜像。COPY app.py .把应用源码复制进镜像。现在依赖已经装好再把代码放进去这样以后改代码时依赖层可以继续走缓存。EXPOSE 5000声明容器对外提供服务的端口是5000。它本身不发布端口只起到“告诉别人这个镜像默认监听哪个端口”的作用更像一份文档。CMD [python, app.py]指定容器启动后要运行的默认命令。使用JSON数组形式写表示不会经过Shell执行这是官方推荐的做法。2.3 构建、启动、验证三条命令打开新世界一切准备就绪后在项目根目录执行下列命令docker build -t my-flask-app .注意最后的.不能丢它表示构建上下文build context是当前目录。Docker会把这个目录下的所有文件打包发送给Docker守护进程供构建过程使用。构建完成后你可以用一条命令将其启动docker run -p 5000:5000 my-flask-app-p 5000:5000的作用是把容器内的5000端口映射到宿主机上的5000端口。然后打开浏览器访问http://localhost:5000如果看到Hello, Docker!恭喜你第一个自建镜像已经跑通了。如果想在后台运行把-p前面的启动命令改成docker run -d -p 5000:5000 --name my-flask-app my-flask-app查看日志用docker logs -f my-flask-app很多人第一次会漏掉-p结果容器起来了但宿主机根本访问不到。这不是Dockerfile的问题是你还没理解容器端口和宿主机端口是隔离的。EXPOSE只做声明-p才是真正的“接线”。理解这点后以后调试网络问题会省力很多。2.4 用 docker history 看镜像分层的真实面貌构建完成后建议立刻执行docker history my-flask-app你会看到类似这样的输出IMAGE CREATED CREATED BY SIZE a1b2c3d4e5f6 1 minute ago CMD [python app.py] 0B ab12cd34ef56 1 minute ago EXPOSE 5000 0B ...每一行对应的正是你书写的每一条Dockerfile指令。通过docker history你能直观看到层数是按你写的指令数量生成的有些指令不产生文件变化如EXPOSE、CMD所以SIZE为0只有真正改动文件系统的指令如COPY、RUN才会产生体积。这一步做完前面“一行指令 一层镜像”就不再是抽象概念而是亲眼可证的事实了。3. 核心指令逐个拆解每条指令都有它存在的理由3.1 FROM基础镜像不是越大越好FROM是Dockerfile的第一条有效指令它定义了构建的起点。你可以选择几乎任何镜像仓库里的镜像但选择本身是有讲究的。常见的Python官方镜像变体有python:3.11、python:3.11-slim、python:3.11-alpine。完整版体积大里带有很多编译工具和开发头文件slim版本精简了大部分非必需组件alpine基于musl libc体积最小但有些依赖需要编译翻车概率也更高。我的建议很简单优先考虑官方镜像优先使用slim变体等真正遇到体积瓶颈或者安全扫描要求再考虑alpine。为了省几十兆体积去踩一堆编译兼容性的坑很划不来。还有一个基础镜像的隐性风险有些镜像的tag是可变的。比如python:3.11会持续更新而python:3.11.7是固定的。如果你追求可复现构建建议锁定到具体的小版本或者至少锁定到次要版本避免某天基础镜像更新依赖编译行为变化导致镜像构建出一个“昨天还能跑今天就起不来”的情况。3.2 COPY和ADD复制文件也是一门学问COPY的作用是把构建上下文里的文件或目录复制到镜像文件系统中它是Dockerfile里最常用的指令之一。基本语法是COPY 源路径 目标路径源路径是相对于构建上下文的目标路径是相对于WORKDIR的绝对路径。ADD在功能上是COPY的超集它额外支持远程URL下载并且当源文件是本地tar压缩包时会自动解压。听起来很方便但这恰恰是最大的坑。假如你想把一个名为package.tar.gz的文件复制到镜像里而不是解压它你无法用ADD完成这个操作因为它会按自己的规则自动解开。建议新手一律用COPY等真正需要解压逻辑时再明确使用ADD。这背后有一个更普适的原则单一职责。COPY只做文件复制逻辑简单、行为可预期ADD融合了“下载”和“解压”多个行为使用它在节省编写时间的同时也把不确定性引入了构建过程。对于构建自动化来说不确定性是敌人。3.3 RUN凡是容器里要安装的东西都在这一条命令里处理RUN是你执行安装操作的主力指令。几乎所有的apt-get install、pip install、npm install都写在RUN里。但这里面的执行方式有一个重要细节——命令行的写法。很多初学者会写FROM ubuntu:22.04 RUN apt-get update RUN apt-get install -y python3 RUN rm -rf /var/lib/apt/lists/*这个写法在语法上没错但在实践中有两个问题它生成了三个层其中apt-get update和apt-get install产生的apt缓存数据被保留在了第一层和第二层。如果你只改了第三层清理缓存的命令前两层依然会被缓存但这跟前两层无关。实际上由于前两层是“变化不频繁”的反而缓存命中率很高——可问题在于它们留下的缓存文件会永远占据镜像体积。更合理的写法是FROM ubuntu:22.04 RUN apt-get update \ apt-get install -y python3 \ rm -rf /var/lib/apt/lists/*用把update、install、clean三个步骤串在同一条RUN中它们会被包含在同一层里。这样产生的镜像层既包含安装结果也不包含apt缓存垃圾。更关键的是如果以后你需要调整安装的软件包名单只需修改这一条RUN整层缓存失效后重建不会留下一堆没用的中间层。3.4 ENV与ARG构建参数和运行参数千万别混用简单说ENV设置的是容器内始终存在的环境变量它在构建阶段和运行阶段都有效会被写入镜像配置。ARG只是一个构建期参数仅存在于构建过程中镜像运行起来后它就不存在了。举个例子ARG APP_ENVdevelopment ENV APP_ENV$APP_ENV通过docker build --build-arg APP_ENVproduction -t my-app .传入构建参数然后把它固化到ENV里让最终运行的容器环境变量是production。如果你直接写ENV APP_ENVproduction也不是不行但这样你就没法在不改Dockerfile的前提下切换环境了。实际操作中我见过太多人在容器里硬编码数据库地址、密钥等环境变量。千万不要这样做。环境变量在Dockerfile里是“配置的入口”真正的值应该通过-e参数或者docker compose的environment字段注入。Dockerfile可以定义默认值但不应该成为敏感信息的存放地。3.5 CMD与ENTRYPOINT一个管“默认”一个管“固定”这是最容易混淆的一对指令我就用一句话讲清楚区别CMD是“默认启动命令”ENTRYPOINT是“固定入口程序”。如果你在Dockerfile里只写CMD那么使用者可以在docker run时附加参数来覆盖它。比如CMD [python, app.py]那么执行docker run my-flask-app --help时Docker会把--help追加到命令后面相当于实际执行python app.py --help。如果你用ENTRYPOINT指定了入口比如ENTRYPOINT [python, app.py]那么后面再传的--help会变成它的参数执行docker run my-flask-app --help就相当于执行python app.py --help两者在表面上看着相似但语义不同——ENTRYPOINT是“程序的主要入口”CMD是“额外的默认参数”。两者经常搭配使用最经典的组合是ENTRYPOINT [python] CMD [app.py]这样使用者就可以通过docker run my-flask-app other.py切换到别的Python脚本而Python解释器本身始终不会变。对可执行程序类镜像来说这种设计非常常见。为了更清晰地对比我整理了一张表指令组合运行docker run [镜像] --help的效果适用场景只有CMD执行默认命令并附加--help普通服务、可改入口的应用只有ENTRYPOINT执行固定入口并附加参数固定解释器、封装的工具ENTRYPOINT CMD入口固定CMD作为默认参数想保留灵活性又锁住主程序的镜像3.6 EXPOSE、USER、VOLUME、HEALTHCHECK那些看着不起眼但迟早要用的指令EXPOSE上面讲过了是声明端口用的。它不影响实际网络映射但会给使用镜像的人提供重要信息比如别人拿到你的镜像看EXPOSE就能知道服务默认监听哪个端口。USER用于切换运行身份。默认情况下容器以root运行这在本地开发时无感但一旦涉及到生产环境、容器逃逸风险、权限粒度授权root身份都是隐患。最佳实践是创建一个普通用户并用它启动进程RUN useradd -m appuser USER appuser这样容器内进程以非特权身份运行降低被攻破后的影响面。VOLUME用来声明挂载点。它不会真的创建匿名卷主要是写给使用镜像的人看“这些目录需要挂载数据卷否则数据无法持久化。”比如数据库镜像会声明VOLUME [/var/lib/postgresql/data]。HEALTHCHECK是镜像层面的探活指令。它允许你定义容器如何被判定存活比如HEALTHCHECK --interval30s --timeout3s --retries3 \ CMD curl -f http://localhost:5000/ || exit 1这样编排平台就能依赖健康状态自动做重启等操作。在本地写镜像时你大可以忽略但如果你想做一个能上线、能被编排系统管理的镜像HEALTHCHECK是不可或缺的。4. 为什么指令顺序会影响构建速度缓存、分层和.dockerignore4.1 构建缓存是如何命中和失效的Docker构建缓存的核心逻辑是逐层哈希。当Docker开始构建一条指令时它会检查当前的基础层是否和上一次构建一致如果一致它还会比较要执行的指令内容以及构建上下文里涉及的文件内容。只有当前一层不变、指令不变、相关文件不变它才会直接复用缓存层。这就是为什么COPY requirements.txt .在逻辑上会“碰”到文件本身的内容。如果你把依赖清单放在代码复制那一行之后才复制那么每次代码有改动即使依赖清单没变Docker也会因为无法判断新增的代码是否影响依赖安装而让后续层失效。反之先复制依赖清单安装依赖再复制代码只要依赖清单不变依赖层就能复用缓存构建速度会快非常多。4.2 经验法则把不变的内容放前面把频繁变化的内容放后面这个经验法则几乎适用于所有Dockerfile。稳定的、不怎么动的、体积大的内容放前面你的源码、配置文件这种经常变的内容放后面。这么做带来的收益在修改源代码后立刻就能体现——你改了一行代码依赖层不用重装只需重新复制源码层耗时从几分钟变成几秒。举一个反例有人把COPY . .放在最前面然后才RUN install。这等于把整个项目的文件变化都丢给了缓存判定。结果是改一行代码后续所有安装步骤全部重来。这通常发生在不熟悉缓存机制的人身上也是构建时间长的主要原因之一。4.3 .dockerignore避免把不相干的东西烤进镜像.dockerignore之于Dockerfile相当于.gitignore之于Git。它的作用是定义构建上下文的排除规则。每次构建时Docker会把当前目录的文件打包发送给守护进程如果你的项目里有node_modules、__pycache__、.git、dist这些大目录它们都会被无差别发送即使你的Dockerfile完全不复制它们。这不仅让构建上下文体积膨胀得厉害在某些场景下还会导致缓存判断异常。一个典型的.dockerignore文件.git node_modules __pycache__ *.pyc .DS_Store dist build .env编写它的原则很简单凡是Dockerfile里不需要的都尽量排除。这既是为了构建速度也是为了避免把你本地的临时文件、密钥文件等意外带进镜像。4.4 不是层越少越好而是“该拆的拆该合的合”有一种误解是“镜像层越少越高级”。因此有些人会把所有RUN全部串成一个巨型RUN。这样做的确能减少层数但代价是可读性变差、缓存粒度过大。比如你把安装操作系统依赖、安装Python依赖、安装项目依赖全部写进一条RUN以后只要改其中一个另外两个也要跟着重新执行。我的建议是按“依赖阶段”拆分而不是死抠层数。比如系统级依赖放一条RUN语言级依赖放一条RUN源码复制单独一条。这样既照顾了缓存命中率也保持了可读性。镜像层数本身不是性能问题关键是要在缓存、体积、可读性之间找到一个适合你项目的平衡点。5. 调试和发布时踩过的坑我帮你提前标记出来5.1 ADD的解压行为好用但容易失控前面提过ADD会自动解压本地tar。这个特性在某些场景下是褒义的比如你要解压一个离线安装包一条ADD就搞定ADD jdk-17.tar.gz /opt/但如果你只是想复制一个.tar.gz文件到镜像里等运行时再处理ADD就会给你带来完全无法理解的“行为偏差”——它会提前解压最终产出的目录结构和你的预期完全不一样。以我个人的经验生产环境里的新坑大多是ADD引起的。所以除非明确要做解压否则一律用COPY。5.2 容器的时区是UTC这个坑能坑你一整天容器默认时区一般是UTC而国内服务的日志和业务通常需要北京时间。如果你没有设置时区很可能会在排查日志时间时发现怎么都对不上差了8小时。解决方案很简单ENV TZAsia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime echo $TZ /etc/timezone注意时区文件的路径需要基础镜像里有tzdata包有些精简镜像没有需要先安装。这是一个典型的环境差异问题不写Dockerfile的人根本不会意识到。5.3 用非root用户启动进程安全上线前必做的事默认情况下容器内进程以root身份运行。这在一台隔离的本地开发机上可能没什么问题但在生产环境里容器一旦被突破攻击者就拿到了宿主机的root权限当然这取决于容器配置、内核版本等但风险真实存在。自动化审计和安全管理工具通常也会对“容器以root运行”发出警告。我的建议是在Dockerfile里显式创建用户并用USER指令切换。比如FROM python:3.11-slim RUN groupadd -r appuser useradd -r -g appuser appuser WORKDIR /app COPY --chownappuser:appuser . . USER appuser CMD [python, app.py]这里还用到了--chown参数把复制文件的所有者切换为普通用户。否则即使你USER改成appuser文件还是root所有应用可能没有写权限。5.4 缓存的另一面什么时候必须 --no-cache 强制重建构建缓存会减少构建时间但它也会在某些场景下变成陷阱。比如你的Dockerfile里有一条RUN从网上拉取最新版本的工具包因为指令内容从来没变过Docker会复用它之前构建时的层即使网上已经出新版本了。这会导致你“永远在用旧版本”。遇到这类需求我有两个办法在依赖清单文件层面触发变化比如更新requirements.lock、package-lock.json。在关键位置引用构建参数比如ARG RELEASE_VERSION1.0.0然后通过--build-arg RELEASE_VERSION2.0.0来强制改变这一层的哈希值。至于docker build --no-cache它适合做CI上的定期无缓存构建验证“从零构建也能成功”但不建议每次开发都使用否则你会丢掉缓存带来的效率收益。5.5 镜像瘦身从哪几刀下手最有效镜像瘦身几乎是所有人都会碰到的需求但下手顺序错了容易白忙活。我一般按以下顺序来换更小的基础镜像。把python:3.11换成python:3.11-slim往往能立竿见影。清理包管理器的缓存文件。pip的--no-cache-dir、apt的rm -rf /var/lib/apt/lists/*、npm的npm cache clean --force都按需加上。RUN中合并安装与清理保证缓存垃圾不残留在任何层中。多阶段构建把编译器和源码从最终镜像里剥离出去。这个我在下一节专门讲。瘦身的效果往往不是某一个操作带来的而是多个操作叠加的。如果你做好前三点体积通常已经比一开始小30%以上了。6. 进阶分水岭多阶段构建把编译工具和运行环境彻底分离6.1 以Go程序为例看多阶段构建的全过程多阶段构建是Dockerfile里最有含金量的特性之一。它的核心思路是允许一个Dockerfile里出现多个FROM前面的阶段负责编译、依赖安装后面的阶段只拷贝最终产物运行一个精简镜像。以Go语言为例编译一个静态可执行文件需要安装Go工具链、拉取依赖最终产物只有一个二进制文件。如果单阶段构建最终镜像里还要带着Go工具链和源码体积很大。多阶段构建可以这样写FROM golang:1.21 AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED0 go build -o myapp . FROM alpine:3.19 WORKDIR /app COPY --frombuilder /app/myapp . EXPOSE 8080 ENTRYPOINT [./myapp]第一个阶段builder负责完成所有编译工作第二阶段只把编译好的myapp二进制拷贝过来基础镜像换成了极小的alpine。这两阶段在同一次构建中完成构建结果却只有一个体积小得多的运行时镜像。COPY --frombuilder是阶段之间传递文件的桥梁这是多阶段构建的关键语法。6.2 多阶段构建的语法细节和变量传递多阶段构建的语法要点包括用AS给阶段命名名字可以随便取但是要有语义比如builder、runtime。复制其他阶段的文件时用COPY --from阶段名 源路径 目标路径。ARG可以通过--build-arg传入但只作用于当前阶段。如果想在多阶段中共享构建参数可以在每个阶段里都声明同一个ARG。如果你担心Alpine基础镜像里缺少glibc兼容可以在第二阶段选择ubuntu或debian-slim这样体积会大一些但兼容性更稳。这里没有绝对的标准答案取决于你的程序运行方式和依赖。6.3 什么时候该用什么时候其实不需要多阶段构建并不是银弹它不是所有项目的必选项。如果项目本身就是解释型语言比如Python、Node.js非编译型二进制产物那么多阶段构建能提供的帮助主要是“分阶段安装依赖、减小最终镜像”依然有效。比如在一个阶段里安装编译所需的依赖在另一个阶段只复制运行所需的依赖和代码但逻辑确实比Go等编译型语言复杂一些。如果项目只是一个小工具、一个可执行脚本、或者一份静态页面单阶段构建完全够用。强行引入多阶段只会让Dockerfile变得更短不了、甚至更难维护。要学会判断什么时候需要复杂什么时候保持简单。以我的个人习惯来说我会先用最简单的单阶段把功能跑通再在优化体积时引入多阶段构建而不是一上来就写复杂模板。毕竟Dockerfile的终极目标是让构建结果可靠、让维护者一看就懂。复杂度只有在真正能换取价值时才值得引入。最后分享一个小窍门写Dockerfile时我会把docker build的缓存利用作为默认思维把安全非root、时区、敏感信息不固化作为习惯把体积优化作为迭代任务。每次构建后都看一眼docker history和docker images长此以往你对镜像的掌控力会不知不觉提升很多。
