Clase 02 · Módulo 07
Variables de entorno y secretos
Variables de entorno y secretos
Qué logras en esta clase
Tus claves quedan fuera del código y sabes cuáles pueden verse y cuáles no.
- Usas un archivo de variables de entorno sin subirlo a GitHub.
- Clasificas cada clave del curso como pública o secreta.
- Cargas las claves en tu alojamiento y evitas que Claude las lea.
02
Una clave en el código termina publicada
Lo que escribes en un archivo del proyecto viaja a GitHub y a tu alojamiento. Una clave no puede vivir ahí.
03
Qué es una variable de entorno
Es un valor con nombre que vive fuera del código. El programa lo pide por su nombre y el entorno donde corre se lo entrega.
- En tu computador, el valor sale de un archivo local.
- En la web publicada, sale de la configuración del alojamiento.
El código es el mismo en ambos lados. Lo que cambia es el valor.
04
El archivo .env
# Solo disponible en el servidor
RESEND_API_KEY="re_valor_inventado"
# Disponible también en el navegador
PUBLIC_NOMBRE_NEGOCIO="Cafetería Ejemplo"Es un archivo de texto en la raíz del proyecto: un nombre, un signo igual y un valor por línea. Astro lo carga al iniciar. Como viste en el módulo 2, va en .gitignore desde antes del primer commit.
05
La pregunta que decide todo
¿Puede esta clave causar daño o gasto si la tiene otra persona?
- Si la respuesta es sí, es un secreto y solo vive en el servidor.
- Si fue diseñada para estar a la vista, puede ir al navegador.
Ante la duda, trátala como secreta. Cada servicio lo indica en su documentación de claves.
06
Las claves de este curso, clasificadas
| Clave | Dónde puede vivir |
|---|---|
Supabase publicable (sb_publishable_...) | Navegador y servidor |
Supabase secreta (sb_secret_...) | Solo servidor |
| Clave de API de Resend | Solo servidor |
| Turnstile, clave de sitio | Navegador |
| Turnstile, clave secreta | Solo servidor |
| Access Token de Mercado Pago | Solo servidor |
Turnstile es el servicio antibots de la clase 4.
07
El prefijo PUBLIC_ en Astro
Astro aplica una regla simple: el código de servidor puede leer todas las variables. El código que va al navegador solo recibe las que empiezan con PUBLIC_.
const nombre = import.meta.env.PUBLIC_NOMBRE_NEGOCIO;Así se lee una variable. Fíjate en import.meta.env: es la forma que usa Astro.
08
PUBLIC_ significa publicar
Ese prefijo no es un detalle de nombre. Es la decisión de incluir el valor en lo que descarga cada visitante.
09
Un esquema que avisa si falta algo
Astro permite declarar tus variables con su tipo y su alcance:
env: {
schema: {
RESEND_API_KEY: envField.string({ context: "server", access: "secret" }),
},
}Esto va en astro.config.mjs. Luego el código la importa desde astro:env/server. La ventaja: si la variable falta, el error aparece al arrancar y con su nombre, no cuando un cliente envía el formulario.
10
Tres lugares, tres juegos de valores
| Entorno | Qué es | De dónde salen las variables |
|---|---|---|
| Local | Tu computador | Archivo local |
| Vista previa | Copia de prueba publicada | Configuración del alojamiento |
| Producción | La web real | Configuración del alojamiento |
Que funcione en uno no dice nada sobre los otros dos. Cada entorno se carga y se prueba por separado.
11
Si publicas en Cloudflare
Según la documentación del adaptador de Astro:
- En local, los secretos van en un archivo
.dev.varsen la raíz del proyecto. - En producción, cada secreto se carga con
npx wrangler secret put NOMBRE. Wrangler es la herramienta de línea de comandos de Cloudflare. - Los valores que no son delicados van en el archivo
wrangler.jsonc, bajovars.
12
El otro archivo que no se sube
En Vercel las variables se cargan en la configuración del proyecto, desde su panel, eligiendo a qué entorno aplica cada una. Los nombres de menú cambian: sigue la documentación vigente del servicio.
13
Que Claude no lea tus claves
En el módulo 2 creaste la regla deny Read(./.env). Si usas .dev.vars, agrega otra igual para ese archivo.
Para que Claude sepa qué variables existen sin ver sus valores, mantén un archivo .env.example con los nombres y valores vacíos. Ese sí se sube a GitHub.
14
Cómo comprobar que nada se filtró
- Ejecuta
npm run build. - En VS Code, abre la búsqueda en todos los archivos.
- Pega un trozo de tu clave secreta y busca dentro de la carpeta
dist. - El resultado debe ser cero coincidencias.
Si aparece, esa clave llegó al navegador. Corrige el código y cámbiala por una nueva.
15
Si una clave se expuso, se cambia
Borrar el archivo o el commit no alcanza. Una clave que salió de tu control se reemplaza por una nueva en el panel del servicio.
16
Falla publicado y en local funciona
Al publicar un formulario, casi siempre es una variable que falta en el alojamiento.
- Lee el error en los registros del alojamiento.
- Compara los nombres de tu archivo local con los cargados en el panel, letra por letra.
- Carga la que falte y vuelve a publicar.
17
Opciones para guardar secretos
| Opción | Cuándo conviene |
|---|---|
| Archivo local + panel del alojamiento | Proyecto de una persona; es lo que usa el curso |
| Gestor de contraseñas como respaldo | Siempre; ahí guardas una copia de cada clave |
| Servicio dedicado de secretos | Equipos de varias personas |
18
Lo que te llevas
- Una variable de entorno es un valor que vive fuera del código y cambia según dónde corre.
- La pregunta para clasificar: ¿causa daño o gasto en manos ajenas?
- En Astro,
PUBLIC_envía el valor al navegador. Un secreto nunca lleva ese prefijo. - Local, vista previa y producción se cargan por separado.
- Una clave expuesta se reemplaza, no se esconde.
19
Hazlo ahora
En 10 minutos:
- Crea
.env.examplecon los nombres de las variables que usará tu formulario, sin valores. - Marca cada una como pública o secreta con la pregunta del daño o gasto.
- Confirma con
git statusque tus archivos de claves no aparecen. - Pídele a Claude que te muestre el contenido de tu archivo de claves y verifica que la regla deny lo impide.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026