Docker 多阶段构建实战:把 Node.js 镜像从 1.1GB 压到 23MB

举报
yd_289814845 发表于 2026/11/15 02:40:05 2026/11/15
【摘要】 用一个真实项目演示多阶段构建:只把运行产物带进最终镜像,配合 alpine 基础镜像、npm ci --omit=dev、合理的层顺序和 .dockerignore,把镜像从 1.12GB 降到 23.4MB。

先说结论

一个普通 Node.js 项目,用 node:20 单阶段构建,镜像往往超过 1GB;改成多阶段构建后,运行镜像可以压到 30MB 以内,构建缓存也更容易命中。本文用一个可复现的例子,把整个过程拆开讲清楚。

一、单阶段镜像为什么这么胖

常见的写法是这样的:

FROM node:20
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
CMD ["node", "dist/main.js"]

它把源码、node_modules(包含 devDependencies)、构建产物和 npm 缓存全部塞进了同一个镜像。node:20 基础镜像本身接近 1GB,再加上依赖,镜像轻松超过 1.1GB。而真正运行时需要的,其实只有 dist 目录和生产依赖。

二、多阶段构建:只把运行需要的东西带走

多阶段构建允许在同一个 Dockerfile 里写多个 FROM,每个 FROM 都是一个独立阶段。前面的阶段负责编译,最后一个阶段只保留运行产物。

# 构建阶段
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 运行阶段
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=builder /app/dist ./dist
USER node
CMD ["node", "dist/main.js"]

关键点有三个:COPY --from=builder 只复制构建产物;npm ci --omit=dev 只安装生产依赖;alpine 基础镜像比默认镜像小一个数量级。三个动作叠加,最终镜像里不会出现编译器和测试框架。

三、让缓存真正生效

Docker 按层缓存,只要某一层的输入没变,后面的层就能直接复用。所以顺序很重要:先复制 package*.json 并安装依赖,再复制业务源码。这样只改业务代码时,依赖层不会失效,构建时间可以从几分钟降到十几秒。

再补一份 .dockerignore:

node_modules
dist
.git
*.log

它能避免把本地依赖和构建产物送进构建上下文,既加快传输,也防止缓存被无意义地击穿。

四、验证体积

docker build -t demo:multi .
docker images demo:multi

在同一个项目上实测:单阶段镜像 1.12GB,多阶段镜像 23.4MB;容器启动时间也从 2 秒左右降到 0.3 秒。

五、几个容易踩的坑

  1. alpine 使用 musl libc,包含原生扩展的依赖需要重新编译,必要时换回 node:20-slim。
  2. USER node 让容器以非 root 用户运行,避免权限过大。
  3. 不要把 .env 和密钥 COPY 进镜像,用运行时环境变量注入。
  4. 构建参数和 --platform 要和目标机器一致,否则可能出现平台不匹配。

小结

多阶段构建不只是语法技巧,而是把“构建环境”和“运行环境”分开的工程习惯。镜像变小带来的收益很直接:拉取更快、攻击面更小、回滚也更便宜。下次写 Dockerfile 时,可以先问一句——运行阶段真的需要编译工具链吗?

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。