Jekyll GitHub Pages 5 步搭建博客 - 2026 整站源码实战指南，含 5 大关键点 + 自查清单 + 速查手册，新手必学。
# Jekyll + GitHub Pages 5 步搭建博客
Jekyll 是 GitHub Pages 原生支持的静态博客，Ruby 编写。GitHub Pages 直接认 Jekyll 仓库，push 源码就部署完成。本文 5 步搞定 Jekyll + GitHub Pages。
第 1 招：判断标准（用 Jekyll）
3 个场景 Jekyll 是首选：
1. GitHub Pages 用户 — Jekyll 是原生支持
2. 不想配置 CI/CD — GitHub 自动构建
3. 博客文章 < 500 — Jekyll 编译速度够用
Jekyll vs 其他：
| 博客 | 编译 1000 篇 | GitHub Pages 原生 |
|---|---|---|
| Jekyll | 60 秒 | ✓ |
| Hexo | 20 秒 | ✗（需 CI） |
| Hugo | 5 秒 | ✗（需 CI） |
第 2 招：避坑点（Ruby 版本 + 主题）
1. Ruby 版本：必须 3.0+（用 rbenv / rvm）
2. 依赖安装：用 `bundle install`，不要用 `gem install`
3. 主题装在 `_layouts/`：不是 `_themes/`
4. 中文文件名：必须 `encoding: utf-8`
第 3 招：关键参数（5 步流程）
| 步骤 | 命令 |
|---|---|
| 1. 创建仓库 | `yourname.github.io` |
| 2. clone 到本地 | `git clone` |
| 3. 安装依赖 | `bundle install` |
| 4. 本地预览 | `bundle exec jekyll serve` |
| 5. 推送部署 | `git push origin main` |
第 4 招：易踩坑（部署 + 配置）
```yaml
# _config.yml 关键配置
title: 我的 Jekyll 博客
description: Jekyll + GitHub Pages
url: 'https://yourname.github.io'
baseurl: '' # 子路径填 '/blog'
markdown: kramdown
permalink: /:year/:month/:title/
```
4 个易踩坑：
1. Gemfile 必须 — 不写就 `bundle install` 报错
2. .gitignore 必须 — 忽略 `_site/` 和 `.bundle/`
3. 主题文件 — `_layouts/` 和 `_includes/` 必须在仓库
4. 推送分支 — GitHub Pages 默认 `main`（之前是 `master`）
第 5 招：场景建议（5 步流程）
| 步骤 | 工具 |
|---|---|
| 1. 准备 | 安装 Ruby 3.0+ |
| 2. 安装 Jekyll | `gem install jekyll bundler` |
| 3. 创建博客 | `jekyll new myblog` |
| 4. 本地预览 | `bundle exec jekyll serve` |
| 5. 部署 | 推到 `yourname.github.io` |
下载包里有什么
[Jekyll + GitHub Pages 5 步速查 PDF]：5 页速查
[Jekyll附件-启动脚本.bat]：一键启动
[部署指南.txt]：完整部署步骤
[配置模板.txt]：`_config.yml` 模板
[常见报错.txt]：5 大常见报错解决
为什么必须下载
Jekyll 安装坑多（Ruby 版本、依赖、跨平台），下载包提供 Windows 启动脚本 + 完整部署指南 + 5 大报错解决方案。按步骤执行 5 分钟跑通 Jekyll。
本文配套下载包按 4 件套打包：PDF 速查 + 启动脚本 + 部署指南 + 配置模板 + 常见报错。打开即用。
