跳转到正文

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。