0Pricing
Frontend Academy · Lección

Variables de entorno en CI

Almacene secretos en GitHub Secrets, inyéctelos en la compilación como variables de entorno y acceda a ellos en Vite con import.meta.env o en Next.js con process.env.

Variables de entorno en CI es una lección gratuita de Frontend Academy en CoddyKit. Esta es la lección 3 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Frontend Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Frontend Academy incluye 4 lecciones en total.

¿Por qué usar distintos entornos?

Las aplicaciones necesitan valores diferentes en cada entorno: URL de la API de desarrollo, URL de la API de staging y URL de la API de producción. Además, hay secretos (claves de API y tokens) que nunca deben terminar en el repositorio. Las variables de entorno son la forma estándar de inyectar estos valores.

Públicas frente a solo del servidor

Las variables del frontend integradas en el bundle son públicas: cualquiera puede verlas con DevTools. Nunca coloque secretos allí. Las variables del lado del servidor (usadas en funciones serverless, SSR y rutas de API) sí pueden ser secretos reales.

Variables de entorno de Vite

Vite expone al código del cliente las variables con el prefijo VITE_ mediante import.meta.env.

# .env
VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAGS={"newOnboarding":true}

# In code:
const apiUrl = import.meta.env.VITE_API_URL;

# DEV_ONLY or NEVER PREFIXED vars are NOT exposed:
SECRET_KEY=xxx  # not accessible to client code

Variables de entorno de Next.js

Next utiliza el prefijo NEXT_PUBLIC_ para las variables públicas. Las variables exclusivas del servidor no llevan prefijo (se usan en Route Handlers y getServerSideProps).

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com  # client-accessible
DATABASE_URL=postgres://...                  # server-only

# Client:
const url = process.env.NEXT_PUBLIC_API_URL;

# Server (API route):
const db = process.env.DATABASE_URL;

Archivos .env locales

Use .env.local para sus valores personales, y .env.development / .env.production para los valores predeterminados específicos de cada entorno. Añada .env.local a .gitignore; nunca haga commit de secretos.

# .gitignore
.env.local
.env.*.local

# Commit only .env.example with placeholder values:
VITE_API_URL=https://api.example.com
DATABASE_URL=

Almacenamiento de secretos en GitHub Actions

Añada los secretos en Settings → Secrets and variables → Actions del repositorio. Acceda mediante secrets.NAME.

# .github/workflows/deploy.yml
- name: Deploy
  env:
    VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  run: |
    npx vercel --token $VERCEL_TOKEN --prod
    npx sentry-cli releases new $RELEASE

Secretos específicos de cada entorno

GitHub Environments (Settings → Environments) le permiten limitar los secretos a un entorno específico (staging o producción), con puertas de aprobación opcionales.

# Job that requires environment:
deploy-prod:
  environment: production   # requires reviewer approval if configured
  steps:
    - run: deploy
      env:
        DB_URL: ${{ secrets.DB_URL }}  # only prod's DB_URL is exposed

Variables de entorno del proveedor de alojamiento

Vercel, Netlify y Cloudflare exponen las variables de entorno a la compilación y al runtime. Configúrelas en el dashboard o mediante la CLI.

# Vercel:
vercel env add VITE_API_URL production
vercel env add VITE_API_URL preview

# Netlify:
netlify env:set VITE_API_URL https://api.example.com

# Cloudflare Pages:
wrangler pages secret put API_URL

No codifique secretos directamente en los bundles del frontend

Si un valor está en el JavaScript del cliente, es público. Las claves de API para SDK de terceros (la clave publicable de Stripe y la clave de búsqueda de Algolia) están diseñadas para ser públicas. Cualquier otro valor, como las claves de API del servidor, debe permanecer en el backend.

Validación de variables de entorno durante la compilación

Use zod o envalid para hacer fallar las compilaciones si faltan variables de entorno obligatorias.

// env.ts
import { z } from 'zod';

const envSchema = z.object({
  VITE_API_URL: z.string().url(),
  VITE_SENTRY_DSN: z.string().url().optional()
});

export const env = envSchema.parse(import.meta.env);
// Throws helpful error if VITE_API_URL is missing

Tiempo de compilación frente a tiempo de ejecución

Las variables de entorno en tiempo de compilación se integran en el bundle; cambiarlas requiere volver a compilar. Las variables en tiempo de ejecución (rutas de API de Next, Netlify Functions y Cloudflare Workers) se evalúan en cada solicitud. Elija según si el valor debe poder cambiar sin volver a desplegar.

Rotación de secretos

Rote los secretos periódicamente (cada 90 días) y después de cualquier cambio en el equipo. Use 1Password Secrets Automation, AWS Secrets Manager o una herramienta similar para mantener actualizados los secretos en CI sin actualizaciones manuales.

Errores comunes

1) Hacer commit de un .env con secretos reales: use git-secrets para evitarlo. 2) Exponer variables del servidor al cliente (prefijo incorrecto). 3) Olvidar configurar las variables de entorno en los despliegues de vista previa. 4) Mezclar claves de prueba y de producción en el mismo entorno.

Comprobación rápida

¿Por qué las variables de entorno de Vite expuestas al cliente deben llevar el prefijo VITE_?

Repaso: variables de entorno en CI

Variables públicas: llevan prefijo (VITE_, NEXT_PUBLIC_), se integran en el bundle y son visibles para los usuarios. Variables exclusivas del servidor: no llevan prefijo y se usan en rutas de API o SSR. Incluya .env.local en .gitignore y haga commit de .env.example. Use GitHub Secrets para CI y GitHub Environments para limitar el alcance en producción. Los proveedores de alojamiento (Vercel, Netlify y Cloudflare) permiten configurar variables por entorno. Valídelas con zod durante la compilación.

Preguntas frecuentes

¿La lección «Variables de entorno en CI» es gratis?

Sí — el texto completo de «Variables de entorno en CI» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Frontend Academy, actualiza a CoddyKit PRO. El curso de Frontend Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Variables de entorno en CI»?

Almacene secretos en GitHub Secrets, inyéctelos en la compilación como variables de entorno y acceda a ellos en Vite con import.meta.env o en Next.js con process.env. Practicas Frontend Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Frontend Academy?

No se requiere experiencia previa. Frontend Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 3 de 4.

¿Cuánto tiempo toma la lección «Variables de entorno en CI»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Frontend Academy?

Sí. Cada lección de Frontend Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. GitHub Actions para frontend: lint, test y build
  2. Implementación en Vercel, Netlify y Cloudflare Pages
  3. Variables de entorno en CI
  4. Comprobaciones automatizadas con Lighthouse
← Volver a Frontend Academy