先搞清楚概念：镜像、Dockerfile、构建上下文#

**镜像（Image）**是容器的「安装包」：里面装着应用代码、运行时、依赖库和启动命令，是只读的。容器是镜像跑起来之后的进程。

Dockerfile 是制作镜像的「菜谱」：一个纯文本文件，一行一条指令，描述从哪个基础镜像开始、往里面放什么、装什么、最后怎么启动。docker build 命令照着菜谱一层层执行，产出镜像。

构建上下文（Build Context）是最容易被新手忽略的概念：执行 docker build . 时，最后那个 . 指的目录就是构建上下文，Docker 会先把整个目录打包发送给 Docker 守护进程，Dockerfile 里的 COPY 只能复制这个目录里的文件。两个直接后果：

• 不要在 home 目录、盘根目录这种地方执行 docker build .，几个 GB 的无关文件会被一起打包发送，构建慢到怀疑人生；
• 源码目录里混着的 .git、node_modules、虚拟环境、日志文件都会进上下文，这正是 .dockerignore 要解决的问题，后文专门讲。

层（Layer）：Dockerfile 里每条会修改文件系统的指令（FROM、COPY、RUN 等）都会生成一个只读层，镜像就是一层层叠起来的。层会被缓存——这是理解构建速度的关键，后文优化部分全在围绕它做文章。

再补充两个和构建体验直接相关的点。其一，现在的 Docker 默认使用 BuildKit 构建引擎（docker build 背后就是它），它的输出会把每个步骤编号、并行处理互不依赖的阶段，还原生支持后文提到的多阶段构建和构建期密钥挂载。你在构建日志里看到的步骤编号和 CACHED 标记，都来自它。其二，Dockerfile 的文件名默认就叫 Dockerfile（没有扩展名，首字母大写），放在项目根目录；一个项目需要多个镜像时可以用 -f 指定别的文件，比如 docker build -f Dockerfile.worker -t myapp-worker:1.0 .，但没有特殊需求时保持默认名，工具链和同事都能一眼找到它。

主线例子：一个极简 Python 服务#

先写应用本身。用 Flask 写一个只有两个接口的小服务，保存为 app.py：

1
from flask import Flask, jsonify
2
import os
3

4
app = Flask(__name__)
5

6

7
@app.route("/")
8
def index():
9
    return jsonify(message="hello from my image", env=os.environ.get("APP_ENV", "prod"))
10

11

12
@app.route("/health")
13
def health():
14
    return jsonify(status="ok")
15

16

17
if __name__ == "__main__":
18
    app.run(host="0.0.0.0", port=8000)

依赖清单 requirements.txt：

1
flask==3.0.3
2
gunicorn==22.1.0

注意两个细节：一是 app.run 监听 0.0.0.0 而不是默认的 127.0.0.1，容器里的服务只听本机回环的话，宿主机端口映射进来也连不上，这是新手最常见的坑之一；二是依赖钉死版本号，保证半年后重新构建出来的镜像和今天的一致。

生产环境不用 Flask 自带的开发服务器（app.run），用 gunicorn 承载，所以它也在依赖清单里。app.py 里的 app.run 只留作本地直接运行调试。

项目目录结构：

1
myapp/
2
├── app.py
3
├── requirements.txt
4
└── Dockerfile

初版 Dockerfile：先跑起来再说#

第一版怎么简单怎么来：

1
FROM python:3.12
2
WORKDIR /app
3
COPY . .
4
RUN pip install -r requirements.txt
5
EXPOSE 8000
6
CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]

构建并运行：

1
cd myapp
2
docker build -t myapp:0.1 .
3
docker run -d --name myapp -p 8000:8000 myapp:0.1
4
curl http://localhost:8000/
5
curl http://localhost:8000/health

两个接口都返回 JSON 就说明镜像做对了。docker build 的 -t 是给镜像起名字和标签（名字:标签），结尾的 . 是构建上下文路径，一个都不能少。

这一版能跑，但毛病不少：镜像有 1 GB 上下（完整的 python:3.12 带着全套编译工具）、改一行代码就要把依赖重装一遍、容器里是 root 在跑服务。下面逐条把指令讲透，边讲边改。

逐条讲指令#

1
RUN pip install --no-cache-dir -r requirements.txt

1
ARG PYTHON_VERSION=3.12
2
FROM python:${PYTHON_VERSION}-slim
3
ENV APP_ENV=prod \
4
    TZ=Asia/Shanghai \
5
    PYTHONUNBUFFERED=1

1
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
2
  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"

1
ENTRYPOINT ["gunicorn"]
2
CMD ["-b", "0.0.0.0:8000", "app:app"]

层缓存优化：改代码别重装依赖#

回到初版的问题：为什么改一行 app.py，pip install 要全部重跑？因为构建缓存是按层失效的：COPY . . 这一层里任何文件变了（包括 app.py），这一层及其之后所有层的缓存全部作废，排在它后面的 RUN pip install 自然要重新执行。

解法是把「变得少的」和「变得勤的」拆开：依赖清单很少变，源码天天变，那就先只拷依赖清单、装依赖，最后才拷源码：

1
FROM python:3.12-slim
2
WORKDIR /app
3
COPY requirements.txt .
4
RUN pip install --no-cache-dir -r requirements.txt
5
COPY . .
6
EXPOSE 8000
7
CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]

对比效果立竿见影：

记住这条通用原则：指令按「变化频率从低到高」排列——基础镜像、系统包、依赖清单、依赖安装、源码，越靠前越稳定。这也是为什么经验丰富的 Dockerfile 都是这个套路。

另外验证缓存时可以看构建输出：命中缓存的步骤会标 CACHED。改一行 app.py 重新 docker build，确认只有最后两三层在重跑，优化就生效了。

还有一个体积相关的层常识：删除文件要在同一层里删。镜像的层是只读叠加的，你在下一层 RUN rm 删掉上一层装的东西，只是做了个「遮罩」，文件本体还躺在下层里，镜像一点没小。所以 apt 清列表、pip 不留缓存都要和安装写进同一条 RUN。

.dockerignore：别把垃圾打包进上下文#

在项目根目录建 .dockerignore，语法和 .gitignore 一样，列出的文件在构建时既不发送给守护进程、也 COPY 不到：

1
.git
2
__pycache__
3
*.pyc
4
.venv
5
venv
6
.env
7
*.log
8
.pytest_cache
9
Dockerfile
10
.dockerignore

它的重要性有三层：

1. 构建速度：上下文从几百 MB（带着 .git 和虚拟环境）瘦到几 MB，发送和 COPY 都快得多；
2. 缓存准确：不相干的文件（日志、缓存目录）变动不会让 COPY . . 层失效，白白触发重构建；
3. 安全：.env 里常有数据库密码、Token，不写进 ignore 的话 COPY . . 就把它们焊死在镜像里，谁拿到镜像谁就能翻出来——这是真实发生过很多次的泄露方式。

每写一个新项目，先建 .dockerignore 再写 Dockerfile。

再细讲三条写法规则，避免踩坑：

还有一种常见误会要澄清：.dockerignore 只影响构建时发送的上下文，镜像里已经通过其他途径装进去的东西不受它管，它不是运行时文件过滤器。

多阶段构建：从几百 MB 瘦到几十 MB#

有些应用构建时需要一整套重型工具链（编译器、开发头文件、Node 依赖），但运行时只需要编译产物。把工具链也塞进最终镜像，体积爆炸且攻击面变大。多阶段构建的做法是：在一个 Dockerfile 里写多个 FROM，前面的阶段负责构建，最后一个阶段只从前面拷产物。

以 Go 服务为例（Go 编译出单个二进制，最能体现效果）。源码 main.go：

1
package main
2

3
import (
4
  "fmt"
5
  "net/http"
6
)
7

8
func main() {
9
  http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
10
    fmt.Fprintln(w, "hello from go")
11
  })
12
  http.ListenAndServe(":8080", nil)
13
}

两阶段 Dockerfile：

1
# ---------- 构建阶段 ----------
2
FROM golang:1.22 AS builder
3
WORKDIR /src
4
COPY go.mod ./
5
RUN go mod download
6
COPY . .
7
RUN CGO_ENABLED=0 go build -o /out/server .
8

9
# ---------- 运行阶段 ----------
10
FROM alpine:3.20
11
WORKDIR /app
12
COPY --from=builder /out/server .
13
EXPOSE 8080
14
CMD ["./server"]

拆解关键点：

• FROM golang:1.22 AS builder 给第一阶段起名 builder，这个阶段的镜像约 800 MB，装着完整 Go 工具链，但它只是中间产物，不会发布；
• 最后阶段从只有约 7 MB 的 alpine 重新开始，COPY --from=builder /out/server . 只把编译好的二进制拷过来；
• CGO_ENABLED=0 编译出纯静态二进制，不依赖 glibc，所以能在 alpine（musl）甚至 scratch（空镜像）里跑。

最终镜像 = alpine 底 + 一个十几 MB 的二进制，总共不到 30 MB，而单阶段直接用 golang 镜像跑会是 800 MB 以上。前端项目同理：第一阶段用 node 镜像 npm run build，最终阶段用 nginx:alpine 只拷 dist 目录，几百 MB 的 node_modules 一点都不带走。

多阶段构建里层缓存的原则同样适用：例子中先 COPY go.mod 并 go mod download，再 COPY . . 编译，改源码不会重下依赖。

前端项目的两阶段写法也一并给出，套路完全相同——第一阶段负责「生产」，第二阶段只拿产物去「营业」：

1
# ---------- 构建阶段 ----------
2
FROM node:20-slim AS builder
3
WORKDIR /app
4
COPY package.json package-lock.json ./
5
RUN npm ci
6
COPY . .
7
RUN npm run build
8

9
# ---------- 运行阶段 ----------
10
FROM nginx:1.27-alpine
11
COPY --from=builder /app/dist /usr/share/nginx/html
12
EXPOSE 80

第一阶段里装着完整的 Node 环境和几百 MB 的 node_modules，最终镜像却只有 Nginx alpine 加一份静态文件，通常不到 50 MB。这里还顺带用了缓存原则：先拷 package.json 和锁文件装依赖，再拷源码构建，改页面代码不会触发重新装包。注意 npm ci 是按锁文件精确安装，比 npm install 更适合构建场景，结果可复现。

非 root 运行：给服务一个普通用户#

容器里默认 root 跑服务，意味着一旦应用被打穿，攻击者拿到的就是容器内的最高权限，再叠加内核或配置问题时风险更大。给应用建个普通用户只需要三步，写进 Dockerfile：

1
FROM python:3.12-slim
2
WORKDIR /app
3

4
RUN groupadd -r appuser && useradd -r -g appuser appuser
5

6
COPY requirements.txt .
7
RUN pip install --no-cache-dir -r requirements.txt
8

9
COPY --chown=appuser:appuser . .
10

11
USER appuser
12
EXPOSE 8000
13
CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]

要点：

• 用户要在 COPY 和 USER 之前创建好（Debian 系用 groupadd/useradd，alpine 是 addgroup/adduser）；
• COPY --chown=appuser:appuser 在复制时直接把文件属主设成应用用户。否则文件全是 root 的，USER 切过去之后应用想写日志、写临时文件会 permission denied。不加 --chown 就得额外 RUN chown -R，那会再复制一份文件数据，白白多一层体积；
• USER 写在 CMD 之前，它决定运行时的身份；它之前的 RUN pip install 仍然是 root 执行，装系统级依赖不受影响；
• 普通用户不能监听 1024 以下的特权端口，所以容器内服务用 8000、8080 这类高位端口，再用 -p 80:8000 映射出去，正好和我们的例子一致。

改完后 docker exec myapp whoami 应该输出 appuser，验证生效。

给镜像打标签与推送#

1
docker build -t myapp:1.2.0 .
2
docker tag myapp:1.2.0 myapp:1.2
3
docker tag myapp:1.2.0 myapp:latest

1
docker tag myapp:1.2.0 anexns/myapp:1.2.0
2
docker push anexns/myapp:1.2.0

1
docker history myapp:1.2.0
2
docker image inspect myapp:1.2.0

汇总：生产可用的最终版 Dockerfile#

把前面所有优化合到一起，本例的成品：

1
FROM python:3.12-slim
2

3
ENV PYTHONUNBUFFERED=1 \
4
    TZ=Asia/Shanghai
5
WORKDIR /app
6

7
RUN groupadd -r appuser && useradd -r -g appuser appuser
8

9
COPY requirements.txt .
10
RUN pip install --no-cache-dir -r requirements.txt
11

12
COPY --chown=appuser:appuser . .
13

14
USER appuser
15
EXPOSE 8000
16
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
17
  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"
18
CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]

配合 .dockerignore 使用。这版镜像约 180 MB，非 root 运行，改源码重构建只要几秒，健康状态在 docker ps 里可见。

排障#

构建失败，先定位到哪一层。 docker build 的输出是按步骤走的，报错的那一步就是出问题的指令。常见原因：COPY 的源文件不在构建上下文里（路径写错或被 .dockerignore 排除了）；RUN 里命令返回非 0（依赖源连不上、包名写错）。想进到失败现场看看，可以构建到出问题的前一层打个临时镜像进去排查：

1
docker build --target builder -t debug:tmp .
2
docker run -it --rm debug:tmp /bin/bash

（--target 指定构建到多阶段中的某个阶段为止。）另外 docker build --no-cache 可以排除缓存干扰，确认问题是不是缓存造成的，但别拿它当日常构建方式，那等于放弃全部缓存优化。

构建特别慢。 十有八九是上下文太大：构建开始时会显示发送上下文的大小（Sending build context to Docker daemon 512MB 这种），真这么大就去补 .dockerignore，尤其检查 .git、node_modules、.venv 有没有被排掉。

容器起来就退出 / 连不上。 先 docker logs 容器名 看应用自己的报错；再检查监听地址是不是 0.0.0.0（只听 127.0.0.1 时端口映射无效）；然后核对 -p 映射的容器端口和应用监听、Dockerfile 里 EXPOSE 的是否一致。

构建时装依赖超时或 404。 先分清是网络问题还是版本问题：同一个命令在宿主机上直接跑一遍，能复现就是源或版本的问题（版本号写错、包被下架），宿主机正常而容器里失败，多半是构建环境没走代理或 DNS 有问题。国内网络装 pip、apt 慢，可以在构建时临时换镜像源（给 pip 加 -i 参数指向国内源、apt 换源地址），但换源地址建议通过 ARG 传入而不是写死在 Dockerfile 里，这样同一份文件在不同网络环境都能构建。构建成功但运行行为和本地不一致，则优先怀疑三件事：基础镜像版本没钉死导致依赖漂移、时区和语言环境变量没设（日志时间对不上多半是它）、文件属主或权限不对（配合前文的 --chown 检查）。

镜像太大，常见原因清单：

• 基础镜像用了完整版（换 slim/alpine 或多阶段构建）；
• 构建工具链、开发依赖进了运行镜像（多阶段构建，或把 dev 依赖拆到单独的 requirements 文件）；
• pip/apt 缓存留在层里（--no-cache-dir、清 apt lists，且和安装写在同一条 RUN）；
• 在后面的层里 rm 前面层的文件（删不掉，用同一层删除或多阶段）；
• COPY . . 把 .git、日志、大文件一起拷了进来（.dockerignore 没写全）。

定位顺序：docker history 找到胖的那一层 → 对照上面清单逐项排除。

小结#

• Dockerfile 是镜像的菜谱，构建上下文决定 COPY 能拿到什么，先写 .dockerignore 再构建；
• 指令按变化频率从低到高排：依赖清单先于源码，改代码才不会重装依赖；
• 基础镜像选 slim 而非 alpine 图小，libc 兼容性更重要；体积的大头靠多阶段构建砍；
• 服务用普通用户跑，文件属主用 COPY --chown 一步到位；
• CMD/ENTRYPOINT 用 exec 形式，信号才能正确传给应用；
• 标签打语义化版本，latest 只当别名；推送前用 docker history 和 inspect 体检一遍。

最后给一条练习路径建议：不要对着文档空学，拿自己手头任何一个小脚本，按「初版跑通 → 换 slim → 拆依赖层 → 补 .dockerignore → 切非 root」的顺序亲手改五遍，每改一步都 docker history 看一眼体积、docker build 掐一次时间。五遍走完，Dockerfile 的核心手感就有了，以后碰到别的语言（Java、Rust、PHP）也只是把构建命令换掉，骨架完全一样。

下一篇可以把这个镜像放进 Compose 里正式部署，再接上自动更新——你的应用就此进入和官方镜像一样的运维轨道了。