Pular para o conteúdo

Servindo WordPress como HTML estático

A maioria das páginas de marketing ou documentação é igual para todos os visitantes anônimos. WordPress ainda inicia, carrega todos os plugins, executa o tema e renderiza os blocos a cada requisição. Um plugin de cache de página pode ajudar, mas é mais uma peça móvel, com regras próprias sobre o que pode ser armazenado com segurança.

Blockstudio oferece uma pré-renderização estática opcional. Ela armazena documentos HTML anônimos completos em seu próprio diretório de cache e, se você permitir, os serve por meio de um drop-in advanced-cache.php antes que WordPress seja iniciado. Tudo é configurado em blockstudio.json.

Este guia ativa o recurso passo a passo, mostra como verificar o que é armazenado ou não em cache, explica a única regra que protege visitantes conectados e termina com uma configuração CDN que só armazena em cache o que a origem marca como armazenável.

Como uma requisição é atendida

Com a pré-renderização ativada, uma requisição elegível termina de uma destas três formas:

  1. Acerto antecipado. O drop-in encontra um documento armazenado no mapa de rotas e o envia antes de WordPress carregar. A resposta contém X-Blockstudio-Static-Prerender: HIT-EARLY.
  2. Acerto. WordPress é iniciado e, em template_redirect, Blockstudio encontra um documento armazenado ainda válido e o envia em vez de renderizar o modelo. A resposta contém X-Blockstudio-Static-Prerender: HIT.
  3. Falha de cache. WordPress renderiza a página normalmente. Se o visitante for anônimo e o resultado for um documento HTML completo com status 200, Blockstudio o armazena para a próxima requisição.

Requisições que não são elegíveis nunca acessam o cache.

Etapa 1: Ative o perfil e o cache

Comece com o perfil de desempenho e a pré-renderização ativados, mantendo o atendimento antecipado desativado:

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
      }
    }
  }
}

O que cada parte faz:

  • profile: "speed" ativa os padrões de produção do frontend: ruído no cabeçalho, descoberta oEmbed, XML-RPC e recursos genéricos do frontend do núcleo são removidos, e links da mesma origem são pré-carregados quando há intenção de acessá-los. Teste primeiro a remoção dos recursos do frontend do núcleo, pois uma página que dependa deles apresentará problemas visíveis. Qualquer valor filho substitui o perfil.
  • staticPrerender.enabled registra o tempo de execução. Enquanto estiver false, o recurso não grava arquivos nem registra hooks de requisição.
  • ttl é a idade máxima de um documento armazenado, em segundos (padrão 86400).
  • dynamicPaths lista os prefixos de caminho que sempre devem ser processados ao vivo.
  • warm agenda um processo em segundo plano que renderiza novamente URLs públicas desatualizadas a cada interval segundos.

A linha $schema abrange todas as chaves, então um editor com suporte ao esquema JSON sinaliza erros como "ttl": 0 (o mínimo é 1).

Etapa 2: Saiba o que é elegível

Blockstudio é conservador quanto ao que armazena. Estas requisições sempre ignoram o cache:

  • tudo que não seja GET
  • qualquer URL com uma string de consulta
  • wp-admin, wp-json, wp-login.php, xmlrpc.php, Ajax e cron
  • feeds, pesquisas e caminhos de pré-visualização
  • requisições que enviam um cabeçalho X-WP-Nonce
  • caminhos sob dynamicPaths
  • visitantes com um cookie wordpress_logged_in_*, wp-postpass_* ou comment_author_email_*, a menos que serveLoggedIn esteja ativado

Os caminhos dinâmicos correspondem a limites de caminho. Com a configuração acima:

Requisição Ignorada
/pricing/ não
/account/orders/ sim
/accounting/ não
/checkout sim
/pricing/?utm_source=x sim
/blog/feed/ sim

Para armazenar o conteúdo, só se guarda um documento completo: a resposta deve começar com <!doctype html ou <html, ter status 200 e não conter o marcador de exclusão. Um modelo que nunca deve ser armazenado pode exibir o marcador em qualquer lugar da página:

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

Páginas de erro nunca são armazenadas, então um 404 temático nunca pode ser reapresentado como se fosse uma resposta bem-sucedida.

Etapa 3: Verifique os acertos

Visite algumas páginas em uma janela privada e depois pergunte a Blockstudio o que ela contém:

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 e bytes aumentam conforme os documentos são armazenados; queue mostra a fila do processo de atualização, e diagnostics traz contadores de acertos, falhas, compilações e erros por escopo. Para verificar uma página específica, solicite-a duas vezes como visitante anônimo e procure o cabeçalho:

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

A segunda resposta contém X-Blockstudio-Static-Prerender: HIT. Use uma GET como acima: curl -I envia uma requisição HEAD, que sempre ignora o cache.

Etapa 4: Atenda antes que WordPress seja iniciado

Quando os acertos estiverem corretos, defina "earlyServe": true. Blockstudio passa então a controlar três componentes pequenos de estado: um drop-in wp-content/advanced-cache.php, um mapa de rotas compartilhado wp-content/blockstudio-static-prerender-map.php e uma declaração WP_CACHE em wp-config.php. Eles são instalados na próxima requisição de administração.

Algumas regras mantêm isso seguro em hospedagem compartilhada e multisite:

  • Blockstudio nunca sobrescreve um drop-in, mapa ou linha de WP_CACHE que não seja de sua propriedade. Se outro plugin de cache já controla advanced-cache.php, o atendimento antecipado permanece desativado.
  • Se WP_CACHE já estiver definido como true, wp-config.php não será alterado. Em hospedagens onde wp-config.php não pode ser gravado, defina-o manualmente.
  • Antes de servir, tanto o drop-in quanto o caminho PHP verificam se a folha de estilos Tailwind, cujo conteúdo tem hash e que está vinculada ao documento, ainda existe. Se não existir, a solicitação será direcionada a WordPress, em vez de ser servida sem estilos.
  • As entradas do Multisite compartilham um mapa, mas são isoladas por host, caminho inicial e ID do site.
  • Os cabeçalhos de resposta indicados em replayHeaders, cujo padrão é Link, são armazenados com cada documento e enviados novamente em todos os acessos, para que um cabeçalho Link enviado por uma página com header() continue disponível no atendimento antecipado. Cabeçalhos de cookies e cache nunca são reproduzidos.

Os acessos antecipados carregam X-Blockstudio-Static-Prerender: HIT-EARLY. Desativar earlyServe ou enabled remove uma vez o estado que Blockstudio gerencia, e wp bs teardown o remove explicitamente em instalações Composer que não têm um gancho de desativação.

Visitantes conectados e marcação idêntica

Por padrão, visitantes conectados sempre recebem uma renderização ao vivo. Definir "serveLoggedIn": true também permite que eles usem um documento armazenado existente, deixando o site tão rápido para editores e clientes quanto para visitantes anônimos.

Respostas personalizadas nunca criam entradas de cache: uma solicitação sem correspondência de um usuário conectado é renderizada ao vivo e não é armazenada. A consequência pode passar despercebida. Com serveLoggedIn ativado, um visitante conectado recebe o documento anônimo sempre que ele existe, e uma renderização personalizada ao vivo somente quando ele não existe. Qualquer ramificação de modelo baseada no usuário atual aparece apenas em solicitações sem correspondência, então a mesma página muda entre visitas, e a ramificação personalizada fica, na prática, inativa nas rotas em cache.

A regra decorrente disso: em todas as rotas fora de dynamicPaths, a marcação para usuários conectados deve ser idêntica, byte por byte, à marcação para usuários anônimos. Isso significa não usar ramificações is_user_logged_in() ou wp_get_current_user() em modelos renderizados em rotas 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; ?>

Há duas soluções simples. Mova a rota para dynamicPaths quando a página inteira for pessoal, como um painel de conta. Ou mantenha a página estática e renderize a parte pessoal como uma ilha de bloco dinâmico, que envia um espaço reservado seguro para cache no HTML armazenado e busca o fragmento real na própria solicitação do visitante:

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

O guia Fragmentos personalizados em páginas em cache ensina a criar esse bloco.

Invalidação por assinatura ou grafo

invalidate define como os documentos armazenados expiram.

Aspecto signature (padrão) graph
Quem preenche o cache solicitações anônimas sem correspondência e o aquecedor sua etapa de compilação, além de solicitações anônimas sem correspondência
O que expira as entradas TTL, salvamentos de posts, alterações no nível do site uma nova compilação, com TTL como limite superior
Aquecedor em segundo plano disponível desativado
Indicado para sites comuns sites com pipeline de implantação

O modo signature não exige ferramentas. Salvar um post limpa o cache ou aquece novamente a página inicial e o link permanente desse post; alterações no nível do site, como trocar o tema, renovam a identidade do cache.

O modo graph é voltado a implantações determinísticas. Uma compilação calcula um plano com Static_Prerender_Runtime::build_plan(), renderiza somente as URLs afetadas, registra cada resultado e ativa atomicamente o conjunto concluído com Static_Prerender_Early_Serve::install_artifact_entry(). Se a validação de qualquer documento referenciado falhar, o conjunto anterior permanece ativo. As rotas mapeadas são atendidas pelo artefato ativado até que a próxima compilação o substitua; assim, o conteúdo editado no wp-admin chega a essas rotas na próxima implantação. O aquecedor por URL fica desativado neste modo porque os artefatos são compilados e ativados como uma unidade. Um ambiente de produção típico é assim:

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

O ttl de 30 dias apenas limita a idade máxima de um documento disponibilizado. A atualização vem da implantação que recompila o grafo. A compilação API, o particionamento e o transporte interno de renderização são abordados na referência Pré-renderização estática.

Colocando um CDN na frente

A pré-renderização já informa quais respostas podem ser compartilhadas: exatamente aquelas que incluem um cabeçalho HIT. Faça a origem convertê-lo em um cabeçalho de cache e deixe o CDN seguir as instruções da origem. Com nginx na frente 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;
    }
}

A expressão regular corresponde tanto a HIT quanto a HIT-EARLY. Para todas as outras respostas, a variável fica vazia e o nginx não adiciona um cabeçalho com valor vazio; assim, solicitações sem correspondência, caminhos dinâmicos e renderizações de usuários conectados saem da origem sem um tempo de validade de cache compartilhado.

No lado do CDN:

  • Armazene HTML em cache somente quando a origem enviar um tempo de validade de cache. Desative qualquer TTL de borda padrão para respostas sem esse valor.
  • Ignore o cache de borda para os mesmos cookies que Blockstudio trata como pessoais (wordpress_logged_in_, wp-postpass_, comment_author_email_) e para seu dynamicPaths, wp-admin e wp-json.
  • Limpe o CDN após toda implantação que altere páginas, modelos ou ativos. O cache da origem se renova sozinho; a borda não sabe que isso deve acontecer.

Se você usar Tailwind com "output": "link", a folha de estilos URL terá hash de conteúdo, então esse caminho pode ser servido com um cabeçalho de cache imutável e de longa duração.

Comandos de manutenção

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

warm enfileira URLs públicas desatualizadas e renderiza até warm.concurrency por execução, exibindo um resumo JSON. purge remove os documentos armazenados e a fila do site atual. teardown remove os eventos cron e o estado de disponibilização antecipada pertencentes a esta instalação, sem alterar os arquivos de configuração.

Faça a implantação nesta ordem: primeiro o perfil, depois a pré-renderização com earlyServe desativado e, por fim, a disponibilização antecipada, quando status e os cabeçalhos estiverem corretos. Cada camada pode ser revertida por conta própria, restaurando o valor anterior.

Próximas etapas