Variables de entorno NEXT_PUBLIC_ en Next.js: nunca pongas secretos ahí
Guía/ 12 min de lectura
NEXT_PUBLIC_ copia el valor en el JavaScript del navegador al construir. Cómo se ve en el bundle, qué puede ser público y cómo rotar una clave que se filtró.
- Next.js
- Seguridad
En este artículo (8)
Una variable NEXT_PUBLIC_ en Next.js se copia como texto dentro del JavaScript que descarga el navegador cuando haces next build. Cualquiera que abra tu sitio puede leerla. Por eso solo sirve para valores públicos, como el ID de GA4; las claves secretas van sin prefijo y se usan solo en código de servidor.
Vas a ver cómo queda una clave expuesta en el bundle (lo probamos en una app de prueba con Next 15.5.23 y valores falsos), qué sí puede ser público, dónde usar los secretos y qué hacer si ya se filtró uno. Si estás decidiendo qué componentes van al navegador, empieza por dónde poner 'use client' en Next.js; y si tu API recibe llamadas desde el navegador, lee también por qué CORS no protege tu API.
Qué hace el prefijo NEXT_PUBLIC_
Por defecto, las variables de entorno de Next.js solo existen en el servidor, en el entorno de Node.js. Según la guía de variables de entorno de Next.js, el prefijo NEXT_PUBLIC_ le pide a Next.js que «incruste» el valor: durante next build reemplaza cada process.env.NEXT_PUBLIC_... por el valor literal, y ese valor queda dentro de cualquier JavaScript que se mande al navegador. No es una lectura en tiempo de ejecución: es texto copiado en tus archivos.
La app de prueba tiene este .env.local (los valores son falsos a propósito):
NEXT_PUBLIC_STORE_NAME=Tienda Demo
NEXT_PUBLIC_PAYMENTS_SECRET_KEY=sk_test_FALSO_PUBLICO_123
PAYMENTS_SECRET_KEY=sk_test_FALSO_SERVIDOR_456
PAYMENTS_API_URL=http://localhost:3200/api/fake-provider
NEXT_PUBLIC_STORE_NAMEes un valor público de verdad: el nombre de la tienda ya está en la página.NEXT_PUBLIC_PAYMENTS_SECRET_KEYes el error que estudia este artículo: una clave secreta con el prefijo público.PAYMENTS_SECRET_KEYes la misma clave hecha bien: sin prefijo, solo para el servidor.PAYMENTS_API_URLapunta a un proveedor de pagos falso que corre dentro de la propia demo.
Desliza la figura para verla completa
El valor se congela al construir
La guía lo advierte: después del build, la app ya no responde a cambios en esas variables. Si construyes una imagen de Docker y la promueves a varios entornos, todas las NEXT_PUBLIC_ llevan el valor del momento del build. Lo comprobamos con esta página, que lee una variable de cada tipo después de connection():
import { connection } from "next/server";
export default async function RuntimePage() {
await connection();
return (
<ul>
<li id="public">{process.env.NEXT_PUBLIC_STORE_NAME}</li>
<li id="server">{process.env.STORE_REGION}</li>
</ul>
);
}
await connection()hace que la página se renderice en cada petición, no en el build. Es lo que la guía recomienda para leer variables en tiempo de ejecución.- Construimos con
NEXT_PUBLIC_STORE_NAME=Tienda DemoySTORE_REGION=centro. - Sin reconstruir, cambiamos
.env.localaTienda Cambiadaynorte, y reiniciamosnext start. - Resultado: la página mostró
Tienda Demoynorte. La variable pública se quedó con el valor del build, también en el servidor; la de servidor tomó el nuevo.
Las búsquedas dinámicas no son una protección
La guía dice que las búsquedas dinámicas, como process.env[varName] o const env = process.env seguido de env.NEXT_PUBLIC_..., no se incrustan. Probamos las tres formas en un componente de cliente y esto es lo que pasó en nuestra build:
| Cómo se lee en el componente de cliente | ¿El valor quedó en .next/static? | Valor en el navegador |
|---|---|---|
process.env.NEXT_PUBLIC_STORE_NAME | Sí | El valor |
process.env.PAYMENTS_SECRET_KEY (sin prefijo) | No | undefined |
const env = process.env; y luego env.NEXT_PUBLIC_DYNAMIC_ONLY | Sí, en Next 15.5.23 | El valor |
process.env[name] con name constante | No | undefined |
Una función read(key) que devuelve process.env[key] | No | undefined |
La tercera fila contradice la documentación: con const env = process.env, el valor sí terminó en el chunk. No es una regla, es lo que medimos en esta versión; la conclusión práctica es la misma de todos modos: no uses búsquedas dinámicas ni para esconder un valor ni para leerlo en tiempo de ejecución. Trata toda variable NEXT_PUBLIC_ como pública. Sobre las variables sin prefijo, la guía de Server y Client Components dice que Next.js las reemplaza por un string vacío; en nuestra build quedaron como lectura de un objeto vacío y valían undefined. En los dos casos, el valor no llega.
Cómo se ve una clave expuesta en el navegador
Este es el error clásico: llamar al proveedor de pagos directamente desde un componente de cliente, con la clave secreta en una variable pública.
"use client";
export default function BadPayButton() {
async function pay() {
await fetch("https://api.payments.example/v1/sessions", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.NEXT_PUBLIC_PAYMENTS_SECRET_KEY}` },
});
}
return <button type="button" onClick={pay}>Pay</button>;
}
"use client": el archivo y lo que importa van al navegador.pay()llama a la API del proveedor desde el navegador del cliente.- La cabecera
Authorizationllevaprocess.env.NEXT_PUBLIC_PAYMENTS_SECRET_KEY. Funciona, y justo por eso es peligroso: para funcionar, la clave tiene que estar en el navegador.
Después de next build, buscamos los dos valores en la carpeta que se sirve al navegador:
$ grep -rl "sk_test_FALSO_PUBLICO_123" .next/static
.next/static/chunks/app/bad/page-78203093a6f45326.js
$ grep -rl "sk_test_FALSO_SERVIDOR_456" .next/static
$ grep -o "Authorization:[^}]*" .next/static/chunks/app/bad/page-*.js
Authorization:"Bearer ".concat("sk_test_FALSO_PUBLICO_123")
- La clave con prefijo está en el chunk de la página
/bad, un archivo que se descarga de/_next/static/. - La clave sin prefijo no aparece en ningún archivo de
.next/static. - El fragmento minificado deja la clave en texto plano. Minificar no es cifrar.
Para verla no hace falta tu código fuente: basta abrir las herramientas de desarrollador del navegador, buscar en los archivos JavaScript que cargó la página o descargar el chunk con la URL que aparece en el HTML. Si una clave está en NEXT_PUBLIC_, ya es pública.
Sin prefijo también se puede filtrar
Quitar el prefijo no basta si el valor termina en el navegador por otro camino. Encontramos dos en la demo. El primero: pasar el secreto como prop a un componente de cliente.
import PaymentsWidget from "@/components/PaymentsWidget";
export default function LeakPage() {
return <PaymentsWidget apiKey={process.env.PAYMENTS_SECRET_KEY} />;
}
PaymentsWidget ni siquiera pinta la clave: solo muestra «ready» si existe. Aun así, las props de un componente de cliente viajan serializadas en el payload RSC, dentro del HTML:
$ grep -o 'apiKey[^,]*' .next/server/app/leak.html
apiKey\":\"sk_test_FALSO_SERVIDOR_456\"}]
El segundo: leer process.env.PAYMENTS_SECRET_KEY dentro de un componente con 'use client' y pintarlo. En el navegador vale undefined, pero el componente también se prerenderiza en el servidor, donde la variable sí existe, y el valor quedó escrito en el HTML de la página:
$ grep -o 'id="secret">[^<]*' .next/server/app/probe.html
id="secret">sk_test_FALSO_SERVIDOR_456
La regla que sale de las dos pruebas: un secreto no debe tocar ningún archivo con 'use client', ni como lectura de process.env ni como prop.
Qué sí puede ser público
Una variable pública es la que no te importaría ver publicada mañana. La prueba rápida: si se filtra, ¿tendrías que rotarla? Si la respuesta es sí, no lleva el prefijo.
Desliza la figura para verla completa
- Sí pueden ser públicos: el nombre de la tienda, la URL pública de tu sitio o de tu API, el ID de medición de GA4 o de Google Tag Manager, y las claves que el proveedor llama «publicables» o de cliente, pensadas para usarse en el navegador.
- Nunca: claves secretas de pagos, URLs de bases de datos con usuario y contraseña, tokens de APIs de administración (Shopify Admin, CMS, ERP), secretos para firmar webhooks o sesiones, y claves de servicios que cobran por uso, como APIs de IA o de correo.
Que una clave sea publicable no quiere decir que no tenga límites: si tu proveedor permite restringirla por dominio o por permisos, hazlo.
Dónde usar secretos: route handlers, server actions y componentes de servidor
La forma segura es que el navegador nunca hable con el proveedor usando tu clave: habla con tu servidor y tu servidor habla con el proveedor. En la demo, todo el acceso a la clave vive en un módulo, lib/payments.js:
import "server-only";
export async function createSession() {
const res = await fetch(`${process.env.PAYMENTS_API_URL}/sessions`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PAYMENTS_SECRET_KEY}` },
});
if (!res.ok) throw new Error(`payments: ${res.status}`);
return res.json();
}
export async function getAccountStatus() {
const res = await fetch(`${process.env.PAYMENTS_API_URL}/status`, {
headers: { Authorization: `Bearer ${process.env.PAYMENTS_SECRET_KEY}` },
});
if (!res.ok) throw new Error(`payments: ${res.status}`);
return res.json();
}
import "server-only"convierte en error de build cualquier import de este módulo desde un componente de cliente. Lo probamos: el build falló con «You're importing a component that needs "server-only"».createSession()lee la URL y la clave deprocess.enven el servidor, en tiempo de ejecución.- Si el proveedor responde con error, lanza una excepción con el código de estado, nunca con la clave.
getAccountStatus()usa la misma clave para una lectura; el patrón es idéntico.
Route handler. Para llamadas que llegan por HTTP, como una app móvil u otro servicio tuyo, app/api/checkout/route.js:
import { createSession } from "@/lib/payments";
export async function POST() {
const session = await createSession();
return Response.json({ id: session.id });
}
Devuelve solo el id de la sesión, no la respuesta completa del proveedor: lo que sale del handler llega al navegador. En la demo, POST /api/checkout respondió {"id":"cs_test_FALSO_001"}.
Server action. Para llamarlo desde tu propia interfaz sin escribir un endpoint, app/checkout/actions.js:
"use server";
import { createSession } from "@/lib/payments";
export async function startCheckout() {
const session = await createSession();
return { id: session.id };
}
El botón es un componente de cliente que recibe la acción como prop y nunca ve la clave:
"use client";
import { useState } from "react";
export default function PayButton({ action, children }) {
const [id, setId] = useState(null);
return (
<>
<button type="button" onClick={async () => setId((await action()).id)}>
{children}
</button>
{id && <p role="status">{id}</p>}
</>
);
}
Componente de servidor. La página junta las dos cosas: lee datos con la clave en el servidor y le pasa la acción al botón, app/pago/page.jsx:
import { connection } from "next/server";
import { getAccountStatus } from "@/lib/payments";
import { startCheckout } from "@/app/checkout/actions";
import PayButton from "@/components/PayButton";
export default async function CheckoutPage() {
await connection();
const status = await getAccountStatus();
return (
<main>
<p>{process.env.NEXT_PUBLIC_STORE_NAME} · {status.mode}</p>
<PayButton action={startCheckout}>Pagar</PayButton>
</main>
);
}
await connection()hace que la página se renderice en cada petición, así lee la clave en tiempo de ejecución.getAccountStatus()corre en el servidor; a la página solo le llegastatus.mode.startCheckoutse pasa como prop. Las Server Actions sí se pueden pasar a componentes de cliente; las funciones normales no.- Al hacer clic, el navegador mostró
cs_test_FALSO_001. Revisamos el HTML y todos los archivos JavaScript que cargó la página: la clave del servidor no estaba en ninguno.
Si ya se filtró: cómo rotarla
Si una clave secreta estuvo en una variable NEXT_PUBLIC_ y llegó a producción, considérala comprometida. Quitar el prefijo no la invalida: el JavaScript viejo sigue en cachés, en CDNs y en copias que alguien ya descargó. Estos son los pasos, en orden:
- Crea una clave nueva en el panel del proveedor. Si permite limitar sus permisos a lo que tu servidor usa, hazlo.
- Guárdala sin prefijo en las variables de entorno de tu hosting y mueve el código que la usa al servidor (un route handler, una server action o un módulo con
server-only). - Construye y despliega. Como el valor viejo estaba incrustado en el build, solo un build nuevo lo saca del JavaScript que sirves. Después, busca la clave vieja en
.next/staticpara confirmarlo. - Revoca o elimina la clave vieja en el proveedor. Este es el paso que cierra la fuga.
- Revisa los logs y la actividad del proveedor desde la fecha en que la clave llegó a producción (el historial de git y de tus despliegues te la da): cargos, reembolsos o lecturas de datos que no reconozcas.
- Si la clave llegó a un commit, sigue siendo pública aunque borres el archivo. Ya la rotaste; ahora asegúrate de que tus archivos
.envestén en.gitignore. La guía de Next.js advierte que casi nunca quieres subirlos al repositorio.
Desliza la figura para verla completa
Si la clave mueve dinero o datos de clientes y ya está expuesta, no esperes al deploy: revócala primero y acepta unos minutos de error en el checkout. Un checkout caído se arregla con un deploy; una clave usada por otra persona, no.
Errores comunes
- Poner el prefijo para que «funcione en el cliente». Si el navegador necesita la clave para funcionar, el diseño está mal: mueve la llamada al servidor.
- Pensar que minificado u ofuscado es seguro. En el chunk, la clave sigue en texto plano.
- Leer un secreto en un componente con
'use client'. En el navegador valeundefined, pero si lo pintas, el prerender del servidor lo escribe en el HTML. - Pasar el secreto como prop. Las props de un componente de cliente viajan en el payload, aunque no las muestres.
- Devolver la respuesta completa del proveedor desde un route handler o una server action. Lo que devuelves llega al navegador; devuelve solo lo necesario.
- Cambiar la variable en el hosting y no reconstruir. Las
NEXT_PUBLIC_se quedan con el valor del build. - Quitar el prefijo sin rotar. La clave vieja sigue funcionando para quien la copió.
Preguntas frecuentes
¿Puedo esconder la clave si la divido en partes o la codifico en base64?
No. El navegador tiene que reconstruirla para usarla, así que quien lea el JavaScript también puede. Si el navegador la necesita, no es secreta.
¿Una variable sin NEXT_PUBLIC_ puede llegar al navegador?
Sí, si la pasas como prop a un componente de cliente, si la pintas en uno o si la devuelves desde un route handler o una server action. Lo comprobamos en la demo con las dos primeras.
¿Por qué cambié la variable en el hosting y el sitio sigue con el valor viejo?
Porque las variables NEXT_PUBLIC_ se incrustan en next build. Tienes que volver a construir y desplegar para que cambien.
¿Cómo leo en el navegador un valor que cambia por entorno sin reconstruir?
La guía de Next.js propone exponerlo con tu propia API, o leerlo en el servidor con renderizado dinámico y pasarlo como prop. Hazlo solo con valores públicos.
Checklist
- Ninguna variable con
NEXT_PUBLIC_contiene una clave secreta, un token o una contraseña. - Buscaste los primeros caracteres de tus claves secretas en
.next/staticdespués de un build y no aparecen. - Los módulos que usan secretos empiezan con
import "server-only". - Ningún archivo con
'use client'lee un secreto deprocess.envni lo recibe como prop. - Los route handlers y las server actions devuelven solo los datos que la interfaz necesita.
- Tus archivos
.envestán en.gitignore. - Si una clave estuvo expuesta, la rotaste, la revocaste y revisaste los logs del proveedor.
El prefijo NEXT_PUBLIC_ no es un permiso, es una publicación: lo que lleva, lo lee cualquiera. Para decidir qué partes de tu página son de cliente, sigue con dónde poner 'use client' en Next.js; para proteger la API a la que llama tu navegador, lee por qué CORS no protege tu API. Y si trabajas con un agente de IA en el repo, un hook para proteger tu .env evita que lo lea por accidente.
¿Viste esto en Instagram? Comenta SECRETOS en el Reel y te mando la guía.
Escrito por

Publicado el 30 de octubre de 2026 · actualizado el 1 de noviembre de 2026