跳转到正文

设置

Blockstudio 包含功能强大的设置 API,可让你通过主题文件夹中的 blockstudio.json 文件或筛选器设置选项。此外,获准用户还可以在管理区域中通过可视化界面更改设置。

通过 JSON

如果主题文件夹中存在 blockstudio.json 文件,就会用它来设置当前站点的默认选项。你可以使用 JSON 架构验证该文件,并在 IDE 中获得自动补全支持。

该文件是可选的。如果没有该文件,Blockstudio 会在内置默认值的基础上,使用保存在管理区域中的设置。系统会自动检测文件的添加、更改或移除,因此无需清除缓存或手动重新加载。

可用属性如下:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "users": {
    "ids": [],
    "roles": []
  },
  "assets": {
    "enqueue": true,
    "reset": {
      "enabled": false,
      "fullWidth": []
    },
    "minify": {
      "css": false,
      "js": false
    },
    "process": {
      "scss": false
    }
  },
  "cache": {
    "enabled": true,
    "path": "blockstudio/cache"
  },
  "themeDefaults": {
    "titleTag": false,
    "suppressDirectoryUpdates": false
  },
  "performance": {
    "profile": "compat",
    "wordpress": {
      "headNoise": false,
      "embeds": false,
      "xmlrpc": false,
      "editor": false,
      "frontendAssets": false,
      "media": false,
      "heartbeat": false
    },
    "preload": {
      "links": "off"
    },
    "media": {
      "lazy": false,
      "skeleton": false,
      "metadata": false,
      "rootMargin": "300px"
    },
    "measurement": {
      "enabled": false,
      "queryMonitor": false,
      "headers": false,
      "timings": false
    }
  },
  "content": {
    "enabled": false,
    "id": "default",
    "path": "content",
    "includePageSyncManaged": false,
    "authors": "ignore",
    "postTypes": [],
    "meta": {
      "include": [],
      "exclude": ["_edit_lock", "_edit_last", "_wp_old_slug"],
      "references": {}
    },
    "taxonomies": [],
    "media": "manifest"
  },
  "editor": {
    "formatOnSave": false,
    "assets": [],
    "markup": false
  },
  "tailwind": {
    "enabled": false,
    "config": "",
    "output": "inline"
  },
  "blockTags": {
    "enabled": false,
    "allow": [],
    "deny": [],
    "prefixes": {}
  },
  "ui": {
    "enabled": false
  },
  "blockEditor": {
    "disableLoading": false,
    "enhance": false,
    "cssClasses": [],
    "cssVariables": [],
    "blocks": {
      "allow": [],
      "deny": [],
      "directory": true,
      "categories": {
        "allow": [],
        "deny": [],
        "rename": {},
        "order": []
      },
      "styles": {
        "deny": {}
      },
      "legacyWidgets": {
        "hide": []
      }
    },
    "patterns": {
      "core": true,
      "remote": true,
      "theme": true,
      "blockstudio": true,
      "categories": {
        "allow": [],
        "deny": [],
        "rename": {},
        "order": []
      }
    },
    "media": {
      "openverse": true,
      "imageSizes": {
        "allow": [],
        "deny": []
      }
    }
  },
  "dev": {
    "grab": {
      "enabled": false
    },
    "perf": false,
    "canvas": {
      "enabled": false,
      "adminBar": true
    }
  },
  "githooks": {
    "commit": false
  },
  "phpstan": {
    "preset": "base",
    "configuration": "",
    "roots": ["."],
    "excludePaths": [],
    "maxFiles": 10000
  },
  "ai": {
    "enableContextGeneration": false
  }
}

通过筛选器

你也可以使用 blockstudio/settings/${setting} 筛选器,通过 PHP 设置选项,以获得更大的灵活性。

PHP
add_filter('blockstudio/settings/assets/enqueue', '__return_false');
add_filter('blockstudio/settings/editor/formatOnSave', '__return_true');
add_filter('blockstudio/settings/ui/enabled', '__return_true');
add_filter('blockstudio/settings/block_editor/patterns/remote', '__return_false');

通过 blockstudio/settings/${setting} 筛选器设置的选项会覆盖通过 blockstudio.json 文件设置的选项。两种方式可以同时使用。

运行时值还提供 blockstudio/performance/${setting} 筛选器,以及最后一个 blockstudio/performance/config 筛选器。后者必须返回有效的配置对象。

配置来源的叠加方式

每个来源都会按优先级从低到高加载并合并:

  1. 内置默认值
  2. 通过管理后台 UI 保存的设置(blockstudio_settings 选项)
  3. 主题中的 blockstudio.json
  4. blockstudio/settings/* 筛选器

blockstudio.json 只会覆盖它声明的键。过去,它会完全替换已保存的设置,因此文件一旦出现,其他无关的管理后台设置值就不再生效;现在,它会叠加在这些设置之上。另一方面,通过管理后台 UI 保存的过期值会继续生效,直到文件声明了对应的键,或已保存的值被移除。如果设置的实际行为与文件中的声明不符,请使用 wp bs settings 或 Settings::get_raw() 检查已保存的配置层;它只会返回当前 JSON 或选项来源明确声明的内容。

从 PHP 读取设置

Blockstudio\Settings 会加载当前来源、报告格式错误的 JSON,并在 blockstudio.json 更改时自动重新加载:

PHP
use Blockstudio\Settings;

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

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

当集成只需要由当前 JSON 或选项来源明确声明的值时,请使用 Settings::get_raw()。Settings::fingerprint() 会返回确定性的有效设置标识。长时间运行的进程可以显式调用 Settings::reload(),以立即读取文件更改。常规访问会在每个请求或长时间运行的 PHP 进程中每秒最多检查一次文件,包括大小未变的编辑。更改配置路径会在下次读取时生效。没有启用 JSON 文件时,数据库中保存的设置不会受到此时间窗口的延迟影响。

可通过 Blockstudio\Runtime_Settings::current() 获取解析后的性能配置。路径支持斜杠或点号表示法:

PHP
use Blockstudio\Runtime_Settings;

$runtime = Runtime_Settings::current();

if ($runtime->enabled('measurement/queryMonitor')) {
    $hash = $runtime->hash();
}

可用设置

users

选项 类型 默认值 描述
ids 数组 [] 拥有编辑器访问权限的用户 ID
roles 数组 [] 拥有编辑器访问权限的用户角色

assets

选项 类型 默认值 说明
enqueue boolean true 自动加入区块资源队列
reset.enabled boolean false 移除核心区块样式并应用编辑器工具类重置样式
reset.fullWidth array [] 使用全宽编辑器布局的文章类型
minify.css boolean false 压缩 CSS 输出
minify.js boolean false 压缩 JS 输出
process.scss boolean false 处理 SCSS 文件
output string source 编译后资源的写入位置:source 或 cache
inlineLimit integer 0 每个页面内联输出的外部区块 CSS 字节数

output 默认为 source,会在每个区块旁创建一个 _dist 目录。将其设为 cache,即可将编译后的资源写入 Blockstudio 缓存目录,让区块源代码树保持干净,并可从不可变检出中直接部署。无法写入源文件的 Blockstudio 会自动将资源写入缓存,无论此设置为何值。

inlineLimit 在 0 时处于关闭状态,因此每个外部样式表都会保留其 <link> 标签。将其设为字节数后,则会以内联方式输出页面中最小的外部区块样式表,但总量必须在该数值范围内。40000 是 WordPress 核心对此规则采用的限制。请参阅 内联小型样式表。

启用 reset.enabled 后,Blockstudio 还会将经过清理的前端 body_class 值复制到编辑器画布中。使用 blockstudio/editor/canvas/body_class 调整仅用于编辑器的类列表。

cache

选项 类型 默认值 描述
enabled 布尔值 true 启用由 Blockstudio 文件支持的缓存
path 字符串 "blockstudio/cache" 缓存路径,相对于 WP_CONTENT_DIR 或使用绝对路径
namespaceGrace 整数 86400 已退役缓存命名空间在清理前保留的秒数

默认情况下,缓存文件会写入 wp-content/blockstudio/cache,位于 uploads 目录之外。相对 path 路径以 WP_CONTENT_DIR 为基准解析;绝对路径则直接使用。这样便支持提供专用可写缓存卷的主机。

启用后,Blockstudio 会使用此根目录存放构建负载、预构建区块注册数据、已解析的编辑器资源、Tailwind CSS、渲染文档、岛屿片段、静态预渲染内容、图索引、队列和诊断信息。每个对象都按网络、站点、完整运行时标识和作用域隔离。运行时标识涵盖 Blockstudio、设置、WordPress、PHP、当前主题、当前插件、逻辑发现来源、主机上下文,以及所属操作提供的显式依赖哈希。

内容、术语、用户和元数据的更改会使已填充的字段选项失效,但不会影响结构块发现或已编译资源。选项会在固定的构建路径锁下单独刷新。一连串写入(例如同步翻译或导入)会合并处理:安静期后的首次写入会立即刷新,突发写入的最后一次更改则会在经过三十秒后反映一次,可通过 blockstudio/cache/populate_debounce 调整。作为记账操作而写入的元数据 WordPress(例如文章编辑锁)不算作更改;blockstudio/cache/populate_ignored_meta_keys 会扩展此列表。编辑器始终查询实时选项,因此时间窗口只会影响渲染时读取的缓存选项。源文件和构建设置仍会按正常方式使结构缓存失效。覆盖选项不会在每次内容更改时重新扫描缓存目录;定期清理仍会收集孤立的临时文件。特定语言的运行时标识彼此隔离;多语言站点上存在多个缓存命名空间目录,本身并不能证明发生了缓存未命中。

SQLite 在区块的 db 数据目录中产生的日志活动不会丢弃缓存的区块元数据。对 db.php、受监视源文件或数据目录中源文件及子目录结构的更改,仍会使缓存失效。

并发的运行时重建只会选出一个构建者。其他请求最多等待五秒,然后在源文件和所需的编译资源仍然存在时复用最近一次成功的区块元数据。如果冷启动请求没有可安全复用的负载,就会返回带有 Retry-After 的 HTTP 503,而不会启动另一次构建。blockstudio/cache/build_wait_budget 筛选器可调整结构重建和选项刷新所需的等待时间,单位为毫秒。不支持建议文件锁的主机会不加锁地刷新并发布选项,因此下一个请求即可命中缓存。

旧版本遗留的空闲、按键区分的 .build.lock 文件会由 WP-Cron 跨该站点的缓存命名空间收集;升级五分钟后开始,每分钟最多移除 10,000 个锁,每次任务限时十秒。wp bs cache status 会报告剩余数量,wp bs cache cleanup 会立即清空积压队列,wp bs cache clear 则会清除运行时缓存。如果因 cron 未触发而导致计划任务批次逾期超过十分钟,请求会每小时扫描并清理有限数量的锁,避免清理停滞。最近创建或仍被占用的锁会保留,新建的固定路径锁永远不会被收集。积压队列清空后,同一批任务会在已退役缓存命名空间的 namespaceGrace 到期后将其收集;每个站点每小时最多一次,并会为此保留每日定时任务。宽限期从首次扫描发现命名空间已退役时开始计算,而不是从该命名空间中的最新文件开始计算;只要某个作用域仍在使用该命名空间,就绝不会将其收集。 内部缓存清理不会调用 WordPress 附件删除筛选器。停用了 WP-Cron 的主机应继续运行常规的计划 cron 工作进程;不要为了清理积压而不加区分地删除仍在使用的锁文件。

blockstudio/settings/cache/path 设置筛选器会更改配置值。对于部署特定的路径解析,可用 blockstudio/cache/dir 筛选器处理解析后的基础目录:

PHP
add_filter('blockstudio/cache/dir', function (string $directory): string {
    return WP_CONTENT_DIR . '/cache/blockstudio';
});

租户标识与 WordPress 网络/博客 ID 不同的主机可以筛选 blockstudio/cache/site_key。结果会经过清理,且仅用作目录段。若要更改对象标识,应使用 blockstudio/cache/context,为其提供可序列化的运行时变体。

themeDefaults

选项 类型 默认值 描述
titleTag 布尔值 false 启用 WordPress 标题标签主题支持
suppressDirectoryUpdates 布尔值 false 从目录更新结果中移除当前子主题和父主题

模式仍使用现有的 Blockstudio\Patterns API;这些默认设置不会引入其他页面或模式门面。

performance

compat 配置档不会改变通用的 WordPress 行为。speed 和 strict 会启用相同的可选前端默认设置;每项子设置都可以覆盖其配置档值。

主动启用设置是注册门控。当某项可选功能false时, Blockstudio不会挂载该功能的前端、管理后台、编辑器、REST或 计划回调。使用后禁用 Early Serve 或计划预热会执行一次其负责的清理;后续请求保持无操作。

选项 类型 兼容模式默认值 速度/严格模式默认值 说明
profile string "compat" 不适用 compat、speed 或 strict
wordpress.headNoise boolean false true 移除通用 head 发现功能和 emoji 输出
wordpress.embeds boolean false true 移除 oEmbed 发现功能和主机脚本
wordpress.xmlrpc boolean false true 禁用 XML-RPC 和 pingback
wordpress.editor boolean false true 禁用远程编辑器发现界面
wordpress.frontendAssets boolean false true 移除通用核心前端资源
wordpress.media boolean false true 应用图像输出默认值
wordpress.heartbeat boolean false true 降低编辑器之外的 Heartbeat 频率
preload.links string "off" "intent" 用户发出操作后预取同源文档
media.lazy boolean false true 使用 Blockstudio 的图像加载器
media.skeleton boolean false true 显示内置加载骨架屏
media.metadata boolean false true 声明使用 assets/media.json
media.rootMargin string "300px" "300px" 延迟加载器的交叉区域边距
measurement.enabled boolean false false 启用运行时测量 API
measurement.queryMonitor boolean false false 包含耗时至少为 50ms 的查询
measurement.headers boolean false false 发送配置文件和配置哈希标头
measurement.timings boolean false false 发送运行时耗时标头
staticPrerender.enabled boolean false false 启用适用于匿名用户的 HTML 缓存
staticPrerender.ttl integer 86400 86400 缓存文档的最长时间(秒)
staticPrerender.invalidate string "signature" "signature" 使用 signature 或增量 graph 标识
staticPrerender.earlyServe boolean false false 在 WordPress 启动前提供安全的缓存命中
staticPrerender.serveLoggedIn boolean false false 允许用户使用缓存命中,但不能创建缓存命中
staticPrerender.dynamicPaths array [] [] 必须保持动态的路径前缀
staticPrerender.replayHeaders array ["Link"] ["Link"] 缓存命中时一并存储和发送的响应标头
staticPrerender.warm.enabled boolean false false 启用持久化的定时预热队列
staticPrerender.warm.interval integer 3600 3600 预热间隔(秒)
staticPrerender.warm.concurrency integer 2 2 单次预热最多处理的任务数
staticPrerender.warm.transport string "http" "http" 使用 http 或由主机提供的 internal 渲染器

除非明确启用,否则静态预渲染保持禁用状态。主开关关闭时不会注册预渲染请求钩子;关闭的 earlyServe 和 warm.enabled 开关不会注册管理界面或 cron 钩子。签名模式会在普通请求中使用低成本的激活身份标识。图模式适用于显式构建:它会记录每个页面的源依赖,因此更改一个页面不会使无关文档失效。有关预热、部署、提前提供和安全性的详细信息,请参阅静态预渲染。

可通过程序获取测量数据:

PHP
use Blockstudio\Performance_Measurement;

$snapshot = Performance_Measurement::snapshot();

启用标头后,Blockstudio 会发送 X-Blockstudio-Performance-Profile、 X-Blockstudio-Performance-Config,以及可选的 X-Blockstudio-Performance-Time。 blockstudio/performance/measurement_enabled 操作会接收解析后的 运行时设置。

media 选项用于驱动 bs_media_image()、assets/media.json 清单以及前端延迟加载器。有关辅助函数、清单构建器和加载器行为的说明,请参阅媒体。

content

选项 类型 默认值 说明
enabled boolean false 启用 Content Sync 配置
id string "default" 存储在已同步实体上的内容集命名空间
path string "content" 相对于主题的内容文件目录
includePageSyncManaged boolean false 纳入由 Page Sync 管理的文章,但不拥有其正文
authors string "ignore" 作者处理方式(ignore 或现有用户 login)
postTypes array [] 允许列表中的文章类型
meta.include array [] 要同步的 meta 键 glob 模式
meta.exclude array ["_edit_lock", "_edit_last", "_wp_old_slug"] 要排除的 meta 键 glob 模式
meta.references object {} 在 ID 和 UID 之间重写已声明的 meta 引用
taxonomies array [] 允许列表中的已注册分类法(适用于术语和关系)
media string "manifest" 附件引用行为(manifest 或 none)

Content Sync 通过 wp bs content 管理,并将允许列表中的文章、文章元数据及已声明的引用导出为可移植文件。有关工作流程和文件格式,请参阅内容同步。

editor

选项 类型 默认值 说明
formatOnSave boolean false 保存时格式化 block.json
assets array [] 在编辑器中加载其他资源
markup boolean false 启用标记编辑

tailwind

选项 类型 默认值 说明
enabled 布尔值 false 启用 Tailwind CSS 编译
config 字符串 "" Tailwind v4 CSS 优先配置

有关编译行为和 CSS 优先配置格式,请参阅Tailwind CSS。

blockTags

选项 类型 默认值 说明
enabled boolean false 启用在文章内容和小工具区域中渲染页面级 bs: 标签
allow array [] 区块名称模式的允许列表;支持 fnmatch() 通配符
deny array [] 区块名称模式的拒绝列表;优先级高于 allow
prefixes object {} 为简写指定命名空间前缀,每个值为一个命名空间或有序数组

模板级标签渲染始终启用;这些选项控制页面级替换。有关标签语法和解析规则,请参阅渲染。

ui

选项 类型 默认值 说明
enabled boolean false 注册随附的 bsui/* UI 组件和 app/* 演示应用

blockEditor

选项 类型 默认值 说明
disableLoading boolean false 禁用编辑器中的区块加载
enhance boolean false 启用 Blockstudio 编辑器悬停和选择控件
cssClasses array [] 要从中提取 CSS 类供类字段自动补全使用的样式表 URL
cssVariables array [] 要从中提取 CSS 变量供代码字段自动补全使用的样式表 URL

blockEditor.blocks

使用 blockEditor.blocks 设置整个项目的区块插入器策略。allow 和 deny 接受区块名称和通配符模式,例如 core/*。

JSON
{
  "blockEditor": {
    "blocks": {
      "allow": ["core/*", "my-theme/*"],
      "deny": ["core/embed", "core/freeform"],
      "directory": false,
      "categories": {
        "rename": {
          "text": "Writing",
          "design": "Layout"
        },
        "order": ["my-theme", "text", "media"]
      },
      "legacyWidgets": {
        "hide": ["archives", "calendar"]
      }
    }
  }
}

blocks.styles.deny 会注销通过 WordPress 的 PHP 区块样式注册表注册的样式:

JSON
{
  "blockEditor": {
    "blocks": {
      "styles": {
        "deny": {
          "my-theme/card": ["outline"],
          "my-theme/media": ["framed"]
        }
      }
    }
  }
}

blockEditor.patterns

使用 blockEditor.patterns 禁用全局模式来源并筛选模式类别。

JSON
{
  "blockEditor": {
    "patterns": {
      "core": false,
      "remote": false,
      "theme": true,
      "blockstudio": true,
      "categories": {
        "deny": ["gallery"],
        "rename": {
          "featured": "Featured Layouts"
        },
        "order": ["featured", "buttons"]
      }
    }
  }
}

blockEditor.media

使用 blockEditor.media 设置全局媒体插入器策略。

JSON
{
  "blockEditor": {
    "media": {
      "openverse": false,
      "imageSizes": {
        "allow": ["thumbnail", "large"],
        "deny": ["medium_large"]
      }
    }
  }
}

dev

选项 类型 默认值 说明
grab.enabled boolean false 启用前端元素抓取器
perf boolean false 在每次页面加载时启用性能分析器
canvas.enabled boolean false 启用画布
canvas.adminBar boolean true 查看画布时显示 WordPress 管理栏

githooks

选项 类型 默认值 说明
commit boolean false 运行 blockstudio-githooks sync 时生成仅用于分析的提交前钩子

有关生成的钩子会执行哪些操作以及如何保持同步,请参阅受管理的提交钩子。

phpstan

选项 类型 默认值 说明
preset string "base" 命令行未选择预设时使用的分析预设:base、theme、extreme-theme 或 wordpress-render
configuration string "" 与预设一同包含的项目 PHPStan 配置,从 blockstudio.json 解析
roots array ["."] 规范命令要分析的主题根目录
excludePaths array [] 相对于每个已配置根目录的其他扫描器排除项
maxFiles integer 10000 主题扫描器检查的文件数上限
blockTags object {} 元素映射、标签别名,以及 scanPhp 的 区块标签规则

这些设置用于驱动规范的 blockstudio-phpstan 命令。有关预设、层级和采用方式,请参阅PHPStan。

ai

选项 类型 默认值 说明
enableContextGeneration boolean false 生成一个合并的上下文文件,包含区块、设置、架构和供 LLM 工具使用的文档

有关文档索引和完整生成文本,请参阅AI 集成。

UI组件

启用并组合在 Blockstudio 7.3 中推出的随附无头 UI 组件。