Variables de entorno y .env: qué son y por qué tu API key no debería estar nunca en el código

Seguro que en algún momento has visto (o has hecho tú mismo) esto: subes tu proyecto a GitHub para enseñárselo a alguien, y ahí, en mitad del código, está tu clave de la API de OpenAI, la contraseña de tu base de datos, o el token de acceso a algún servicio. Puede parecer una tontería mientras el repositorio es privado o el proyecto es solo un ejercicio... hasta que un día no lo es.

En este artículo vas a aprender qué son las variables de entorno, por qué existen, y cómo usarlas en un proyecto de Node.js para que tus contraseñas y claves nunca lleguen a subirse a GitHub.

El problema: datos sensibles mezclados con el código

Imagina que tienes un archivo db.js con algo así:

const conexion = mysql.createConnection({
  host: "localhost",
  user: "root",
  password: "miContraseñaSecreta123",
  database: "mi_blog"
});

Funciona perfectamente... hasta que subes ese archivo a un repositorio de GitHub. A partir de ese momento, esa contraseña queda para siempre en el historial de Git (aunque luego borres la línea, sigue estando en commits anteriores), visible para cualquiera que tenga acceso al repositorio. Y si es público, para cualquiera del mundo — hay bots que rastrean GitHub constantemente buscando justo este tipo de descuidos.

Lo mismo pasa con claves de API (OpenAI, Stripe, Google Maps...), tokens de acceso, o cualquier dato que no deberías compartir con nadie.

La solución: variables de entorno

Una variable de entorno es un valor que vive fuera de tu código, en el entorno donde se ejecuta el programa, y que tu aplicación puede leer en tiempo de ejecución. En vez de escribir el valor directamente en el código, escribes el nombre de la variable, y ese nombre se sustituye por el valor real según dónde se esté ejecutando el programa.

El archivo anterior, usando variables de entorno, quedaría así:

const conexion = mysql.createConnection({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME
});

process.env es un objeto que Node.js rellena automáticamente con las variables de entorno disponibles. Ahora ese archivo ya no tiene ningún dato sensible — puedes subirlo a GitHub sin problema.

El archivo .env

En local, la forma más cómoda de definir estas variables es un archivo .env en la raíz de tu proyecto:

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=miContraseñaSecreta123
DB_NAME=mi_blog

Sin espacios alrededor del =, y sin comillas salvo que el valor las necesite. Ahora tu aplicación necesita cargar este archivo, y hay dos formas de hacerlo:

1. El paquete dotenv (el más usado, funciona en cualquier versión de Node):

npm install dotenv

Y al principio del todo de tu archivo principal:

require('dotenv').config();

Con esa línea, dotenv lee tu .env y mete cada valor dentro de process.env.

2. Soporte nativo de Node.js (sin instalar nada, desde Node 20.6): si usas una versión reciente (compruébalo con node -v), puedes arrancar tu app así:

node --env-file=.env index.js

Es una opción cada vez más usada porque quita una dependencia del proyecto, aunque todavía te vas a encontrar dotenv en la mayoría del código que veas por ahí, así que merece la pena conocer las dos.

Nunca subas el .env a GitHub

Este es el paso que de verdad importa. Abre (o crea) tu .gitignore y añade:

.env
node_modules/

Si ya habías subido un .env por error antes de añadir esta línea, añadirlo ahora no es suficiente: el archivo ya está en el historial de Git. En ese caso, lo primero es cambiar inmediatamente esas contraseñas y claves (dalas por comprometidas), y luego preocuparte de limpiar el historial.

El archivo .env.example: la buena práctica que te vas a agradecer

Como el .env no se sube al repositorio, cualquiera que clone tu proyecto (incluido tú mismo dentro de unos meses) no tiene ni idea de qué variables necesita definir. La solución es crear un segundo archivo, .env.example, que sí se sube a GitHub, con los mismos nombres de variable pero sin los valores reales:

DB_HOST=
DB_USER=
DB_PASSWORD=
DB_NAME=

Así, cualquiera que descargue tu proyecto solo tiene que copiar ese archivo como .env y rellenar sus propios valores.

¿Y en producción? El caso de Railway (o Vercel, Heroku...)

Aquí viene la parte que más confunde al principio: cuando despliegas tu proyecto en un servicio como Railway, ese archivo .env no existe en el servidor (porque no lo has subido a git). ¿Cómo se definen entonces las variables en producción?

Las plataformas de hosting tienen su propio panel para esto. En Railway, por ejemplo, entras en tu proyecto, vas a la pestaña Variables y las defines ahí manualmente (o las importas de golpe pegando tu .env). Railway las inyecta en el entorno del contenedor donde corre tu app, y tu código las lee exactamente igual, con process.env.LO_QUE_SEA, sin cambiar ni una línea.

Esto tiene una ventaja importante: puedes tener valores distintos en local y en producción (una base de datos de pruebas en tu ordenador, la real en el servidor) sin tocar el código — solo cambia de dónde vienen los valores.

Un aviso si trabajas con React, Vite o similares

Si en algún momento usas variables de entorno en el frontend, ten cuidado: cualquier variable que uses ahí acaba dentro del código JavaScript que se descarga en el navegador del usuario, así que nunca es un sitio seguro para una clave secreta de verdad. Frameworks como Vite incluso obligan a poner un prefijo (VITE_) a las variables que quieres exponer al navegador, precisamente para que sea intencional y no un descuido. Las claves realmente secretas (bases de datos, pagos, etc.) solo deben vivir en el backend.

En resumen

• Nunca escribas contraseñas, claves de API o tokens directamente en tu código.
• Guárdalos en un .env y léelos con process.env (con dotenv o el soporte nativo desde Node 20.6).
• Añade .env a tu .gitignore desde el primer commit.
• Sube un .env.example sin valores para que cualquiera sepa qué variables hacen falta.
• En producción, define las variables en el panel de tu plataforma de hosting, no en un archivo.

Es una costumbre que cuesta cero esfuerzo tomar desde el principio, y te libra de un disgusto serio más adelante.

Si todavía no tienes soltura con .gitignore ni con el primer commit, aquí tienes la guía de Git y GitHub para principiantes. Y si te manejas mejor desde la terminal que con el ratón, échale un vistazo también a los comandos de terminal que más vas a repetir.