最近重置了 Mac 系统，需要重新配置 Ruby 和 Jekyll 环境来运行我的静态博客。相比于直接使用系统 Ruby，这次选择了更优雅的 rbenv 进行版本管理。整个过程遇到不少“坑”，特此记录以备忘，希望这篇记录也能帮你绕开这些坑。

核心思路：为何使用 rbenv？

rbenv 将 Ruby 环境和所有 Gem 安装在你的用户目录下，实现完全的隔离管理，是当前 Ruby 社区推荐的最佳实践。

第一步：安装和基础配置

# 1. 通过 Homebrew 安装 rbenv 和 ruby-build（用来编译安装 Ruby）
brew install rbenv ruby-build

# 2. 初始化 rbenv，并按照提示把下面这行加到 ~/.zshrc 里
rbenv init
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc # 让配置生效

# 3. 安装一个稳定的 Ruby 版本（这里选了 3.4.4，因为我系统显示最新的就是3.4.4）
rbenv install --list-all
rbenv install 3.4.4
rbenv global 3.4.4 # 设为默认版本
rbenv rehash # 重要：重建命令链接

# 4. 验证一下，确保 ruby 和 gem 命令指向的是 rbenv 安装的版本
which ruby # 应该显示 ~/.rbenv/shims/ruby
which gem  # 应该显示 ~/.rbenv/shims/gem
ruby -v    # 应该显示 3.4.4

# 5. 现在可以安全安装 Jekyll 了
gem install jekyll

第二步：在博客项目中启动，问题接踵而至

本以为万事大吉，在博客目录下输入 jekyll s，结果错误连环出现。

第一个坑：项目依赖 vs 全局安装

直接报错，说项目 Gemfile 里锁定的 Jekyll 版本（4.3.2）和我刚全局安装的版本（4.4.1）对不上。

解决：在项目目录下，让 Bundler 根据 Gemfile 重新安装所有依赖。

bundle install

第二个坑：架构冲突，编译失败

运行 bundle install 时，在编译 nokogiri 时卡住了，报错提示在找 x86_64 的库，但我的是 ARM 芯片（Apple Silicon）。

ld: warning: ignoring file '/opt/homebrew/Cellar/xz/5.8.1/lib/liblzma.dylib': found architecture 'arm64', required architecture 'x86_64'

原因：我的机器上好像混用了两个 Homebrew（Intel 和 ARM 版）。默认的 brew 命令指向了 Intel 版本。

解决：

1. 先检查当前 brew 路径：which brew。我的是 /usr/local/bin/brew（Intel版）。
2. 切换回 ARM 版的 Homebrew：

   eval $(/opt/homebrew/bin/brew shellenv)
   

3. 之后再重新 bundle install，编译就通过了。

第三个坑：public_suffix 版本激活冲突

再次尝试 jekyll s，又出现新错误：全局的 public_suffix (7.0.2) 和项目需要的 (5.0.4) 冲突。

解决：改用 bundle exec 命令，严格使用项目 Gemfile.lock 里锁定的版本。

bundle exec jekyll s

第四个坑：Ruby 3.4 的“惊喜”——标准库缺失

以为终于行了，结果连续报错：

• cannot load such file -- csv
• cannot load such file -- base64
• cannot load such file -- bigdecimal

原因：Ruby 3.4 开始，像 csv、base64、bigdecimal、zlib、openssl 这些以前默认就有的标准库，现在需要单独作为 gem 安装了。而我的博客用的 Jekyll 版本比较旧，还依赖它们。

解决：在项目目录下，把这些缺失的库一次性补上。

bundle add csv base64 webrick bigdecimal zlib openssl

最后，终于跑起来了！

完成以上所有步骤后，再次运行：

bundle exec jekyll s

熟悉的启动信息终于出现了，浏览器打开 http://localhost:4000，博客本地预览恢复正常。

几点心得

1. rbenv 不错：虽然一开始配置多点步骤，但彻底告别了权限混乱，值。
2. bundle exec 是护身符：在项目目录下运行任何 gem 相关的命令，都习惯性加上它，能避免很多奇怪的版本冲突。
3. 注意 Homebrew 架构：尤其是换过芯片的 Mac，确保用的是对应版本的 brew，能省去很多编译麻烦。
4. Ruby 3.4+ 的用户：如果跑老项目，记得缺啥标准库就用 bundle add 装啥，csv、base64、bigdecimal、zlib、openssl 这几个是常客。