跳转到正文

CLI

Blockstudio 会注册 WP-CLI 命令,用于在终端管理区块、基于文件的页面、数据库记录、RPC 函数、cron 作业、设置以及 WPML 语言配置。

区块

列出所有区块

命令行
wp bs blocks list
代码
+----------------------------+---------------------+-----------+------------------------+
| name                       | title               | component | category               |
+----------------------------+---------------------+-----------+------------------------+
| my-theme/hero              | Hero                |           | my-theme               |
| my-theme/card              | Card                | yes       | my-theme               |
| my-theme/newsletter        | Newsletter          |           | my-theme               |
+----------------------------+---------------------+-----------+------------------------+

仅筛选组件

命令行
wp bs blocks list --components

输出为JSON

命令行
wp bs blocks list --format=json

验证已存储字段

命令行
wp bs blocks validate 42
wp bs blocks validate 42 57 --format=json

检查指定文章 ID 中存储的内容,包括嵌套的 innerBlocks,并使用 bs_validate_block()。它不会渲染区块、展开同步模式引用,也不会修改文章。没有 Blockstudio 扩展的未知区块会被跳过。

默认表格会列出文章 ID、从零开始的区块路径、区块名称、发现代码、字段路径、来源和消息。JSON 还会包含原始的 value 和 expected 值。嵌套区块的区块路径可以是 0/1,字段路径可以是 cards/2/style;两者是不同的路径。

没有发现问题时,命令以 0 退出;存在问题时以 1 退出。JSON 输出是纯列表,成功时也包含 [],因此即使命令以 1 退出,自动化程序仍可读取输出。文章缺失、ID 缺失,以及使用 table 或 json 以外的格式,都会报错。所有 ID 都会在验证开始前检查。

渲染区块

命令行
wp bs blocks render
wp bs blocks render my-theme/hero my-theme/card
wp bs blocks render my-theme/card --attributes='{"variant":"wide"}'
wp bs blocks render my-theme/card --attributes=@card.json --format=json

按照页面的渲染方式渲染已注册区块,并报告其模板引发的每条 PHP 通知、警告、弃用提示和抛出错误。主题可以在 CI 中运行此命令,以对照已安装的 Blockstudio 对其区块进行冒烟测试。不指定名称时,会渲染所有已注册区块,包括组件。

每个区块都会通过 do_blocks() 渲染:该命令从区块注释生成带有 blockstudio.attributes 的内容,也就是编辑器存储的结构,并在 WP-CLI 的前端上下文中渲染,而不是使用插入器预览。渲染前不会设置查询文章。动态岛屿会渲染其实际模板正文,而不只是占位内容;模板意外输出的内容不会出现在报告中。

命令本身不会保存文章或字段值,但会像普通的 PHP 一样执行你的模板和渲染钩子。它们可能写入数据、调用外部服务或产生其他副作用。请在专用测试站点上对可信代码运行此命令;它不是只读沙箱。

每次渲染所用的属性按区块选择:

情况 属性
example 区块 block.json 的 example.attributes,即 插入器预览 使用的值。
defaults 每个字段的 default。用于没有 example.attributes 的区块;命令会为每个字段打印一行。
attributes --attributes 的值,用来替代示例。

--attributes 接受一个以存储键为键的 JSON 字段值对象,或者接受 @ 和包含该对象的文件路径,并且必须且只能指定一个区块名称。可用它访问示例未覆盖的模板分支,例如某个变体。仅用于在插入器预览中生成占位图像的示例值会被跳过,并且不会渲染示例的 innerBlocks。

代码
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| block               | case     | level      | message                                                                       | file                                                                         | line |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| smoke/deprecated    | defaults | Deprecated | strlen(): Passing null to parameter #1 ($string) of type string is deprecated | /wordpress/wp-content/themes/smoke-theme/blockstudio/deprecated/index.php    | 1    |
| smoke/undefined-key | example  | Warning    | Undefined array key "subtitle"                                                | /wordpress/wp-content/themes/smoke-theme/blockstudio/undefined-key/index.php | 2    |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+

表格会为每个问题列出一行。JSON 输出则会为每个渲染的区块列出一项,包括没有问题的区块,以便自动化程序读取所用的情况:

JSON
[
  {
    "block": "smoke/branch",
    "case": "attributes",
    "problems": [
      {
        "level": "Warning",
        "message": "Undefined array key \"width\"",
        "file": "/wordpress/wp-content/themes/smoke-theme/blockstudio/branch/index.php",
        "line": 2
      }
    ]
  }
]

level 可以是 Notice、Warning、Deprecated 或 Error。同一个问题若在同一文件和行重复出现,例如在循环中,会针对每个区块报告一次。由 @ 屏蔽的问题不会报告。只有在启用 WP_DEBUG 时,WordPress 才会产生其自身的弃用提示,例如 _deprecated_function() 的弃用提示。

没有发现问题时,命令以 0 退出;否则以 1 退出。未知区块名称、无法读取或无效的 --attributes,以及使用 table 或 json 以外的格式,都会报错;所有名称都会在渲染第一个区块前检查。

页面

由文件支持的页面同步是显式进行的。普通的WordPress请求 不会完整发现页面,也不会写入页面文章。冷启动的运行时可能会 读取一次集合清单以恢复路由,但不会同步内容。

命令行
wp bs pages sync

该命令会协调完整的目标清单,并报告发现、新建、更新、未更改、已锁定、已保留、已移除和失败的页面。指纹相同则不会写入文章或文章元数据。

表格输出会列出已更改、已锁定、内容已保留和已移除页面的文章 ID。JSON 包含 pages.<name>.preserved、pages.<name>.overwritten 和 removedPages 条目,其中列出页面名称、键、文章 ID 和清理操作。按键合并后若文章内容相同,则会报告为未更改,不会创建修订版本,也不会更新修改时间戳。

现有发布状态会保留;文件所有的标题和别名替换会作为警告打印。请参阅 文章字段所有权。

使用--authoritative替换受管理的内容,而不是保留带键的编辑器内容;使用--full时,无论存储的源标识是什么,都会将本轮报告为完整协调。无论采用哪种方式,每轮都会比较完整清单:

命令行
wp bs pages sync --authoritative --full

需要完整报告的部署脚本可使用:

命令行
wp bs pages sync --format=json

命令解析的每个页面都会检查区块存储但从未渲染的属性:也就是Blockstudio区块既未将其声明为字段、也未转发到根元素的属性,例如未声明的class。表格输出会针对每个页面和区块打印警告,dropped列会统计数量,JSON报告会在pages.<name>.droppedAttributes下列出这些属性。源内容未更改的页面不会重新解析,因此会在下次更改时,或在升级导致解析器变更后的首次同步时报告。

如果发现或协调过程中报告错误,命令会以失败状态退出。有关页面、PHPAPI及部署标识约定,请参阅相关文档。

数据库

列出架构

命令行
wp bs db schemas
代码
+-------------------+-------------+---------+---------------------+
| block             | schema      | storage | fields              |
+-------------------+-------------+---------+---------------------+
| my-theme/app      | subscribers | table   | email, name, plan   |
| my-theme/app      | logs        | jsonc   | action, details     |
| my-theme/app      | events      | storh   | title, status       |
+-------------------+-------------+---------+---------------------+

CRUD 操作

命令行
# List records
wp bs db list my-theme/app subscribers

# List with filters
wp bs db list my-theme/app subscribers --plan=pro --limit=10

# Get a single record
wp bs db get my-theme/app subscribers 1

# Create a record
wp bs db create my-theme/app subscribers --email=a@b.com --plan=pro

# Update a record
wp bs db update my-theme/app subscribers 1 --plan=enterprise

# Delete a record
wp bs db delete my-theme/app subscribers 1

对于单架构区块,架构名称默认为default:

命令行
wp bs db list my-theme/leads

将JSONC记录迁移到Storh

如果架构已有db/{schema}.jsonc文件,并且你想将记录移至Storh文件后端,请使用migrate:

命令行
wp bs db migrate my-theme/app subscribers --to=storh

对于单架构区块:

命令行
wp bs db migrate my-theme/app --to=storh

该命令会保留整数记录 ID,写入 uploads/blockstudio/db/{block-scope}/{schema}/,重建Storh索引, 验证目标存储,并保留源.jsonc文件。

输出格式

所有列表命令均支持--format=table(默认)、--format=json和 --format=csv:

命令行
wp bs db list my-theme/app subscribers --format=json

RPC

列出所有函数

命令行
wp bs rpc list
代码
+-------------------+-------------+--------+----------------+---------+
| block             | function    | public | capability     | methods |
+-------------------+-------------+--------+----------------+---------+
| my-theme/app      | subscribe   | yes    |                | POST    |
| my-theme/app      | stats       |        | edit_posts     | POST    |
| my-theme/app      | get_status  |        |                | GET,POST|
+-------------------+-------------+--------+----------------+---------+

调用函数

命令行
wp bs rpc call my-theme/app subscribe --email=user@example.com

输出为JSON:

JSON
{
  "success": true
}

参数以--key=value标志传递:

命令行
wp bs rpc call my-theme/app load_more --offset=10 --limit=5

Cron

列出所有任务

命令行
wp bs cron list
代码
+-------------------+----------+----------+---------------------+
| block             | job      | schedule | next_run            |
+-------------------+----------+----------+---------------------+
| my-theme/app      | cleanup  | daily    | 2026-03-17 00:00:00 |
| my-theme/app      | sync     | hourly   | 2026-03-16 15:00:00 |
+-------------------+----------+----------+---------------------+

手动运行任务

命令行
wp bs cron run my-theme/app cleanup

这会立即执行回调,不受计划安排限制。适用于测试和调试。

设置

显示所有设置

命令行
wp bs settings list

获取特定设置

命令行
wp bs settings get tailwind/enabled
wp bs settings get assets/enqueue

Tailwind

将HTML编译为CSS

命令行
wp bs tailwind compile '<div class="flex items-center p-4">'

从文件编译

命令行
wp bs tailwind compile --file=template.html

缓存管理

命令行
wp bs tailwind cache path    # show cache directory
wp bs tailwind cache clear   # clear compiled cache

SCSS

将SCSS编译为CSS

命令行
wp bs scss compile '$color: red; .test { color: $color; }'

从文件编译

命令行
wp bs scss compile --file=styles.scss

自定义字段

列出所有已注册的自定义字段

命令行
wp bs fields list
代码
+-------+----------------+---------------------------+
| name  | title          | fields                    |
+-------+----------------+---------------------------+
| hero  | Hero Section   | heading, description, cta |
| card  | Card           | title, image, link        |
+-------+----------------+---------------------------+

资源

列出所有资源

命令行
wp bs assets list

按类型筛选

命令行
wp bs assets list --type=global
wp bs assets list --type=admin
wp bs assets list --type=editor
wp bs assets list --type=registered

脚本编写

所有命令都支持--format=json,方便进行管道操作:

命令行
# Export all subscribers as JSON
wp bs db list my-theme/app subscribers --format=json > subscribers.json

# Count records
wp bs db list my-theme/app subscribers --format=json | jq length

# Batch delete
wp bs db list my-theme/app logs --format=json | \
  jq -r '.[].id' | \
  xargs -I {} wp bs db delete my-theme/app logs {}

内容同步

内容同步会将允许列表中的WordPress内容导出到文件,并将这些文件应用回数据库。它需要显式触发并由CLI驱动;不会在页面加载或管理后台初始化时同步。

有关配置、文件格式,以及适合采用基于文件的数据库内容的情形,请参阅内容同步。

将数据库内容拉取到文件

命令行
wp bs content pull

将拉取范围限制为一个已配置的文章类型或分类法:

命令行
wp bs content pull --post-type=team_member
wp bs content pull --taxonomy=category

预览但不写入 UID 或文件:

命令行
wp bs content pull --dry-run

将文件推送到数据库

命令行
wp bs content push

预览应用计划,但不写入:

命令行
wp bs content push --dry-run

清理文件中已不存在、由内容集拥有的数据库文章和术语:

命令行
wp bs content push --prune --yes

使用--prune时,Blockstudio会先应用所有文件更改,然后移除文件中已不存在、由内容集拥有的实体。除非提供--yes,否则不会执行破坏性清理。

检查状态

命令行
wp bs content status

表格会将每个由文件支持的实体报告为unchanged、would-update、missing-db、conflict、locked或orphaned。

静态预渲染

有关缓存本身,请参阅静态预渲染;这些命令用于驱动缓存。

预热过期条目

命令行
wp bs prerender warm

将过期的公开 URL 加入队列,然后从持久化预热队列中最多重新渲染warm.concurrency个任务,并打印包含queued、processed、 warmed、skipped和failed数量的JSON摘要。内容和站点变更会自动加入替换任务。再次运行该命令,或等待计划的预热程序运行,以逐步处理更大的队列;渲染失败的URL会保持过期状态,并在下次运行时重新入队。在graph模式下,按URL预热功能会关闭,命令不会加入任何任务。

报告缓存状态

命令行
wp bs prerender status

报告当前标识、文件、字节数、图谱记录、队列状态、提前提供映射报告,以及按范围统计的命中、未命中、构建和失败计数。

清除缓存

命令行
wp bs prerender purge

移除当前站点的预渲染文档。下一次匿名请求或预热过程会重新构建这些文档。

检查并清理提前提供映射

命令行
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune

map status会报告安装范围内的提前提供映射:其中的条目和路由、缺失的路由文档、不再存在的站点对应的orphaned条目,以及对应目录已消失的dead条目。map prune会移除孤立和失效条目,并逐项打印移除原因;--dry-run则只打印相同报告,不进行写入。绝不会触碰由其他工具拥有的映射。

WPML

生成语言配置

命令行
wp bs wpml config
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml

打印一个 wpml-config.xml,将每个已注册区块的文本字段声明为待翻译字段,并将文件字段声明为附件 ID;也可以使用 --file 将其写入文件。在现有文件中,只会替换 Blockstudio 标记之间的部分。请参阅 WPML,了解声明的内容以及如何保持文件更新。

区块标签迁移

独立脚本会将前缀和别名简写改写为规范的<bs:namespace-slug>拼写。它不会加载WordPress,除非明确提供--apply,否则不会写入:

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

前缀文件会将调用方拥有的前缀映射到有序命名空间。已知区块文件是已注册区块名称的JSON列表。精确别名是可选的。报告包含确定性映射、前后哈希、未知标签、含糊别名、动态标签,以及在注释、代码围栏、<pre>或<code>范围中找到的示例。

扫描器可处理成对、嵌套和自闭合标记,包括PHP字符串中的字面标记。它会保留属性,只更改标记名称。注释和代码示例仅用于报告。无关的自定义元素会被忽略。除非调用方有意传入--allow-unresolved,否则只要仍有未知、含糊或动态情形,就会阻止应用迁移。 再次对规范输出运行该命令不会产生任何更改。

有关规范拼写存在的原因及其解决的问题,请参阅迁移。

拆除

命令行
wp bs teardown

移除安装所拥有的cron事件和静态预渲染状态:当前站点的提前提供映射条目,以及在最后一个自有条目消失后移除共享的advanced-cache.php临时文件和WP_CACHE声明。对于没有插件停用钩子的安装(例如Composer捆绑式部署),可使用此命令彻底移除。配置文件会保留。