Saltar al contenido

Servir WordPress como HTML estático

La mayoría de las páginas de un sitio de marketing o documentación son iguales para todos los visitantes anónimos. WordPress sigue iniciándose, cargando todos los plugins, ejecutando el tema y representando los bloques en cada solicitud. Un plugin de caché de páginas puede ayudar, pero añade otra pieza móvil con sus propias reglas sobre qué es seguro almacenar.

Blockstudio incluye una función opcional de representación previa estática. Almacena documentos HTML anónimos completos en su propio directorio de caché y, si lo permite, los sirve desde un complemento advanced-cache.php antes de que se inicie WordPress. Todo se configura en blockstudio.json.

Esta guía activa la función paso a paso, muestra cómo comprobar qué se almacena y qué no, explica la única regla que protege a los visitantes con sesión iniciada y termina con una configuración de CDN que solo almacena en caché lo que el servidor de origen marca como apto para la caché.

Cómo se atiende una solicitud

Con la representación previa activada, una solicitud apta termina de una de estas tres formas:

  1. Acierto temprano. El complemento encuentra un documento almacenado en su mapa de rutas y lo transmite antes de que se cargue WordPress. La respuesta incluye X-Blockstudio-Static-Prerender: HIT-EARLY.
  2. Acierto. WordPress se inicia y, en template_redirect, Blockstudio encuentra un documento almacenado vigente y lo envía en lugar de representar la plantilla. La respuesta incluye X-Blockstudio-Static-Prerender: HIT.
  3. Fallo de caché. WordPress representa la página normalmente. Si el visitante es anónimo y el resultado es un documento HTML completo con estado 200, Blockstudio lo almacena para la siguiente solicitud.

Las solicitudes que no cumplen los requisitos nunca acceden a la caché.

Paso 1: Activar el perfil y la caché

Empiece con el perfil de rendimiento y la representación previa, sin activar el servicio anticipado:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "performance": {
    "profile": "speed",
    "staticPrerender": {
      "enabled": true,
      "ttl": 86400,
      "earlyServe": false,
      "dynamicPaths": ["/account", "/checkout", "/login"],
      "warm": {
        "enabled": true,
        "interval": 900,
        "concurrency": 4
      }
    }
  }
}

Qué hace cada opción:

  • profile: "speed" activa los valores de producción predeterminados del frontend: elimina el ruido de la cabecera, la detección de oEmbed, XML-RPC y los recursos genéricos del frontend del núcleo, y precarga los enlaces del mismo origen cuando hay intención de visitarlos. Pruebe primero la eliminación de recursos del frontend del núcleo, porque las páginas que dependan de ellos mostrarán errores visibles. Cualquier valor secundario anula el perfil.
  • staticPrerender.enabled registra el entorno de ejecución. Mientras esté false, la función no escribe archivos ni registra enlaces de solicitud.
  • ttl es la antigüedad máxima, en segundos, de un documento almacenado (valor predeterminado: 86400).
  • dynamicPaths enumera los prefijos de ruta que siempre deben generarse en tiempo real.
  • warm programa un proceso en segundo plano que vuelve a generar las URL públicas obsoletas cada interval segundos.

La línea $schema cubre todas las claves, así que un editor con compatibilidad con esquemas JSON señala errores como "ttl": 0 (el mínimo es 1).

Paso 2: Saber qué solicitudes cumplen los requisitos

Blockstudio aplica criterios conservadores para almacenar contenido. Estas solicitudes siempre omiten la caché:

  • cualquier método distinto de GET
  • cualquier URL con una cadena de consulta
  • wp-admin, wp-json, wp-login.php, xmlrpc.php, Ajax y cron
  • feeds, búsquedas y rutas de vista previa
  • solicitudes que envían una cabecera X-WP-Nonce
  • rutas bajo dynamicPaths
  • visitantes con una cookie wordpress_logged_in_*, wp-postpass_* o comment_author_email_*, salvo que serveLoggedIn esté activado

Las rutas dinámicas se comparan respetando los límites entre rutas. Con la configuración anterior:

Solicitud ¿Se omite la caché?
/pricing/ no
/account/orders/ sí
/accounting/ no
/checkout sí
/pricing/?utm_source=x sí
/blog/feed/ sí

Al almacenar, solo se conserva un documento completo: la respuesta debe empezar por <!doctype html o <html, tener el estado 200 y no contener el marcador de exclusión. Una plantilla que nunca deba almacenarse puede imprimir el marcador en cualquier parte de la página:

HTML
<!-- blockstudio:no-cache -->

Las páginas de error nunca se almacenan, así que un 404 con diseño personalizado nunca puede reproducirse como si fuera una respuesta correcta.

Paso 3: Verificar los aciertos

Visite algunas páginas en una ventana privada y luego consulte Blockstudio para ver qué contiene:

Shell
wp bs prerender status
JSON
{
    "enabled": true,
    "invalidate": "signature",
    "identity": "e6cdd3fcda14ad6ded85a763bd01a33b",
    "cacheRoot": ".../wp-content/blockstudio/cache/sites/.../static-prerender",
    "files": 0,
    "bytes": 0,
    "records": 0,
    "queue": {
        "pending": 0,
        "processing": 0,
        "done": 0,
        "unique": 0,
        "bytes": 0
    },
    ...
    "diagnostics": []
}

files y bytes aumentan a medida que se almacenan documentos, queue muestra la cola pendiente del proceso de calentamiento y diagnostics contiene contadores de aciertos, fallos, compilaciones y errores por ámbito. Para comprobar una sola página, solicítela dos veces como visitante anónimo y busque la cabecera:

Shell
curl -s -o /dev/null -D - https://example.com/pricing/ | grep -i x-blockstudio-static-prerender

La segunda respuesta incluye X-Blockstudio-Static-Prerender: HIT. Use un GET como el anterior: curl -I envía una solicitud HEAD, que siempre omite la caché.

Paso 4: Servir el contenido antes de que se inicie WordPress

Cuando los aciertos sean correctos, configure "earlyServe": true. Entonces Blockstudio gestiona tres pequeños elementos de estado: un complemento wp-content/advanced-cache.php, un mapa de rutas compartido wp-content/blockstudio-static-prerender-map.php y una declaración WP_CACHE en wp-config.php. Se instalan en la siguiente solicitud de administración.

Unas pocas reglas mantienen la seguridad en alojamientos compartidos y en instalaciones multisitio:

  • Blockstudio nunca sobrescribe un complemento de servicio anticipado, un mapa ni una línea de WP_CACHE que no le pertenezca. Si otro plugin de caché ya controla advanced-cache.php, el servicio anticipado permanece desactivado.
  • Si WP_CACHE ya está definido como true, wp-config.php no se modifica. En los alojamientos donde wp-config.php no tenga permisos de escritura, defínalo usted mismo.
  • Antes de servir el contenido, tanto el complemento de servicio anticipado como la ruta PHP comprueban que la hoja de estilos Tailwind con hash de contenido a la que enlaza un documento siga existiendo. Si no existe, la solicitud se envía a WordPress en lugar de servirse sin estilos.
  • Las entradas multisitio comparten un mapa, pero se aíslan por host, ruta de inicio e ID del sitio.
  • Los encabezados de respuesta indicados en replayHeaders, Link de forma predeterminada, se almacenan con cada documento y se vuelven a enviar en cada visita, por lo que un encabezado Link que una página envía con header() se conserva durante el servicio anticipado. Los encabezados de cookies y caché nunca se reproducen.

Los accesos tempranos llevan X-Blockstudio-Static-Prerender: HIT-EARLY. Al desactivar earlyServe o enabled se elimina el estado que Blockstudio administra una sola vez, y wp bs teardown lo elimina explícitamente en instalaciones Composer que no tienen un hook de desactivación.

Visitantes con sesión iniciada y marcado idéntico

De forma predeterminada, los visitantes con sesión iniciada siempre reciben una renderización en vivo. Si se configura "serveLoggedIn": true, también pueden consumir un documento almacenado existente, lo que hace que el sitio sea igual de rápido para editores y clientes que para visitantes anónimos.

Las respuestas personalizadas nunca crean entradas de caché: si no hay una entrada para un usuario con sesión iniciada, se renderiza en vivo y no se almacena. Es fácil pasar por alto la consecuencia. Con serveLoggedIn activado, un visitante con sesión iniciada recibe el documento anónimo cuando existe, y solo obtiene una renderización personalizada en vivo cuando no existe. Cualquier rama de plantilla que dependa del usuario actual aparece únicamente cuando no hay una entrada en caché; por eso, la misma página cambia entre visitas y la rama personalizada queda, en la práctica, inactiva en las rutas almacenadas en caché.

La regla que se deriva es la siguiente: en todas las rutas fuera de dynamicPaths, el marcado de los usuarios con sesión iniciada debe ser idéntico byte por byte al marcado anónimo. Esto significa que no debe haber ramas is_user_logged_in() ni wp_get_current_user() en las plantillas que se renderizan en rutas estáticas:

PHP
<?php // Do not do this on a static route. ?>
<?php if ( is_user_logged_in() ) : ?>
  <a href="/account/">Hi, <?php echo esc_html( wp_get_current_user()->display_name ); ?></a>
<?php else : ?>
  <a href="/login/">Sign in</a>
<?php endif; ?>

Hay dos soluciones claras. Mueva la ruta a dynamicPaths si toda la página es personal, como un panel de cuenta. O mantenga la página estática y renderice la parte personal como una isla de bloque dinámica, que envía un marcador seguro para la caché en el HTML almacenado y obtiene el fragmento real en la propia solicitud del visitante:

PHP
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>

La guía Fragmentos personalizados en páginas en caché explica cómo crear ese bloque.

Invalidación por firma o grafo

invalidate determina cómo caducan los documentos almacenados.

Aspecto signature (predeterminado) graph
Quién llena la caché solicitudes anónimas sin una entrada y el proceso de precalentamiento el paso de compilación y las solicitudes anónimas sin una entrada
Qué caduca las entradas TTL, guardados de entradas y cambios a nivel del sitio una nueva compilación, con el TTL como límite máximo
Proceso de precalentamiento en segundo plano disponible desactivado
Adecuado para sitios comunes sitios con un proceso de despliegue

El modo signature no requiere herramientas. Al guardar una entrada, se purga o vuelve a precalentar la página de inicio y el enlace permanente de esa entrada; los cambios a nivel del sitio, como cambiar el tema, renuevan la identidad de la caché.

El modo graph está pensado para despliegues deterministas. Una compilación calcula un plan con Static_Prerender_Runtime::build_plan(), renderiza solo las URL afectadas, registra cada resultado y activa el conjunto terminado de forma atómica con Static_Prerender_Early_Serve::install_artifact_entry(). Si falla la validación de cualquier documento referenciado, el conjunto anterior sigue activo. Las rutas asignadas se sirven desde el artefacto activado hasta que la siguiente compilación lo sustituya, por lo que el contenido editado en wp-admin llega a esas rutas con el siguiente despliegue. En este modo, se desactiva el proceso de precalentamiento por URL porque los artefactos se compilan y activan como una sola unidad. Una configuración típica de producción es la siguiente:

JSON
{
  "performance": {
    "profile": "speed",
    "staticPrerender": {
      "enabled": true,
      "invalidate": "graph",
      "ttl": 2592000,
      "earlyServe": true,
      "serveLoggedIn": true,
      "dynamicPaths": [
        "/account",
        "/cart",
        "/checkout",
        "/login",
        "/reset-password"
      ]
    }
  }
}

El ttl de 30 días solo limita la antigüedad máxima de un documento servido. La actualización depende del despliegue que vuelve a compilar el grafo. La compilación API, la fragmentación y el transporte interno de renderización se explican en la referencia de prerenderizado estático.

Colocar un CDN delante

El prerenderizado ya indica qué respuestas se pueden compartir: exactamente las que llevan el encabezado HIT. Haga que el origen convierta ese encabezado en uno de caché y configure el CDN para que siga las indicaciones del origen. Con nginx delante de PHP-FPM:

Nginx
map $upstream_http_x_blockstudio_static_prerender $edge_cache_control {
    "~^HIT"  "public, s-maxage=604800";
    default  "";
}

server {
    listen 80;
    server_name example.com;
    root /var/www/html;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php-fpm.sock;
        add_header Cache-Control $edge_cache_control;
    }
}

La expresión regular coincide con HIT y HIT-EARLY. Para cualquier otra respuesta, la variable está vacía y nginx no añade un encabezado con un valor vacío. Por lo tanto, las solicitudes sin una entrada, las rutas dinámicas y las renderizaciones de usuarios con sesión iniciada salen del origen sin una duración de caché compartida.

En el lado de CDN:

  • Almacene en caché HTML solo cuando el origen envíe una duración de caché. Desactive cualquier TTL perimetral predeterminado para las respuestas que no incluyan uno.
  • Omita la caché perimetral para las mismas cookies que Blockstudio trata como personales (wordpress_logged_in_, wp-postpass_, comment_author_email_) y para sus dynamicPaths, wp-admin y wp-json.
  • Purgue CDN después de cada despliegue que cambie páginas, plantillas o recursos. La caché del origen se renueva por sí sola; la perimetral no sabe que debe hacerlo.

Si utiliza Tailwind con "output": "link", la hoja de estilos URL tiene un hash de contenido, por lo que esa ruta se puede servir con un encabezado de caché inmutable de larga duración.

Comandos de mantenimiento

Shell
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
wp bs teardown

warm encola URL públicas obsoletas y renderiza hasta warm.concurrency por ejecución, mostrando un resumen de JSON. purge elimina los documentos almacenados y la cola del sitio actual. teardown elimina los eventos cron y el estado de servicio temprano que administra esta instalación, y deja intactos los archivos de configuración.

Implemente en este orden: primero el perfil, luego el prerenderizado con earlyServe desactivado y, por último, el servicio temprano una vez que status y los encabezados tengan el aspecto correcto. Puede revertir cada capa por separado restableciendo su valor.

Pasos siguientes