En mi máquina funciona, en el servidor falla: 7 comprobaciones tras el primer despliegue

Ha creado una aplicación con una herramienta de IA y funciona en su portátil. Esta página es para el día en que tenga que funcionar en un servidor.

Estos son 7 puntos en los que un servidor puede diferir de un portátil, cada uno con una comprobación, algunas de ellas sobre una copia de su proyecto.

Necesita el código del proyecto en su ordenador, una ventana de terminal y un acceso a su hosting. Algunas comprobaciones requieren además accesos a su proveedor de pagos y a su proveedor de DNS.

¿Por dónde empiezo sin arriesgar la producción?

Haga la primera comprobación sobre una copia nueva del proyecto y no ponga en ella claves de producción. No cambie nada en producción mientras comprueba: no edite los ajustes del hosting, los registros DNS, la base de datos ni el panel de un proveedor. Pare a los 60 minutos y anote lo que todavía no sabe en la hoja del final de esta página.

Ejecute estos 2 comandos en una carpeta fuera de su copia de trabajo y sustituya YOUR-REPO-URL por la dirección de su repositorio.

git clone YOUR-REPO-URL deploy-check
cd deploy-check

Lea primero cada comando y omita cualquier paso que modifique algo.

¿Cuáles son las 7 diferencias entre un portátil y un servidor?

Las 7 diferencias son las variables de entorno, los tiempos de espera, CORS, los webhooks, las migraciones de base de datos, los secretos y el dominio con sus registros DNS.

¿Cómo compruebo cada una de las 7 diferencias?

Cuando una sección enlaza una página de documentación, su explicación se basa en esa página y otros proveedores pueden diferir, así que consulte el mismo punto para su propio hosting.

1. Variables de entorno: ¿coinciden los nombres del hosting con los del código?

Una variable de entorno es un ajuste con nombre que su aplicación lee desde fuera de su código, como una dirección web o una clave.

Next.js carga las variables desde archivos .env* en process.env, y su plantilla inicial predeterminada añade todos los archivos .env a .gitignore. La misma página dice que casi nunca querrá hacer commit de estos archivos (documentación de Next.js: Environment Variables). Así que no dé por hecho que el hosting los tiene y compruebe que cuenta con su propio ajuste para cada nombre.

Comprobación: liste los nombres de variable que lee el código y los nombres definidos en los ajustes del hosting, y anote todo nombre que esté en la primera lista y no en la segunda. Compare solo los nombres, nunca los valores secretos. Ejecute esto en la copia y cambie los nombres de las carpetas para que coincidan con su proyecto.

grep -rhoE "(process\.env|import\.meta\.env)\.[A-Za-z0-9_]+" app src pages lib 2>/dev/null | sort -u

Después lea el valor de cada variable de URL en el hosting y compruebe que ninguna sigue apuntando a localhost.

Trampa: algunos valores se fijan cuando se compila el proyecto. Next.js incrusta los valores de NEXT_PUBLIC_ en el bundle de JavaScript durante la compilación, y la aplicación ya compilada deja de responder a los cambios en ellos (documentación de Next.js: Environment Variables).

Vite empaqueta los valores de VITE_ en el código fuente durante la compilación (documentación de Vite: Env Variables and Modes). Vuelva a compilar después de cambiar cualquiera de los dos tipos en el hosting.

2. Tiempos de espera: ¿cuánto tiempo espera el hosting una respuesta?

Es posible que su hosting fije un límite de tiempo para cada solicitud. Lea ese límite en la documentación del propio hosting y no suponga ninguno.

Comprobación: anote lo más lento que puede iniciar un usuario, como una llamada a la IA o una exportación, y el límite documentado de su hosting para ello. Después busque en los registros del hosting una entrada de tiempo de espera agotado de su última ejecución.

Trampa: comparar el límite con la carga rápida de una página. Compárelo con la acción más lenta que anotó.

3. CORS: ¿permite la API el origen de su sitio en producción?

Los navegadores restringen las solicitudes que los scripts de una página envían a otro origen, salvo que la respuesta incluya las cabeceras CORS adecuadas (MDN: Cross-Origin Resource Sharing). Un origen es distinto si cambia el dominio, el esquema o el puerto, así que una dirección localhost y su dominio en producción son orígenes diferentes. Compruebe por separado el dominio raíz y www.

Comprobación: confirme que el ajuste de orígenes permitidos de la API nombra el origen de su sitio en producción, no solo localhost. Después abra el sitio en producción en una ventana privada con la consola del navegador abierta y repita la acción que falla, pero únicamente si es de solo lectura, como cargar una página; no repita un formulario, un pago ni una exportación. MDN dice que la consola es el único lugar donde se pueden leer los detalles de un fallo de CORS.

Envíe a mano la solicitud preflight, sustituyendo las partes en mayúsculas por la dirección de su API y el origen de su sitio.

curl -i -X OPTIONS https://YOUR-API/PATH -H "Origin: https://YOUR-SITE" -H "Access-Control-Request-Method: POST"

Busque una cabecera Access-Control-Allow-Origin cuyo valor sea exactamente igual al origen de su sitio. MDN califica OPTIONS de método seguro, es decir, que no puede usarse para cambiar el recurso.

Trampa: el comodín *. Si la solicitud incluye una credencial, como una cookie, MDN dice que el navegador bloquea el acceso a una respuesta que lleve Access-Control-Allow-Origin: *. Indique sus orígenes exactamente, incluidos https y www.

4. Webhooks: ¿llama el proveedor a su dirección en producción?

Un webhook es una llamada de otro servicio a su aplicación, como la confirmación de un pago. La documentación de Stripe dice que los endpoints de webhook registrados deben ser URL HTTPS de acceso público (documentación de Stripe: Webhooks).

Comprobación: en el panel del proveedor, liste todos los endpoints registrados y confirme que cada uno usa su dirección HTTPS en producción, no una dirección temporal de las pruebas. Abra el registro de entregas, si el proveedor lo conserva, y cuente los fallos. Confirme que el secreto de firma guardado en su hosting pertenece a ese endpoint.

Stripe genera un secreto único para cada endpoint, y un secreto distinto para el uso de prueba y el uso en producción del mismo endpoint.

Trampa: entre otros puntos, la misma página de Stripe describe 3 cosas que hay que gestionar en el endpoint.

• Responda rápido. El endpoint debe devolver un código de estado correcto (2xx) antes de cualquier lógica compleja que pueda provocar un tiempo de espera agotado.
• Conserve el cuerpo sin procesar. Stripe exige el cuerpo sin procesar de la solicitud para verificar la firma, y cualquier manipulación de este hace que la verificación falle.
• Espere repeticiones. Un endpoint podría recibir ocasionalmente el mismo evento más de una vez, así que registre los ID de los eventos que ya ha procesado y omita los eventos ya registrados.

5. Migraciones de base de datos: ¿tiene la base de datos del servidor los últimos cambios?

Una migración es un cambio registrado y repetible en la estructura de una base de datos, como una tabla nueva o una columna nueva. Cada base de datos, en el portátil o en el servidor, necesita que se le aplique la migración. Busque en la documentación de su herramienta qué comando aplica las migraciones a la base de datos de un servidor.

Comprobación: responda a las preguntas de abajo. Ejecute estos comandos en la copia para buscar una carpeta de migraciones y un paso de migración en package.json.

ls migrations prisma/migrations 2>/dev/null
grep -n -i "migrat" package.json

¿Hay una carpeta de migraciones en el repositorio? ¿Muestra el último registro de despliegue un paso que aplica las migraciones? Use un comando de estado de la documentación de su herramienta solo si su página dice que no cambia nada, y ejecútelo en el hosting, donde ya está la conexión de producción, nunca poniendo claves de producción en la copia; de lo contrario, escriba DESCONOCIDO para esta diferencia en la hoja.

Trampa: la copia no puede mostrar qué migraciones ha aplicado producción, y una carpeta de migraciones en el repositorio solo muestra lo que contiene el proyecto.

6. Secretos: ¿hay una clave en los archivos del navegador o en git?

Busque 2 tipos de fuga: una clave en una variable que se envía al navegador y una clave que se incluyó en un commit de git. Next.js incrusta los valores de NEXT_PUBLIC_ en cualquier JavaScript que se envía al navegador (documentación de Next.js: Environment Variables), y Vite dice que las variables VITE_ no deberían contener información sensible, como claves de API (documentación de Vite: Env Variables and Modes).

Comprobación: lea el nombre de cada variable destinada al navegador en el código y en el hosting, y anote todo nombre que suene a clave, secreto o token. Después busque en el historial de git. Ejecute estos comandos en la copia y cambie los nombres de las carpetas para que coincidan con su proyecto.

grep -rhoE "(NEXT_PUBLIC|VITE)_[A-Za-z0-9_]+" app src pages lib 2>/dev/null | sort -u
git log --all --full-history --oneline -- '*.env*'

El segundo comando está pensado para listar los commits que tocaron un archivo env. Abra cada commit que muestre y compruebe que el archivo no contenía claves reales. Una lista vacía significa que este comando no encontró ninguno, no que no exista ninguno.

Trampa: quitar la clave de git no es el primer paso. La guía de GitHub dice que, cuando el dato sensible es un secreto, el primer paso es revocarlo o rotarlo (documentación de GitHub: Removing sensitive data from a repository).

7. Dominio y DNS: ¿apunta el nombre adonde espera el hosting?

Un registro DNS asocia un nombre con un servidor. Su TTL (tiempo de vida) es el tiempo que el registro permanece en caché.

Comprobación: pregunte al DNS por el dominio raíz y por www, y lea después el TTL de cada registro en la tabla de registros de su proveedor de DNS. Ejecute estos 2 comandos en una ventana de terminal.

dig +short YOUR-DOMAIN
dig +short www.YOUR-DOMAIN

El comando dig pregunta a un servidor de nombres por los registros de un nombre y muestra las respuestas. Compare cada respuesta con lo que le pide establecer la página de dominios de su hosting. Si su sitio usa los dos nombres, compruebe ambos.

Trampa: un TTL largo puede ralentizar un cambio. Cuando llegue a planificar uno, baje primero el TTL y espere a que expire el TTL antiguo (esto edita un registro DNS, así que no forma parte de la comprobación). Cambie el dominio en último lugar, cuando las variables de entorno, los orígenes CORS y las URL de los webhooks ya nombren el dominio final.

¿Cuáles son los límites de estas comprobaciones?

Las afirmaciones respaldadas por una fuente de esta página proceden de las páginas de documentación enumeradas en Fuentes, leídas el 10 de octubre de 2026; no se anotaron las versiones de Next.js, de Vite ni de la API de Stripe. Las definiciones sencillas, las comprobaciones, los consejos, la tabla, la hoja y el límite de tiempo son nuestros.

• Se desconoce: con qué frecuencia ocurre cada diferencia en las aplicaciones creadas con IA. Esta página no tiene datos al respecto, y el orden de las 7 es un orden de lectura, no una clasificación.
• Otros proveedores pueden diferir: los webhooks se muestran con Stripe, y las variables de entorno con Next.js y Vite. Esta página no enlaza documentación sobre límites de tiempo, migraciones ni registros DNS, así que lea las páginas de su propio hosting y de sus herramientas para esos puntos, y vuelva a leer cualquier página antes de basarse en un comando o en una cifra.
• No probado: los comandos y la hoja no se ejecutaron en un proyecto real. La comprobación de secretos cubre los nombres destinados al navegador y los archivos env del historial de git, no los archivos del servidor, así que un OK en ese punto no es prueba de que no haya ninguna fuga.

¿Qué puedo comprobar hoy?

Dedique 60 minutos a las comprobaciones y rellene la hoja de comprobación del despliegue de abajo: una línea por diferencia, cada una terminada en OK, DESCONOCIDO o CON FALLO. El resultado visible son 7 líneas y un número: cuántas no están OK.

¿Qué aspecto tiene la hoja de comprobación del despliegue?

Pegue una copia de la hoja por proyecto en un archivo de texto o en un documento.

HOJA DE COMPROBACIÓN DEL DESPLIEGUE (trabaje sobre una copia, no cambie nada en producción, pare a los 60 minutos)
PROYECTO:
URL EN PRODUCCIÓN:
HOSTING:
REVISADO POR Y FECHA:

1 VARIABLES DE ENTORNO: NOMBRES EN EL CÓDIGO QUE NO ESTÁN EN EL HOSTING: ____ | VARIABLE DE URL AÚN EN LOCALHOST: SÍ / NO | ESTADO: OK / DESCONOCIDO / CON FALLO
2 TIEMPOS DE ESPERA: ACCIÓN DE USUARIO MÁS LENTA: ____ | LÍMITE DEL HOSTING SEGÚN SU DOCUMENTACIÓN: ____ | ENTRADAS DE TIEMPO DE ESPERA AGOTADO EN LOS REGISTROS DEL HOSTING: SÍ / NO | ESTADO:
3 CORS: ORIGEN PERMITIDO PARA EL SITIO EN PRODUCCIÓN: ____ | COINCIDENCIA EXACTA (HTTPS, WWW): SÍ / NO | ESTADO:
4 WEBHOOKS: EL ENDPOINT ES LA DIRECCIÓN HTTPS EN PRODUCCIÓN: SÍ / NO | ENTREGAS FALLIDAS: ____ | EL SECRETO PERTENECE A ESTE ENDPOINT: SÍ / NO | ESTADO:
5 MIGRACIONES: CARPETA DE MIGRACIONES EN EL REPOSITORIO: SÍ / NO | PASO DE MIGRACIÓN EN EL REGISTRO DE DESPLIEGUE: SÍ / NO | PENDIENTES EN PRODUCCIÓN: ____ | ESTADO:
6 SECRETOS: NOMBRES DESTINADOS AL NAVEGADOR QUE PARECEN CLAVES: ____ | ARCHIVOS ENV EN EL HISTORIAL DE GIT: SÍ / NO | ESTADO:
7 DOMINIO Y DNS: RESPUESTAS DEL DOMINIO RAÍZ: ____ | RESPUESTAS DE WWW: ____ | COINCIDE CON LAS INSTRUCCIONES DEL HOSTING: SÍ / NO | TTL: ____ | ESTADO:

RECUENTO DE LÍNEAS QUE NO ESTÁN OK: ____
NOTAS: CADA LÍNEA EN DESCONOCIDO O CON FALLO, CON LO QUE VIO

Siguiente paso

Fuentes

Comprobadas el 10 de octubre de 2026.

• Next.js: Environment Variables (variables de entorno)
• Vite: Env Variables and Modes (variables de entorno y modos)
• MDN: Cross-Origin Resource Sharing (intercambio de recursos de origen cruzado)
• Stripe: Webhooks
• GitHub: Removing sensitive data from a repository (eliminar datos sensibles de un repositorio)