Butterfly 主题配置指南

主题概述

Butterfly 是一款基于 hexo-theme-melody 开发的 Hexo 主题，具有简洁的卡片式 UI 设计。

官方文档: https://butterfly.js.org/
GitHub: https://github.com/jerryc127/hexo-theme-butterfly
当前版本: 5.5.4

主题安装

方式一：npm 安装（推荐）

1
npm install hexo-theme-butterfly

升级方法：

1
npm update hexo-theme-butterfly

方式二：Git 安装

1
2
3
4
5
# 稳定版（推荐）
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

# 测试版
git clone -b dev https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

升级方法：在主题目录下运行 git pull

应用主题

修改 Hexo 根目录下的 _config.yml：

1
theme: butterfly

安装渲染插件

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

配置文件说明

配置文件优先级

Hexo 会自动合并主题配置，优先级从高到低：

  1. _config.butterfly.yml（根目录，推荐使用）
  2. themes/butterfly/_config.yml（主题目录）

建议: 在 Hexo 根目录创建 _config.butterfly.yml 文件，将主题配置放在这里，方便升级。

配置文件结构

1
2
3
4
5
6
HexoBlogDemo/
├── _config.yml              # Hexo 主配置
├── _config.butterfly.yml    # Butterfly 主题配置（推荐）
└── themes/
    └── butterfly/
        └── _config.yml      # 主题默认配置

导航栏配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
nav:
  # 导航栏 Logo 图片
  logo:
  
  # 是否显示网站标题
  display_title: true
  
  # 滚动时是否显示文章标题
  display_post_title: true
  
  # 是否固定导航栏
  fixed: true

# 菜单项配置
# 格式: 显示名称: 路径 || 图标类名
menu:
  Home: / || fas fa-home
  Archives: /archives/ || fas fa-archive
  Tags: /tags/ || fas fa-tags
  Categories: /categories/ || fas fa-th
  About: /about/ || fas fa-heart

图标说明

使用 Font Awesome 图标：https://fontawesome.com/icons

常用图标：

  • fas fa-home - 首页
  • fas fa-archive - 归档
  • fas fa-tags - 标签
  • fas fa-th - 分类
  • fas fa-heart - 关于
  • fas fa-user - 用户
  • fas fa-book - 书
  • fas fa-code - 代码

子菜单

1
2
3
4
menu:
  List||fas fa-list:
    Music: /music/ || fas fa-music
    Movies: /movies/ || fas fa-video

代码块配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
code_blocks:
  # 代码块主题: darker / pale night / light / ocean / false
  theme: light
  
  # 是否使用 Mac 风格窗口
  macStyle: false
  
  # 代码块高度限制（单位: px），false 不限制
  height_limit: false
  
  # 是否自动换行
  word_wrap: false

  # 工具栏设置
  copy: true           # 显示复制按钮
  language: true       # 显示语言标签
  shrink: false        # true: 收缩 | false: 展开 | none: 展开并隐藏按钮
  fullpage: false      # 显示全屏按钮

代码高亮配置

在 Hexo 根目录 _config.yml 中配置：

1
2
3
4
5
6
# 使用 PrismJS（推荐）
syntax_highlighter: prismjs
prismjs:
  preprocess: true
  line_number: true
  tab_replace: ''

图片配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# 网站图标
favicon: /img/favicon.png

# 头像设置
avatar:
  img: /img/my-avatar.png    # 头像图片
  effect: false               # 头像效果（鼠标悬停旋转）

# 禁用所有横幅图片
disable_top_img: false

# 默认横幅图片
default_top_img:

# 首页横幅图片
index_img: /img/bg.jpg

# 归档页横幅图片
archive_img:

# 标签页横幅图片
tag_img:

# 为每个标签设置横幅图片
tag_per_img:
  # - Hexo: /img/hexo.jpg
  # - AI: /img/ai.jpg

# 分类页横幅图片
category_img:

# 为每个分类设置横幅图片
category_per_img:
  # - 技术: /img/tech.jpg

# 页脚背景图片
footer_img: false

# 网站背景（支持颜色或图片）
background: /img/boat.jpg

封面设置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
cover:
  # 是否在首页显示封面
  index_enable: true
  
  # 是否在侧边栏显示封面
  aside_enable: true
  
  # 是否在归档页显示封面
  archives_enable: true
  
  # 首页封面位置: left / right / both
  position: both
  
  # 默认封面（未设置封面时显示）
  default_cover:
    # - /img/default-cover.jpg

错误图片

1
2
3
4
5
6
7
8
9
error_img:
  flink: /img/friend_404.gif     # 友情链接错误图片
  post_page: /img/404.jpg        # 文章页面错误图片

# 404 页面
error_404:
  enable: false
  subtitle: 'Page Not Found'
  background: /img/error-page.png

文章元数据配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
post_meta:
  # 首页文章元数据
  page:
    date_type: created      # 日期类型: created / updated / both
    date_format: date       # 日期格式: date / relative
    categories: true        # 显示分类
    tags: false             # 显示标签
    label: true             # 显示文字标签

  # 文章页元数据
  post:
    position: left          # 位置: left / center
    date_type: both         # 日期类型
    date_format: date       # 日期格式
    categories: true        # 显示分类
    tags: true              # 显示标签
    label: true             # 显示文字标签

首页配置

副标题打字效果

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
subtitle:
  enable: true
  
  # 打字机效果
  effect: true
  
  # 打字机配置
  typed_option:
    typeSpeed: 100         # 打字速度（越小越快）
    backSpeed: 50          # 删除速度
    loop: false            # 循环播放
    backDelay: 1000        # 打完停顿时间
    startDelay: 500        # 开始前延迟
  
  # 第三方 API（仅中文）
  # false: 禁用 | 1: hitokoto.cn | 2: yijuzhan.com | 3: jinrishici.com
  source: false
  
  # 副标题内容
  sub:
    - "Henry的技术小酒馆，séi来都得醉"

首页文章布局

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 布局方式
# 1: 行布局（封面左，信息右）
# 2: 行布局（封面右，信息左）
# 3: 行布局（封面和信息左右交替）
# 4: 列布局（封面上，信息下）
# 5: 信息显示在封面上
# 6: 瀑布流布局（封面上，信息下）
# 7: 瀑布流布局（信息显示在封面上）
index_layout: 3

# 首页文章简介
index_post_content:
  method: 3                # 1: 描述 | 2: 两者 | 3: 自动摘要 | false: 不显示
  length: 500              # 摘要长度

文章页配置

目录 (TOC)

1
2
3
4
5
6
7
toc:
  post: true               # 文章页显示目录
  page: false              # 页面不显示目录
  number: true             # 显示序号
  expand: false            # 默认展开
  style_simple: false      # 简洁风格（仅文章）
  scroll_percent: true     # 显示滚动百分比

版权声明

1
2
3
4
5
6
post_copyright:
  enable: true
  decode: false
  author_href:
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

打赏功能

1
2
3
4
5
6
7
8
9
10
reward:
  enable: false
  text:
  QR_code:
    - img: /img/wechat.jpg
      link:
      text: 微信
    - img: /img/alipay.jpg
      link:
      text: 支付宝

相关文章

1
2
3
4
related_post:
  enable: true
  limit: 6                 # 显示数量
  date_type: created       # created / updated

文章分页

1
2
3
4
# 1: 下一篇链接到旧文章
# 2: 下一篇链接到新文章
# false: 禁用分页
post_pagination: 1

过期提醒

1
2
3
4
5
6
7
noticeOutdate:
  enable: false
  style: flat              # simple / flat
  limit_day: 365           # 多少天后显示
  position: top            # top / bottom
  message_prev: It has been
  message_next: days since the last update, the content may be outdated.

页脚配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
footer:
  nav:                     # 页脚导航
  
  owner:
    enable: true
    since: 2026            # 网站创建年份
  
  copyright:
    enable: false
    version: false
  
  custom_text: |
    <a href="https://beian.miit.gov.cn/" target="_blank">陕ICP备XXXXXXXX号-1</a>
    <span class="footer-separator"> | </span>
    <a href="https://github.com/Dhongli" target="_blank">Henry Dai</a>
    <span class="footer-separator"> | </span>
    <a href="/" target="_blank">Copyright © 2026</a>

侧边栏配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
aside:
  enable: true
  hide: false              # 默认隐藏
  button: true             # 显示隐藏按钮
  mobile: true             # 移动端启用
  position: right          # left / right
  
  display:
    archive: true
    tag: true
    category: true

  # 作者卡片
  card_author:
    enable: true
    description:
    button:
      enable: true
      icon: fab fa-github
      text: Follow Me
      link: https://github.com/Dhongli

  # 公告卡片
  card_announcement:
    enable: true
    content: Henry的技术小酒馆，séi来都得醉

  # 最近文章
  card_recent_post:
    enable: true
    limit: 5
    sort: date             # date / updated
    sort_order:

  # 最新评论
  card_newest_comments:
    enable: false
    sort_order:
    limit: 6
    storage: 10            # 分钟，保存到 localStorage
    avatar: true

  # 分类卡片
  card_categories:
    enable: true
    limit: 8
    expand: none           # none / true / false
    sort_order:

  # 标签卡片
  card_tags:
    enable: true
    limit: 40
    color: false           # 启用颜色
    custom_colors:
    orderby: random        # random / name / length
    order: 1               # 1: 升序 / -1: 降序
    sort_order:

  # 归档卡片
  card_archives:
    enable: true
    type: monthly          # monthly / yearly
    format: MMMM YYYY
    order: -1
    limit: 8
    sort_order:

  # 网站信息卡片
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true
    sort_order:
    runtime_date:          # 运行时间起始日期

右下角按钮配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 简繁转换
translate:
  enable: false
  default: 繁
  defaultEncoding: 2       # 1: 繁体 / 2: 简体
  translateDelay: 0
  msgToTraditionalChinese: '繁'
  msgToSimplifiedChinese: '簡'

# 阅读模式
readmode: true

# 暗黑模式
darkmode:
  enable: true
  button: true
  # autoChangeMode: 1  跟随系统
  # autoChangeMode: 2  晚上6点到早上6点
  # autoChangeMode: false  不自动切换
  autoChangeMode: false
  start:
  end:

# 显示滚动百分比
rightside_scroll_percent: false

全局设置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 锚点
anchor:
  auto_update: false
  click_to_scroll: false

# 图片标题
photofigcaption: false

# 复制设置
copy:
  enable: true
  copyright:
    enable: false
    limit_count: 150

# 字数统计（需安装 hexo-wordcount）
wordcount:
  enable: false
  post_wordcount: true
  min2read: true
  total_wordcount: true

# 不蒜子统计
busuanzi:
  site_uv: true
  site_pv: true
  page_pv: true

数学公式配置

1
2
3
4
5
6
7
8
9
10
11
12
math:
  # 选择: mathjax / katex / 留空不启用
  use:
  per_page: true           # true: 每页加载 | false: 在 Front-matter 中设置
  hide_scrollbar: false

  mathjax:
    enableMenu: true
    tags: none             # all / ams / none

  katex:
    copy_tex: false

搜索配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
search:
  # 选择: algolia_search / local_search / docsearch / 留空不启用
  use: local_search
  placeholder: 搜索文章...
  placement: right         # left / right
  trigger: click           # click / hover

  # 本地搜索
  local_search:
    preload: true
    top_n_per_article: 1
    unescape: false
    pagination:
      enable: false
      hitsPerPage: 8
    CDN:

分享配置

1
2
3
4
5
6
7
8
9
share:
  # 选择: sharejs / addtoany / 留空不启用
  use: sharejs

  sharejs:
    sites: wechat,weibo,qq

  addtoany:
    item: facebook,x,wechat,sina_weibo,facebook_messenger,email,copy_link

评论系统配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
comments:
  # 最多两个评论系统，第一个为默认
  # 选择: Disqus/Disqusjs/Livere/Gitalk/Valine/Waline/Utterances/Facebook Comments/Twikoo/Giscus/Remark42/Artalk
  use:
  text: true
  lazyload: false
  count: false
  card_post_count: false

# Twikoo（推荐国内使用）
twikoo:
  envId:
  region:
  visitor: false
  option:

# Giscus（基于 GitHub Discussions）
giscus:
  repo:
  repo_id:
  category_id:
  light_theme: light
  dark_theme: dark
  js:
  option:

# Waline
waline:
  serverURL:
  bg:
  pageview: false
  option:

统计分析配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 百度统计
baidu_analytics:

# Google 分析
google_analytics:

# Cloudflare 分析
cloudflare_analytics:

# Microsoft Clarity
microsoft_clarity:

# Umami（自托管）
umami_analytics:
  enable: false
  serverURL:
  script_name: script.js
  website_id:
  option:
  UV_PV:
    site_uv: false
    site_pv: false
    page_pv: false
    token:

CDN 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
CDN:
  # 内部脚本: local / jsdelivr / unpkg / cdnjs / custom
  internal_provider: local
  
  # 第三方脚本: local / jsdelivr / unpkg / cdnjs / custom
  third_party_provider: jsdelivr
  
  # URL 是否添加版本号
  version: true
  
  # 自定义格式
  # 例如: https://cdn.staticfile.org/${cdnjs_name}/${version}/${min_cdnjs_file}
  custom_format:
  
  option:
    # 可以单独配置每个库的 CDN
    # fancybox: https://cdn.example.com/fancybox.js

自定义注入

1
2
3
4
5
6
7
8
9
inject:
  # 在 </head> 前注入
  head:
    - <link rel="stylesheet" href="/css/custom.css">
    # - <meta name="keywords" content="xxx">
  
  # 在 </body> 前注入
  bottom:
    - <script src="/js/custom.js"></script>

背景特效配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# Canvas Ribbon（丝带）
canvas_ribbon:
  enable: false
  size: 150
  alpha: 0.6
  zIndex: -1
  click_to_change: false
  mobile: false

# Canvas Nest（网格）
canvas_nest:
  enable: false
  color: '100,100,100'
  opacity: 0.25
  zIndex: -1
  count: 99
  mobile: false

# 烟花效果
fireworks:
  enable: false
  zIndex: 9999
  mobile: false

# 鼠标点击爱心
click_heart:
  enable: false
  mobile: false

# 鼠标点击文字
clickShowText:
  enable: false
  text:
    # - I
    # - LOVE
    # - YOU
  fontSize: 15px
  random: false
  mobile: false

其他配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
# Pjax（无刷新加载）
pjax:
  enable: false
  exclude:

# 图片灯箱
lightbox:
  # 选择: fancybox / medium_zoom / 留空不启用

# 标签外挂
note:
  style: flat              # simple / modern / flat / disabled
  icons: true
  border_radius: 3
  light_bg_offset: 0

# Mermaid 图表
mermaid:
  enable: false
  code_write: false
  theme:
    light: default
    dark: dark
  open_in_new_tab: true
  zoom_pan: true

# 懒加载
lazyload:
  enable: false
  native: false
  field: site
  placeholder:
  blur: false

# PWA
pwa:
  enable: false
  manifest:
  apple_touch_icon:
  favicon_32_32:
  favicon_16_16:
  mask_icon:

# Open Graph
Open_Graph_meta:
  enable: true
  option:

# 结构化数据
structured_data:
  enable: false
  alternate_name:

# CSS 前缀
css_prefix: true

# 加载动画
preloader:
  enable: false
  source: 1                # 1: fullpage-loading | 2: pace

# 页面过渡
enter_transitions: true

# 默认显示模式: light / dark
display_mode: light

常用主题页面

友情链接页

1
hexo new page "link"

编辑 source/link/index.md：

1
2
3
4
5
---
title: 友情链接
date: 2026-06-19
type: "link"
---

图库页

1
hexo new page "Gallery"

说说页

1
hexo new page "talking"

升级注意事项

  1. 备份配置: 升级前备份 _config.butterfly.yml
  2. 查看更新日志: https://butterfly.js.org/posts/198a4240/
  3. 合并配置: 新版本可能有配置变更，需要手动合并
  4. 测试: 升级后本地测试确认无误再部署

参考资源