Variables de entorno en Next.js con Docker: por qué NEXT_PUBLIC_ se queda congelada en el build
Cambias una variable en el servidor y el navegador sigue viendo la vieja. Qué variables lee Next.js en el build, cuáles en ejecución y cómo organizarlas.
Este blog es de CREA.MBA, un boilerplate de Next.js con auth, pagos y panel de admin ya montados. Ver qué incluye
Despliegas tu app de Next.js en Docker, cambias NEXT_PUBLIC_SITE_URL en el panel de la plataforma, reinicias el contenedor y el navegador sigue usando el valor de antes. O al revés: añades la clave de analítica, la página no la ve, y en el contenedor printenv te la enseña perfectamente.
Docker y Coolify están haciendo lo que deben. Next.js trata las variables de entorno de dos formas muy distintas según su nombre y según desde dónde las leas, y en un despliegue con contenedores la diferencia salta a la vista. Vamos por partes.
Dos momentos: el build y la ejecución
Una app de Next.js pasa por dos fases con entornos distintos:
- El build (
next build), donde se compila el código y se genera el JavaScript que va al navegador. - La ejecución (
next start), donde el servidor atiende peticiones.
En Vercel las dos fases comparten configuración y casi nunca lo notas. En Docker son dos momentos separados, a veces en máquinas distintas, y las variables que existen en uno no tienen por qué existir en el otro.
NEXT_PUBLIC_ se copia literalmente en el bundle
La documentación de Next.js lo explica así: para que una variable sea accesible desde el navegador, Next.js «incrusta» su valor en el JavaScript durante el build, sustituyendo cada referencia a process.env.NEXT_PUBLIC_... por el texto literal. Eso lo activa el prefijo.
// Tu código
initAnalytics(process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID);
// Lo que llega al navegador tras el build
initAnalytics("G-ABC123");La consecuencia, también en palabras de la documentación: después del build, la app ya no responde a cambios en esas variables. Si construyes una imagen de Docker y la despliegas en varios entornos, todas las NEXT_PUBLIC_ se quedan con el valor que tenían al construirla.
Hay dos casos en los que la sustitución ni siquiera ocurre, y tu código recibe undefined sin ningún aviso:
// ❌ No se sustituye: el nombre es dinámico
const key = 'NEXT_PUBLIC_GA_MEASUREMENT_ID';
process.env[key];
// ❌ Tampoco: se lee a través de otra variable
const env = process.env;
env.NEXT_PUBLIC_GA_MEASUREMENT_ID;El reemplazo es textual, así que tiene que encontrar process.env.NEXT_PUBLIC_LO_QUE_SEA escrito tal cual.
Las variables sin prefijo solo existen en el servidor
Todo lo que no lleva NEXT_PUBLIC_ está disponible solo en el entorno de Node.js. En el navegador, process.env.STRIPE_SECRET_KEY vale undefined, que es justo lo que quieres para un secreto.
El problema aparece con código que se usa en los dos lados. Un patrón que hemos visto en más de un proyecto:
// src/config/env.ts
export const isPolarConfigured = Boolean(process.env.POLAR_ACCESS_TOKEN);'use client';
import { isPolarConfigured } from '@/config/env';
export function PaymentWarning() {
if (isPolarConfigured) return null;
return Los pagos no están configurados;
}En el servidor, isPolarConfigured es true. En el navegador, POLAR_ACCESS_TOKEN no existe y el aviso de «pagos no configurados» sale siempre, aunque los pagos funcionen. TypeScript no protesta y el build pasa.
Hay tres arreglos posibles, según el caso:
- Calcularlo en el servidor y pasarlo como prop. El componente de servidor que renderiza
PaymentWarningcomprueba la variable y le pasa un booleano. El secreto nunca sale del servidor. - Exponer solo lo necesario. Si el cliente tiene que saber algo, crea una variable pública que diga solo eso (
NEXT_PUBLIC_PAYMENTS_ENABLED=true), nunca la clave. - Mover el componente al servidor si no necesita interactividad.
Para evitar que un módulo con secretos acabe importado desde el cliente por accidente, el import server-only hace que el build falle si eso ocurre (en Next.js instalar el paquete es opcional, según su documentación; el framework reconoce el import):
// src/lib/payments/config.ts
import 'server-only';Leer variables en tiempo de ejecución en el servidor
Las variables sin prefijo se leen cuando el código se ejecuta… siempre que el código se ejecute en cada petición. Si la página se renderiza de forma estática durante el build, process.env.MI_VARIABLE se evalúa en ese momento y el resultado queda guardado en el HTML.
La documentación de Next.js propone marcar el componente como dinámico antes de leer la variable:
import { connection } from 'next/server';
export default async function Page() {
await connection();
// A partir de aquí, la variable se lee en cada petición
const supportEmail = process.env.SUPPORT_EMAIL;
// ...
}connection() (igual que leer cookies() o headers()) hace que la ruta se renderice bajo demanda. Con eso, la misma imagen de Docker sirve para varios entornos con valores distintos.
Lo mismo vale para el código que se ejecuta al importar un módulo. Si haces const client = new Client(process.env.API_KEY) en el nivel superior y el build importa ese módulo para generar páginas estáticas, la variable se lee en el build. Cuando el contenedor se construye sin esa variable, el cliente queda mal configurado. El limitador de peticiones del boilerplate de CREA.MBA resuelve la REDIS_URL en el primer uso, y no en el constructor, por este motivo: el contenedor se construye sin ella y solo la recibe al arrancar.
Cómo hacer llegar una NEXT_PUBLIC_ al build
Si una variable pública tiene que estar en el bundle, tiene que existir cuando se ejecuta next build.
Con un Dockerfile propio, se declara como argumento de construcción:
ARG NEXT_PUBLIC_SITE_URL
ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
RUN bun run builddocker build --build-arg NEXT_PUBLIC_SITE_URL=https://tudominio.com .En Coolify, cada variable de entorno tiene opciones para decidir si está disponible durante el build, durante la ejecución o en ambos. Las NEXT_PUBLIC_ tienen que estar disponibles en el build, y después de cambiarlas hay que volver a desplegar, no basta con reiniciar. Reiniciar arranca el mismo contenedor con el mismo bundle.
Lo contrario también importa: no marques secretos como variables de build si no hacen falta. Una variable disponible en el build puede acabar en las capas de la imagen o en los logs de construcción.
Y si de verdad necesitas cambiar un valor público sin reconstruir
Hay casos legítimos: una única imagen promovida de staging a producción, o una URL que cambia según el cliente. La documentación de Next.js sugiere montar tu propia API para dar esos valores al cliente. En la práctica, con el App Router hay una forma más sencilla: leerlos en un componente de servidor dinámico y pasárselos al cliente.
// app/layout.tsx (componente de servidor)
import { connection } from 'next/server';
import { PublicConfigProvider } from '@/components/public-config';
export default async function RootLayout({ children }: { children: React.ReactNode }) {
await connection();
const config = {
siteUrl: process.env.SITE_URL ?? '',
supportEmail: process.env.SUPPORT_EMAIL ?? '',
};
return (
{children}
);
}El coste es que todo lo que cuelga de ese layout pasa a renderizarse bajo demanda, así que conviene hacerlo en el layout más bajo que lo necesite. Y lo que pases ahí acaba en el HTML: solo valores que no te importe que vea cualquiera.
También circulan scripts que reemplazan marcadores en los ficheros .js del bundle al arrancar el contenedor. Funcionan, pero tocan el resultado del build en caliente, y preferimos no depender de eso.
Una lista de comprobación antes de desplegar
- Inventario. Lista todas las variables que usa la app y márcalas: secreta de servidor, pública de build, o pública que necesitas cambiar en ejecución.
- Ninguna secreta con
NEXT_PUBLIC_. Lo que lleva el prefijo es público, sin excepciones. Una clave de Stripesk_live_con ese prefijo está en el JavaScript que descarga cualquiera. - Ningún
process.envde servidor dentro de'use client'. Búscalo congrep. Si aparece, es unundefinedesperando a pasar. - Las públicas, disponibles en el build de tu plataforma.
- Tras cambiar una pública, redespliega. Reiniciar no reconstruye.
El último punto tiene un caso que se ve poco: el DSN público de Sentry tiene que estar en el build por dos motivos: el SDK lo necesita y el boilerplate lo usa para construir la política de seguridad de contenido (CSP). Sin él, el navegador bloquea los envíos de errores y no te enteras de nada.
Lo que te llevas
NEXT_PUBLIC_se copia como texto en el bundle durantenext build. Cambiarla exige reconstruir.- Sin prefijo, la variable solo existe en el servidor; en un componente cliente vale
undefined. - Para leer una variable en cada petición, la ruta tiene que ser dinámica (
connection(),cookies(),headers()). - Si un valor público tiene que cambiar sin reconstruir, sácalo de un componente de servidor y pásalo hacia abajo.
La infraestructura de servidor propio la explicamos en Hetzner + Coolify como alternativa a Vercel. El .env.example de CREA.MBA separa las variables por servicio y avisa de las que Coolify tiene que tener en el build, como el DSN de Sentry.
¿Cuánto tiempo perdiste la primera vez que una NEXT_PUBLIC_ no cambiaba?
¿Te gustó este artículo?
Suscríbete para más tutoriales y tips sobre crear productos con IA