Docker 多阶段构建实战:把 Node.js 镜像从 1.1GB 压到 23MB
先说结论
一个普通 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 秒。
五、几个容易踩的坑
alpine使用 musl libc,包含原生扩展的依赖需要重新编译,必要时换回node:20-slim。USER node让容器以非 root 用户运行,避免权限过大。- 不要把
.env和密钥COPY进镜像,用运行时环境变量注入。 - 构建参数和
--platform要和目标机器一致,否则可能出现平台不匹配。
小结
多阶段构建不只是语法技巧,而是把“构建环境”和“运行环境”分开的工程习惯。镜像变小带来的收益很直接:拉取更快、攻击面更小、回滚也更便宜。下次写 Dockerfile 时,可以先问一句——运行阶段真的需要编译工具链吗?
- 点赞
- 收藏
- 关注作者
评论(0)