# Vercel: variables de entorno sin .env en Git
> Variables de entorno, Development/Preview/Production, un nuevo deployment y cómo comprobar claves de forma segura en Next.js sin enviar secretos al navegador.
Source: https://ailoot.ai/blog/es/vercel-environment-variables/
Canonical: https://ailoot.ai/blog/es/vercel-environment-variables/
Language: es
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-229
Revision: sha256-bf87b453398e85cf8297b139bbda7ebccca40aee8e4a7347ba075c7e7beafbab
Idea clave
Si el archivo `.env` que contiene tus secretos no está en Git, añade las variables necesarias en la sección **Environment Variables** de tu proyecto de Vercel. Selecciona el entorno, guarda la configuración y crea un nuevo deployment: las versiones que ya están desplegadas no cambiarán. En Next.js, no añadas el prefijo `NEXT_PUBLIC_` a una clave secreta: su valor se incluirá en el código del navegador durante la compilación.
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](https://ailoot.ai/docs/).
## 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](https://ailoot.ai/blog/es/vibe-coding-security/). 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.
| Qué comprobar | Opciones posibles | Por qué importa |
|----|----|----|
| Entorno de Vercel | Development, Preview, Production | La configuración debe aplicarse a la versión que estás comprobando |
| Dónde se lee | Servidor o navegador | Una clave privada no debe incluirse en el código del cliente |
| Cuándo se lee | Durante la compilación o al ejecutar una función del servidor | En Next.js, los valores públicos se fijan durante la compilación |
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](https://ailoot.ai/blog/es/astro-vs-nextjs-for-ai-built-sites/) 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.
| Síntoma | Qué comprobar |
|----|----|
| Funciona en local, pero no en Preview | Si el nombre existe en la configuración Preview del proyecto; si se ha seleccionado otra rama |
| Preview funciona, pero Production no | Si el nombre está configurado para Production; si se creó una nueva versión principal después de guardar |
| Una rama de Preview se comporta de forma distinta | Si hay un valor con el mismo nombre configurado para esa rama que sobrescribe la configuración general |
| El servidor ve la variable, pero el navegador no | En Next.js, esto es lo esperado para una variable no pública; no muevas una clave privada al navegador |
| La etiqueta pública de Next.js sigue teniendo el valor anterior | Si hubo una nueva compilación con el valor requerido; si la URL que abriste pertenece a ese deployment |
| El nombre público es correcto, pero la sustitución no funciona | Si el código la lee dinámicamente con `process.env[varName]`: Next.js no inserta estas referencias durante la compilación |
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](https://ailoot.ai/blog/es/coolify-claude-code-deploy/). Los nombres de los botones y los pasos de configuración de Vercel no se aplican allí.
### Fuentes
- [Variables de entorno de Vercel](https://vercel.com/docs/environment-variables)
- [Añadir y gestionar variables de entorno de Vercel](https://vercel.com/docs/environment-variables/managing-environment-variables)
- [Variables de entorno de Next.js](https://nextjs.org/docs/app/guides/environment-variables)
[Ir a Ailoot](https://ailoot.ai/).
## Preguntas sobre Vercel
### ¿Por qué la variable sigue undefined después de guardarla en Vercel?
Comprueba proyecto, entorno y cualquier ámbito específico de rama; después crea otro despliegue. Los despliegues existentes no reciben una variable solo porque hayas guardado un ajuste nuevo.
### ¿Puedo añadir NEXT_PUBLIC_ para que mi aplicación Next.js vea un secreto?
No uses ese prefijo para secretos: introduce el valor en el código del navegador durante la compilación. Mantenlo en el servidor y verifica su presencia sin imprimir la clave.
## Ailoot · La empresa y su cartera de proyectos
Ailoot se apoya en la experiencia operativa acumulada, una amplia base de clientes, un servicio estable y el seguimiento continuo de KPI.
La empresa y su cartera de proyectos: millones de clientes; ventas por miles de millones al mes.
Ailoot aplica esa experiencia operativa al acceso por API a funciones de IA en productos de clientes, agentes, aplicaciones y automatizaciones.