企业官网建设流程全解析

一个项目里构建出来的镜像莫名其妙从 180MB 涨到了 800MB，构建时长也跟着翻了三倍，第一反应都是去翻代码、翻依赖、翻构建脚本。结果翻了半天，最后发现问题出在 Dockerfile 的第一行——FROM被人从node:18-alpine改成了node:18，一个后缀的事。这事我遇到过不止一次，每次复盘都会把同一条结论重新确认一遍：FROM 指令决定了镜像的地基，后面所有指令都是在它上面叠砖，地基选错了，上面的砖砌得再漂亮也白搭。

这篇是 Dockerfile 系列的第一篇，专门聊FROM。看起来它就是一句话——指定基础镜像，实际上它牵扯的东西比想象中多：镜像从哪来、用什么标签、要不要锁摘要、多阶段构建怎么命名阶段、ARG写在哪里才能被它读到、跨架构构建怎么指定平台。这些细节单拎出来都不复杂，但组合在一起，构成了大量构建失败的根源。这篇适合刚开始写 Dockerfile 的朋友，也适合已经写了很久但一直在用同一个模板、没仔细想过为什么这么写的人。我会把语法、选型、多阶段、参数顺序、排错链路挨个拆开讲，尽量给出能直接抄的写法和判断依据。

1. 一次镜像体积暴涨的复盘：FROM 到底在构建流程里决定了什么

先把这个事故讲完整。那个项目是个前端 SSR 服务，原本的 Dockerfile 很标准：第一行FROM node:18-alpine，中间装依赖、编译、跑构建，最后再来一个阶段把产物拷进一个更小的运行时镜像。整套下来最终镜像 180MB 左右，构建大概两分钟。后来有人为了排查一个原生模块编译失败的问题，临时把基础镜像换成了完整版，问题解决之后这行改动没改回去，直接进了主干。

带来的连锁反应是四层叠加的：第一层，基础镜像本身从 40 多 MB 变成了 300 多 MB；第二层，完整版镜像里带的构建工具链让npm install的预编译二进制判断走了不同的分支，多装了一批本来用不上的包；第三层，镜像层数变多，缓存命中率下降，构建时间被拉长；第四层，CI 的镜像推送环节因为体积变大超时了两次，失败重试又把整体时长进一步拉高。表面上只是第一行动了几个字符，实际上改的是整个构建链的起点。

1.1 从 180MB 到 800MB：一次 tag 改动带来的连锁反应

把体积拆开看会更清楚。基础镜像贡献 40MB 变成 340MB，这是 300MB 的硬增量；依赖层因为编译工具链的差异多出 150MB 左右；构建缓存失效导致的临时层残留大概 100MB 上下；剩下的差异来自运行时阶段没有清理干净的中间文件。也就是说，FROM这一行的改动贡献了总增量的将近一半，但它是"乘数"性质的影响——它不是自己变大了就完了，它改变了后面每一层的构建结果。

这里有个很多人忽略的点：基础镜像决定的不只是体积，还包括系统库版本、包管理器、默认用户、shell 类型、时区数据库、CA 证书这些隐性的运行时环境。你换一个基础镜像，等于把这套环境整体换掉，而 Dockerfile 后面所有指令都是在跟这套环境打交道。所以在写FROM的时候，脑子里要有一个意识：我不是在选一个起点，我是在选一整套运行环境和工具链。

提示：改动FROM这行之后，务必重新跑一次完整的构建和镜像体积对比，不要只看构建是否成功。构建成功和镜像健康是两件事。

1.2 FROM 不只是"一行声明"，它锁定了后面所有层的起点

从技术实现上说，FROM做了这么几件事：确定本轮构建的父镜像、触发拉取（如果本地没有、或者带了强制拉取参数）、把父镜像的所有层作为新镜像的第一批层、给这个构建阶段起一个可以被后续引用的名字（如果写了AS）。这四个动作里，前三个是必须的，第四个是可选的但极其有用。

还有个容易被忽略的规则：FROM必须是 Dockerfile 里第一条有效指令。注释不算，空行不算，另外还有一个例外是ARG——这个例外后面会单独用一章讲，它是整篇里最容易踩坑的地方。如果你在一个 Dockerfile 里写了多条FROM，那么每条FROM都会开启一个新的构建阶段，默认情况下最终镜像取最后一个阶段的结果。这条规则是多阶段构建的地基，理解了它，后面所有的阶段引用、阶段继承、指定目标阶段构建才有落脚点。

对新手来说，最实用的判断标准是：如果你的 Dockerfile 只有一条FROM，那就老老实实把基础镜像选对、把标签钉住；如果你的 Dockerfile 里有多条FROM，那你要想清楚每一条的职责边界——哪一条负责编译，哪一条负责运行，它们之间只通过COPY --from传递产物，不要互相污染。

2. 拆开 FROM 的语法：镜像坐标、标签与阶段名各自管什么

完整形式大概是这样的：FROM [--platform=<平台>] <镜像名>[:<标签>|@<摘要>] [AS <阶段名>]。三块内容，一块是镜像坐标，一块是版本定位（标签或摘要二选一），一块是可选的阶段别名。前两块决定"从哪里开始"，第三块决定"这个阶段叫什么"，方便后面引用。

看起来很简单，但每一块都有坑。镜像坐标不写仓库前缀就会默认去公共仓库找，写错了前缀会去错误的地方找；标签不写会默认用latest，这是个几乎所有规范文档都会劝阻但依然遍地都是的写法；摘要写起来是一长串十六进制，没人会手敲，必须靠命令生成。下面逐块拆。

2.1 镜像坐标的三段式写法与几个高频笔误

镜像坐标的完整形式是[仓库地址/][命名空间/]镜像名。只写镜像名，比如FROM nginx，意思是去公共镜像仓库的官方命名空间找；写某组织/nginx，意思是去同一个仓库的某个组织命名空间找；带上仓库地址前缀，比如registry.internal.example:5000/base/nginx，就是去指定的私有仓库找。

高频笔误基本集中在三个地方。第一个是命名空间写错，把library/nginx写成nginx/nginx，报错信息是拉取失败，但实际原因是命名空间不存在。第二个是私有仓库地址少了端口或者少了协议之外的主机名部分，比如内网仓库跑在非标准端口上，地址里不带端口就会连到默认端口然后超时。第三个是大小写和连字符，镜像名规范要求小写，某些仓库对大小写敏感，写错了不一定立刻报错，可能拉到另一个名字相近的镜像，这种最麻烦。

注意：从私有仓库拉取需要提前完成认证，认证信息通常存在本地的配置文件里。CI 环境里这一步经常漏掉，表现是构建一开始就失败，报错里带认证相关的关键词。

另外提醒一个实际操作上的细节：如果你的基础镜像来自内网自建仓库，而 CI 机器和你的开发机走的是不同的网络路径，那么"本地能构建成功、CI 上拉不到"是很常见的现象。排查这类问题时，第一步永远是确认执行构建的那台机器能不能访问到那个仓库地址，而不是去怀疑 Dockerfile 写错了。

2.2 tag 与 digest：可复现性的分水岭

标签和摘要是同一个位置上的两种写法，但语义完全不同。标签是"可变指针"，alpine:3.19这个标签背后指向的实际镜像内容，会随着维护方推送新版本而改变；摘要是"内容指纹"，alpine@sha256:一长串指向的是唯一确定的一份内容，永远不会变。

这个区别在什么场景下要命？团队协作和线上发布的场景。你今天用node:18构建出一个镜像，测试通过，明天另一个同事重新构建，拉到的基础镜像可能已经更新过，系统库版本变了，行为就可能变，而你完全不知道问题出在哪。这类问题排查起来极其痛苦，因为两次构建用的 Dockerfile 一模一样，代码一模一样，结果不一样。

所以结论很明确：开发阶段用标签，方便跟进更新；发布阶段用摘要，保证可复现。摘要有两种写法都能接受，一种是直接写摘要（FROM nginx@sha256:...），另一种是标签加摘要（FROM nginx:1.25@sha256:...），后者可读性更好，建议用后者。

锁摘要的代价也必须说清楚：安全更新不会自动进来。基础镜像发布了修复漏洞的新版本，你的构建依然用旧的那份内容，直到有人主动去刷新摘要。所以这是个权衡，不是无脑锁死就完事了，需要配套一个定期刷新的机制——比如每周或每两周由流水线自动检查一次基础镜像是否有新摘要，有就提一个变更。

获取摘要的方法，最直接的是看本地已有镜像的信息：

docker inspect --format='{{index .RepoDigests 0}}' nginx:1.25

如果想在不拉取整个镜像的前提下查询远端仓库里的摘要和可用平台，用构建工具自带的多平台查询子命令会更方便：

docker buildx imagetools inspect nginx:1.25

这条命令会输出摘要信息和每个平台的清单，做跨架构选型的时候很有用。

2.3 --platform 参数在多架构环境里的实际作用

--platform是近几年用得越来越多的参数，原因是开发机普遍是 ARM 架构，而服务器多数还是 x86。默认情况下构建会使用当前机器的架构，于是就会出现"本地构建的镜像推到服务器上跑不起来"的经典问题，报错信息大致是找不到匹配的平台清单。

写法的格式是操作系统/架构[/变体]，常见的几个值：linux/amd64、linux/arm64、linux/arm/v7。有两种写法：一种是硬编码，比如FROM --platform=linux/amd64 nginx:1.25，适合明确知道目标环境的场景；另一种是用变量，配合构建工具预定义的平台参数，在跨架构构建时自动取到正确的值。

# 硬编码目标平台，适合单一目标环境 FROM --platform=linux/amd64 nginx:1.25 AS runtime # 用变量取构建机平台，适合编译阶段使用本机原生性能 FROM --platform=$BUILDPLATFORM golang:1.22 AS builder # 用变量取目标平台，适合最终运行时镜像 FROM --platform=$TARGETPLATFORM debian:bookworm-slim AS runtime

这里有个很实用的组合思路：编译阶段用构建机自身平台，这样编译器跑的是本机原生指令，速度快；产物阶段用目标平台，保证最终镜像能跑在目标服务器上。交叉编译的场景下这个组合几乎是标配，也是多阶段构建在跨架构场景里最有价值的地方之一。

提示：使用平台变量参数需要构建工具的多平台构建能力支持，老版本的构建引擎可能不认这些变量，会原样当成字符串处理然后报错。

3. 基础镜像选型的真实权衡：几类常见底座怎么选

选基础镜像这件事，没有"最优解"，只有"在你的约束下最合适的解"。约束无非是几项：体积、启动速度、安全面、生态兼容性、维护成本。这几项之间天然互相拉扯，比如体积小的往往牺牲了兼容性，兼容性好的往往体积大。

我一般的判断顺序是：先看运行时依赖（有没有原生扩展、有没有动态链接库需求），再看体积要求（镜像分发频率高不高、节点多不多），再看安全合规要求（有没有扫描漏洞的要求、能不能接受镜像里有 shell），最后看团队熟悉度。按这个顺序走下来，基本八九不离十。下面把几类常见底座的特点拆开讲。

3.1 scratch 不是"零依赖"，而是"零内容"

scratch是 Dockerfile 里的一个特殊关键字，代表一个完全空的镜像，没有文件系统、没有 shell、没有包管理器、没有任何库。它适合的场景很明确：你的程序是完全静态链接的单个二进制文件，运行时不需要任何外部依赖。

Go 和 Rust 这类语言很容易做出这样的二进制，所以FROM scratch在它们的项目里很常见。但这里有个几乎所有人第一次都会踩的坑：空镜像里没有 CA 证书。程序启动后第一个 HTTPS 请求就会失败，报错信息是找不到受信任的证书。你盯着代码看半天也想不明白，因为本地跑得好好的。解决办法是从构建阶段把证书文件拷过来：

FROM golang:1.22 AS builder WORKDIR /src COPY . . RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/app FROM scratch COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo COPY --from=builder /out/app /app ENTRYPOINT ["/app"]

除了证书，时区数据库也经常漏。程序里如果用了本地时区（time.Local），空镜像里没有时区文件，取到的会是 UTC。这个问题更隐蔽，因为程序不报错，只是时间差了几个小时，日志里看出来的时候已经过去很久了。另外如果你的程序是动态链接的，空镜像里没有动态链接器，运行时直接报找不到解释器，这种情况要么改成静态编译，要么换一个不空的基础镜像。

3.2 alpine 的体积红利，和 musl 带来的隐形成本

alpine大概是使用率最高的轻量基础镜像，几十 MB 的体积对绝大多数场景都很友好，包管理器也在，装东西方便。但它的"轻"是有代价的，代价来自它用的 C 标准库实现和主流发行版不一样。

最直接的影响是原生扩展的兼容性。某些依赖原生扩展的包，在主流发行版上有预编译好的二进制可以直接下载，在 alpine 上没有对应的预编译版本，需要从源码编译，于是你就得在镜像里装上编译工具链，装完之后镜像反而比用完整版还大。这类问题在前端和 Python 项目里特别常见，表现出来是npm install或pip install阶段突然要编译某个包，然后报缺少头文件或者编译器。

第二个影响是 DNS 解析行为的细微差异，正常的 HTTP 调用一般感知不到，但在某些特殊网络配置下会出现解析慢或者解析结果不一致的现象。这个问题不常遇到，遇到一次能查很久。

第三个影响是调试体验。alpine 默认用的是精简版工具集，很多常用命令的参数和行为跟 GNU 版本不一样，你写好的排查脚本搬过去可能跑不通。

我的实际选择策略是这样的：如果项目里有原生扩展依赖、或者需要频繁进入容器排查问题、或者团队对这套环境不熟，那就别用 alpine，用精简版的常规发行版镜像，体积大一点但省心；如果是纯脚本类服务、静态资源服务、不需要编译任何东西的场景，alpine 是非常好的选择。

3.3 几类常见基础镜像的横向对照

把常见的几类放在一起对比，选型的时候可以对着表快速筛一遍。下表里的体积是数量级参考，具体数值随版本变化，不要当精确值用。

还有一类是无发行版的最小运行时镜像，理念是把运行程序需要的最小文件集合打包，不带 shell 和包管理器，安全面很小，体积也小。它适合已经跑通、不需要进容器调试的生产服务；代价是出问题时你只能靠日志，进不去容器里翻文件，所以一般需要配合一个同版本的调试用镜像做排查。

提示：选型不要只看最终镜像体积，还要看构建阶段的镜像体积。构建阶段可以用大而全的镜像，反正它不进最终产物，这个自由度是白送的。

4. FROM ... AS 与多阶段构建：把编译环境和运行环境彻底分开

多阶段构建是FROM这个指令最有价值的能力延展。核心思路很简单：同一个 Dockerfile 里写多个FROM，前面的阶段负责"把东西做出来"，后面的阶段负责"把东西跑起来"，中间通过COPY --from传递产物。这样构建工具链、源码、测试依赖全都留在前面的阶段，最终镜像只包含运行需要的东西。

这个模式解决的痛点是长期存在的：单阶段构建要么镜像里塞满构建工具（体积大、攻击面大），要么在同一个阶段里装完再删（层还是留着，删不掉）。多阶段构建从根上解决了这个问题，因为不同阶段之间是彼此独立的层，前一阶段的层根本不会进入最终镜像。

4.1 为什么要把编译环境和运行环境切成两个阶段

拿一个典型的编译型项目举例。编译需要编译器、构建工具、开发头文件、源代码，这些东西加起来可能几个 GB；运行只需要一个可执行文件和少量的运行时库，几十 MB。如果放在一个阶段里，最终镜像要么臃肿，要么你用一堆删除命令试图清理，但因为分层机制，删除只是加了一个"白障"层，实际存储空间并没有释放。

拆成两个阶段之后，构建阶段的镜像只在构建过程中存在，不进产物；运行阶段从一个干净的小镜像开始，只拷进来编译好的产物。这样最终镜像的体积就是"小基础镜像 + 产物"的量级，通常是原来单阶段方案的十分之一到五分之一。

还有一个额外好处是缓存效率。源代码变动频繁，依赖安装变动少，如果把依赖安装放在前面的阶段，产物拷贝放在后面的阶段，那么改代码时只需要重新执行后面阶段的拷贝和打包，前面装依赖的阶段能吃到缓存。这个优化在大型项目上的收益非常明显，能把构建时间从十几分钟压到一两分钟。

# 阶段一：构建，用大而全的镜像，不关心体积 FROM node:20-bookworm AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build # 阶段二：运行，用精简镜像，只装运行时必需 FROM node:20-bookworm-slim AS runtime WORKDIR /app ENV NODE_ENV=production COPY --from=builder /app/dist ./dist COPY --from=builder /app/node_modules ./node_modules COPY --from=builder /app/package.json ./ USER node CMD ["node", "dist/server.js"]

4.2 阶段引用的三种写法与典型引用错误

引用一个阶段有三种写法，各有各的适用场景。第一种按序号引用，COPY --from=0，序号从 0 开始按FROM出现的顺序递增。这种写法最脆弱，中间插一个阶段或者调整顺序就全错了，我不推荐在正式项目里用，只在快速试验的时候图省事。

第二种按阶段名引用，COPY --from=builder，这是最推荐的方式，可读性好、不受顺序影响。要求是阶段必须写了AS 名字，名字大小写敏感，写错了会报错说找不到这个阶段。

第三种是直接引用一个外部镜像，COPY --from=nginx:1.25 /etc/nginx/nginx.conf /etc/nginx/nginx.conf。这个用法知道的人不多但非常实用，比如你想从官方镜像里拿一份默认配置文件，或者从某个镜像里拷贝前端静态产物，不用自己构建这个镜像，直接按坐标拷就行。注意这种写法会触发镜像拉取，拉取失败的表现跟FROM拉取失败是一样的。

典型的引用错误有三种。第一种是名字拼错或者大小写不一致，报错信息比较直白，提示找不到指定阶段。第二种是引用了后面才定义的阶段，顺序反了，这种报错也一样是找不到阶段，但原因不同，容易看懵。第三种是引用了一个已经被"覆盖"的名字——如果你在同一个 Dockerfile 里给两个不同阶段用了同一个名字，后面那个会覆盖前面那个，COPY --from拿到的可能不是你预期的那个。

第三种情况要特别小心，因为它在构建时不报错，产物看起来也正常，只是内容不对。我曾经见过一个项目因为复制粘贴导致两个阶段同名，构建出来的镜像缺了几个静态文件，线上页面白屏，查了两个小时才发现问题在阶段命名上。

4.3 COPY --from 之后仍然容易漏掉的三类文件

多阶段构建最常见的翻车点不是语法，而是"漏拷"。编译阶段跑得好好的，运行阶段一启动就报错，报错信息五花八门，根因基本都是少拷了东西。我总结下来有三类最容易被漏。

第一类是运行时依赖。编译阶段装了一堆依赖，你会下意识觉得"运行时也需要"，但具体需要哪些、放在哪个路径，经常搞不清。稳妥的做法是先在运行阶段启动一次，看报错里缺什么补什么；或者用一个能列出动态链接依赖的工具，把可执行文件依赖的库列出来，逐个确认目标镜像里有没有。

第二类是证书和时区文件，前面讲空镜像的时候提过。只要运行阶段的基础镜像足够精简，这两样就都得主动确认一遍。判断方法很简单：在容器里跑一次 HTTPS 请求，再打印一次本地时间，两个都对就说明没问题。

第三类是配置文件和启动脚本。编译阶段生成的产物目录里往往不含这些，它们在仓库根目录或者单独的目录里，需要单独拷。这类文件漏了的表现是容器启动就退出，日志里通常有一句很明确的"找不到某某文件"，但前提是你得去看日志——很多人习惯性地只看构建日志，不看容器启动日志，然后在构建成功的假象里打转。

提示：COPY --from支持通配符和目录，但通配符匹配不到任何文件时会直接失败，反而能帮你提前发现问题是漏拷。如果你把这种拷贝写成了COPY --from=builder /app/dist* ./这类宽松形式，漏拷就不会报错，等到运行才暴露。

5. ARG 写在 FROM 之前还是之后：一个位置决定成败的语法细节

ARG和FROM的配合是这份语法里最反直觉的地方。很多人为了把基础镜像的标签做成可配置的，会在 Dockerfile 里写一个ARG，然后在FROM里引用它，结果发现取不到值，构建出来的是一个字面量的字符串或者空值。

原因在于作用域的设计。ARG声明在FROM之前，它属于"构建开始之前"的那一层作用域，只能被FROM这一行使用；一旦进入某个构建阶段，这个ARG就失效了，要在阶段内重新声明一次才能用。反过来，声明在FROM之后的ARG，在FROM那一行是完全不可见的。这个规则的出发点是让每个阶段的依赖关系清晰可追溯，但对写的人不太友好。

5.1 作用域规则：FROM 里为什么取不到后面的 ARG

举个具体的例子说明。下面这种写法是错的，BASE_TAG在FROM那一行取不到，会被当成空值，于是镜像坐标变成了node:，直接报错。

# 错误示例：ARG 声明在 FROM 之后，FROM 里取不到 FROM node:${BASE_TAG} ARG BASE_TAG=20-slim

正确写法是把ARG提到FROM前面：

# 正确示例：ARG 在 FROM 之前声明 ARG BASE_TAG=20-slim FROM node:${BASE_TAG}

但这里还有第二层坑：这个ARG虽然能在FROM里用了，进到阶段内部它又失效了。如果阶段里还需要用它（比如在标签里打版本号、在某个命令里引用），必须在阶段内再声明一次：

ARG BASE_TAG=20-slim FROM node:${BASE_TAG} # 阶段内重新声明，才能在这个阶段里使用 ARG BASE_TAG RUN echo "built on node ${BASE_TAG}" > /build-info.txt

这种"声明两次"的写法看起来啰嗦，但它是有意为之的：第一次声明是给FROM用的，第二次声明是给阶段内用的，两次声明同一个名字，作用域不同。理解了这一点，就不会再困惑"为什么我明明声明了却用不了"。

还有个小细节值得注意：FROM里能引用的变量范围很窄，只限于FROM之前声明的ARG，以及构建工具预定义的那批平台相关参数。构建阶段里通过ENV设置的环境变量，FROM那一行同样取不到。这点经常被混淆，因为ENV和ARG在阶段内的行为确实有点像。

5.2 一份可以直接抄的模板与自检清单

把上面这些规则拼起来，一份比较稳妥的写法长这样：

# 全局参数集中在这里，只用于 FROM 行 ARG BASE_REGISTRY=registry.internal.example:5000 ARG BASE_IMAGE=base/runtime ARG BASE_TAG=1.4.2 ARG BASE_DIGEST=sha256:0000000000000000000000000000000000000000000000000000000000000000 # 构建阶段：大而全的镜像，可跟进最新的构建工具 FROM ${BASE_REGISTRY}/base/builder:1.4.2 AS builder WORKDIR /src COPY . . RUN ./build.sh # 运行阶段：锁摘要，保证可复现 FROM ${BASE_REGISTRY}/${BASE_IMAGE}:${BASE_TAG}@${BASE_DIGEST} AS runtime # 阶段内需要用到的参数，重新声明 ARG BASE_TAG LABEL base.tag="${BASE_TAG}" COPY --from=builder /src/out/app /usr/local/bin/app USER 10001 ENTRYPOINT ["/usr/local/bin/app"]

配套的自检清单，我每次写新 Dockerfile 都会过一遍：

• FROM前面有没有多余的、不属于参数声明的指令？除了ARG和注释，别的都不该出现。
• 阶段内用到的ARG，有没有在阶段内重新声明？
• 基础镜像的标签是不是明确指定的？有没有意外依赖默认标签？
• 发布用的阶段，摘要有没有锁？
• 多阶段之间的阶段名有没有重复？
• 排序靠后的阶段引用了靠前的阶段，顺序对不对？
• 如果用了平台参数，构建工具版本支不支持？

这几条过一遍，能避免掉日常构建里八成的FROM相关问题。清单本身不复杂，难的是养成习惯，因为这些问题大多在出错之前毫无征兆。

6. FROM 出问题时的排查链路：从报错表象走到根因

构建失败的时候，报错信息往往指向的不是根因，而是根因的下游表现。比如"找不到某个文件"，实际可能是基础镜像换版本之后路径变了；比如"拉取失败"，实际可能是网络不通、认证过期、镜像真的不存在这三种完全不同的原因。所以排查的核心是分层：先确认是哪一类问题，再往下钻。

我在实际排这类问题时，习惯按"从外到内"的顺序走：先确认能不能访问仓库，再确认镜像坐标对不对，再确认版本和摘要存不存在，再确认平台匹配不匹配，最后才去看 Dockerfile 里的语法问题。这个顺序的依据是，外层问题的发生概率远高于内层，先查外层的成本更低。

6.1 三类高频报错的特征对比

把高频报错归成三类，特征差别还挺明显的，对照着看能省不少时间。

第三类报错值得单独说一句。现在很多镜像都提供多架构版本，但并不是所有标签都有。某些小众的镜像或者较早的版本可能只有单一架构，你在 ARM 机器上构建就会失败。遇到这种情况，要么换一个有对应架构的版本，要么用平台参数指定一个存在的架构，但后者要承担模拟执行的性能代价。

摘要不匹配这种情况也有点反直觉：摘要本身是内容指纹，理论上不会"错"，报这个错通常意味着这个摘要对应的内容在仓库里已经不存在了（比如被清理掉了），或者你在复制摘要的时候漏了字符。后者非常常见，摘要是六十四位十六进制，手动复制时漏一位的情况我见过好几次。

6.2 按顺序验证下去的命令清单

下面这套命令我基本是条件反射地用，顺序也可以照着来。第一步，先确认基础镜像本身能不能单独拉下来：

docker pull registry.internal.example:5000/base/runtime:1.4.2

这一步能区分问题在"拉取"还是在"构建"。如果拉取就失败，那后面都不用看了，先解决拉取问题。第二步，如果拉取成功但构建失败，检查镜像里的实际内容是否符合预期：

docker run --rm -it registry.internal.example:5000/base/runtime:1.4.2 sh

进去看看路径、证书、时区文件在不在，能快速验证COPY --from漏拷这类问题。第三步，确认多平台清单：

docker buildx imagetools inspect registry.internal.example:5000/base/runtime:1.4.2

这一步能一次性看到摘要、平台、每一层的摘要，前面提到的平台不匹配和摘要核对都能在这里解决。第四步，如果怀疑是缓存导致的"本地能行、干净环境不行"，强制重新拉取基础镜像再构建一次：

docker build --pull --no-cache -t myapp:test .

--pull会强制检查远端有没有更新，--no-cache会让所有层重新执行。这两个参数一起用的代价是慢，但能排除掉绝大多数"环境不一致"的干扰项。我一般在确认是环境问题的阶段才用，平时构建不带上。

第五步，如果构建成功但运行失败，去看容器日志而不是构建日志，这一步很多人会忘：

docker run --rm myapp:test

运行时报的错和构建时报的错是两套完全不同的信息源，混着看只会浪费时间。

7. 我在项目里沉淀下来的 FROM 书写习惯

写到最后，分享几条我在多个项目里反复验证过、现在基本固化成习惯的做法，都是踩过坑之后留下来的。

第一条，基础镜像的标签永远不用默认值。哪怕只是自己本地玩，也明确写上版本，因为"默认"这两个字在构建环境里意味着"随时可能变"。第二条，发布用的阶段一律锁摘要，并且把刷新摘要这件事放进流水线的定期任务里，不让它靠人的记性。摘要和标签同时写，可读性和可复现性都拿到。第三条，多阶段构建里给每个阶段都起名字，哪怕某个阶段当下没人引用，起名字的成本几乎为零，未来引用的时候省事，也避免了按序号引用带来的脆弱性。

第四条，构建阶段和运行阶段的基础镜像分开选。构建阶段怎么方便怎么来，大而全没关系，反正不进产物；运行阶段则严格按最小必要原则选，能不装的一律不装。这个思路在很多项目里能直接把最终镜像体积砍掉一大截，而且不牺牲构建体验。第五条，如果团队规模超过两三个人，把常用的基础镜像和阶段模板抽成一个统一的起始文件，所有项目从同一个起点开始写。不是为了强制统一，是为了让"证书要拷、时区要拷、摘要要锁"这些容易忘的事只写一次。

第六条也是我觉得最实在的一条：改FROM这一行的时候，把它当成一次有风险的变更来处理，跟改业务代码一个待遇。改完跑一次完整构建、对比镜像体积、确认运行时行为没变，再合进去。我见过太多次"就改一行应该没事"，然后花了半天定位问题的情况。这行确实是整个 Dockerfile 里最值得谨慎对待的一行，因为它是地基。

这个系列后面还会继续拆其他指令，RUN的层合并与缓存、COPY与ADD的边界、ENTRYPOINT与CMD的配合，每一个都有类似的坑。有兴趣的可以顺着往下看。