Multi-stage build là gì và giải quyết vấn đề gì?
Một application hiện đại thường cần nhiều thứ để build hơn là để chạy: TypeScript compiler, test runner, bundler, native compiler, package manager cache và toàn bộ source code. Nếu đem tất cả vào production image, runtime image sẽ lớn hơn, có nhiều dependency hơn cần scan và nhiều tool hơn mức process thực sự cần.
Multi-stage build tách build environment khỏi runtime environment trong cùng một Dockerfile. Build stage tạo ra artifact. Final stage chỉ copy artifact và runtime dependency thật sự cần thiết.
Nó không phải phép thuật làm image luôn nhỏ hơn. Nếu copy nhầm node_modules chứa dev dependency, giữ lại compiler/library mà runtime không cần, hoặc base image vốn đã rất lớn, final image vẫn phình to. Multi-stage chỉ cho tôi ranh giới để làm đúng — làm đúng hay không vẫn tùy vào cách viết Dockerfile.
App demo: có dev dependency và build artifact
Tạo một app demo TypeScript nhỏ.
package.json:
{
"name": "multi-stage-demo",
"private": true,
"type": "module",
"scripts": {
"build": "tsc -p tsconfig.json",
"start": "node dist/server.js"
},
"dependencies": {
"express": "5.1.0"
},
"devDependencies": {
"@types/express": "5.0.3",
"@types/node": "22.15.3",
"typescript": "5.8.3"
}
}
src/server.ts:
import express from "express"; const app = express(); const port = Number(process.env.PORT || 3000); app.get("/health", (_request, response) => { response.json({ ok: true }); }); app.listen(port, "0.0.0.0", () => { console.log(`listening on ${port}`); });
tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "dist",
"strict": true,
"skipLibCheck": true
},
"include": ["src/**/*.ts"]
}
Cách đầu tiên: single-stage build
Dockerfile single-stage dễ viết:
FROM node:24-bookworm-slim WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build ENV NODE_ENV=production EXPOSE 3000 CMD ["npm", "start"]
Build và kiểm tra:
docker build -f Dockerfile.single --tag multi-stage-demo:single . docker image ls multi-stage-demo:single docker run --rm -p 3000:3000 multi-stage-demo:single
Image này chạy được. Nhưng nó giữ lại TypeScript, @types/*, source .ts, tsconfig và toàn bộ dev dependency. Runtime server thật ra chỉ cần JavaScript build artifact, Express runtime dependency và Node runtime — phần còn lại chỉ chiếm chỗ và tăng attack surface.
Cách thứ hai: multi-stage build
Dockerfile multi-stage:
FROM node:24-bookworm-slim AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci FROM deps AS builder COPY tsconfig.json ./ COPY src ./src RUN npm run build FROM node:24-bookworm-slim AS runner WORKDIR /app ENV NODE_ENV=production COPY package.json package-lock.json ./ RUN npm ci --omit=dev && npm cache clean --force COPY --from=builder /app/dist ./dist USER node EXPOSE 3000 CMD ["node", "dist/server.js"]
Build final stage:
docker build --tag multi-stage-demo:multi . docker image ls multi-stage-demo:single multi-stage-demo:multi docker run --rm -p 3000:3000 multi-stage-demo:multi
Final stage không copy src, tsconfig.json, TypeScript compiler hay @types. Nó cài lại production dependencies từ lockfile, sau đó chỉ copy dist từ builder sang.
Vì sao không copy nguyên node_modules từ builder
Cách dưới có thể hoạt động trong vài app:
COPY --from=builder /app/node_modules ./node_modules
Nhưng node_modules của builder thường chứa cả dev dependency. Nếu dùng cách này, final image vô tình giữ lại TypeScript, test library, type definitions. Có thể tách bằng một deps-prod stage riêng để prune, hoặc cài npm ci --omit=dev riêng ở runner như demo phía trên — cách thứ hai đơn giản và dễ audit hơn.
Với native dependency, vấn đề còn sâu hơn. Builder và runner phải tương thích OS, architecture và shared library. Copy node_modules từ Debian builder sang Alpine runner có thể fail lúc runtime vì khác libc (glibc vs musl). Đừng đổi base image ở final stage chỉ vì nó nhỏ hơn, nếu native artifact được build cho một base khác.
So sánh phải đo, không đoán
Sau khi build, lấy số đo thực tế trên máy local:
docker image ls multi-stage-demo:single multi-stage-demo:multi docker run --rm multi-stage-demo:single sh -lc \ 'test -d node_modules/typescript && echo "typescript exists"' docker run --rm multi-stage-demo:multi sh -lc \ 'test ! -d node_modules/typescript && echo "typescript absent"'
Kết quả size phụ thuộc base image, lockfile, cache và architecture. Bài viết không nên nêu một con số MB cố định như kết quả phổ quát — mỗi máy, mỗi thời điểm build lại cho một con số hơi khác nhau. Chụp số liệu thật từ máy chạy lab và ghi rõ environment (OS, kiến trúc CPU, phiên bản Docker) đi kèm.
| Image | Size local | Có TypeScript runtime? |
/health pass? |
|---|---|---|---|
multi-stage-demo:single |
97.9MB | Có | Có |
multi-stage-demo:multi |
81.7MB | Không | Có |
root@unity:/home/docker-multibuild# docker image ls multi-stage-demo:single
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
multi-stage-demo:single df1f43025c01 419MB 97.9MB
root@unity:/home/docker-multibuild# docker image ls multi-stage-demo:multi
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
multi-stage-demo:multi d57c625695c7 337MB 81.7MB
Multi-stage giúp gì ngoài image size
- Final image có ít build tool hơn, giảm dependency surface và scan noise.
- Dockerfile diễn đạt rõ artifact nào đi từ build sang runtime.
- CI cache có thể tách dependency install với source build.
- Runtime container dễ chạy non-root hơn vì chỉ cần writable path cụ thể.
- Review release dễ hơn: final stage copy gì chính là runtime contract.
Multi-stage không tự giải quyết:
- Secret bị truyền vào build hoặc hardcode trong source.
- CVE trong base image/runtime dependency.
- Health check không phản ánh database readiness.
- Database migration chạy đồng thời khi nhiều replica boot.
- Persistent upload/data bị đặt trong local container filesystem.
Khi nào multi-stage không đáng phức tạp
Một static config image rất nhỏ, không có build artifact, có thể chỉ cần một stage. Một image tool/debug cũng có thể chủ ý giữ lại CLI utility. Nhưng application production có compile/bundle/native build thường nên có build/runtime boundary rõ ràng.
Đừng ép multi-stage nếu final stage cuối cùng vẫn copy lại toàn bộ source, full node_modules, compiler và package manager cache. Khi đó Dockerfile dài hơn nhưng boundary vẫn không tồn tại.
LinuxUnity sẽ áp dụng gì từ đây
LinuxUnity đã dùng multi-stage Dockerfile phức tạp hơn demo: build libvips native, build Sharp theo ràng buộc compatibility, prune production dependency, build Next.js standalone rồi copy artifact cần cho runtime. Điều đáng học không phải chỉ là số stage. Điều đáng học là mỗi stage có trách nhiệm rõ ràng:
native library build -> dependency build -> Next.js build -> minimal runner
Kết Luận
Multi-stage build không phải chiếc đũa thần tự động làm nhỏ Docker image, mà là công cụ giúp bạn thiết lập ranh giới kiến trúc rõ ràng giữa môi trường build và môi trường runtime. Việc giảm dung lượng từ 97.9MB xuống 81.7MB ở bài demo trên chỉ là kết quả bề nổi; giá trị cốt lõi nằm ở việc loại bỏ triệt để các dev dependency, thu hẹp diện tích tấn công (attack surface) và làm cho runtime contract của ứng dụng trở nên minh bạch.
Những điểm then chốt cần đóng gói lại:
-
Tự tạo ranh giới đúng: Multi-stage chỉ cung cấp cơ chế, còn việc chọn lọc những artifact nào được đi tiếp vào final stage hoàn toàn phụ thuộc vào kỷ luật viết Dockerfile. Copy nguyên khối
node_moduleshay giữ lại compiler thừa sẽ triệt tiêu toàn bộ lợi ích của việc chia stage. - Đo lường thực tế, không đoán mò: Đừng chọn base image chỉ vì một con số MB trên mạng. Mỗi môi trường build, kiến trúc CPU và phiên bản Docker sẽ cho ra kết quả khác nhau. Hãy luôn đo đạc số liệu thực tế trên máy local/CI trước khi đưa ra quyết định.
-
Cẩn trọng với Native Dependencies: Tốc độ hay dung lượng nhỏ của Alpine/musl không bao giờ đáng đánh đổi bằng sự bất ổn định của hệ thống runtime. Việc đổi base image ở final stage mà không kiểm tra khả năng tương thích của shared library (
glibcvsmusl) là nguyên nhân hàng đầu gây ra lỗi runtime ẩn.
Nắm vững tư duy phân tách ranh giới này là tiền đề quan trọng trước khi xử lý các bài toán containerization phức tạp hơn trong thực tế.