Hình ảnh Docker Next.js với đầu ra: 'standalone': bản dựng nhiều giai đoạn và không phải root
Tại sao lại độc lập
Hình ảnh Next.js thông thường sao chép toàn bộ node_modules cùng với devDependency, nguồn và bộ nhớ đệm bản dựng. Với output: 'standalone' Next.js, khi được xây dựng, sẽ theo dõi những tệp nào máy chủ thực sự cần và đặt chúng vào .next/standalone cùng với [[VB_9_CODE] tối thiểu]. Chỉ cái này, tĩnh và public mới xuất hiện trong hình ảnh cuối cùng.
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone",
};
export default nextConfig;Trong kho lưu trữ đơn, hãy thêm outputFileTracingRoot cùng với đường dẫn đến thư mục gốc của kho lưu trữ, nếu không dấu vết sẽ không tìm thấy các gói từ các thư mục lân cận.
##Tệp Docker
# syntax=docker/dockerfile:1
FROM node:22-bookworm-slim AS base
ENV NEXT_TELEMETRY_DISABLED=1
WORKDIR /app
# 1. Только зависимости — слой кэшируется, пока не меняется lock-файл
FROM base AS deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
# 2. Сборка
FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ARG NEXT_PUBLIC_SITE_URL
ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
RUN npm run build
# 3. Рантайм
FROM base AS runner
ENV NODE_ENV=production \
PORT=3000 \
HOSTNAME=0.0.0.0
COPY --from=builder --chown=node:node /app/public ./public
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
USER node
EXPOSE 3000
CMD ["node", "server.js"]Phân tích các giải pháp:
- Ba giai đoạn. Trình biên dịch, devDependency và nguồn vẫn ở các giai đoạn trung gian và không có ở hình ảnh cuối cùng.
- `--mount=type=cache` bảo toàn bộ đệm npm giữa các bản dựng trên cùng một máy. Đây là hàm BuildKit, do đó có dòng
# syntaxở đầu. - `HOSTNAME=0.0.0.0`.
server.jsnghe địa chỉ từ biến này. Nếu không có nó, máy chủ có thể liên kết với tên vùng chứa và cổng được chuyển tiếp sẽ phản hồi khi có lỗi kết nối. - Số liệu thống kê được sao chép riêng.
.next/standalonekhông chứa.next/staticvàpublic- đây là nguyên nhân phổ biến gây ra lỗi 404 trên CSS và JS sau bản dựng đầu tiên. - `USER node`. Hình ảnh Nút chính thức đã có người dùng không có đặc quyền
node(uid 1000). Không cần thiết phải tạo tệp của riêng bạn nhưng các tệp phải được sao chép từ--chown, nếu không quá trình sẽ không thể ghi vào.next/cacheđể tối ưu hóa ISR và hình ảnh.
Biến môi trường: bản dựng và thời gian chạy
Các biến NEXT_PUBLIC_* được thay thế thành JavaScript máy khách trong next build. Đã quá muộn để chuyển chúng bằng docker run - gói đã chứa giá trị từ tập hợp hoặc trống. Do đó, chúng trải qua ARG trong giai đoạn xây dựng.
Ngược lại, bí mật máy chủ (DATABASE_URL, khóa API không được đưa vào hình ảnh. Không chuyển chúng dưới dạng ARG và không sao chép .env - đặt chúng khi khởi động:
docker run -d --env-file /etc/myapp/prod.env -p 127.0.0.1:3000:3000 myapp:1.4.0
Và hãy chắc chắn .dockerignore, nếu không COPY . . sẽ kéo những thứ không cần thiết vào bối cảnh hợp ngữ, bao gồm cả các bí mật:
node_modules .next .git .env* *.log coverage
PID 1 và dừng container
Quá trình nút chạy dưới dạng PID 1 không nhận được hành vi lõi tiêu chuẩn cho tín hiệu. Nếu ứng dụng không có trình xử lý SIGTERM thì docker stop sẽ đợi thời gian chờ (10 giây theo mặc định) và tắt quy trình thông qua SIGKILL, chấm dứt các yêu cầu đang hoạt động. Một giải pháp đơn giản là quá trình init:
# compose.yml
services:
web:
image: myapp:1.4.0
init: true
env_file: /etc/myapp/prod.env
ports:
- "127.0.0.1:3000:3000"
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
interval: 30s
timeout: 5s
retries: 3Hình ảnh mỏng không có curl, do đó, việc kiểm tra tình trạng được viết bằng chính Node: fetch toàn cầu có sẵn trong Node 18 trở lên.
Hình ảnh và sắc nét
Trong Next.js 15, sharp được kết nối tự động với next start và ở chế độ độc lập; không cần phải cài đặt thủ công. Nếu bạn vẫn thấy cảnh báo về việc thiếu sắc nét, hãy kiểm tra xem bản dựng và thời gian chạy có trên cùng một nền tảng hay không: các tệp nhị phân được biên dịch cho glibc không hoạt động trên Alpine (musl) và ngược lại. Do đó, trong ví dụ này, tất cả các giai đoạn đều từ một hình ảnh cơ bản.
Cách kiểm tra kết quả
docker build -t myapp:test --build-arg NEXT_PUBLIC_SITE_URL=https://example.com . docker image ls myapp:test # размер образа docker run --rm myapp:test id # uid=1000(node), не root docker run --rm myapp:test ls -la .next # владелец node
Để phân tích những gì chiếm không gian trong các lớp, công cụ dive rất tiện lợi. Nếu hình ảnh cuối cùng lớn bất ngờ, nó thường chứa toàn bộ node_modules: kiểm tra xem không có COPY . . trong đường chạy.
##Những lỗi thường gặp
Error: EACCESkhi ghi vào.next/cache- các tệp được sao chép mà không có--chown.- Trang web hoạt động nhưng không có kiểu - họ quên sao chép
.next/static. NEXT_PUBLIC_*trống trong trình duyệt - được truyền khi chạy, không phải trong khi lắp ráp.- Xây dựng trên máy Mac với Apple Silicon, chạy trên máy chủ amd64 - bạn cần
docker buildx build --platform linux/amd64, nếu không thì các mô-đun gốc có kiến trúc sai.
Khi không cần độc lập
Nếu quá trình triển khai chuyển sang Vercel hoặc nền tảng khác có tổ hợp riêng, cài đặt này sẽ không cung cấp bất kỳ điều gì. Để xuất tĩnh (output: 'export'), hoàn toàn không cần máy chủ - nginx với static là đủ.