title: "Multi-stage build là gì và giải quyết vấn đề gì" description: "So sánh Dockerfile single-stage với multi-stage trên một Node.js app có build step, kiểm tra runtime artifact và hiểu khi nào multi-stage không tự làm image nhỏ hay an toàn hơn." date: 2026-08-20 author: nhatnghia category: Docker tags: - Docker - Dockerfile - Multi-stage Build - Node.js series: docker-to-eks-on-aws --- # 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 để chạy: TypeScript compiler, test runner, bundler, native compiler, package manager cache và source code đầy đủ. Nếu đem tất cả vào production image, runtime image 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 với runtime environment trong cùng Dockerfile. Build stage tạo artifact. Final stage chỉ copy artifact và runtime dependency cần thiết. Nó không phải phép thuật làm image luôn nhỏ. Nếu copy nhầm node_modules chứa dev dependency, giữ compiler library runtime không cần thiết hoặc base image vốn rất lớn, final image vẫn phình. Multi-stage chỉ cho tôi ranh giới để làm đúng. ## App demo: có dev dependency và build artifact Tạo app demo TypeScript nhỏ. package.json: 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: 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: 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: dockerfile 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: bash 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ữ TypeScript, @types/*, source .ts, tsconfig và mọi dev dependency. Runtime server chỉ cần JavaScript build artifact, Express runtime dependency và Node runtime. [HÌNH 1 — Single-stage image] Tên file gợi ý: docker-single-stage-image.webp text runtime image |- Node runtime |- production dependencies |- TypeScript compiler |- type definitions |- source TypeScript |- build artifact ## Cách thứ hai: multi-stage build Dockerfile multi-stage: dockerfile 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: bash 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 đó copy dist từ builder. [HÌNH 2 — Multi-stage pipeline] Tên file gợi ý: docker-multi-stage-pipeline.webp text package lock | v deps stage: npm ci | v builder stage: source + tsc -> dist/ | v runner stage: Node + production deps + dist/ ## Vì sao không copy nguyên node_modules từ builder Cách dưới có thể hoạt động trong vài app: dockerfile COPY --from=builder /app/node_modules ./node_modules Nhưng builder node_modules thường chứa cả dev dependency. Nếu dùng cách này, final image vô tình giữ TypeScript/test library/types. Có thể prune trong một deps-prod stage, hoặc cài npm ci --omit=dev riêng ở runner như demo. 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. Không đổi base image ở final stage chỉ vì nó nhỏ nếu native artifact được build cho base khác. ## So sánh phải đo, không đoán Sau build, lấy số đo local: bash 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 số MB cố định như kết quả phổ quát. Chụp số từ máy làm lab và ghi rõ environment. [CODE CẦN THÊM] Thêm bảng benchmark thật sau khi chạy lab: | Image | Size local | Có TypeScript runtime? | /health pass? | |---|---:|---:|---:| | multi-stage-demo:single | <điền kết quả> | Có | Có | | multi-stage-demo:multi | <điền kết quả> | Không | Có | ## 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ì 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 build artifact, có thể chỉ cần một stage. Một image tool/debug cũng có thể intentionally giữ 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 bắt đầu 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õ: text native library build -> dependency build -> Next.js build -> minimal runner Ở bài áp dụng sau, tôi sẽ đọc từng stage và giải thích vì sao “đổi Alpine cho image nhỏ” có thể làm Sharp/media processing fail nếu không benchmark và regression test. ## Checklist cuối bài - [ ] Phân biệt build dependency và runtime dependency. - [ ] Biết final stage chỉ copy artifact/runtime dependency thật sự cần. - [ ] Đo image size và kiểm tra runtime behavior thay vì đoán. - [ ] Không copy dev node_modules từ builder sang runner vô tình. - [ ] Kiểm tra native module compatibility giữa builder và runner. - [ ] Không xem multi-stage là thay thế cho secret management, health check và persistence design. ## Bài tiếp theo Bài tiếp theo dựng một stack Docker Compose 101 gồm application và database, sau đó đọc depends_on, healthcheck, network, volume và docker compose config trước khi áp dụng vào Compose thật của LinuxUnity.
Series: Docker
Related posts
Dockerfile: FROM, RUN, COPY, CMD, ENTRYPOINT và build cache
Build một Node.js HTTP server nhỏ bằng Dockerfile, hiểu vai trò của từng instruction, cache layer, .dockerignore và cách đọc image sau khi build.
28/08/2026 · 8 min read · Docker
Docker Compose: services, depends_on, healthcheck và network
Dựng stack Node.js và PostgreSQL tối giản bằng Docker Compose, hiểu service discovery, named volume, depends_on condition và dùng docker compose config để kiểm tra cấu hình trước khi chạy.
28/08/2026 · 8 min read · Docker
Docker: Volume và network
Phân biệt bind mount, named volume và tmpfs; tạo bridge network riêng và kiểm tra service discovery giữa hai container bằng Docker DNS.
24/08/2026 · 8 min read · Docker