发布Homebrew流程

一、前置准备

 

1.1 核心概念梳理

 

• Homebrew Tap：自定义的 Formula 仓库，分为「个人 Tap（非官方）」和「官方 Tap（homebrew-core）」；
• Formula：Homebrew 的包定义脚本（Ruby 文件，后缀.rb），描述软件的下载地址、校验值、安装逻辑等；
• sha256：二进制包的哈希校验值，用于验证下载文件完整性；
• brew 命令核心操作：brew tap（添加仓库）、brew install（安装包）、brew audit（校验 Formula 合法性）。

 

1.2 环境要求

 

• 操作系统：macOS（推荐）或 Linux（需安装 Homebrew on Linux）；
• 已安装 Git、Homebrew；
• 拥有 GitHub 账号（需创建个人 Tap 仓库、软件源码仓库）；
• 软件已发布二进制包到 GitHub Releases（或其他可访问的地址）。

 

二、个人 Tap 仓库发包（快速发布，无审核）

 

个人 Tap 是最灵活的发包方式，无需审核，适合个人工具、内测包或非通用型软件。

 

2.1 初始化个人 Tap 仓库

 

Homebrew 要求个人 Tap 仓库命名规范为homebrew-xxx（示例中为homebrew-tap）。

 

步骤 1：创建并克隆仓库

 

git clone https://github.com/navysummer/homebrew-tap.git

 

步骤 2：创建 Formula 目录并编写脚本

 

Homebrew 约定 Formula 文件放在Formula目录下（小写命名）。

 

# 创建Formula目录（首次需初始化）
mkdir -p Formula
# 创建并编辑Formula文件（文件名建议与软件名一致，小写）
vim Formula/ns-sandbox.rb

 

 

将以下脚本（优化后）写入ns-sandbox.rb：

 

class NsSandbox < Formuladesc "Cross-platform command-line ns-sandbox"homepage "https://github.com/navysummer/ns-sandbox"version "0.0.1"license "MIT"on_macos doon_intel dourl "https://github.com/navysummer/ns-sandbox/releases/download/v0.0.1/ns-sandbox-#{version}-x86_64.tar.gz"sha256 "9c37892e94909f6bd39a79fd3bc4f785b31be9d1bc3691bc23ba06ab7a6beb96"endon_arm dourl "https://github.com/navysummer/ns-sandbox/releases/download/v0.0.1/ns-sandbox-#{version}-arm64.tar.gz"sha256 "5a31dafa76824e5725751793317e2b9a8643b2760eb656c8e6d9e1e5b8715222"endenddef installbin.install "ns-sandbox"endtest dosystem "bin/ns-sandbox", "--version"end
end

 

 

 

步骤 3：校验 Formula 合法性

 

发布前必须通过brew audit校验，避免语法 / 逻辑错误：

# 测试 Formula
brew install --build-from-source navysummer/tap/ns-sandbox
brew test ns-sandbox
brew audit --strict ns-sandbox # 检查规范# 测试 Cask
brew install --cask navysummer/tap/ns-sandbox

步骤 4：提交并推送仓库

 

# 提交代码
git add Formula/ns-sandbox.rb
git commit -m "feat: add ns-sandbox v0.0.1"
# 推送到GitHub
git push origin main

 

2.2 让用户安装你的包

 

用户只需执行以下命令即可安装：

# 1. 添加你的个人Tap（首次安装需执行）
brew tap navysummer/tap
# 2. 安装软件
brew install ns-sandbox

 

2.3 个人 Tap 版本更新流程

 

当软件发布新版本（如0.0.2）时：

 

1. 更新 GitHub Releases，上传对应版本的二进制包；
2. 计算新包的 sha256 值：

   shasum -a 256 /path/to/ns-sandbox-0.0.2-x86_64.tar.gz
   shasum -a 256 /path/to/ns-sandbox-0.0.2-arm64.tar.gz
   

    

    
3. 修改Formula/ns-sandbox.rb中的version、url、sha256；
4. 重新执行brew audit校验，提交并推送代码；
5. 用户更新命令：
    

   brew update && brew upgrade ns-sandbox
   

    

 

三、官方仓库（homebrew-core）发包（需审核）

 

将包提交到 Homebrew 官方仓库homebrew-core，用户无需手动tap，直接brew install即可，但需满足严格的审核标准。

 

3.1 提交前的核心要求（必须满足）

 

1. 软件必须是开源的（MIT/Apache 等合规协议）；
2. 软件有清晰的维护周期，非一次性项目；
3. Formula 脚本符合 Homebrew 规范（无硬编码、测试用例有效）；
4. 二进制包 / 源码可稳定访问，且 sha256 校验值准确；
5. 软件名称未与homebrew-core现有包冲突；
6. 需通过brew audit --strict和brew test全量校验。

 

3.2 提交流程（Fork + PR 模式）

 

步骤 1：Fork 并克隆 homebrew-core 仓库

 

 

# 1. 网页端Fork：https://github.com/Homebrew/homebrew-core
# 2. 克隆Fork后的仓库到本地
git clone https://github.com/navysummer/homebrew-core.git
cd homebrew-core
# 3. 添加官方上游仓库（用于同步最新代码）
git remote add upstream https://github.com/Homebrew/homebrew-core.git
git fetch upstream

 

 

步骤 2：创建分支并编写 Formula

 

# 创建新分支（命名规范：<软件名>-<版本>）
git checkout -b ns-sandbox-0.0.1 upstream/master
# 编写Formula文件（放在Formula目录下）
vim Formula/ns-sandbox.rb

 

 

注：官方仓库的 Formula 脚本需更严格，建议移除手动version，改用url自动解析（需 GitHub Release 标签规范）：

 

 

rubyclass NsSandbox < Formuladesc "Cross-platform command-line ns-sandbox"homepage "https://github.com/navysummer/ns-sandbox"url "https://github.com/navysummer/ns-sandbox/archive/refs/tags/v0.0.1.tar.gz"sha256 "替换为源码包的sha256（若用源码编译）"# 若用二进制包，需保留on_macos分支，但官方更推荐源码编译license "MIT"def installbin.install "ns-sandbox" # 若源码编译，需补充make/install逻辑endtest dosystem "#{bin}/ns-sandbox", "--version"end
end

 

 

步骤 3：严格校验 Formula

 

官方审核会自动执行这些检查，本地提前校验可减少驳回概率：

 

 

# 1. 基础校验
brew audit --strict --online Formula/ns-sandbox.rb
# 2. 测试安装
brew install --build-from-source Formula/ns-sandbox.rb
# 3. 运行测试用例
brew test ns-sandbox
# 4. 检查依赖（确保无多余依赖）
brew deps --tree ns-sandbox

 

步骤 4：提交 PR 并遵循模板

 

# 提交代码到自己的Fork
git add Formula/ns-sandbox.rb
git commit -m "ns-sandbox 0.0.1"
git push origin ns-sandbox-0.0.1

 

 

然后在 GitHub 网页端（你的 Fork 仓库）创建 Pull Request：

 

1. 目标仓库选择Homebrew/homebrew-core的main分支；
2. 填写 PR 描述，需包含：
   • 软件功能说明；
   • 测试步骤和结果；
   • 二进制包 / 源码的合法性说明；
    
3. 提交 PR 后，Homebrew 的 CI 会自动运行校验，需关注 CI 结果并修复问题。

 

3.3 审核与合并

 

• 审核周期：通常 1-7 天，取决于 Homebrew 维护者的响应；
• 常见驳回原因：
  1. Formula 脚本不符合规范（如测试用例无效、sha256 错误）；
  2. 软件不够通用（官方优先收录被广泛使用的工具）；
  3. 二进制包未提供源码编译选项；
   
• 合并后：用户可直接brew install ns-sandbox，无需tap。

 

四、关键技巧与避坑指南

 

4.1 计算 sha256 的正确方法

# 方法1：直接下载文件并计算
curl -L https://github.com/navysummer/ns-sandbox/releases/download/v0.0.1/ns-sandbox-0.0.1-x86_64.tar.gz -o temp.tar.gz
shasum -a 256 temp.tar.gz
# 方法2：不保存文件直接计算
curl -L https://github.com/navysummer/ns-sandbox/releases/download/v0.0.1/ns-sandbox-0.0.1-x86_64.tar.gz | shasum -a 256

 

 

 

4.2 Formula 脚本优化建议

 

1. 避免硬编码版本号：优先通过url自动解析（如https://github.com/xxx/xxx/archive/v#{version}.tar.gz）；
2. 测试用例要有效：至少验证--version或--help，避免空测试；
3. 区分源码编译和二进制包：官方仓库更推荐源码编译，个人仓库可灵活使用二进制包；
4. 适配多架构：必须同时支持 x86_64 和 arm64（macOS），否则部分用户无法安装。

 

4.3 常见错误及解决

 

表格

 

错误现象	原因	解决方法
sha256 mismatch	哈希值错误或文件下载不全	重新计算 sha256，确认下载链接有效
brew audit报错desc is too short	描述信息过短	补充软件功能描述（至少 10 个字符）
安装后命令找不到	bin.install路径错误	确认压缩包内可执行文件路径，或指定完整路径bin.install "path/to/ns-sandbox"

 

五、总结

 

• 个人 Tap：适合快速发布、自定义工具，流程简单无审核，用户需手动tap；
• 官方仓库：适合通用型开源工具，曝光度高，但审核严格、流程较长；
• 核心流程：编写 Formula → 校验脚本 → 提交仓库（个人 / 官方 PR） → 验证安装 → 版本维护。

 

通过以上流程，你可以完成从 Formula 编写到包发布的全链路操作，用户可便捷地通过 Homebrew 安装你的ns-sandbox工具。