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() 将项目注册的所有内容作为一个普通数组返回,不执行任何渲染。
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 作为用于渲染的模板。
定向选择
指定记录即可缩小处理范围,无需事后再筛选。
$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 作为字符串返回。
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 文档。
$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
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() 会为组件变体返回一个小型可调用函数:
$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 可在一处启用生产环境前端默认设置。
{
"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 中保存的任意值。
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。
{
"cache": {
"enabled": true,
"path": "cache/blockstudio"
}
}
构建载荷、区块注册数据、编辑器资源、编译后的 Tailwind CSS、渲染文档、岛屿片段、静态 HTML、图谱索引、预热队列和诊断信息都位于该根目录下。相对路径以 WP_CONTENT_DIR 为基准解析,绝对路径则可将其指向专用卷。
对象按当前网络和站点归档,再按运行时身份标识归档。该标识是 Blockstudio、WordPress 和 PHP 版本、有效设置、活动主题和插件、发现来源以及相关源文件的指纹。输入发生变化时,受影响的对象会生成新版本;旧对象则会被清理。
冷启动构建采用单次执行模式:一个请求负责构建并原子地发布结果,其余请求等待。刷新失败时,会继续提供上一个正常对象,同时保留可观测的失败信息;Blockstudio\Runtime_Cache::purge('tailwind') 可清除一个作用域。
静态预渲染
静态预渲染会缓存完整的匿名 HTML 文档,并可在 WordPress 启动前提供。默认关闭。
{
"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 模式适用于显式的构建和部署工具。它会记录每个页面自身的来源依赖,因此构建计划只需重新构建受影响的网址。
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 和提交钩子使用相同的配置:
{
"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。
托管提交钩子
通过一项设置和一个命令,即可将已配置的预设设为提交门禁。
{
"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 函数和类,以及命令。
## 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 时,这种简写:
<brand-card>
<ui-input />
</brand-card>
表示同一内容:
<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,每项操作都会撤销一层更改。
建议按以下顺序采用:
- 将
performance.profile设置为speed,然后检查 head 输出、feeds,以及任何依赖 oEmbed 或 XML-RPC 的插件。 - 生成
assets/media.json,将模板移至bs_media_image(),然后启用performance.media.lazy。 - 启用
performance.staticPrerender,保持earlyServe关闭,使用wp bs prerender status验证命中情况,然后启用earlyServe。 - 运行
blockstudio-phpstan --preset theme,直到检查结果干净,再将任何预设置于githooks.commit之后。