Archivo .env: qué es, ejemplo y por qué va en .gitignore

Un archivo .env es un archivo de texto donde guardas la configuración de tu app que no debe ir dentro del código: la URL de tu base de datos, llaves de API, contraseñas de servicios. Cada línea tiene la forma NOMBRE=valor. Tu app lee esos valores al arrancar. Como suele contener secretos, nunca debe subirse a GitHub: por eso se agrega al .gitignore.

El punto al inicio del nombre (.env) hace que el archivo quede oculto en macOS y Linux; por eso a veces “no lo ves” en tu carpeta.

.env file example (ejemplo)

Así se ve un .env típico en un proyecto de Vite con Supabase y Stripe:

# Supabase
VITE_SUPABASE_URL=https://abcdefgh.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6...

# Stripe (llave pública, para el navegador)
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_51H...

# Solo servidor: NUNCA con prefijo VITE_
STRIPE_SECRET_KEY=sk_test_51H...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6...

Reglas de formato:

• Una variable por línea, sin espacios alrededor del =.
• Las líneas que empiezan con # son comentarios.
• Si el valor tiene espacios, ponlo entre comillas: NOMBRE_NEGOCIO="Tacos Don Pepe".

Por qué existe el .env

1. Separar secretos del código. El código se comparte; las llaves no.
2. Cambiar de entorno sin tocar el código. En tu computadora apuntas a una base de datos de pruebas; en producción, a la real. Mismo código, distinto .env.
3. Que cada persona tenga sus propias llaves.

.env y .gitignore

El .gitignore es un archivo que le dice a git qué no subir al repositorio. Debe incluir:

# .gitignore
.env
.env.local
.env.*.local
node_modules
dist

Para comprobar que tu .env no está en git:

git ls-files | grep .env

Si aparece .env (y no solo .env.example), está en el repositorio. Sácalo así:

git rm --cached .env
echo ".env" >> .gitignore
git commit -m "quita .env del repositorio"
git push

Ojo: esto lo quita de ahora en adelante, pero sigue en el historial. Cualquier llave que haya estado ahí debe considerarse expuesta y cambiarse. Te explicamos cómo en qué hacer si tu API key está expuesta.

.env.example

Es la “plantilla” del .env: mismos nombres, valores vacíos o de ejemplo. Este sí se sube al repositorio.

# .env.example
VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=
VITE_STRIPE_PUBLISHABLE_KEY=
STRIPE_SECRET_KEY=

Así, quien clone el proyecto (o tu yo del futuro) sabe qué variables necesita:

cp .env.example .env
# y llena los valores

Lo más importante: no todo lo que está en .env es secreto

En apps de frontend (React, Vite), las variables con prefijo VITE_ (o NEXT_PUBLIC_ en Next.js) se copian dentro del JavaScript que descarga el navegador. Cualquiera puede verlas. La documentación de Vite lo advierte: no pongas información sensible en variables VITE_.

Tipo de llave	¿Puede ir en el navegador?
URL de Supabase y llave anon / publishable	Sí, están hechas para eso (si tienes RLS bien configurado)
Llave pública de Stripe (pk_...)	Sí
service_role de Supabase	No, nunca
Llave secreta de Stripe (sk_...)	No, nunca
API key de OpenAI, Gemini, etc.	No; llámalas desde el servidor

Más detalle en service role key expuesta.

.env, .env.local, .env.production: cuál se usa

En muchos proyectos verás varios archivos parecidos. En Vite (lo que usan Lovable, Bolt y muchas apps de React) funcionan así:

• .env: se carga siempre.
• .env.local: se carga siempre también, pero está pensado solo para tu computadora; git lo ignora por convención.
• .env.development y .env.production: se cargan solo en ese modo (npm run dev usa development; npm run build, production).
• Si la misma variable está en dos archivos, gana el más específico (por ejemplo, .env.production.local sobre .env).

Next.js usa una lógica muy parecida. Si un valor “no cambia” aunque lo editaste, revisa que no esté repetido en otro de estos archivos.

Cómo se lee el .env en tu código

El archivo no hace nada por sí solo: algo tiene que leerlo.

• Vite / React: import.meta.env.VITE_SUPABASE_URL. Solo están disponibles las variables con prefijo VITE_.
• Node.js: las versiones recientes de Node leen el archivo con node --env-file=.env app.js; en versiones anteriores se usa la librería dotenv. Luego accedes con process.env.NOMBRE.
• Python: con python-dotenv (load_dotenv()) y luego os.environ["NOMBRE"].

Si tu app dice que una variable es undefined o None, casi siempre es una de tres cosas: el nombre está mal escrito, falta el prefijo correcto o no reiniciaste el programa.

Y en Lovable, Bolt o Replit, ¿dónde está mi .env?

Las herramientas de IA manejan esto de forma distinta, y conviene saberlo antes de pegar una llave en el chat:

• En Replit, los secretos van en la herramienta Secrets del proyecto, no en un archivo visible; tu código los lee como variables de entorno normales.
• En Lovable con Supabase, las llaves que solo deben vivir en el servidor (por ejemplo, la de OpenAI o la secreta de Stripe) se guardan como secretos de las Edge Functions de Supabase, no en el código del frontend.
• En Bolt y proyectos exportados, normalmente sí hay un archivo .env en la raíz.

Los menús cambian con cada versión; revisa la documentación de tu herramienta. La regla no cambia: lo secreto, en el servidor.

Cómo comprobar que no se te fue un secreto al navegador

Después de npm run build, busca prefijos de llaves secretas dentro de la carpeta que se publica:

grep -rE "sk_live|sk_test|service_role|sk-proj" dist/

Si aparece algo, ese secreto está en el JavaScript público: muévelo al servidor y cámbialo.

El .env en el hosting

Vercel, Netlify y similares no leen tu archivo .env (y no deberían, porque no está en el repo). Ahí las variables se agregan en el panel del proyecto, con el mismo nombre exacto. Si tu app funciona en tu computadora pero no publicada, revisa esto primero. Ver variables de entorno en Vite y React.

Errores comunes

• Subir .env a un repositorio público.
• Poner llaves secretas con prefijo VITE_ “para que funcione”.
• Espacios alrededor del = (NOMBRE = valor).
• Olvidar reiniciar npm run dev después de cambiar el .env.
• Pegar el .env completo en un chat de IA.

Si no sabes si tus llaves quedaron expuestas, o tu app hecha con IA tiene secretos en el código del navegador, en Black Engine lo revisamos contigo por WhatsApp. Puedes empezar con la checklist de seguridad para apps hechas con IA.