企业官网建设流程全解析

从这篇开始，说明你已经不再满足于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 . /app

ADD比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提供默认的执行命令或参数，容器运行时如果没有额外指定命令，就用CMD；
• ENTRYPOINT是容器启动时固定执行的入口程序，不会被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 VERSION=1.0 ENV APP_VERSION=$VERSION

常见用法是：用ARG传不同环境的版本号，用ENV把ARG值固化到环境变量里。构建时可以用--build-arg VERSION=2.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特性--mount=type=cache，把包管理器缓存目录挂出来，多轮构建之间可以复用：

# syntax=docker/dockerfile:1 FROM node:18-slim WORKDIR /app COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm \ npm ci

这样npm ci下载的包缓存不会随层销毁，二次构建速度快非常多。

3.2 用.dockerignore给构建上下文瘦身

构建上下文越大，发送给Docker守护进程的数据就越多，构建越慢。默认情况下docker build .，Docker会把当前目录整个打包发给守护进程。

我见过有人把整个项目目录、node_modules、git目录、构建产物全打进去，构建一次需要几十秒来传输数据。解决办法是写一份.dockerignore：

node_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_ENABLED=0 go build -o app . # 阶段二：运行阶段 FROM alpine:3.19 RUN apk add --no-cache ca-certificates COPY --from=builder /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 --chown=appuser:appuser . /app # 切换用户 USER appuser ENTRYPOINT ["node", "app.js"]

容器内部默认是root用户，而一旦容器被攻破，root权限意味着这等于和宿主机root一样。创建非root用户，至少有了一层隔离。COPY --chown是为了让复制的文件归这个用户所有，否则普通用户没有权限读或执行。

另一个安全习惯是给基础镜像打sha256指纹，来保证不可变性：

FROM node:18-slim@sha256: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 └── Dockerfile

package.json：

{ "name": "my-app", "version": "1.0.0", "main": "app.js", "scripts": { "start": "node app.js" }, "dependencies": { "express": "^4.18.2" } }

app.js：

const 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 第一版Dockerfile

FROM 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 --only=production && \ npm cache clean --force # 改用户后复制源码 COPY --chown=appuser: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 --from=build --chown=appuser:appuser /app/node_modules ./node_modules COPY --chown=appuser: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 常见报错速查表

5.2 时会遇到的几个典型问题

APK_INDEX之类的缓存问题、时区不对的问题、镜像内没有bash的问题——这些小问题看着不起眼，但一旦遇到排查起来很花时间。

第一个是时区问题。基础镜像默认UTC时间，中国时区需要显示东八区：

RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive 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不难，但它绝对是容器化实践里最关键的一步。