Gambar Docker Next.js dengan keluaran: 'standalone': build multi-tahap dan non-root
Mengapa mandiri
Gambar Next.js biasa menyalin seluruh node_modules bersama dengan dependensi dev, sumber, dan cache build. Dengan output: 'standalone' Next.js, ketika dibangun, menelusuri file mana yang benar-benar dibutuhkan server dan menempatkannya di .next/standalone bersama dengan [[VB_9_CODE] minimum. Hanya ini, statis dan public yang berakhir di gambar akhir.
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone",
};
export default nextConfig;Di monorepositori, tambahkan outputFileTracingRoot dengan jalur ke root repositori, jika tidak, pelacakan tidak akan menemukan paket dari folder tetangga.
File 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"]Analisis solusi:
- Tiga tahap. Kompiler, dependensi dev, dan sumber tetap berada pada tahap peralihan dan tidak berakhir di gambar akhir.
- `--mount=type=cache` mempertahankan cache npm antar build pada mesin yang sama. Ini adalah fungsi BuildKit, oleh karena itu baris
# syntaxada di awal. - `HOSTNAME=0.0.0.0`.
server.jsmendengarkan alamat dari variabel ini. Tanpanya, server dapat mengikat nama kontainer, dan port yang diteruskan akan merespons dengan kegagalan koneksi. - Statis disalin secara terpisah.
.next/standalonetidak berisi.next/staticdanpublic- ini adalah penyebab umum 404 pada CSS dan JS setelah build pertama. - `USER node`. Gambar Node Resmi sudah memiliki pengguna yang tidak memiliki hak istimewa
node(uid 1000). Tidak perlu membuatnya sendiri, tetapi file harus disalin dari--chown, jika tidak, proses tidak akan dapat menulis ke.next/cacheuntuk ISR dan pengoptimalan gambar.
Variabel lingkungan: build dan runtime
Variabel NEXT_PUBLIC_* diganti ke dalam JavaScript klien selama next build. Sudah terlambat untuk mentransfernya dengan docker run - bundel sudah berisi nilai dari rakitan atau kosong. Oleh karena itu mereka melewati ARG pada tahap pembuat.
Rahasia server (DATABASE_URL, kunci API), sebaliknya, tidak boleh disertakan dalam gambar. Jangan meneruskannya sebagai ARG dan jangan menyalin .env - atur saat startup:
docker run -d --env-file /etc/myapp/prod.env -p 127.0.0.1:3000:3000 myapp:1.4.0
Dan pastikan untuk .dockerignore, jika tidak COPY . . akan menyeret hal-hal yang tidak perlu ke dalam konteks perakitan, termasuk rahasia:
node_modules .next .git .env* *.log coverage
PID 1 dan menghentikan container
Proses Node yang berjalan sebagai PID 1 tidak menerima perilaku kernel standar untuk sinyal. Jika aplikasi tidak memiliki pengendali SIGTERM, docker stop menunggu waktu habis (10 detik secara default) dan menghentikan proses melalui SIGKILL, menghentikan permintaan aktif. Solusi sederhana adalah proses 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: 3Gambar ramping tidak memiliki curl, jadi healthcheck ditulis di Node itu sendiri: fetch global tersedia di Node 18 dan yang lebih baru.
Gambar dan tajam
Di Next.js 15, sharp terhubung secara otomatis dengan next start dan dalam mode mandiri; tidak perlu menginstalnya secara manual. Jika Anda masih melihat peringatan tentang tidak adanya sharp, periksa apakah build dan runtime berada pada platform yang sama: binari yang dikompilasi untuk glibc tidak berfungsi di Alpine (musl), dan sebaliknya. Oleh karena itu, pada contoh, semua tahapan berasal dari satu gambar dasar.
Cara memeriksa hasilnya
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
Untuk menganalisis apa yang memakan ruang dalam lapisan, alat dive mudah digunakan. Jika gambar akhir berukuran besar, biasanya berisi seluruh node_modules: periksa apakah tidak ada COPY . . di runner.
Kesalahan umum
Error: EACCESsaat menulis ke.next/cache- file disalin tanpa--chown.- Situs berfungsi, tetapi tanpa gaya - mereka lupa menyalin
.next/static. NEXT_PUBLIC_*kosong di browser - ditransfer saat runtime, bukan saat perakitan.- Bangun di Mac dengan Apple Silicon, jalankan di server amd64 - Anda memerlukan
docker buildx build --platform linux/amd64, jika tidak, modul asli memiliki arsitektur yang salah.
Ketika mandiri tidak diperlukan
Jika penerapannya dilakukan di Vercel atau platform lain dengan perakitannya sendiri, pengaturan ini tidak memberikan apa pun. Untuk ekspor statis (output: 'export'), server tidak diperlukan sama sekali - nginx dengan statis sudah cukup.