blocks.json 架构
完整架构
JSON
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"public": "https://example.com/registry.json",
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
字段
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
$schema |
string |
否 | 用于编辑器验证的 JSON Schema URL。 |
directory |
string |
是 | 区块安装位置相对于 blocks.json 的相对路径。不得为空。 |
registries |
Record<string, string | RegistryRef> |
是 | 将命名空间名称映射到注册表引用的映射。可以为空。 |
注册表引用格式
registries 中的每个值可以是字符串 URL,也可以是对象:
字符串:指向 registry.json 文件的有效 URL。
对象:
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
url |
string |
是 | 指向 registry.json 文件的有效 URL。 |
headers |
Record<string, string> |
否 | 每次请求此注册表时都会发送的 HTTP 标头。值支持 ${ENV_VAR} 插值。 |
验证规则
directory必须是非空字符串。registries中的每个键都必须是非空字符串。- 字符串形式的注册表值必须是有效 URL。
- 对象形式的注册表值必须包含有效的
url字段。 - 标头中的
${ENV_VAR}引用会在运行时解析。缺少变量时会报错,并指出变量名和标头。 registries对象可以为空。此时add会以No registries configured in blocks.json. Add a registry first.退出,list会输出No registries configured.,而search会输出No blocks matching "<query>".。
配置发现
CLI 会从当前工作目录开始向上遍历父目录,最多搜索 20 层以查找 blocks.json。使用找到的第一个 blocks.json。