快速搭建免费的个人博客网站：Hexo + GitHub Pages + Butterfly 完整指南
本文概览：本文将从零开始讲解如何使用 Hexo 和 GitHub Pages 搭建一个完全免费的个人博客网站。内容包括环境准备、Hexo 初始化、主题选择与安装、Butterfly 主题配置、文章发布、GitHub Pages 部署以及常见问题排查。最终你将拥有一个类似 青山木 这样的个人博客网站，可以用来记录技术学习、项目实践、算法笔记和个人成长。
一、为什么选择 Hexo + GitHub Pages 搭建个人博客？
很多人刚开始写技术博客时，通常会选择 CSDN、掘金、博客园、知乎等平台。这些平台的好处是流量大、发布方便，但它们也有一些限制：
- 页面样式由平台决定，个性化空间有限
- 文章数据主要托管在第三方平台
- 广告、推荐流、平台规则会影响阅读体验
- 不方便打造一个长期属于自己的个人技术名片
而使用 Hexo + GitHub Pages 搭建博客，可以很好地解决这些问题。正式开始搭建之前，我们先简单了解一下这套方案里的几个核心概念。
- Hexo：一个基于 Node.js 的静态博客框架。它的作用是把我们写好的 Markdown 文章、主题模板和站点配置，生成一套可以直接访问的 HTML、CSS、JavaScript 静态网页。
- GitHub：一个代码托管平台。博客项目的源码、配置文件、文章文件都可以保存在 GitHub 仓库中，方便备份、版本管理和多设备同步。
- GitHub Pages：GitHub 提供的免费静态网站托管服务。它可以把仓库中的静态网页发布成一个可以公网访问的网站，个人主页的访问地址一般是
https://你的GitHub用户名.github.io/。 - GitHub Pages 仓库：用于存放网站发布内容的仓库。个人博客通常创建名为
你的GitHub用户名.github.io的仓库，Hexo 生成的静态文件最终会部署到这个仓库中。 - Butterfly 主题：一个 Hexo 博客主题。Hexo 负责生成网站内容，而 Butterfly 负责网站的页面样式和交互效果，比如首页布局、文章目录、暗黑模式、代码块复制、侧边栏作者信息等。
简单来说，这套方案的工作流程是：我们用 Markdown 写文章，Hexo 把文章生成为静态网页，Butterfly 负责美化页面，最后 GitHub Pages 把生成后的网站免费发布到互联网上。
我的个人博客 青山木 就是基于这个方案搭建的。整体效果包括首页文章列表、分类、标签、归档、代码高亮、暗黑模式、侧边栏作者信息、公告栏等功能，基本可以满足个人技术博客的日常使用。
二、最终效果展示
搭建完成后，你的博客访问地址通常是：
1 | https://你的GitHub用户名.github.io/ |
例如我的博客地址是：
1 | https://li-s-h.github.io/ |
博客首页可以展示：
- 博客标题和副标题
- 最新文章列表
- 文章分类
- 文章标签
- 归档时间线
- 作者信息卡片
- GitHub 主页链接
- 网站公告
- 深色模式切换
- 文章目录
- 代码块复制按钮
以我的博客为例，网站名称是 青山木，主要用来记录 Java 后端开发、AI Agent、算法题解、技术实践等内容。
这种博客最大的优势是：免费、可控、简洁、长期可维护。
三、准备工作
在正式开始之前，需要先准备下面几个工具。
3.1 安装 Node.js
Hexo 是基于 Node.js 运行的，所以首先需要安装 Node.js。
进入 Node.js 官网下载安装包：
1 | https://nodejs.org/ |
建议选择 LTS 长期支持版本。
安装完成后，在终端中输入：
1 | node -v |
如果能看到版本号，说明安装成功，例如：
1 | v20.x.x |
Node.js 安装完成后，npm 也会一起安装。npm 是 Node.js 的包管理工具，后面安装 Hexo、主题和插件都会用到它。
3.2 安装 Git
Git 用来管理代码，并且把博客部署到 GitHub Pages。
下载安装地址：
1 | https://git-scm.com/ |
安装完成后输入：
1 | git --version |
如果能看到版本号，说明 Git 安装成功。
3.3 准备 GitHub 账号
GitHub Pages 是 GitHub 提供的免费静态网站托管服务，所以需要提前注册一个 GitHub 账号。
GitHub 地址：
1 | https://github.com/ |
注册完成后，记住你的 GitHub 用户名。后面创建博客仓库时会用到。
比如我的 GitHub 用户名是：
1 | LI-S-H |
所以我的 GitHub Pages 仓库名就是：
1 | LI-S-H.github.io |
对应博客访问地址就是：
1 | https://li-s-h.github.io/ |
这里要注意，GitHub Pages 的个人主页仓库名称必须符合下面这个格式：
1 | 你的GitHub用户名.github.io |
如果仓库名写错，后面部署后可能无法正常访问。
四、安装 Hexo
4.1 全局安装 Hexo CLI
打开终端，执行：
1 | npm install -g hexo-cli |
安装完成后检查版本：
1 | hexo -v |
如果能看到 Hexo 相关版本信息，说明安装成功。
Hexo CLI 是 Hexo 的命令行工具，后面我们会使用它来初始化博客、生成静态页面、启动本地预览服务和部署网站。
4.2 初始化博客项目
选择一个你想存放博客项目的目录，然后执行：
1 | hexo init my-blog |
这几条命令分别表示：
hexo init my-blog：创建一个名为my-blog的 Hexo 博客项目cd my-blog：进入博客项目目录npm install：安装项目依赖
初始化完成后，项目结构大概如下：
1 | my-blog |
其中比较重要的是：
_config.yml：Hexo 站点主配置文件package.json：项目依赖和脚本配置source/_posts：博客文章存放目录themes：主题目录scaffolds：文章模板目录
五、本地预览博客
初始化完成后，可以先启动本地服务看看默认效果。
执行：
1 | hexo server |
或者使用简写：
1 | hexo s |
正常启动后，终端会出现类似地址：
1 | http://localhost:4000/ |
打开浏览器访问这个地址，就能看到本地博客页面。
如果你修改了文章或配置，有时需要先清理缓存再重新生成：
1 | hexo clean |
对应含义是：
hexo clean：清理缓存和已生成的静态文件hexo generate：重新生成静态网页hexo server：启动本地预览服务
六、选择博客主题：Butterfly
Hexo 默认主题比较简单，如果想让博客更加美观，可以更换主题。
我这里选择的是 Butterfly 主题。Butterfly 是 Hexo 生态里非常受欢迎的主题之一，页面美观，功能丰富，适合个人技术博客使用。
它支持：
- 响应式布局
- 暗黑模式
- 首页文章卡片
- 文章目录
- 代码块复制
- 分类和标签
- 归档页面
- 作者信息卡片
- 公告栏
- 社交链接
- 文章版权声明
- 背景图和头像配置
如果想进一步了解 Butterfly 的功能、效果预览和完整配置项，可以查看 Butterfly 官方文档：
1 | https://butterfly.js.org/ |
七、安装 Butterfly 主题
Butterfly 主题可以通过 npm 安装，也可以通过 Git 克隆到 themes 目录。这里推荐使用 npm 安装，依赖管理更清晰。
在博客根目录执行：
1 | npm install hexo-theme-butterfly |
安装完成后，打开 Hexo 主配置文件 _config.yml，找到 theme 配置项：
1 | theme: landscape |
修改为：
1 | theme: butterfly |
我的项目中就是这样配置的：
1 | theme: butterfly |
这样 Hexo 就会使用 Butterfly 主题来渲染博客页面。
八、安装 Butterfly 需要的渲染器
Butterfly 主题通常需要 pug 和 stylus 渲染器支持，可以执行：
1 | npm install hexo-renderer-pug hexo-renderer-stylus --save |
如果你的项目中已经有这些依赖，就不需要重复安装。
例如我的博客项目里，package.json 中已经包含了：
1 | "hexo-renderer-pug": "^3.0.0", |
同时还包含了 Hexo 常用的分类、标签、归档生成器：
1 | "hexo-generator-archive": "^2.0.0", |
这些插件可以让博客自动生成归档页、分类页、标签页和首页文章列表。
九、配置站点基本信息
打开博客根目录下的 _config.yml，配置站点基本信息。
示例：
1 | title: 青山木 |
这些配置分别表示：
title：网站标题subtitle：网站副标题description：网站描述keywords：网站关键词author：作者名称language：网站语言timezone：时区
以我的博客为例：
1 | title: 青山木 |
设置完成后，网站页面上就会显示对应的博客名称和作者信息。
十、配置博客访问地址
继续修改 _config.yml 中的 url 配置。
如果你使用 GitHub Pages 个人主页仓库，格式一般是：
1 | url: https://你的GitHub用户名.github.io |
例如我的博客配置是：
1 | url: https://LI-S-H.github.io |
实际访问地址是：
1 | https://li-s-h.github.io/ |
这里建议和你的 GitHub Pages 地址保持一致，否则可能会出现资源路径错误、样式加载失败、图片无法显示等问题。
十一、配置文章链接格式
在 _config.yml 中可以配置文章链接格式：
1 | permalink: :year/:month/:day/:title/ |
这样生成的文章链接会包含年月日和文章标题，例如：
1 | https://li-s-h.github.io/2026/07/01/Hot%20100%20---%20排序链表/ |
这种格式的优点是：
- 链接结构清晰
- 能看出文章发布时间
- 适合长期维护
- 对归档和 SEO 比较友好
十二、配置代码高亮
技术博客经常需要展示代码，所以代码高亮非常重要。
Hexo 支持多种代码高亮方式，我的配置中使用的是 highlight.js：
1 | syntax_highlighter: highlight.js |
这表示：
- 使用 highlight.js 作为代码高亮工具
- 显示代码行号
- 不自动检测语言
- 保留代码块包装结构
如果你写 Java、JavaScript、Python、Shell 等技术文章，代码高亮会明显提升阅读体验。
十三、配置 Butterfly 主题
Butterfly 的主题配置一般放在 _config.butterfly.yml 中。
这个文件负责控制主题外观和功能，比如头像、背景图、社交链接、侧边栏、暗黑模式、文章目录等。
13.1 配置 GitHub 社交链接
示例：
1 | social: |
这表示在博客页面展示 GitHub 图标，点击后跳转到 GitHub 主页。
如果你要换成自己的账号，只需要把链接改成：
1 | social: |
13.2 配置头像和网站图标
示例：
1 | favicon: /img/头像.jpg |
这里的图片路径 /img/头像.jpg 对应的是：
1 | source/img/头像.jpg |
也就是说，如果你想使用自己的头像，需要把图片放到 source/img/ 目录下，然后在配置文件里填写对应路径。
13.3 配置首页背景图
示例：
1 | default_top_img: /img/背景图.webp |
这几个配置分别控制：
default_top_img：默认顶部图index_img：首页顶部图background：网站背景图
对应图片放在：
1 | source/img/背景图.webp |
如果想让博客更有个人风格，可以准备一张自己喜欢的背景图。
13.4 配置首页打字机副标题
Butterfly 支持首页副标题打字机效果。
示例：
1 | subtitle: |
这个配置会让首页展示动态打字效果。
我的博客里使用的是苏轼《定风波》中的句子，整体风格比较适合个人博客：既有技术记录，也有个人表达。
13.5 配置首页文章布局
示例：
1 | index_layout: 3 |
Butterfly 的首页文章布局有多种模式。3 表示文章封面和信息左右交替展示，页面会更有层次感。
还可以配置首页文章摘要：
1 | index_post_content: |
这表示优先显示文章 description，如果文章没有 description，就自动截取正文内容作为摘要，长度为 500。
13.6 配置文章目录
技术文章通常比较长，文章目录可以帮助读者快速定位内容。
示例：
1 | toc: |
含义如下：
post: true：文章页开启目录page: false：普通页面不开启目录number: true：目录显示编号expand: false：默认不全部展开scroll_percent: true：显示阅读进度
对于技术教程类文章，这个功能非常实用。
13.7 配置文章版权信息
示例：
1 | post_copyright: |
开启后，每篇文章底部会显示版权声明。
如果你的博客文章主要是原创内容，建议开启这个功能。
13.8 配置侧边栏作者信息
示例：
1 | aside: |
这个配置会在博客侧边栏显示作者卡片。
我的博客中作者描述是：
1 | 正在学习Java后端开发＋智能体开发，希望能与大家多多交流 |
这类描述不需要太复杂，重点是让访问者快速知道你是谁、在学习什么、博客主要记录什么内容。
13.9 配置网站公告
示例：
1 | card_announcement: |
公告栏适合放一句简短介绍，比如：
1 | 欢迎来到我的博客，记录学习与成长的点滴。 |
也可以放近期计划、联系方式、学习方向等。
13.10 开启暗黑模式
Butterfly 支持暗黑模式。
示例：
1 | darkmode: |
这表示：
- 开启暗黑模式
- 显示暗黑模式切换按钮
- 不根据时间自动切换
对于经常阅读技术文章的人来说，暗黑模式是一个很实用的功能。
十四、创建分类页和标签页
Hexo 默认不一定会自动创建分类页和标签页，需要手动创建。
执行：
1 | hexo new page tags |
然后分别修改生成的文件。
标签页一般是：
1 | source/tags/index.md |
内容如下：
1 | --- |
分类页一般是：
1 | source/categories/index.md |
内容如下：
1 | --- |
其中最关键的是：
1 | type: tags |
和：
1 | type: categories |
Butterfly 会根据这个字段识别页面类型，然后渲染成标签页和分类页。
十五、创建第一篇博客文章
执行：
1 | hexo new "我的第一篇博客" |
Hexo 会在 source/_posts/ 目录下生成一篇 Markdown 文章。
文章开头会有一段 front matter，例如：
1 | --- |
这些字段分别表示：
title：文章标题date：发布时间tags：文章标签categories：文章分类description：文章摘要cover：文章封面图
在我的博客项目中，文章基本也是这种结构。例如技术文章会放在 source/_posts/ 下，图片资源一般放在 source/img/ 或 source/img/title-picture/ 目录中。
十六、文章图片如何管理？
写技术博客时，经常需要插入截图、架构图、流程图。
推荐把图片统一放到：
1 | source/img/ |
如果是文章封面，可以放到：
1 | source/img/title-picture/ |
如果是某一篇文章专用图片，可以单独创建一个目录，例如：
1 | source/img/博客搭建/ |
然后在 Markdown 中这样引用：
1 |  |
或者设置文章封面：
1 | cover: /img/title-picture/blog.png |
需要注意，Hexo 里的图片路径通常从站点根路径开始写，也就是以 /img/... 开头。
十七、本地生成和预览
写完文章后，建议先本地预览。
执行：
1 | hexo clean |
或者简写：
1 | hexo clean |
然后打开：
1 | http://localhost:4000/ |
检查下面几点：
- 首页文章是否正常显示
- 文章标题是否正确
- 分类和标签是否正常
- 图片是否能加载
- 代码块是否正常高亮
- 文章目录是否正常生成
- 移动端显示是否正常
确认没问题后，再部署到 GitHub Pages。
十八、创建 GitHub Pages 仓库
打开 GitHub，创建一个新的仓库。
仓库名必须是：
1 | 你的GitHub用户名.github.io |
例如我的仓库名是：
1 | LI-S-H.github.io |
如果你的 GitHub 用户名是 zhangsan，那么仓库名应该是：
1 | zhangsan.github.io |
仓库创建完成后，你会得到一个仓库地址。
如果使用 HTTPS，类似：
1 | https://github.com/你的GitHub用户名/你的GitHub用户名.github.io.git |
如果使用 SSH，类似：
1 | git@github.com:你的GitHub用户名/你的GitHub用户名.github.io.git |
我自己的项目使用的是 SSH 地址：
1 | git@github.com:LI-S-H/LI-S-H.github.io.git |
十九、配置 SSH Key
如果使用 SSH 方式部署，需要先配置 SSH Key。
19.1 生成 SSH Key
执行：
1 | ssh-keygen -t ed25519 -C "你的邮箱" |
如果你的环境不支持 ed25519，也可以使用：
1 | ssh-keygen -t rsa -b 4096 -C "你的邮箱" |
一路回车即可。
生成后，公钥一般位于：
1 | ~/.ssh/id_ed25519.pub |
或者：
1 | ~/.ssh/id_rsa.pub |
19.2 添加到 GitHub
复制公钥内容，然后进入 GitHub：
1 | Settings -> SSH and GPG keys -> New SSH key |
把公钥粘贴进去保存。
19.3 测试连接
执行：
1 | ssh -T git@github.com |
如果看到类似：
1 | Hi 用户名! You've successfully authenticated |
说明 SSH 配置成功。
二十、安装部署插件
Hexo 需要部署插件才能一键发布到 GitHub。
执行：
1 | npm install hexo-deployer-git --save |
我的项目中也使用了这个插件：
1 | "hexo-deployer-git": "^4.0.0" |
二十一、配置部署信息
打开 _config.yml，找到最下面的 deploy 配置。
示例：
1 | deploy: |
我的博客配置是：
1 | deploy: |
这里说明一下：
type: git：使用 Git 部署repo：GitHub Pages 仓库地址branch：部署分支
有些 GitHub 仓库默认分支是 main，有些是 master。如果你的 GitHub Pages 仓库默认分支是 main，这里就写：
1 | branch: main |
如果默认分支是 master，就写：
1 | branch: master |
这个地方一定要和你的仓库实际分支保持一致。
二十二、一键部署博客
部署前建议先清理并生成静态文件：
1 | hexo clean |
然后执行部署：
1 | hexo deploy |
或者使用简写：
1 | hexo d |
也可以合并执行：
1 | hexo clean && hexo generate && hexo deploy |
部署成功后，等待一会儿，打开：
1 | https://你的GitHub用户名.github.io/ |
就可以看到自己的博客网站了。
例如我的博客：
1 | https://li-s-h.github.io/ |
二十三、日常写作和发布流程
博客搭建完成后，日常写文章的流程非常简单。
23.1 创建新文章
1 | hexo new "文章标题" |
23.2 编辑 Markdown
打开：
1 | source/_posts/文章标题.md |
填写文章内容、标签、分类、摘要和封面。
例如：
1 | --- |
23.3 本地预览
1 | hexo clean |
访问：
1 | http://localhost:4000/ |
23.4 发布上线
确认没有问题后执行：
1 | hexo clean |
发布完成后，访问线上博客检查效果。
二十四、常见问题排查
24.1 页面样式丢失
如果部署后页面只有文字，没有样式，通常是 url 配置错误。
检查 _config.yml：
1 | url: https://你的GitHub用户名.github.io |
如果是项目页，比如：
1 | https://用户名.github.io/仓库名/ |
还需要配置 root。但如果是个人主页仓库 用户名.github.io，通常不需要额外配置。
24.2 图片无法显示
常见原因有三个：
第一，图片没有放到 source/img/ 目录。
第二，Markdown 中路径写错。
推荐写法：
1 |  |
第三，文件名中包含特殊符号或大小写不一致。
建议图片文件名尽量使用简单中文、英文或数字，不要混用太多特殊字符。
24.3 部署失败
如果执行 hexo d 部署失败，可以检查：
- 是否安装了
hexo-deployer-git _config.yml中deploy.repo是否正确- SSH Key 是否配置成功
- GitHub 仓库是否存在
- 分支名称是
main还是master - 当前网络是否能访问 GitHub
可以先测试 SSH：
1 | ssh -T git@github.com |
如果 SSH 测试失败，就需要重新配置 GitHub SSH Key。
24.4 GitHub Pages 访问 404
如果仓库已经部署成功，但访问页面是 404，可以检查：
- 仓库名是否是
用户名.github.io - GitHub Pages 是否开启
- 部署分支是否正确
- 是否刚部署完还没生效，可以等待一两分钟
- 浏览器缓存是否影响显示
GitHub Pages 有时不会立刻刷新，稍等一会儿再访问即可。
24.5 文章没有显示分类和标签
检查文章开头是否正确配置：
1 | tags: [Hexo, GitHub Pages] |
同时确认已经创建了标签页和分类页：
1 | source/tags/index.md |
标签页需要：
1 | type: tags |
分类页需要：
1 | type: categories |
二十五、我的博客配置参考
这里简单总结一下我的博客 青山木 的核心配置，供你参考。
25.1 站点配置
1 | title: 青山木 |
25.2 部署配置
1 | deploy: |
25.3 主题配置
1 | social: |
25.4 首页副标题
1 | subtitle: |
25.5 侧边栏作者卡片
1 | aside: |
这些配置组合起来，就形成了现在博客的基本效果：简洁首页、技术文章列表、标签分类、作者信息、背景图、暗黑模式和 GitHub 入口。
二十六、为什么推荐自己搭建博客？
自己搭建博客不只是为了“有一个网站”，更重要的是它能成为一个长期积累的技术空间。
我个人比较推荐把个人博客当成下面几类内容的沉淀地：
- 技术学习笔记
- 项目实战记录
- 源码阅读总结
- 算法题解复盘
- 工具使用经验
- 面试知识体系
- AI 工具实践心得
- 个人成长记录
相比只把内容发在第三方平台，自建博客会更像一个属于自己的“技术主页”。以后找实习、找工作、做项目展示、整理知识体系时，都可以直接把博客地址放出来。
比如我的博客 青山木 当前主要记录 Java 后端开发、AI Agent 和 LeetCode Hot 100 题解。随着文章越来越多，博客本身就会逐渐变成一个个人知识库。
二十七、完整命令速查
最后整理一份常用命令。
初始化博客
1 | npm install -g hexo-cli |
启动本地服务
1 | hexo server |
新建文章
1 | hexo new "文章标题" |
清理缓存
1 | hexo clean |
生成静态文件
1 | hexo generate |
部署网站
1 | hexo deploy |
常用组合命令
1 | hexo clean |
简写形式：
1 | hexo clean |
总结
使用 Hexo + GitHub Pages 搭建个人博客，是一个非常适合技术学习者的免费方案。
整体流程可以概括为：
- 安装 Node.js 和 Git
- 安装 Hexo
- 初始化博客项目
- 安装并启用 Butterfly 主题
- 配置站点信息、头像、背景图、标签分类
- 创建 GitHub Pages 仓库
- 配置 SSH Key 和部署地址
- 使用
hexo clean && hexo g && hexo d发布博客
这个方案的优点非常明显：
- 完全免费
- 部署简单
- 支持 Markdown 写作
- 页面美观
- 数据自己掌控
- 适合长期积累技术内容
如果你也想拥有一个自己的技术博客，可以参考我的博客示例：青山木，从最简单的 Hexo 初始化开始，一步一步搭建属于自己的个人网站。
当你发布第一篇文章之后，这个网站就不只是一个页面，而是你持续学习、持续输出、持续成长的起点。
