为什么我要建立这个博客

在互联网高度碎片化的今天，我渴望一个真正属于自己的、不受平台审核机制干扰的”私人领地”。我不信任那些随时可能删除内容或倒闭的供应商，因此我选择了 GitHub。

经过一周的摸索和实践，我终于搭建起了这个完全属于自己的数字花园。这篇文章记录了完整的搭建过程，希望能帮助同样想要拥有自己博客的朋友们。

核心步骤与避坑指南

第一步：创建 GitHub 仓库

1.1 命名是成功的关键

这是整个过程中最容易出错的地方！仓库名必须精确匹配以下格式：

用户名.github.io

例如：Qingchuan-ZHU.github.io

❌ 错误示例：

  • git.io - 缺少用户名
  • myblog.github.io - 用户名不匹配
  • Qingchuan-ZHU.github.io.git - 多了.git后缀
  • Qingchuan-ZHU.github - 缺少.io后缀

✅ 正确示例：

  • Qingchuan-ZHU.github.io - 完全匹配

1.2 创建仓库步骤

  1. 登录 GitHub，点击右上角的 + 号
  2. 选择 “New repository”
  3. 输入仓库名（严格按照上述格式）
  4. 选择 “Public”（必须公开才能使用 GitHub Pages）
  5. 不要勾选 “Add a README file”
  6. 点击 “Create repository”

💡 提示： 创建仓库后，GitHub 会自动检测到 用户名.github.io 格式的仓库名，并在几分钟内激活 GitHub Pages 功能。

GitHub Pages 初始化页面预览

这是刚创建仓库、尚未自定义主题时的默认页面效果，确保你能顺利访问再继续。

第二步：配置 Jekyll 基础

2.1 创建配置文件

在仓库根目录创建 _config.yml 文件：

# Site settings
title: 你的博客标题
description: 你的博客描述
url: "https://用户名.github.io"
baseurl: ""

# Theme
theme: jekyll-theme-cayman

# Build settings
markdown: kramdown
highlighter: rouge
plugins:
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag

# SEO settings
author: 你的名字
lang: zh-CN
timezone: Asia/Shanghai

2.2 创建首页

创建 index.md 文件：

---
layout: default
title: 首页
---

# 欢迎来到我的博客

这里是我的第一篇博客文章，正在搭建中...

第三步：选择和配置主题

3.1 官方主题选择

GitHub Pages 提供了多个官方主题：

主题名称 特点 适用场景
cayman 简洁现代，蓝绿配色 技术博客
merlot 优雅红色，传统风格 文学博客
midnight 深色主题，代码友好 开发者博客
minima 极简设计，快速加载 个人博客

启用 Caymen 主题后的默认页面

选择官方主题后，你应该能看到类似上图的配色风格，说明主题已经正确加载。

3.2 自定义主题样式

如果你觉得默认主题不够美观，可以创建 _sass/custom.scss 文件来自定义样式：

// 自定义品牌色
$brand-color: #667eea;
$brand-color-dark: #764ba2;

// 美化标题
h1 {
  color: $brand-color;
  border-bottom: 3px solid $brand-color;
}

// 自定义按钮样式
.btn {
  background: linear-gradient(135deg, $brand-color, $brand-color-dark);
  border-radius: 25px;
}

第四步：创建文章结构

4.1 创建 _posts 目录

在仓库根目录创建 _posts 文件夹，所有文章都放在这里。

4.2 文章命名规范

文章文件名必须遵循以下格式：

年-月-日-文章标题.md

例如：2026-01-05-build-digital-garden.md

4.3 文章模板

每篇文章都需要包含 YAML 头信息：

---
layout: post
title: "文章标题"
date: 2026-01-05
description: 文章描述
categories: [技术]
tags: [Jekyll, GitHub Pages]
---

# 文章内容

这里是文章的正文内容...

第五步：本地开发环境

5.1 安装 Ruby 环境

Windows 的 Ruby 环境搭建步骤（包含下载、Add Ruby to PATH、执行 ridk install 及图文详解）已整理在另一篇文章《02｜突破局限：实现 GitHub 博客的本地实时预览》中，这里不再重复。完成该篇文章中的第 1 节后即可继续下面的 Jekyll 安装流程。

5.2 安装 Jekyll

# 安装 Jekyll 和 Bundler
gem install jekyll bundler

# 创建 Gemfile
bundle init

# 添加 GitHub Pages 依赖
echo 'gem "github-pages", group: :jekyll_plugins' >> Gemfile

# 安装依赖
bundle install

5.3 本地预览

# 启动本地服务器
bundle exec jekyll serve

# 访问 http://localhost:4000

第六步：高级功能配置

6.1 自定义域名

如果你有自己的域名，可以：

  1. 在仓库根目录创建 CNAME 文件
  2. 写入你的域名：yourdomain.com
  3. 在域名提供商处配置 DNS 记录

6.2 添加评论系统

可以使用 Gitalk 或 Utterances：

<!-- 在文章模板中添加评论容器 -->
<div id="comments"></div>
<script src="https://utteranc.es/client.js"
        repo="用户名/仓库名"
        issue-term="pathname"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

6.3 添加统计分析

在 _includes/head-custom.html 中添加 Google Analytics：

<!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_MEASUREMENT_ID');
</script>

常见问题解决

问题1：网站无法访问

症状：访问 用户名.github.io 显示 404

解决方案：

  1. 确认仓库名完全正确
  2. 等待 10 分钟（GitHub 需要时间处理）
  3. 检查仓库是否为 Public

问题2：样式不显示

症状：页面显示纯文本，没有样式

解决方案：

  1. 检查 _config.yml 中的主题配置
  2. 确保所有文件名正确（注意大小写）
  3. 清除浏览器缓存

问题3：本地预览失败

症状：运行 jekyll serve 报错

解决方案：

# 清理并重新安装
bundle clean --force
bundle install
bundle exec jekyll serve

问题4：文章不显示

症状：新建的文章不在首页显示

解决方案：

  1. 检查文件名格式
  2. 检查 YAML 头信息
  3. 确保日期不是未来时间

成本分析

费用对比

方案 年费用 存储空间 流量限制 审核风险
GitHub Pages ¥0 1GB 100GB/月 无
阿里云虚拟主机 ¥298+ 10GB 不限 有
WordPress.com ¥300+ 3GB 不限 有
自建服务器 ¥500+ 不限 不限 无

为什么选择 GitHub Pages？

  1. 完全免费 - 无需支付任何费用
  2. 高可用性 - GitHub 基础设施，99.9%+ 在线时间
  3. 无审核 - 完全的内容自由
  4. 版本控制 - Git 管理，永不丢失
  5. CDN 加速 - 全球访问速度快
  6. HTTPS 支持 - 自动配置 SSL 证书

成果展示

经过以上步骤，你将得到：

  • 一个完全免费的个人博客
  • 自定义域名的专业网站
  • 支持评论和统计分析
  • 移动端友好的响应式设计
  • SEO 优化的搜索引擎收录

持续优化建议

内容优化

  • 定期发布高质量文章
  • 使用合适的标签分类
  • 添加目录导航

技术优化

  • 压缩图片资源
  • 使用 CDN 加速
  • 添加 PWA 支持

推广优化

  • 提交搜索引擎收录
  • 社交媒体分享
  • 与其他博客互链

总结

搭建个人博客不是技术难题，而是开始记录和分享的第一步。通过 GitHub Pages，我们能够以零成本建立一个完全属于自己的数字花园。

希望这篇详细的指南能够帮助你顺利搭建自己的博客。如果在过程中遇到任何问题，欢迎在评论区讨论交流！

记住：最好的开始时间是昨天，其次是现在。