Hexo-Butterfly的搭建
Hexo-Butterfly 的搭建过程
欢迎来到我的博客! 初次见面,我会介绍一下关于 Hexo-Butterfly 主题的相关搭建过程。
这篇文章更像是一篇从零开始的记录,而不是特别严谨的官方教程。毕竟在第一次接触博客搭建的时候,我也是一边看文档,一边百度,一边报错,一边怀疑自己是不是少装了什么东西(/doge)。
所以这里会把我当时比较关心的几个问题写清楚:
- 为什么选择 Hexo 和 Butterfly。
- 搭建前需要准备什么。
- 如何把 Hexo 跑起来。
- 如何安装并启用 Butterfly。
- 部署到 GitHub Pages 时需要注意什么。
- 后续配置和踩坑记录。
Hexo
Why?
目前接触的框架搭建系统比较少,只有 WordPress 和 Hexo。对于 WordPress 来说,它当然很强大,不管是页面搭建、插件生态还是网站自由度,都比 Hexo 要丰富很多。
但是对于超级小白(比如说我)来说,第一次上手 WordPress 反而会感觉选择太多:主题怎么选,插件怎么装,数据库怎么配,后台怎么维护,这些东西一多,搭博客这件事情就会从“我想写点东西”变成“我怎么还没搭好”。
Hexo 相对来说就轻很多。
它的思路比较简单:本地写 Markdown,Hexo 帮你生成静态网页,然后把生成好的 public 文件部署到 GitHub Pages 之类的平台上。没有数据库,也不用一直挂着服务器。对于个人博客来说,这种方式其实已经非常够用了。
我第一次接触到 Hexo-Butterfly,是在 点木 这个专注收集英雄联盟所有英雄语音的网站上。当时第一眼看到这个主题,就觉得它的页面很清爽,动效也比较舒服,既不是特别素,也不是花到看不清内容。
于是就有了一个非常朴素的想法:
这个好看,我也想试试。
What?
Hexo 本身是一个静态博客框架,Butterfly 是 Hexo 的一个主题。
可以这样理解:
1 | Hexo:负责把 Markdown 文章生成网页 |
所以整个搭建过程大概是:
1 | 安装 Node.js 和 Git |
看起来步骤挺多,但实际上真正麻烦的地方通常不在“命令本身”,而在于路径、配置文件、版本和网络问题。
搭建前的准备
在正式搭建之前,电脑里最好先准备好下面几个东西:
Node.js
Hexo 是基于 Node.js 的,所以 Node.js 是必须的。安装完成后,可以在终端里检查:
1
2node -v
npm -v如果能正常显示版本号,就说明安装基本没问题。
Git
Git 用来拉取主题、管理代码,也用来把博客部署到 GitHub。安装后检查:
1
git --version
GitHub 账号
如果想把博客发布到网上,GitHub Pages 是一个很方便的选择。它不需要额外购买服务器,对个人博客来说已经非常友好。
一个顺手的编辑器
VS Code 就很好用,写 Markdown、改配置文件、查看目录结构都比较方便。
安装 Hexo
准备工作做好之后,就可以开始安装 Hexo。
首先全局安装 Hexo 命令行工具:
1 | npm install -g hexo-cli |
安装完成后检查:
1 | hexo -v |
如果能看到 Hexo 和相关依赖的版本信息,就说明安装成功。
然后新建一个博客项目:
1 | hexo init myblog |
这里的 myblog 就是博客项目的文件夹名字,可以按照自己的习惯改。
接着在本地启动预览:
1 | hexo server |
或者简写:
1 | hexo s |
正常情况下,终端里会出现类似这样的地址:
1 | http://localhost:4000 |
打开浏览器访问这个地址,如果能看到 Hexo 默认页面,就说明第一步已经成功了。
安装 Butterfly 主题
对于 Butterfly 的配置安装,可以参考官方文档:
一般来说,可以在博客根目录下执行:
1 | git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly |
这样就会在 themes 文件夹下多出一个 butterfly 文件夹。
然后打开 Hexo 根目录下的 _config.yml,找到主题配置:
1 | theme: landscape |
把它改成:
1 | theme: butterfly |
这里要注意,Hexo 有两个层面的配置:
1 | _config.yml Hexo 主配置文件 |
后来 Butterfly 更推荐使用根目录下的 _config.butterfly.yml 来覆盖主题配置。这样做的好处是,主题以后更新时,不容易把自己的配置覆盖掉。
也就是说,比较推荐的结构是:
1 | myblog/ |
当时我刚开始搭的时候,对这几个配置文件的关系有点迷糊。后来理解之后,其实一句话就够了:
_config.yml管 Hexo 本体,_config.butterfly.yml管 Butterfly 长什么样。
常用目录结构
搭好之后,一个 Hexo 博客大概会长这样:
1 | myblog/ |
其中最常用的是:
| 路径 | 作用 |
|---|---|
source/_posts |
存放 Markdown 博客文章 |
source/tags/index.md |
标签页入口 |
source/categories/index.md |
分类页入口 |
source/link/index.md |
友情链接页入口 |
_config.yml |
Hexo 主配置 |
_config.butterfly.yml |
Butterfly 主题配置 |
public |
生成后的静态网页 |
一般情况下,写文章主要改 source/_posts,调整主题主要改 _config.butterfly.yml。
创建文章
Hexo 创建文章可以使用:
1 | hexo new "文章标题" |
它会在 source/_posts 下生成一个 Markdown 文件。
文章开头一般会有一段 front matter:
1 |
|
这里面比较常用的是:
title:文章标题。date:发布时间。tags:标签。categories:分类。cover:首页文章卡片封面。top_img:文章页顶部图。
这里有个小细节,tags 和 categories 写错的话,页面可能不是报错,而是“看起来什么都没有发生”。比如标签页如果没有正确配置 type: "tags",网页端就可能看不到标签云。
所以配置文件这种东西,看起来只差一个字母,实际效果可能差很多。这个坑非常适合让人反复怀疑人生。
配置标签页和分类页
Butterfly 的标签页和分类页需要单独创建页面。
标签页:
1 | hexo new page tags |
然后修改 source/tags/index.md:
1 |
|
分类页:
1 | hexo new page categories |
然后修改 source/categories/index.md:
1 |
|
这里最重要的是 type 字段。
标签页是:
1 | type: "tags" |
分类页是:
1 | type: "categories" |
如果不写,或者写错,Butterfly 就不知道这个页面应该渲染成标签云还是分类列表。
本地预览和生成
每次改完文章或配置后,可以先清理再生成:
1 | hexo clean |
也可以简写:
1 | hexo clean |
本地预览:
1 | hexo s |
如果访问 http://localhost:4000 没有看到最新内容,可以尝试:
- 停掉当前服务,重新
hexo s。 - 执行
hexo clean后重新生成。 - 浏览器强制刷新。
- 检查自己改的是不是根目录配置文件,而不是主题内部的另一个配置文件。
有时候问题不是没有改对,而是旧缓存还在。这个时候不要急着怀疑人生,先 clean 一下。
部署到 GitHub Pages
如果要部署到 GitHub Pages,一般需要先安装部署插件:
1 | npm install hexo-deployer-git --save |
然后在 _config.yml 里配置:
1 | deploy: |
然后执行:
1 | hexo clean |
简写也可以:
1 | hexo clean |
部署成功之后,访问:
1 | https://你的用户名.github.io |
就可以看到自己的博客了。
需要注意的是,GitHub Pages 的仓库名通常是:
1 | 用户名.github.io |
如果仓库名、分支、部署地址写错,命令可能看起来执行完了,但是网页就是没有更新。这个时候优先检查 _config.yml 里的 url 和 deploy。
Butterfly 常见配置
Butterfly 的配置项很多,一开始没必要全部看懂。可以先改几个最容易看到效果的地方。
菜单
在 _config.butterfly.yml 中可以配置导航栏:
1 | menu: |
这里的图标来自 Font Awesome。刚开始不用纠结太多,能正常跳转最重要。
头像和首页图
1 | avatar: |
这些图片一般放在主题的 source/img,或者放在博客的 source/img 中。路径写错的话,页面上就会出现 404 图片。
文章信息
比如首页是否显示分类和标签:
1 | post_meta: |
如果希望读者在首页就能看到文章标签,可以把 page.tags 打开。
我遇到的一些问题
1. 配置文件改错位置
这是刚开始最容易犯的错误。
Hexo 有根目录 _config.yml,Butterfly 主题里也有 _config.yml,后来还可以有 _config.butterfly.yml。如果不知道某个配置到底归谁管,就容易出现“我明明改了,为什么没变化”的情况。
我的理解是:
1 | 站点地址、文章路径、部署信息:改根目录 _config.yml |
这样分清之后,后面会舒服很多。
2. 标签页不显示
标签页不显示,很多时候不是文章没有写 tags,而是 source/tags/index.md 里的页面类型没有写对。
正确写法是:
1 | type: "tags" |
如果写成别的,比如 types: "tags",就会被当成普通页面,最后网页端看起来就是空的。
3. 图片路径问题
图片路径也是一个很容易踩坑的地方。
如果直接复制本地绝对路径,比如:
1 | D:\Blog\myblog\source\_posts\xxx\picture.png |
本地可能看起来还有机会显示,但部署到 GitHub 之后,别人电脑上没有你的 D 盘,自然就找不到图片。
所以图片路径一定要写成网站能访问的相对路径或站点路径。
关于图片插入的问题,我后来又单独写了一篇记录,这里就不展开了。
4. 生成内容没有更新
有时候改了文章或配置,刷新网页没有效果。
这个时候可以试试:
1 | hexo clean |
如果是部署后没有更新,再执行:
1 | hexo d |
总之,先确认本地生成没问题,再去看线上部署。
总结
总结一下,Hexo-Butterfly 的搭建并不算特别难,但它对新手来说有几个容易绕的地方:
- Node.js、Git、Hexo 的环境要先装好。
_config.yml和_config.butterfly.yml要分清楚。- 标签页、分类页这类独立页面需要正确写
type。 - 图片路径不要直接复制本地绝对路径。
- 每次改完配置后,可以先
hexo clean再重新生成。 - 部署到 GitHub Pages 时,要检查仓库、分支和站点地址。
对于我来说,Hexo-Butterfly 最吸引人的地方,不是它能把博客做得多复杂,而是它能让我比较快地拥有一个“像样的、愿意继续写下去的地方”。
博客本身当然只是一个容器,真正重要的还是以后不断写进去的内容。
如果搭建过程里出现报错,也不用太着急。大多数问题最后都会回到三件事:依赖有没有装好,路径有没有写对,配置文件有没有改到正确的位置。
先让博客跑起来,再慢慢把它改成自己喜欢的样子。





