前言

Hexo 默认的主题比较简单，不够美观。Butterfly 是一个功能强大、设计精美的 Hexo 主题，拥有丰富的功能和良好的用户体验。

本教程将介绍如何安装和配置 Butterfly 主题。

安装 Butterfly 主题

1. 下载主题

在博客根目录下执行：

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

2. 安装依赖

Butterfly 主题需要安装渲染器插件：

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

3. 启用主题

修改博客根目录下的 _config.yml 文件：

1
theme: butterfly

4. 复制主题配置文件

在博客根目录下执行：

1
cp themes/butterfly/_config.yml _config.butterfly.yml

这样可以在不修改主题源码的情况下自定义配置。

基础配置

1. 网站信息

编辑 _config.yml：

1
2
3
4
5
6
7
title: 我的博客
subtitle: 记录生活，分享知识
description: 基于 Hexo + Butterfly 的个人博客
keywords: Hexo, Butterfly, 博客
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai

2. 导航栏配置

编辑 _config.butterfly.yml：

1
2
3
4
5
6
7
8
9
10
11
12
nav:
  logo: /img/logo.png  # Logo 图片
  display_title: true
  display_post_title: true
  fixed: true  # 固定导航栏

menu:
  首页: / || fas fa-home
  归档: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder-open
  关于: /about/ || fas fa-heart

3. 代码块配置

1
2
3
4
5
6
code_blocks:
  theme: light  # 代码块主题
  macStyle: true  # Mac 风格
  height_limit: false  # 高度限制
  copy: true  # 复制按钮
  language: true  # 语言显示

4. 封面图片

1
2
3
4
5
6
7
8
cover:
  index_enable: true  # 首页启用封面
  aside_enable: true  # 侧边栏启用封面
  archives_enable: true  # 归档页启用封面
  default_cover:  # 默认封面列表
    - /img/1.jpg
    - /img/2.jpg
    - /img/3.jpg

创建页面

1. 创建分类页

1
hexo new page categories

编辑 source/categories/index.md：

1
2
3
4
5
---
title: 分类
date: 2026-01-02 21:00:00
type: categories
---

2. 创建标签页

1
hexo new page tags

编辑 source/tags/index.md：

1
2
3
4
5
---
title: 标签
date: 2026-01-02 21:00:00
type: tags
---

3. 创建关于页

1
hexo new page about

编辑 source/about/index.md：

1
2
3
4
5
6
7
8
---
title: 关于
date: 2026-01-02 21:00:00
---

## 关于我

这是一个关于我的页面...

文章配置

1. Front-matter

文章开头的配置区域：

1
2
3
4
5
6
7
8
9
10
---
title: 文章标题
date: 2026-01-02 21:00:00
tags:
  - 标签1
  - 标签2
categories:
  - 分类
cover: /img/cover.jpg  # 封面图片
---

2. 摘要

在文章中添加 <!-- more -->，前面的内容将作为摘要显示在首页。

1
2
3
4
5
这是文章的摘要内容...

<!-- more -->

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

侧边栏配置

1. 启用侧边栏

1
2
3
4
5
6
aside:
  enable: true
  hide: false
  button: true  # 显示隐藏按钮
  mobile: true  # 移动端显示
  position: right  # 位置：left/right

2. 卡片配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
aside:
  card_author:
    enable: true
    description: 这是我的个人博客
    button:
      enable: true
      icon: fab fa-github
      text: Follow Me
      link: https://github.com/yourname

  card_recent_post:
    enable: true
    limit: 5  # 显示数量

  card_categories:
    enable: true
    limit: 8

  card_tags:
    enable: true
    limit: 40

评论系统

Butterfly 支持多种评论系统，这里以 Gitalk 为例：

1. 申请 GitHub OAuth App

  1. 访问 https://github.com/settings/developers
  2. 点击 “New OAuth App”
  3. 填写信息：
  4. 创建后获取 Client ID 和 Client Secret

2. 配置 Gitalk

编辑 _config.butterfly.yml：

1
2
3
4
5
6
7
8
9
10
comments:
  use: Gitalk
  text: true

gitalk:
  client_id: your_client_id
  client_secret: your_client_secret
  repo: yourname.github.io
  owner: yourname
  admin: yourname

搜索功能

1. 安装搜索插件

1
npm install hexo-generator-searchdb --save

2. 配置搜索

编辑 _config.yml：

1
2
3
4
5
search:
  path: search.xml
  field: post
  format: html
  limit: 10000

编辑 _config.butterfly.yml：

1
2
3
search:
  use: local_search
  placeholder: 搜索文章...

图片处理

1. 图片资源文件夹

在 _config.yml 中启用：

1
post_asset_folder: true

这样创建文章时会自动创建同名文件夹，用于存放图片。

2. 引用图片

在文章中使用相对路径引用图片：

1
![图片描述](图片文件名.jpg)

自定义 CSS

如果需要自定义样式，可以在 source/css/ 目录下创建 custom.css：

1
2
3
4
/* 自定义样式 */
.post-content {
  font-size: 16px;
}

然后在 _config.butterfly.yml 中引入：

1
2
3
inject:
  head:
    - <link rel="stylesheet" href="/css/custom.css">

常见问题

Q: 主题没有生效？

A: 检查 _config.yml 中的 theme 是否设置为 butterfly，并执行 hexo clean && hexo g。

Q: 如何更新主题？

A: 进入主题目录执行 git pull。

Q: 如何自定义主题颜色？

A: 在 _config.butterfly.yml 中配置 theme_color。

Q: 如何添加社交链接？

A: 在 _config.butterfly.yml 的 social 部分添加。

下一步

恭喜你，已经配置好了 Butterfly 主题！

接下来的教程将介绍：

继续学习，让你的博客更加完善吧！