Alojamiento de Next.js
Sacar Next.js de Vercel: guía práctica de migración
Migra tu aplicación Next.js desde Vercel paso a paso: ajustes, tareas cron, pruebas y dominio, con ejemplos opcionales de Adios.
En esta página7 secciones
Puedes sacar una aplicación Next.js de Vercel sin cambiar de framework. Next.js funciona en alojamientos compatibles con Node.js. El trabajo consiste en hacer funcionar los ajustes, los servicios conectados y las tareas programadas en el nuevo entorno. Opciones de despliegue de Next.js
La primera migración suele ser más sencilla si conservas la base de datos y el almacenamiento, haces funcionar la aplicación en una URL nueva y después trasladas el dominio. Así tendrás menos elementos que investigar a la vez.
Esta guía sigue ese proceso. Puedes usarla con el alojamiento Node.js que elijas; los ejemplos de Adios muestran una forma de aplicar los pasos. Necesitarás los archivos del proyecto, acceso a los ajustes de Vercel y acceso a la configuración DNS del dominio cuando quieras trasladarlo.
1. Haz una lista breve de los servicios que utiliza tu aplicación
Conserva los servicios que ya funcionan
Trasladar la aplicación no significa trasladar sus datos. Si tu base de datos permite conexiones desde el nuevo alojamiento, normalmente puedes conservarla. Comprueba si tiene una lista de IP permitidas u otras restricciones.
Haz lo mismo con el almacenamiento de archivos, la autenticación, los pagos y el correo. Conserva los servicios que te funcionan si admiten la nueva configuración. Por ejemplo, Vercel documenta cómo acceder a Blob desde fuera de Vercel con un token de lectura y escritura. Autenticación de Vercel Blob
Guarda una versión funcional del código antes de empezar. Para este primer traslado, evita combinar el cambio de alojamiento con una actualización del framework o un rediseño de la base de datos.
Revisa los ajustes que proporciona Vercel
Abre los ajustes del proyecto de Vercel y los archivos de tu proyecto package.json, next.config.*, y vercel.json, si existe. Completa esta breve lista:
| Qué buscar | Qué anotar |
|---|---|
| Ajustes de compilación | Versión de Node, gestor de paquetes, comando de compilación y carpeta del proyecto |
| Variables de entorno | Nombres de variables y si pertenecen a Production, Preview o Development |
| Base de datos y almacenamiento | Qué servicios utilizas y si el nuevo alojamiento puede conectarse |
| Inicio de sesión y pagos | URL de retorno y de webhooks que apuntan a la aplicación actual |
| Tareas cron | Qué URL llama cada tarea, con qué frecuencia y qué modifica |
| Dominios | Qué dominio usan los visitantes y dónde se gestiona su DNS |
Una URL de retorno es la dirección a la que un servicio devuelve al usuario después de una acción, como iniciar sesión. Una URL de webhook recibe notificaciones de otro servicio, como una actualización de pago. Puede que debas cambiar ambas cuando cambie la dirección de la aplicación.
Busca también en el código @vercel/ y VERCEL_. Revisa cada resultado: algunas integraciones funcionan en otros alojamientos, mientras que otras dependen de un valor o servicio proporcionado por Vercel. El nuevo alojamiento no recreará esos ajustes automáticamente.
Mantén disponible el despliegue anterior mientras preparas y pruebas su sustituto.
2. Comprueba que tu aplicación funciona en modo producción
Compila y arranca la aplicación en tu equipo
Empieza con la versión de Node y el gestor de paquetes que ya utiliza el proyecto. Estos ejemplos usan npm y suponen que tienes en el repositorio un archivo package-lock.json.
Comprueba que los scripts de package.json incluyan estas entradas. Combínalas con los scripts existentes y conserva los pasos de compilación que necesite tu aplicación.
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}
En un terminal abierto en la carpeta de la aplicación, ejecuta:
npm ci --include=dev
npm run build
npm start
npm ci instala las versiones guardadas en el archivo de bloqueo. npm run build prepara la aplicación para producción. npm start ejecuta esa compilación. Si utilizas pnpm o Yarn, emplea los comandos equivalentes de tu proyecto. Configurar Next.js como servidor Node
Abre la dirección local que aparece en el terminal. Comprueba varias páginas, incluida una que cargue datos. Si falta un ajuste durante la compilación, añádelo al entorno local e inténtalo de nuevo. Usa credenciales de prueba para enviar correos, procesar pagos o modificar datos de clientes.
Este ejemplo utiliza la configuración habitual de next start. Si tu aplicación ya utiliza output: 'standalone', conserva el comando de inicio del servidor generado e incluye los recursos del navegador. Las instrucciones de Next.js para standalone explican esa opción de empaquetado.
Opcional: describe la configuración para Adios
En el alojamiento elegido, configura el comando de compilación, el de inicio y el puerto. El puerto es el número en el que escucha la aplicación; el ajuste del alojamiento y el de la aplicación deben coincidir.
En Adios, crea adios.yaml junto a package.json. Este ejemplo utiliza Node 24, una instancia en ejecución y el puerto 3000:
name: my-nextjs-app
region: de
replicas: 1
build_cmd: npm ci --include=dev && npm run build
start_cmd: npm start -- --hostname 0.0.0.0 --port 3000
runtime:
name: node@24
port: 3000
health_path: /api/health
memory_mb: 1024
Elige una versión de Node compatible con tu aplicación y disponible en la plataforma, y una región disponible para tu equipo. El ajuste --hostname 0.0.0.0 permite que el alojamiento acceda a la aplicación en ejecución. Termina de añadir los ajustes de la siguiente sección antes de desplegar. La Inicio rápido de Adios explica estos campos.
El health_path es una URL que el alojamiento consulta para comprobar si la aplicación responde. Si todavía no tienes una, este ejemplo básico de App Router va en app/api/health/route.js, o src/app/api/health/route.js si utilizas src/:
export function GET() {
return Response.json({ status: 'ok' })
}
Asegúrate de que el middleware de autenticación permite acceder a esta URL sin iniciar sesión. Esta comprobación confirma que la aplicación responde; no demuestra que funcionen el acceso, los pagos o la base de datos. Los probarás por separado.
3. Copia los ajustes y conecta los servicios
Coloca cada ajuste donde corresponde
Copia los ajustes que necesita la aplicación desde Vercel a la configuración del nuevo alojamiento. Utiliza los adecuados para el entorno de prueba: un despliegue de prueba debe usar claves de pago de prueba y datos apropiados.
Un ajuste puede ser necesario en dos momentos:
- Durante la compilación: mientras
npm run buildprepara la aplicación. - Durante la ejecución: mientras la aplicación compilada atiende solicitudes.
| Ejemplo de ajuste | Dónde suele ir |
|---|---|
NEXT_PUBLIC_SITE_URL | Ajustes de compilación; el valor puede aparecer en el navegador |
DATABASE_URL | Ajustes privados del servidor; también de compilación si esta lee la base de datos |
| Secreto de firma de autenticación | Ajustes privados del servidor, siguiendo las instrucciones de la biblioteca de autenticación |
| Clave de API de pagos o correo | Ajustes privados del servidor |
CRON_SECRET | Ajustes privados del servidor para el ejemplo de tarea programada de abajo |
Utiliza los nombres reales de las variables de tu aplicación. Un nombre que empiece por NEXT_PUBLIC_ indica información que puede ser pública. Nunca utilices ese prefijo para una contraseña o una clave de API privada.
Next.js inserta los valores NEXT_PUBLIC_* referenciados directamente en el código del navegador durante la compilación. Si cambias uno, vuelve a compilar. Cambiar solo un ajuste de ejecución no actualizará ese código del navegador. Variables de entorno de Next.js
Opcional: añade secretos de Adios y despliega
En Adios, selecciona el equipo propietario de la aplicación y crea sus valores privados en Secretos. Después, haz referencia a ellos en adios.yaml. Para una aplicación que utilice estas dos variables, añade:
env:
DATABASE_URL: secret://DATABASE_URL
CRON_SECRET: secret://CRON_SECRET
El texto secret://DATABASE_URL indica a Adios que cargue el valor almacenado. No es la contraseña de la base de datos. Añade únicamente las variables que utilice tu aplicación. Secretos y configuración de Adios
Para un ajuste público necesario durante la compilación, añade un bloque build.env. Sustituye esta dirección de ejemplo por la que vayas a utilizar:
build:
env:
NEXT_PUBLIC_SITE_URL: https://app.example.com
Si el servidor también lee ese ajuste durante la ejecución, inclúyelo en env también. Si la compilación necesita un valor privado, utiliza una referencia a un secreto en build.env. No escribas valores privados en el archivo. Referencia del manifiesto de Adios
Después de instalar la CLI de Adios, inicia sesión, consulta tus equipos y selecciona el mismo que utilizaste para Secrets:
adios login
adios teams
adios teams switch YOUR_TEAM_ID
adios up
Reemplaza los marcadores YOUR_TEAM_ID por el ID de tu equipo. Ejecuta estos comandos desde la carpeta que contiene adios.yaml. adios up sube y compila la aplicación, inicia una versión y espera sus comprobaciones de estado. Abre la URL generada cuando termine. Despliegues en Adios
En otro alojamiento, sigue sus instrucciones de despliegue y continúa con las mismas comprobaciones de tareas y aplicación.
4. Sustituye Vercel Cron por otro programador
Conserva la ruta actual de la tarea
Omite esta sección si tu aplicación no utiliza tareas programadas.
Una tarea cron es un trabajo que se ejecuta según un horario, como enviar un informe o borrar registros caducados. Con Vercel Cron, el código está en tu aplicación y Vercel llama a su URL. Trasladar el código no programa la tarea en el nuevo alojamiento.
Por ejemplo, podrías tener esto en vercel.json:
{
"crons": [
{ "path": "/api/cron/daily-report", "schedule": "0 8 * * *" }
]
}
Esa configuración solicita una ejecución diaria de /api/cron/daily-report a las 08:00 UTC. Puedes conservar la ruta y hacer que otro programador la invoque. Tareas cron de Vercel
Mantén la ruta protegida. Si ya comprueba el valor CRON_SECRET, copia ese ajuste privado a la nueva aplicación. El nuevo programador debe enviar una cabecera Authorization con el contenido Bearer seguido del mismo secreto. La ruta debe rechazar las credenciales ausentes o incorrectas antes de hacer nada. Proteger las tareas cron de Vercel
Opcional: ejecuta la tarea con un workflow de Adios
Un workflow de Adios puede llamar a tu ruta existente y mostrar el resultado de cada ejecución. También puedes utilizar otro programador compatible con solicitudes HTTPS y cabeceras de autenticación.
Conserva el código de la tarea y sustituye su activador. Elige un intervalo o un programador a una hora fija según las necesidades de la tarea.
Empieza con una ejecución manual. En Secretos del mismo equipo de Adios, crea CRON_AUTHORIZATION. Su valor debe ser la cabecera completa, Bearer seguido del valor actual de CRON_SECRET. La aplicación utiliza CRON_SECRET para comprobar la solicitud; el workflow utiliza CRON_AUTHORIZATION para enviarla.
Crea workflows/daily-report.yaml. Mantenlo separado del archivo raíz de la aplicación, adios.yaml:
workflow_id: daily-report
title: Daily report
team_id: YOUR_TEAM_ID
enabled: true
version: "1"
steps:
- step_id: call-report
name: Run the existing report route
kind: http
timeout_seconds: 30
command:
method: GET
url: https://your-app.example.com/api/cron/daily-report
headers:
Authorization: secret://CRON_AUTHORIZATION
Sustituye el ID del equipo y la URL por los tuyos. En esta primera ejecución, usa un despliegue de prueba conectado a datos de prueba: una ejecución manual también envía los correos o modifica los registros que indique la ruta. Conserva la ruta exacta de la configuración cron actual. La referencia al secreto debe ocupar toda la cabecera: escribir Bearer secret://CRON_SECRET enviaría ese texto de forma literal. Secretos de los workflows de Adios
Despliega el workflow:
adios workflow deploy ./workflows/daily-report.yaml
Abre Flujos de trabajo, inicia una ejecución manual e inspecciona el estado y la salida del paso. Confirma que se generó el informe o se modificó la base de datos. Comprueba también que las solicitudes sin autorización se rechazan. Aumenta timeout_seconds solo si la ruta lo necesita y el alojamiento permite solicitudes de esa duración. Crear e inspeccionar una ejecución de workflow
Después, elige el horario que realmente necesitas:
| Requisito | Cómo programarlo |
|---|---|
| Repetir cada 24 horas; la hora exacta no importa | Añade un activador por intervalo de Adios |
| Ejecutar a las 08:00 UTC o a una hora local concreta | Utiliza un programador de calendario para activar el workflow mediante un webhook o llamar directamente a la ruta protegida |
Para la opción por intervalo, añade este bloque en el nivel superior del archivo del workflow:
triggers:
- type: schedule
interval: 24h
Un intervalo de 24 horas no equivale a una ejecución programada a las 08:00. Adios todavía no interpreta expresiones cron de calendario generales como 0 8 * * *. Un intervalo nuevo puede ejecutarse en la siguiente comprobación del programador, y reiniciarlo restablece el seguimiento de los intervalos. Elige esta opción solo si ese comportamiento encaja con la tarea. Comportamiento de la programación en Adios
No añadas el bloque de activación hasta que pasen las comprobaciones de la siguiente sección y estés listo para trasladar la tarea. Apunta el workflow a la nueva aplicación de producción, desactiva la programación de Vercel y comprueba si queda alguna ejecución en curso. Después, añade el activador y vuelve a desplegar con el comando anterior. Vercel ofrece el control Disable Cron Jobs para todo el proyecto; si solo vas a trasladar una tarea, elimina su configuración y vuelve a desplegar en Vercel. Gestionar tareas cron de Vercel
Haz que repetir una ejecución sea seguro. Para un informe diario, registra qué fecha ya se ha enviado y rechaza los duplicados mediante una restricción de base de datos o una protección equivalente frente a solicitudes simultáneas. El programador actual de Adios no aplica su campo concurrency, por lo que ese ajuste no impedirá las ejecuciones simultáneas.
5. Prueba la aplicación en su nueva URL
Recorre las acciones habituales de un cliente
Mantén el dominio principal en la aplicación existente mientras pruebas la nueva dirección. Si utilizas un proveedor de autenticación externo, registra la nueva URL de retorno antes de iniciar sesión. Usa cuentas y modos de pago de prueba cuando estén disponibles.
| Prueba | Qué debería ocurrir |
|---|---|
| Abre la página de inicio y una página interior | Ambas páginas cargan, incluidos estilos, imágenes y scripts |
| Inicia sesión, actualiza la página y cierra sesión | La sesión se comporta como esperas |
| Crea o modifica un registro de prueba | El cambio se guarda y sigue apareciendo al actualizar |
| Sube y abre un archivo | El archivo funciona y los archivos privados siguen siendo privados |
| Abre la URL privada de otra cuenta | Se rechaza el acceso |
| Activa un webhook de pago de prueba, si lo utilizas | El estado de pago esperado cambia una sola vez |
| Ejecuta una tarea programada manualmente | Aparece el resultado esperado sin acciones duplicadas |
Una prueba de webhook debe comprobar qué ha cambiado en la aplicación, no solo si el endpoint devolvió una respuesta correcta. En Stripe, comprueba también las entregas duplicadas: su documentación indica que un evento puede entregarse más de una vez. Guía de webhooks de Stripe
Si ambas versiones se conectan a datos de producción, las dos pueden modificarlos. Controla las pruebas y deja desactivadas las tareas destructivas hasta que estés listo para trasladarlas.
Usa los registros para corregir los fallos
En Adios, estos comandos muestran los registros de compilación y de la aplicación en ejecución:
adios logs --build
adios logs --runtime
En otro alojamiento, abre su vista equivalente de registros. Empieza por el primer error pertinente:
| Síntoma | Qué comprobar primero |
|---|---|
| La compilación indica que falta una variable | ¿Está disponible durante la compilación? |
| La aplicación arranca, pero el alojamiento la considera no disponible | ¿Coinciden el comando de inicio, el puerto y la URL de estado? |
| La conexión de la base de datos falla | ¿Es correcto el ajuste de conexión y la base de datos permite acceder a este alojamiento? |
| El inicio de sesión redirige a la URL anterior | Actualiza la URL de retorno del proveedor de autenticación y la URL de la aplicación |
| El ajuste de URL pública sigue mostrando el valor anterior | Vuelve a compilar después de cambiar la variable pública de compilación |
La tarea devuelve 401 Unauthorized | Comprueba el secreto de la aplicación y la cabecera completa de autorización del workflow |
Prueba las funciones especiales de tu aplicación a través de la nueva URL pública. En un chat con IA, comprueba que el texto llegue de forma gradual. En páginas con caché, modifica datos de prueba y comprueba que los visitantes vean el cambio. Si ejecutas varias instancias, sigue la guía de Next.js sobre caché compartida y otros ajustes para varios servidores. Alojar Next.js por tu cuenta
6. Traslada el dominio cuando las comprobaciones sean correctas
Añade el dominio y después actualiza DNS
DNS indica a los navegadores dónde encontrar tu dominio. Antes de modificarlo, guarda los registros actuales para poder restaurarlos si hace falta.
Añade tu dominio al nuevo alojamiento y sigue sus instrucciones de verificación, DNS y HTTPS. En Adios, consulta la guía de configuración de dominios. Utiliza los registros proporcionados para tu aplicación; evita copiar direcciones de otro ejemplo.
Si usaste una URL temporal durante las pruebas, actualiza las URL de la aplicación y de retorno para el dominio definitivo. Vuelve a compilar los valores públicos que hayan cambiado. Revisa también los destinos de los webhooks y la URL del workflow.
Después de actualizar DNS, abre el dominio y repite las comprobaciones de inicio de sesión, lectura y escritura de prueba e imágenes. Confirma que estás viendo la versión prevista. Algunos visitantes pueden seguir llegando a la aplicación anterior mientras caducan los registros DNS en caché; conserva la compatibilidad de ambas versiones con la base de datos compartida durante el cambio.
Conserva una forma de volver a la aplicación que funciona
Mantén disponible el despliegue anterior mientras compruebas el nuevo. Guarda la revisión del código que funciona, sus ajustes y los registros DNS anteriores.
Si falla una función esencial, como iniciar sesión o guardar datos, puedes restaurar el enrutamiento anterior mientras investigas, siempre que la aplicación anterior siga siendo compatible con la base de datos actual. Un cambio de DNS tarda en llegar a todos y no deshace cambios en la base de datos ni correos ya enviados.
Anota qué programador está activo. Devolver el sitio a Vercel no implica necesariamente reactivar sus tareas cron. Decide eso por separado para que solo el programador previsto ejecute el trabajo.
7. Utiliza una lista final de comprobación
Confirma que la aplicación está lista para los visitantes
- La compilación de producción termina correctamente y la nueva URL sirve la versión prevista.
- Los ajustes necesarios están disponibles durante la compilación o la ejecución, según corresponda.
- Funcionan el inicio de sesión, los cambios de datos, las imágenes y las subidas.
- Las páginas y los archivos privados siguen protegidos.
- Las integraciones de pago y correo han superado sus pruebas correspondientes.
- Cada tarea programada tiene un sustituto probado con autenticación y horarios adecuados.
- El programador anterior está desactivado antes de activar el nuevo.
- El dominio funciona con HTTPS, incluidas las URL de retorno y los webhooks.
- La versión anterior que funciona y los registros DNS están disponibles para recuperarla si hace falta.
Comprueba la primera ejecución programada real
Tras el traslado, revisa los registros, un recorrido habitual de cliente y la primera tarea programada. Una prueba manual demuestra que la tarea puede ejecutarse; la primera ejecución programada comprueba también su activador.
Guarda la lista de servicios y los resultados de las pruebas junto al proyecto. Te ayudarán a comprobar el próximo despliegue.
Para más información sobre cómo ejecutar el servidor Node por tu cuenta, lee Ejecuta Next.js como un servidor Node sin Lambda. Si quieres utilizar Adios, la Guía de despliegue de Next.js explica la configuración de la plataforma.