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)
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"]
FROM node:24.22.3-bookwormusa la variante completa. Según la documentación de la imagen oficial de Node, está construida sobrebuildpack-depsy trae una gran cantidad de paquetes comunes de Debian. Sirve para compilar, pero tu servidor no los usa.COPY . .sin.dockerignoremete todo lo que hay en la carpeta:.git, tunode_moduleslocal, un.nextviejo y, si existe, tu.env.npm installinstala también lasdevDependencies: TypeScript, ESLint, las herramientas de pruebas. Hacen falta para compilar, no para correr.npm run builddeja en.nextla salida y la caché del build, y todo se queda en la imagen.npm startcorrenext start, que necesita elnode_modulescompleto.
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.
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"]
ARG NODE_VERSIONantes del primerFROMfija 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.- Etapa
deps: copia solopackage.jsony el lockfile, y correnpm 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. - Etapa
build: trae elnode_modulesdedeps, copia el código y compila. Aquí sí hacen falta lasdevDependencies. COPY . .depende del.dockerignore(más abajo): sin él, tunode_moduleslocal pisaría el de Linux.- Etapa
runner: arranca otra vez desde la imagen base limpia.NODE_ENV=production, el puerto yHOSTNAME=0.0.0.0van como variables de entorno. - Los tres
COPY --from=buildtraen solo la carpeta standalone, los estáticos ypublic.--chown=node:nodedeja los archivos a nombre del usuarionode, que ya existe en la imagen oficial, para que el servidor pueda escribir su caché en.next. USER nodecorre el proceso sin root, yCMD ["node", "server.js"]arranca el servidor mínimo en lugar denext 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.
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.js | Sí | /app/server.js |
node_modules rastreado | Sí, solo lo que se usa | /app/node_modules |
.next/static | No | /app/.next/static |
public | No | /app/public |
.env, .env.production | Sí, 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.
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
node_modules: el de tu máquina tiene binarios de tu sistema operativo. Si entra,COPY . .pisa el que instalónpm cien Linux y el build falla o corre con binarios equivocados..next: la salida de un build local. El build del contenedor genera la suya..git: el historial completo del repo, que no usa ninguna etapa..env*con la excepción!.env.example: los secretos no deben entrar. Next.js copia.envy.env.productiona.next/standalonesinext buildlos leyó, así que terminarían en la imagen. Pásalos como variables al arrancar el contenedor. LasNEXT_PUBLIC_se incrustan en el build, así que van comoARGen la etapabuild; repasa qué es público en NEXT_PUBLIC y secretos.- Logs, reportes de pruebas y Markdown: nada de eso corre en producción.
Dockerfile*y.dockerignore: Docker los envía igual porque los necesita, peroCOPYno 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
- Las dos primeras líneas construyen la versión de una etapa y la nueva con etiquetas distintas.
docker image ls mi-appmuestra la columnaSIZE, que según la referencia es el espacio acumulado de la imagen y sus imágenes padre, base incluida.docker image historylista 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.docker runla levanta en el puerto 3000. Abre la página y comprueba que respondan con 200 un archivo de/_next/static, uno depublicy, 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/staticopublic. 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 propioHOSTNAMEy el servidor escucha solo en esa dirección. - Copiar el
node_moduleslocal. Sin.dockerignore, los binarios de tu máquina pisan los de Linux. - Usar
next starten la imagen final. Te obliga a copiar todas las dependencias; con standalone esnode server.js. - Dejar
.enven 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/publicfalla 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"ennext.config.- Tres etapas:
deps,buildyrunner, con la misma base fijada en unARG. package.jsony el lockfile se copian antes que el código.- La etapa final copia
.next/standalone,.next/staticypublic. PORTyHOSTNAME=0.0.0.0definidos; arranca connode server.js.- Corre como
USER node. .dockerignoredeja fueranode_modules,.next,.gity.env.- Base slim; alpine solo después de probar la app.
- Mediste con
docker image lsydocker 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

Publicado el 19 de noviembre de 2026