跳转到正文

静态预渲染

静态预渲染是一种可选的匿名HTML缓存。可缓存的响应必须是完整的HTML文档,也可以通过<!-- blockstudio:no-cache -->选择不缓存。默认情况下,Blockstudio会绕过非 GET 请求、查询字符串、WordPress管理后台、REST、Ajax、cron、订阅源、位于站点主页路径中搜索基础路径以下的搜索结果(例如/search/term/)、预览和画布标头、带 nonce 的请求、声明的动态路径、密码/评论 Cookie,以及已登录用户的请求。路径中只有更深处包含search或preview片段的页面(例如/docs/blocks/preview/),会像其他页面一样缓存。

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

只有当serveLoggedIn为 true 时,已登录用户才能使用现有缓存命中;个性化响应绝不会创建缓存条目。动态路径按路径边界匹配,因此/account匹配/account/orders,但不匹配/accounting。

功能关闭时,不会写入文件、安装 drop-in,也不会注册请求或管理后台钩子。earlyServe: false同样不会注册 Early Serve 管理后台回调,而warm.enabled: false不会注册cron回调或计划任务。关闭任一功能时,会一次性移除此前归其所有的状态;后续请求不会执行文件系统或cron清理检查。

按环境关闭

上述每个值也都可以通过设置筛选器配置。Blockstudio会在活动主题之前启动,可从插件或主题的Composer自动加载配置中启动,因此主题加载完毕后,它会再次解析运行时设置,并在after_setup_theme决定是否注册静态预渲染钩子。因此,插件中或主题functions.php中的筛选器会生效:

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

通过这种方式关闭功能,效果与在blockstudio.json中关闭相同:不会注册请求、内容、管理后台或cron钩子;此前采用提前提供服务的站点,其 Early Serve 条目也会被移除一次。稍后添加的筛选器,例如在init上添加的筛选器,不会改变已注册的钩子。

签名模式与图模式

signature模式会在普通匿名缓存未命中时,填充一个以身份为键的响应。它适用于普通WordPress站点,并会在站点级别变更后轮换。

graph模式适用于确定性的构建/部署集成。使用实时源 URL 调用Static_Prerender_Runtime::build_plan(),仅渲染affectedUrls,然后使用persist_built_response()或persist_skipped_response()记录每个结果。计划会比较共享文件以及每个页面的精确依赖哈希。garbage_collect()会移除已删除的 URL 和未引用的HTML。

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);

可选的目标主机/主页参数可以为部署改写路由,而无需将第一个页面路径用作站点根路径。批处理工具可以使用Static_Prerender_Batch_Renderer::render()和稳定的N/TOTAL分片;Static_Prerender_Batch_Renderer::parse_shard()和select_shard()为分片选项提供支持,因此调用方可以计算出与渲染器相同的分区。在构建过程中,Static_Prerender_Batch_Renderer::is_rendering()会判断当前请求是批量渲染还是访客请求,因此模板可以跳过不应在构建期间运行的工作。通用的blockstudio/static_prerender/render_internal筛选器会提供internal传输;可选的HTTP回退会使用常规预热标头。

图模式跟踪的内容

使用默认的HTTP传输时,Static_Prerender_Batch_Renderer::render()会为每个预热请求发送签名令牌,请求则会报告读取过的文件:模板WordPress加载的文件、每个已渲染Blockstudio区块的模板、模板文件和资源文件、通过blockstudio/render/dependencies添加的文件,以及同步页面的定义、模板、内容和布局文件。报告会写入站点缓存目录;渲染器和 Web 服务器已在共享该目录,用于存放渲染后的HTML。下次构建时,build_plan()会再次对这些文件计算哈希,并标记文件发生变化的路由、新路由、超过ttl的路由,以及共享文件发生变化时的所有路由(blockstudio.json、theme.json、style.css、functions.php、header.php、footer.php、inc/下的所有内容、parts/和templates/,以及Blockstudio打包的UI资源源文件)。共享签名会对源文件而非编译输出进行哈希,因此构建首次渲染时编译的_dist文件不会改变签名:artifact_entry()会根据与build_plan()渲染前相同的签名生成构建 ID。

仅存于数据库中的内容不是文件,因此不会被跟踪:在管理后台编辑的文章、选项、生成的行或价格。若构建必须纳入这些变更,请将$force传给build_plan(),或自行渲染受影响的 URL。internal传输会记录其筛选器返回的依赖项。

提前提供服务与原子部署

启用earlyServe后,Blockstudio会管理一个小型wp-content/blockstudio-static-prerender-map.php、一个advanced-cache.phpdrop-in,以及一条精确的WP_CACHE声明。drop-in 会读取每个站点的路由映射,并在WordPress、插件或主题启动前,流式传输符合条件的缓存命中。

Blockstudio绝不会覆盖其他程序拥有的映射、drop-in 或WP_CACHE声明。交换映射前,图构建产物会验证每个引用的HTML文件;如果验证失败,先前的图仍会保持活动状态。多站点条目共享映射,但会按主机、主页路径和站点 ID 隔离。关闭功能或停用Blockstudio时,只会移除当前站点的条目;只有最后一个归其所有的条目移除后,才会移除共享构建产物。

部署工具可以原子化地激活完整渲染的图:

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

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

配置始终是权威来源。除非enabled和earlyServe都为 true,否则install_artifact_entry()会返回false,因此部署绝不会安装一组映射、drop-in 和WP_CACHE声明,随后又被下一次管理后台请求移除。

install_artifact_entry()会保留条目的build_id,这样部署后便可将其与installed_map_entries()返回的条目进行比较。映射是通过include读取的PHP文件;每次写入都会将其从操作码缓存中移除,因此即使启用了opcache.enable_cli,同一进程中的读取也能看到新条目。

安装构建产物时,其文档会被提升到专用的构建产物作用域,保留清理绝不会触及该作用域。无论映射引用的文件位于何处,都不会被逐出,因此实时渲染流量不会让映射路由因过期而退出提前服务。路由键并非完全由内容寻址,因此重新渲染可能在键不变时更改文档;安装时会比较字节内容,并原子替换不同的构建产物文档,保留相同的文档,也会保留存储副本已消失的构建产物文档。Static_Prerender_Early_Serve::last_promotion()会报告上次安装中提升、替换、跳过或保留的路由数量,便于部署时记录。

存储的文档会通过URL固定其链接的构建资源文件,而这些文件有各自的保留策略,因此两者的存续时间可能不同。提供服务前,PHP缓存和 drop-in 都会检查磁盘上是否仍存在所链接的、带内容哈希的Tailwind样式表。如果样式表已不存在,文档会交由WordPress处理,而不会以无样式的状态提供;它会重新发布样式表和文档。将响应存入缓存前也会执行同样的检查,因此无法提供的文档绝不会写入缓存。

如果请求的Accept标头包含text/markdown,就会绕过PHP存储和 drop-in,因为存储的文档是HTML,而页面可能会用其source Markdown响应该请求。 因此,已提供的文档会发送Vary: Accept。更新Blockstudio后,在下次写入映射时会重写较旧的 drop-in。

映射图中的路由始终使用已激活的构建产物。如果某个安全的匿名路由不在该映射中,但WordPress后来已将它渲染并持久化,Early Serve 会在启动WordPress前,回退到以身份为键的运行时存储。这支持有意限制范围的部署图之外的生成路由或长尾路由。回退使用已激活的图身份,并遵循与映射路由相同的主机、路径规范化、TTL、Cookie、标头、查询字符串、动态路径和订阅源绕过规则;它只会找到运行时存储的文档,而这些文档从不包含搜索结果。

响应头

存储的文档会在没有生成它的请求的情况下重放,因此主题或插件通过 header() 发送的标头会在每次命中时缺失。Blockstudio 会将 replayHeaders 中指定的标头与每份文档一同存储,并在 PHP 缓存和提前提供内容的 drop-in 中再次发送这些标头。默认值 ["Link"] 涵盖诸如 Markdown alternate(rel="alternate"; type="text/markdown")、rel="describedby" 或 rel="canonical" 之类的标头。名称匹配时不区分大小写,设置筛选器也会像处理其他值一样更改此列表:

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

    return $headers;
});

将 replayHeaders 设为 [] 可禁用标头重放。指定列表会替换默认列表,因此如果添加其他标头名称且仍想重放链接标头,请一并包含 Link。

标头是在渲染页面的进程中捕获的:实时未命中并存储时来自 headers_list();构建或预热器在 HTTP 上渲染时则来自预热请求本身。因此,Web 服务器自行添加且在每份已提供文档中都会再次添加的标头不会被存储。只有当 HTTP 渲染未写入报告时,才会使用其响应中的标头。internal 传输会在结果中将它们作为 headers 返回,而 persist_built_response() 将它们作为最后一个参数接收,格式可以是 Name: value 行,也可以是名称到值的映射。

这些内容会写入与文档同目录的 <key>.headers.json,并随文档一起经历产物提升、垃圾回收和保留期限清理;重新渲染时若未发送任何标头,这些内容就会被移除。Cookie、缓存和传输标头永远不会被存储或重放,即使它们列在其中也不例外:Set-Cookie、Cache-Control、Expires、Pragma、Age、ETag、Last-Modified、Vary、Content-Type、Content-Length、Content-Encoding、Transfer-Encoding、Location、Status、Date,以及逐跳标头和身份验证标头。已提供的文档会设置自己的 Content-Type 和 Vary。

发送存储的标头时,会再次根据列表进行检查。PHP 缓存会读取当前设置;drop-in 会读取网站映射条目中的副本,该副本会在下次安装产物或同步映射时更新。升级前存储的文档没有标头文件,在重新渲染前会照常提供。

预热、维护与可观测性

预热队列持久化,按URL合并,采用单航班处理,并能恢复超时的任务认领。即使当前签名未变化,内容和站点变更也会强制创建替换任务;定期检查只会将过期任务加入队列。每次定期检查或通过wp bs prerender warm执行时,最多渲染warm.concurrency个任务。graph模式会关闭按URL运行的预热器,因为图构建产物是作为一个整体构建并激活的。

命令行
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会报告活动身份、文件、字节数、图记录、队列状态、提前服务映射报告,以及各作用域的命中/未命中/构建/失败计数。

提前服务映射由安装中的所有站点共享。map status(以及Static_Prerender_Early_Serve::map_report())会列出提前服务已无法使用的条目:站点不再存在的orphaned条目、目录已删除的dead条目,以及剩余条目中的missing路由文档数量。map prune(Static_Prerender_Early_Serve::prune_map())会在映射锁定期间移除孤立和失效条目,并说明每个条目的原因;--dry-run只报告信息。移除最后一个条目时,映射、drop-in 和WP_CACHE声明都会一并移除。多站点网络中删除站点时会立即移除其条目;缓存清理绝不会收集已激活构建产物所服务的命名空间,因此只有通过其他方式删除文件时,条目才会失效。

使用blockstudio/static_prerender/outcome查看单个响应的结果,使用blockstudio/cache/outcome查看所有共享缓存结果。

拆除

对于没有插件停用钩子的安装方式(例如采用Composer捆绑的配置),可以通过一条命令移除该功能所管理的所有内容:

命令行
wp bs teardown

它会移除cron事件和安装所拥有的静态预渲染状态:当前站点的映射条目,以及最后一个归其所有的条目移除后共享的 drop-in 和WP_CACHE声明。配置文件会保留不动,因此重新启用功能时可以从干净状态开始。

在生产环境中采用

建议按以下顺序采用:

  1. 将performance.profile设为speed,然后检查 head 输出、订阅源,以及依赖 oEmbed 或XML-RPC的任何插件。
  2. 生成assets/media.json,将模板移至bs_media_image(),然后启用performance.media.lazy。
  3. 启用performance.staticPrerender,保持earlyServe关闭;使用wp bs prerender status确认缓存命中,然后启用earlyServe。

回滚按功能分别进行:将staticPrerender.enabled设为false后,会一次性移除Blockstudio所拥有的 Early Serve 状态和预热计划任务,随后不再注册预渲染运行时。将performance.profile重新设为compat即可撤销配置文件。每种回滚都会保留其他层。

性能

配置文件、性能分析器以及底层渲染技术。

缓存

所有生成的构建产物都存放在同一个缓存目录中。