Jekyll + Ruby + Nokogiri 安装指南 (macOS M 系列)

本文档指导在 macOS (M1/M2/M3/M4) 上通过 rbenv 安装 Ruby，并在 Ruby 环境中顺利安装 Jekyll 与 Nokogiri。

1. 环境准备

1.1 安装 Homebrew

如果尚未安装 Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1.2 安装必要依赖

brew install rbenv ruby-build openssl@3 libyaml libffi
brew install node  # 可选：用于 Jekyll 扩展功能
brew install git

2. 配置 rbenv

2.1 初始化 rbenv

在 ~/.zshrc 或 ~/.bash_profile 中添加：

export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

然后重新加载 shell：

source ~/.zshrc

2.2 验证 rbenv

rbenv -v
ruby-build -v

3. 安装 Ruby

Apple Silicon 推荐安装最新的 Ruby 3.x。

# 安装 Ruby 3.3.2
RUBY_CFLAGS="-O2 -march=arm64" rbenv install 3.3.2

# 设置全局 Ruby
rbenv global 3.3.2

# 验证 Ruby
ruby -v

⚠️ 如果下载/编译慢，可以使用镜像：

RUBY_BUILD_MIRROR_URL=https://cache.ruby-lang.org/ ruby-build 3.3.2 ~/.rbenv/versions/3.3.2

4. 安装 Bundler

gem install bundler
rbenv rehash

5. 安装 Jekyll 与依赖

5.1 安装 Jekyll

gem install jekyll
rbenv rehash
jekyll -v

5.2 安装 Nokogiri (解决 M 系列架构问题)

gem install nokogiri -- --use-system-libraries \
  --with-xml2-config=$(brew --prefix libxml2)/bin/xml2-config \
  --with-xslt-config=$(brew --prefix libxslt)/bin/xslt-config
rbenv rehash

6. 创建和启动 Jekyll 项目

jekyll new my_blog
cd my_blog
bundle install
bundle exec jekyll serve --livereload

访问 http://localhost:4000 查看效果。

7. 常见问题与解决方案

问题	解决方案
`LoadError: nokogiri/nokogiri`	删除旧 gem: `sudo gem uninstall nokogiri`，然后用上文方式安装。
编译慢 / 卡住	加 `RUBY_CFLAGS="-O2 -march=arm64"` 并确保 Homebrew 的 openssl@3 已安装。
权限问题 (`Gem::FilePermissionError`)	不要用系统 Ruby，必须用 rbenv 安装的 Ruby。

8. 验证环境

ruby -v          # 3.3.2
gem list         # bundler, nokogiri, jekyll
jekyll -v        # Jekyll 版本

9. 附加

如果是 M4 架构（属于 Apple Silicon 系列）

在 Apple Silicon（M1/M2/M4）上，系统自带 Ruby 往往是 x86_64 架构，而 nokogiri 需要编译 C 扩展，导致架构不匹配。直接用 sudo gem install 是行不通的。

最稳妥方案：安装一个原生 arm64 Ruby，再在它上面安装 Jekyll 与 Nokogiri。

步骤如下（用 rbenv 举例）：

# 1. 安装 rbenv 和 ruby-build
brew install rbenv ruby-build

# 2. 初始化 rbenv（加到 shell 配置里）
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

# 3. 安装最新稳定版 Ruby（arm64 原生）
rbenv install 3.3.2
rbenv global 3.3.2

# 4. 更新 gem
gem update --system

# 5. 安装 Nokogiri（使用系统库加 Homebrew 提供的 libxml2）
brew install libxml2 libxslt
gem install nokogiri -- --use-system-libraries \
    --with-xml2-include=$(brew --prefix libxml2)/include/libxml2 \
    --with-xml2-lib=$(brew --prefix libxml2)/lib \
    --with-xslt-include=$(brew --prefix libxslt)/include \
    --with-xslt-lib=$(brew --prefix libxslt)/lib

# 6. 安装 Jekyll
gem install jekyll bundler

这样就能在 M4 Mac 上顺利运行 jekyll serve，不会再遇到 x86_64 与 arm64 的冲突。