能静态就静态
在blockstudio.json中设置预渲染页面和生产环境默认值。
预渲染匿名页面
默认关闭静态预渲染。启用performance.staticPrerender后,Blockstudio会存储匿名访客收到的每份完整HTML文档,然后向下一位匿名访客返回该副本。
必须实时处理的请求不会访问缓存:非 GET 请求、查询字符串、管理后台、REST、Ajax、cron、订阅源、搜索、预览、包含 nonce 的页面、dynamicPaths下的所有路径,以及登录用户的请求(除非已启用serveLoggedIn)。
{
"performance": {
"staticPrerender": {
"enabled": true,
"ttl": 3600,
"earlyServe": true,
"dynamicPaths": ["/account", "/checkout"]
}
}
}<!-- blockstudio:no-cache -->
<p class="stock">
<?php echo esc_html( $a['label'] ); ?>
</p>默认关闭
只有blockstudio.json指定了该功能后,才会有任何变化。
动态路径
动态路径 /account 会匹配 /account/orders,但不会匹配 /accounting。
选择退出标记
blockstudio:no-cache注释会使任何响应都不进入缓存。
已登录访客
启用 serveLoggedIn 后,他们可以读取已存储的页面;但他们自己的页面永远不会被存储。
自定义绕过规则
static_prerender/request_bypass 筛选器会让你指定的请求不使用已存储页面,例如带有购物车 Cookie 的请求。
预热队列
持久化队列会按照你设定的间隔重新渲染过期页面。
长尾路由
部署映射之外的路由也会提前提供,前提是 WordPress 已对其完成渲染并存储。
样式表检查
如果已存储页面所链接的 Tailwind 样式表已不存在,就会重新渲染该页面,绝不会提供缺少样式的页面。
在WordPress启动前提供
启用earlyServe后,Blockstudio会安装一个advanced-cache.phpdrop-in,在WordPress、插件或主题加载前传输已存储的页面。它绝不会覆盖 drop-in、路由映射,或它未写入的任何WP_CACHE行。
本网站正在运行此功能。10 月 8 日,2026,blockstudio.dev页面返回了x-blockstudio-static-prerender: HIT-EARLY,即 drop-in 发送的响应头。
# Identity, files, queue, and hit/miss counters
wp bs prerender status
# Re-render stale entries now
wp bs prerender warm
# Dead or orphaned early-serve map entries
wp bs prerender map status
wp bs prerender map prune --dry-run
# Remove the drop-in and map this install owns
wp bs teardowncurl -sI https://blockstudio.dev/ | grep -i x-blockstudio
# x-blockstudio-static-prerender: HIT-EARLY每次更改后都保持最新
默认的signature模式会在匿名请求未命中时填充缓存,并在网站级更改后轮换缓存。保存或删除文章会清除该文章及首页的缓存;启用预热后,还会将它们加入重新渲染队列。
graph 模式面向部署工具。它会记录每个页面读取过的文件,因此构建时只会重新渲染文件发生变化的路由,随后将新的一组路由作为一个制品启用。如果引用的文件未通过验证,之前的制品会继续在线运行。
安装制品时会比较字节,并以原子方式替换已更改的文档。last_promotion() 会报告已提升、替换、跳过或保留的路由数量,方便部署记录这些数据并与当前构建 ID 对比。
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']
);
}
Static_Prerender_Runtime::garbage_collect(array_keys($plan['live']));use Blockstudio\Static_Prerender_Early_Serve;
use Blockstudio\Static_Prerender_Runtime;
$entry = Static_Prerender_Runtime::artifact_entry($targetUrls);
Static_Prerender_Early_Serve::install_artifact_entry(
$entry,
Static_Prerender_Runtime::cache_root_path()
);
$counts = Static_Prerender_Early_Serve::last_promotion();位于 CDN 后方
预渲染标头已标明哪些响应可以安全共享。在源站将 HIT 和 HIT-EARLY 映射到一个 Cache-Control 有效期,只缓存带有该标头的响应;遇到 wordpress_logged_in_、wp-postpass_ 和 comment_author_email_ Cookie、你的 dynamicPaths、wp-admin 和 wp-json 时,则绕过边缘缓存。
边缘缓存中的页面会继续链接到渲染时使用的内容哈希样式表。将 cache.namespaceGrace 调高至此类副本可能存留的最长时间,旧样式表便会一直保留在磁盘上,直到期限届满。
map $upstream_http_x_blockstudio_static_prerender $edge_cache_control {
"~^HIT" "public, s-maxage=604800";
default "";
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_pass unix:/run/php/php-fpm.sock;
add_header Cache-Control $edge_cache_control;
}{
"cache": {
"namespaceGrace": 777600
},
"tailwind": {
"enabled": true,
"output": "link"
}
}缓存页面中的一个实时区块
将 blockstudio.island 设为 dynamic 后,缓存页面会携带占位符,而不是该区块。浏览器会收集页面上的所有动态岛,并通过一个批量请求获取它们的片段;每个请求都使用区块名称及其许可列表中的属性签名。
hydrate 会将完整的 HTML 保留在页面中,只发送挂载事件。动态岛可以等到可见时再加载,在窗口事件触发时刷新,也可以按用户或全局缓存片段。
{
"name": "acme/cart-count",
"title": "Cart count",
"blockstudio": {
"island": {
"mode": "dynamic",
"attributes": ["productId"],
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}<div class="cart-count-placeholder">
Loading cart...
</div>window.dispatchEvent(new Event('cart:updated'));查看渲染时间的分布
将 ?blockstudio-perf 添加到任何前端 URL,面板便会列出每个区块的渲染时间、调用次数,以及转换、模板和组件阶段的数据。这些计时数据也会作为 Server-Timing 标头发送出去,即使 CDN 缓存了 HTML,仍然有效。
只有拥有 edit_posts 的已登录用户才能看到输出,其他所有请求都会在 init 处关闭性能分析器。performance.measurement 会添加性能分析和配置哈希标头,以及 Performance_Measurement::snapshot() API。
{
"dev": {
"perf": true
},
"performance": {
"measurement": {
"enabled": true,
"headers": true,
"timings": true
}
}
}use Blockstudio\Performance_Measurement;
$snapshot = Performance_Measurement::snapshot();用一个开关设置生产环境默认值
将performance.profile设为speed后,会从 head 中移除 generator、emoji、feed 和 discovery 输出,关闭 oEmbed discovery,禁用XML-RPC和 pingback,移除通用核心前端资源,在编辑器之外限制 Heartbeat,并在悬停或聚焦时预取同源链接。
默认值为compat,不会产生任何变化。每个子项的值都会覆盖此配置文件,因此你可以保留某项行为,同时采用其余设置。
{
"performance": {
"profile": "speed",
"preload": {
"links": "off"
}
}
}让图片保留原有空间
主题图片位于媒体库之外,因此WordPress无法获知它们的尺寸。bs_media_image()会从生成的assets/media.json中读取实际尺寸,并在文件加载前预留宽高比对应的空间。
启用performance.media.lazy后,实际的URL会先显示在尺寸正确的占位图后面,直到图片接近视口。
<?php
echo bs_media_image([
'src' => 'assets/images/hero.webp',
'alt' => 'Hero',
'eager' => true,
]);{
"performance": {
"media": {
"lazy": true,
"skeleton": true,
"metadata": true,
"rootMargin": "300px"
}
}
}一个缓存目录
每个生成的文件都位于cache.path下,并以运行时标识为键。
单航班构建
一个请求负责构建尚未缓存的键。其他请求会等待、复用上一个正常载荷,或收到带有 Retry-After 的 503。
适合 OPcache 的载荷
较小的缓存载荷是纯 PHP 数组,OPcache 可以从共享内存中复用。较大的载荷则会保持压缩状态。
渲染缓存
带有相同属性的自闭合区块标签在每个请求中只渲染一次。后续重复项会从内存中读取。
合并刷新选项
一批内容写入操作(例如导入)会合并为一次刷新,以更新缓存中已填充的字段选项。
多租户缓存
使用 cache/site_key 筛选器定义你自己的租户边界,并使用 cache/context 筛选器处理同一网站的运行时变体。
缓存中的编译资源
将 assets.output 设为 cache 后,编译资源会脱离区块树,因此可以从不可变的检出版本进行部署。
分片构建
Static_Prerender_Batch_Renderer 会将构建拆分为稳定的 N/TOTAL 分片,调用方也可以计算出相同的分区。
内联小型样式表
assets.inlineLimit 会在字节数预算内,将最小的区块样式表以内联方式输出,并保持相同的层叠顺序。
在 head 末尾输出区块 CSS
区块 CSS 会添加在 head 结束标签之前,位于主题和插件样式表之后。
跳过未使用的资源
不返回任何内容的模板不会加入任何资源。将 assets.enqueue 设为 false 后,所有资源都由你自行管理。
缓存命令
wp bs cache status、cleanup 和 clear 可检查、清空和清除运行时缓存。wp bs prerender purge 可删除已存储的页面。
彻底清理
wp bs teardown 只会移除此安装实例拥有的状态。
结果钩子
cache/outcome 和 static_prerender/outcome 会将命中、构建、未命中和失败情况报告到你的指标中。
错误钩子
error/logged 和 error/exception 会将 Blockstudio 错误转发到外部日志记录器或跟踪器。
批量渲染
Batch_Render::reset() 会在同一进程处理不同文档之间清除请求状态。render/dependencies 会列出每个区块的文件。
官方扩展套件
高级站点模板、AI 系统指令和私人 Discord 社区。一次购买,终身更新。
- 500+ 个网站模板
- AI 系统指令
- 终身更新
- 私有 Discord 社区