将 WordPress 作为静态 HTML 提供服务
营销网站或文档网站上的大多数页面,对所有匿名访客来说都相同。每次请求时,WordPress 仍会启动、加载所有插件、运行主题并渲染区块。页面缓存插件或许能帮上忙,但它会增加一个需要管理的环节,还会带来一套关于哪些内容可以安全存储的规则。
Blockstudio 提供可选启用的静态预渲染功能。它会将完整的匿名 HTML 文档存储在自己的缓存目录中;如果你允许,还可以通过 advanced-cache.php drop-in 在 WordPress 启动前提供这些文档。所有配置都在 blockstudio.json 中完成。
本指南将逐步启用此功能,介绍如何检查哪些内容已缓存、哪些未缓存,说明确保登录访客安全的一条规则,并以 CDN 配置收尾;该配置只会缓存源站标记为可缓存的内容。
请求如何得到响应
启用预渲染后,符合条件的请求会以以下三种方式之一结束:
- 提前命中。 drop-in 会在路由映射中找到已存储的文档,并在 WordPress 加载前将其传出。响应包含
X-Blockstudio-Static-Prerender: HIT-EARLY。 - 命中。 WordPress 启动后,在
template_redirect阶段,Blockstudio 会找到仍有效的已存储文档并发送,而不再渲染模板。响应包含X-Blockstudio-Static-Prerender: HIT。 - 未命中。 WordPress 会正常渲染页面。如果访客是匿名用户,且结果是完整的 HTML 文档,状态为 200,Blockstudio 就会将其存储起来,供下次请求使用。
不符合条件的请求完全不会访问缓存。
第 1 步:启用配置方案和缓存
先启用性能配置方案和预渲染功能,并关闭提前提供服务:
{
"$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
}
}
}
}
各部分的作用:
profile: "speed"启用生产环境前端默认设置:移除 head 冗余内容、oEmbed 发现、XML-RPC 和通用核心前端资源,并在用户表达意图时预取同源链接。移除核心前端资源的设置应优先测试,因为依赖这些资源的页面会明显出错。任何子级值都可以覆盖配置方案。staticPrerender.enabled注册运行时。当它处于false状态时,此功能不会写入文件,也不会注册请求钩子。ttl是已存储文档的最长有效期,单位为秒(默认值为86400)。dynamicPaths列出必须始终实时渲染的路径前缀。warm会安排后台预热程序,每隔interval秒重新渲染过期的公开 URL。
$schema 这一行涵盖所有键,因此支持 JSON 架构的编辑器会标记诸如 "ttl": 0 这样的错误(最小值为 1)。
第 2 步:了解哪些请求符合条件
Blockstudio 对存储内容采取保守策略。以下请求始终绕过缓存:
- 任何非
GET请求 - 带有查询字符串的任何 URL
wp-admin、wp-json、wp-login.php、xmlrpc.php、Ajax 和 cron- feed、搜索和预览路径
- 发送
X-WP-Nonce标头的请求 - 位于
dynamicPaths下的路径 - 带有
wordpress_logged_in_*、wp-postpass_*或comment_author_email_*Cookie 的访客,除非已启用serveLoggedIn
动态路径会按路径边界进行匹配。使用上述配置时:
| 请求 | 是否绕过 |
|---|---|
/pricing/ |
否 |
/account/orders/ |
是 |
/accounting/ |
否 |
/checkout |
是 |
/pricing/?utm_source=x |
是 |
/blog/feed/ |
是 |
在存储方面,只会保存完整文档:响应必须以 <!doctype html 或 <html 开头,状态必须为 200,且不得包含退出缓存标记。绝不应存储的模板可以在页面任意位置输出该标记:
<!-- blockstudio:no-cache -->
错误页面绝不会被存储,因此带主题样式的 404 绝不会被当作成功页面重放。
第 3 步:验证命中
在隐私窗口中访问几个页面,然后询问 Blockstudio 缓存中存有什么:
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 和 bytes 会增大;queue 显示预热程序的待处理任务;diagnostics 则提供各范围的命中、未命中、构建和失败计数器。若要检查单个页面,请以匿名访客身份请求两次,并查找以下标头:
curl -s -o /dev/null -D - https://example.com/pricing/ | grep -i x-blockstudio-static-prerender
第二个响应会包含 X-Blockstudio-Static-Prerender: HIT。请像上文那样使用 GET:curl -I 会发送 HEAD 请求,该请求始终会绕过缓存。
第 4 步:在 WordPress 启动前提供服务
确认命中情况正常后,设置 "earlyServe": true。随后,Blockstudio 会管理三项小型状态:一个 wp-content/advanced-cache.php drop-in、一个共享的 wp-content/blockstudio-static-prerender-map.php 路由映射,以及 wp-config.php 中的 WP_CACHE 声明。它们会在下一次管理请求时安装。
以下几条规则有助于确保共享主机环境和多站点环境的安全:
- Blockstudio 绝不会覆盖它不拥有的 drop-in、映射或
WP_CACHE行。如果另一个缓存插件已经拥有advanced-cache.php,则会保持关闭状态,不启用提前提供内容。 - 如果
WP_CACHE已定义为true,则不会改动wp-config.php。如果主机不允许写入wp-config.php,请自行定义它。 - 提供内容前,drop-in 和 PHP 路径都会检查文档链接到的带内容哈希的 Tailwind 样式表是否仍然存在。如果不存在,请求会转到 WordPress,而不是提供没有样式的页面。
- 多站点条目共用一个映射,但会按主机、主页路径和站点 ID 隔离。
replayHeaders中指定的响应标头(默认由Link指定)会与每份文档一同存储,并在每次命中时再次发送。因此,页面通过header()发送的Link标头在提前提供内容时仍会保留。Cookie 和缓存标头绝不会重放。
提前命中会携带 X-Blockstudio-Static-Prerender: HIT-EARLY。关闭 earlyServe 或 enabled 会移除 Blockstudio 曾创建的状态,而 wp bs teardown 会为没有停用钩子的 Composer 安装显式移除该状态。
已登录访客与相同标记
默认情况下,已登录访客始终获得实时渲染。设置 "serveLoggedIn": true 后,他们也可以使用已有的存储文档,让编辑者和客户访问网站的速度与匿名访客一样快。
个性化响应绝不会创建缓存条目:未命中时,已登录访客会获得实时渲染,且结果不会存储。其影响很容易被忽略。启用 serveLoggedIn 后,只要存在匿名文档,已登录访客就会收到该文档;只有在文档不存在时,才会获得个性化实时渲染。模板中任何依赖当前用户的分支都只会在未命中时显示,因此同一页面会在不同访问中发生变化,而在已缓存的路由上,个性化分支实际上不会运行。
由此得出的规则是:在 dynamicPaths 之外的每条路由上,已登录访客的标记都必须与匿名访客的标记逐字节相同。这意味着静态路由上渲染的模板中不能有 is_user_logged_in() 或 wp_get_current_user() 分支:
<?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; ?>
有两种简洁的解决方法。如果整个页面都属于个人内容(例如账户仪表板),就将路由移入 dynamicPaths。或者保留静态页面,并将个人内容渲染为动态区块岛;它会在存储的 HTML 中提供可安全缓存的占位内容,再通过访客自己的请求获取真实片段:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
缓存页面上的个性化片段指南会介绍如何构建该区块。
签名或图结构失效
invalidate 决定存储文档的过期方式。
| 方面 | signature(默认) |
graph |
|---|---|---|
| 谁填充缓存 | 匿名访客的未命中请求和预热器 | 你的构建步骤,以及匿名访客的未命中请求 |
| 什么会使条目过期 | TTL、文章保存、站点级更改 | 新构建;TTL 作为最长时限 |
| 后台预热器 | 可用 | 关闭 |
| 适用对象 | 普通网站 | 带有部署流水线的网站 |
signature 模式无需任何工具。保存文章会清除或重新预热首页和该文章的固定链接;切换主题等站点级更改则会更换缓存标识。
graph 模式适用于确定性部署。构建过程使用 Static_Prerender_Runtime::build_plan() 计算计划,仅渲染受影响的 URL,记录每个结果,并使用 Static_Prerender_Early_Serve::install_artifact_entry() 原子化激活完整结果集。如果对任何引用文档的验证失败,之前的结果集仍保持激活状态。映射路由会从已激活的构建产物提供服务,直到下次构建将其替换,因此在 wp-admin 中编辑的内容会在下次部署时显示在这些路由上。此模式会关闭每个 URL 的预热器,因为构建产物会作为一个整体构建并激活。典型的生产环境配置如下:
{
"performance": {
"profile": "speed",
"staticPrerender": {
"enabled": true,
"invalidate": "graph",
"ttl": 2592000,
"earlyServe": true,
"serveLoggedIn": true,
"dynamicPaths": [
"/account",
"/cart",
"/checkout",
"/login",
"/reset-password"
]
}
}
}
30 天 ttl 仅限制所提供文档的最大时限。新鲜度由重新构建图结构的部署保障。构建 API、分片和内部渲染传输的内容,请参阅静态预渲染参考。
在前面放置一个 CDN
预渲染会明确指出哪些响应可以安全共享:恰好是带有 HIT 标头的响应。让源站将其转换为缓存标头,再让 CDN 遵循源站的设置。使用 nginx 并在 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;
}
}
此正则表达式会同时匹配 HIT 和 HIT-EARLY。对于其他所有响应,该变量都为空;nginx 不会添加值为空的标头,因此未命中、动态路径和已登录用户的渲染都不会从源站获得共享缓存时长。
在 CDN 端:
- 仅当源站发送了缓存时长时才缓存 HTML。对于未提供缓存时长的响应,禁用任何默认边缘 TTL。
- 对于 Blockstudio 视为个人内容的相同 Cookie(
wordpress_logged_in_、wp-postpass_、comment_author_email_),以及你的dynamicPaths、wp-admin和wp-json,绕过边缘缓存。 - 每次部署更改页面、模板或资源后,都清除 CDN。源站缓存会自行轮换;边缘缓存并不知道它也应当轮换。
如果将 Tailwind 与 "output": "link" 搭配使用,样式表 URL 会经过内容哈希处理,因此可以为该路径设置长期有效的不可变缓存标头。
维护命令
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
wp bs teardown
warm 会将过期的公共 URL 加入队列,并在每次运行中最多渲染 warm.concurrency 个,最后输出 JSON 摘要。purge 会移除当前站点的存储文档和队列。teardown 会移除此安装所拥有的 cron 事件和提前提供服务状态,并保留配置文件不变。
按此顺序逐步上线:先进行性能分析,再启用预渲染但关闭 earlyServe,最后在 status 和标头看起来正确后启用提前提供服务。每一层都可以通过将其值设回原值来单独回滚。
后续步骤
- 静态预渲染参考:图结构构建、构建产物激活、保留策略和可观测性钩子。
- 性能:
speed配置会带来哪些变化,以及如何衡量效果。 - 缓存:所有存储文档所在的缓存目录。
- 缓存页面上的个性化片段:静态路由上的访客专属内容。
- 部署Blockstudio网站:页面同步、清除和预热如何融入发布流程。