在 GitHub 上发布区块注册表
构建了几个不错的区块后,你肯定也希望在下一个项目中使用它们。手动在主题之间复制文件夹,直到副本逐渐不一致,没人记得哪个主题包含修复后的版本。为每个区块打包并单独构建,又显得过于繁琐,因为这些文件夹里只有一个 block.json 和一个模板。
区块注册表正好介于两者之间。它由一个 registry.json 文件和一组通过普通 HTTP 提供服务的区块文件夹组成。使用者运行 CLI 命令,区块源代码会复制到其主题中,之后该副本就归他们所有。GitHub 仓库足以托管注册表,因为 GitHub 会通过原始 URL 提供公共仓库中的所有文件。
本指南将构建一个名为 acme 的注册表,其中包含四个区块;通过仓库 acme/acme-blocks 发布注册表,将区块安装到主题中,并通过 git 标签固定一个发行版本。
blockstudio 包在 npm 上的版本为 0.0.1。该版本只是一个占位版本:它唯一的命令 add 会打印 Adding block: <name>,然后退出,不会获取任何内容。本指南中的命令和输出来自 Blockstudio 仓库(packages/registry)中的注册表 CLI,这正是 CLI 所描述的 注册表文档。
各部分如何配合
需要了解的文件有两个:
registry.json由区块作者发布。它列出区块、每个区块包含的文件,以及用于下载这些文件的baseUrl。blocks.json位于使用者的主题或插件中。它指定要使用的注册表,以及区块的安装目录。
安装区块时,CLI 会获取 blocks.json 中的每个注册表,查找该区块并解析其依赖项,从 {baseUrl}/{block}/{file} 下载列出的每个文件,再将其写入 {directory}/{block}/{file}。它不会转换任何内容,因此磁盘上的文件与仓库中的文件完全相同。
第 1 步:整理仓库结构
创建一个仓库,在根目录放置 registry.json,并在 blocks/ 下为每个区块创建一个文件夹:
acme-blocks/
registry.json
blocks/
hero/
block.json
index.php
card/
block.json
index.php
style.scss
tabs/
block.json
index.php
style.scss
tab-item/
block.json
index.php
文件夹名称是区块在注册表中的名称,也会成为区块在使用者主题中的文件夹名称。请确保它与 block.json 中区块名称的后半部分完全一致(acme/hero 位于 hero/ 中),这样安装后的文件夹就容易识别。
第 2 步:编写区块
每个文件夹都是普通的 Blockstudio 区块。主视觉区区块包含一个字段:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"category": "design",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build faster"
}
]
}
}
<section useBlockProps class="acme-hero">
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>
card 遵循相同模式,并添加一个 style.scss。tabs 会渲染 <InnerBlocks allowedBlocks='["acme/tab-item"]' />,而 tab-item 会声明 "parent": ["acme/tabs"],因此没有 tab-item 时,tabs 就没有用处。下一步会在注册表中声明这种关系。
这些区块没有任何注册表专属内容。CLI 会复制文件夹,因此使用 @wordpress/create-block 构建或通过普通的 PHP 注册的区块,也可以用相同方式发布。
第 3 步:编写 registry.json
registry.json 会列出 CLI 应下载的所有区块和文件:
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "acme",
"description": "Acme block library.",
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
"blocks": [
{
"name": "hero",
"title": "Hero",
"description": "Full-width hero section with a heading.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
},
{
"name": "card",
"title": "Card",
"description": "Content card with a title.",
"category": "components",
"type": "blockstudio",
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tab-item",
"title": "Tab Item",
"description": "Single tab panel used inside Tabs.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
}
]
}
以下几条规则决定此文件是否有效:
files是一个明确的列表。 CLI只会下载这些路径,不会下载其他内容。它不使用 glob,因此只有将新资源添加到此处后,它才会随包发布。路径可以包含子目录,安装时会创建这些目录。baseUrl必须是绝对URL。 CLI会将其验证为URL,并拒绝相对值。区块文件始终从baseUrl获取,绝不会从registry.json加载位置的相对路径获取。dependencies必须引用同一注册表中的区块。 添加tabs会先安装tab-item。缺失依赖和循环依赖都会导致安装停止并报错。name为必填项,但不会显示。 命令和输出使用使用者在blocks.json中提供给注册表的键,两者不必一致。type仅供参考。 它接受blockstudio、create-block或wordpress,不会改变CLI的行为。
CLI每次获取文件时都会验证整个文件,并报告每个校验失败的字段,因此拼写错误会在下载任何文件之前显示出来。$schema行会在编辑器中执行相同的检查。
第 4 步:通过原始 URL 发布
将仓库提交并推送到GitHub。之后,公共仓库中的每个文件都可通过以下地址访问:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref>是分支、标签或提交 SHA。对于此注册表,有两个重要的 URL:
- 使用者配置的注册表URL:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json registry.json中的baseUrl:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
使用该baseUrl时,hero的index.php会从https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php获取。
原始主机会返回文件内容,而不是HTML的GitHub页面,这是CLI所需的内容。所有者、仓库或 ref 有误时,第一次执行命令就会出现404:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
第 5 步:在主题中安装区块
在使用方主题的根目录中创建blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes会写入一个空的registries对象。在你希望用于输入命令的命名空间下添加注册表:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
在终端中运行不带--yes的init,即可改为交互式回答相同的问题(区块目录、注册表名称和 URL)。
检查注册表是否可解析:
npx blockstudio list
acme (4 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
tabs Tabs layout blockstudio
tab-item Tab Item layout blockstudio
search会对名称、标题和描述进行不区分大小写的子字符串匹配:
npx blockstudio search tab
Results for "tab"
acme/tabs - Tabs
Tabbed content with keyboard navigation.
acme/tab-item - Tab Item
Single tab panel used inside Tabs.
使用--dry-run预览安装。依赖项会列在前面,因为它会先安装:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
然后正式安装:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
现在这两个文件夹都位于主题的blockstudio目录中,结构与仓库中的完全一致:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
如果只有一个已配置的注册表包含该区块,可以省略命名空间;也可以一次传入多个区块:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio会像发现主题中的其他区块一样,发现这些新文件夹。
更新已安装的区块
安装的文件只是副本。系统不会跟踪你安装的版本,CLI也不会自行更新区块。要获取较新版本,请再次添加该区块。如果没有终端,或在 CI 中运行,已有文件夹会导致命令停止:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
在终端中,CLI会先询问是否覆盖。--dry-run会报告将要替换的文件夹,--yes则会执行替换:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
覆盖会将所列文件替换为注册表中的版本,因此请先提交本地更改,再使用git diff检查结果。
卸载时,按名称移除文件夹:
npx blockstudio remove tabs --yes
Removed tabs
remove接收的是文件夹名称,而不是namespace/block。它不会移除依赖项,因此移除tabs后,tab-item仍会保留。
使用 git ref 进行版本管理
CLI没有版本字段,也没有版本标志。它获取的内容完全由 URL 决定;在GitHub上,URL中的 ref 就是版本。使用者若指向main,安装时会获取main当前包含的内容。
要发布固定不变的版本,标签中的registry.json也必须从该标签下载。打标签前,将baseUrl设置为该标签:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
然后提交、打标签并推送:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
之后,将baseUrl恢复为main并提交,这样分支就会继续提供当前文件。如果跳过第一步,固定到该标签的使用者会获取标签中的区块列表,却从main下载文件。
使用者可以在注册表URL中使用标签来固定版本:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
在此示例中,v1.0.0是在tabs和tab-item创建之前打的标签,因此固定的注册表只提供最初的两个区块:
npx blockstudio list
acme (2 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
npx blockstudio add acme/tabs
Block "tabs" not found in registry "acme".
提交 SHA 也可以用于注册表URL,但提交本身无法在baseUrl中包含自己的 SHA。因此,按 SHA 固定可以锁定区块列表,但文件仍来自该提交的baseUrl所指向的 ref,所以发布版本时建议使用标签。
注意事项
- 会先获取每个注册表。
add会先加载blocks.json中的所有注册表,再解析任何内容,因此即使是acme/hero,只要有一个注册表无法访问,命令就会失败。请移除不再使用的注册表。 - 名称有歧义时需要指定命名空间。 如果两个注册表都包含
hero,终端会话会询问要使用哪一个,--yes会按blocks.json顺序选择第一个,而非交互式运行则会以Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero退出。 - 私有仓库需要请求头。 使用注册表条目的对象形式,并设置
url和headers。请求头的值支持${VAR}占位符,其内容会从环境中读取;CLI 会在获取注册表和下载每个文件时发送这些请求头。有关令牌设置,请参阅 GitHub 托管。
后续步骤
- 注册表概览:了解注册表是什么,以及CLI如何工作
- registry.json:清单中的每个字段
- blocks.json:使用方配置、身份验证和配置发现
- 添加:命名空间解析、依赖项和覆盖行为
- GitHub托管:GitHub Pages和私有仓库
- 自定义服务器:通过自己的基础设施提供注册表