Vercel: variables de entorno sin .env en Git

Esta guía está dirigida a un proyecto que ya está alojado en Vercel. Necesitas acceso a su configuración y saber qué variables lee la aplicación. El ejemplo siguiente se aplica a Next.js; los nombres de variables de otro framework no se pueden reutilizar automáticamente. La guía se basa en la documentación oficial y no se ha probado con una cuenta real.

En la documentación encontrarás información práctica sobre el uso de Ailoot.

Por qué no necesitas añadir .env a Git#

Una variable de entorno es una configuración con un nombre y un valor que una aplicación recibe por separado de su código fuente. Por ejemplo, el nombre SERVICE_API_KEY permite que el programa acceda al valor de la clave de un servicio externo. No incluyas la clave en sí en la guía, en tu conversación con un agente ni en el repositorio.

Next.js puede cargar variables desde archivos locales .env*. Sin embargo, un archivo local y la configuración de un proyecto en Vercel son dos ubicaciones distintas. Si el archivo no se sube al repositorio, configura los valores por separado en la plataforma de alojamiento. La plantilla estándar create-next-app añade los archivos .env a .gitignore; la documentación de Next.js advierte que casi nunca deberías subirlos al repositorio.

Si todavía no sabes con seguridad qué se puede guardar en los archivos fuente, empieza por la comprobación de seguridad de un proyecto creado con IA. Aquí abordamos una pregunta más concreta: dónde configurar la aplicación para un deployment específico de Vercel.

Primero, determina dónde lee la aplicación la variable#

Antes de introducir valores, haz una lista de los nombres, sin incluir los secretos. Para cada nombre, debes determinar tres cosas: qué entorno lo usa, dónde se ejecuta el código que lee la variable y cuándo se necesita el valor.

El entorno Development está pensado para el desarrollo local. Preview es para los deployments de vista previa y Production, para la versión principal publicada. Preview puede tener configuraciones para una rama específica de Git: estas sustituyen a las configuraciones generales de Preview que tengan los mismos nombres.

En un proyecto de Next.js, las variables sin NEXT_PUBLIC_ están disponibles en el servidor de forma predeterminada. El prefijo NEXT_PUBLIC_ permite incrustar el valor en el JavaScript que se entrega al navegador. Esto es adecuado para una configuración explícitamente pública, como una etiqueta de versión que no sea secreta, pero no para una clave API privada. Incluso sin este prefijo, el código de la aplicación no debe devolver manualmente un secreto al cliente.

Si todavía no has identificado el framework, pide al agente que lo determine a partir de los archivos del proyecto. La comparación entre Astro y Next.js puede ayudarte a entender las diferencias; no puedes aplicar la regla de NEXT_PUBLIC_ a todas las aplicaciones React.

La configuración del alojamiento es una de las tareas que implica trabajar en una aplicación con un agente de IA.

¿Qué precauciones tomar al añadir variables de entorno en Vercel?#

Realiza tú mismo los pasos en el dashboard oficial. No le des una clave real al agente para que rellene el formulario ni adjuntes una captura de pantalla que muestre su valor.

1. Abre el dashboard de Vercel y selecciona el proyecto correcto. No te fíes únicamente de que coincida el nombre del repositorio: comprueba que estás configurando la aplicación que quieres abrir.
2. Ve a Environment Variables en la barra lateral de la configuración del proyecto.
3. En Name, introduce el nombre que lee la aplicación, como SERVICE_API_KEY. Es un nombre de ejemplo; si el código espera otro, usa su escritura exacta.
4. En Value, introduce el valor de tu gestor de credenciales. No lo pongas en el código fuente, un chat ni un registro de verificación.
5. Selecciona el entorno que necesita esta configuración. Usa Preview para comprobar una versión de vista previa y Production para la versión principal. No asignes automáticamente un mismo secreto a todos los entornos.
6. Si la configuración de Preview se aplica a una rama específica, comprueba la rama seleccionada y cualquier sobrescritura con el mismo nombre.
7. Haz clic en Save.

Vercel pone las variables del proyecto a disposición tanto durante la compilación como al ejecutar las Vercel Functions del lado del servidor. Sin embargo, que un valor esté disponible en Vercel no significa que pueda enviarse al navegador: eso depende del código de la aplicación y de las reglas del framework.

Por qué necesitas un nuevo deployment después de guardar#

Guardar una variable no cambia los deployments existentes. La documentación de Vercel indica que debes volver a desplegar el proyecto para que la nueva configuración llegue a la versión que utilizas.

Si trabajas con Git, puedes crear un nuevo deployment de Production subiendo un commit a la rama indicada en Production Branch, y un deployment de Preview subiéndolo a otra rama. No des por hecho que la rama principal siempre se llama main: comprueba la configuración de tu proyecto. Debe ser una publicación normal y acordada del proyecto, sin añadir un archivo secreto al commit.

Después de iniciar el deployment, espera a que termine la compilación y abre la URL del nuevo deployment. Anota su URL, entorno y rama. Si compruebas la URL antigua de un deployment concreto, allí no aparecerá la nueva configuración.

Next.js tiene otra condición: las referencias como process.env.NEXT_PUBLIC_RELEASE_LABEL se sustituyen por sus valores durante next build. El valor queda fijado una vez terminada la compilación. Cambiar la configuración sin una nueva compilación no reescribirá el JavaScript del cliente que ya se ha entregado.

Cómo comprobar el resultado sin exponer la clave#

Empieza con un ejemplo seguro: una etiqueta explícitamente no secreta llamada NEXT_PUBLIC_RELEASE_LABEL con el valor preview-check. Son un nombre y un texto de ejemplo, no una clave ni una prueba realizada aquí. Si una aplicación de Next.js lee esta variable directamente mediante process.env.NEXT_PUBLIC_RELEASE_LABEL, puede mostrar la etiqueta en el lugar previsto de la interfaz después de una nueva compilación. Esta comprobación solo confirma que se pasó la configuración pública.

Una clave privada se comprueba de otra manera. No muestres su valor, parte de él, su longitud ni todo process.env. No crees una URL pública que devuelva el contenido de la variable. Primero, comprueba únicamente si la configuración está «presente / ausente» en el servidor y, después, comprueba por separado la función de la aplicación que utiliza el servicio. Que la configuración esté presente no demuestra que la clave sea válida ni que tenga los permisos necesarios.

Puedes registrar los resultados sin incluir secretos:

• el proyecto, el entorno y la rama coinciden con los seleccionados durante la configuración;
• estás comprobando la URL de un nuevo deployment creado después de guardar la variable;
• la compilación ha terminado y la función necesaria de la aplicación se ha ejecutado con datos de prueba seguros;
• el secreto no queda expuesto en el navegador, las respuestas de la API, los registros ni las conversaciones.

Si la función realiza un pago, envía un mensaje o ejecuta otra acción con consecuencias, usa el modo de prueba designado por el servicio. Comprobar la configuración no autoriza por sí solo una operación real.

Qué comprobar si el valor sigue siendo undefined#

undefined significa que en ese punto de acceso no se obtuvo ningún valor. Comprueba el nombre, el entorno y la versión en ese orden, sin cambiar todas las configuraciones a la vez.

Aunque hayas comprobado el nombre, el entorno y la nueva versión, un error en la función no demuestra que la variable sea la causa. Investiga el error específico del código del servidor sin publicar datos de diagnóstico que contengan secretos. Esta guía no promete resolver todas las respuestas HTTP 500.

Pasar a tu propio servidor requiere otro procedimiento: consulta la guía para desplegar un proyecto con Coolify. Los nombres de los botones y los pasos de configuración de Vercel no se aplican allí.

Ir a Ailoot.