# 能静态就静态

在blockstudio.json中设置预渲染页面和生产环境默认值。

## 预渲染匿名页面

默认关闭静态预渲染。启用 `performance.staticPrerender` 后，Blockstudio会存储匿名访客收到的每份完整HTML文档，然后向下一位匿名访客返回该副本。

必须实时处理的请求不会访问缓存：非 GET 请求、查询字符串、管理后台、REST、Ajax、cron、订阅源、搜索、预览、包含 nonce 的页面、`dynamicPaths` 下的所有路径，以及登录用户的请求（除非已启用 `serveLoggedIn`）。

[静态预渲染](https://blockstudio.dev/zh/docs/production/static-prerendering/)

blockstudio.json

```
{
  "performance": {
    "staticPrerender": {
      "enabled": true,
      "ttl": 3600,
      "earlyServe": true,
      "dynamicPaths": ["/account", "/checkout"]
    }
  }
}
```

## 默认关闭

只有blockstudio.json指定了该功能后，才会有任何变化。

## 动态路径

动态路径 /account 会匹配 /account/orders，但不会匹配 /accounting。

## 选择退出标记

blockstudio:no-cache注释会使任何响应都不进入缓存。

## 已登录访客

启用 serveLoggedIn 后，他们可以读取已存储的页面；但他们自己的页面永远不会被存储。

## [自定义绕过规则](https://blockstudio.dev/zh/docs/blocks/hooks/php/#blockstudio-static_prerender-request_bypass)

static_prerender/request_bypass 筛选器会让你指定的请求不使用已存储页面，例如带有购物车 Cookie 的请求。

## 预热队列

持久化队列会按照你设定的间隔重新渲染过期页面。

## [长尾路由](https://blockstudio.dev/zh/docs/production/static-prerendering/#early-serving-and-atomic-deployment)

部署映射之外的路由也会提前提供，前提是 WordPress 已对其完成渲染并存储。

## 样式表检查

如果已存储页面所链接的 Tailwind 样式表已不存在，就会重新渲染该页面，绝不会提供缺少样式的页面。

## 在WordPress启动前提供

启用 `earlyServe` 后，Blockstudio会安装一个 `advanced-cache.php` drop-in，在WordPress、插件或主题加载前传输已存储的页面。它绝不会覆盖 drop-in、路由映射，或它未写入的任何 `WP_CACHE` 行。

本网站正在运行此功能。10 月 8 日，2026，blockstudio.dev页面返回了 `x-blockstudio-static-prerender: HIT-EARLY`，即 drop-in 发送的响应头。

[提前提供](https://blockstudio.dev/zh/docs/production/static-prerendering/#early-serving-and-atomic-deployment)

终端

```
# 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 teardown
```

## 每次更改后都保持最新

默认的 `signature` 模式会在匿名请求未命中时填充缓存，并在网站级更改后轮换缓存。保存或删除文章会清除该文章及首页的缓存；启用预热后，还会将它们加入重新渲染队列。

`graph` 模式面向部署工具。它会记录每个页面读取过的文件，因此构建时只会重新渲染文件发生变化的路由，随后将新的一组路由作为一个制品启用。如果引用的文件未通过验证，之前的制品会继续在线运行。

安装制品时会比较字节，并以原子方式替换已更改的文档。`last_promotion()` 会报告已提升、替换、跳过或保留的路由数量，方便部署记录这些数据并与当前构建 ID 对比。

[签名和图模式](https://blockstudio.dev/zh/docs/production/static-prerendering/#signature-and-graph-modes)

deploy.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']
  );
}

Static_Prerender_Runtime::garbage_collect(array_keys($plan['live']));
```

## 位于 CDN 后方

预渲染标头已标明哪些响应可以安全共享。在源站将 `HIT` 和 `HIT-EARLY` 映射到一个 `Cache-Control` 有效期，只缓存带有该标头的响应；遇到 `wordpress_logged_in_`、`wp-postpass_` 和 `comment_author_email_` Cookie、你的 `dynamicPaths`、`wp-admin` 和 `wp-json` 时，则绕过边缘缓存。

边缘缓存中的页面会继续链接到渲染时使用的内容哈希样式表。将 `cache.namespaceGrace` 调高至此类副本可能存留的最长时间，旧样式表便会一直保留在磁盘上，直到期限届满。

[CDN 设置](https://blockstudio.dev/zh/guides/static-prerendering/#putting-a-cdn-in-front)

nginx.conf

```
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;
}
```

## 缓存页面中的一个实时区块

将 `blockstudio.island` 设为 `dynamic` 后，缓存页面会携带占位符，而不是该区块。浏览器会收集页面上的所有动态岛，并通过一个批量请求获取它们的片段；每个请求都使用区块名称及其许可列表中的属性签名。

`hydrate` 会将完整的 HTML 保留在页面中，只发送挂载事件。动态岛可以等到可见时再加载，在窗口事件触发时刷新，也可以按用户或全局缓存片段。

[区块孤岛](https://blockstudio.dev/zh/docs/blocks/islands/)

block.json

```
{
  "name": "acme/cart-count",
  "title": "Cart count",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "attributes": ["productId"],
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
```

## 查看渲染时间的分布

将 `?blockstudio-perf` 添加到任何前端 URL，面板便会列出每个区块的渲染时间、调用次数，以及转换、模板和组件阶段的数据。这些计时数据也会作为 `Server-Timing` 标头发送出去，即使 CDN 缓存了 HTML，仍然有效。

只有拥有 `edit_posts` 的已登录用户才能看到输出，其他所有请求都会在 `init` 处关闭性能分析器。`performance.measurement` 会添加性能分析和配置哈希标头，以及 `Performance_Measurement::snapshot()` API。

[性能分析器](https://blockstudio.dev/zh/docs/production/performance/#profiler)

blockstudio.json

```
{
  "dev": {
    "perf": true
  },
  "performance": {
    "measurement": {
      "enabled": true,
      "headers": true,
      "timings": true
    }
  }
}
```

## 用一个开关设置生产环境默认值

将 `performance.profile` 设为 `speed` 后，会从 head 中移除 generator、emoji、feed 和 discovery 输出，关闭 oEmbed discovery，禁用XML-RPC和 pingback，移除通用核心前端资源，在编辑器之外限制 Heartbeat，并在悬停或聚焦时预取同源链接。

默认值为 `compat`，不会产生任何变化。每个子项的值都会覆盖此配置文件，因此你可以保留某项行为，同时采用其余设置。

[性能配置文件](https://blockstudio.dev/zh/docs/production/performance/#performance-profiles)

blockstudio.json

```
{
  "performance": {
    "profile": "speed",
    "preload": {
      "links": "off"
    }
  }
}
```

## 让图片保留原有空间

主题图片位于媒体库之外，因此WordPress无法获知它们的尺寸。`bs_media_image()` 会从生成的 `assets/media.json` 中读取实际尺寸，并在文件加载前预留宽高比对应的空间。

启用 `performance.media.lazy` 后，实际的URL会先显示在尺寸正确的占位图后面，直到图片接近视口。

[媒体](https://blockstudio.dev/zh/docs/production/media/)

index.php

```
<?php
echo bs_media_image([
  'src' => 'assets/images/hero.webp',
  'alt' => 'Hero',
  'eager' => true,
]);
```

## [一个缓存目录](https://blockstudio.dev/zh/docs/production/caching/)

每个生成的文件都位于cache.path下，并以运行时标识为键。

## [单航班构建](https://blockstudio.dev/zh/docs/production/caching/#concurrency-and-retention)

一个请求负责构建尚未缓存的键。其他请求会等待、复用上一个正常载荷，或收到带有 Retry-After 的 503。

## 适合 OPcache 的载荷

较小的缓存载荷是纯 PHP 数组，OPcache 可以从共享内存中复用。较大的载荷则会保持压缩状态。

## [渲染缓存](https://blockstudio.dev/zh/docs/production/performance/#render-cache)

带有相同属性的自闭合区块标签在每个请求中只渲染一次。后续重复项会从内存中读取。

## 合并刷新选项

一批内容写入操作（例如导入）会合并为一次刷新，以更新缓存中已填充的字段选项。

## 多租户缓存

使用 cache/site_key 筛选器定义你自己的租户边界，并使用 cache/context 筛选器处理同一网站的运行时变体。

## [缓存中的编译资源](https://blockstudio.dev/zh/docs/general/settings/#assets)

将 assets.output 设为 cache 后，编译资源会脱离区块树，因此可以从不可变的检出版本进行部署。

## 分片构建

Static_Prerender_Batch_Renderer 会将构建拆分为稳定的 N/TOTAL 分片，调用方也可以计算出相同的分区。

## [内联小型样式表](https://blockstudio.dev/zh/docs/blocks/assets/registering/#inline-small-stylesheets)

assets.inlineLimit 会在字节数预算内，将最小的区块样式表以内联方式输出，并保持相同的层叠顺序。

## [在 head 末尾输出区块 CSS](https://blockstudio.dev/zh/docs/blocks/assets/registering/#load-order)

区块 CSS 会添加在 head 结束标签之前，位于主题和插件样式表之后。

## [跳过未使用的资源](https://blockstudio.dev/zh/docs/blocks/assets/registering/#disable-enqueuing)

不返回任何内容的模板不会加入任何资源。将 assets.enqueue 设为 false 后，所有资源都由你自行管理。

## [缓存命令](https://blockstudio.dev/zh/docs/dev/cli/)

wp bs cache status、cleanup 和 clear 可检查、清空和清除运行时缓存。wp bs prerender purge 可删除已存储的页面。

## 彻底清理

wp bs teardown 只会移除此安装实例拥有的状态。

## 结果钩子

cache/outcome 和 static_prerender/outcome 会将命中、构建、未命中和失败情况报告到你的指标中。

## [错误钩子](https://blockstudio.dev/zh/docs/blocks/hooks/php/#error-handling)

error/logged 和 error/exception 会将 Blockstudio 错误转发到外部日志记录器或跟踪器。

## [批量渲染](https://blockstudio.dev/zh/docs/production/performance/#in-process-batch-rendering)

Batch_Render::reset() 会在同一进程处理不同文档之间清除请求状态。render/dependencies 会列出每个区块的文件。

Plus

## 官方扩展套件

高级站点模板、AI 系统指令和私人 Discord 社区。一次购买，终身更新。

- 500+ 个网站模板
- AI 系统指令
- 终身更新
- 私有 Discord 社区

[获取 Plus](https://blockstudio.dev/zh/plus/)
