Hexo + Butterfly + GitHub Pages 快速搭建个人博客

一、教程说明

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

二、前期准备

2.1 必备工具

GitHub 账号：注册地址 https://github.com
Node.js：下载地址 https://nodejs.org/（选择 LTS 版，自动安装 npm）
Git：下载地址 https://git-scm.com/（版本控制工具，部署用）
文本编辑器：推荐 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 仓库

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

四、第二步：安装 Hexo 框架

4.1 初始化博客项目

本地创建一个空文件夹（例如：D:\my-blog），用于存放博客文件
打开终端，通过 cd 命令进入该文件夹：

1 2	d: # Windows切换到D盘 cd my-blog # 进入博客文件夹

安装 Hexo 命令行工具：

1	npm install -g hexo-cli

初始化 Hexo 博客：

1 2	hexo init # 自动下载依赖文件 npm install # 安装额外依赖

本地预览测试：

1	hexo clean && hexo g && hexo s

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

4.2 Hexo 目录结构说明

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，修改以下关键配置：

# 博客基础信息
title: 你的博客名称
subtitle: ''
description: 记录技术与生活的点滴
keywords: 博客,技术,分享
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai

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

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

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

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

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

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

6.1 配置「关于我」页面

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

---
title: 关于我
date: 2026-02-10
type: about
---

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

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

6.2 配置「友链」页面

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

---
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 中添加：

comment:
  use: waline
  waline:
    serverURL: https://waline.vercel.app
    lang: zh-CN
    placeholder: 欢迎留言～
    visitor: true

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

8.1 写第一篇博客

执行命令创建新文章：

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

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

---
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

十一、拓展功能（可选）

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

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

文章作者: 颂雅风

文章链接: https://yadinae.github.io/2026/02/10/hexo-butterfly-github-blog-tutorial/

Hexo Butterfly GitHub Pages 博客搭建教程

[ cover of previous post

如何让AI通过Hexo接管GitHub博客

引言在这个AI迅速发展的时代，我们可以用智能助手来帮助我们管理技术博客。本文将详细介绍如何让AI通过Hexo接管并自动化维护你的GitHub博客，从而提高内容更新效率。为什么让AI接管博客？1. 提高效率自动内容生成：AI可以根据主题自动生成技术文章快速部署：无需手动操作，AI可以直接发布新内容智能优化：AI可以优化标题、标签和分类，提高SEO效果 2. 降低维护成本无需手动学习Hexo命令：AI知道如何操作自动处理重复任务：如文章格式化、图片优化等 24/7可用：随时可以进行更新和维护 3. 提升质量内容一致性：AI可以保持统一的写作风格技术准确性：AI可以自动验证代码和技术细节多语言支持：AI可以轻松处理多语言内容系统架构123456789101112graph TB A[用户指令] –> B[AI Agent] B –> C[内容生成] B –> D[Hexo命令执行] B –> E[Git操作] C –> F[文章源文件] D –> F F –&…

](/2026/02/15/%E5%A6%82%E4%BD%95%E8%AE%A9AI%E9%80%9A%E8%BF%87Hexo%E6%8E%A5%E7%AE%A1GitHub%E5%8D%9A%E5%AE%A2/ “如何让AI通过Hexo接管GitHub博客”)