v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T10:04:00.000Z▲ 0 upvotes

Imagen de Next.js Docker con salida: 'independiente': compilación de varias etapas y no raíz

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

¿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 # syntax al principio.
  • `HOSTNAME=0.0.0.0`. server.js escucha 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/standalone no contiene .next/static y public - 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/cache para 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: 3

La 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: EACCES al 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.

Обсуждение (0)

Ещё на vbcd4u.com