跳转到正文

Dennis · 2026年7月27日

Blockstudio 7.6

Blockstudio 7.6 让项目内容可通过 PHP 查看和呈现,并将生产环境前端默认设置迁移到 blockstudio.json:包括清单 API、独立呈现、媒体和 Tailwind 模板助手、性能配置文件、统一缓存目录、支持提前提供服务的静态预渲染、更严格的分析预设,以及为编码代理生成的项目工具。

本次发布的大部分功能由两个调用实现。Canvas::inventory() 会返回项目注册的所有页面、区块、样板、站点编辑器模板、模板部件和打包的 UI 示例。Render::document() 会返回其中任意项目的成品 HTML,并包含呈现过程中实际使用的全部资产。

7.6.2 更新: 基于文件的页面不再在常规 WordPress 请求期间进行协调。应用源更改时,请运行 wp bs pages sync 或调用 Blockstudio\Pages::reconcile()。集合路由和 templateFor 默认设置会使用持久化的运行时配置;显式协调也避免了先前的大型多语言 OR-meta 查询。由于页面同步不再通过请求钩子运行,现已移除短期 themeDefaults.syncPagesInDevelopment 选项。Pages::init() 现在仅用于引导;传入 force 的集成必须改用 Pages::reconcile() 或 CLI。打开 Canvas 时,仍会为其创作清单执行一次经过身份验证的显式协调。

7.6.12 更新: 编辑器样式表现在通过一次重写处理添加前缀,而不是对每个资源单独执行一次 SASS 编译,因此包含许多区块的网站进行冷启动编辑器构建时,不再有耗尽有限内存的风险。缓存的预渲染页面若其内容哈希 Tailwind 样式表已被清除,现在会重新渲染,而不是以无样式状态提供;PHP 缓存和 Early Serve 插件均如此处理。在顶层写入的区块属性现在会在渲染时读取,而不会被丢弃,因此会遵循在 WP_Block_Type 上注册的架构 Blockstudio 的程序化写入器也能生效。

7.6.11 更新: 图谱产物安装现在会在存储副本发生变化但键相同时,原子地替换路由文档;相同的文档保持不变,并通过 Static_Prerender_Early_Serve::last_promotion() 报告已提升、已替换、已跳过和已保留的路由。

7.6.10 更新: 运行时缓存命中现在会在监视防抖期间检测已移除的编译资源;7.6 之前的扁平运行时缓存会被原子地隔离,并分批删除,每批数量有上限 cron。打包的 UI 全局变量每页只输出一次。图谱模式的 Early Serve 可以通过身份缓存提供已部署路由映射之外、由实时渲染生成的路由。Tailwind 可选择将其内容哈希缓存文件与 tailwind.output: "link" 一同输出;默认仍为内联输出。

简而言之:

  • 项目清单:Canvas::inventory() 返回每条已注册记录及其来源,并按稳定的显示顺序排列。
  • 定向选择:指定区块和页面后,发现、同步、渲染和编译范围会缩小到这些记录。
  • 独立渲染:Blockstudio\Render 为区块、组合或完整文档返回已完成的 HTML。
  • UI 组件系列:Blockstudio\Ui 将打包的库按组件归为一个个公开系列,每个系列都附有一个示例。
  • 稳定的图像尺寸:bs_media_image() 使用生成的 assets/media.json 渲染主题资源,并提供真实尺寸。
  • Tailwind 类名辅助工具:bs_tw_merge() 和 bs_tw_variants() 在 PHP 中组合类名,并能识别冲突后合并。
  • 性能配置:performance.profile 一次性启用生产环境前端默认设置;子级值优先。
  • 类型化设置访问:Settings::get_bool() 及其同类项以实际类型读取 blockstudio.json,并报告解析错误。
  • 单一缓存目录:所有生成文件都保存在 cache.path 下,并按运行时身份标识归档。
  • 静态预渲染:匿名 HTML 可以缓存,通过依赖图失效,并在 WordPress 启动前提供。
  • 分析预设:theme、extreme-theme 和 wordpress-render 将 blockstudio/phpstan 的分析范围扩展到区块模板之外。
  • 托管提交钩子:blockstudio-githooks sync 写入并管理一个运行已配置预设的 pre-commit 钩子。
  • 项目约定:blockstudio-agents 写入一个 AGENTS.md,说明项目作者编写的内容、启用的功能以及预设会强制执行的规则。
  • 文档索引:AI 上下文文件现在列出每份文档、其用途以及归属它的标识符。
  • 规范区块标签:独立命令会将前缀和别名简写重写为 <bs:namespace-slug>,并支持试运行。
  • 默认兼容:只有在 blockstudio.json 中明确指定后,上述功能才会影响网站。

项目的读取与渲染

项目清单

Canvas::inventory() 将项目注册的所有内容作为一个普通数组返回,不执行任何渲染。

PHP
use Blockstudio\Canvas;

$result = Canvas::inventory();

foreach ($result['inventory']['blocks'] as $block) {
    echo $block['name'] . "\n";
}

记录按类型分组:pages、blocks、patterns、templates、parts 和 ui。order 是所有类型共用的稳定显示顺序,sources 将每条记录映射到其来源路径,而 warnings 和 errors 则将问题收集为结构化条目。

区块记录包含 id、name、title、source、path、provenance,以及可直接渲染的 declaration。页面记录将 source 保留为稳定身份标识,并将 path 作为用于渲染的模板。

定向选择

指定记录即可缩小处理范围,无需事后再筛选。

PHP
$changed = Canvas::inventory([
    'blocks' => ['mytheme/hero'],
    'pages' => ['about'],
]);

这会返回一个区块和一个页面。patterns、templates、parts 和 ui 为空,且不会读取、同步、渲染或编译它们的来源。

规则如下,且严格遵循:

  • 不提供任何类型键时,会加载所有类型。
  • true、null 或 "*" 会加载该类型的所有记录。
  • 字符串或列表会按 ID、名称、slug、路径或来源路径进行精确匹配。
  • 空字符串、空列表或 false 会加载该类型的零条记录。
  • 一旦提供任意类型键,未指定的类型就会保持不变。

不再存在的标识符会列在 deleted 下,而不会导致失败;Canvas 的 REST 刷新端点也会对其 blocks 和 pages 参数采用同一规则。

Canvas::documents() 接受相同的选择条件,并为每条记录额外添加一个渲染后的文档。所选页面会在恢复后的前端上下文中渲染,因此查询条件、body 类名、短代码、布局、重定向和资源入队回调所看到的是该页面,而不是发起请求的页面。

独立渲染

Blockstudio\Render 会通过与前端相同的处理流程,将渲染后的 HTML 作为字符串返回。

PHP
use Blockstudio\Render;

$html = Render::composition([
    'root' => 'mytheme/card',
    'data' => ['heading' => 'Example card'],
    'layers' => [
        ['name' => 'mytheme/button', 'data' => ['label' => 'Continue']],
    ],
]);

底层采用一种包含四个键的声明结构:name、attributes、content 和 children。root、data、inner、innerBlocks、layers 和 example 是便于输入的写法,Render::normalize() 会将它们整合进该结构。子项会递归渲染;输入格式错误时会抛出异常,并指出出错的区块。

Render::document() 会将输出包装为完整的独立 HTML 文档。

PHP
$document = Render::document('mytheme/hero', [
    'title' => 'Hero preview',
]);

echo $document['html'];

body 仅包含区块输出,html 是组装后的文档,blocks 是参与生成的区块名称,而 assets 会将标记拆分为 head、footer、styles、scripts、modules、interactivity、ui 和 tailwind。资源仅限于实际渲染的内容,因此不会包含仅供编辑器使用的资源。

Render::document_from_html() 会包装在其他位置渲染的 HTML,而 Render::content() 会在没有文档的情况下渲染序列化的区块内容。在同一个 PHP 进程中渲染多个文档时,请在文档之间调用 Blockstudio\Batch_Render::reset();Canvas::documents() 已经这样做。

UI 组件系列

Blockstudio\Ui 将打包的 UI 库按每个公开组件提供一个条目,而不是列出内部部件。

Ui::inventory() 为每个系列返回一个条目,其中包含根区块、标题以及所需的实现区块。Ui::examples() 为每个系列添加确定性的声明:保留默认值,将必需的子层嵌套在其父项下,并为字段为空的情况提供稳定的示例文本。该声明是规范形式,因此可直接放入 Render::document()。

Canvas 也采用相同的分组方式。打包的 UI 会作为 ui 类型下的条目出现,每个系列一个示例;实现层的注册不会出现在 blocks 中。

这些系列旨在组合使用:选择框会在对话框中打开,列表框浮层覆盖触发器;菜单和组合框会以固定的视口坐标定位,不受滚动影响;模态框可以堆叠,并且每按一次 Escape 就关闭一个;所有页脚都用同一个关闭控件和变体组合而成。这些组件如何衔接,以及维持其正常工作的各项约束,请参阅 组合章节;/ui/examples 展示了实际运行的组合示例。

模板辅助工具

稳定的图像尺寸

bs_media_image() 使用真实的宽度和高度渲染主题资源,并预留宽高比,因此媒体库之外的图像不再导致布局跳动。

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

输出是一个 figure.blockstudio-media,其中的 aspect-ratio 内联包裹着一个 img,后者带有真实的 width、height、loading 和 decoding。尺寸来自生成的 assets/media.json,可在构建步骤中由 Blockstudio\Media_Metadata_Builder 写入,也可手动填写。

src 接受相对于主题的路径、绝对路径或完整的 URL;attachmentId 则用于媒体库图像。eager 可让首屏上方的内容不使用延迟加载,而 sources 会输出一个 <picture>。

启用 performance.media.lazy 后,实际的 URL 会移至 data-src,并由尺寸正确的占位图替代。

Tailwind 类名辅助工具

bs_tw_merge() 和 bs_tw_variants() 会在 PHP 模板中组合 Tailwind 类名,并使用 Blockstudio 已经打包的引擎。

bs_tw_merge('px-2 text-sm', 'px-4') 返回 text-sm px-4:发生冲突的 px-2 会被移除,后面的值优先。支持嵌套的类名值数组。

bs_tw_variants() 会为组件变体返回一个小型可调用函数:

PHP
$button = bs_tw_variants([
    'base' => 'inline-flex items-center',
    'variants' => [
        'size' => ['sm' => 'h-8 px-3', 'lg' => 'h-12 px-6'],
    ],
    'defaultVariants' => ['size' => 'sm'],
]);

echo $button(['size' => 'lg', 'class' => 'rounded']);

输出结果为 inline-flex items-center h-12 px-6 rounded。支持基础类名、变体、默认变体、复合变体,以及每次调用时传入的 class 或 className。

生产环境配置

性能配置

performance.profile 可在一处启用生产环境前端默认设置。

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

compat 是默认配置,不会更改任何内容。speed 和 strict 会启用同一组设置:从 head 中移除 generator、emoji、feed、discovery 和相邻文章输出;移除 oEmbed discovery 和主机脚本;禁用 XML-RPC、pingbacks 和远程编辑器发现;移除通用的 core 前端资源;应用图像输出默认值;在编辑器之外降低 Heartbeat 频率;在用户意图悬停或聚焦时预获取同源文档;并使用 Blockstudio 的图像加载器。

每个子级值都会覆盖配置中的对应值,如上面的 preload.links 所示。建议先测试移除 core 前端资源,因为依赖这些资源的页面会出现明显故障。Runtime_Settings::current() 可查看解析后的配置。

themeDefaults 涵盖主题通常需要自行实现的两项功能:titleTag 和 suppressDirectoryUpdates,用于在更新结果中隐藏当前子主题和父主题。

类型化设置访问

Blockstudio\Settings 以实际类型读取配置,而不是返回 JSON 中保存的任意值。

PHP
use Blockstudio\Settings;

$lazy = Settings::get_bool('performance/media/lazy');
$margin = Settings::get_string('performance/media/rootMargin', '300px');
$ttl = Settings::get_int('performance/staticPrerender/ttl', 86400);
$roles = Settings::get_array('users/roles');

foreach (Settings::errors() as $error) {
    error_log($error);
}

格式错误的 JSON 会通过 Settings::errors() 报告,而不是解析为默认值。Settings::get_raw() 只返回当前来源声明的内容,因此可以区分值被设为 false 和从未设置的情况。

Settings::fingerprint() 会为生效中的设置返回稳定的身份标识;当 blockstudio.json 发生变化时,访问操作会重新加载。

单一缓存目录

现在,每个生成文件都保存在 cache.path 下,默认路径为 wp-content/blockstudio/cache。

JSON
{
  "cache": {
    "enabled": true,
    "path": "cache/blockstudio"
  }
}

构建载荷、区块注册数据、编辑器资源、编译后的 Tailwind CSS、渲染文档、岛屿片段、静态 HTML、图谱索引、预热队列和诊断信息都位于该根目录下。相对路径以 WP_CONTENT_DIR 为基准解析,绝对路径则可将其指向专用卷。

对象按当前网络和站点归档,再按运行时身份标识归档。该标识是 Blockstudio、WordPress 和 PHP 版本、有效设置、活动主题和插件、发现来源以及相关源文件的指纹。输入发生变化时,受影响的对象会生成新版本;旧对象则会被清理。

冷启动构建采用单次执行模式:一个请求负责构建并原子地发布结果,其余请求等待。刷新失败时,会继续提供上一个正常对象,同时保留可观测的失败信息;Blockstudio\Runtime_Cache::purge('tailwind') 可清除一个作用域。

静态预渲染

静态预渲染会缓存完整的匿名 HTML 文档,并可在 WordPress 启动前提供。默认关闭。

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

适用条件

只有完整的匿名 HTML 文档符合条件。非 GET 请求、查询字符串、管理页面、REST、Ajax、cron、feed、搜索、预览、带 nonce 的请求、个性化 Cookie,以及 dynamicPaths 下的任何路径都会绕过缓存。响应可通过 <!-- blockstudio:no-cache --> 标记完全选择退出。

路径匹配会遵循边界规则,因此 /account 会匹配 /account/orders,但不会匹配 /accounting。

签名模式与图谱模式

invalidate 用于选择条目的过期方式。默认的 signature 模式会在匿名请求未命中时填充按身份标识区分的响应,并在站点级别发生变化后轮换,适用于普通网站。

graph 模式适用于显式的构建和部署工具。它会记录每个页面自身的来源依赖,因此构建计划只需重新构建受影响的网址。

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

提前提供

启用 earlyServe 后,Blockstudio 会管理一个小型站点级路由映射,以及一个 advanced-cache.php 插件,可在 WordPress、插件或主题启动前流式传输符合条件的缓存命中。

它绝不会覆盖其他程序的映射、插件或 WP_CACHE 声明。在替换映射之前,图谱产物会验证每个引用的 HTML 文件,因此未完成渲染的部署不会影响当前生效的图谱。多站点条目按主机、主页路径和站点 ID 隔离。

预热与状态

三个 WP-CLI 命令涵盖日常使用场景:

命令行
wp bs prerender warm
wp bs prerender status
wp bs prerender purge

status 会报告当前身份标识、文件数和字节数、图谱记录、队列状态,以及每个作用域的命中、未命中、构建和失败计数。

分析与智能体工具

分析预设

blockstudio/phpstan 在区块分析之上增加三个层级,并提供一个命令来运行项目所选的层级。

预设 添加的检查
base 现有的架构、模板、钩子、设置和 API 分析。
theme 主题根目录、样式表头、资源、选择器作用域、字段默认值、重复字段边界。
extreme-theme PHPStan max、不安全的 PHP、转义、Tailwind、JavaScript 和 Interactivity 检查。
wordpress-render 在 extreme-theme 的基础上运行由调用方提供的实时渲染探测。

默认值来自 blockstudio.json,因此交互式运行、CI 和提交钩子使用相同的配置:

JSON
{
  "phpstan": {
    "preset": "theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}
命令行
vendor/bin/blockstudio-phpstan --root . -- --no-progress

通过时退出码为 0,存在诊断信息时为 1,用法无效时为 2。包装器会在系统临时目录中组合配置,因此项目中不会生成配置文件、基线或缓存,并会将 PHPStan 的内存限制提高到 1G。

它还打包了一个 BC Math 提供程序,因此 JavaScript 检查不再需要 ext-bcmath。

托管提交钩子

通过一项设置和一个命令,即可将已配置的预设设为提交门禁。

JSON
{
  "githooks": {
    "commit": true
  }
}
命令行
vendor/bin/blockstudio-githooks sync

同步操作会在 Git 的公共目录中写入钩子和所有权记录,将 core.hooksPath 指向托管目录,并接续此前配置的任何 pre-commit 钩子。钩子会在提交时解析仓库和项目根目录,因此关联的检出目录和包含空格的路径都能正常工作。

该钩子只会运行 vendor/bin/blockstudio-phpstan,不会执行其他操作;它绝不会格式化或重写文件。将 commit 设为 false 后再次同步,或运行 blockstudio-githooks remove,即可恢复记录的钩子路径,并且只删除由 Blockstudio 管理的文件。

项目约定

blockstudio-agents 会写入一个 AGENTS.md,说明区块存放位置、项目中页面的定义、启用的功能,以及分析器会拒绝的内容。

命令行
vendor/bin/blockstudio-agents

该文档根据项目实际情况生成,而非使用模板。包含 style.css 标头、区块和文件页面的主题,其约定会不同于仅注册区块的插件;文档还会记录扫描器发现的数量、目录、命名空间和模板语言。blockstudio.json 决定显示哪些功能,因此未启用静态预渲染的项目不会看到相关说明。

正确性部分会逐层读取所选预设自身的规则文件,因此预设新增规则时,所有生成的约定都会随之更新。

所有权机制与提交钩子类似。若文件没有生成标记,除非 --force 另有规定,否则会拒绝替换;末尾的备注区域会在重新生成时保留;若约定已过时,--check 会以 1 退出;--stdout 则会打印约定而不触及文件系统。

文档索引

blockstudio-llm.txt 现在是索引,不再是拼接内容。每份已发布文档都会在所属章节和小节中列出一次,并附上其路由、源文件、单行用途说明,以及归属它的标识符:设置路径、钩子名称、PHP 函数和类,以及命令。

Text
## Docs / Dev / Inspection Tools

### Canvas
route: /docs/dev/canvas
file: docs/docs/dev/canvas.md
purpose: A visual workspace and public inventory API for Blockstudio content.
settings: dev/canvas/enabled, ui
hooks: blockstudio/settings/dev/canvas/admin_bar, blockstudio/settings/dev/canvas/enabled
php: Blockstudio\Canvas, Canvas::documents(), Canvas::inventory()

代理读取索引,找到包含所需标识符的文档,然后打开该文档。此前生成并发布的半兆字节拼接文件仍可通过 /blockstudio-llm-full.txt 获取;它不再是首先交到任何人手中的内容。

规范区块标签

独立命令会将前缀和别名简写改写为规范的 <bs:namespace-slug> 拼写,其中记录了真实的区块名称,即使没有加载项目筛选器也能解析。

使用 brand 前缀覆盖 theme-components,并使用 ui 前缀覆盖 bsui 时,这种简写:

HTML
<brand-card>
  <ui-input />
</brand-card>

表示同一内容:

HTML
<bs:theme-components-card>
  <bs:bsui-input />
</bs:theme-components-card>

前缀和精确别名仍然可用,也未被弃用。该命令不会加载 WordPress,且除非指定 --apply,否则不会写入任何内容:

命令行
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/prefixes.json \
  --known-blocks=/tmp/blocks.json \
  --report=/tmp/tag-migration.json \
  --dry-run

--prefix-map 将每个前缀映射到其命名空间,而 --known-blocks 列出已注册的区块名称。报告会记录从旧名称到规范名称的映射及出现次数、每个文件的哈希值,并分别列出未知标签、有歧义的别名和动态标签。只要仍有此类项目,--apply 就会拒绝写入,除非传入 --allow-unresolved。

支持成对、嵌套和自闭合标记,包括 PHP 字符串中的字面标签。只会更改标签名称,第二次运行不会产生任何更改;注释、代码围栏、<pre> 或 <code> 中的示例只会出现在报告中。

默认行为

安装 7.6 本身不会造成任何更改。

性能配置文件默认为 compat。 head 输出、oEmbed、XML-RPC、Heartbeat、图像默认设置、链接预取、延迟加载以及前端 <title>,都会保持为 WordPress 和主题原先设置的状态。

以下功能默认关闭,除非启用: 每个 performance.staticPrerender、performance.measurement、performance.media 和 themeDefaults 键,以及 githooks.commit、dev.canvas.enabled、ui.enabled、tailwind.enabled 和 blockTags.enabled。静态预渲染处于禁用状态时,不会写入文件,也不会安装 drop-in。

Canvas 和 Render 均为被动功能。 它们读取现有注册表,只渲染调用方要求的内容;二者都不会挂接到前端输出,也不会注册路由。Canvas 管理界面仍需要 dev.canvas.enabled 和 edit_posts。

要进行更严格的分析,必须明确指定。 安装 blockstudio/phpstan 只会启用基础扩展;除非项目指定预设,否则规范命令会运行 base。

生成的文件需要运行相应命令才会生成。 在运行 blockstudio-githooks sync 之前,githooks.commit 不会执行任何操作;在运行 blockstudio-agents 之前,AGENTS.md 也不会执行任何操作。

从 7.5 升级

要求未变:PHP 8.2 或更高版本,WordPress 6.7 或更高版本。

命令行
composer require blockstudio/blockstudio

缓存只会重建一次。 运行时标识包含 Blockstudio 版本,因此升级后的首次请求会是冷启动,并清理旧对象。可以删除位于 wp-content/uploads/blockstudio/tailwind/cache 下的旧 Tailwind 缓存;如果某段代码使用 glob 匹配该缓存,应改为调用 Blockstudio\Runtime_Cache::purge('tailwind')。

升级前的扁平 wp-content/blockstudio/cache/runtime 目录会自动重命名并移出活动路径,再通过有界的 WP-Cron 处理逐步移除。因此,部署请求期间无需删除大型旧锁文件目录树。

生成的文件各有其归属。 assets/media.json 应纳入版本控制或构建步骤。路由映射、advanced-cache.php drop-in 和 WP_CACHE 声明仅在启用 earlyServe 时存在,预提交钩子则仅在同步时存在。其他生成内容都位于 cache.path 下,可以安全删除。

没有任何内容被移除或重命名。 bs_render_block()、bs_block()、Blockstudio\Pages 和 Blockstudio\Patterns 仍是规范的基于文件的内容界面。

回滚按功能分别进行。 将 performance.profile 恢复到 compat、将 staticPrerender.enabled 恢复到 false、将 githooks.commit 恢复到 false 并配合一个 sync,以及将 cache.enabled 恢复到 false,每项操作都会撤销一层更改。

建议按以下顺序采用:

  1. 将 performance.profile 设置为 speed,然后检查 head 输出、feeds,以及任何依赖 oEmbed 或 XML-RPC 的插件。
  2. 生成 assets/media.json,将模板移至 bs_media_image(),然后启用 performance.media.lazy。
  3. 启用 performance.staticPrerender,保持 earlyServe 关闭,使用 wp bs prerender status 验证命中情况,然后启用 earlyServe。
  4. 运行 blockstudio-phpstan --preset theme,直到检查结果干净,再将任何预设置于 githooks.commit 之后。

详细内容所在位置