Qué son las variables de entorno y por qué existen
Toda aplicación necesita información para funcionar: la dirección de la base de datos, la clave de una API, la contraseña de un servicio. Esa información cambia de un lugar a otro. En tu computadora, la base de datos es local. En Vercel, la base de datos está en la nube. Una variable de entorno es una forma de guardar esos valores fuera del código, para que la misma app se ejecute en cualquier lugar con solo cambiar la configuración.
🧠 Analogía: la caja fuerte separada del código
Imagina que tu app es una casa y el código es el plano de la casa. Puedes mostrarle el plano a cualquiera, publicarlo en Internet, ponerlo en GitHub. Pero la llave de la puerta no lo dibujas en el plano. Lo guardas en una bóveda aparte.
- •El código y es la planta: igual en todas partes, puede ser pública.
- •Las variables de entorno son la clave de la bóveda: secretas, cambian según el lugar.
- •Cambiar la clave (config) no exige reconstruir la casa (la app).
Cómo el código lee una variable
En vez de escribir el valor directamente en el código, lo lees de la variable de entorno. El nombre habitual es process.env en Node.js.
# INCORRECTO: secreto en el código (cualquiera puede verlo)
const apiKey = "sk-live-9f8a7b6c5d4e3f2a1b0c";
# CORRECTO: el código lee la variable de entorno
const apiKey = process.env.API_KEY;
El código sigue igual en todas partes. Quien define el valor de API_KEY y es el entorno donde se ejecuta la app.
El archivo .env local
En tu computadora, la bóveda tiene un nombre: el archivo .env (con punto al principio). Es un archivo de texto simple, con una variable por línea, en el formato CHAVE=valor. Está en la raíz del proyecto y nunca va a GitHub.
Crear el archivo .env
# En la raíz del proyecto, crea el archivo
$ touch .env
$ nano .env
# Dentro del .env, una variable por línea:
API_KEY=sk-live-9f8a7b6c5d4e3f2a1b0c
DATABASE_URL=postgres://user:senha@host:5432/db
PORT=3000
Sin comillas, sin espacios alrededor de =. Por convención, los nombres se escriben en MAYUSCULAS_CON_GUION_BAJO.
Leer el .env con dotenv
Node.js no lee el archivo .env por sí solo. La biblioteca dotenv carga el archivo y coloca las variables en process.env.
# Instalar la biblioteca
$ npm install dotenv
added 1 package in 1s
# En la parte superior de tu archivo principal (index.js):
require('dotenv').config();
# Ahora process.env.API_KEY funciona
console.log(process.env.PORT);
3000
Frameworks como Next.js y Vite ya leen el .env automáticamente, sin necesitar dotenv.
💡 Consejo: crea un .env.example
Cómo el .env no va a GitHub; quien clone el proyecto no sabrá qué variables completar. La solución es crear un .env.example con las claves pero sin los valores (ej.: API_KEY=). Ese sí lo confirmas con commit: sirve como modelo, sin filtrar secretos.
⚠️ Error común
Problema: "Definí la variable en el .env, pero process.env.API_KEY aparece como undefined."
Solución: Generalmente hay tres causas: (1) olvidaste llamar require('dotenv').config() en la parte superior del archivo; (2) el .env no está en la raíz donde se ejecuta la app; (3) pusiste un espacio o comillas en el valor. Verifica los tres puntos y reinicia la app (las variables se leen solo al iniciar).
Variables en Vercel
Cuando la app se despliega en Vercel, no tiene tu .env local (que tampoco se envió). Entonces tienes que registrar las mismas variables en el panel de Vercel. Se guardan de forma segura y se inyectan en la app en cada deploy. Lo mejor: Vercel separa las variables por entorno (Production, Preview, Development).
Abre la configuración del proyecto
En el panel de Vercel, elige el proyecto y ve a Settings > Environment Variables.
Agrega cada variable
Completa el nombre (Key) y el valor (Value), iguales a los de tu .env.
# Ejemplo de una variable
Key: API_KEY
Value: sk-live-9f8a7b6c5d4e3f2a1b0c
Elige el entorno
Marca dónde se aplica la variable: Producción (sitio en línea), Preview (deploys de branch) y/o Development (local con vercel dev). Puedes tener una base de datos de pruebas en Preview y la base de datos real solo en Production.
Haz un nuevo deploy
Las variables se aplican en el próximo build. Si agregaste una variable después del deploy, necesitas hacer un Redeploy para que entre en vigor.
👁 Qué vas a ver en la pantalla
En la página Environment Variables, cada variable registrada aparece como una línea. El valor queda oculto (se muestra como puntos) y puedes ver en qué entornos está activa:
# Lista de variables en el panel
API_KEY •••••••• Production, Preview
DATABASE_URL •••••••• Production
NEXT_PUBLIC_URL myapp.com All Environments
En Next.js, las variables con el prefijo NEXT_PUBLIC_ quedan visibles en el navegador. Úsalas solo para valores que no son secretos (como la URL pública del sitio).
Variables en GitHub Actions
Si usas GitHub Actions para automatizar pruebas o deploy, los scripts también necesitan secretos: token de deploy, clave de API, contraseña de la base de datos. GitHub guarda estos valores en los Secrets del repositorio. Se mantienen cifrados, nadie puede leerlos y los usas dentro del workflow.
Cómo registrar un Secret
En el repositorio de GitHub, ve a Settings > Secrets and variables > Actions y haz clic en New repository secret.
# Ejemplo de secret registrado
Name: DEPLOY_TOKEN
Secret: ghp_xxxxxxxxxxxxxxxxxxxx
Después de guardar, GitHub nunca vuelve a mostrar el valor. Si lo olvidas, solo tienes que registrarlo de nuevo.
Usar el Secret en el workflow
Dentro del archivo del workflow (.github/workflows/deploy.yml), lees el secret con la sintaxis ${{ secrets.NOME }}.
name: Deploy
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Hacer deploy
# inyecta el secret como variable de entorno
env:
API_KEY: ${{ secrets.API_KEY }}
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
run: npm run deploy
Dentro del step, la app lee process.env.API_KEY como siempre. El secret nunca aparece en los logs: GitHub oculta el valor automáticamente.
💡 Consejo: Secrets vs Variables
GitHub tiene dos pestañas: Secrets (valores secretos, ocultos para siempre) y Variables (valores no secretos, visibles). Usa Secrets para tokens, claves y contraseñas. Usa Variables (se gestionan con ${{ vars.NOME }}) para configuraciones públicas, como el nombre del entorno o la región.
Seguridad: Qué NUNCA debes incluir en un commit
La regla de oro es simple: ningún secreto va a Git. Cuando haces commit de un archivo, queda para siempre en el historial y, si el repositorio es público, cualquier persona en el mundo puede verlo. Los bots revisan GitHub todo el día en busca de claves filtradas para usarlas de forma indebida. La principal defensa es el archivo .gitignore.
El .gitignore protege tu .env
O .gitignore es una lista de archivos que Git debe ignorar. Agrega el .env en esta lista antes de cualquier commit.
# Contenido del archivo .gitignore
.env
.env.local
.env*.local
node_modules/
# Confirma que Git está ignorando:
$ git status
nothing to commit, working tree clean
# El .env NO aparece en la lista. Protegido.
✓ Puedes hacer commit
- ✓O
.gitignore(la lista de exclusión) - ✓O
.env.example(solo las claves, sin valores) - ✓Código que lee
process.env - ✓Configuración pública (URL del sitio, nombre de la app)
✗ NUNCA hacer commit
- ✗El archivo
.envcon valores reales - ✗Claves de API y tokens en el código
- ✗Contraseñas de bases de datos
- ✗Archivos de credenciales (
.pem,.key, JSON de service account)
⚠️ Error común
Problema: "Hice commit del .env por error antes de crear el .gitignore. Borré el archivo e hice commit de nuevo. ¿Se solucionó?"
Solución: No. El valor sigue en el historial de Git y cualquiera puede recuperarlo. Borrarlo ahora no sirve. Trata la clave como filtrada: revócala y genera una nueva en el servicio (consulta el tema 6). Reescribir el historial (con git filter-repo) ayuda, pero si ya llegó a GitHub público, considera que el secreto está comprometido.
Rotación de secretos
Aunque esté bien guardado, un secreto no debe durar para siempre. Rotar y cambiar la clave por una nueva cada cierto tiempo y revocar la anterior. Así, si una clave se filtró sin que te dieras cuenta, tendrá una fecha de vencimiento cercana. Y si tú sabe que se filtró; la rotación es inmediata y obligatoria.
🧠 Analogía: cambiar la cerradura
Nunca sabrías si un exempleado hizo una copia de la llave de tu casa. Por eso, cuando cambias de inquilino, cambia la cerradura: todas las copias antiguas dejan de funcionar de una vez. Eso es exactamente rotar un secreto. La clave nueva entra en vigor; la anterior queda inservible, aunque alguien tenga una copia.
Genera la clave nueva
En el panel del servicio (Supabase, Stripe, etc.), crea una clave nueva. La mayoría permite mantener ambas claves activas por un tiempo para que el cambio no interrumpa la app.
Actualiza en todos los lugares
Cambia el valor en el .env local, en el panel de Vercel y en los Secrets de GitHub. Los tres deben apuntar a la clave nueva.
# Lugares donde vive el secreto
.env (local)
Vercel > Settings > Environment Variables
GitHub > Settings > Secrets
Haz el redeploy y prueba
Sube la nueva versión y confirma que la app funcione con la clave nueva. Solo después pasa al último paso.
Revoca la clave anterior
En el panel del servicio, elimina o desactiva la clave anterior. A partir de aquí, cualquier copia antigua deja de funcionar. Este es el paso que realmente cierra la puerta.
✓ Buenas prácticas
- ✓Rotar los secretos importantes cada 60-90 días
- ✓Revocar INMEDIATAMENTE cualquier clave filtrada
- ✓Usar claves diferentes por entorno (dev / prod)
- ✓Dar a cada clave solo los permisos que necesita
✗ Evitar
- ✗Usar la misma clave durante años sin cambiarla
- ✗Compartir secretos por chat o correo electrónico
- ✗Reutilizar la clave de producción en el entorno de pruebas
- ✗Dejar la clave antigua activa «por si acaso»
🏆 ¡Cerraste la Trilha 2!
Ya sabes subir una app a Vercel, conectar una base de datos en Supabase, consumir APIs y ahora guardar secretos de forma segura. Este es el ciclo completo del deploy moderno: código en Git, app en la nube, datos en la base de datos y configuración en la bóveda. En la próxima trilha, bajarás un nivel y aprenderás a ejecutar todo en tu servidor propio.
📚 Resumen del módulo
Siguiente ruta:
Ruta 3 - Servidor propio (VPS, SSH, firewall y tokens: ejecuta todo en tu propia máquina en la nube)