Saltar al contenido

Prerenderizado estático

El prerenderizado estático es una caché HTML anónima y opcional. Una respuesta almacenable en caché debe ser un documento HTML completo y puede excluirse mediante <!-- blockstudio:no-cache -->. Blockstudio omite las solicitudes que no sean GET, las cadenas de consulta, el administrador de WordPress, REST, Ajax, cron, los feeds, los resultados de búsqueda que estén por debajo de la ruta base de búsqueda en la ruta principal del sitio (como /search/term/), las cabeceras de vista previa y lienzo, las solicitudes con nonce, las rutas dinámicas declaradas, las cookies de contraseña o comentarios y, de forma predeterminada, las solicitudes de usuarios con sesión iniciada. Una página cuya ruta solo contenga un segmento search o preview más adelante, como /docs/blocks/preview/, se almacena en caché como cualquier otra página.

JSON
{
  "performance": {
    "staticPrerender": {
      "enabled": true,
      "ttl": 3600,
      "invalidate": "graph",
      "earlyServe": true,
      "serveLoggedIn": false,
      "dynamicPaths": ["/account", "/checkout"],
      "replayHeaders": ["Link"],
      "warm": {
        "enabled": true,
        "interval": 900,
        "concurrency": 4,
        "transport": "http"
      }
    }
  }
}

Los usuarios con sesión iniciada solo pueden obtener un resultado existente si serveLoggedIn es verdadero; las respuestas personalizadas nunca generan entradas de caché. Las rutas dinámicas respetan los límites de ruta: /account coincide con /account/orders, pero no con /accounting.

Mientras la función está desactivada, no escribe archivos, no instala ningún drop-in ni registra ganchos de solicitud o de administración. earlyServe: false tampoco registra ninguna devolución de llamada de administración de Early Serve, y warm.enabled: false no registra ninguna devolución de llamada cron ni programación. Al desactivar cualquiera de las dos funciones se elimina una vez el estado que poseían; las solicitudes posteriores no realizan comprobaciones de limpieza del sistema de archivos ni de cron.

Desactivarla según el entorno

Todos los valores anteriores también pueden configurarse con un filtro de ajustes. Blockstudio se inicia antes que el tema activo, desde un plugin o desde el autoload Composer del tema, por lo que vuelve a resolver sus ajustes de ejecución una vez cargado el tema y decide en after_setup_theme qué ganchos de prerenderizado estático registrar. Por tanto, surte efecto un filtro añadido por un plugin o en functions.php del tema:

PHP
add_filter('blockstudio/settings/performance/staticPrerender/enabled', function ($enabled) {
    return 'local' === wp_get_environment_type() ? false : $enabled;
});

Desactivar la función de esta manera equivale a desactivarla en blockstudio.json: no se registra ningún gancho de solicitud, contenido, administración o cron, y se elimina una vez la entrada de Early Serve de un sitio que se hubiera servido antes de forma temprana. Un filtro añadido más tarde, por ejemplo en init, no cambia qué ganchos se registran.

Modos de firma y de grafo

El modo signature rellena una respuesta con clave de identidad cuando se produce una ausencia normal de caché anónima. Es práctico para sitios WordPress habituales y se renueva tras cambios en el sitio.

El modo graph está pensado para integraciones deterministas de compilación y despliegue. Llame a Static_Prerender_Runtime::build_plan() con las URL de origen activas, renderice solo affectedUrls y registre después cada resultado con persist_built_response() o persist_skipped_response(). El plan compara los archivos compartidos y los hashes exactos de las dependencias de cada página. garbage_collect() elimina las URL borradas y los HTML sin referencias.

PHP
use Blockstudio\Static_Prerender_Runtime;

$plan = Static_Prerender_Runtime::build_plan($sourceUrls);

foreach ($plan['affectedUrls'] as $url) {
    $result = render_with_dependencies($url);

    Static_Prerender_Runtime::persist_built_response(
        $url,
        $result['html'],
        $result['files'],
        $result['virtualHashes']
    );
}

$targets = array_keys($plan['live']);
Static_Prerender_Runtime::garbage_collect($targets);

Los argumentos opcionales de host y ruta principal de destino reescriben las rutas para un despliegue sin usar la ruta de la primera página como raíz del sitio. Las herramientas por lotes pueden usar Static_Prerender_Batch_Renderer::render() y fragmentos N/TOTAL estables; Static_Prerender_Batch_Renderer::parse_shard() y select_shard() respaldan la opción de fragmentos, para que quien realiza la llamada pueda calcular la misma partición que usaría el renderizador. Durante una compilación, Static_Prerender_Batch_Renderer::is_rendering() indica si la solicitud actual es un renderizado por lotes y no de un visitante, para que una plantilla pueda omitir tareas que no deben ejecutarse durante la compilación. El filtro genérico blockstudio/static_prerender/render_internal proporciona un transporte internal; el HTTP opcional de reserva utiliza la cabecera de calentamiento habitual.

Qué registra el modo de grafo

Con el transporte HTTP predeterminado, Static_Prerender_Batch_Renderer::render() envía un token firmado con cada solicitud de calentamiento, y la solicitud informa de los archivos que ha leído: la plantilla WordPress cargada, la plantilla, los archivos de plantilla y los archivos de recursos de cada bloque Blockstudio renderizado, los archivos añadidos mediante blockstudio/render/dependencies y, en una página sincronizada, sus archivos de definición, plantilla, contenido y diseño. El informe se guarda en el directorio de caché del sitio, que el renderizador y el servidor web ya comparten para el HTML renderizado. En la siguiente compilación, build_plan() vuelve a calcular el hash de esos archivos y marca solo las rutas cuyos archivos han cambiado, además de las rutas nuevas, las rutas que hayan superado su ttl y todas las rutas cuando cambia un archivo compartido (blockstudio.json, theme.json, style.css, functions.php, header.php, footer.php, todo lo que hay bajo inc/, parts/ y templates/, y las fuentes de los recursos UI agrupados de Blockstudio). La firma compartida calcula el hash de las fuentes, nunca del resultado compilado, por lo que los archivos _dist que compila el primer renderizado de una compilación no la alteran: artifact_entry() obtiene el ID de compilación de la misma firma que build_plan() había visto antes del renderizado.

El contenido que solo existe en la base de datos no es un archivo y no se registra: publicaciones editadas en el administrador, opciones, filas generadas o precios. Para recoger esos cambios, una compilación debe pasar $force a build_plan() o renderizar por sí misma las URL afectadas. El transporte internal registra las dependencias que devuelve su filtro.

Servicio temprano y despliegue atómico

Con earlyServe activado, Blockstudio administra un pequeño wp-content/blockstudio-static-prerender-map.php, un drop-in de advanced-cache.php y una declaración exacta de WP_CACHE. El drop-in lee un mapa de rutas por sitio y transmite una respuesta válida desde la caché antes de iniciar WordPress, los plugins o el tema.

Blockstudio nunca sobrescribe un mapa, drop-in o declaración de WP_CACHE ajenos. Los artefactos del grafo validan todos los archivos HTML referenciados antes de sustituir el mapa; si la validación falla, el grafo anterior sigue activo. Las entradas de multisitio comparten el mapa, pero se aíslan por host, ruta principal e ID del sitio. Al desactivar la función o Blockstudio, solo se elimina la entrada del sitio actual; los artefactos compartidos se eliminan únicamente cuando desaparece la última entrada propia.

Las herramientas de despliegue pueden activar de forma atómica un grafo completamente renderizado:

PHP
$entry = Static_Prerender_Runtime::artifact_entry($targetUrls);

Blockstudio\Static_Prerender_Early_Serve::install_artifact_entry(
    $entry,
    Static_Prerender_Runtime::cache_root_path()
);

La configuración sigue siendo la fuente de verdad. install_artifact_entry() devuelve false, salvo que tanto enabled como earlyServe sean verdaderos, para que un despliegue nunca instale un mapa, un drop-in y una declaración de WP_CACHE que la siguiente solicitud de administración volvería a eliminar.

install_artifact_entry() conserva build_id de la entrada, para que el despliegue pueda compararlo con el que installed_map_entries() devuelve después. El mapa es un archivo PHP que se lee con include, y cada escritura lo elimina de la caché de código de operación, para que esa lectura obtenga la nueva entrada en el mismo proceso incluso cuando opcache.enable_cli está activado.

Al instalar un artefacto, sus documentos se promueven a un ámbito de artefactos específico que la poda de retención nunca toca. Además, los archivos a los que hace referencia el mapa están protegidos contra la expulsión, dondequiera que se encuentren, así que el tráfico de renderizado activo no puede hacer que las rutas del mapa dejen de estar disponibles para el servicio temprano. Una clave de ruta no está direccionada por contenido en su totalidad, así que un nuevo renderizado puede cambiar un documento sin cambiar su clave; la instalación compara los bytes y reemplaza de forma atómica los documentos de artefacto distintos, deja intactos los documentos idénticos y conserva los documentos de artefacto cuya copia de almacenamiento haya desaparecido. Static_Prerender_Early_Serve::last_promotion() informa cuántas rutas se promovieron, reemplazaron, omitieron o conservaron en la última instalación, para que el despliegue pueda registrarlo.

Un documento almacenado fija los recursos de compilación a los que enlaza mediante URL, y esos archivos tienen su propia retención, por lo que cada uno puede durar más que el otro. Antes de servirlo, tanto la caché PHP como el drop-in comprueban que la hoja de estilos Tailwind enlazada y con hash de contenido siga existiendo en el disco. Si falta la hoja de estilos de un documento, se entrega a WordPress en lugar de servirse sin estilos; así se vuelven a publicar juntos la hoja y el documento. Se hace la misma comprobación antes de guardar una respuesta, de modo que nunca se escribe un documento que no podría servirse.

Una solicitud cuyo encabezado Accept contiene text/markdown omite tanto el almacén PHP como el complemento, porque los documentos almacenados son HTML y una página puede responder a esa solicitud con su origen Markdown. Por tanto, los documentos servidos envían Vary: Accept. Al actualizar Blockstudio, se reescribe un complemento anterior en la siguiente escritura del mapa.

Las rutas del grafo asignadas siempre usan el artefacto activado. Cuando una ruta anónima segura no está en ese mapa, pero WordPress ya la ha renderizado y guardado, Early Serve recurre al almacén de ejecución con clave de identidad antes de iniciar WordPress. Esto admite rutas generadas o de cola larga fuera de un grafo de despliegue delimitado deliberadamente. La alternativa usa la identidad del grafo activado y las mismas reglas de host, normalización de ruta, TTL, cookies, cabeceras, cadenas de consulta, rutas dinámicas y omisión de feeds que las rutas asignadas; solo encuentra documentos almacenados durante la ejecución, que nunca incluyen resultados de búsqueda.

Encabezados de respuesta

Un documento almacenado se reproduce sin la solicitud que lo generó, por lo que faltaría en cada visita cualquier encabezado que un tema o plugin envíe con header(). Blockstudio almacena con cada documento los encabezados indicados en replayHeaders y vuelve a enviarlos tanto desde la caché PHP como desde el complemento de servicio anticipado. El valor predeterminado, ["Link"], incluye encabezados como un alternativo de Markdown (rel="alternate"; type="text/markdown"), rel="describedby" o rel="canonical". Los nombres no distinguen entre mayúsculas y minúsculas, y el filtro de configuración modifica la lista como cualquier otro valor:

PHP
add_filter('blockstudio/settings/performance/staticPrerender/replayHeaders', function (array $headers): array {
    $headers[] = 'X-Robots-Tag';

    return $headers;
});

Establezca replayHeaders en [] para desactivar la reproducción de encabezados. Una lista explícita sustituye a la predeterminada, así que incluya Link al añadir otros nombres de encabezado si aún desea reproducir los encabezados de enlace.

Los encabezados se capturan en el proceso que genera la página: desde headers_list() cuando se almacena una página tras un fallo de caché en vivo, y desde la propia solicitud de calentamiento cuando una compilación o el calentador genera contenido sobre HTTP; por eso, un encabezado que el servidor web añade por su cuenta, y vuelve a añadir a cada documento servido, nunca se almacena. Solo se usan los encabezados de la respuesta cuando una generación de HTTP no escribe ningún informe. El transporte internal los devuelve como headers en su resultado, y persist_built_response() los recibe como último argumento, ya sea en forma de líneas Name: value o de mapa de nombre a valor.

Se escriben en <key>.headers.json junto al documento, lo acompañan durante la promoción de artefactos, la recolección de basura y la depuración por retención, y se eliminan cuando una nueva generación no envía ninguno. Los encabezados de cookies, caché y transporte nunca se almacenan ni se reproducen, aunque estén en la lista: Set-Cookie, Cache-Control, Expires, Pragma, Age, ETag, Last-Modified, Vary, Content-Type, Content-Length, Content-Encoding, Transfer-Encoding, Location, Status, Date, y los encabezados salto a salto y de autenticación. Un documento servido establece sus propios Content-Type y Vary.

Los encabezados almacenados se vuelven a comprobar con la lista al enviarlos. La caché PHP lee la configuración actual; el complemento de servicio anticipado lee la copia de la entrada del mapa del sitio, que se actualiza con la siguiente instalación de artefactos o sincronización del mapa. Los documentos almacenados antes de una actualización no tienen archivo de encabezados y se sirven exactamente igual que antes hasta que se vuelvan a generar.

Calentamiento, mantenimiento y observabilidad

La cola de calentamiento es persistente, agrupa por URL, ejecuta un solo trabajo a la vez y recupera las tareas reclamadas que agotan el tiempo de espera. Los cambios de contenido y del sitio fuerzan un trabajo de reemplazo incluso si la firma actual no ha cambiado; las pasadas por intervalo solo ponen en cola las tareas obsoletas. Cada pasada, programada o mediante wp bs prerender warm, renderiza hasta warm.concurrency tareas. El modo graph desactiva el calentador por URL, porque los artefactos del grafo se compilan y activan como una unidad.

Shell
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
wp bs prerender map status
wp bs prerender map prune --dry-run

status informa de la identidad activa, los archivos, los bytes, los registros del grafo, el estado de la cola, el informe del mapa de servicio temprano y los contadores de aciertos, fallos de caché, compilaciones y errores por ámbito.

El mapa de servicio temprano lo comparten todos los sitios de una instalación. map status (y Static_Prerender_Early_Serve::map_report()) muestra las entradas que el servicio temprano ya no puede usar: entradas orphaned cuyo sitio ya no existe y entradas dead cuyo directorio ha desaparecido, además del número de documentos de ruta missing en las entradas restantes. map prune (Static_Prerender_Early_Serve::prune_map()) elimina las entradas huérfanas y obsoletas bajo el bloqueo del mapa e informa del motivo de cada una; --dry-run solo informa. Al eliminar la última entrada, se eliminan el mapa, el drop-in y la declaración de WP_CACHE. Al borrar un sitio de una red multisitio se eliminan sus entradas de inmediato, y la limpieza de la caché nunca recoge el espacio de nombres desde el que se sirve un artefacto activado, así que las entradas solo quedan obsoletas cuando sus archivos se eliminan por otros medios.

Observe los resultados de cada respuesta con blockstudio/static_prerender/outcome y los resultados de toda la caché compartida con blockstudio/cache/outcome.

Desinstalación

Las instalaciones sin un gancho de desactivación de plugin, como las configuraciones incluidas en Composer, pueden eliminar de una sola vez todo lo que posee la función con un solo comando:

Shell
wp bs teardown

Elimina los eventos cron y el estado de prerenderizado estático que posee la instalación: la entrada del mapa del sitio actual y el drop-in compartido y la declaración de WP_CACHE cuando desaparece la última entrada propia. Los archivos de configuración quedan intactos, así que al volver a activar la función, todo empieza limpio.

Adopción en producción

Un orden de adopción razonable:

  1. Establezca performance.profile en speed y compruebe la salida de head, los feeds y cualquier plugin que dependa de oEmbed o XML-RPC.
  2. Genere assets/media.json, mueva las plantillas a bs_media_image() y, después, active performance.media.lazy.
  3. Active performance.staticPrerender con earlyServe desactivado, compruebe los aciertos con wp bs prerender status y, después, active earlyServe.

La reversión se realiza por función: al establecer staticPrerender.enabled en false se elimina una vez el estado de Early Serve de Blockstudio y la programación de calentamiento, y se deja el entorno de ejecución de prerenderizado sin registrar. Al volver a establecer performance.profile en compat se revierte el perfil. Cada operación deja las demás capas intactas.

Rendimiento

Los perfiles, el perfilador y las técnicas de renderizado subyacentes.

Almacenamiento en caché

El único directorio de caché donde se guardan todos los artefactos generados.