缓存页面上的个性化片段
从静态缓存提供的页面对所有人都相同。这正是缓存的目的,也带来了问题:页眉需要对已登录客户显示“嗨,Ada”,购物车图标则要显示三件商品。如果模板根据当前用户进行分支,缓存要么会把某位访客的问候语存下来并展示给所有人,要么就只能完全跳过该页面。
Blockstudio的动态岛将这两个需求分开处理。缓存的 HTML包含一个可安全缓存的占位符。页面加载后,一个小型运行时会在访客自己的请求中向 WordPress请求个性化片段,并将其替换进去。页面仍可缓存,只有片段是动态的。
本指南将构建两个岛:问候语和购物车数量,并介绍缓存页面包含的内容、片段请求的形式,以及端点如何判断访客身份。本指南与以静态WordPress提供HTML配套。
动态岛的工作方式
- 区块在标记元素中渲染占位符。标记中包含区块名称、允许列表中的属性,以及服务器生成的签名。
- 由于渲染后的页面包含标记,Blockstudio会注入岛运行时。没有岛的页面不会加载岛JavaScript。
- 运行时收集已就绪的标记,并向
/wp-json/blockstudio/v1/island/render发送一个批量POST。 - 端点会验证每个签名,在访客的请求上下文中渲染区块,并返回片段。
- 运行时替换每个占位符并分发事件。
在区块编辑器中,区块会正常渲染,不使用占位符。
第 1 步:问候区块
创建区块,包含三个文件:
blocks/
└── greeting/
├── block.json
├── placeholder.php
└── index.php
{
"apiVersion": 3,
"name": "acme/greeting",
"title": "Greeting",
"category": "widgets",
"icon": "admin-users",
"description": "Account link that greets signed-in visitors.",
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "span",
"attributes": ["guestLabel"],
"cache": {
"ttl": 300,
"per": "user"
}
},
"attributes": [
{ "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
]
}
}
mode: "dynamic"让它成为会发起片段请求的岛。
tag设置标记元素,因此该岛可以内嵌在导航栏中。attributes是随片段请求传递的区块属性允许列表;未列出的属性既不会发送,也不会签名。下文将进一步介绍 cache。
缓存页面中包含的就是这个占位符。它必须能安全地展示给每位访客,因此不能包含用户数据。“账户”链接适用于所有人:
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
主模板会渲染实际片段:
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
<?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
</a>
<?php else : ?>
<a href="<?php echo esc_url( wp_login_url() ); ?>">
<?php echo esc_html( $a['guestLabel'] ); ?>
</a>
<?php endif; ?>
在此处根据当前用户进行分支没有问题:该模板只会在片段请求时运行,绝不会用于缓存页面。
将它放在页眉的渲染位置:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
区块标签也可以使用:<bs:acme-greeting /> 或
<block name="acme/greeting" />。
第 2 步:缓存页面包含的内容
区块在服务器上渲染时,只会生成标记和占位符:
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{"guestLabel":"Sign in"}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>
分别以匿名访客和已登录用户的身份渲染一次,得到的两段字符串会逐字节相同。这正是启用了 serveLoggedIn 的静态预渲染所要求的特性:无论是谁触发渲染,存储的文档都相同,其中不会包含任何个人信息。
第 3 步:片段请求
运行时会在一个请求中发送所有已就绪的岛:
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
响应以 clientId 为键。对于已登录访客:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
验证失败的条目会返回错误代码,而不是 HTML,且不会影响批次中的其余条目。这里,第二个条目在没有相应签名的情况下更改了 guestLabel,第三个条目则指定了一个并非动态岛的区块:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/wp-login.php\">\n Sign in </a>\n",
"a2": {
"error": "blockstudio_island_invalid_signature"
},
"a3": {
"error": "blockstudio_island_not_allowed"
}
}
每个响应都会携带
Cache-Control: no-store, no-cache, must-revalidate, max-age=0、
Pragma: no-cache 和 X-Robots-Tag: noindex。端点位于
/wp-json 下,静态预渲染总会绕过该路径,因此无论是源站缓存,还是遵循源站标头的 CDN,都不会存储片段。
访客身份的判断方式
运行时会使用 credentials: 'same-origin' 发送请求,因此浏览器会附带 WordPress 登录 Cookie。WordPress REST API 通常不会在没有随机数的情况下接受 Cookie 身份验证,而缓存页面中无法包含随机数。岛端点会自行处理这一问题:对于同源浏览器请求,它会验证 logged_in Cookie,并在渲染前恢复该用户身份。
同源性根据 Sec-Fetch-Site 标头判断;如果请求中带有 Origin 标头,则会将其与 home_url() 对比。来自其他源的请求即使携带该 Cookie,也会以匿名身份进行渲染,因此来自其他网站的请求绝不会渲染访客的个性化片段。实际情况如下:
| 请求 | 渲染身份 |
|---|---|
| 携带有效登录 Cookie 的同源 fetch 请求 | 已登录用户 |
| 携带相同 Cookie 的跨源请求 | 匿名 |
| 不携带 Cookie | 匿名 |
这是哪个页面?
当片段需要其所属页面的身份信息时,请将 "context": true 添加到 blockstudio.island。随后,标记会在属性之外,对查询页面的文章 ID 和文章类型进行签名。在片段中,$block['postId']、$block['postType']、get_the_ID() 和 get_queried_object_id() 都指向该页面。在查询循环中,这仍指外层被查询的页面,而不是循环项。
页面上下文为可选项,也会作为片段缓存键的一部分。即使片段已缓存,端点也会再次检查访问权限,因此签名标记不会暴露后来已设为私密或受密码保护的页面。配置和安全详情请参阅 页面上下文。不会重放任意 URL 或查询参数。
第 4 步:自动刷新的购物车数量
第二个岛展示了另一种占位符样式和两个运行时选项。模板不使用单独的占位符文件,而是检查 $isIslandPlaceholder:
{
"apiVersion": 3,
"name": "acme/cart-count",
"title": "Cart Count",
"category": "widgets",
"icon": "cart",
"description": "Number of items in the visitor's cart.",
"blockstudio": {
"island": {
"mode": "dynamic",
"loading": "visible",
"event": "acme:cart-updated"
},
"attributes": []
}
}
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
<a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
<a href="/cart/" class="cart-count">
Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
</a>
<?php endif; ?>
所有模板语言都有相同的标志:isIsland、
isIslandPlaceholder、isIslandFragment 和 islandPhase("normal"、
"hydrate"、"placeholder" 或 "fragment")。这里,数量来自一个由你的电商代码填充的 acme/cart_count 筛选器;当它返回 3 时,端点会返回:
{"c1":"<!--blockstudio/acme/cart-count--> <a href=\"/cart/\" class=\"cart-count\">\n Cart <span class=\"cart-count__badge\">3</span>\n </a>\n"}
loading: "visible"会使用 IntersectionObserver,直到标记进入视口后才发起请求。相邻出现的可见岛仍会合并到一个请求中。event用于指定重新获取岛内容的窗口事件,因此调用加入购物车后,你的脚本只需发出通知:
window.dispatchEvent(new Event('acme:cart-updated'));
在前端代码中作出响应
事件会从标记处向上冒泡,因此在 document 上添加一个监听器即可覆盖所有岛屿。event.detail.name 保存区块名称:
document.addEventListener('blockstudio:island:rendered', (event) => {
if (event.detail.name !== 'acme/cart-count') return;
event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});
document.addEventListener('blockstudio:island:error', (event) => {
console.warn('Island failed', event.detail.name, event.detail.error);
});
交换后,运行时会先分发 blockstudio:island:rendered,再分发 blockstudio:island:hydrate。失败时,占位符会保留在原位,并触发 blockstudio:island:error。已水合的岛屿("island": "hydrate")会完全跳过请求:页面中已有完整的 HTML,它们只会收到 hydrate 事件,适用于选项卡等可安全缓存的交互式区块。
片段缓存
默认情况下,每次请求都会渲染片段。上面的问候语启用了短期缓存:
{
"cache": {
"ttl": 300,
"per": "user"
}
}
per: "user" 会按 WordPress 用户 ID 区分缓存片段,并且匿名请求绝不会以此方式缓存,因此两个匿名访客不会共用原本属于某个用户的条目。per: "global" 会为相同的区块和属性共用一个片段,适用于实时但不涉及个人信息的内容,例如库存量。ttl 默认为 60 秒,cache: true 是一个 60 秒的全局缓存。
安全模型
该端点是公开的,但它并非通用区块渲染器。只有满足以下所有条件时,它才会渲染一个条目:
- 区块已注册、为动态区块,并且
island.mode设置为dynamic - 签名与区块名称以及经过筛选后保留的属性相匹配:仅限同时存在于区块架构和岛屿允许列表中的键
签名是对规范化后的区块名称和属性计算得到的 HMAC-SHA256,使用提供服务的网站的 auth 盐值作为密钥。签名会在该网站上渲染时创建,绝不会预先写入主题。因此有两个结果:在预发布环境中渲染的文档带有预发布环境的签名,所以应在提供这些文档的网站上渲染。轮换 WordPress 盐值会使存储文档中的所有签名失效,因此盐值轮换后应清除静态预渲染内容。
单个请求最多可接受 50 个岛屿;超过后会返回 HTTP 413。使用 blockstudio/islands/max_per_request 更改此限制。对于需要采用不同方案的主机,可使用签名钩子(blockstudio/islands/signature_payload、blockstudio/islands/signature、blockstudio/islands/verify_signature)。
不适合使用岛屿的情况
片段不在初始 HTML 中,因此爬虫看不到它们。请将与 SEO 相关的内容保留在常规渲染中。动态岛屿适合用于页面框架加载后才出现的内容:账户链接、购物车状态、推荐内容和受权限控制的控件。如果整个页面都涉及个人信息,例如账户仪表板,请改为在 dynamicPaths 中列出其路径,并实时渲染。
后续步骤
- 岛屿参考:所有选项、占位符查找顺序、PHP API 和钩子。
- 将 WordPress 作为静态 HTML提供:这些岛屿专为这种缓存而设计。
- 静态预渲染参考:
serveLoggedIn、动态路径和提前提供服务。 - 交互式组件:为需要挂载事件以外功能的区块添加客户端行为。