使用 Homebrew 从私有 GitHub 仓库分发早期访问二进制文件

对于许多开发者来说，Homebrew 是 macOS 上不可或缺的软件包管理器。它简化了软件的安装和管理流程。然而，当涉及到从**私有 GitHub 仓库**分发构建产物（例如，为赞助者提供早期访问版本）时，情况就变得复杂了。本文将探讨如何利用 Homebrew 和 GitHub Actions 实现这一目标，为您的赞助者提供流畅的 `brew install` 安装体验。

##### 面临的挑战

为公共仓库创建 Homebrew Formula 相对直接，通常只需在 `url` 中指定源码包的下载地址即可。然而，对于私有仓库的发布产物（Release Artifacts），简单地使用 `browser_download_url` 是行不通的，因为 Homebrew 在下载时无法通过常规方式携带认证信息，会导致下载失败。

##### 解决方案：利用 GitHub API 和 `HOMEBREW_GITHUB_API_TOKEN`

要解决这个问题，我们不能直接使用面向浏览器的下载链接，而需要转向 GitHub 的 API。具体来说，是通过 API 端点来获取二进制文件，并在请求头中附加授权信息。

幸运的是，Homebrew 已经考虑到了这种情况，并提供了一个内置的解决方案：`HOMEBREW_GITHUB_API_TOKEN` 环境变量。当用户在他们的环境中设置了这个环境变量后，Homebrew 会在向 GitHub API 发出请求时自动携带它。

**实现步骤：**

1.  **创建自定义下载策略 (Custom Download Strategy)**
    为了让 Homebrew 使用 API 进行下载，我们需要在我们的 Tap 仓库中定义一个 Ruby 类，即自定义下载策略。这个类会构建正确的 GitHub API URL (`https://api.github.com/repos/$ORG/$REPO/releases/assets/$ASSET_ID`)，并添加必要的 `Authorization` 和 `Accept` 请求头。

2.  **在 Formula 中使用新策略**
    在你的软件的 Formula 文件中，你需要引入并使用这个自定义的下载策略。这通常通过在 `url` 定义后面加上 `, :using => GitHubPrivateRepositoryReleaseDownloadStrategy` 来实现。

3.  **动态更新 Asset ID 和 SHA256**
    一个棘手的问题是，每次创建新的构建（例如夜间构建）时，发布产物的 `ASSET_ID` 和文件的 `sha256` 校验和都会改变。为了自动化这个过程，你需要在你的 CI/CD 流程（如 GitHub Actions）中加入一个步骤：
    *   在构建和发布成功后，通过 GitHub API 获取最新的 Asset ID 和新产物的 sha256 值。
    *   自动更新你的 Homebrew Tap 仓库中的 Formula 文件，将新的 Asset ID 和 sha256 值写入其中。
    *   将更新后的 Formula 文件提交并推送到 Tap 仓库。

4.  **引导用户设置 Token**
    为了让最终用户（你的赞助者）能够成功安装，他们需要在自己的电脑上设置 `HOMEBREW_GITHUB_API_TOKEN`。你需要提供清晰的指引，告诉他们如何生成一个具有 `repo` 权限的 Personal Access Token (PAT)，并将其导出为环境变量。

##### 结论

虽然为私有仓库设置 Homebrew 分发比公共仓库要复杂一些，但通过利用 GitHub API 和 Homebrew 的自定义下载策略，我们可以为赞助者或内部团队成员提供一种无缝、专业的软件安装体验。这种方法不仅提升了用户体验，也为独立开发者通过提供早期访问权限来获得财务支持创造了具体可行的途径。