Homebrew 回退到历史版本：以 zola 0.22.1 为例

Homebrew 回退到历史版本：以 zola 0.22.1 为例

TL;DR: 任何包管理器装“旧版本“都只能是固定快照——apt 装旧包、Homebrew 装历史公式都一样，因为 homebrew/core 里的 zola 永远只有最新版，旧版本天然无法“自动升级“。正确的姿势是：装旧版时用本地 tap 装历史公式，想升级时切回 core 的新公式，两步就回来了。

1. 背景：为什么要回退

zola 0.23.0 是破坏性版本（Tera v2：宏 / 短代码被替换为组件语法）。如果正在使用的主题（如 Ametrine）还没适配 0.23，站点会直接构建失败：

ERROR Failed to render page content of ...
ERROR Reason: error: `load_data`: ... doesn't exist

此时最稳妥的做法是暂时留在 0.22.1，等主题适配后再升级。

2. 为什么不能直接 brew install 旧版本

• homebrew/core 的每个公式只有一个定义，永远指向最新稳定版，没有 zola@0.22.1 这种版本化公式；
• 旧版本公式只存在于 homebrew-core 的 git 历史中，需要“捞“出来；
• 新版 Homebrew 不允许直接安装游离的本地 .rb（brew install ./zola.rb 会报 Homebrew requires formulae to be in a tap）；
• Homebrew 官方推荐的做法是 brew extract 到自己的 tap；本文用手动方式做等价操作，每一步都看得见。

3. 回退：安装 zola 0.22.1

3.1 从 homebrew-core 历史取公式文件

Formula/z/zola.rb 在提交 da70294 时对应 0.22.1（公式里 url 为 v0.22.1.tar.gz，sha256 为 0f59479e…）：

cd ~/Downloads
curl -fsSL -o zola.rb \
  "https://raw.githubusercontent.com/Homebrew/homebrew-core/da702940397d32e261f7e1a577555f7d49929a31/Formula/z/zola.rb"

3.2 放进本地 tap 再安装

brew tap-new --no-git local/zola-old
TAP_DIR="$(brew --prefix)/Library/Taps/local/homebrew-zola-old"
mkdir -p "$TAP_DIR/Formula"
cp ~/Downloads/zola.rb "$TAP_DIR/Formula/zola.rb"
brew install local/zola-old/zola
brew pin zola

验证：

zola --version          # zola 0.22.1
brew list --versions zola

几点说明：

• 公式自带 bottle（arm64 Tahoe/Sequoia/Sonoma 等），匹配的 macOS 直接下载预编译包；其他平台自动走源码编译（会自动装 rust，稍慢）；
• brew pin zola 防止手滑 brew upgrade 把 zola 升走；
• 公式的 url/sha256 指向官方 v0.22.1 源码包，来源可靠。

3.3 备选：完全不管 brew 的临时方案

如果旧版只是临时用一下、之后 brew 永远保持最新版，也可以直接放官方二进制到 ~/.local/bin（这条脱离 brew 管理，不适合“想统一用 brew 管理“的需求）：

cd ~/Downloads
curl -OL https://github.com/getzola/zola/releases/download/v0.22.1/zola-v0.22.1-aarch64-apple-darwin.tar.gz
tar -xzf zola-v0.22.1-aarch64-apple-darwin.tar.gz
mkdir -p ~/.local/bin && mv zola ~/.local/bin/zola

（Intel 机器把文件名换成 zola-v0.22.1-x86_64-apple-darwin.tar.gz）

4. 升级：切回最新版

brew unpin zola
brew untap local/zola-old
brew upgrade zola        # 从 homebrew/core 拿最新版

万一 upgrade 有残留报错：

brew uninstall zola && brew install zola

结论： “升级能力“没有丢，只是它不在旧版本快照里，而在“随时可以切回 core“这个动作里。这正是 Homebrew 官方对“安装旧版本“的标准做法（brew extract 到自己的 tap），手动复制 .rb 只是等价实现。

5. 何时升级：等主题完全支持 0.23.0

zola 0.23.0 属于破坏性版本，主题需要把旧的宏 / 短代码迁移到新组件语法才能兼容。在正在使用的 Zola 主题（如 Ametrine）完全支持 0.23.0 之前，建议保持 0.22.1 不要升级；等主题适配完成、站点用 0.23.x 构建无报错后，再执行第 4 节的升级命令。