最近把内部一个应用容器化验收docker images 一拉下来差点没绷住1.3GB。项目本身代码只有几十兆打包完膨胀了二十多倍这谁看了不皱眉。第一反应就是上多阶段构建折腾一轮之后镜像确实小了但远没到预期准确说是“不算成功”。这篇文章就把这次完整复盘写下来1.3G 是从哪来的、多阶段构建为什么能瘦身、为什么这次只算半成功以及后面我又用了哪些手段真正把体积压下去。适合正在做 Docker 镜像瘦身、或者刚接触多阶段构建但卡在体积优化上的开发者参考。1. 1.3G 镜像是怎么“吃”出来的1.1 镜像体积不等于代码体积先搞懂分层机制很多人有个直觉镜像体积 ≈ 代码体积。这个想法错得离谱。Docker 镜像不是一个大文件而是一堆只读层的堆叠。每执行一条RUN、COPY、ADD指令Docker 就会在现有层之上新建一层记录这一次操作产生的文件变更。所以最终体积是所有层的体积之和代码本身往往只占极小一部分。这个机制可以类比成做蛋糕每一层指令就是一层蛋糕胚上面的奶油、水果、装饰全都会累计到最后的总高度里。你想减掉某一层不能只把奶油刮掉得从那一层开始重新叠。这也是为什么很多人在 Dockerfile 里写了rm -rf /tmp/cache镜像却一点没变小——因为rm也是在新层里执行的只是把上一层文件标记成删除物理空间早就被那一层占住了。理解这一点之后再看 1.3G 就不奇怪了。我那个应用是基于某个脚本语言生态的 Web 服务Dockerfile 第一版极其偷懒一行基础镜像、一行 COPY 整个项目目录、一行安装全量依赖、一行启动命令。看似没写几行实际每一行都在往镜像里塞东西。1.2 体积大头通常藏在四个地方我给大量项目做过镜像体积排查基本逃不出下面四个“吃空间”的环节按贡献从大到小排列基础镜像本身如果你用的是xxx:latest或者带完整工具链的镜像基础层可能就有 300MB 到 1GB。很多官方镜像自带编译器、包管理器、文档、证书这些运行时根本用不上。依赖安装产物脚本语言尤其明显npm 会把 devDependencies 一起装上pip 会把构建依赖和运行依赖混在一起Java 的 Maven/Gradle 会把下载的中间件、插件全塞进来。这些依赖目录动辄几百 MB。包管理器缓存npm cache、pip cache、apt-get的/var/lib/apt/lists、yum缓存它们体积不小而且是典型的“装了就忘”。很多镜像明明用不到这些却因为没清理被一并打进层里。项目文件残留.git目录、本地临时文件、日志、上传的测试资源、node_modules如果构建机本地已经装了一份又 COPY 进去这些都是隐形杀手。我这次 1.3G 的构成就很典型基础镜像约 700MB带了构建工具链全量依赖安装后node_modules或等价目录约 400MB缓存和项目残留加一起又多了 200MB 左右。代码实际不到 50MB剩下全是被层层叠加进镜像的“行李”。这就是为什么必须先搞清楚体积分布再动手优化而不是一上来就盲目加.dockerignore。2. 多阶段构建的套路与边界2.1 核心思路把“造东西的环境”和“跑东西的环境”分开多阶段构建之所以有效本质是打破“一个 Dockerfile 只能产出一个镜像”的惯性。你可以在同一个 Dockerfile 里写多个FROM每一段是一个独立构建环境前一段可以装编译器、拉全量依赖、跑测试最后一段只挑出运行需要的产物拷贝过去。用大白话说你做饭的时候需要一个厨房锅碗瓢盆、煤气灶、菜刀全部要备齐但吃饭的时候只需要端菜上桌没人会连厨房一起端过去。多阶段构建就是让你在厨房里做完菜然后只端盘子出门。构建阶段多乱都无所谓运行阶段重开一个干净的新环境只拿最终产物干净又清爽。这个机制天然适合解决“构建依赖太大”的问题。比如编译类项目构建阶段装编译器、拉源码、编译运行阶段只需要二进制文件。脚本类项目稍微复杂一点因为运行阶段仍然需要解释器和依赖包但至少可以把开发依赖、编译工具链、缓存全部留在构建阶段。2.2 多阶段构建的标准写法我这里用一个简化的例子说明。假设项目是一个 Node.js Web 服务单阶段 Dockerfile 长这样# 单阶段所有东西都装 FROM node:20-bookworm WORKDIR /app COPY . . RUN npm install EXPOSE 3000 CMD [npm, start]这个 Dockerfile 的问题一眼就能看出来node:20-bookworm本身就大npm install把 devDependencies 全装上.git目录和本地临时文件也被 COPY 进去。改成多阶段之后# 阶段一构建环境装全量依赖跑构建 FROM node:20-bookworm AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . # 如果需要构建前端产物/编译 TS在这里执行 RUN npm run build # 阶段二运行环境只要产物和线上依赖 FROM node:20-bookworm WORKDIR /app ENV NODE_ENVproduction COPY --frombuilder /app/package*.json ./ COPY --frombuilder /app/node_modules ./node_modules COPY --frombuilder /app/dist ./dist EXPOSE 3000 CMD [node, dist/server.js]关键点是COPY --frombuilder。这条指令只从构建阶段指定的路径里复制我们需要的东西运行阶段不会继承构建阶段任何多余的文件。构建阶段用的编译器、缓存在第二个阶段里根本不存在天然就把体积砍掉一大块。2.3 为什么这次“不算成功”预期和现实的落差我按上面的思路改完之后重新构建、打 tag、查看镜像体积结果确实从 1.3G 降到了大约 700M。但说实话这个结果我是不满意的因为离“瘦”还差得远。复盘原因这次“不算成功”主要栽在三个地方第一基础镜像没换。我依然用node:20-bookworm作为运行阶段镜像这个基础镜像本身就是几百 MB 级别。多阶段构建把依赖打包工具、构建缓存挪走了但厨房里的锅碗瓢盆编译器、包管理器、系统工具还是留在运行环境里。如果你的运行阶段仍然用同一个全量基础镜像那多阶段构建省下的其实只有一层依赖安装的浪费基础镜像那部分一点没动。第二依赖裁剪没做彻底。构建阶段npm ci默认装的是全量依赖包括 devDependencies。虽然我拷贝到运行阶段时通过--omitdev可以只装生产依赖但如果我在构建阶段没有显式区分后续的清理逻辑就容易被忽略。实际上我这版直接把整个node_modules拷过去了里面躺着大量构建时才用的工具包。第三缓存清理缺位。构建阶段下载的依赖包、临时文件、npm 缓存全被留在了 builder 层里虽然运行阶段没拷它们但如果后续优化不到位构建阶段本身的体积还是会影响 CI 效率而且这也说明我没系统性地审视每一层的体积。所以这次多阶段构建只能算“部分成功”方向对了手段用了一半深层的体积大头没碰到。这也是我接下来要解决的问题。3. 实战复盘从 1.3G 到 520M 再到更小3.1 第一次真实改动拆 Dockerfile 与调整依赖那次“半成功”的多阶段构建我保留了完整记录。操作过程并不复杂但要细心。我先是在 Dockerfile 里把构建阶段拆出来再调整运行阶段的启动方式最后重新构建对比。实际执行的步骤大概是这样把原来的单阶段 Dockerfile 改成二阶段结构构建阶段命名builder。在构建阶段使用npm ci替代npm install保证依赖按 lock 文件精确安装避免版本漂移。运行阶段把NODE_ENVproduction显式设好让依赖安装时自动跳过 devDependencies。只拷贝package.json、package-lock.json、dist目录和必要的配置文件到运行阶段。重新构建用docker images确认新镜像体积。前后对比大概是版本镜像体积备注单阶段 v11.3G全量基础镜像 全量依赖 缓存多阶段 v2约 700M构建产物和依赖分离但基础镜像仍是全量版多阶段 依赖裁剪 v3约 520M只拷生产依赖去掉 devDependencies看到 520M 的时候我知道方向完全正确但还远远不够。一个 50M 的代码服务镜像体积 520M说明大头还是在别处。3.2 用 dive 精准定位“每一层都在装什么”与其继续拍脑袋猜体积去哪了不如用工具看实际的层分布。我用了dive这个命令行工具一条命令就能列出镜像每一层的大小、文件变更、重复文件也能直接看到哪些文件是“垃圾”。安装 dive 之后对刚才构建的 520M 镜像跑dive 你的镜像名:v3界面里左侧是每一层的大小右侧是当前层实际新增的文件列表。我当时看完之后几个结论立刻浮出水面基础层占了接近 300MB这是node:20-bookworm自带的系统工具和文档。生产node_modules仍然有 100 多 MB里面混着很多实际上不会在运行时触及的包。项目目录里一个上传测试用的资源文件夹被原样拷贝了进来占 60MB 左右。日志、临时文件、.dockerignore没命中漏掉的文件加起来也有几十 MB。dive 最有价值的地方在于它还显示每一层内被删除的文件占用的空间以及所有层之间是否存在重复文件。很多你以为删掉的东西其实只是标记为删除物理空间还留在镜像里。把这一层看完之后瘦身的优先级就很清晰了。3.3 组合拳换基础镜像、清缓存、卡掉多余文件既然 520M 里大头是基础镜像、生产依赖、误拷贝文件三块那就挨个处理。先换基础镜像。官方镜像有一个精简版和另一个更激进的运行时镜像。对于 Node.js 服务我把运行阶段从node:20-bookworm换成了更小的发行版基础层体积直接下降。如果还要更激进可以使用基于 Alpine 的镜像或者干脆用 distroless——只包含运行所需的最小运行时连 shell 都没有。但这里有个风险点基础镜像不能乱换。项目里有原生模块的话glibc 换成 musl libc 可能导致二进制不兼容后面我会细讲。我这次的服务没有强依赖原生模块所以换镜像相对安全。然后是清依赖缓存。构建阶段改成RUN npm ci --omitdev npm cache clean --forcenpm cache clean --force会把 npm 缓存清掉这一步在构建阶段做会让那个层小不少。同理系统包安装后也要主动清理RUN apt-get update apt-get install -y --no-install-recommends xxx \ apt-get clean \ rm -rf /var/lib/apt/lists/*--no-install-recommends是关键它阻止 apt 把“推荐安装”的一堆包拉进来步骤里再补apt-get clean和删除/var/lib/apt/lists/*缓存问题就解决了。最后是.dockerignore这一点经常被忽略作用却非常大。我在项目根目录建了.dockerignore把不需要进入构建上下文的通通排除.git .gitignore node_modules logs *.log test/ tests/ coverage .idea .vscode Dockerfile .dockerignore 上传测试资源路径.dockerignore的作用是把文件挡在构建上下文之外。如果某些大文件本来就不该进镜像挡在入口处比进去之后再删高效得多。构建上下文越小Dockerfile 里的COPY . .也越快属于一举两得。这一轮改完之后镜像体积从 520M 降到了 160M 左右。如果再叠加 distroless还能再往下走但那一步对运维排查和可调试性有影响我没有在项目里强上。对比一下优化动作体积变化说明多阶段构建1.3G → 约 700M分离构建产物保留基础镜像裁剪生产依赖约 700M → 约 520M去掉 devDependencies换小基础镜像 清缓存 ignore约 520M → 约 160M基础层瘦身 依赖缓存清零 挡掉误拷贝换 distroless 验证约 160M → 约 100M 以下影子验证过体积但未上线到这里才算“成功了一半”最终体积仍有 160M 左右距离理论上 50M 左右的代码体积还有差距但那部分更多是运行时和依赖带来的合理成本硬压容易压出稳定性问题。3.4 给体积优化排优先级先看构成再动手这次配合下来我总结了一套优先级不高的执行顺序。如果你也在瘦身按这个顺序走基本不会跑偏先测量。用docker history或dive搞清每一层体积不要凭感觉猜。再挡入口。.dockerignore把明显不必要的文件挡在构建上下文外。然后拆阶段。多阶段构建分离构建环境和运行环境能解决“编译工具 源文件 缓存”这类大头。接着清缓存。包管理器缓存、apt 缓存、临时文件构建阶段能清就清。最后换底座。基础镜像的精简版或 distroless 放在最后因为它带来的兼容性风险最高。很多人一上来就换 Alpine结果项目跑不起来再花时间去折腾原生依赖这是典型的优先级颠倒。先清掉那些不加风险就能省掉的空间再去碰有代价的选项。4. 避坑指南常见问题与解决办法4.1 多阶段构建后运行报错缺动态链接库或系统依赖这是多阶段构建最容易踩的坑。构建阶段可以编译运行阶段却可能连最基本的动态库都没有。最常见的症状是容器启动时提示error while loading shared libraries: libxxx.so或者某个原生模块加载失败。我之前排查过一个 Python 服务构建阶段编译了某个科学计算依赖运行阶段只拷贝了 site-packages结果一启动就报libgomp.so.1: cannot open shared object file。原因很简单编译阶段生成二进制时需要动态链接库运行阶段没把这些库一起拷贝过来。解决办法一般是两种一是保持运行阶段基础镜像和构建阶段一致或兼容这样动态库还在二是显式把缺失的动态库文件通过COPY --frombuilder /usr/lib/xxx /usr/lib/xxx拷过来。前者简单但体积更大后者更省空间但需要准确知道缺了哪些库可以用ldd命令查。4.2 Alpine 镜像的“隐形坑”musl libc 与 C 扩展Alpine 因为体积小在镜像瘦身圈子里非常流行但它不是银弹。Alpine 默认使用 musl libc 而不是 glibc这个差异对纯脚本应用影响不大但凡是涉及编译型原生模块的项目都可能踩坑。我见过最典型的案例某个 Node.js 项目用了带原生代码的图片处理库在 Debian 基础镜像上一切正常换成 Alpine 之后要么编译失败要么运行时报段错误。即使强行加上--no-cache和编译工具编译出来的二进制基于 musl行为和 glibc 环境下可能不一致。除非你很确定项目里没有原生模块或它们对 musl 兼容良好否则不要盲目上 Alpine。多阶段构建里运行阶段不一定非要 Alpineslim版本在体积和兼容性之间往往更均衡。安全优先体积其次。4.3 体积明明改了docker images 显示却没变小心构建缓存有一种情况特别让人抓狂Dockerfile 改了重新构建也成功了docker images一看体积还是老样子。大概率是构建缓存把旧层直接复用了。Docker 的层缓存逻辑是如果指令文本没变且前置上下文没变就会复用已有层RUN的结果不会重新执行。解决办法有几个一是确保COPY之前的文件没变动过因为 Docker 会比较上下文内容二是明确需要强制重建时加上--no-cache参数三是如果只在部分步骤改了可以尝试调整 Dockerfile 中“容易变化”的指令顺序把COPY package.json和RUN npm ci放在COPY . .之前这样依赖安装层不会因为代码变更而失效。用docker system df可以查看当前构建缓存占了多少磁盘空间如果缓存积累太多定期执行docker builder prune清理一下。4.4 有些“技巧”别乱用合并 RUN、压缩层要看场景网上有很多关于减小镜像体积的野路子不是全错但别照单全收。比如“把所有 RUN 合并成一条并用连接”这能让层数变少减少最终镜像的层数。但过度合并会导致可读性严重下降而且如果中间某一步失败排查会非常痛苦。合理的合并目标是“相关操作放一起”不是把所有操作塞进一行。再比如“对镜像层做 squash压平”确实能减小体积但代价是丢失了层信息镜像无法按层复用缓存而且有些容器运行时对 squashed 镜像支持并不好。能用多阶段构建解决的问题不值得拿 squash 去凑。还有一条不算技巧但经常被反着用为了“调试方便”把调试工具、shell、完整包管理器留在镜像里。生产环境的镜像越小、越干净攻击面越小。体积和安全的取舍不要太犹豫。5. 写在最后几次折腾之后的真实体会这次 1.3G 镜像的瘦身过程最大的收获倒不是最终体积压到了多少而是重新理解了镜像优化的底层逻辑。多阶段构建不是一键瘦身的魔法它只是帮你把“构建环境”和“运行环境”这个最容易产生浪费的边界划清楚了。真正的瘦身要靠一层层看、一步步量先搞清楚每一层装了什么再决定哪些能去掉。我现在做镜像体积优化不会第一件事就去换 Alpine也不会盯着某个单条指令反复试。先把镜像当成一个由层构成的数据结构用工具量出体积大头再按“挡入口、拆阶段、清缓存、换底座”的顺序动手。大部分项目走到第三步就能收到明显效果最后一步能用就用不用也不必强求。最后再分享一个实用习惯每次改完 Dockerfile记录一下改动前后的体积数字顺手写进提交信息里。时间一长你会有自己的镜像体积基线哪些依赖是“隐形胖子”、哪些基础镜像升级会带来多大体积波动全部都看得清清楚楚。镜像瘦身这事没有玄学只有测量和复盘。
