WordPressEscape

Inicio / Guía

Banco de trabajo

Migrar 528,854 páginas de WordPress a Hugo: notas de ingeniería

Estas son las notas de trabajo de la migración de Unlimited Charters, nuestro sitio hermano interno, de WordPress a Hugo en mayo de 2026. El resumen para el negocio está en el caso de estudio; esta es la parte para quien tenga que hacer el trabajo: qué falló con medio millón de páginas, qué comandos nos dieron problemas y qué comprobaciones ejecutamos ahora en todos los sitios, grandes o pequeños.

6 min de lectura 9 secciones Diseñado para posicionar
En esta página
  1. Contexto
  2. Inventario de plantillas antes del contenido
  3. Compilaciones particionadas y trampas del sistema de archivos
  4. Correcciones de rendimiento aplicadas como cambio de plantilla más una pasada por todo el corpus
  5. Ajustes de Cloudflare que marcaron la diferencia
  6. Detalles de schema y SEO
  7. La captación de clientes potenciales es la parte que no puedes perder
  8. Qué haríamos de otra manera
  9. Fuentes y lecturas adicionales
  10. Preguntas frecuentes
Respuesta rápida

A esta escala, los problemas tienen más que ver con el sistema de archivos y los procesos que con Hugo: particionar las compilaciones, mantener el contenido apartado fuera del punto de montaje de contenido de Hugo, no ejecutar nunca dos procesos de traslado sobre el mismo directorio y tratar cada corrección como un cambio de plantilla más una pasada automatizada por todo el corpus. Las mejoras de rendimiento más importantes fueron las dimensiones de las imágenes, el CSS crítico síncrono, una imagen LCP no diferida, un widget de presupuestos diferido con espacio reservado y la desactivación de Cloudflare Email Obfuscation.

01

Contexto

Unlimited Charters pertenece al mismo grupo que WordPressEscape; esta fue nuestra propia migración de prueba, realizada con acceso completo al servidor. El sitio tenía algo más de medio millón de URL, principalmente páginas de ubicaciones generadas mediante plantillas, además de páginas de categorías, páginas de la flota y un blog. El objetivo era una compilación de Hugo servida como archivos estáticos detrás de Cloudflare, conservando todas las rutas existentes.

02

Inventario de plantillas antes del contenido

Empezamos agrupando las URL según la plantilla de WordPress que las generaba, no según el patrón de la URL. Cada familia requería tomar una decisión: reconstruirla como un layout de Hugo o servir temporalmente una instantánea estática del resultado de WordPress. Reconstruir primero las familias con más tráfico y generar instantáneas de las páginas atípicas permitió avanzar sin quedar bloqueados por la larga cola de páginas personalizadas.

Un detalle importante: en WordPress, la ruta de la URL no siempre coincide con el slug post_name. Las páginas jerárquicas, las reglas de reescritura personalizadas y las importaciones antiguas generaban rutas que no coincidían con el slug, así que la ruta tuvo que obtenerse del rastreo, no de la base de datos.

03

Compilaciones particionadas y trampas del sistema de archivos

Renderizar todas las páginas en una sola ejecución era lento y hacía que cualquier cambio pequeño resultara costoso. Particionamos el proceso: mover los archivos fuente que no estábamos compilando a un directorio de reserva, compilar un subconjunto, desplegarlo y restaurar los archivos. Cuatro trampas nos hicieron perder tiempo:

  1. El directorio de reserva debe estar fuera del punto de montaje de contenido de Hugo. Si se encuentra dentro del directorio de contenido montado, Hugo sigue recorriendo todos los archivos y la partición no sirve de nada.
  2. rsync --exclude=index.html excluye todos los index.html en cualquier nivel, no solo el de la raíz. Hay que anclar el patrón (--exclude=/index.html).
  3. Dos procesos de traslado simultáneos sobre el mismo directorio lo anidan. Dos procesos de restauración ejecutándose a la vez generaron unos 367,000 directorios con un nivel de profundidad de más. Producción funcionaba porque servía el resultado compilado; un único traslado automatizado los dejó planos. Un solo proceso debe controlar el directorio, algo que garantizamos mediante un bloqueo.
  4. mv dir/* target/ falla con este tamaño (la lista de argumentos es demasiado larga). Usa find ... -exec mv -t target {} +.
# renderizar unas pocas páginas sin recompilarlo todo
flock /tmp/uc-content.lock bash -c '
  mv content/migrated/* ../stash/            # el directorio de reserva está FUERA del punto de montaje de contenido
  for s in $(cat targets.txt); do mv ../stash/$s content/migrated/; done
  hugo --minify -d ../staged
  find ../stash -mindepth 1 -maxdepth 1 -exec mv -t content/migrated/ {} +
'
04

Correcciones de rendimiento aplicadas como cambio de plantilla más una pasada por todo el corpus

Cada corrección tuvo dos partes: ajustar la plantilla de Hugo para que las compilaciones futuras fueran correctas y modificar el HTML ya compilado para poder publicarla sin necesitar una recompilación completa. Estas fueron las más importantes:

  • Dimensiones de las imágenes. Una plantilla fijaba width="1600" height="700", mientras que el CSS utilizaba una relación de aspecto diferente. Lo corregimos en 527,815 páginas. El ancho y el alto deben coincidir con la relación de aspecto renderizada; de lo contrario, el navegador reserva un espacio incorrecto (optimizar CLS).
  • Reglas de aspect-ratio en conflicto sobre el mismo selector en dos hojas de estilos; las consolidamos en una sola.
  • CSS crítico en el archivo asíncrono. Las reglas para móviles necesarias durante el primer renderizado estaban en una hoja de estilos diferida, lo que provocaba un reajuste tardío del diseño. Las trasladamos a la hoja de estilos síncrona.
  • Imagen principal cargada de forma diferida. loading="lazy" en la imagen visible en la primera pantalla retrasaba el LCP; lo sustituimos por fetchpriority="high" (optimizar LCP).
  • Imágenes LCP sobredimensionadas sustituidas por variantes más pequeñas, con un ahorro de entre 50 y 440 KB por página.
  • Widget de presupuestos cargado en la primera interacción (con un mecanismo alternativo tras un tiempo de espera), mientras que su contenedor reserva 480 px (560 px en móviles). Antes, su montaje desplazaba la página y provocaba un CLS aproximado de 0.54.
05

Ajustes de Cloudflare que marcaron la diferencia

  • Email Obfuscation desactivado. Su decodificador recorre el DOM después de la carga y reescribe los enlaces de correo electrónico, lo que provocaba desplazamientos del diseño. Fue la fuente de CLS más persistente que encontramos.
  • Rocket Loader desactivado. Reordenaba los scripts e interfería con la carga diferida.
  • Purgar después de cada despliegue. Las cachés perimetrales conservaban HTML antiguo; purgar por ruta después de cada despliegue evitaba servir páginas obsoletas (documentación de purga de Cloudflare).
  • Medir en producción, no en staging. Un entorno de staging sin los mismos ajustes de Cloudflare generaba puntuaciones de laboratorio que no coincidían con las de producción.
06

Detalles de schema y SEO

  • Search Console notificaba errores de datos estructurados porque una entidad Service incluía aggregateRating y review. Los eliminamos en lugar de intentar validarlos; el marcado debe reflejar el contenido que los usuarios pueden ver (directrices sobre datos estructurados).
  • Al principio, las entradas del blog se renderizaban con la plantilla de ubicaciones y heredaban el tipo de schema incorrecto. Ahora cada plantilla declara su propia entidad.
  • 35 rutas incoherentes de flotas y servicios recibieron redirecciones permanentes a las páginas anidadas correctas (redirecciones).
  • Los archivos multimedia pasaron de /wp-content/uploads/ a /uploads/ mediante una única regla 301; una pasada paralela con sed reescribió 528,852 de 528,854 archivos en pocos minutos.
  • Eliminamos Yoast cuando Hugo empezó a generar el sitemap, el schema, las metaetiquetas y robots.txt.
find static-v5 -name '*.html' -print0 \
  | xargs -0 -P 8 -n 500 sed -i 's|/wp-content/uploads/|/uploads/|g'
07

La captación de clientes potenciales es la parte que no puedes perder

El formulario de presupuestos es la fuente de ingresos del sitio, así que recibió sus propias comprobaciones: el punto de montaje del widget debe existir en el HTML compilado de todas las páginas que lo incluyan, los nombres de los campos deben coincidir con lo que espera el endpoint de recepción y un despliegue que sustituya un directorio no debe eliminar la página de presupuestos independiente. Un cambio que elimine silenciosamente la captación de clientes puede parecer correcto en todas las métricas de SEO mientras el negocio deja de recibir solicitudes.

08

Qué haríamos de otra manera

  1. Desactivar Email Obfuscation antes de realizar la primera medición de CLS.
  2. Particionar la compilación desde el primer día.
  3. Bloquear el directorio de contenido desde el primer día.
  4. Documentar el patrón de cambio de plantilla más pasada por todo el corpus antes de la primera corrección, no después de la quinta.
  5. Incluir la comprobación de datos de campo (CrUX) en la lista de lanzamiento, porque las puntuaciones de laboratorio en staging no representan las de producción.

La visión de negocio del mismo proyecto, incluido lo que dejamos en WordPress, está en el caso de estudio.

09

Fuentes y lecturas adicionales

Preguntas frecuentes

¿Es esta una migración de un cliente?

No. Unlimited Charters es un sitio hermano interno que pertenece al mismo grupo que WordPressEscape. Es nuestro propio caso de prueba.

¿Hugo puede gestionar medio millón de páginas?

Sí, pero las compilaciones completas son lo bastante lentas como para que las compilaciones particionadas y una gestión cuidadosa de los archivos sean importantes. La mayoría de nuestros problemas estuvieron relacionados con el sistema de archivos y los procesos, no con errores de Hugo.

¿Qué provocó el mayor desplazamiento del diseño?

El montaje del widget de presupuestos sin espacio reservado (alrededor de 0.54 de CLS en las páginas de categorías) y Cloudflare Email Obfuscation, que reescribía la página después de cargarla.

¿Estas lecciones se aplican a sitios pequeños?

Sí. Las mismas comprobaciones (paridad de URL, dimensiones de las imágenes, CSS crítico, imagen principal no diferida y widgets diferidos) se aplican a un sitio de 40 páginas; simplemente se ejecutan en minutos en lugar de horas.

Analiza mi sitio gratis

Descubre si tu sitio puede recibir el mismo tratamiento

La auditoría gratuita de 60 segundos muestra tu puntuación real de PageSpeed, el número exacto de páginas, las carencias de SEO y las funciones de WordPress que necesitas sustituir. Después, WordPressEscape reconstruye tu sitio en Hugo, conserva todas las URL y te entrega el código fuente desde el primer día, tal como hicimos con UC.

Analiza mi sitio gratis
Seguir leyendo
Todas las guías33
Búsquedas relacionadasmigración de wordpress a hugo528,854 páginas (prueba interna)compilación particionada de hugocorrección de cls en cloudflarelimpieza del schemaparidad de url