Orion
4a97c1cb4a
在引导脚本的 PATH 变量中增加 Homebrew 的 sbin 路径，以解决常见的路径缺失 警告。同步更新 README 文档，增加了关于 brew doctor 警告的处理指南，包括 如何处理废弃的 Cask 以及手动配置 PATH 的详细步骤。
236 lines
6.1 KiB
Markdown
236 lines
6.1 KiB
Markdown
# Homebrew Upgrade Manager
|
||
|
||
`brew-upgrade-manager.sh` 是一个 macOS Homebrew 升级脚本，用于按固定流程更新 Homebrew、检查环境、升级 Formula 和 Cask，并清理旧版本与缓存。
|
||
|
||
仓库中同时提供 `brew-upgrade-manager-bootstrap.sh`。它是启动器：先从远端下载最新版 `brew-upgrade-manager.sh` 到临时文件，准备 sudo 凭据，执行后自动删除临时文件。适合在本机配置成 `brewup` 命令长期使用。
|
||
|
||
## 文件说明
|
||
|
||
| 文件 | 作用 |
|
||
| --- | --- |
|
||
| `brew-upgrade-manager.sh` | 真正执行 Homebrew 升级流程的主脚本 |
|
||
| `brew-upgrade-manager-bootstrap.sh` | 远程启动器，下载主脚本、执行、清理临时文件 |
|
||
|
||
## 功能
|
||
|
||
- 执行 `brew update -v` 更新 Homebrew 仓库。
|
||
- 执行 `brew doctor` 做健康检查；发现问题时给出警告，但不中断后续流程。
|
||
- 检查并安装 `buo/cask-upgrade` tap，保留 GUI 应用升级相关兼容能力。
|
||
- 使用 `brew upgrade --formula` 升级命令行工具。
|
||
- 使用 `brew upgrade --cask --greedy --force` 强制升级 GUI 应用。
|
||
- 执行 `brew cleanup --prune=all` 清理旧版本和缓存。
|
||
- 支持固定终端宽度，避免非交互环境下输出宽度异常。
|
||
- 启动器支持通过 macOS Keychain 保存并读取 sudo 密码，用于 `sudo -A -v` 预刷新 sudo 凭据。
|
||
|
||
## 依赖
|
||
|
||
- macOS
|
||
- Homebrew
|
||
- Bash
|
||
- `curl`
|
||
- macOS Keychain 工具 `/usr/bin/security`，仅启动器需要
|
||
|
||
可先检查：
|
||
|
||
```bash
|
||
brew --version
|
||
curl --version
|
||
```
|
||
|
||
## 推荐用法：配置 `brewup`
|
||
|
||
把下面函数加入 `~/.zshrc`：
|
||
|
||
```bash
|
||
brewup() {
|
||
curl -fsSL https://git.orionc.me/orion/script/raw/branch/main/homebrew/brew-upgrade-manager-bootstrap.sh | bash -s -- "$@"
|
||
}
|
||
```
|
||
|
||
重新加载 shell 配置：
|
||
|
||
```bash
|
||
source ~/.zshrc
|
||
```
|
||
|
||
之后直接运行：
|
||
|
||
```bash
|
||
brewup
|
||
```
|
||
|
||
传递参数时也可以正常转发给主脚本：
|
||
|
||
```bash
|
||
brewup --width 160
|
||
```
|
||
|
||
如果更偏好 alias，也可以使用：
|
||
|
||
```bash
|
||
alias brewup='curl -fsSL https://git.orionc.me/orion/script/raw/branch/main/homebrew/brew-upgrade-manager-bootstrap.sh | bash -s --'
|
||
```
|
||
|
||
函数版对参数转发更直观，推荐优先使用函数。
|
||
|
||
## 本地运行主脚本
|
||
|
||
如果已经 clone 了本仓库，也可以直接运行主脚本：
|
||
|
||
```bash
|
||
cd homebrew
|
||
chmod +x brew-upgrade-manager.sh
|
||
./brew-upgrade-manager.sh
|
||
```
|
||
|
||
指定固定终端宽度：
|
||
|
||
```bash
|
||
./brew-upgrade-manager.sh --width 130
|
||
./brew-upgrade-manager.sh --width=130
|
||
```
|
||
|
||
也可以通过环境变量指定：
|
||
|
||
```bash
|
||
HB_TERMINAL_WIDTH=130 ./brew-upgrade-manager.sh
|
||
```
|
||
|
||
优先级为：命令行 `--width` 高于 `HB_TERMINAL_WIDTH`。两者都不设置时，脚本会读取当前终端宽度；无法读取时默认使用 `130`。
|
||
|
||
## 启动器行为
|
||
|
||
`brew-upgrade-manager-bootstrap.sh` 会执行以下操作：
|
||
|
||
1. 创建临时文件。
|
||
2. 生成临时 `SUDO_ASKPASS` 脚本。
|
||
3. 从 macOS Keychain 读取 sudo 密码；首次使用时提示输入一次并保存到 Keychain。
|
||
4. 执行 `sudo -A -v` 刷新 sudo 凭据。
|
||
5. 下载远端 `brew-upgrade-manager.sh`。
|
||
6. 可选校验 SHA256。
|
||
7. 使用 `bash "$TEMP" "$@"` 执行主脚本并转发参数。
|
||
8. 退出时删除临时脚本文件。
|
||
|
||
默认 Keychain service 名称为：
|
||
|
||
```bash
|
||
brewup-sudo-password
|
||
```
|
||
|
||
如需删除已保存的 sudo 密码：
|
||
|
||
```bash
|
||
security delete-generic-password -a "$USER" -s brewup-sudo-password
|
||
```
|
||
|
||
如需使用自定义 Keychain service：
|
||
|
||
```bash
|
||
BREWUP_KEYCHAIN_SERVICE=my-brewup-password brewup
|
||
```
|
||
|
||
## SHA256 校验
|
||
|
||
启动器支持通过 `BREWUP_SHA256` 校验下载到的主脚本。先计算远端脚本当前哈希：
|
||
|
||
```bash
|
||
curl -fsSL https://git.orionc.me/orion/script/raw/branch/main/homebrew/brew-upgrade-manager.sh | shasum -a 256
|
||
```
|
||
|
||
运行时指定：
|
||
|
||
```bash
|
||
BREWUP_SHA256=<sha256> brewup
|
||
```
|
||
|
||
如果哈希不匹配，启动器会停止执行。
|
||
|
||
## 调试
|
||
|
||
查看启动器下载到的主脚本首行：
|
||
|
||
```bash
|
||
BREWUP_DEBUG=1 brewup
|
||
```
|
||
|
||
## 执行流程
|
||
|
||
主脚本执行顺序：
|
||
|
||
1. `brew update -v`
|
||
2. `brew doctor`
|
||
3. 检查 `buo/cask-upgrade` tap
|
||
4. `brew upgrade --formula`
|
||
5. `brew upgrade --cask --greedy --force`
|
||
6. `brew cleanup --prune=all`
|
||
|
||
## 常见问题
|
||
|
||
### 首次运行为什么要输入 sudo 密码？
|
||
|
||
启动器会把 sudo 密码保存到当前用户的 macOS Keychain，后续通过临时 `SUDO_ASKPASS` 脚本读取，用于刷新 sudo 凭据。密码不会写入仓库，也不会写入主脚本。
|
||
|
||
### Keychain 中的 sudo 密码不可用
|
||
|
||
通常是系统密码已变更，或 Keychain 条目内容不再正确。删除后重新运行即可：
|
||
|
||
```bash
|
||
security delete-generic-password -a "$USER" -s brewup-sudo-password
|
||
brewup
|
||
```
|
||
|
||
### 表格或输出宽度异常
|
||
|
||
指定固定宽度：
|
||
|
||
```bash
|
||
brewup --width 130
|
||
```
|
||
|
||
或：
|
||
|
||
```bash
|
||
HB_TERMINAL_WIDTH=130 brewup
|
||
```
|
||
|
||
### `brew tap buo/cask-upgrade` 失败
|
||
|
||
通常是网络、Homebrew tap 或权限问题。先确认 Homebrew 可正常访问 GitHub 和对应 tap。
|
||
|
||
### `brew doctor` 提示 warning
|
||
|
||
`brew doctor` 的 warning 不一定代表脚本失败。脚本会继续执行，并打印：
|
||
|
||
```bash
|
||
Warning: 'brew doctor' detected issues. Manual review and resolution are recommended.
|
||
```
|
||
|
||
常见 warning 处理方式：
|
||
|
||
- `Some installed casks are deprecated or disabled`：说明某些 Cask 已废弃或被禁用，例如 `ayugram`。可以自行寻找替代应用，或不再需要时卸载：
|
||
|
||
```bash
|
||
brew uninstall --cask ayugram
|
||
```
|
||
|
||
- `Homebrew's "sbin" was not found in your PATH`：说明 shell 的 PATH 缺少 Homebrew 的 sbin 目录。Apple Silicon Mac 通常可加入：
|
||
|
||
```bash
|
||
echo 'export PATH="/opt/homebrew/sbin:$PATH"' >> ~/.zshrc
|
||
source ~/.zshrc
|
||
```
|
||
|
||
Intel Mac 或 `/usr/local` 安装的 Homebrew 可加入：
|
||
|
||
```bash
|
||
echo 'export PATH="/usr/local/sbin:$PATH"' >> ~/.zshrc
|
||
source ~/.zshrc
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- 脚本启用了 `set -e` 和 `set -o pipefail`，关键命令失败会终止流程。
|
||
- `brew upgrade --cask --greedy --force` 可能升级或替换已安装 GUI 应用，建议先保存重要工作。
|
||
- 远程启动器属于“下载后执行”模式，只应从可信仓库使用。
|
||
- 在公司设备或受管 macOS 上运行前，先确认 Homebrew、Cask、Keychain 和 sudo 策略允许自动升级。
|