Imagen de Next.js Docker con salida: 'independiente': compilación de varias etapas y no raíz
¿Por qué independiente?
Una imagen Next.js normal copia el node_modules completo junto con las dependencias de desarrollo, las fuentes y el caché de compilación. Con output: 'standalone' Next.js, cuando se compila, rastrea qué archivos el servidor realmente necesita y los coloca en .next/standalone junto con el [[VB_9_CODE] mínimo. Sólo esto, estático y public terminan en la imagen final.
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone",
};
export default nextConfig;En un monorrepositorio, agregue outputFileTracingRoot con la ruta a la raíz del repositorio; de lo contrario, el seguimiento no encontrará paquetes de las carpetas vecinas.
Archivo 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"]Análisis de soluciones:
- Tres etapas. Los compiladores, las dependencias de desarrollo y las fuentes permanecen en etapas intermedias y no terminan en la imagen final.
- `--mount=type=cache` conserva el caché npm entre compilaciones en la misma máquina. Esta es una función de BuildKit, de ahí la línea
# syntaxal principio. - `HOSTNAME=0.0.0.0`.
server.jsescucha la dirección de esta variable. Sin él, el servidor puede vincularse al nombre del contenedor y el puerto reenviado responderá con una falla de conexión. - Las estadísticas se copian por separado.
.next/standaloneno contiene.next/staticypublic- esta es una causa común de 404 en CSS y JS después de la primera compilación. - `USER node`. Las imágenes oficiales del Nodo ya tienen un usuario sin privilegios
node(uid 1000). No es necesario crear el suyo propio, pero los archivos deben copiarse desde--chown; de lo contrario, el proceso no podrá escribir en.next/cachepara ISR y optimización de imágenes.
Variables de entorno: compilación y tiempo de ejecución
Las variables NEXT_PUBLIC_* se sustituyen en el JavaScript del cliente durante next build. Es demasiado tarde para transferirlos con docker run: el paquete ya contiene un valor del ensamblaje o está vacío. Por lo tanto, pasan por ARG en la etapa de creación.
Los secretos del servidor (DATABASE_URL, claves API), por el contrario, no deben incluirse en la imagen. No los pase como ARG y no copie .env - configúrelos al inicio:
docker run -d --env-file /etc/myapp/prod.env -p 127.0.0.1:3000:3000 myapp:1.4.0
Y asegúrese de .dockerignore; de lo contrario, COPY . . arrastrará cosas innecesarias al contexto del ensamblado, incluidos los secretos:
node_modules .next .git .env* *.log coverage
PID 1 y parada del contenedor
Un proceso de nodo que se ejecuta como PID 1 no recibe el comportamiento estándar del kernel para las señales. Si la aplicación no tiene un controlador SIGTERM, docker stop espera un tiempo de espera (10 segundos de forma predeterminada) y finaliza el proceso a través de SIGKILL, finalizando las solicitudes activas. Una solución simple es el proceso de inicio:
# 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: 3La imagen delgada no tiene curl, por lo que la verificación de estado está escrita en el propio Nodo: el fetch global está disponible en el Nodo 18 y posteriores.
Imágenes y nitidez
En Next.js 15, sharp se conecta automáticamente con next start y en modo independiente; no es necesario instalarlo manualmente. Si aún ve una advertencia sobre la ausencia de Sharp, verifique que la compilación y el tiempo de ejecución estén en la misma plataforma: los binarios compilados para glibc no funcionan en Alpine (musl) y viceversa. Por lo tanto, en el ejemplo, todas las etapas provienen de una imagen básica.
Cómo comprobar el resultado
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
Para analizar qué ocupa espacio en las capas, es conveniente la herramienta dive. Si la imagen final es inesperadamente grande, generalmente contiene el node_modules completo: verifique que no haya ningún COPY . . en el corredor.
Errores comunes
Error: EACCESal escribir en.next/cache- los archivos se copiaron sin--chown.- El sitio funciona, pero sin estilos - olvidaron copiar
.next/static. NEXT_PUBLIC_*vacío en el navegador - transferido en tiempo de ejecución, no durante el ensamblaje.- Compile en una Mac con Apple Silicon, ejecútelo en un servidor AMD64; necesita
docker buildx build --platform linux/amd64; de lo contrario, los módulos nativos tienen la arquitectura incorrecta.
Cuando no se necesita el sistema independiente
Si el despliegue va a Vercel u otra plataforma con montaje propio, esta configuración no da nada. Para la exportación estática (output: 'export'), no se necesita ningún servidor; nginx con estática es suficiente.