blocks.json
blocks.json 位于主题或插件的根目录中。它会告诉 CLI 区块的安装位置,以及要搜索哪些注册表。
架构
{
"$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 的对象。
字符串格式(公共注册表):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
对象格式(需要身份验证的注册表):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
两种格式可以在同一配置中混用。注册表数量不限。添加未指定命名空间的区块时,CLI 会搜索所有注册表。
身份验证
需要身份验证的注册表使用带有 headers 的对象格式。CLI 会在向该注册表发送的每个请求中附带这些标头,包括获取 registry.json 和下载单个文件。
Bearer 令牌
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Basic 身份验证
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
自定义标头
可以添加任意标头。这适用于 API 密钥、组织标识符,或注册表服务器要求的任何内容:
{
"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。
示例:包含两个注册表的主题
{
"$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"
}
}
示例:使用自定义目录的插件
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}