Saltar al contenido

Imagen de Docker más ligera para Next.js: multi-stage y standalone

En la práctica/ 12 min de lectura

Reduce la imagen de Docker de Next.js con un build multi-stage, output: 'standalone', una base slim y un .dockerignore. El Dockerfile completo, línea por línea.

  • Next.js
  • Node.js
  • Rendimiento
En este artículo (9)
  1. Por qué tu imagen de Docker pesa tanto
  2. Build multi-stage: construir en una etapa, correr en otra
  3. output: 'standalone' en Next.js: qué copia y qué no
  4. Imagen base: slim o alpine
  5. .dockerignore: lo que no debe entrar al contexto
  6. Medir el antes y el después
  7. Errores comunes
  8. Preguntas frecuentes
  9. Checklist

Para que tu imagen de Docker de Next.js pese menos, combina cuatro cosas: un build multi-stage que instala y compila en etapas que no se publican, output: 'standalone' para copiar solo el servidor y las dependencias que usa, una imagen base -slim y un .dockerignore que deje fuera lo que sobra.

Aquí tienes el Dockerfile completo explicado línea por línea, qué trae la carpeta standalone y qué no, cuándo elegir slim o alpine, y cómo medir el antes y el después. Probamos la salida standalone con Next.js 16.4.6; el Dockerfile no lo construimos en esta máquina, y lo decimos donde importa.

Por qué tu imagen de Docker pesa tanto

La mayoría de las imágenes pesadas salen de un Dockerfile de una sola etapa como este:

FROM node:24.22.3-bookworm
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]
  1. FROM node:24.22.3-bookworm usa la variante completa. Según la documentación de la imagen oficial de Node, está construida sobre buildpack-deps y trae una gran cantidad de paquetes comunes de Debian. Sirve para compilar, pero tu servidor no los usa.
  2. COPY . . sin .dockerignore mete todo lo que hay en la carpeta: .git, tu node_modules local, un .next viejo y, si existe, tu .env.
  3. npm install instala también las devDependencies: TypeScript, ESLint, las herramientas de pruebas. Hacen falta para compilar, no para correr.
  4. npm run build deja en .next la salida y la caché del build, y todo se queda en la imagen.
  5. npm start corre next start, que necesita el node_modules completo.

Cada instrucción agrega una capa. Borrar archivos en una instrucción posterior no los quita de la capa donde se escribieron: siguen en la imagen, solo que ocultos. Por eso la solución no es limpiar al final, sino no meterlos en la imagen final desde el principio.

la misma app, dos imágenes de Dockerantes · una etapadespués · tres etapasnode:24-bookworm (completa)COPY . . (código, .git, .env)npm install (todas las deps)npm run build (.next, caché)node:24-bookworm-slimstandalone: server.js + deps.next/staticpublicse quedan en la etapa de build:devDependencies, código, cachéalturas ilustrativas: muestran qué capas hay, no cuánto pesanla imagen final lleva solo lo que corremulti-stage de Docker + output: 'standalone' de Next.js

Desliza la figura para verla completa

Build multi-stage: construir en una etapa, correr en otra

Un build multi-stage usa varios FROM en el mismo Dockerfile. Cada uno empieza una etapa nueva, desde cero. La documentación de Docker lo resume así: puedes copiar de forma selectiva artefactos de una etapa a otra y dejar atrás todo lo que no quieres en la imagen final. Las etapas se nombran con AS y se copian con COPY --from. Este es el Dockerfile completo para una app de Next.js, con la misma estructura que el ejemplo with-docker de Next.js:

# syntax=docker/dockerfile:1
ARG NODE_VERSION=24.22.3-bookworm-slim

# 1) deps: install every dependency (dev included) from the lockfile
FROM node:${NODE_VERSION} AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --no-audit --no-fund

# 2) build: compile the app with output: "standalone"
FROM node:${NODE_VERSION} AS build
WORKDIR /app
ENV NEXT_TELEMETRY_DISABLED=1
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# 3) runner: only the standalone server, static files and public
FROM node:${NODE_VERSION} AS runner
WORKDIR /app
ENV NODE_ENV=production \
    NEXT_TELEMETRY_DISABLED=1 \
    PORT=3000 \
    HOSTNAME=0.0.0.0
COPY --from=build --chown=node:node /app/.next/standalone ./
COPY --from=build --chown=node:node /app/.next/static ./.next/static
COPY --from=build --chown=node:node /app/public ./public
USER node
EXPOSE 3000
CMD ["node", "server.js"]
  1. ARG NODE_VERSION antes del primer FROM fija la imagen base en un solo lugar para las tres etapas. Usamos la versión exacta: el 19 de noviembre de 2026 la más reciente de la rama 24 es 24.22.3, un parche de seguridad del 10 de noviembre.
  2. Etapa deps: copia solo package.json y el lockfile, y corre npm ci. Como esta capa depende solo de esos dos archivos, Docker la reutiliza de la caché mientras no cambies dependencias, aunque cambies el código.
  3. Etapa build: trae el node_modules de deps, copia el código y compila. Aquí sí hacen falta las devDependencies.
  4. COPY . . depende del .dockerignore (más abajo): sin él, tu node_modules local pisaría el de Linux.
  5. Etapa runner: arranca otra vez desde la imagen base limpia. NODE_ENV=production, el puerto y HOSTNAME=0.0.0.0 van como variables de entorno.
  6. Los tres COPY --from=build traen solo la carpeta standalone, los estáticos y public. --chown=node:node deja los archivos a nombre del usuario node, que ya existe en la imagen oficial, para que el servidor pueda escribir su caché en .next.
  7. USER node corre el proceso sin root, y CMD ["node", "server.js"] arranca el servidor mínimo en lugar de next start.

Con BuildKit, Docker construye solo las etapas de las que depende la etapa objetivo, y con --target puedes parar en una intermedia, por ejemplo docker build --target build . para revisar qué produjo el build.

tres etapas en un Dockerfile, una sola imagen final1 · depspackage.jsonpackage-lock.jsonnpm cinode_modules (todo)2 · buildCOPY --from=depsCOPY . .npm run build.next/standalone3 · runnerstandalone → ./.next/staticpublicnode server.jscada etapa empieza de cero: solo pasa lo que copias con COPY --fromla imagen que subes es la etapa runner; deps y build no viajanconstruir en una etapa, correr en otraDocker Docs: multi-stage builds; ejemplo with-docker de Next.js

Desliza la figura para verla completa

output: 'standalone' en Next.js: qué copia y qué no

El multi-stage por sí solo no basta: si la etapa final copia el node_modules entero para correr next start, sigues cargando todas las dependencias. La pieza de Next.js es output: 'standalone':

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

Según la documentación de output, durante next build Next.js analiza los import, require y lecturas de archivos de cada página, y con esta opción crea .next/standalone: un server.js mínimo y solo los archivos de node_modules que el servidor usa. Esa carpeta se despliega sin instalar dependencias. Lo que no copia son public ni .next/static, porque la idea es que los sirva un CDN; si los copias a mano, server.js los sirve.

Carpeta o archivo¿Viene en .next/standalone?Dónde va en la imagen
server.jsSí/app/server.js
node_modules rastreadoSí, solo lo que se usa/app/node_modules
.next/staticNo/app/.next/static
publicNo/app/public
.env, .env.productionSí, si next build los leyóMejor que no lleguen: secretos en tiempo de ejecución

Lo probamos con una app mínima en Next.js 16.4.6. Sin copiar nada, server.js respondió 200 en la página y en una ruta de API, pero 404 en el JavaScript de /_next/static y en una imagen de public: la página carga sin estilos ni interactividad. Después del cp que indica la documentación, todo respondió 200, incluida /_next/image, porque sharp viene rastreado dentro de standalone. Como referencia ilustrativa, en esa prueba en Windows el node_modules del proyecto ocupaba 379 MB y la carpeta standalone 33 MB; tu proporción será otra.

Dos variables controlan dónde escucha: PORT (por defecto 3000) y HOSTNAME (por defecto 0.0.0.0). En Docker esto importa: Docker define HOSTNAME en cada contenedor Linux con el hostname del contenedor, según la referencia de ejecución, y server.js lo usaría para escuchar solo en esa dirección. Lo probamos con el nombre de la máquina: la app respondía en ese nombre y no en 127.0.0.1. Por eso el Dockerfile fija HOSTNAME=0.0.0.0, igual que el ejemplo oficial.

Si tu app lee archivos con rutas armadas en tiempo de ejecución, el rastreo puede no verlos: agrégalos con outputFileTracingIncludes. En un monorepo, outputFileTracingRoot le dice desde dónde rastrear.

Imagen base: slim o alpine

La imagen oficial de Node tiene tres familias: la completa, -slim, que trae solo lo necesario para correr node, y -alpine, basada en Alpine Linux, mucho más pequeña, pero con musl en lugar de glibc, lo que puede dar problemas según lo que asuman tus dependencias sobre la libc. bookworm y trixie son versiones de Debian. Leímos los manifiestos del registro de Docker Hub el 19 de noviembre de 2026 (tamaño comprimido de las capas, linux/amd64):

  • node:24.22.3-bookworm: 410 MB.
  • node:24.22.3-bookworm-slim: 81 MB.
  • node:24.22.3-trixie-slim: 83 MB.
  • node:24.22.3-alpine: 63 MB.

En disco ocupan más, porque las capas se descomprimen al bajarlas. Las buenas prácticas de Docker recomiendan Alpine por pequeña; el ejemplo de Next.js usa slim por compatibilidad con paquetes nativos. Las dos posturas tienen sentido: empieza con slim, y prueba alpine si el tamaño es crítico y tus dependencias nativas (sharp, drivers de bases de datos, bcrypt) tienen builds para musl. Si cambias de base, corre la app y sus pruebas, no solo el build.

Dos notas más. Fijar la versión exacta hace visible qué Node corre; cuando salga un parche, cambias una línea y reconstruyes, como explicamos en actualizar Node en Docker. Y si usas el optimizador de imágenes de Next.js en una base con glibc, la guía de self-hosting advierte que puede necesitar configuración extra para no consumir memoria de más; lo vimos en cómo bajé la memoria de un servidor Next.js.

imágenes base de Node para la etapa runneretiquetalibcbajadaqué traenode:24.22.3-bookwormglibc410 MBcompleta: muchos paquetes de Debiannode:24.22.3-bookworm-slimglibc81 MBsolo lo necesario para correr nodenode:24.22.3-trixie-slimglibc83 MBslim sobre Debian 13 (trixie)node:24.22.3-alpinemusl63 MBla más chica; prueba tus deps nativastamaño comprimido de las capas, linux/amd64, Node 24.22.3en disco ocupan más: al bajarlas se descomprimenslim por defecto; alpine si tus deps lo aguantanregistro de Docker Hub, manifiestos leídos el 19 nov 2026

Desliza la figura para verla completa

.dockerignore: lo que no debe entrar al contexto

Cuando corres docker build ., la carpeta es el contexto del build. Según la documentación del contexto, el cliente busca un .dockerignore en su raíz y no envía al builder lo que coincide con sus patrones. Este es un punto de partida:

node_modules
.next
.git
.env*
!.env.example
npm-debug.log*
coverage
test-results
playwright-report
*.md
Dockerfile*
.dockerignore
  1. node_modules: el de tu máquina tiene binarios de tu sistema operativo. Si entra, COPY . . pisa el que instaló npm ci en Linux y el build falla o corre con binarios equivocados.
  2. .next: la salida de un build local. El build del contenedor genera la suya.
  3. .git: el historial completo del repo, que no usa ninguna etapa.
  4. .env* con la excepción !.env.example: los secretos no deben entrar. Next.js copia .env y .env.production a .next/standalone si next build los leyó, así que terminarían en la imagen. Pásalos como variables al arrancar el contenedor. Las NEXT_PUBLIC_ se incrustan en el build, así que van como ARG en la etapa build; repasa qué es público en NEXT_PUBLIC y secretos.
  5. Logs, reportes de pruebas y Markdown: nada de eso corre en producción.
  6. Dockerfile* y .dockerignore: Docker los envía igual porque los necesita, pero COPY no los puede usar.

Los patrones se escriben uno por línea, como los globs de shell; ! crea una excepción y gana la última línea que coincide. Si usas .env.production para valores no secretos del build, agrégalo con !.env.production.

Medir el antes y el después

No te quedes con la sensación de que pesa menos: compara las dos imágenes con la misma app. Guarda el Dockerfile de una etapa como Dockerfile.naive y construye las dos:

docker build -f Dockerfile.naive -t mi-app:antes .
docker build -t mi-app:despues .
docker image ls mi-app
docker image history mi-app:despues
docker run --rm -p 3000:3000 mi-app:despues
  1. Las dos primeras líneas construyen la versión de una etapa y la nueva con etiquetas distintas.
  2. docker image ls mi-app muestra la columna SIZE, que según la referencia es el espacio acumulado de la imagen y sus imágenes padre, base incluida.
  3. docker image history lista cada capa con la instrucción que la creó y su tamaño: ahí ves si una capa grande es la base, las dependencias o un archivo que no debería estar.
  4. docker run la levanta en el puerto 3000. Abre la página y comprueba que respondan con 200 un archivo de /_next/static, uno de public y, si la usas, /_next/image.

Anota los dos números con la fecha y la versión de la base. No publicamos cifras de imágenes porque esta guía no se construyó con un proyecto real: la diferencia depende de tus dependencias, de la base y de lo que tengas en public. Si tu imagen final sigue grande, docker image history te dice en qué capa está el peso.

Errores comunes

  • Olvidar .next/static o public. La página responde 200 pero sin JavaScript, CSS ni imágenes. Standalone no los copia.
  • No definir HOSTNAME=0.0.0.0. Docker pone su propio HOSTNAME y el servidor escucha solo en esa dirección.
  • Copiar el node_modules local. Sin .dockerignore, los binarios de tu máquina pisan los de Linux.
  • Usar next start en la imagen final. Te obliga a copiar todas las dependencias; con standalone es node server.js.
  • Dejar .env en el contexto. Next.js lo copia a standalone y queda dentro de la imagen.
  • Cambiar a alpine sin probar. Un paquete nativo sin build para musl puede fallar recién al arrancar o al usarse, no en el build.
  • Proyecto sin carpeta public. COPY --from=build /app/public falla si no existe; crea la carpeta o quita esa línea.

Preguntas frecuentes

¿Necesito standalone si ya uso multi-stage?

Si la etapa final corre next start, necesita el node_modules de producción completo. Standalone reduce eso a los archivos que el servidor usa de verdad. Las dos técnicas se suman.

¿Standalone funciona con Next.js 15 y 16?

Sí. output: 'standalone' es estable desde Next.js 12.2, según su anuncio de versión, y la configuración es la misma. Lo probamos con 16.4.6, la versión más reciente en npm el 19 de noviembre de 2026.

¿Alpine o slim para Next.js?

Slim, salvo que el tamaño sea crítico. Alpine es más pequeña, pero usa musl; si alguna dependencia nativa no la soporta, lo descubres al correr la app, no al construirla. Si la eliges, prueba la app completa en la imagen.

¿Dónde pongo las variables de entorno y los secretos?

Los secretos, al arrancar el contenedor, desde tu plataforma o tu gestor de secretos. Las NEXT_PUBLIC_, como ARG en la etapa de build, porque se incrustan en el JavaScript. Ninguno debe vivir en un .env dentro del contexto.

Checklist

  • output: "standalone" en next.config.
  • Tres etapas: deps, build y runner, con la misma base fijada en un ARG.
  • package.json y el lockfile se copian antes que el código.
  • La etapa final copia .next/standalone, .next/static y public.
  • PORT y HOSTNAME=0.0.0.0 definidos; arranca con node server.js.
  • Corre como USER node.
  • .dockerignore deja fuera node_modules, .next, .git y .env.
  • Base slim; alpine solo después de probar la app.
  • Mediste con docker image ls y docker image history, y los estáticos responden 200.

Una imagen más chica se baja y arranca más rápido, pero sigue corriendo el Node que tenga su base. Cuando salga un parche, revisa cómo actualizar Node en Docker.

¿Viste esto en Instagram? Comenta DOCKER en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 19 de noviembre de 2026

← Blog