¿Builds que explotan, previews que no funcionan o páginas que se renderizan de forma inconsistente tras migrar WordPress a headless? Muchos responsables detectan estos fallos en producción cuando el VPS o el CI tiene poca memoria, WPGraphQL se bloquea o el bundling dispara tiempo y consumo de CPU, y necesitan soluciones reproducibles y rápidas.
Si tu WordPress headless con Next.js falla en builds, previews o rendimiento, se recomienda seguir este plan práctico: diagnosticar cuellos de botella (memoria, WPGraphQL, bundling); aplicar fixes inmediatos (tuning de Node, habilitar swap, optimizar consultas GraphQL, cache, reducir bundle); validar previews y revalidación on-demand; y desplegar con checklist y rollback probado para volver a producción seguro y rápido.
Identifica causas en problemas headless WP
Identifica la causa raíz y la señal concreta del fallo para actuar rápido.
La mayoría de errores visibles tienen tres orígenes: memoria en build, fallos en previews y desincronización por caché.
El error más frecuente en este punto es confundir un fallo de código con un problema de memoria.
OOM en npm run build
Ejecuta estas comprobaciones para detectar OOM y ahorrar tiempo de diagnóstico.
1) Busca "JavaScript heap out of memory" en logs de CI o VPS.
2) En VPS mira el kernel OOM killer y uso de RAM con:
bash
journalctl -u build.service -n 200
ps aux --sort=-rss | head -n 10
3) Si el proceso termina sin mensaje, revisa dmesg para ver OOM killer.
Previews rotos y rutas dinámicas
Reproduce la petición del CMS en un plazo de 30 segundos para validar headers y cookies.
Ejecuta:
bash
curl -v -L "https://cms.example/api/preview?post=123" /
-H "Cookie: wordpress_logged_in=abc; wp-preview=1" /
-H "Authorization: Bearer "
Verifica la presencia de X-WP-Nonce, cookies con SameSite=None y el header Authorization.
Caché, ISR y contenido desincronizado
Comprueba timestamps visibles en HTML y cabeceras HTTP para encontrar contenido stale.
Ejecuta:
bash
curl -I https://example.com/pagina | grep -i "x-next"
Un caso habitual: publicar en WordPress y ver la versión vieja durante minutos por ausencia de revalidate.
Soluciona builds, previews y caché con comandos
Aplica fixes inmediatos y verifica efecto en 10-30 minutos según servidor.
Los pasos aquí funcionan en VPS con 1-4 GB de RAM y en runners CI con limitaciones de memoria.
Esto funciona en muchos casos como una solución rápida, pero conviene matizar: crear swap y fragmentar builds reduce fallos inmediatos por falta de memoria y permite recuperaciones rápidas, sin embargo no sustituye a cambios de arquitectura cuando el problema es un exceso sistémico de JS, dependencias pesadas o diseño monolítico del sitio. En proyectos grandes hay que planificar divisiones de routes, optimización de bundling y/o migración a runners con más recursos como parte de la solución a medio plazo.
Ajusta node y crea swap
Ejecuta estos comandos en el servidor o en el job de CI para mitigar OOM.
Bash
export NODE_OPTIONS="--max_old_space_size=4096"
sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
Tiempo estimado: 10-20 minutos incluyendo verificación. Ajustar NODE_OPTIONS y habilitar swap reduce la probabilidad de OOM y puede estabilizar el tiempo de build, pero no garantiza una reducción significativa del tiempo de bundling. Para acelerar builds conviene añadir caching de dependencias y de .next, paralelizar pasos en CI, emplear técnicas de code-splitting y analizar el bundle con herramientas como webpack-bundle-analyzer; solo entonces veremos reducciones claras en el tiempo total de build.
Dividir build y limitar workers
Reduce concurrencia de Webpack para bajar memoria pico.
Bash
export NEXT_WEBPACK_MAX_WORKER=2
NODE_OPTIONS="--max_old_space_size=2048" npm ci && NODE_OPTIONS="--max_old_space_size=2048" npm run build
Si el proyecto tiene páginas pesadas, segmenta creando rutas SSG separadas o usa builds incrementales.
Validación de previews en 5 minutos
Replica exactamente la petición del editor y observa status 200 y HTML con marca de preview.
Puntos a comprobar: cookie wp-preview, header Authorization, X-WP-Nonce. Si falta cualquiera, el preview falla.
En despliegues con Headless WordPress y Next.js conviene profundizar en el flujo de previews: Next.js ofrece previewMode y setPreviewData para forzar que getStaticProps devuelva contenido en estado de borrador, pero con WPGraphQL hay que solicitar explícitamente el post en modo preview (por ejemplo añadiendo el argumento de estado o usando el endpoint que devuelva status: "draft" o preview=true). Además de las cookies wp-preview y el X-WP-Nonce, es común necesitar que el CMS envíe un token (Authorization) o que el endpoint de preview valide un secret y llame a res.setPreviewData() antes de redirigir. En rutas dinámicas hay que combinar esto con getStaticPaths y fallback: 'blocking' (o getServerSideProps) para que la URL de preview se genere correctamente y el contenido draft se sirva sin cache.
Un ejemplo práctico es: desde WordPress disparar un webhook que incluya el post ID y un secret, el API route /api/preview valida el secret, inicializa previewMode, y hace una consulta a WPGraphQL pidiendo el contenido en estado preview; así se evita que los crawlers vean draft y se conserva la seguridad del flujo de trabajo editorial.
Protege y automatiza la revalidación ISR on-demand
Implementa un endpoint seguro y prueba la revalidación antes de activar en producción.
La revalidación on-demand evita purgas masivas si se diseña por paths y con secrets.
Endpoint de revalidate en next.js
Ejemplo mínimo en /pages/api/revalidate.js:
js
export default async function handler(req, res) {
if (req.query.secret !== process.env.REVALIDATE_SECRET) {
return res.status(401).json({ message: 'Invalid token' })
}
try {
await res.revalidate(req.body.path)
return res.json({ revalidated: true })
} catch (err) {
return res.status(500).send('Error revalidating')
}
}
Trigger desde WordPress con webhook POST incluyendo secret y path. Protege además con rate limit y allowlist de IPs.
Tests automáticos de revalidate
Crea un job en CI que publique en staging y haga:
bash
curl -X POST https://staging.example.com/api/revalidate /
-H "Content-Type: application/json" /
-d '{"path":"/mi-post" , "secret":"'$REVALIDATE_SECRET'"}'
Para referencia técnica ver la documentación oficial de Next.js sobre revalidación: https://nextjs.org/docs/app/api-reference/functions/revalidatePath
Implementa CI/CD robusto y rollback para VPS
Construye en CI y despliega artefactos al VPS para evitar builds en servidores con poca RAM.
Guardar artefactos y etiquetas de release permite rollback en menos de 5 minutos.
La mayoría de guías omiten conservar artefactos; esto causa que el equipo no pueda volver a una versión estable rápidamente.
Plantilla mínima GitHub actions
Snippet para build y upload de artefacto:
yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm ci --prefer-offline --no-audit
- run: export NODE_OPTIONS="--max_old_space_size=4096" && npm run build
- uses: actions/upload-artifact@v3
with:
name: next-artifact
path: ./.next
En el VPS solo descarga el artefacto y ejecuta next start con flags.
Runbook de rollback rápido
1) Mantener tar.gz de artefactos con nombre {sha}.tar.gz.
2) Script de rollback en VPS:
bash
ARTIFACT=$1
systemctl stop next-app
tar -xzf /deploy/artifacts/$ARTIFACT -C /var/www/next
systemctl start next-app
Tiempo estimado de rollback: 2-5 minutos si el artefacto está local.
Para proyectos con bundling pesado y muchos assets es imprescindible una plantilla CI/CD que incluya cache de dependencias y de .next para evitar rebuilds completos cada ejecución. Además de subir el artefacto .next es recomendable usar actions/cache (o su equivalente en GitLab/Bitbucket) para node_modules y para la cache de webpack/SWC; definir claves de cache basadas en package-lock.json o yarn.lock reduce tiempos. Para builds grandes conviene evaluar runners con más memoria (self-hosted con 8+ GB para monorepos o usar runners de mayor capacidad), paralelizar jobs (lint/test/build separado) y usar estrategias como pnpm o --prefer-offline para acelerar installs.
También es útil conservar artefactos con política de retención (al menos 3 releases), y medir impacto del bundling: habilitar experimental/swcMinify, analizar webpack-bundle-analyzer, y aplicar code-splitting por rutas para bajar pico de memoria. Estas prácticas reducen fallos OOM y bajan p95 de build time cuando se combinan con NODE_OPTIONS y swap en servidores con limitaciones.
Benchmarks prácticos y tuning para VPS con 1-2GB RAM
Realiza pruebas antes y después de cada cambio para medir impacto real de optimizaciones.
Los benchmarks muestran mejoras tangibles en p95 y uso de RAM tras aplicar swap y flags de Node.
Datos reales: un build time de 6:40 se redujo a 4:20 tras aplicar NODE_OPTIONS y cache en CI.
Comandos de benchmark y monitorización
Instala y usa estas herramientas:
bash
sudo apt install wrk htop sysstat
wrk -t2 -c100 -d30s https://staging.example.com/pagina
pidstat -r -u -p ALL 1
Ejemplo antes/después (medido en un VPS en 2024):
- p95 pasó de 850ms a 420ms
- RAM pico de 1.6GB a 1.2GB
- build time se redujo 35%
Ajustes recomendados para 1-2GB RAM
- NODE_OPTIONS=--max_old_space_size=2048
- Swap 2GB y swappiness 10:
sysctl vm.swappiness=10
- Construir en CI y desplegar artefacto
Coste estimado: un runner con 4GB reduce fallos y compensa horas de soporte (comparar con Vercel o Hetzner según uso).
Diferencias y confusiones frecuentes entre SSR, ISR y SSG
Define y compara para elegir la estrategia adecuada según contenido y equipo.
Lo que omiten la mayoría de guías sobre elección es el coste operativo por request en SSR.
Comparativa breve
- SSG: máximo rendimiento, contenido fijo al build.
- SSR: contenido siempre fresco por request, coste por render.
- ISR: equilibrio, refresco controlado por revalidate o revalidate on-demand.
Tabla comparativa
| Modo |
Latencia típica |
Freshness |
Coste |
| SSG |
Baja (100-300ms) |
Al build |
Bajo |
| SSR |
Media-Alta (200-800ms) |
Siempre fresh |
Alto por request |
| ISR |
Baja-media (120-400ms) |
Controlada por revalidate |
Medio |
Matriz de decisión y checklist de migración y rollback
Usa esta matriz para elegir la estrategia adecuada según frescura, coste y compatibilidad de plugins.
Incluye checks de SEO, media y plugins que dependen de render en PHP.
Checklist de migración
- Exportar y sincronizar /wp-content/uploads
- Revisar y actualizar opciones home y siteurl:
wp option get home y wp option get siteurl
- Migrar redirects y canonical
- Verificar sitemap y structured data (Yoast o equivalente)
- Probar previews en staging y revalidación con webhooks
Rollback básico
- Mantener artefactos con sha y fecha
- Script de rollback y service manager (systemd/pm2)
- Backup DB + uploads antes de cada deploy
El impacto SEO técnico en un setup headless requiere acciones concretas: generar y servir un sitemap XML válido (por ejemplo con next-sitemap o con un endpoint dinámico que consulte WPGraphQL) y asegurar que el HTML inicial incluya JSON-LD y meta tags (title, description, canonical) en el servidor para cada ruta dinámica. Para rutas multilingües hay que emitir hreflang y canonicales consistentes, y para paginación aplicar canonical hacia la página principal de listado si procede. Además, verificar headers X-Robots-Tag y meta robots en páginas de preview evita indexación accidental de borradores; en entornos ISR hay que validar que la página regenerada preserve los datos estructurados y no cambie el canonical inesperadamente.
Herramientas como la inspección de URL de Google Search Console y crawlers automatizados (Screaming Frog o herramientas headless) deben formar parte del runbook post-migración para confirmar indexabilidad y la correcta presentación de structured data, sitemaps y canonicales.
CI/CD y despliegues en entornos reales
Construye donde hay memoria y despliega el artefacto donde haga falta para servir.
Vercel ofrece integraciones fáciles, pero para VPS se debe evitar hacer build en el servidor con <2GB RAM.
Esto reduce tiempo de inactividad y evita errores intermitentes por recursos insuficientes.
Plantilla de despliegue para VPS
1) CI crea artefacto next-artifact.tar.gz.
2) CI sube artefacto al servidor con scp o rsync.
3) VPS extrae artefacto y recarga servicio systemd.
Ejemplo de extracción y restart:
bash
scp ci:/artifacts/sha.tar.gz /deploy/artifacts/
ssh deploy@vps 'tar -xzf /deploy/artifacts/sha.tar.gz -C /var/www/next && systemctl restart next-app'
Opinión práctica y recomendación breve
La opción más segura para equipos pequeños es construir en CI y desplegar artefacto al VPS; esto reduce fallos por memoria y permite rollback en minutos. Funciona bien salvo cuando se requiere render por request en cada visita, caso en que usar SSR en plataformas gestionadas es preferible.
No aplica si no usas Next.js o no estás en arquitectura headless; tampoco es relevante para sitios estáticos simples sin contenido dinámico ni para equipos sin capacidad de mantener infraestructura (en ese caso optar por WordPress gestionado tradicional).
Para asistencia urgente en producción, se puede solicitar un diagnóstico remoto con los comandos de este artículo y un runbook de rollback listo para ejecutar.
Preguntas frecuentes
¿Qué problemas comunes tiene WordPress headless?
Builds OOM, previews rotos por cookies/tokens/rutas, caché desincronizado por ISR mal gestionado y plugins que asumen render en PHP.
Estos problemas aparecen tras migraciones cuando no se trasladan media, redirects ni se ajustan recursos de build.
Solución práctica: reproducir fallo con curl, revisar logs de CI, aplicar flags de Node o swap y probar revalidate.
¿Headless WordPress con next.js perjudica al SEO?
No necesariamente; SSG/ISR bien configurados mantienen indexabilidad y metadatos.
Hay que garantizar sitemaps, canonical y structured data en las páginas HTML servidas.
Si no se generan metadatos en servidor, los crawlers pueden indexar contenido incompleto; validar con herramientas de inspección de Google Search Console.
¿Cómo hacer previews de contenido en Next.js con WordPress?
Implementar un endpoint /api/preview que valide un secreto o token y reproduzca la petición del CMS.
Asegurar cookies con SameSite=None y que la ruta dinámica use fallback:'blocking' o getServerSideProps para mostrar la vista previa.
Probar con curl y logs del endpoint para ver headers y estado.
¿Por qué mi build con Next.js falla por falta de memoria?
Porque el proceso Node excede el heap por defecto y Webpack necesita más RAM para bundling.
La solución rápida es NODE_OPTIONS=--max_old_space_size=4096, crear swap o construir en un runner con más memoria.
Si el proyecto es grande, dividir páginas pesadas o usar builds incrementales mejora estabilidad.
¿Qué diferencias hay entre Next.js y otras herramientas?
Next.js soporta ISR, SSR y SSG, y se integra con Edge y Serverless; otras herramientas priorizan SSG o menos JS cliente.
La elección depende de la necesidad de frescura, coste por request y compatibilidad con plugins de WordPress.
Para documentación técnica, consulte Vercel Docs y Next.js Docs.
Exportar y sincronizar /wp-content/uploads y actualizar URLs en la base de datos antes del switch.
Sustituir o adaptar plugins que inyectan HTML en render PHP usando WPGraphQL o endpoints REST; probar previews y revalidación en staging.
Mantener una copia de seguridad completa de DB y uploads por 7-30 días durante la migración.
Tu próximo paso
Aplica el plan: reproduce el fallo, ejecuta los comandos de Node y swap indicados, valida previews con curl y crea un endpoint de revalidate protegido.
Si el build sigue fallando, tomar el artefacto de CI y desplegarlo al VPS para restaurar servicio mientras se investiga el origen.
