缓存
Blockstudio 包含持久化的文件缓存。默认情况下,通过 cache.enabled 设置启用,并写入以下位置:
wp-content/blockstudio/cache/
这个配置的根目录统一管理运行时构建资源、预构建的区块注册数据、编辑器资源、Tailwind CSS、渲染后的文档、岛屿片段、静态 HTML、图索引、热队列和缓存诊断信息。这样可以避免重复执行发现、解析、编译和渲染,同时将所有生成的运行时状态限制在一个由主机管理的边界内。
默认位置特意设在 uploads 之外,因为安全加固的主机可能会阻止 PHP 缓存资源。使用 cache.path 更改位置;相对路径以 WP_CONTENT_DIR 为基准解析,而绝对路径可用于专用的可写缓存卷:
{
"cache": {
"enabled": true,
"path": "cache/blockstudio"
}
}
要按环境进行配置,请使用设置筛选器或已解析目录筛选器:
add_filter('blockstudio/settings/cache/path', function () {
return '/srv/wordpress-cache/blockstudio';
});
add_filter('blockstudio/cache/dir', function (string $directory): string {
return WP_CONTENT_DIR . '/cache/blockstudio';
});
更改路径后,缓存会从冷启动开始。系统不再读取 wp-content/uploads/blockstudio/cache 下的旧文件,可以将其删除。
标识和失效
每个作用域都嵌套在网络/博客身份和完整的运行时身份之下。输入发生变化时,缓存条目也会随之更新;输入包括受监视的区块文件、字段文件、资源依赖项、设置、当前主题、当前插件、逻辑发现清单、WordPress、PHP 和 Blockstudio 版本。针对具体项目的依赖哈希可将仅构建变更项目的操作与无关对象隔离开来。
逻辑发现来源还会提供其来源 ID、内容指纹和监视输入。其他运行时选择可以添加 blockstudio/cache/context 值,以隔离所有缓存作用域。逻辑发现来源如果主机的租户边界与 WordPress 网络/博客 ID 不同,可以筛选 blockstudio/cache/site_key;结果会先经过清理,再用作路径片段。
在热缓存的前端请求中,Blockstudio 会先载入运行时注册表,再构建发现来源。因此,命中有效缓存时,会跳过递归来源发现、区块构建、字段解析和重复的缓存键树遍历。
运行时负载还会存储已解析的区块资源路径、大小、时间戳和模块样式表列表。温热请求会复用这些元数据,而不会针对每个已渲染区块重复查询资源输出或扫描模块目录。当前请求仍会运行资源URL和禁用筛选器,assets.inlineLimit仍会保留其页面级预算和级联顺序。禁用assets.enqueue或持久化缓存时,不会收集资源输出元数据。过期的最近一次成功构建会回退到从磁盘解析其资源。
未更改的已解析设置也会在请求期间复用其指纹。 重新加载或更改设置会使其失效;可变对象或引用 值会重新计算哈希,而不是复用可能已过期的指纹。
在 production 和 staging 中,经过验证的监视快照会受信任 20 秒;此后 Blockstudio 会再次检查文件和目录。local 和 development 环境的默认值为零,因此源文件编辑会立即生效。使用以下设置更改此间隔:
add_filter('blockstudio/cache/watch_debounce', function () {
return 30;
});
防抖最多会将自动源更改检测延迟配置的秒数。每次命中缓存时,仍会检查必需的已编译资源、已缓存的非空原始资源和模块样式表。删除资源会立即使运行时负载失效,而不会在时间窗口结束前继续提供过期的资源元数据。如果生产环境也用于主动编辑文件,请将防抖设为 0。
缓存负载存储为受保护的 PHP 文件。对于较小的负载,如果写入进程启用了 OPcache 共享内存,且目标文件未被排除,则会使用普通数组。这样,后续包含该文件时,OPcache 可以复用已编译的数组;修改返回的数据仍遵循 PHP 的正常写时复制行为。
如果没有共享内存 OPcache,载荷会保持为压缩的序列化数据。当 OPcache 已满、其 API 不可用或受到限制,或者其黑名单或 opcache.max_file_size 排除了该文件时,也会如此。仅使用文件缓存的 OPcache 不会选择纯数组格式。有关这些主机级控制,请参阅 PHPOPcache 配置。
默认普通数组格式的上限为 1 MiB,按序列化数据和生成的 PHP 源码两者的大小计算。更大的负载仍会压缩,以避免没有 OPcache 的 CLI 进程读取由 Web 工作进程预热的缓存时产生大数组编译开销。
此类读取进程仍需解析较小的普通文件,而新写入的文件可能需要在 opcache.file_update_protection 期间编译。
blockstudio/cache/compress 筛选器会按作用域覆盖格式,例如 WP-CLI 为启用了 OPcache 的 Web 工作进程预热缓存文件时。返回 false 也会覆盖大小限制:只有在每个读取进程都能处理生成的 PHP 文件时才这样做。如果 zlib 不可用,则回退到普通 PHP。
并发与保留
冷缓存键使用单航锁。一个请求负责构建资源,其他并发请求会等待结果原子发布,而不是重复执行相同的发现或编译工作。原子发布可防止产生不完整对象。刷新失败时,有效的上次成功对象仍可用,故障也会被记录,后续请求可以恢复。
默认情况下,运行时作用域会保留 20 个已发布资源。如果某个集成会有意创建更多缓存上下文,可按作用域调整上限:
add_filter(
'blockstudio/cache/max_files_per_scope',
function (int $maximum, string $scope): int {
return 'runtime' === $scope ? 50 : $maximum;
},
10,
2
);
清理时绝不会逐出已安装的早期提供映射所引用的文件;blockstudio/cache/protected_paths 筛选器还可标记其他必须保留的路径。
未使用的命名空间会自动清理,不会在每次插件启用以及 PHP 或 WordPress 更新时不断累积。过去用于对旧 Tailwind 缓存目录执行 glob 操作的部署片段,应改为调用 Blockstudio\Runtime_Cache::purge('tailwind')。
运行时身份发生变化时,命名空间会进入退役状态,例如 WordPress 核心更新后。首次清理扫描发现命名空间已退役时,会在其中写入 .retired 标记;自此经过 cache.namespaceGrace 秒(默认一天)后,系统会清理整个目录。在此期间如果目录再次写入,宽限期会重新开始。当前作用域的命名空间不会被清理;早期提供映射仍在为已激活资源提供服务的命名空间也不会被清理。对于后者,只有下次激活将映射条目移至其他位置后,宽限期才会开始。缓存在 WordPress 之外的页面仍会链接到渲染时使用的内容哈希样式表,因此,如果站点通过 CDN 或较长的浏览器缓存提供 tailwind.output: "link" 页面,应将宽限期延长至此类副本最长可能的存留时间:
{
"cache": {
"namespaceGrace": 777600
}
}
升级后的安装如果包含 7.6 之前的扁平 cache/runtime 目录,Blockstudio 会以原子方式将其重命名,使其移出活动路径。随后,WP-Cron 作业每次最多删除 500 个文件系统条目。这样可避免旧资源和 .build.lock 目录占满磁盘,也不会让发现大型目录的请求递归删除整个目录。只有在 cache.enabled 处于活动状态时才会执行清理;主机需要减少或增加每批处理量时,可使用 blockstudio/cache/legacy_cleanup_batch_size 更改批次大小。
在 blockstudio.json 中禁用持久化缓存:
{
"cache": {
"enabled": false
}
}
也可以通过筛选器启用:
add_filter('blockstudio/settings/cache/enabled', '__return_false');
性能一节介绍的内存中单请求渲染缓存有意独立运行,但其持久化资源使用相同的文件系统边界。
清理遗留锁积压
7.6.14 之前的版本在每次内容变更时都会遗留一个 .build.lock 文件,繁忙的站点可能积累数十万个。升级后,WP-Cron 会自动分批清理,且每批数量有限。若要立即清理积压并将结果交给主机,请运行 CLI:
wp bs cache status
wp bs cache cleanup
status 会统计剩余的旧锁,并报告下一批何时运行。cleanup 会持续分批清理,直到没有空闲锁剩下,然后清理宽限期已过的缓存命名空间。创建时间不足一小时或仍被运行中的请求持有的锁会留待下一轮处理。站点提供服务期间,切勿手动删除锁文件;被持有的锁用于选定一个请求负责构建,防止并发请求同时构建。
wp bs cache clear 会清除当前站点的整个运行时缓存;使用 --scope=runtime 可清除所有命名空间中的一个作用域。下一次请求会从冷启动重新构建,因此请在访问量较低时运行。
Tailwind 缓存
Tailwind 编译后的 CSS 缓存使用共享运行时根目录,位于其 network/site/runtime 命名空间和 tailwind 作用域下。默认情况下,该缓存最多存储 1,000 个条目,保留 30 天,足以保存整个站点的页面级键,而不会在少量路由后就将其逐出。
对于相同的 CSS 输入,Tailwind 还会在长时间运行的进程中重复使用热编译器,并在进程之间持久化编译器构建状态。冷启动的页面候选集仍会分别编译,但无需每次都重新构建框架解析器。
使用以下筛选器更改保留策略:
add_filter('blockstudio/tailwind/cache_max_files', function () {
return 1500;
});
add_filter('blockstudio/tailwind/cache_max_age', function () {
return 14 * DAY_IN_SECONDS;
});
最短期限为一小时。
缓存文件使用内容哈希,每个缓存页面都会链接一个 URL,因此逐出操作和已存储页面对哪些文件仍重要可能判断不一。提供预渲染文档前,系统会检查其关联的样式表;因此,文件被逐出后只会导致页面重新渲染,不会出现无样式的页面。将 cache_max_files 提高到超过不同页面级键的数量,即可完全避免重新渲染。
位于同一根目录下的匿名 HTML 缓存。