Variables de Entorno

Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…

Dónde viven

Abre tu proyecto en Orbit y haz clic en la pestaña Env vars, en /orbit/<project-id>/env-vars.

La página está organizada en secciones:

All environments en la parte superior: variables de nivel de proyecto, disponibles en cada compilación.
Una sección contraíble por entorno (Production, Staging y cualquier vista previa) que contiene los valores que anulan los de ese entorno.

Encima de la lista hay un cuadro de búsqueda y un filtro Secrets only, que son la forma rápida de navegar una lista larga.

Cómo funciona el alcance

Alcance	Lo que afecta
All environments (a nivel de proyecto)	Se inyecta en cada compilación de este proyecto
Anulación a nivel de entorno	Se aplica solo a ese entorno, y prevalece sobre el valor a nivel de proyecto con la misma clave

El subtítulo en la página expresa la regla claramente: las variables de nivel de proyecto están disponibles en cada compilación, y los valores que anulan los de nivel de entorno tienen prioridad.

Una configuración típica es una DATABASE_URL a nivel de proyecto que apunta a una base de datos de prueba, con una anulación a nivel de producción que apunta a la real. Las compilaciones de producción obtienen la base de datos real, todo lo demás obtiene la de prueba, y nada que agregues después filtrará accidentalmente las credenciales de producción a una vista previa.

También hay un control Available in en las variables a nivel de proyecto, que te permite excluir tipos de entorno particulares (production, staging, preview) de una variable que de otro modo sería a nivel de proyecto.

Encontrarás detalles completos sobre el alcance por entorno, incluido el razonamiento de seguridad, en Establecer variables de entorno por entorno.

Una variable a nivel de proyecto se inyecta en compilaciones de vista previa de rama, y las URLs de vista previa son accesibles públicamente por cualquiera que tenga el enlace. Las credenciales de base de datos de producción, las claves de pago activas y los tokens de administrador deben limitarse solo a producción. Esta es la cosa más importante en la que acertar en esta página.

Agregar una variable

Desplázate al formulario Add variable en la parte inferior de la pestaña Env vars.
Introduce la KEY, por ejemplo NEXT_PUBLIC_API_URL.
Introduce el value.
Elige un Scope: All environments (project-wide), o una anulación de entorno específico.
Si elegiste a nivel de proyecto, usa los botones Available in para deseleccionar cualquier tipo de entorno al que no deba llegar esta variable.
Marca Mark as secret para cualquier cosa sensible.
Haz clic en Add.

El formulario te indica qué está a punto de hacer antes de que confirmes: una anulación de entorno muestra un aviso diciendo que se aplicará solo a las compilaciones de ese entorno, y una variable a nivel de proyecto restringida muestra en qué tipos de entorno se inyectará.

Cuándo entran en vigor los cambios

Agregar, editar o eliminar una variable no cambia la implementación que está en vivo actualmente. Las variables se inyectan cuando se ejecuta una compilación, por lo que el cambio se aplica desde la siguiente implementación en adelante. Vuelve a implementar después de cambiar cualquier cosa de la que tu aplicación dependa.

Orbit es explícito al respecto. Abre la página de detalle de una implementación y, si la configuración ha cambiado desde que fue compilada, recibirás un aviso Environment variables updated since this deployment indicándote que el cambio no entrará en vigor hasta que vuelvas a implementar.

Secretos

Marca Mark as secret para cualquier cosa que no pegarías en un chat: claves API, contraseñas de base de datos, tokens, claves de firma.

Los valores secretos se enmascaran en el panel y llevan una insignia secret. Los valores no secretos muestran un marcador (plain).

El valor de un secreto no puede ser leído nuevamente después de guardarlo, ni por ti ni por nadie más en el panel. Puedes reemplazarlo (haz clic en el icono de edición, escribe un nuevo valor, guarda) pero no puedes revelarlo. Mantén tu propia copia en un gestor de contraseñas antes de guardarlo aquí.

Orbit también registra cuánto tiempo ha estado un valor en su lugar y muestra una insignia de antigüedad en variables más antiguas, con una sugerencia de rotación. Es un empujón, no una obligación.

Editar y eliminar

Haz clic en el icono de edición junto a una variable para cambiar su valor. Haz clic en Delete para eliminarlo y confirma: el diálogo advierte que las compilaciones que dependan de él se romperán, que es la descripción exacta de lo que sucede en la siguiente implementación.

Importación y exportación en lote

Dos botones en la parte superior de la pestaña manejan el trabajo en lote.

Import .env abre un cuadro de pegado. Pega el contenido de un archivo .env, elige un alcance, y Orbit te dice cuántas variables detectó y cuántas marcará como secreto. Marca claves automáticamente basándose en sus nombres, así que cualquier cosa que contenga SECRET, TOKEN, KEY, PASSWORD y similares se marca como secreto antes de la importación. Hay una opción Overwrite existing variables with the same key, desactivada por defecto.

Download .env produce una plantilla que contiene solo los nombres de variable, sin valores. Está pensada para compartir con un compañero que luego complete sus propios valores, no para usarla como copia de seguridad.

Descargar una plantilla .env nunca incluye valores, incluidos los de variables no secretas. No hay forma de exportar valores desde Orbit. Si necesitas una copia de un valor, tómalo de dónde lo generaste originalmente.

Copiar variables entre entornos

El panel Copy variables between environments copia un conjunto completo de un alcance a otro. Elige un From (a nivel de proyecto o un entorno específico) y un To, opcionalmente marca Overwrite variables that already exist in the target, y haz clic en Preview para ver exactamente cuántas se agregarán, actualizarán y omitirán antes de confirmar.

También hay una página Env sync check que compara producción y puesta en escena clave por clave e informa qué está solo en una, qué difiere y qué coincide. Es la herramienta correcta para "por qué funciona la puesta en escena y la producción no".

Compartir variables entre proyectos

Si varios proyectos necesitan la misma credencial, usa un env group en lugar de copiarlo en cada proyecto. Ve a Orbit, luego Env groups, crea un grupo, agrega variables a él, y vincula los proyectos que lo necesitan.

Las variables de grupo se inyectan en tiempo de compilación, y las variables a nivel de proyecto y a nivel de entorno tienen prioridad sobre las variables de grupo. Puedes tener hasta 20 grupos en una cuenta.

Notas del marco

Qué variables llegan al navegador lo decide tu marco, no Orbit. Orbit inyecta todo en alcance; el marco decide qué exponer.

Next.js: las claves con prefijo NEXT_PUBLIC_ se incluyen en el paquete del navegador en tiempo de compilación. Todo lo demás se queda en el servidor.
Vite: las claves con prefijo VITE_ se exponen al navegador. Todo lo demás es solo en tiempo de compilación.
Aplicaciones Node.js: todo en alcance está en process.env durante la compilación, y en tiempo de ejecución cuando Server mode está activado.

Nunca marques un valor como secreto y luego también lo prefijes con NEXT_PUBLIC_ o VITE_. La bandera de secreto solo controla si el panel te muestra el valor; el prefijo controla si tu marco lo envía al navegador de cada visitante. El prefijo gana.

Verificar qué realmente recibió una compilación

Cada página de detalle de implementación enumera las claves de variable de entorno que se inyectaron en tiempo de compilación, y las compara con tu configuración actual: agregadas, cambiadas, eliminadas e inalteradas. Las claves de color azul verdoso provienen de una anulación específica del entorno, las grises de nivel de proyecto. Los valores nunca se almacenan ni se muestran, pero pasar el cursor sobre una clave da una huella dactilar SHA-256, que es suficiente para confirmar que dos entornos contienen el mismo valor sin revelarlo.

Esta es la respuesta definitiva a "¿mi variable realmente está llegando a la compilación?". Verifica esto antes de cambiar cualquier otra cosa.

Solución de problemas

La variable no está definida en tiempo de ejecución. Verifica que la implementación sea posterior al cambio, luego verifica que el alcance cubra este entorno, luego verifica las reglas de prefijo del marco arriba. En ese orden.

Funciona en producción pero no en una vista previa. La variable tiene alcance solo de producción, o una variable a nivel de proyecto tiene preview deseleccionado bajo Available in. Eso generalmente es deliberado.

Funciona localmente pero no en la compilación. Tu archivo .env local no está en el repositorio, y no debería estarlo. Impórtalo con Import .env y elige el alcance correcto.

La puesta en escena carece de todo lo que tiene producción. Activa Inherit production env vars en Settings, bajo Staging: environment variables, o usa Copy variables between environments.