第2章：安装与环境配置
第2章：安装与环境配置
2.1 安装概览
Jekyll 的安装链路为：Ruby → RubyGems → Bundler → Jekyll。
操作系统
└── Ruby（语言运行时）
└── RubyGems（包管理器）
└── Bundler（依赖管理）
└── Jekyll（站点生成器）
各平台安装方式
| 平台 | 推荐方式 | 备注 |
|---|---|---|
| macOS | rbenv + ruby-build | 系统自带 Ruby 版本较旧 |
| Ubuntu/Debian | rbenv 或 apt | apt 版本可能滞后 |
| Windows | RubyInstaller2 + Devkit | 必须带 Devkit |
| Docker | 官方 ruby 镜像 | 见第 13 章 |
2.2 安装 Ruby
macOS（使用 rbenv）
# 1. 安装 rbenv 和 ruby-build
brew install rbenv ruby-build
# 2. 将 rbenv 加入 shell 初始化
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc
# 3. 查看可安装的 Ruby 版本
rbenv install --list | grep "^3."
# 4. 安装 Ruby 3.2.2（推荐版本）
rbenv install 3.2.2
# 5. 设置全局默认版本
rbenv global 3.2.2
# 6. 验证
ruby --version
# => ruby 3.2.2p53 (2023-03-30 revision 15149e8) [arm64-darwin23]
Ubuntu / Debian
# 方法一：使用 rbenv（推荐）
# 安装依赖
sudo apt update
sudo apt install -y build-essential libssl-dev libreadline-dev zlib1g-dev \
libyaml-dev libffi-dev libgdbm-dev
# 安装 rbenv
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
# 配置 shell
echo 'eval "$(~/.rbenv/bin/rbenv init - bash)"' >> ~/.bashrc
source ~/.bashrc
# 安装 Ruby
rbenv install 3.2.2
rbenv global 3.2.2
# 方法二：使用 apt（版本可能较旧）
sudo apt install -y ruby-full build-essential
ruby --version
Windows
1. 访问 https://rubyinstaller.org/
2. 下载 Ruby+Devkit 3.2.x（x64）
3. 运行安装程序，勾选 "Add Ruby executables to your PATH"
4. 安装完成后选择 MSYS2 toolchain（选项 3）
5. 打开新的命令行窗口验证
# PowerShell 验证
ruby --version
gem --version
验证 Ruby 环境
ruby --version # Ruby 版本
gem --version # RubyGems 版本
which ruby # Ruby 路径
注意事项：
- 不要使用系统自带的 Ruby（macOS 和 Linux 的系统 Ruby 版本老旧且权限复杂）
- 始终使用版本管理器（rbenv 或 RVM）管理 Ruby
- Windows 用户务必安装带 Devkit 的版本，否则编译 gem 会失败
2.3 安装 Bundler
Bundler 是 Ruby 的依赖管理工具，类似于 Node.js 的 npm 或 Python 的 pip。
# Bundler 通常随 RubyGems 一起安装
gem install bundler
# 验证
bundler --version
# => Bundler version 2.4.22
配置国内镜像（可选）
# 替换为国内镜像源，加速 gem 下载
gem sources --remove https://rubygems.org/
gem sources --add https://gems.ruby-china.com/
# 验证源
gem sources -l
2.4 安装 Jekyll
方式一：通过 Bundler（推荐）
这是生产项目推荐的方式，使用 Gemfile 管理依赖：
# 创建项目目录
mkdir my-jekyll-site && cd my-jekyll-site
# 创建 Gemfile
cat > Gemfile << 'EOF'
source "https://rubygems.org"
gem "jekyll", "~> 4.3"
gem "jekyll-paginate"
gem "jekyll-sitemap"
gem "jekyll-seo-tag"
EOF
# 安装依赖
bundle install
方式二：直接安装 gem
# 全局安装 Jekyll
gem install jekyll
# 验证
jekyll --version
# => jekyll 4.3.3
常见安装问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
Failed to build gem native extension | 缺少编译工具 | 安装 Xcode Command Line Tools（macOS）或 build-essential（Linux） |
Permission denied | 权限不足 | 使用 rbenv 而非系统 Ruby |
Could not find 'bundler' | Bundler 版本不匹配 | gem install bundler && bundle install |
jekyll: command not found | 未加入 PATH | 重启终端或 rbenv rehash |
2.5 版本管理
使用 Gemfile 锁定版本
# Gemfile
source "https://rubygems.org"
gem "jekyll", "~> 4.3" # 允许 4.3.x 补丁更新
gem "jekyll-paginate", "~> 1.1" # 锁定大版本
# Gemfile.lock 自动生成，锁定精确版本
bundle install
cat Gemfile.lock | grep jekyll
# => jekyll (4.3.3)
Ruby 版本管理工具对比
| 工具 | 说明 | 推荐度 |
|---|---|---|
| rbenv | 轻量、灵活 | ⭐⭐⭐⭐⭐ |
| RVM | 功能全面、较重 | ⭐⭐⭐ |
| asdf | 多语言版本管理 | ⭐⭐⭐⭐ |
| Docker | 完全隔离 | ⭐⭐⭐⭐ |
.ruby-version 文件
# 在项目根目录创建，指定 Ruby 版本
echo "3.2.2" > .ruby-version
echo "jekyll" > .ruby-gemset # RVM 用户
# rbenv 会自动读取此文件
cd my-jekyll-site
ruby --version # 自动切换到 3.2.2
2.6 创建第一个 Jekyll 项目
方法一：jekyll new（推荐新手）
# 创建新站点（带默认主题 minima）
jekyll new my-blog
# 进入目录
cd my-blog
# 目录结构
tree -a -L 2
# ├── Gemfile
# ├── _config.yml
# ├── _posts/
# │ └── 2025-01-01-welcome-to-jekyll.markdown
# ├── about.markdown
# └── index.markdown
# 本地启动
bundle exec jekyll serve
# 访问 http://localhost:4000
方法二：手动创建（推荐进阶用户）
# 创建目录结构
mkdir -p my-site/{_layouts,_includes,_posts,_data,assets/css}
cd my-site
# 创建 Gemfile
cat > Gemfile << 'EOF'
source "https://rubygems.org"
gem "jekyll", "~> 4.3"
group :jekyll_plugins do
gem "jekyll-paginate"
end
EOF
# 创建 _config.yml
cat > _config.yml << 'EOF'
title: My Awesome Site
description: A Jekyll-powered site
baseurl: ""
url: "https://example.com"
markdown: kramdown
permalink: /posts/:title/
paginate: 5
EOF
# 创建首页
cat > index.md << 'EOF'
---
layout: home
---
Welcome to my site!
EOF
# 安装依赖并启动
bundle install
bundle exec jekyll serve --drafts
方法三：使用模板仓库
# 从 GitHub 模板创建
git clone https://github.com/jekyll/minimal.git my-site
cd my-site
rm -rf .git
git init
bundle install
bundle exec jekyll serve
2.7 Jekyll CLI 命令速查
| 命令 | 说明 | 常用参数 |
|---|---|---|
jekyll new | 创建新站点 | --blank（空白项目） |
jekyll build | 构建站点 | --destination、--profile |
jekyll serve | 启动开发服务器 | --livereload、--drafts、--port |
jekyll doctor | 检查配置问题 | — |
jekyll clean | 清理生成文件 | — |
jekyll new-theme | 创建新主题 | — |
# 常用组合
bundle exec jekyll serve --livereload --drafts --port 4001
# 构建并输出到指定目录
bundle exec jekyll build --destination ./public
# 查看构建详情（性能分析）
bundle exec jekyll build --profile
注意事项：
- 使用
bundle exec前缀确保使用 Gemfile 中指定的版本 --livereload会在浏览器中自动刷新--drafts会显示_drafts/目录中的草稿
2.8 .gitignore 配置
# Jekyll 生成文件
_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata
# 依赖
vendor/
# Gemfile.lock（如果是主题/插件开发则提交）
# Gemfile.lock
# 编辑器
.vscode/
.idea/
# OS
.DS_Store
Thumbs.db
业务场景：在团队协作中，Gemfile.lock 应该提交到 Git，以确保所有成员使用相同的依赖版本。但如果是开发 Jekyll 主题/插件，则不提交，以测试兼容性。
2.9 IDE / 编辑器配置
VS Code 推荐插件
| 插件 | 用途 |
|---|---|
| Liquid by panoply | Liquid 语法高亮 |
| Jekyll Snippets | Jekyll 代码片段 |
| Markdown All in One | Markdown 增强 |
| YAML | YAML 语法检查 |
VS Code 工作区配置
// .vscode/settings.json
{
"files.associations": {
"*.md": "markdown",
"*.html": "liquid-html"
},
"emmet.includeLanguages": {
"liquid-html": "html"
}
}
2.10 扩展阅读
本章小结
| 步骤 | 命令/工具 | 说明 |
|---|---|---|
| 安装 Ruby | rbenv / RubyInstaller | 版本 3.1+ |
| 安装 Bundler | gem install bundler | 依赖管理 |
| 安装 Jekyll | gem install jekyll 或 Gemfile | 推荐 Gemfile |
| 创建项目 | jekyll new 或手动 | 推荐手动以理解结构 |
| 启动服务 | bundle exec jekyll serve | 访问 localhost:4000 |
下一章：项目结构与基础