Next.js carga variables de entorno desde archivos .env, con una regla de seguridad importante: las variables son solo del servidor por defecto, y solo las que tienen el prefijo NEXT_PUBLIC_ se exponen al navegador.
.env # loaded in all environments
.env.local # local overrides — GITIGNORED (put secrets here)
.env.development # only in `next dev`
.env.production # only in production builds
# .env.local
DATABASE_URL=postgres://...secret... # server-only — NEVER sent to the browser
NEXT_PUBLIC_API_URL=https://api.example.com # exposed to the browser
// Server Component / Route Handler / Server Action — can read anything
const db = process.env.DATABASE_URL; // ✅ works on the server
// Client Component — only NEXT_PUBLIC_* are available
"use client";
const api = process.env.NEXT_PUBLIC_API_URL; // ✅ works
const secret = process.env.DATABASE_URL; // ❌ undefined in the browser
Esta regla de prefijo es una característica de seguridad: te impide enviar accidentalmente contraseñas de base de datos o secretos de API al cliente. Una variable sin prefijo simplemente no existe en los paquetes del navegador.
NEXT_PUBLIC_* are INLINED at BUILD time (baked into the JS bundle).
Porque se incrustan en tiempo de compilación, cambiar un valor NEXT_PUBLIC_ requiere una reconstrucción — y nunca debes poner secretos verdaderos detrás del prefijo (serían visibles en el paquete para todos).
✓ Secrets (DB URLs, API keys) → no prefix, kept server-side, in .env.local (gitignored)
✓ Public config (public API base, analytics id) → NEXT_PUBLIC_
✓ Commit a .env.example documenting required vars (no real values)
El modelo solo de servidor por defecto con la opción NEXT_PUBLIC_ es la barrera de Next.js contra la fuga de secretos al cliente — un error común y grave.
Comprender qué variables llegan al navegador, que los públicos se incrustan en tiempo de compilación, y dónde almacenar secretos (.env.local ignorado por git) es esencial tanto para la funcionalidad como para la seguridad.