homebrew 是 macos 构建可复用、可验证、可迁移开发环境的核心基础设施，关键在于“管得住”而非“装得快”；其需严格适配芯片架构（apple silicon 为 /opt/homebrew，intel 为 /usr/local），并区分 formula（命令行工具）与 cask（gui 应用），配合 brewfile 实现环境一键重建及国内镜像源加速。
Homebrew 不是“装软件的快捷方式”，而是 macOS 上构建可复用、可验证、可迁移的开发环境的核心基础设施。关键不在“装得快”，而在“管得住”——版本可控、依赖明确、状态可查、多机一致。
确保 Homebrew 本身适配你的芯片架构
这是后续一切稳定性的前提。M1/M2/M3 芯片必须使用 ARM 原生版 Homebrew，路径为 /opt/homebrew；Intel 芯片则为 /usr/local。错误路径会导致命令找不到、包冲突或性能下降。
- 运行 which brew，确认输出是
/opt/homebrew/bin/brew（Apple Silicon）或/usr/local/bin/brew（Intel） - 若不匹配，先卸载旧版：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)" - 再用官方脚本重装，并确保 shell 配置文件（如
~/.zshrc）已加载：echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc && source ~/.zshrc
用 Brewfile 实现环境一键重建
Brewfile 是 Homebrew 的“环境快照”，相当于整个 CLI 工具链的配置清单。它让新机器、新同事、CI 环境能在 1 分钟内获得完全一致的软件栈。
- 生成当前环境的 Brewfile：
brew bundle dump --file=Brewfile - 标准模板建议包含三类内容：基础工具（
git、curl、jq）、开发依赖（python、node、docker）、GUI 应用（visual-studio-code、google-chrome，需用cask声明） - 在新机器上执行：
brew bundle install，自动安装缺失项、升级过时项、跳过已存在项
区分 Formula 与 Cask，避免混用陷阱
Homebrew 管理两类软件：命令行工具（Formula）和图形界面应用（Cask）。二者安装路径、更新机制、依赖处理完全不同，混用会引发权限异常或更新失败。
- 命令行工具走
brew install python，安装到/opt/homebrew/Cellar/，由 Homebrew 统一管理符号链接 - GUI 应用必须用
brew install --cask visual-studio-code，实际下载 .app 包并移至/Applications，不参与常规brew upgrade - 检查已装项目类型：
brew list --versions显示 Formula，brew list --casks显示 Cask
设置国内镜像源，提升稳定性与速度
默认 GitHub 源在国内常出现超时、校验失败（Checksum mismatch）等问题。切换为中科大或阿里云镜像后，brew update 从数分钟缩短至 10 秒内。
- 临时生效（推荐首次安装后立即执行）：
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"和export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git" - 永久生效：将上述两行写入
~/.zshrc，再执行source ~/.zshrc - 验证是否生效：
brew tap-info homebrew/core中的 URL 应含mirrors.ustc.edu.cn
