跳转到正文

blocks.json

blocks.json 位于主题或插件的根目录中。它会告诉 CLI 区块的安装位置,以及要搜索哪些注册表。

架构

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}

字段

$schema

可选。指向 JSON 架构,以支持编辑器自动补全和验证。

directory

必填。 区块安装位置相对于 blocks.json 的路径。

每个区块都会在此目录下获得自己的子文件夹。如果 directory 为 blockstudio,并且你添加 hero,文件就会放在 blockstudio/hero/。

registries

必填。 将命名空间名称映射到注册表引用的对象。

键是在 CLI 命令中使用的命名空间(npx blockstudio add ui/hero)。值可以是 URL 字符串,也可以是包含 url 和可选 headers 的对象。

字符串格式(公共注册表):

JSON
{
  "registries": {
    "ui": "https://example.com/registry.json"
  }
}

对象格式(需要身份验证的注册表):

JSON
{
  "registries": {
    "private": {
      "url": "https://private.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

两种格式可以在同一配置中混用。注册表数量不限。添加未指定命名空间的区块时,CLI 会搜索所有注册表。

身份验证

需要身份验证的注册表使用带有 headers 的对象格式。CLI 会在向该注册表发送的每个请求中附带这些标头,包括获取 registry.json 和下载单个文件。

Bearer 令牌

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Basic 身份验证

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Basic ${REGISTRY_CREDENTIALS}"
      }
    }
  }
}

自定义标头

可以添加任意标头。这适用于 API 密钥、组织标识符,或注册表服务器要求的任何内容:

JSON
{
  "registries": {
    "internal": {
      "url": "https://blocks.internal.company.com/registry.json",
      "headers": {
        "X-API-Key": "${BLOCKS_API_KEY}",
        "X-Org-ID": "acme"
      }
    }
  }
}

环境变量

标头值支持 ${VAR_NAME} 语法,用于读取环境变量。这样可以避免将令牌提交到版本控制中。

CLI 会在运行时解析环境变量。如果所引用的变量未设置,CLI 会报错退出,并指出缺失的变量及其所用的标头。

在 shell 或 CI 环境中设置该变量。CLI 只读取进程环境;它不会自行加载 .env 文件:

命令行
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

静态标头值(不含 ${...})会原样传递。

配置发现

CLI 会从当前工作目录开始向上查找 blocks.json。因此,你可以从项目的任意子目录运行命令。

代码
my-theme/
  blocks.json        <- found here
  blockstudio/
    hero/
  templates/
    page.php          <- running `npx blockstudio add` here still works

如果找不到 blocks.json,CLI 会提示你运行 npx blockstudio init。

示例:包含两个注册表的主题

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.mycompany.com/ui/registry.json",
    "internal": "https://blocks.mycompany.com/internal/registry.json"
  }
}

示例:使用自定义目录的插件

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "src/blocks",
  "registries": {
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}