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:
- 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. - 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 incluyeX-Blockstudio-Static-Prerender: HIT. - 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:
{
"$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.enabledregistra el entorno de ejecución. Mientras estéfalse, la función no escribe archivos ni registra enlaces de solicitud.ttles la antigüedad máxima, en segundos, de un documento almacenado (valor predeterminado:86400).dynamicPathsenumera los prefijos de ruta que siempre deben generarse en tiempo real.warmprograma un proceso en segundo plano que vuelve a generar las URL públicas obsoletas cadaintervalsegundos.
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_*ocomment_author_email_*, salvo queserveLoggedInesté 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:
<!-- 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:
wp bs prerender status
{
"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:
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_CACHEque no le pertenezca. Si otro plugin de caché ya controlaadvanced-cache.php, el servicio anticipado permanece desactivado. - Si
WP_CACHEya está definido comotrue,wp-config.phpno se modifica. En los alojamientos dondewp-config.phpno 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,Linkde forma predeterminada, se almacenan con cada documento y se vuelven a enviar en cada visita, por lo que un encabezadoLinkque una página envía conheader()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 // 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 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:
{
"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:
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 susdynamicPaths,wp-adminywp-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
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
- Referencia de prerenderizado estático: compilación de grafos, activación de artefactos, retención y hooks de observabilidad.
- Rendimiento: qué cambia el perfil
speedy cómo medirlo. - Almacenamiento en caché: el directorio de caché donde se guarda cada documento.
- Fragmentos personalizados en páginas en caché: contenido por visitante en rutas estáticas.
- Despliegue de un sitio Blockstudio: cómo encajan la sincronización, la purga y el precalentamiento de páginas en una versión.