Homebrew 构建环境实战：superenv、env :std 与自定义 Requirement 如何正确应对非 Homebrew 依赖

Homebrew 的 formula 默认在 superenv 中构建，这会过滤构建者机器的用户环境、只暴露声明过的依赖，从而保证不同维护者、不同 CI 上构建出一致的结果。本文基于仓库文档 Building-Against-Non-Homebrew-Dependencies.md 展开，结合 Library/Homebrew 下的源码，讲清三件事：homebrew/core 对构建依赖的硬性约束、第三方 tap 在必须依赖私有/本地/非 Homebrew 软件时该如何声明 env :std 或自定义 Requirement，以及如何在干净环境中验证这些约束。读完你可以判断自己的 formula 应该走哪条路径，并知道每条路径背后的实现机制。

superenv：构建不依赖用户环境的原理

文档开宗明义：Homebrew formula 通常在 superenv 中构建，它过滤用户环境并只暴露已声明的依赖。这使构建可复现，防止某位贡献者机器上一个未声明的程序或库悄悄改变构建结果。

源码印证了这一点。构建入口 build.rb 在安装阶段首先根据环境模式分叉：

# Library/Homebrew/build.rb#L94-L105（节选）
if superenv?(args.env)
  superenv = ENV
  superenv.keg_only_deps = keg_only_deps
  superenv.deps = formula_deps
  superenv.run_time_deps = run_time_deps
  ENV.setup_build_environment(
    formula:, cc: args.cc, build_bottle: args.build_bottle?, ...
  )

其中 superenv? 定义在 extend/kernel.rb：当 env == "std" 时直接返回 false，否则要求 Superenv.bin 存在。也就是说 env :std 是显式退出 superenv 的唯一入口。

在 superenv 模式下，PATH、PKG_CONFIG_PATH 等搜索路径由 superenv 按 formula_deps 生成；而进入 std 模式的 else 分支（build.rb）则会退化为“手动把 keg-only 依赖逐个 prepend_path 进 PATH/PKG_CONFIG_PATH/ACLOCAL_PATH/CMAKE_PREFIX_PATH”的旧式做法。此外，setup_build_environment 会先执行 reset，删除一组固定的敏感变量，见 extend/ENV/shared.rb：

SANITIZED_VARS = %w[
  CDPATH CLICOLOR_FORCE
  CPATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH OBJC_INCLUDE_PATH
  CC CXX OBJC OBJCXX CPP MAKE LD LDSHARED
  CFLAGS CXXFLAGS OBJCFLAGS OBJCXXFLAGS LDFLAGS CPPFLAGS
  MACOSX_DEPLOYMENT_TARGET SDKROOT DEVELOPER_DIR
  CMAKE_PREFIX_PATH CMAKE_INCLUDE_PATH CMAKE_FRAMEWORK_PATH
  GOBIN GOPATH GOROOT PERL_MB_OPT PERL_MM_OPT
  LIBRARY_PATH LD_LIBRARY_PATH LD_PRELOAD LD_RUN_PATH
  RUSTFLAGS
].freeze

从这段变量清单可以确认：无论哪种模式，CC/CFLAGS/LIBRARY_PATH 等由构建者环境带来的“污染”都会被剥离后再按公式重新设置——这正是“可复现构建”的底层保障。构建完成后还可用 brew --env 查看最终生效的环境变量，其实现见 cmd/--env.rb，输出变量集合由 build_environment.rb 中的 KEYS 白名单（PATH、CFLAGS、PKG_CONFIG_PATH、CMAKE_PREFIX_PATH 等）约束。

homebrew/core 的硬约束：一切依赖必须声明

文档对 homebrew/core 的规则是明确的：

• core 中的 formula 必须使用已声明的 Homebrew 依赖或受支持的平台设施；
• 当存在受支持的 Homebrew 依赖作为替代时，不能依赖用户 PATH 上的任意可执行文件、库或语言运行时；
• 普通依赖一律用 depends_on 声明；对存在默认 formula 的需求，使用默认 formula；
• 不得在 homebrew/core 中使用 env :std 来暴露未声明的用户软件。

这一约束在实现层是被结构性强制的：core formula 走 superenv 分支，PATH 只包含 Homebrew prefix 和声明依赖的 keg，用户 PATH 中的程序对构建脚本不可见（superenv 的 shim 机制位于 shims/super 目录）。若某个程序确实存在未声明依赖，构建在干净环境（如 CI）中会直接失败，而不是“在我机器上碰巧能过”——文档中“防止未声明软件悄悄改变结果”说的就是这种失败模式。

实践中遇到“构建需要某运行时/工具”时的正确做法，仍然是回到声明式路径：depends_on "nodejs"、depends_on "openssl@3" 等，让依赖解析和链接路径全部来自 Homebrew 自身。

第三方 tap：必须构建于非 Homebrew 依赖之上时

当软件必须构建于私有、本地管理的或非 Homebrew 的依赖之上时，文档给出的策略是：把 formula 维护在你自己的 tap 里（参考 docs/How-to-Create-and-Maintain-a-Tap.md），并在 tap 中记录外部依赖、支持的版本以及用户需要做的准备工作。tap 拥有两条可选路径：

路径一：env :std

外部 tap 允许使用 env :std，前提是“暴露用户正常环境”是该 formula 契约的有意组成部分。文档同时警告：这会降低可复现性，并可能导致 bottle 不再适用（bottle 的构建产物可能绑定特定机器的本地库），因此只要可能就优先使用声明式依赖。

env :std 的生效链路在源码中可以完整追踪：formula 中的 env :std 会写入 BuildEnvironment（见 build_environment.rb 的 std? 判断），安装时 FormulaInstaller 据此把构建参数改为 --env=std：

# Library/Homebrew/formula_installer.rb#L1131-L1135（节选）
if @env.present?
  args << "--env=#{@env}"
elsif formula.env.std? || formula.deps.select(&:build?).any? { |d| d.name == "scons" }
  args << "--env=std"
end

随后 build.rb 的 else 分支按 std 模式搭建环境。注意这里的 elsif 条件：即便没有显式 env :std，带 build 依赖的 scons 也会自动走 std 模式——从源码结构看，这是为了兼容需要完整用户环境的老式构建系统。

路径二：自定义 Requirement 精确校验外部软件

当能够精确验证外部软件时，tap 还可以定义自定义 Requirement，而不是笼统地放行整个用户环境。文档要求：Requirement 应当说明如何满足它，且不应接受 formula 未经验证的版本或安装方式。

Requirement 基类位于 Library/Homebrew/requirement.rb，核心机制有三处值得细看：

1. 满足判定走 satisfy DSL。satisfied?（requirement.rb#L93-L106）读取类级 satisfy 配置并求值，不再支持直接覆写 satisfied?。Satisfier 支持 build_env: true 选项，让满足性检查直接在构建环境中进行，避免“检查环境和构建环境不一致”的假阳性。

2. 不满足时的报错即文档。message 方法（requirement.rb#L64-L81）会根据类上的 cask / download 声明，自动给出 brew install --cask xxx 或下载地址——这正是文档所说“requirement 应解释如何满足它”的实现支撑。

3. 在 superenv 下也能找到外部可执行文件。Requirement 内部的 which 默认搜索 ORIGINAL_PATHS（requirement.rb#L206-L209），即构建开始前的原始 PATH；当 satisfy 块返回的 Pathname 指向外部安装位置时，modify_build_environment（requirement.rb#L135-L150）会把其父目录临时 prepend 进构建 PATH，让 satisfy { which("external-tool") } 这类写法即使在 superenv 下也能工作。

Homebrew 自带的几个需求实现可作为模板参考，均位于 Library/Homebrew/requirements 目录：arch_requirement.rb（CPU 架构）、linux_requirement.rb、macos_requirement.rb（macOS 版本，如 depends_on :macos => :ventura）、xcode_requirement.rb（Xcode 版本校验）。一个自定义 Requirement 的典型形态是：class FooRequirement < Requirement，用 satisfy { ... 版本/路径校验 ... } 声明约束，fatal true 使其未满足时构建直接失败，并可选声明 cask/download 让报错信息自解释。

两条路径的选择可以概括为：env :std 是把整个用户环境交给 formula，代价是牺牲可复现性和 bottle 可用性；自定义 Requirement 只暴露经过验证的那一个外部软件，是更精细、更接近 core 精神的方案。

在干净环境中验证：audit 与测试

文档的收尾要求值得单独强调：tap 应当在干净环境中运行 formula 的 audit 与测试，确保未声明的软件没有意外成为构建的隐性必需项。

这一要求针对的正是两类路径共同的失效模式：维护者本机装有外部工具 A，formula 从未声明它，但构建脚本实际调用了它；在维护者机器上构建成功，在干净环境（干净 CI 或清空的 shell）里失败。验证手段与文档主题直接相关：

• 用 brew sh --env=std（实现见 dev-cmd/sh.rb）进入与构建一致的环境，手动跑一遍 install 块中的命令，确认外部依赖是否真的被触达；
• 用 brew --env <formula> 对比 superenv 与 std 两种模式下实际暴露的 PATH、PKG_CONFIG_PATH 等（cmd/--env.rb），确认声明依赖是否覆盖了构建脚本实际使用的一切；
• 在最小化 shell 环境中运行 brew test/audit 流程，复现“无本地环境”的构建者视角。

要点小结

场景	文档给出的做法	源码依据
homebrew/core formula	只用 depends_on 声明的 Homebrew 依赖或平台设施，禁用 env :std	build.rb 的 superenv 分支、extend/ENV/shared.rb 的环境变量清洗
第三方 tap 必须依赖外部软件	维护在自有 tap，记录外部依赖、版本与用户准备步骤	docs/How-to-Create-and-Maintain-a-Tap.md
有意暴露用户环境	显式 env :std，接受可复现性下降与 bottle 受限	formula_installer.rb、extend/kernel.rb
可精确校验的外部软件	自定义 Requirement，说明满足方式，不放过未测试版本	requirement.rb 的 satisfy/message/modify_build_environment
交付前验证	在干净环境跑 audit 与测试，防止未声明软件变成必需项	结合 brew sh（dev-cmd/sh.rb）与 brew --env 核对

判断顺序很简单：先问“有没有 Homebrew 依赖或平台设施可以替代”，有则走 depends_on；没有且 tap 无法精确校验时，用 env :std 并在文档中声明契约；能够精确校验时，优先写自定义 Requirement，把对外部世界的开口收敛到最小。