用 Jekyll 搭建静态博客

环境

• 系统：macOS（13.x 及更新版本步骤相同）
• 架构：Apple Silicon（M 系列）或 Intel

安装 Homebrew

国内源（可选，脚本来自第三方，请自行判断信任度）：

/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

官方安装脚本：

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

安装完成后按终端提示，把 brew 加入 PATH（Apple Silicon 常见为 /opt/homebrew/bin）。

安装 Ruby

推荐用 Homebrew 安装较新的 Ruby（系统自带的 Ruby 往往偏旧，不适合跑新版 Jekyll）：

brew install ruby

将 Homebrew 的 Ruby 放到 PATH 前面（Apple Silicon 示例，Intel 可能是 /usr/local/opt/ruby）：

echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

检查版本：

ruby -v

Bundler 与项目依赖（推荐做法）

有 Gemfile 的站点（例如本仓库）不要依赖「全局 gem install jekyll」来对齐版本。先装 Bundler，再在站点根目录安装依赖：

gem install bundler
cd /path/to/your-site

把 gem 装进项目目录、避免污染系统环境，并与 .gitignore 里的 vendor/bundle/ 一致：

bundle config set --local path 'vendor/bundle'
bundle install

• Gemfile：声明要哪些 gem（Jekyll、主题插件等）。
• Gemfile.lock：锁定具体版本，建议提交到 Git，方便本机与 CI / 他人环境一致。

本仓库的 Gemfile 里示例：jekyll-sass-converter钉在 2.2 系可避免部分环境下 sass-embedded / 本地编译问题；较新的 Ruby 有时需显式加上 logger、csv 等 gem（已在 Gemfile 中）。

选择主题

主题列表可参考 Jekyll Themes。克隆或下载主题仓库后，进入站点根目录，以该目录下的 Gemfile 为准执行 bundle install。

配置

编辑站点根目录下的 _config.yml（文件名是下划线前缀 _config.yml，不是 __config.yml）。

本地预览与构建

在站点根目录：

bundle exec jekyll serve

浏览器访问 http://127.0.0.1:4000（或终端里提示的地址）。serve 适合改稿时自动重建并起本地服务。

只生成静态文件、不启服务（适合检查「干净构建」或对接脚本）：

bundle exec jekyll build

输出目录默认是 _site/（已在 .gitignore 中忽略）。

草稿（_drafts）

bundle exec jekyll serve --drafts 会在本地把 _drafts/ 里的未发布文稿也编进站点，方便预览；去掉 --drafts 则与正式构建行为更接近。

GitHub Pages

若站点托管在 GitHub Pages，线上构建会使用 Pages 支持的 Jekyll / gem 组合（版本以官方文档为准）。本地用 同一套 Gemfile + Gemfile.lock + bundle install，能最大程度减少「本地能编、线上报错」。若线上限定的插件与本地不一致，以 Pages 依赖说明 为准调整 Gemfile。

常见问题（速查）