企业官网建设流程全解析

1. 为什么你需要认真看这篇多阶段构建指南

先说结论：如果你还在用那种“一个 Dockerfile 从头写到尾”的方式打包应用，你构建出来的镜像体积很可能是最终方案的 5 到 10 倍，而且里面还塞满了一堆运行时根本不需要的编译工具和中间文件。

我最早接触 Docker 多阶段构建，是被一个线上事故逼的。那时候团队里有个 Java 服务，基础镜像用的是带 JDK 的完整版本，每次构建出来的镜像接近 1.2 GB。推送私有仓库慢，拉取也慢，测试环境磁盘三天两头报警。最离谱的是，后来安全扫描报告出来，镜像里因为包含了完整的 gcc、make 等编译链，直接拉高了好几个高危漏洞的评分。后来我们花了两个晚上把所有服务的 Dockerfile 全改成多阶段构建，镜像从 1.2 GB 直接压到 150 MB 出头，构建时间还缩短了将近一半。

这个案例不是我编的，是当时实实在在踩过坑之后总结出来的。所以你完全可以相信，多阶段构建不是“锦上添花”的优化技巧，而是 Docker 镜像交付里一个绕不开的核心实践。

这篇指南不会给你堆概念。我会从多阶段构建的底层逻辑讲起，然后拆解两个不同语言项目的完整实操案例，再把你实际运行中最容易踩的坑和排查方法全部列出来。不管你是刚接触 Docker 的新手，还是已经在用但经常被镜像体积问题的老手，这篇内容都能给你一些可以立刻上手的参考。

2. 多阶段构建到底解决了什么问题

2.1 传统构建方式的三个痛点，你大概率都遇到过

先说最传统的 Dockerfile 写法。那时候大家刚接触 Docker，思路很直接：装环境、拉依赖、拷代码、跑编译，所有步骤全写在一个 Dockerfile 里，最后产出的镜像既能构建又能运行。听着好像没什么问题，但实际用起来你会碰到三个非常现实的情况。

第一，镜像体积失控。构建一个 Go 项目，你需要在镜像里装 Go 工具链；构建一个 Java 项目，你得装完整 JDK；构建前端项目，你得装 Node.js 和 npm。但这只是第一步，真正可怕的是安装依赖这一步，npm 的 node_modules 动辄几百兆，Maven 的 .m2 仓库更是能把镜像撑得没法看。这些依赖是构建期需要，运行期完全用不上，却被原封不动地打进了最终的镜像里。

第二，构建工具链暴露在运行环境里。这不仅是安全问题，更是个“卫生问题”。你想想，运行阶段本来只需要一个精简的 JRE 或者可以直接执行的二进制文件，但因为构建和运行共用一个镜像，所有编译工具、头文件、开发库全都暴露在运行环境里。一旦镜像被拉取到你无法完全掌控的服务器上，这些多余的组件就从“体积问题”升级成了“安全风险”。

第三，构建环境不一致。你开发机上的环境跟 CI 机器、生产机器很可能不一样。今天你在自己电脑上构建没问题，明天换台机器，同样的代码就编译不过去。因为你依赖了宿主机器上的某些隐式工具或库，而 Dockerfile 里并没有完整记录这些依赖。

2.2 多阶段构建的核心理念：把构建和运行彻底拆开

多阶段构建的思路可以用一句话说清楚：一个 Dockerfile 里写多个 FROM，前面的阶段用来构建，最后一个阶段用来运行，中间阶段产生的所有文件，你想拿多少进最终镜像就拿多少。

这句话背后其实在做一件事：隔离与选择性继承。构建阶段用的环境可以极其复杂，装多少工具都不心疼，因为那些阶段生成的中间层不会出现在最终的镜像里。只有你显式通过COPY --from=某个阶段拷贝的那些文件，才会进入运行阶段。

打个比方你就明白了。这就像你在厨房里做菜，备菜区可以摆满各种刀具、砧板、调味料，但端上桌的永远只有那一盘成品菜。你不会把整张厨房操作台搬到餐桌上，对吧？多阶段构建就是帮你把“备菜区”和“餐桌”彻底分开的机制。

传统单阶段构建是“一把菜刀从头用到尾”，多阶段则是“备菜台归备菜台，餐桌归餐桌”。这个分离带来的直接收益有三点：镜像体积大幅缩小、运行环境精简、构建缓存利用率更高。

2.3 一个“生活类比”帮你快速理解 FROM ... AS 的关系

AS关键字是多阶段构建里最重要的语法点。它给阶段起了一个别名，后面的阶段可以通过COPY --from=别名从指定阶段拷贝文件，也可以通过FROM 别名继承上一个阶段的基座。

注意，这两种方式有本质区别：

• COPY --from=是“拿文件”，只把需要的产物拷贝过来，不继承构建阶段的环境。
• FROM 上一个阶段名是“继承环境”，如果你在多个阶段里都需要同样的工具链，可以直接基于上一个阶段继续往下写，不用重新拉基础镜像。

第二种方式特别适合处理那种需要多步编译的场景，比如你从源码编译 OpenSSL，再编译 Nginx，每一步都在上一个阶段的基础上进行，最终只把编译好的二进制文件拷贝进最后的运行阶段。

理解了这个区别，你再看其他 Dockerfile 就会有一种“通透”的感觉。很多人看网上现成的多阶段构建配置，觉得代码背下来就行，其实不然。你得先理解阶段之间的关系，才能真正根据自己项目的需求调整。

3. 多阶段构建的语法拆解与工具选型解析

3.1 基础语法：FROM、COPY --from、AS 的关键点

先看一段最基础的多阶段构建 Dockerfile，用 Go 项目举例：

# 第一阶段：构建阶段 FROM golang:1.21-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -o myapp . # 第二阶段：运行阶段 FROM alpine:3.19 RUN apk add --no-cache ca-certificates WORKDIR /root/ COPY --from=builder /app/myapp . EXPOSE 8080 ENTRYPOINT ["./myapp"]

拆开看几个关键点：

第一，FROM golang:1.21-alpine AS builder给构建阶段起了个名字叫builder。这个名字在后面的COPY --from=builder里被引用。注意，阶段名只在当前 Dockerfile 内部有效，不要想着跨 Dockerfile 引用，不同项目之间没有这个能力。

第二，COPY --from=builder /app/myapp .是把 builder 阶段里编译好的二进制文件拷到运行阶段。这里有个很多人忽略的细节：--from可以不止指向同一个 Dockerfile 里的阶段名，它也可以指向一个完整的镜像名。比如COPY --from=nginx:1.25-alpine /usr/share/nginx/html /usr/share/nginx/html。这个特性常用来做静态资源提取，后面实操部分我会专门演示。

第三，RUN apk add --no-cache ca-certificates是为了让运行阶段可以信任 HTTPS 证书。Go 编译出来的静态二进制默认不携带系统证书，如果你的程序要发起 HTTPS 请求，不加这行后面绝对踩坑。这类“构建期不会暴露、运行期必炸”的问题，我强烈建议你在写 Dockerfile 的时候就考虑到，别等部署了才知道。

3.2 每个阶段可以单独指定基础镜像版本

多阶段构建还有一个容易被忽略的好处：基础镜像可以按阶段灵活指定。

比如构建阶段需要完整的编译工具链，你就用golang:1.21-alpine、maven:3.9-eclipse-temurin-17这种带工具链的镜像；运行阶段只需要一个最小化的运行环境，你就可以用alpine、eclipse-temurin:17-jre-alpine或者干脆用scratch。两者的版本可以完全不一致，Docker 不会要求你保持统一。

这个灵活性带来的实际价值是“构建期要全，运行期要精”。我在实际项目中见过一个典型的反面教材：有人把构建阶段的完整 JDK 环境带进了运行阶段，就因为他在两个阶段用了同一个带 JDK 的基础镜像。明明可以只COPY --from把 jar 包拷过来，偏要图省事继承整个环境，结果镜像体积白白多了 300 多 MB。

所以我给你一个经过验证的选型原则：

• 构建阶段：优先选包含完整工具链的官方镜像，比如golang、maven、node，不需要过度精简。
• 运行阶段：优先选不含包管理器和多余 shell 的极简镜像，比如alpine、distroless、scratch。

其中scratch是一个特殊的保留镜像，它表示“空镜像”，一个文件都没有。如果你的程序是静态编译的（如 Go、Rust），可以直接把二进制扔进去跑。scratch镜像跑起来的容器，体积可能只有 10 MB 出头，安全扫描报告几乎是全绿的。

3.3 选择合适的基础镜像，对镜像体积的影响有多大

基础镜像的选择对最终结果影响非常大。你看下面这个实测对照，前提是用多阶段构建的方式，但运行阶段选择不同镜像：

同样的程序，因为基础镜像不同，体积差了 6 到 7 倍。这里我补充说一句：alpine和scratch的区别不仅仅是体积，还关系到动态链接与静态链接的问题。如果你的程序是动态链接的，比如依赖了 glibc 或者某个动态库，直接扔进scratch镜像里跑会报错。这也是为什么很多 Go 项目的 Dockerfile 要在构建阶段特意设置CGO_ENABLED=0，目的就是强制走静态链接，让最终二进制不依赖任何系统动态库，可以放心放进scratch或者alpine。

4. 实操案例一：Java 服务从 1.2 GB 压到 150 MB

4.1 项目背景与 Dockerfile 重构前的状态

我先拿一个真实项目做演示。这是个基于 Spring Boot 的微服务，用的 Java 17 和 Maven 构建。重构前 Dockerfile 写得很“传统”，核心逻辑是这样的：

FROM maven:3.9-eclipse-temurin-17 WORKDIR /app COPY . . RUN mvn clean package -DskipTests EXPOSE 8080 CMD ["java", "-jar", "target/my-service.jar"]

这个 Dockerfile 构建出来的镜像会有多大？给你几个参考数据：

• maven 基础镜像本身就有大约 600 到 700 MB，因为里面包含完整 JDK、Maven 和一堆系统工具。
• Maven 在构建过程中会把所有依赖下载到本地仓库，这些依赖在镜像的中间层里，加起来又是三四百 MB。
• 最终镜像里不仅包含target/my-service.jar，还包含项目的源码、没有清理的.m2仓库、一堆构建临时文件。

实际构建出来，这个镜像的体积在 1.2 GB 左右。每次推到私有仓库都要等很久，开发环境拉取也很痛苦。更要命的是，这个镜像里藏着完整 JDK 和构建工具，一旦泄露或者被拉取到非受控环境，攻击面会大很多。

4.2 重构后的多阶段 Dockerfile 与关键命令解析

我们重构后的 Dockerfile 长这样：

# 阶段一：Maven 构建 FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /app # 先拷贝 pom.xml，利用 Docker 层缓存 COPY pom.xml . RUN mvn dependency:go-offline -B # 再拷贝源码并打包 COPY src ./src RUN mvn clean package -DskipTests # 阶段二：最小运行环境 FROM eclipse-temurin:17-jre-alpine RUN addgroup -S spring && adduser -S spring -G spring USER spring:spring WORKDIR /app COPY --from=builder /app/target/my-service.jar app.jar EXPOSE 8080 ENTRYPOINT ["java", "-jar", "app.jar"]

重构后的几个关键动作，我给你逐个拆解：

第一，COPY pom.xml .和RUN mvn dependency:go-offline -B这两行的组合，核心作用是构建缓存优化。Maven 构建最耗时的步骤是下载依赖。如果你把 pom.xml 单独拷贝进去、先执行一次依赖下载，那么只要 pom.xml 不变化，后续构建就会直接命中这一层的缓存，哪怕你的源码改了，也不会重新下载依赖。我们实际用下来，增量构建的速度大概能快 40% 到 50%。这个操作很值得你在所有 Java 项目里推广。

第二，运行阶段用的是eclipse-temurin:17-jre-alpine。注意这里刻意选择了 JRE 而不是 JDK。Java 程序运行时只需要 JRE，不需要编译器和其他开发工具。这一条降下来的体积非常明显，JDK 基础镜像 300 多 MB，JRE-alpine 版本大约 70 多 MB。

第三，addgroup和adduser创建了一个非 root 用户，并用USER spring:spring切换。这是一个安全实践：容器内用非 root 用户运行，能限制容器被攻破后攻击者获得的权限。很多人在本地跑没问题，到了生产环境因为权限问题导致写不了文件才意识到这件事。提前用非 root 用户运行，后面能省很多麻烦。

第四，COPY --from=builder /app/target/my-service.jar app.jar只把 jar 包拷进运行阶段。源文件、Maven 仓库、编译中间产物统统不进来。

重构之后的效果，镜像体积从 1.2 GB 降到不到 160 MB，降幅接近 87%。运行阶段的基础镜像只承担“跑 Java 进程”这个最小职责，安全扫描报告也干净了很多。

4.3 构建缓存优化：pom.xml 单独拷贝为什么能大幅提速

上面提到了COPY pom.xml .配合RUN mvn dependency:go-offline能利用 Docker 层缓存加速构建，这里我再多说一点原理。

Docker 在构建镜像时，每一条指令都会生成一个新的层。层缓存命中的前提是：这一层指令的内容和上下文文件哈希都跟之前完全一致。也就是说，如果你整体COPY . .，只要代码里任何一个文件变了，这一层缓存就失效了，后面所有层都得重新执行。但如果你先只拷贝pom.xml，再执行依赖下载，那么只要pom.xml这个文件没变化，依赖下载这一层就能复用之前的缓存结果。

实际效果是：你改了业务代码，重新构建时 Maven 会直接跳过依赖解析和下载环节，从源码编译开始。这跟你先在本地把依赖下好、再反复编译代码的体验是类似的。这个技巧在多阶段构建的“构建阶段”里特别重要，因为 Maven 构建是整个流程里最耗时的部分。

注意一个细节：mvn dependency:go-offline只能下载大部分依赖，如果后续执行mvn clean package时还有插件或依赖没有缓存，它照样会去联网下载。所以它并不能保证 100% 离线构建，但能帮你把绝大多数依赖在缓存层里固化下来，这对 CI/CD 中的重复构建非常有价值。

5. 实操案例二：前端项目静态资源提取与 Nginx 托管

5.1 前端部署的核心诉求：构建产物才是唯一需要的

前端项目的部署逻辑跟后端有很大区别。后端通常需要跑一个 JVM 或者二进制进程，前端则是一个纯静态资源集合——HTML、CSS、JS 文件——需要一个 Web 服务器来托管。

传统做法是把构建产物拷到服务器上，再单独安装一个 Nginx，配置好站点目录。这种做法在服务器环境复杂多变的情况下，很容易出现“我这能跑你怎么不行”的问题。Nginx 配置、端口、目录权限，任何一个环节不一致都会折腾半天。

多阶段构建解决这个问题的思路很直白：前面的阶段安装 Node.js，执行构建，产出静态文件；后面的阶段基于 Nginx 镜像，把静态文件直接 COPY 进 Nginx 的站点目录。

这样最终产出的镜像自带 Nginx 和正确版本的静态资源，部署到任何支持 Docker 的环境里都能立刻跑起来，不需要额外安装任何东西。这正是镜像“自包含、可移植”的思想落地。

5.2 完整的 Vue/React 项目多阶段构建 Dockerfile

下面是我在一个 Vue 3 项目中实际用过的 Dockerfile，你可以直接参考：

# 阶段一：Node 构建 FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 阶段二：Nginx 托管 FROM nginx:1.25-alpine COPY --from=builder /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD ["nginx", "-g", "daemon off;"]

这里有两个细节值得展开讲。

第一，npm ci和npm install的区别。npm ci要求必须有package-lock.json文件存在，它会严格按照锁文件安装依赖，速度更快，且不会修改锁文件。在多阶段构建里，优先推荐用npm ci，因为这样可以保证每次构建的依赖版本完全一致，不会出现“今天构建能用，明天构建依赖升级了导致失败”的情况。如果你拿到一个没有锁文件的老项目，第一次先跑npm install生成锁文件，提交到代码仓库，之后再统一用npm ci。

第二，COPY --from=builder /app/dist /usr/share/nginx/html是从 Node 构建阶段拷贝dist目录到 Nginx 的默认站点目录。如果你用的是 Vite，默认构建输出目录是dist；如果用 Create React App 或者 Umi，输出目录可能是build。这个目录路径要根据你项目实际配置调整。

另外，前端项目经常遇到的一个问题是：npm run build执行完之后，node_modules 还是被带进了某个中间层里。多阶段构建天然规避了这个问题——最终镜像里只有dist静态文件和 Nginx 运行环境，node_modules 压根不会出现在最终镜像里。

5.3 Nginx 配置的注意事项与常见坑

前端项目用 Nginx 托管时，最大的坑就是前端路由。Vue Router 或 React Router 默认使用 history 模式时，路由路径如/user/123会被请求到 Nginx，如果 Nginx 没有配置try_files，它会在站点目录里找user目录，找不到直接 404。

所以你的nginx.conf至少要包含这段配置：

server { listen 80; server_name _; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } # 静态资源缓存（可选但推荐） location /assets/ { expires 7d; add_header Cache-Control "public"; } }

try_files $uri $uri/ /index.html的含义是：先尝试按原路径找文件，找不到再尝试找目录，还找不到就回退到/index.html。这样前端路由刷新页面时，Nginx 会把请求交给前端应用自己处理，不会因为路径不存在而报 404。

还有个细节我提一下：如果你用 Nginx 官方镜像，默认配置文件在/etc/nginx/conf.d/default.conf。直接覆盖这个文件即可，不用去改/etc/nginx/nginx.conf主配置文件。

5.4 怎样把 Nginx 配置文件优雅地放入镜像

上面 Dockerfile 里有一行COPY nginx.conf /etc/nginx/conf.d/default.conf。这里有个经验：把 Nginx 配置单独放一个文件，不要跟源码混在一起。

我见过一些项目把所有配置直接写在 Dockerfile 的 RUN 指令里，用 echo 拼字符串，维护起来非常痛苦。建议的方式是：

• 项目根目录下建一个deploy/nginx.conf或者其他路径，跟源码区分开。
• Dockefile 里直接COPY deploy/nginx.conf /etc/nginx/conf.d/default.conf。
• 配置放在版本控制里，改配置走跟改代码一样的流程，可审计、可回滚。

另外一个常见问题是：本地 Nginx 配置测试没问题，进容器就出问题。比较典型的是路径写绝对路径还是相对路径、监听端口是不是被占用、权限是不是不对。排查思路也是固定的：先docker exec -it 容器名 sh进入容器，手动看nginx -t的报错信息，再检查配置文件内容是否跟预期一致。

6. 进阶技巧：--from指向外部镜像与多架构构建

6.1 COPY --from 外部镜像：从任意镜像提取文件的妙用

COPY --from除了能引用同一 Dockerfile 里的阶段名，还能直接引用一个已有的镜像名。这个用法在做“镜像内容复制”时特别有用。

举个例子，你希望容器里带一个特定版本的curl，但你的运行阶段基础镜像是distroless，连 shell 都没有。这时你可以通过--from把curl二进制从curlimages/curl镜像里拷出来，放进运行阶段。类似地，你可以从busybox镜像里提取一些常用的命令行工具。这相当于把“安装依赖”变成“直接 COPY 二进制”，从根本上避免在运行阶段执行apt-get install这类操作。

再举一个更实际的场景：TLS 根证书。Java 服务或者 Go 服务启动时要访问外部 HTTPS 接口，需要在运行阶段包含一套系统根证书。常见做法是：

COPY --from=alpine:3.19 /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

直接从 alpine 镜像里把证书文件拿过来，不需要额外安装任何包。相比在运行阶段执行apk add ca-certificates，这种做法的优势在于：即使你的运行阶段是scratch，也能拥有可用的根证书。

6.2 通过构建参数动态调整 Dockerfile 行为

多阶段构建中，ARG和构建阶段配合可以做出很多灵活的组合。最常见的用法是通过ARG指定需要拉取的依赖版本，避免在每个阶段里重复写死。

看个例子：

ARG GOLANG_VERSION=1.21-alpine FROM golang:${GOLANG_VERSION} AS builder # ...

这样在构建时可以通过--build-arg GOLANG_VERSION=1.22-alpine动态调整版本，而不用改 Dockerfile。构建工具如 Jenkins、GitHub Actions 可以用同一个 Dockerfile 根据分支或者环境传入不同的参数，实现一套配置多环境复用。

另一个进阶用法是条件化构建。虽然 Dockerfile 本身不支持if/else，但ARG配合RUN中的 shell 逻辑可以做到类似效果。不过这种写法可读性差，维护成本高，建议只在确实需要时才用。我的建议是：如果条件分支真的很多，把构建逻辑拆分成多个 Dockerfile 或者改用构建脚本，比在一个 Dockerfile 里堆条件更清晰。

6.3 多架构构建与 Buildx 的配合

多阶段构建本身就具备一个隐藏优势：中间阶段的内容在不同架构之间的差异可以做到最小。你的构建阶段可能依赖特定的编译器，但最终产物如果是纯静态的 Java jar 包或者前端静态文件，那运行阶段的基础镜像换成任何架构都行。这就是--platform参数发挥作用的地方。

用 Docker Buildx 做多架构构建时，一个典型命令是：

docker buildx build --platform linux/amd64,linux/arm64 -t myapp:1.0.0 --push .

Buildx 会为每个平台分别构建镜像，然后打包成 manifest 列表推送。拉取时 Docker 会自动选择对应平台的镜像。这个能力在实际部署 Apple Silicon 开发机和 x86 服务器混用的环境里特别有用。

在做多架构构建时，有几个需要注意的细节：

• 构建阶段的工具链要支持目标架构交叉编译。比如 Go 通过GOOS和GOARCH控制，Java 通常用--platform控制基础镜像的架构。
• 某些依赖包含 native 模块，比如 Node 项目里的 node-sass、bcrypt，需要确保它们支持目标架构。
• 构建时不要依赖宿主机架构相关的二进制文件，否则一个平台能构建成功，另一个平台可能直接报错。

7. 常见问题与排查技巧实录

7.1 增量构建总是失效，缓存没生效怎么办

遇到最多的问题就是“我觉得 Dockerfile 已经写好了，为什么改了代码后重新构建还是很慢？”大概率是缓存失效了。

排查思路很简单，构建时加上--progress=plain参数查看每一条指令的缓存状态，或者用docker build --no-cache强制全量重建，对比一下耗时，基本能判断是哪一层导致缓存失效。

常见原因无非这几个：

• COPY . .直接拷贝了整个项目目录，任何文件变动都会让这一步和后续步骤缓存失效。解决办法是像前面说的那样，精确控制 COPY 的颗粒度，先拷依赖描述文件，再拷源码。
• .dockerignore没有排除无关文件，比如日志、临时文件、IDE 配置等。这些文件的变动会破坏上下文哈希，导致缓存无法命中。
• 某些 RUN 指令本身带有随机性，比如RUN npm update或者RUN apt-get upgrade，执行结果每次可能不同，Docker 会保守地让其缓存失效。

改进方法就是把 Dockerfile 里不稳定的层尽量往后放，稳定的层往前放。这不是玄学，是 Docker 层缓存机制直接决定的规律。

7.2 运行阶段缺文件、缺证书，怎么排查

多阶段构建把镜像精简了，但也带来一个新问题：运行阶段缺少编译期随便能用的文件。

最常见的两类：

• 缺少证书文件。程序访问 HTTPS 接口报证书错误，但本地跑没任何问题。因为本地开发机的系统证书和你精简后的镜像不是一回事。解决办法是像前面建议的，从alpine镜像里把ca-certificates.crt拷贝进来，或者RUN apk add --no-cache ca-certificates。
• 缺少时区数据库。很多定时任务场景需要准确时区，精简镜像里可能没有包含tzdata。解决办法是在运行阶段安装它：

RUN apk add --no-cache tzdata ENV TZ=Asia/Shanghai

排查这类问题有个常用技巧：启动容器时用docker cp拷文件进去验证，或者改用docker run --entrypoint sh进入容器手动确认。先确认文件缺失是不是原因，再验证解决方案是否有效，最后再把验证结果固化到 Dockerfile 里。

7.3 构建上下文太大导致构建缓慢

这个问题经常被忽略。Docker 构建时会把当前目录及 Dockerfile 中指定的上下文打包发送给 Docker daemon。如果一个项目目录里有 node_modules、target 这类动辄几百 MB 的目录，每次构建都要上传这么多数据，不慢才怪。

解决办法是在项目根目录创建.dockerignore文件：

node_modules target dist .git .idea *.log .DS_Store

.dockerignore的语法跟.gitignore基本一致。这个文件存在的意义是：告诉 Docker 哪些文件不参与构建上下文。用了它之后，不仅构建速度会明显提升，还能避免开发机上的本地配置被误打包进镜像里。

7.4 多阶段构建下的调试技巧：临时镜像与 docker cp

在调试 Dockerfile 时，最忌讳的是一遍遍地重新构建看结果。构建一次少说几十秒，多则几分钟，效率太低。更聪明的做法是利用多阶段构建的特点做定向调试。

我的习惯是这样的：

• 如果构建阶段出问题，用交互式容器进入该阶段的基础镜像，手动执行命令看看哪里报错。
• 如果运行阶段出问题，构建完成后不要直接跑，先用docker create创建容器但不启动，再用docker cp把容器里的文件拷贝出来检查，或者直接docker run --rm -it 镜像名 sh进容器看目录内容和环境变量。
• 不要怕在中间阶段开调试用的步骤，调试完了再删掉，重新构建最终版本。

比如你想确认运行阶段里的app.jar是否被正确拷贝、权限对不对，可以这样操作：

docker build -t myapp:debug . docker run --rm -it --entrypoint sh myapp:debug # 进入容器后 ls -lh /app file /app/app.jar

7.5 多阶段构建常见问题速查表

我把实际运行中最常见的问题整理成一张表，方便你照方抓药：

8. 我个人的实操体会与后续可以继续优化的方向

多阶段构建用了这么长时间，我最大的体会是：真正决定镜像质量的不是你会不会写那几行 Dockerfile，而是你愿不愿意去理解每一条指令背后的层级关系和数据流。很多人直接在 GitHub 上复制一份 Dockerfile，跑通了就觉得万事大吉，但一旦碰到体积超标或者构建报错，完全没有排查头绪。多阶段构建的底层逻辑并不复杂，核心就是“构建期与运行期分离”和“层缓存机制”，把这两点吃透了，大部分问题都能自己解决。

最后说一个我自己一直保留的习惯：每次写完 Dockerfile，我会顺手看一眼每一层的体积。用docker history 镜像名就能看到每一层的占用，这能帮你快速定位是哪个阶段产生的垃圾被意外带进了镜像。如果你的构建阶段里某一条RUN产生了超大文件，但最终镜像里并不需要它，考虑是不是该加一层清理命令。另外，关注一下 Docker 官方的docker init工具，它会根据项目语言自动生成一个初始的 Dockerfile，很多就是多阶段构建范式，拿来作为初稿非常合适，省事还规范。

这个方向你后续还可以继续深挖：把构建流程接入 Kubernetes 的构建系统、用 BuildKit 优化远程缓存、在 GitLab CI 或 GitHub Actions 里做镜像构建与安全检查，都是很自然的下一个优化点。先把多阶段构建这个地基打牢，后面这些进阶玩法才能接得住。