跳转到正文

GitHub

GitHub 是托管注册表最简单的方式。将区块推送到代码库,然后使用 GitHub 的原始内容 URL。

设置

创建一个采用以下结构的代码库:

代码
acme-blocks/
  registry.json
  blocks/
    hero/
      block.json
      index.php
    card/
      block.json
      index.php
      style.scss

registry.json

将 baseUrl 设置为 blocks/ 目录对应的原始 GitHub URL:

JSON
{
  "name": "acme",
  "description": "Acme Corp block library.",
  "baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
  "blocks": [
    {
      "name": "hero",
      "title": "Hero",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    },
    {
      "name": "card",
      "title": "Card",
      "category": "components",
      "type": "blockstudio",
      "files": ["block.json", "index.php", "style.scss"]
    }
  ]
}

baseUrl 使用 raw.githubusercontent.com,这样 CLI 获取的就是原始文件内容,而不是 GitHub HTML 页面。

使用者配置

用户将你的注册表添加到他们的 blocks.json 中:

JSON
{
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
  }
}

然后:

命令行
npx blockstudio add acme/hero

固定到某个版本

要固定到特定版本,请使用标签或提交 SHA,而不是 main:

JSON
{
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

只要该标签上的 registry.json 也在其 baseUrl 中使用该标签,就能避免破坏性更改影响现有项目。CLI 会从 baseUrl 下载区块文件,因此,如果带标签的 registry.json 的 baseUrl 仍指向 main,安装的文件就来自 main。提交 SHA 也一样:它固定的是区块列表,而文件来自该提交的 baseUrl 所命名的引用。

GitHub Pages

如果你希望获得更简洁的 URL,也可以通过 GitHub Pages 提供注册表:

  1. 为代码库启用 GitHub Pages
  2. 将 baseUrl 设置为你的 Pages URL:https://acme.github.io/acme-blocks/blocks
  3. 可通过 https://acme.github.io/acme-blocks/registry.json 访问 registry.json

私有代码库

对于私有代码库,请使用对象注册表格式,并提供 GitHub 个人访问令牌:

JSON
{
  "registries": {
    "private": {
      "url": "https://raw.githubusercontent.com/acme/private-blocks/main/registry.json",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

在环境中设置令牌:

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

要通过 raw.githubusercontent.com 访问私有代码库内容,令牌需要具备 repo 权限范围(细粒度令牌则需要 contents:read)。