GitHub Pages + Jekyll 搭建个人博客完整教程：从零到上线

本文是一份完整的实践指南，记录从创建 GitHub Pages 仓库到配置完成的全过程。使用当前博客正在运行的 Animal Design 主题模板，涵盖基础部署、主题配置、功能启用、日常维护等环节。面向有一定编程基础的读者，按使用频率编排——高频操作在前，一次性配置在后。

一、前置准备

你需要什么

原理简述

GitHub Pages 的工作流程非常简单：

本地写 Markdown → git push → GitHub 自动编译 → 发布为网页

整个过程不需要购买服务器、不需要配置数据库、不需要管理 PHP/Node 运行环境。每次 git push 后，GitHub 自动运行 Jekyll 将 Markdown 编译为静态 HTML，托管在 GitHub 的 CDN 上。

二、三步搭建你的博客

第 1 步：创建仓库

在 GitHub 上创建一个新仓库，命名为 你的用户名.github.io（例如我的用户名是 bigsinger，仓库名就是 bigsinger.github.io）：

• 仓库必须设置为 Public
• 不要勾选 “ Add a README”（README 会由模板提供）
• 不要添加 .gitignore 或 License

注意：仓库名必须严格为 用户名.github.io 格式，GitHub Pages 只认这个名字。

第 2 步：克隆模板到本地

从模板仓库克隆代码到你本地：

# 先用我的博客模板做示范，你可以 fork 或下载
git clone https://github.com/bigsinger/zhupite.github.io.git my-blog
cd my-blog

# 然后替换为自己的远程仓库
git remote set-url origin https://github.com/你的用户名/你的用户名.github.io.git

如果你更愿意从头开始或使用其他模板，可以参考第三节的架构说明自行构建。

第 3 步：修改站点配置

编辑项目根目录的 _config.yml，这是博客的核心配置文件：

# 站点基本信息
url: https://你的用户名.github.io    # 你的博客域名
title: 你的博客标题                   # 浏览器标签栏显示的文字
subtitle: "你的副标题"                # 首页显示的副标题
description: "博客描述"               # SEO 描述信息
repository: 你的用户名/你的用户名.github.io

# 如果有自定义域名，可以配置
# url: https://你的域名.com

搞定这三步，推送代码到 GitHub 后访问 https://你的用户名.github.io 就能看到博客了。

git add .
git commit -m "初始化博客"
git push origin master

GitHub 会自动构建，等待 1-2 分钟后刷新即可看到效果。

三、项目结构说明

了解项目的文件结构后，你就知道在哪里写文章、在哪里改配置：

├── _posts/              ★ 博客文章目录（重点，日常写文章在这里）
│   ├── dev/               开发技术分类
│   ├── sec/               安全研究分类
│   ├── ai/                AI 分类
│   └── ...                其他分类（按需创建子目录）
├── _config.yml          ★ 站点配置文件（重点，一次性配置）
├── pages/               ★ 独立页面（关于、归档等，按需修改）
│   ├── about.md            关于页面
│   ├── archives.md         文章归档
│   ├── categories.md       分类页
│   └── search.md           站内搜索
├── assets/              ★ 样式和脚本（一般不用动）
│   ├── css/                样式文件（theme-modern.css）
│   └── js/                 JavaScript
├── _data/               结构化数据（友链、社交账号等）
│   └── links.yml           友链配置
├── _layouts/            页面模板（一般不用动）
├── _includes/           组件片段（header、footer 等）
└── images/              图片资源（文章引用的图片放这里）

重点记住：

• _posts/ 是你写文章的地方
• _config.yml 是改站点设置的地方
• pages/ 是改”关于”、”友链”页面的地方
• 其他目录通常不需要动

四、发布你的第一篇文章

4.1 写文章的标准格式

在 _posts/ 目录下创建 Markdown 文件，命名规则：

YYYY-MM-DD-英文标题.md

例如：2026-06-18-my-first-post.md

文件名必须以 日期开头，这决定了文章的发布日期和 URL。建议使用英文命名，避免 URL 编码问题。

4.2 文章头部配置（Frontmatter）

每篇文章开头必须有一段 YAML 格式的配置：

---
layout: post
title: "我的第一篇博客文章"
categories: [dev]
description: "这是文章摘要，会显示在首页卡片和搜索引擎结果中"
tags:
  - 标签1
  - 标签2
  - 标签3
---

字段说明：

分类与目录的关系：categories 字段的值决定了文章在 _posts/ 下的存放位置（例如 categories 为 sec，文章就放在 _posts/sec/ 下），同时也决定了首页卡片的分类颜色。

4.3 正文写作

正文直接用标准 Markdown 语法：

## 二级标题

这是一段正文。

### 三级标题

- 列表项 1
- 列表项 2

**加粗**、*斜体*、`行内代码`

| 表格 | 列2 |
|------|------|
| 数据 | 数据 |

```python
# 代码块，自动显示语言标签和复制按钮
def hello():
    print("Hello, Blog!")

博客模板自动支持：
- **代码高亮**：自动检测 50+ 编程语言
- **复制按钮**：鼠标悬停代码块时右上角显示
- **语言标签**：代码块左上角自动标注语言名称
- **表格渲染**：标准 Markdown 表格
- **图片懒加载**：图片在滚动到视口时才加载

### 4.4 发布

写好文章后，推送到 GitHub 即可：

```bash
git add _posts/sec/2026-06-18-my-first-post.md
git commit -m "发布新文章：我的第一篇博客"
git push

等待 1-2 分钟，访问博客就能看到新文章。不需要在本地安装任何环境。

五、进阶功能配置

5.1 自定义域名

如果你有自己的域名，可以绑定到博客：

1. DNS 配置：在域名管理后台添加一条 CNAME 记录，将域名指向 你的用户名.github.io
2. 仓库配置：在项目的 _config.yml 中修改：

   url: https://你的域名.com
   

3. GitHub 会自动为自定义域名配置 SSL 证书，无需手动申请 HTTPS

详细过程可参考 DNS 服务商文档（阿里云、腾讯云、Cloudflare 等都支持）。

5.2 评论系统

本博客使用 Utterances——基于 GitHub Issues 的评论插件。读者用 GitHub 账号登录后即可发表评论，所有评论存储在指定的 GitHub 仓库的 Issues 中。

配置步骤：

1. 在 GitHub 上创建一个专门存放评论的仓库（如 blog-comments），设为 Public
2. 在 GitHub Apps 页面 安装 Utterances 应用，授权访问此仓库
3. 在 _config.yml 中配置：

utterances:
  repo: 你的用户名/你的博客评论仓库名   # 如 bigsinger/blog-comments
  issue_term: pathname                  # 固定此值
  theme: preferred-color-scheme         # 自适应浅色/深色

如需在单篇文章中禁用评论，在 frontmatter 中添加：

comments: false

5.3 搜索引擎收录

要让你的博客被 Google 搜索到，提交站点地图即可：

# 直接 ping Google
curl "http://www.google.com/ping?sitemap=https://你的域名/sitemap.xml"

GitHub Pages 会自动生成 sitemap.xml，你不需要手动创建。

5.4 统计数据

Busuanzi 阅读量统计（默认开启）

博客自动集成 Busuanzi 统计，显示每篇文章的阅读次数和站点总访问量。无需额外配置。

Google Analytics（可选）

如需更详细的统计，在 Google Analytics 后台创建媒体资源，获取 Measurement ID（格式如 G-XXXXXXXXXX），然后在 _config.yml 中配置：

analytics_id: G-XXXXXXXXXX

5.5 文章置顶

需要在首页置顶某篇文章时，在 frontmatter 中添加：

sticky: true

• 置顶文章在首页优先显示（第 2 页起不显示置顶）
• 首页卡片会显示「📌 置顶」徽章
• 建议置顶文章 ≤ 3 篇
• 取消置顶只需删除 sticky: true 或设为 false

六、写作体验优化

6.1 文章分类与颜色

首页的文章卡片会根据分类自动分配不同的颜色，方便视觉区分：

创建新分类时，只需在 _posts/ 下创建对应文件夹，然后在文章 frontmatter 中使用新分类名称即可。卡片颜色会自动适配。

6.2 文章字数统计

文章顶部自动显示字数和预估阅读时间（按 350 字/分钟计算）。可在 _config.yml 中调整阅读速度：

components:
  word_count:
    enabled: true
    words_per_minute: 350

6.3 相关文章

文章底部自动展示同一分类下的其他文章，帮助读者发现更多内容。这是通过 Jekyll 的相关文章机制自动生成的，无需额外配置。

6.4 上一篇/下一篇导航

文章底部自动生成上一篇和下一篇的卡片式导航，首篇文章和末篇文章会自动禁用对应的导航按钮。

七、页面定制

7.1 “关于”页面

编辑 pages/about.md，修改个人介绍。支持标准的 Markdown 格式。

7.2 友链页面

编辑 _data/links.yml，每项友链格式：

- name: 站点名称
  url: https://example.com
  src: dev           # 分类标识，用于在页面上分组显示
  desc: 站点简介（可选）

7.3 搜索功能

博客内置站内搜索，支持按关键词检索。搜索功能在：

• 桌面端：侧边栏搜索框
• 移动端：顶部搜索图标（弹出全屏搜索覆盖层）
• 搜索页：独立 /search/ 页面

搜索数据源是构建时自动生成的 JSON 文件，无需配置第三方搜索服务。

7.4 404 页面

访问不存在的链接时会显示自定义的 404 页面。编辑 pages/404.md 可修改提示内容。

八、主题特性一览

📱 阅读体验

💻 代码体验

🎨 视觉设计

九、维护与常见问题

日常维护清单

常见问题

Q：推送后博客没有更新？ A：GitHub Pages 构建需要 1-3 分钟，稍等后刷新。可以在仓库的 Actions 页面查看构建状态。

Q：文章没有显示？ A：检查三点：① 文件名格式是否正确（YYYY-MM-DD-标题.md）；② frontmatter 是否有 layout: post；③ categories 字段是否对应已存在的目录。

Q：如何修改导航栏菜单？ A：编辑 _config.yml 的 navs 节，按 YAML 格式添加或删除菜单项。

Q：本地可以预览吗？ A：可以，但不是必须的。如需本地预览：

# 安装 Ruby + Bundler 后
gem install bundler jekyll
bundle install
bundle exec jekyll serve
# 访问 http://localhost:4000

如果只是写文章，直接 push 到 GitHub 即可，不用本地搭建环境。

Q：如何更换配色？ A：修改 assets/css/theme-modern.css 中的 CSS 变量（:root 节），主要变量包括主色、文本色、背景色、圆角、阴影等。

参考资料

• Jekyll 官方文档
• GitHub Pages 官方指南
• Animal Design System (itbug.shop) — 本博客 UI 风格参考
• Utterances 评论插件
• Busuanzi 网站统计

本博客始于 2007 年，19 年来写了 600+ 篇文章。好记性不如烂笔头。