Jekyll 静态站点完全教程 / 第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

下一章：项目结构与基础