registry.json
registry.json 是托管在 URL 上的 JSON 文件。它会列出注册表中所有可用区块、其元数据、依赖项和文件清单。
架构
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "ui",
"description": "Core UI blocks for Blockstudio projects.",
"baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
"blocks": [
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with accessible keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": [
"block.json",
"index.php",
"style.scss"
]
}
]
}
顶层字段
name
必填。 注册表标识符。CLI 会验证该标识符,但不会显示它:命令和输出使用使用者在 blocks.json 中为注册表选择的键。
description
可选。对该注册表内容的简短说明。
baseUrl
必填。 用于下载区块文件的基础 URL。必须是有效的 URL。
文件通过组合基础 URL、区块名称和文件路径来获取:{baseUrl}/{block.name}/{file}。
例如,baseUrl 设置为 https://raw.githubusercontent.com/acme/blocks/main/blocks,区块名称为 tabs,文件为 index.php 时,CLI 会获取:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
区块字段
name
必填。 区块的文件夹名称。这是在 CLI 命令中使用的标识符,也会成为磁盘上的文件夹名称。
title
可选。在 list 和 search 输出中显示的易读名称。
description
可选。在 search 结果中显示的单行说明。
category
可选。在 list 输出中用于分组的标签。
type
可选。可为 blockstudio、create-block 或 wordpress 之一。
此项仅供参考。CLI 不会根据区块类型改变行为。它始终会下载并复制 files 中列出的文件。
dependencies
可选。同一注册表中必须与此区块一起安装的其他区块名称数组。
用户添加带有依赖项的区块时,CLI 会解析完整的依赖树,并按正确顺序安装所有内容。检测到循环依赖时会拒绝操作。
依赖项必须存在于同一注册表中。不支持跨注册表依赖。
files
必填。 相对于区块文件夹的文件路径数组。至少需要一个文件。
这些是 CLI 下载并写入磁盘的确切文件。路径可以包含子目录:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
文件解析
对于区块清单中的每个文件,CLI 会构造下载 URL:
{baseUrl}/{block.name}/{file}
并将其写入:
{directory}/{block.name}/{file}
区块文件夹内的目录结构会保留。如果文件路径包含子目录,则会自动创建这些目录。
文件始终从 registry.json 内的 baseUrl 获取,而不会从 blocks.json 中注册表 URL 的相对位置获取。
验证
每次获取时,CLI 都会根据 Zod 架构验证 registry.json。注册表无效时会给出清晰的错误消息,指出验证失败的具体字段。
缺少必填字段、空的 blocks 或 files 数组、无效 URL 以及未知的 type 值,都会在下载任何文件前被检测出来。