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:
- 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. - 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émX-Blockstudio-Static-Prerender: HIT. - 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:
{
"$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.enabledregistra o tempo de execução. Enquanto estiverfalse, o recurso não grava arquivos nem registra hooks de requisição.ttlé a idade máxima de um documento armazenado, em segundos (padrão86400).dynamicPathslista os prefixos de caminho que sempre devem ser processados ao vivo.warmagenda um processo em segundo plano que renderiza novamente URLs públicas desatualizadas a cadaintervalsegundos.
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_*oucomment_author_email_*, a menos queserveLoggedInesteja 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:
<!-- 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:
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 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:
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_CACHEque não seja de sua propriedade. Se outro plugin de cache já controlaadvanced-cache.php, o atendimento antecipado permanece desativado. - Se
WP_CACHEjá estiver definido comotrue,wp-config.phpnão será alterado. Em hospedagens ondewp-config.phpnã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çalhoLinkenviado por uma página comheader()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 // 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 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:
{
"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:
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 seudynamicPaths,wp-adminewp-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
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
- Referência de pré-renderização estática: compilações do grafo, ativação de artefatos, retenção e ganchos de observabilidade.
- Desempenho: o que o perfil
speedaltera e como medi-lo. - Cache: o diretório de cache onde cada documento armazenado fica.
- Fragmentos personalizados em páginas em cache: conteúdo específico de cada visitante em rotas estáticas.
- Implantação de um site Blockstudio: onde a sincronização, a limpeza e o aquecimento de páginas se encaixam em uma versão.