Jekyll + GitHub Pages 零成本搭建个人博客的 5 步实操指南：含配置模板 + 3 套主题 + 启动脚本 + 报错解决 + 部署文档，新手 1-2 小时就能上线。
Jekyll 博客搭建 5 步：GitHub Pages 免费托管指南
如果你想搭一个属于自己的博客，但又不想折腾服务器、不想付主机费，Jekyll + GitHub Pages 是 2026 年最适合程序员的零成本方案。整个过程不用买服务器、不用装数据库，只要 5 步就能上线一个能写文章、能换主题、SEO 还不错的静态博客。
一、Jekyll 是什么
Jekyll 是一个用 Ruby 写的静态网站生成器。它的工作原理很简单：把你写的 Markdown 博文，配合一套主题模板，编译成纯 HTML + CSS + JS 的静态文件。GitHub Pages 原生支持 Jekyll，只要把代码推到 GitHub 仓库，GitHub 会自动帮你编译并发布到公网。
整个流程里你不需要懂 Ruby，也不需要懂 Jekyll 内部是怎么实现的，你只需要会写 Markdown、会用 Git 提交代码，就够了。
Jekyll 的几个关键优势：
- **零成本**：GitHub Pages 免费提供 https 域名 + 服务器
- **零维护**：没有数据库，没有运行时服务，不用担心被黑
- **速度快**：纯静态文件，CDN 加速后国内访问 < 1 秒
- **可写代码**：博客内容就是 .md 文件，可用 VSCode / Typora / 任何编辑器
- **主题丰富**：minima、chirpy、al-folio 等几十款主流主题免费用
二、5 步搭建流程
### 第 1 步：准备 GitHub 账号和本地环境
首先你需要一个 GitHub 账号，登录后创建一个新仓库，仓库名必须是 `你的用户名.github.io` 这个格式。比如你的 GitHub 用户名是 zhangsan，仓库名就要叫 `zhangsan.github.io`，这样 GitHub 才会把它识别为 GitHub Pages 站点。
仓库创建时建议勾选 "Add a README file"，方便后面 git push 时不会因为没有初始 commit 报错。
本地环境准备：
- 安装 Git（windows 直接装 Git for Windows）
- 安装 Ruby 2.7 或更高版本（推荐用 rbenv 或 rvm 管理多版本）
- 安装 Jekyll 和 Bundler：
gem install jekyll bundler
验证安装成功：
jekyll -v
能看到版本号就 OK 了。
### 第 2 步：克隆仓库到本地
打开终端或 Git Bash，执行：
git clone https://github.com/你的用户名/你的用户名.github.io.git cd 你的用户名.github.io
这样就把空仓库拉到本地了。
### 第 3 步：初始化 Jekyll 项目
在仓库目录下新建一个 `_config.yml` 文件，写入站点基本信息：
title: 我的技术博客 description: 记录学习与生活的个人博客 theme: minima url: "https://你的用户名.github.io" baseurl: "" author: 你的名字
再创建 `_posts` 目录（放博客文章的）：
mkdir _posts
写第一篇博文，文件名要严格遵守 `YYYY-MM-DD-标题.md` 格式：
touch _posts/2026-07-13-hello-world.md
文件内容：
--- layout: post title: 你好世界 date: 2026-07-13 12:00:00 +0800 categories: [随笔] tags: [开篇] --- 这是我的第一篇 Jekyll 博文。
frontmatter（--- 之间的内容）是 Jekyll 解析用的元数据，标题、日期、分类、标签都填这里。
### 第 4 步：本地预览
在项目根目录执行：
bundle exec jekyll serve
终端会输出：
Server address: http://127.0.0.1:4000/
打开浏览器访问 `http://127.0.0.1:4000/`，就能看到博客的样子了。改完 Markdown 文件后，刷新页面就能实时看到效果。
如果想换主题，编辑 `_config.yml` 的 `theme` 字段即可。比如换成 `chirpy`：
theme: chirpy
然后执行：
bundle install bundle exec jekyll serve
chirpy 主题自带评论、搜索、分类、标签全套功能，是 Jekyll 圈最受欢迎的主题之一。
### 第 5 步：推送到 GitHub 触发部署
预览满意后，把代码推送到 GitHub：
git add . git commit -m "first blog post" git push origin main
GitHub Actions 会自动运行 Jekyll 编译，几分钟后访问 `https://你的用户名.github.io` 就能看到你的博客上线了。
三、3 个常见坑
### 坑 1：仓库名写错
GitHub Pages 识别的仓库名必须是 `用户名.github.io` 这个固定格式，写成别的（比如 `my-blog`）就只是一个普通仓库，GitHub 不会自动部署。
### 坑 2：Gemfile 缺失导致主题装不上
用第三方主题（比如 chirpy、al-folio）时，需要先在项目根目录建一个 `Gemfile`：
source "https://rubygems.org" gem "github-pages", group: :jekyll_plugins gem "jekyll-theme-chirpy"
然后执行 `bundle install`，不然主题样式加载不出来。
### 坑 3：中文文件名导致 URL 乱码
`_posts` 目录下的文件名**只能用英文**（因为这是 URL 的一部分）。比如 `2026-07-13-hello-world.md`，不要写 `2026-07-13-你好.md`。文章的中文标题写在 frontmatter 的 `title` 字段里就好。
四、附件包说明
附件包内含：
- **Jekyll 完整本地环境安装包**（Ruby + Jekyll + Bundler 离线安装指南）
- **3 款主流主题包**（minima 极简 / chirpy 功能派 / al-folio 学术风）
- **_config.yml 配置模板**（5 套现成配置，按需修改）
- **本地预览启动脚本**（start.bat / start.sh 一键启动）
- **部署到 GitHub Pages 完整流程**（含 Actions 自动化配置）
- **常见报错解决清单**（10 个最常见坑 + 解决方案）
五、写在最后
Jekyll + GitHub Pages 是一套非常成熟的静态博客方案，对程序员尤其友好：所有内容都是纯文本文件，版本管理天然支持，迁移成本几乎为零。不管是写技术博客、读书笔记还是个人日记，都能 hold 住。
跟着这 5 步走，1-2 小时就能把博客搭起来。
