Dockerfile cho app Next.js: multi-stage, standalone, và đừng chạy bằng root
Dockerfile đầu tiên mình viết cho một dashboard nội bộ bằng Next.js chỉ có năm dòng: FROM node, COPY . ., npm install, npm run build, CMD npm start. Chạy được ngay. Rồi mình nhìn docker images: image nặng hơn cả cái laptop cũ của mình, trong đó có nguyên node_modules dùng cho dev, cả thư mục .git, và process trong container chạy bằng root.
Bài này đi từ bản năm dòng đó tới bản mình đang dùng thật, từng bước một, mỗi bước giải thích vì sao. Đọc xong bạn có một Dockerfile mẫu copy dùng được cho app Next.js, và hiểu đủ để tự sửa cho app khác.
Bước 0: bản ngây thơ
FROM node:24
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
CMD ["npm", "start"]
Bốn vấn đề nằm ngay trong sáu dòng này:
| Vấn đề | Hậu quả |
|---|---|
COPY . . trước npm install |
Sửa một dòng CSS là Docker cài lại toàn bộ package, build chậm cả phút |
| Image cuối chứa mọi thứ đã dùng để build | Có cả devDependencies, source TypeScript, cache build. Nặng và lộ nhiều hơn cần |
Không có .dockerignore |
node_modules trên máy, .git, file .env bị gửi vào build context, có thể nằm luôn trong image |
| Chạy bằng root | App có lỗ hổng là kẻ tấn công có root trong container |
Bước 1: chặn rác từ đầu bằng .dockerignore
Khi bạn chạy docker build ., Docker gửi cả thư mục hiện tại (gọi là build context) cho engine. .dockerignore quyết định cái gì không được gửi:
node_modules
.next
.git
.env*
npm-debug.log*
Dockerfile*
docker-compose*
Dòng .env* quan trọng nhất. File .env chứa secret trên máy dev mà lọt vào image thì ai pull được image là đọc được secret, kể cả khi sau đó bạn xoá file trong một lệnh RUN khác (layer cũ vẫn còn trong image).
Bước 2: tách cài package ra một tầng riêng để tận dụng cache
Docker build từng lệnh thành một layer và cache lại. Một lệnh chỉ chạy lại khi input của nó đổi. Nên thứ tự đúng là: copy file khai báo package trước, cài, rồi mới copy source.
FROM node:24-alpine AS dependencies
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
Giờ sửa code mà không đụng package-lock.json thì tầng này lấy từ cache, không cài lại gì. npm ci thay vì npm install vì nó cài đúng y như lock file, và báo lỗi nếu lock file lệch với package.json, thay vì lặng lẽ cập nhật.
node:24-alpine thay cho node:24: bản Alpine nhỏ hơn nhiều. Đổi lại, nếu app có package native cần thư viện C (ví dụ sharp ở vài phiên bản cũ), bạn có thể phải cài thêm. Gặp lỗi lạ lúc cài thì thử bản -slim (Debian rút gọn) trước khi nghi ngờ code.
Bước 3: build ở tầng riêng, bật output standalone
FROM node:24-alpine AS builder
WORKDIR /app
COPY /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
ENV NEXT_OUTPUT_STANDALONE=1
RUN npm run build
Next.js có chế độ output: 'standalone': lúc build, nó dò xem code thật sự import những file nào trong node_modules (gọi là file tracing), rồi gom đúng những file đó cùng một server.js vào .next/standalone. Kết quả chạy được bằng node server.js, không cần npm install ở nơi chạy.
Mình bật nó bằng biến môi trường để next dev trên máy không bị ảnh hưởng:
// next.config.mjs
const nextConfig = {
// Chỉ bật standalone khi build để đóng gói (Docker, pipeline); chạy dev thì giữ mặc định
output: process.env.NEXT_OUTPUT_STANDALONE === '1' ? 'standalone' : undefined,
};
export default nextConfig;
Bước 4: tầng chạy chỉ chứa thứ cần để chạy
FROM node:24-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV HOSTNAME=0.0.0.0
ENV PORT=3000
COPY /app/.next/standalone ./
COPY /app/.next/static ./.next/static
COPY /app/public ./public
USER node
EXPOSE 3000
CMD ["node", "server.js"]
Đây là chỗ multi-stage phát huy tác dụng: image cuối chỉ lấy từ tầng builder đúng ba thư mục. Toàn bộ node_modules đầy đủ, source TypeScript, cache build đều ở lại tầng trước và không có trong image.
Ba chi tiết dễ sai ở tầng này:
- Quên copy
.next/staticvàpublic. Standalone không tự gom hai thư mục này. App vẫn chạy, nhưng mở trang lên thì không có CSS, không có ảnh, console đầy lỗi 404. Lỗi này hay lọt vì trang vẫn "trả về 200". HOSTNAME=0.0.0.0.server.jscủa standalone nghe theo biếnHOSTNAME. Docker lại tự đặtHOSTNAMEtrong container bằng ID của container, nên server chỉ nghe trên địa chỉ đó và từ ngoài gọi vào không được. Đặt rõ0.0.0.0để nghe mọi địa chỉ.USER nodevà--chown=node:node. Imagenodecó sẵn user tênnodekhông phải root. Chuyển sang user đó trướcCMD, và--chownđể user này đọc được file vừa copy. App bị khai thác thì kẻ tấn công cũng chỉ có quyền của user thường.
Trước và sau
| Bản năm dòng | Bản multi-stage | |
|---|---|---|
| Image cuối chứa | Source, toàn bộ node_modules, cache build | server.js, node_modules đã lọc, static |
| Sửa một file code rồi build lại | Cài lại toàn bộ package | Tầng cài package lấy từ cache |
| User chạy app | root | node |
Chênh lệch kích thước tuỳ app, nên tự đo trên project của bạn, đặt hai con số cạnh nhau là thấy ngay:
docker build -t app:naive -f Dockerfile.naive .
docker build -t app:multi .
docker images app
Dockerfile đầy đủ
# Tầng 1: chỉ cài package, cache được khi lock file không đổi
FROM node:24-alpine AS dependencies
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
# Tầng 2: build với output standalone
FROM node:24-alpine AS builder
WORKDIR /app
COPY /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
ENV NEXT_OUTPUT_STANDALONE=1
RUN npm run build
# Tầng 3: chỉ thứ cần để chạy, chạy bằng user thường
FROM node:24-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV HOSTNAME=0.0.0.0
ENV PORT=3000
COPY /app/.next/standalone ./
COPY /app/.next/static ./.next/static
COPY /app/public ./public
USER node
EXPOSE 3000
CMD ["node", "server.js"]
Nếu project không có thư mục public, bỏ dòng copy đó đi, không thì build lỗi.
Checklist cho mọi Dockerfile
[ ] Có .dockerignore, chặn node_modules, .git, .env*
[ ] Copy file khai báo package và cài trước, copy source sau
[ ] Dùng lệnh cài theo lock file (npm ci, pnpm install --frozen-lockfile)
[ ] Multi-stage: image cuối không có công cụ build và source
[ ] Không chạy bằng root
[ ] Không có secret trong ENV hay ARG của Dockerfile
[ ] Tag image base rõ phiên bản (node:24-alpine), không dùng latest
Thử ngay: chạy docker history <image của bạn> và nhìn cột SIZE. Layer nào to bất thường thường là một lệnh COPY . . đang kéo theo thứ không cần.
Bài sau trong series: Docker Compose cho máy dev, dựng ba database bằng một lệnh và bốn cái bẫy mình dính khi làm vậy. Dockerfile của bạn đang chạy bằng root hay user thường? Comment cho mình biết với.
P.S. Phần cấu hình next.config cho standalone và chuyện file tracing, mình hay hỏi skill nextjs-turborepo-stack trong PrimeKit, bộ skill mình tự làm. Skill nắm cách build, cache và tối ưu app Next.js, đỡ phải lục tài liệu khi Next đổi tên tuỳ chọn giữa các phiên bản. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:nextjs-turborepo-stack kèm câu hỏi. Đo kích thước image và kiểm app chạy đúng sau khi đóng gói thì vẫn phải tự làm.
Tài liệu để đọc thêm
- Multi-stage builds, Docker Docs
- Build context và .dockerignore, Docker Docs
- output: standalone, Next.js Docs
Series khác của mình
- SQL thực chiến: Những bài học mình ước đã biết sớm hơn: viết query dễ đọc, đọc execution plan, lỗi NULL và N+1 không báo lỗi, schema và transaction, phân trang bằng con trỏ.
- Backend .NET thực chiến: những case hay gặp trên production: async/await làm treo API, HttpClient hết socket, EF Core kéo cả bảng, idempotency, outbox, caching, bảo mật API.
- Front End thực chiến: những bài toán UI mà tutorial không dạy: ngày giờ và giờ mùa hè, tầng dữ liệu theo hợp đồng API, chart, in ấn và accessibility, Outlook Add-in, E2E với Playwright.
- Dùng AI hiệu quả trong công việc: kinh nghiệm thực chiến của dev: viết prompt đủ ngữ cảnh, bắt AI bịa API, giao việc cho agent, review code AI viết, debug, đọc codebase lạ, đóng gói quy trình thành skill.
All rights reserved