下面为你整理一份 《Homebrew Cask 代码审查指南：遵循 Ruby 风格和最佳实践》，适合开发者在提交 Cask PR 或审核他人代码时作为速查表使用。内容清晰、实用、贴合 Homebrew 官方规范（包括 Cask DSL、Rubocop 要求和常见审查问题）。

🧭 Homebrew Cask 代码审查指南

——遵循 Ruby 风格与最佳实践（最新版）

1️⃣ 基本原则：保持 Cask 简洁、可维护、符合 DSL

Homebrew Cask 的设计理念是：简单、明确、最少逻辑。
在代码审查时，所有判断的根本标准是：是否能保证 Cask 可读、可复用、可自动化维护。

2️⃣ Ruby 风格规范（符合 RuboCop + Homebrew Style Guide）

✔ 使用 2 空格缩进

cask "appname" do
  version "1.2.3"
  sha256 "abc..."
end

✔ 使用单引号 '，除非必须使用字符串插值

url "https://example.com/#{version}/App.zip"

✔ 不允许多余空行、尾随空格

Cask 文件通常非常短，结构应紧凑整齐。

✔ 关键字段应按固定顺序排列（官方强制）

顺序如下：

  1. cask "identifier"
  2. version
  3. sha256
  4. url
  5. name
  6. desc
  7. homepage
  8. 其他字段（如: depends_on、app、zap）

示例：

cask "google-chrome" do
  version "131.0.0000"
  sha256 :no_check

  url "https://..."
  name "Google Chrome"
  desc "Fast and secure web browser"
  homepage "https://www.google.com/chrome/"

  app "Google Chrome.app"

  zap trash: "~/Library/Application Support/Google/Chrome"
end

3️⃣ URL、版本、sha256 的最佳实践

✔ 能使用 version 变量的必须使用

避免硬编码：

❌ 不符合规范：

url "https://example.com/app-1.2.3.zip"

✔ 正确写法：

url "https://example.com/app-#{version}.zip"

✔ sha256 必须对应每个 version

除非是升级非常频繁的应用 → 使用 sha256 :no_check
典型场景：Chrome、VS Code、WeChat 更新都是自动刷新。

⚠ 审查规则：

  • 如文件名包含 version → 应提供固定 sha256
  • 如下载 URL 永远指向最新 → 用 :no_check

4️⃣ 不要写 Ruby 逻辑（Homebrew 禁止复杂逻辑）

❌ 不允许添加 Ruby 判断语句，比如：

if MacOS.version > :big_sur
  url ...
end

✔ 改为条件 DSL：

on_catalina :or_older do
  url ...
end

on_big_sur :or_newer do
  url ...
end

5️⃣ app、pkg、installer 的规范

✔ app 使用相对路径（简洁）

❌ 错误

app "/Applications/MyApp.app"

✔ 正确

app "MyApp.app"

✔ 安装 pkg 时必须加卸载逻辑

pkg "Installer.pkg"

uninstall pkgutil: "com.example.pkg"

6️⃣ zap 清理规则（最常见审查点）

✔ 优先写最关键的用户数据路径

如：

  • ~/Library/Application Support/xxx
  • ~/Library/Preferences/xxx.plist
  • ~/Library/Caches/xxx

✔ 不要写系统级路径（会被拒绝）

如：

  • /Library
  • /System

7️⃣ LICENSE、desc、homepage 的规范

✔ desc 要简短、非营销、非夸张

❌ 不允许的描述：

  • “最强大的 AI 工具！”
  • “革命性应用！”

✔ 合规：

desc "AI-based text analysis tool"

8️⃣ 常见审查 Checklist（PR 必备）

🔍 核心检查点：

  • 文件名必须与 Cask token 规范一致（例如：visual-studio-code）
  • 字段顺序正确
  • 使用单引号
  • URL 可稳定下载
  • sha256 对应 version
  • no_check 是否合理
  • app/pkg 安装路径正确
  • zap 项目必须精准、不侵犯系统路径
  • 没有复杂 Ruby 逻辑或函数
  • RuboCop 检查通过

9️⃣ 最佳示例 Cask（官方风格）

cask "example-app" do
  version "1.0.5"
  sha256 "56eb34cd2c21ad..."

  url "https://download.example.com/app-#{version}.dmg"
  name "Example App"
  desc "Simple demo application"
  homepage "https://example.com/app"

  app "Example.app"

  zap trash: [
        "~/Library/Application Support/Example",
        "~/Library/Preferences/com.example.app.plist",
      ]
end