企业官网建设流程全解析

流水线上有个服务，每次发版构建要三分半，推上去的镜像一点二 G，拉取的时候节点磁盘告警。我把它的 Dockerfile 从头到尾读了一遍，四十多行，看着挺规范，FROM node:18、WORKDIR、COPY . .、RUN npm install、CMD ["npm","start"]，一个错别字都没有。问题恰恰出在"没写错"上——它把源码和依赖安装的顺序反了，把 devDependencies 和构建缓存一起打进了生产镜像，还把 shell 形式的启动命令留在了最后一行的位置。改完五行，构建时间掉到五十秒，镜像 180M，启动信号也能正常收到了。

Dockerfile 这门"语言"的诡异之处在于：它的语法简单到十分钟就能学会，但它背后挂着的镜像分层模型、缓存键计算、信号传递、依赖切分、供应链元数据，没一个是简单的。写得出来和写得对，中间隔着一条很宽的沟。这篇是云原生应用系列第五篇，我不打算从FROM开始逐条讲指令手册——官方文档比我讲得全——我想聊的是每条指令背后的真实代价，以及在这两年镜像构建工具链快速迭代之后，除了手写 Dockerfile 之外还有哪些路可以走、分别在什么场景下更划算。不管你是刚接手一个存量项目要优化构建速度，还是在为新服务选构建方案，下面这些内容应该都能直接对上号。

1. 先算清楚 Dockerfile 每一行的真实代价

1.1 镜像分层模型决定了"少写一行"未必更省

很多人优化 Dockerfile 的第一反应是合并RUN，把五六条命令用&&串成一条，理由是"减少层数"。这个操作在十年前是有意义的，那时候镜像层数多了确实影响性能；现在的存储驱动和镜像格式早就不是那个逻辑了，层数本身不构成瓶颈，真正影响体积的是每一层里新增了什么文件、有没有在后续层里删掉。

举个最典型的例子。下面这两段写法，最终镜像体积能差出三百多兆：

# 写法 A：装完就删，看着很干净 RUN apt-get update && apt-get install -y --no-install-recommends build-essential \ && make something \ && apt-get purge -y build-essential \ && rm -rf /var/lib/apt/lists/*

# 写法 B：同一条 RUN 里完成安装、使用、清理 RUN apt-get update \ && apt-get install -y --no-install-recommends build-essential \ && make something \ && apt-get purge -y --no-install-recommends build-essential \ && rm -rf /var/lib/apt/lists/*

这两段其实是一样的（都在同一条RUN里），我想说的是它们的反面写法——如果apt-get install和apt-get purge分在两条RUN里，purge 只会把一个"删除标记"写进新层，被删掉的文件依然留在上一层里，镜像体积一点没减。镜像层是叠加的，不是覆盖的，这是理解所有镜像瘦身技巧的前提。

所以判断一条指令贵不贵，看三个维度：它有没有引入新文件、引入的文件在最终运行时是否需要、不需要的文件能不能在同一条指令里清掉。三条都命中的指令就是优化目标。

1.2 RUN 的两种写法埋着信号处理的雷

RUN有 shell 形式和 exec 形式，这个大家都知道。但同样的区别在ENTRYPOINT和CMD上，踩坑的人就多了。

shell 形式CMD npm start会被解释成/bin/sh -c "npm start"，容器里的 PID 1 是/bin/sh，npm是它的子进程。Kubernetes 发来 SIGTERM 的时候，信号只到了sh手上，sh自己不会转发给子进程，于是应用根本没收到优雅退出的通知，硬扛三十秒（默认 terminationGracePeriodSeconds）之后被 SIGKILL。表现为：每次滚动更新都慢半拍，日志里看不到任何关闭记录，连接被硬断。

exec 形式CMD ["node", "server.js"]没有这个问题，node 直接是 PID 1。但要注意，即使是 exec 形式，如果你的应用自己不处理 SIGTERM，照样会硬断——PID 1 在 Linux 里有特殊语义，内核对 PID 1 默认不响应未经注册的信号。这时候要么在应用里显式注册信号处理器，要么在启动命令前面挂一个轻量的 init 进程。

我在实际项目里见过一个更隐蔽的变体：ENTRYPOINT ["sh", "-c", "exec java -jar app.jar"]。这里exec起了作用，sh被 java 替换掉了，PID 1 变成 java，信号能收到。但参数传递变得很别扭，docker run image --foo里的--foo会被sh吃掉而不是传给 java。要么改用ENTRYPOINT ["java","-jar","app.jar"]配CMD，要么在sh -c里显式写"$@"。

1.3 COPY 的缓存键与被忽略的 .dockerignore

COPY是缓存失效最主要的触发点，而绝大多数人没意识到它失效得有多彻底。COPY . .这一行的缓存键包含了当前上下文里所有文件的校验和，改一个 README 里的错别字，后面所有层全部重建。如果你的依赖安装写在COPY . .之后，那每次改代码都要重装一遍依赖，这就是前面那个三分半的来源。

正确的顺序永远是：先拷依赖描述文件，装依赖，再拷源码。

COPY package.json package-lock.json ./ RUN npm ci --omit=dev COPY . .

Node 项目对应package*.json，Python 对应requirements.txt或pyproject.toml，Go 对应go.mod/go.sum，Java 对应pom.xml或build.gradle。这一条改动能带来数量级的提速，属于性价比最高的优化，没有之一。

另一个常被忽略的是.dockerignore。构建上下文是整包发给构建引擎的，如果你的项目目录里有node_modules、.git、dist、测试覆盖率报告，几万个文件会被一起打包传输、一起参与校验和计算。在一个中等规模的前端项目里，光是.git目录就能让上下文膨胀到几百兆，构建开始前的传输阶段就要花十几秒。.dockerignore的写法和.gitignore基本一致，建议至少包含：

.git node_modules dist build coverage *.log .env*

注意：.dockerignore里的.env*是必须的。很多人习惯把本地环境变量文件放在项目根目录，COPY . .会把它原样打进镜像层，之后即使在后面某层删掉，历史层里依然能挖出来。

2. 多阶段构建的价值不在"多阶段"三个字

2.1 构建期依赖与运行期依赖到底怎么切

多阶段构建被讲烂了，但我发现不少团队用成了形式主义：写了个FROM ... AS builder，然后把 builder 里的整个工作目录COPY --from=builder /app /app搬过来。这样构建阶段的编译器、测试依赖、缓存目录全跟着进了运行镜像，多阶段等于白写。

切分的核心判断标准只有一条：运行期真正需要的是"产物"，不是"产出产物的环境"。Go 编译出来的静态二进制、Java 打出来的 jar、前端构建出来的静态资源目录，这些是产物；编译器、包管理器缓存、测试框架、源码，这些是环境。搬的时候只搬产物，以及产物运行所依赖的少量运行时文件（CA 证书、时区数据、动态链接库）。后面 2.3 会专门说这几样东西怎么漏。

前端项目还有个特殊之处：node_modules在构建期和运行期完全不是一回事。构建期需要完整的 devDependencies（webpack、vite、babel 都在里面），运行期如果只是用 nginx 托管静态文件，node_modules一个字节都不用带。这类项目的最优结构通常是"构建阶段用 Node，运行阶段用 nginx 或静态文件服务器"，最终镜像能压到几十兆。

2.2 跨架构构建里那几个自动注入的变量

在混合架构集群里构建镜像，--platform是绕不开的。BuildKit 在多平台构建时会自动注入一批构建参数，最常用的四个是BUILDPLATFORM、TARGETPLATFORM、TARGETOS、TARGETARCH。这些参数不需要你在 Dockerfile 里用ARG声明就能在RUN --mount和FROM --platform=里用，但如果要在RUN的命令字符串里引用，就必须显式声明。

Go 项目交叉编译的标准写法：

FROM --platform=$BUILDPLATFORM golang:1.22 AS builder ARG TARGETOS ARG TARGETARCH WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \ go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/app

这里FROM --platform=$BUILDPLATFORM是性能关键：构建阶段跑在构建机自己的架构上，不做模拟；只有产物按目标架构编译。如果不加这个参数，在 x86 机器上构建 arm 镜像时，整个构建阶段都会走指令模拟，速度能慢五到十倍，go mod download这种网络密集型步骤会慢得让人怀疑人生。

-trimpath和-ldflags="-s -w"这两个参数顺手提一下：前者去掉二进制里嵌入的本地绝对路径（既是体积优化，也避免泄露构建机的目录结构），后者去掉符号表和调试信息，通常能让二进制小 25% 左右。代价是出问题的时候没法用dlv直接调试，需要用带调试符号的版本单独构建。

2.3 从 builder 搬产物时最容易漏的三样东西

这是我见过最多的"本地能跑、容器起不来"来源。产物搬过去了，运行环境没搬全。

第一样是CA 证书。Go 的静态二进制本身不带根证书，如果你的程序要发 HTTPS 请求，运行镜像里又是个 scratch 或者极简基础镜像，那所有外发请求都会报x509: certificate signed by unknown authority。解决方式是从 builder 里拷，或者干脆用带证书的极小基础镜像：

COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

第二样是时区数据。容器默认是 UTC，代码里只要有一处用到本地时间格式化，日志时间就和业务方对不上。要么在运行阶段装tzdata并设TZ环境变量，要么从 builder 拷/usr/share/zoneinfo。我倾向于后者，因为运行镜像里装包管理器本身就是要极力避免的事。更省事的做法是代码里统一用 UTC 存、只在展示层转时区，但存量项目未必改得动。

第三样是动态链接库。CGO_ENABLED=1编译出来的 Go 二进制、以及绝大多数 C/C++ 程序，都依赖 glibc 或 musl。产物拷到 scratch 里直接报no such file or directory——注意这个报错很误导，它说的不是二进制不存在，而是它的解释器不存在。用ldd ./app看一眼依赖，要么补齐库，要么把CGO_ENABLED=0打开走纯静态。

提示：scratch是特殊的基础镜像，完全空白，没有 shell、没有ls、没有cat。出问题时你连进容器排查的手段都没有。除非你对产物的自包含性有绝对把握，否则用distroless系列的 static 或 base 镜像更稳妥，它至少带了证书和时区，也依然没有 shell。

3. BuildKit 的缓存机制：为什么你的第二次构建依然慢

3.1 缓存键是怎么算出来的

BuildKit 从 Docker 18.09 起就是默认构建引擎了（现在更是默认后端），但很多人对它的缓存模型还是一知半解，导致优化方向跑偏。

简单说，每个指令的缓存键由三部分组成：父层的摘要 + 指令本身的字符串 + 该指令引用的外部输入的校验和。对于RUN，外部输入通常只有命令字符串，所以只要命令一样、父层没变，缓存就命中——这就是为什么RUN apt-get update单独成行是危险的：命令字符串永远不变，缓存永远命中，你拿到的可能是三个月前的软件包索引。这是"apt 缓存陈旧"问题的根源，跟 BuildKit 没关系，是缓存语义的必然结果。

对于COPY，外部输入是被复制文件的校验和。所以COPY . .的缓存键包含整个上下文的指纹，任何一个文件变动都会让它失效。

还有一个常被误解的点：多阶段构建里未被最终镜像引用的阶段会被跳过。BuildKit 会分析依赖图，只构建最终需要的部分。你写了个测试阶段但最终镜像没引用它，日常构建根本不会执行——这是个好特性，但也意味着"我在构建阶段跑了测试所以镜像就安全了"这种想法是错的，测试压根没跑。

3.2 用 cache mount 把包管理器缓存挪出镜像层

RUN --mount=type=cache是我认为 BuildKit 带来的最有价值的能力，没有之一。它的作用是：给某条RUN指令挂一个持久化的目录，这个目录不进入镜像层，但在多次构建之间保留内容。

传统的包管理器缓存处理方式是"装完就删缓存目录"，因为缓存留在层里会让镜像变大。但删掉之后下次构建又得重新下载，在 CI 里就是每次构建都要从零拉一遍全部依赖。cache mount 把这两个问题一起解决了：

RUN --mount=type=cache,target=/root/.npm \ npm ci --omit=dev

RUN --mount=type=cache,target=/root/.cache/go-build \ --mount=type=cache,target=/go/pkg/mod \ go build -o /out/app ./cmd/app

RUN --mount=type=cache,target=/root/.cache/pip \ pip install --no-cache-dir -r requirements.txt

注意这里的组合：cache mount 提供了下载缓存，--no-cache-dir让 pip 不要往最终层里再写一份。这两个不矛盾，前者是构建期的加速，后者是控制镜像体积。

有个细节容易踩：cache mount 的默认共享范围是shared，多个并发构建会同时读写同一个缓存目录。绝大多数包管理器能扛住并发读写，但偶尔会出现索引文件损坏导致的奇怪报错。如果 CI 上并发度高，把sharing=locked加上更保险，代价是同一时刻只能有一个构建使用该缓存。另外id参数可以用来区分不同项目的缓存，避免互相干扰：

RUN --mount=type=cache,id=gomod-$(head -c8 go.sum | base64),target=/go/pkg/mod \ go mod download

3.3 CI 环境下的缓存复用与外置缓存后端

本地开发时 BuildKit 的缓存存在本地，用起来很爽。到了 CI 上就完全不是一回事：每次流水线跑在一个全新的 runner 上，本地缓存是空的，cache mount 也帮不上忙。

解决办法是把缓存外置。BuildKit 支持两种主要的导出方式：

registry 缓存是最通用的方案，配置起来大概是这样：

docker buildx build \ --cache-from type=registry,ref=registry.example.com/app:cache \ --cache-to type=registry,ref=registry.example.com/app:cache,mode=max \ --push -t registry.example.com/app:${GIT_SHA} .

mode=max这个参数值得单独说。默认的mode=min只导出最终镜像用到的层，中间阶段（比如 builder 阶段）的缓存不会导出。而多阶段构建的耗时大头恰恰在 builder 阶段，用mode=min等于只缓存了个寂寞。代价是mode=max的缓存体积可能达到镜像本身的几倍，如果仓库对存储成本敏感，需要权衡。

3.4 什么时候必须放弃缓存

缓存不是永远对的。有几种情况必须主动放弃或者让缓存失效：

基础镜像的安全补丁更新之后。你的FROM ubuntu:22.04这一行字符串没变，缓存键就没变，但仓库里的镜像内容已经更新了。这时候必须--pull或者显式--no-cache重建，否则你一直在用带漏洞的旧基础层。我的习惯是给 CI 的每日构建任务固定加--pull，日常提交构建不加，兼顾安全与速度。

依赖清单之外的隐式依赖变化。比如apt-get install的包版本、go get的间接依赖、npm 的 peer 依赖解析结果。这些在锁文件里体现不出来的变动，缓存是感知不到的。

排查"本地构建成功、CI 构建失败"这类幽灵问题时。第一件事永远是--no-cache重跑一遍，把变量降到最少。踩过几次之后我养成了一个习惯：出问题先关缓存，确认问题复现之后再去研究缓存策略，不要在带缓存的状态下做归因。

4. 不写 Dockerfile 的几条路线：Buildpacks、ko、apko 与无守护进程构建

4.1 Buildpacks 的适用边界

Buildpacks 的思路是：不写 Dockerfile，构建工具自己检测项目类型，自动决定基础镜像、依赖安装方式、启动命令。云原生 Buildpacks 是这条路线目前的标准化实现，输入一个源码目录，输出一个 OCI 镜像。

它的吸引力在于把镜像构建的责任从"每个服务自己写 Dockerfile"转移到"平台提供统一的构建器"。几十个服务如果都手写 Dockerfile，质量参差不齐是必然的；换成 buildpack，至少基础镜像、非 root 用户、SBOM 生成这些基线是统一的。对平台团队来说，这是治理层面的收益，而不只是省几行配置。

代价是可控性下降。你想在构建过程中跑一段自定义脚本、想用某个特殊的编译参数、想拷一个非常规的配置文件，都得通过 buildpack 提供的扩展点来做，比直接写RUN绕得多。我的经验判断是：项目同质化程度高、且团队里没人愿意维护 Dockerfile 的时候用 buildpacks；有特殊构建需求或者性能敏感的场景老老实实手写。

4.2 面向最小运行时的 apko 与 ko

这两个工具的思路又不一样，它们不是"替代 Dockerfile 的语法"，而是"绕过镜像分层构建这套流程"。

ko 专门服务 Go 项目。它直接读取go build的结果，按 OCI 规范拼装镜像，全程不需要 daemon，也不需要 Dockerfile。用法极简：

KO_DOCKER_REPO=registry.example.com/app ko build ./cmd/app

它默认生成的是基于 distroless static 的镜像，只有你的二进制加上必要的元数据，体积通常在十几兆。配合-P参数可以并行构建多个平台。对纯 Go 的服务，我现在的默认选择就是 ko，快且省心。

apko 走的是另一条路：用声明式的 YAML 描述镜像里要装哪些 apk 包，它直接根据包索引拼装文件系统并生成 OCI 镜像，不执行任何安装脚本。这带来的好处是构建结果可复现——同样的 YAML 在一定时间窗口内产出完全相同的镜像摘要，这对供应链审计很友好。同时因为不跑脚本，构建速度极快，通常是秒级。

contents: repositories: - https://packages.example.com/stable packages: - ca-certificates-bundle - tzdata - glibc entrypoint: command: /app/server

注意 apko 的包生态是 apk 体系的，你的运行时依赖得能在这个生态里找到。它适合构建"运行时底座"——把基础镜像这件事标准化下来，然后业务镜像在它之上追加产物。

4.3 流水线里没有 daemon 怎么办

传统docker build需要一个运行中的守护进程，这在 CI 里会带来两个麻烦：一是需要特权，安全上不好交代；二是构建环境的隔离性差，并发构建容易互相干扰（共享镜像缓存和网络栈）。

无守护进程的构建工具就是解决这个的。Kaniko 在容器内部执行 Dockerfile，逐条指令在用户空间展开文件系统变更，不需要 daemon 也不需要特权；Buildah 类似，但更偏向脚本化操作，支持buildah bud、buildah from、buildah run这一套命令式流程。

# Kaniko 在容器内的典型调用 /kaniko/executor \ --context=dir:///workspace \ --dockerfile=/workspace/Dockerfile \ --destination=registry.example.com/app:${GIT_SHA} \ --cache=true \ --cache-repo=registry.example.com/app/cache

有一个坑得提前说：Kaniko 的缓存机制和 BuildKit 不是一套，它用镜像层做缓存（所谓 cached layers），--cache-repo指向一个仓库路径专门存缓存层。这意味着RUN --mount=type=cache在 Kaniko 里是不生效的，如果 Dockerfile 依赖了 cache mount 做加速，迁到 Kaniko 之后会发现速度掉回来。选工具的时候要把 Dockerfile 里用到的特性一起考虑进去，不能只看工具本身的宣传指标。

4.4 一张对比表说清选型

选型没有绝对优劣，关键看你的约束条件是什么。如果约束是"CI 环境不能跑特权容器"，先排除 daemon 方案；如果约束是"几十个团队各写各的 Dockerfile 质量失控"，往 buildpacks 或者统一构建器走；如果约束是"Go 服务要快、镜像要小"，ko 基本是答案。

5. 镜像交付前后的账：权限、元数据与分发加速

5.1 运行身份收敛：USER 之后那些连带问题

默认情况下容器里的进程以 root 跑，这是历史遗留，也是安全基线检查里最常见的不合格项。改成非 root 只要一行USER 10001，但改完之后你会发现一堆东西跑不起来了。

第一个问题：文件权限。你在 root 身份下COPY进镜像的文件，属主是 root，切到 10001 之后可能连读都读不了。正确做法是在COPY时就用--chown指定属主，或者在构建末尾统一chown。注意--chown要在COPY指令里写，而不是事后再RUN chown -R，后者会多生成一个完整副本的层，镜像体积直接翻倍。

COPY --chown=10001:10001 --from=builder /out/app /app/server USER 10001

第二个问题：端口。Linux 上 1024 以下的端口需要特权，非 root 用户绑不了。如果你的服务写死了监听 80，改成非 root 之后直接启动失败。改端口号是正解，不要想着加CAP_NET_BIND_SERVICE绕过去——在容器里加 capability 比改一行配置风险大得多。

第三个问题：可写目录。非 root 用户往/var/log、/tmp这类路径写文件可能被拒。/tmp通常没问题（有 sticky bit），但如果应用要在某个固定路径下写临时文件，记得提前用mkdir+chown把目录准备好，或者干脆在 Kubernetes 里挂一个 emptyDir 到那个路径上。

配合非 root 用的还有只读根文件系统。把readOnlyRootFilesystem: true打开之后，任何试图往根文件系统写文件的行为都会失败——这个设置能拦下不少"应用偷偷在容器里落盘"的隐性问题，但也会把很多应用打挂。上线前的验证方法是：先在测试环境打开，跑一轮完整业务流，把所有写失败的位置找出来，该挂 emptyDir 的挂 emptyDir，该改配置的改配置。

5.2 SBOM、来源证明与签名

镜像里到底有什么，这个问题在前几年靠"看 Dockerfile"回答，现在越来越靠不住了——多阶段构建、buildpack、ko 这些方式生成的镜像，Dockerfile 根本不存在或者不完整描述最终内容。这时候需要的是SBOM（软件物料清单），它是一份列出镜像内所有软件包及版本的清单，格式常见的有 SPDX 和 CycloneDX。

生成 SBOM 现在基本是构建器内置的能力了：

docker buildx build \ --sbom=true \ --provenance=mode=max \ --push -t registry.example.com/app:${GIT_SHA} .

--provenance生成的是构建来源证明，记录这次构建用了什么源码、什么构建器、什么参数。mode=max会包含完整的构建步骤信息。这两样东西都以 OCI artifact 的形式附着在镜像旁边，不占镜像本身的体积，拉取镜像时也不会被下载下来。

签名则是另一层。构建完的镜像用私钥签一下，部署侧的准入控制器验证签名，能拦住"没经过正规流水线就被推到生产"的镜像。这套机制的门槛不在工具，而在密钥管理和验证策略的设计——私钥放哪、轮换周期多长、验证失败时是拒绝还是告警，这些是需要提前定好的组织决策，技术上反而简单。

我的实际经验是：SBOM 和签名的价值在出事的时候才体现，平时属于纯成本。所以推进节奏上，先做"生成 SBOM 并存档"，这一步几乎零风险；再做到"关键路径上的镜像验证签名"，这一步需要和发布流程配合；最后才是全面强制。一上来就全量强制的项目，通常在第二次紧急发版时就被绕过去了。

5.3 惰性加载与镜像分块分发

镜像体积压到极限之后，还有一个维度可以优化：拉取时间。一个 500M 的镜像，即使网络很好，从零拉完也要十几秒，加上解压落盘，节点上启动一个 Pod 的耗时里有一大半花在这。对于弹性伸缩场景，这个延迟直接影响扩容速度。

惰性加载的思路是：把镜像切成很多小块，按需拉取。应用启动时只需要读到的那些文件才去拉对应的小块，剩下的在后台慢慢拉或者干脆不拉。这种技术（用 eStargz 或类似的分块格式）对启动速度的提升在冷启动场景非常明显，尤其是那种"启动只加载主程序，大量静态资源后续按需访问"的服务。

实现上通常是在构建之后加一步格式转换，把标准镜像转成分块格式，推到仓库时带上特殊的分块索引。运行时的容器引擎只要能识别这个索引，就会自动走惰性加载路径。

代价是复杂度上去了：转换步骤增加了构建时长，仓库要支持分块格式的索引，节点侧要有对应的支持。所以我一般建议在扩容延迟已经构成业务问题的时候再上，而不是一开始就做。先把镜像体积从 1.2G 压到 200M，收益比上惰性加载大得多，成本还低。

6. 三份可直接抄的骨架与我的踩坑清单

6.1 Go、Node、Java 三种典型骨架

Go 服务的骨架，静态编译 + distroless：

FROM --platform=$BUILDPLATFORM golang:1.22 AS builder ARG TARGETOS TARGETARCH WORKDIR /src COPY go.mod go.sum ./ RUN --mount=type=cache,target=/go/pkg/mod go mod download COPY . . RUN --mount=type=cache,target=/go/pkg/mod \ --mount=type=cache,target=/root/.cache/go-build \ CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \ go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/app FROM distroless/static-debian12:nonroot COPY --from=builder /out/app /app/server USER 65532 ENTRYPOINT ["/app/server"]

Node 服务，依赖分层 + 非 root：

FROM node:20-alpine AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev FROM node:20-alpine WORKDIR /app ENV NODE_ENV=production COPY --from=deps --chown=node:node /app/node_modules ./node_modules COPY --chown=node:node . . USER node EXPOSE 3000 CMD ["node", "server.js"]

Java 服务，构建与运行分离：

FROM maven:3.9-eclipse-temurin-21 AS builder WORKDIR /src COPY pom.xml . RUN --mount=type=cache,target=/root/.m2 mvn -B dependency:go-offline COPY src ./src RUN --mount=type=cache,target=/root/.m2 mvn -B package -DskipTests FROM eclipse-temurin:21-jre-alpine RUN addgroup -S app && adduser -S -G app app WORKDIR /app COPY --from=builder --chown=app:app /src/target/*.jar app.jar USER app ENTRYPOINT ["java","-XX:MaxRAMPercentage=75.0","-jar","/app/app.jar"]

Java 这份里-XX:MaxRAMPercentage=75.0值得单独说。容器有内存限制，但 JVM 默认的堆大小是按宿主机物理内存算的，不设这个参数容易出现"容器被 OOMKill，JVM 却觉得自己内存很充裕"。设成 75% 是给堆外内存留空间，具体比例要根据应用特性调，压测一遍最靠谱。

6.2 几个真实踩过的坑

坑一：ARG传密钥。ARG NPM_TOKEN然后RUN npm config set //registry/:_authToken=$NPM_TOKEN，看着没问题，实际上这个 token 会被写进镜像的构建历史，docker history加上--no-trunc就能看到明文。哪怕后面删掉.npmrc也没用，历史层里还在。正确做法是用 secret mount：

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \ npm ci --omit=dev

构建时--secret id=npmrc,src=$HOME/.npmrc，密钥不会进入任何镜像层，也不会留在构建历史里。

坑二：docker history看体积不准。这是我自己误导过自己的地方。docker history显示的是每一层在未压缩状态下的增量大小，而且如果构建时用了--squash或者镜像来自不保留历史的构建方式，显示会完全失真。想准确定位体积分布，用专门的镜像分析工具做按文件、按目录的分解，能看到每个目录占多少、哪些文件其实是冗余的。我第一次用这类工具时的感受是"原来这三百兆是这么来的"，比盯着 Dockerfile 猜有效得多。

坑三：基础镜像 tag 漂移。用node:20和用node:20.11.1-alpine3.19，短期看不出区别，某天上游更新了 tag 指向的版本，你的构建结果就悄悄变了，而且缓存完全感知不到。生产环境的 Dockerfile 我现在的习惯是至少锁到次版本号，node:20.11这样，然后靠定期的依赖升级流程去主动更新，而不是让构建随机漂移。

坑四：HEALTHCHECK在 Kubernetes 里没用。在 Dockerfile 里写HEALTHCHECK对 docker run 场景有效，但 Kubernetes 完全忽略这个指令，它只看 Pod spec 里的livenessProbe/readinessProbe。所以我现在的做法是把健康检查写进 Helm chart 或者部署清单，Dockerfile 里不写，避免"以为有健康检查其实没有"的错觉。

坑五：构建上下文在.dockerignore之外的地方膨胀。有一次构建莫名其妙慢，查了半天发现是项目里有个logs/目录被本地调试脚本写了几万个文件，.dockerignore里没排除。这类问题的排查方法是把构建开头的上下文传输量打出来看，或者干脆在构建前du -sh一下项目根目录，心里有个数。

写了这么多，回到最开始那个三分半的项目：改完之后它其实也只用了本文里最朴素的三招——COPY顺序调整、多阶段只搬产物、npm ci --omit=dev。工具链再花哨，落到日常最常用的还是这几条。我的建议是先把这三招用熟，再去看 BuildKit 的 cache mount，最后再考虑 ko、apko、buildpacks 这些替代路线。顺序反了容易陷入"工具换了一堆，构建还是慢"的循环里——毕竟问题往往不在工具，在于那份四十行的 Dockerfile 里，有几行的顺序本来就是错的。