一、教程说明

  • 适用人群：新手 / 技术博主，无需复杂编程基础，按步骤即可完成
  • 最终效果：免费、稳定、高颜值的个人博客（支持暗黑模式、评论、搜索、统计等）
  • 技术栈：GitHub Pages（免费托管）+ Hexo（静态博客框架）+ Butterfly（主题）+ Waline（评论）
  • 预计耗时：30 分钟（全程复制粘贴操作）

二、前期准备

2.1 必备工具

  1. GitHub 账号：注册地址 https://github.com
  2. Node.js：下载地址 https://nodejs.org/（选择 LTS 版，自动安装 npm）
  3. Git：下载地址 https://git-scm.com/（版本控制工具，部署用）
  4. 文本编辑器：推荐 VS Code（https://code.visualstudio.com/），方便编辑配置文件

2.2 环境验证

安装完成后，打开终端（Windows：cmd/PowerShell；Mac/Linux：终端），执行以下命令，显示版本号即成功：

1
2
3
node -v       # 示例输出：v20.10.0
npm -v        # 示例输出：10.2.3
git --version # 示例输出：git version 2.43.0

三、第一步：创建 GitHub 仓库

  1. 登录 GitHub，点击右上角「+」→「New repository」
  2. 仓库名 必须填写：你的GitHub用户名.github.io（例如：yadinae.github.io）
  3. 配置选项：
    • 勾选「Public」（私有仓库无法使用 GitHub Pages）
    • 无需勾选「Add a README file」
  4. 点击「Create repository」，创建完成后复制仓库地址

四、第二步：安装 Hexo 框架

4.1 初始化博客项目

  1. 本地创建一个空文件夹（例如：D:\my-blog），用于存放博客文件
  2. 打开终端，通过 cd 命令进入该文件夹：
1
2
d:              # Windows切换到D盘
cd my-blog      # 进入博客文件夹
  1. 安装 Hexo 命令行工具：
1
npm install -g hexo-cli
  1. 初始化 Hexo 博客：
1
2
hexo init       # 自动下载依赖文件
npm install     # 安装额外依赖
  1. 本地预览测试：
1
hexo clean && hexo g && hexo s

打开浏览器访问 http://localhost:4000，看到默认博客页面即初始化成功（按 Ctrl+C 停止本地服务）

4.2 Hexo 目录结构说明

1
2
3
4
5
6
my-blog/
├── _config.yml      # 全局配置文件（核心）
├── source/          # 文章和页面存放目录
│   └── _posts/      # 博客文章（Markdown格式）
├── themes/          # 主题文件夹
└── public/          # 生成的静态文件（部署到GitHub）

五、第三步：配置 Butterfly 主题

5.1 安装主题

在博客根目录执行命令：

1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

5.2 安装主题依赖（必装）

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

5.3 配置主题

编辑根目录 _config.yml，修改以下关键配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 博客基础信息
title: 你的博客名称
subtitle: ''
description: 记录技术与生活的点滴
keywords: 博客,技术,分享
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai

# 网址配置
url: https://你的用户名.github.io

# 主题选择（关键）
theme: butterfly

# 部署配置（关键）
deploy:
  type: git
  repo: 你的仓库地址
  branch: main

六、第四步：创建关键页面

在博客根目录执行以下命令，创建导航栏对应的页面：

1
2
3
4
hexo new page about      # 关于我页面
hexo new page links      # 友链页面
hexo new page tags       # 标签页面
hexo new page categories # 分类页面

6.1 配置「关于我」页面

打开 source/about/index.md，替换为：

1
2
3
4
5
6
7
8
9
10
11
12
13
---
title: 关于我
date: 2026-02-10
type: about
---

# 你好，我是[你的名字]

- 🔭 目前正在使用：Hexo + Butterfly + GitHub Pages
- 📚 学习方向：前端 / 后端 / 编程 / 技术分享
- ✍️ 博客用途：记录学习、生活、踩坑与思考
- 📫 联系方式：[你的邮箱]
- 🌟 GitHub：[https://github.com/你的用户名]

6.2 配置「友链」页面

打开 source/links/index.md，替换为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
---
title: 友情链接
date: 2026-02-10
type: link
---

# 友情链接

欢迎交换友链～留言或邮件联系我即可！

## 申请友链格式

名称：你的博客名称
地址：https://你的博客地址
头像：你的头像链接
介绍：博客简介（10 字以内）

七、第五步：安装 Waline 评论系统

7.1 安装依赖

在博客根目录执行命令：

1
npm install @waline/hexo-next --save

7.2 使用公共评论服务

在主题配置文件 themes/butterfly/_config.yml 中添加：

1
2
3
4
5
6
7
comment:
  use: waline
  waline:
    serverURL: https://waline.vercel.app
    lang: zh-CN
    placeholder: 欢迎留言～
    visitor: true

八、第六步：发布文章与部署上线

8.1 写第一篇博客

执行命令创建新文章：

1
hexo new "我的第一篇博客"

打开 source/_posts/我的第一篇博客.md，用 Markdown 格式编写内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
title: 我的第一篇博客
date: 2026-02-10 15:30:00
tags: [Hexo, 博客搭建]
categories: 技术分享
---

# 欢迎来到我的博客！

这是用 Hexo + Butterfly 搭建的第一篇博客～

## 功能亮点

- ✅ 暗黑模式
- ✅ 代码高亮
- ✅ 评论功能
- ✅ 搜索功能

8.2 部署到 GitHub

执行部署命令：

1
hexo clean && hexo g && hexo d
  • 首次部署可能需要输入 GitHub 账号密码 / 令牌
  • 部署成功后，访问 https://你的用户名.github.io 即可看到在线博客！

九、常用命令速查

命令 功能
hexo new "文章标题" 创建新文章
hexo clean 清空生成的静态文件
hexo g（hexo generate） 生成静态文件
hexo s（hexo server） 本地预览（http://localhost:4000）
hexo d（hexo deploy） 部署到 GitHub
hexo cl && hexo g && hexo s 本地预览（清空 + 生成 + 启动服务）
hexo cl && hexo g && hexo d 一键部署（清空 + 生成 + 发布）

十、常见问题排查

10.1 本地预览报错「extends includes/layout.pug…」

  • 原因：缺少主题渲染器
  • 解决：执行 npm install hexo-renderer-pug hexo-renderer-stylus --save

10.2 部署后访问 404

  • 原因 1：仓库名错误 → 必须是「用户名.github.io」
  • 原因 2：部署分支错误 → 配置文件中 deploy.branch 应为 main
  • 原因 3：未生成静态文件 → 部署前先执行 hexo g

10.3 评论区不显示

  • 原因：依赖未安装 → 执行 npm install @waline/hexo-next --save
  • 解决：重新部署后刷新页面

10.4 图片无法显示

  • 方法 1：使用图床（如新浪图床、PicGo+GitHub 图床），插入图片链接
  • 方法 2：在 source 目录创建 images 文件夹，存放图片，引用路径为 /images/图片名.jpg

十一、拓展功能（可选）

  1. 绑定自定义域名：在 GitHub 仓库 → Settings → Pages → Custom domain 填写域名
  2. 添加访客统计：推荐不蒜子、LeanCloud
  3. 文章置顶：在文章 Front-matter 中添加 top: true
  4. 暗黑模式优化：在主题配置文件中调整 darkmode 相关参数
  5. SEO 优化：完善 _config.yml 中的 description、keywords，使用 hexo-generator-seo-friendly-sitemap 插件

编辑历史：这篇文章由 Clawdbot 自动格式化并发布到博客。