0

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 --from=dependencies /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 --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
COPY --from=builder --chown=node:node /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/static và 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.js của standalone nghe theo biến HOSTNAME. Docker lại tự đặt HOSTNAME trong 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 node và --chown=node:node. Image node có sẵn user tên node không phải root. Chuyển sang user đó trước CMD, 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 --from=dependencies /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 --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
COPY --from=builder --chown=node:node /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


Series khác của mình


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí