$ man how-to/env-files-explained

Un archivo .env es un archivo de texto plano que almacena valores de configuración que tu aplicación necesita para ejecutarse. API keys, contraseñas de base de datos, URLs de servicios, feature flags. Un par key-value por línea. No se necesitan comillas (aunque algunos parsers las aceptan). Sin sintaxis especial. El archivo se ubica en la raíz de tu proyecto y nunca se hace commit a Git. Tu código lee de él usando process.env.VARIABLE_NAME en Node.js o os.environ en Python. Los valores existen solo en tu máquina. Tu compañero de equipo tiene su propio .env con sus propias keys. Producción tiene su propio conjunto en la plataforma de hosting. El nombre empieza con un punto, lo que lo convierte en un archivo oculto en Mac y Linux. Eso es intencional. No debería ser visible por defecto porque contiene secretos.

PATTERN

Tres problemas que los archivos .env resuelven. Primero, seguridad. Las API keys hardcodeadas en archivos de código fuente terminan en GitHub. Los bots escanean repos públicos buscando keys expuestas dentro de minutos de un push. Las keys de AWS se roban. Las keys de Stripe se roban. Pasa constantemente. Los archivos .env mantienen los secretos fuera del control de versiones completamente. Segundo, portabilidad. Tu máquina local, tu servidor de staging y tu servidor de producción todos necesitan diferentes URLs de base de datos, diferentes endpoints de API, diferentes feature flags. Mismo codebase, diferentes variables de entorno. Despliegas el mismo código en todos lados y el archivo .env le dice cómo comportarse. Tercero, colaboración. Tu compañero de equipo usa sus propias API keys. Tu pipeline de CI usa keys de cuenta de servicio. Nadie comparte credenciales a través de Slack o email. Cada uno tiene su propio archivo .env con sus propios valores.

CODE

Paso 1: Crea el archivo en la raíz de tu proyecto. touch .env Paso 2: Agrega tus variables. Una por línea. Sin espacios alrededor del signo de igual. API_KEY=sk_live_abc123 DATABASE_URL=postgres://user:pass@localhost:5432/mydb NEXT_PUBLIC_SITE_URL=http://localhost:3000 DEBUG=true Paso 3: Agrega .env a tu .gitignore inmediatamente. Esto es innegociable. echo ".env" >> .gitignore echo ".env.local" >> .gitignore echo ".env*.local" >> .gitignore Paso 4: Instala un loader si tu framework no tiene uno integrado. Next.js carga archivos .env automáticamente. Para otros proyectos Node.js, usa dotenv: npm install dotenv Luego en la parte superior de tu archivo de entrada: require('dotenv').config() Paso 5: Accede a las variables en tu código. Node.js: process.env.API_KEY Python: os.environ.get('API_KEY') Next.js (lado del cliente): process.env.NEXT_PUBLIC_SITE_URL El prefijo NEXT_PUBLIC_ en Next.js significa que la variable está expuesta al navegador. Sin ese prefijo, permanece solo del lado del servidor. Esto importa. No pongas keys secretas detrás de NEXT_PUBLIC_.

PATTERN

La mayoría de los frameworks soportan múltiples archivos .env con una prioridad de carga. Next.js los carga en este orden, con archivos posteriores sobrescribiendo a los anteriores: .env (valores base por defecto, se puede hacer commit al repo si no hay secretos) .env.local (sobrescrituras locales, nunca se hace commit) .env.development (solo en modo de desarrollo) .env.development.local (sobrescrituras locales de desarrollo) .env.production (solo en builds de producción) .env.production.local (sobrescrituras locales de producción) Los archivos .local siempre sobrescriben a los archivos no locales. Los archivos específicos de entorno sobrescriben al .env base. Esto te permite hacer commit de valores seguros por defecto en .env mientras mantienes los secretos en .env.local. Un patrón común: .env tiene NEXT_PUBLIC_SITE_URL=https://tusitio.com como el valor por defecto de producción. .env.local lo sobrescribe a http://localhost:3000 para desarrollo local. Sin cambios de código necesarios para alternar entre entornos.

PRO TIP

Error 1: Olvidar agregar .env a .gitignore antes del primer commit. Una vez que un archivo es rastreado por Git, agregarlo a .gitignore después no lo remueve del historial. Necesitas git rm --cached .env para dejar de rastrearlo, luego force push. Si ya hiciste push a un repo público, rota cada key en ese archivo inmediatamente. Las keys antiguas están en el historial de Git para siempre. Error 2: Usar el prefijo NEXT_PUBLIC_ en keys secretas. NEXT_PUBLIC_STRIPE_SECRET_KEY es visible en el bundle del navegador. Cualquiera puede inspeccionarla. Solo usa el prefijo público para valores que son seguros de exponer, como la URL de tu sitio o una API key pública. Error 3: Compartir archivos .env a través de Slack o email. Usa un gestor de contraseñas, un vault de secretos o una herramienta de compartición segura. Los archivos .env en historiales de chat se indexan, cachean y respaldan en lugares que no puedes controlar. Error 4: No crear un archivo .env.example. Esta es una plantilla que muestra qué variables espera tu app, sin los valores reales. Haz commit de esto al repo para que los nuevos desarrolladores sepan qué llenar. API_KEY= DATABASE_URL= NEXT_PUBLIC_SITE_URL=http://localhost:3000 Error 5: Imprimir variables de entorno en logs durante debugging y olvidar remover las sentencias de log. console.log(process.env) vuelca cada secreto a cualquier servicio de logging que uses.

PATTERN

En producción, no usas archivos .env. Configuras variables de entorno directamente en tu plataforma de hosting. Vercel: Settings > Environment Variables. Agrega cada par key-value. Elige a qué entornos aplica (Production, Preview, Development). Railway: pestaña Variables en la configuración de tu servicio. AWS: Parameter Store o Secrets Manager. El principio es el mismo en todos lados. Los secretos viven en la plataforma, no en archivos. Tu código lee de process.env sin importar de dónde vengan los valores. Localmente vienen del .env. En producción vienen de la plataforma. Tu código no necesita saber la diferencia.