本文转载自Hexo博客搭建教程，感谢原作者的无私分享。

阅读本篇前，请先阅读前面的文章
blog搭建基础教程（一）
blog搭建基础教程（二）

一.前言

快过年啦！祝大家2026年新年快乐！马年大吉！

小崔也是最近才开始搭建属于自己的博客，感觉挺有意思的哈哈哈哈。到现在嘞已经搭建的差不多啦，就想着闲着也是闲着，不如总结一下自己搭建从0到1的全过程，也算是巩固巩固嘿嘿嘿~
本教程几乎为转载内容，原文链接在前言中。由于原作者的教程可能比较久远了，在这里可能部分地方做了一些改进与补充，供大家参考。
最后，让我们一起搭建一款独属于自己的博客网站吧！
文章可能有的地方会出现错字，属于正常现象，不影响阅读。

二.语言

修改站点配置文件_config.yml，默认语言是en 。
主题支持三种语言：

  • default(en)
  • zh-CN (简体中文)
  • zh-TW (繁体中文)

三.网站资料

修改网站各种资料，例如标题、副标题和邮箱等个人资料，请修改站点配置文件_config.yml。
推荐参考文档：Hexo博客搭建教程-主题配置参考文档

四.导航菜单

修改主题配置文件_config.butterfly.yml，找到menu:字段，按照格式添加或修改导航菜单。字体图标可以在Font Awesome中查找。

1
2
3
4
5
6
7
8
9
10
11
menu:
  首页: / || fas fa-home
  时间轴: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder-open
  清单||fa fa-heartbeat:
    音乐: /music/ || fas fa-music
    照片: /Gallery/ || fas fa-images
    电影: /movies/ || fas fa-video
  友链: /link/ || fas fa-link
  关于: /about/ || fas fa-heart

五.代码

1.代码高亮主题

截止目前Butterfly支持6 种代码高亮样式：

  • darker
  • pale night
  • light
  • ocean
  • mac
  • mac light

修改主题配置文件_config.butterfly.yml，找到highlight_theme:字段，修改为你喜欢的代码高亮样式。

1
2
示例：
highlight_theme: darker  //具体可以修改为你喜欢的样式

2.代码复制

修改主题配置文件_config.butterfly.yml中的highlight_copy:字段，将其值修改为true，表示可以复制代码。

1
highlight_copy: true

3.代码框展开/关闭

修改主题配置文件_config.butterfly.yml中的highlight_shrink字段，将其值修改为true，表示可以展开/关闭代码框。

1
highlight_shrink: true #代码框不展开，需点击 '>' 打开

在默认情况下，代码框自动展开，可设置是否所有代码框都关闭状态，点击>可展开代码。

  • true 全部代码框不展开，需点击>打开
  • 代码框展开，有>点击按钮
  • none 不显示>按钮

4.代码换行

在默认情况下，Hexo 在编译的时候不会实现代码自动换行。如果你不希望在代码块的区域里有横向滚动条的话，那么你可以考虑开启这个功能。
修改主题配置文件_config.butterfly.yml，找到highlight_break:字段，将其值修改为true，表示可以换行。

1
highlight_break: true #代码换行

5.代码高度限制

可配置代码高度限制，超出的部分会隐藏，并显示展开按钮。

1
highlight_height_limit: false # unit: px
  • 单位是px，直接添加数字，如 200
  • 实际限制高度为highlight_height_limit + 30 px，多增加 30px 限制，目的是避免代码高度只超出
    highlight_height_limit一点时，出现展开按钮，展开没内容。
  • 不适用于隐藏后的代码块（ css 设置 display: none）。

六.社交图标

Butterfly支持font-awesome v6图标。
书写格式：图标名：url || 描述性文字。

1
2
3
4
social:
  fab fa-github: https://github.com/xxxxx || Github
  fas fa-envelope: mailto:xxxxxx@gmail.com || Email
image-20221029173631192

七.顶部图

如果不要显示顶部图，可直接配置 disable_top_img: true。
修改主题配置文件_config.butterfly.yml,其它页面 （tags/categories/自建页面）和文章页的top_img，请到对应的
md页面设置front-matter中的top_img。

1
index_img: xxx.png

八.文章置顶与封面

1.你可以直接在文章的front-matter区域里添加sticky: 1属性来把这篇文章置顶。数值越大，置顶的优先级越大。
2.文章的markdown文档上，在Front-matter添加cover，并填上要显示的图片地址。如果不配置cover，可以设置显示默认的cover；如果不想在首页显示cover，可以设置为false。
3.修改主题配置文件_config.butterfly.yml,找到cover:字段，将其值修改为true，表示可以显示封面。

1
2
3
4
5
6
7
8
9
10
11
cover:
  # 是否显示文章封面
  index_enable: true
  aside_enable: true
  archives_enable: true
  # 封面显示的位置
  # 三个值可配置 left , right , both
  position: both
  # 当没有设置cover时，默认的封面显示
  default_cover: 
    - /img/cover.jpg

当配置多张图片时，会随机选择一张作为cover，此时写法应为：

1
2
3
4
default_cover: 
  - /img/cover1.jpg
  - /img/cover2.jpg
  - /img/cover3.jpg

九.文章页相关配置

1.文章meta显示

post_meta这个属性用于显示文章的相关信息的，修改主题配置文件_config.butterfly.yml。

1
2
3
4
5
6
7
8
9
10
11
12
13
post_meta:
  page:
    date_type: both # created or updated or both 主页文章日期是创建日或者更新日或都显示
    date_format: relative # date/relative 显示日期还是相对日期
    categories: true # true or false 主页是否显示分类
    tags: true # true or false 主页是否显示标签
    label: true # true or false 显示描述性文字
  post:
    date_type: both # created or updated or both 文章页日期是创建日或者更新日或都显示
    date_format: relative # date/relative 显示日期还是相对日期
    categories: true # true or false 文章页是否显示分类
    tags: true # true or false 文章页是否显示标签
    label: true # true or false 显示描述性文字

2.文章版权和协议许可

修改主题配置文件_config.butterfly.yml，找到post_copyright:字段，将其值修改为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/

由于Hexo 4.1开始，默认对网址进行解码，以至于如果是中文网址，会被解码，可设置decode: true来显示中文网址。如果有文章（例如：转载文章）不需要显示版权，可以在文章页Front-matter中单独设置。

1
copyright: false

从v3.0.0开始，支持对单独文章设置版权信息，可以在文章Front-matter单独设置。

1
2
3
4
5
6
post_copyright:
copyright_author: xxxx
copyright_author_href: https://xxxxxx.com
copyright_url: https://xxxxxx.com
copyright_info: 此文章版权归xxxxx所有，如有转载，请註明来自原作者
image-20221029173741784

3.文章打赏

修改主题配置文件_config.butterfly.yml，找到post_reward:字段，将其值修改为true，表示可以显示文章打赏。

1
2
3
4
5
6
7
8
9
reward:
  enable: false
  QR_code:
    - img: /img/wechat.jpg
      link:
      text: wechat
    - img: /img/alipay.jpg
      link:
      text: alipay

4.文章目录TOC

修改主题配置文件_config.butterfly.yml，找到post_toc:字段，将其值修改为true，表示可以显示文章目录。

1
2
3
4
5
6
7
toc:
  post: true # 文章页是否显示 TOC
  page: false # 普通页面是否显示 TOC
  number: true # 是否显示章节数
  expand: false# 是否展开 TOC
  style_simple: false # for post 简洁模式（侧边栏只显示 TOC, 只对文章页有效 ）
image-20221029173812311

5.相关文章推荐

修改主题配置文件_config.butterfly.yml，找到post_related:字段，将其值修改为true，表示可以显示相关文章推荐。

1
2
3
4
related_post:
  enable: true
  limit: 6 # 显示推荐文章数目
  date_type: created # or created or updated 文章日期显示创建日或者更新日

6.文章分页按钮

修改主题配置文件_config.butterfly.yml，找到post_pagination:字段，将其值修改为true，表示可以显示文章分页按钮。

1
2
3
4
5
6
7
# post_pagination (分页)
# value: 1 || 2 || false# false:为关闭分页按钮；1:下一篇显示的是旧文章；2:下一篇显示的是新文章
# 1: The 'next post' will link to old post
# 2: The 'next post' will link to new post
# false: disable pagination
post_pagination: false
image-20221029173929409

十.头像

修改主题配置文件_config.butterfly.yml，找到avatar:字段，将其值修改为头像的地址。

1
2
3
4
avatar:
  img: /assets/head.jpg
  effect: false # true则会一直转圈
image-20221028141401289

十一.文章内容复制相关配置

修改主题配置文件_config.butterfly.yml，找到post_copy:字段，将其值修改为true，表示可以显示文章内容复制按钮。

1
2
3
4
5
6
7
# copy settings
# copyright: Add the copyright information after copied content (复制的内容后面加上版权信息)
copy:
  enable: true# 是否开启网站复制权限
  copyright:# 复制的内容后面加上版权信息
    enable: true# 是否开启复制版权信息添加
    limit_count: 50# 字数限制，当复制文字大于这个字数限制时，将在复制的内容后面加上版权信息

修改主题配置文件_config.butterfly.yml，找到footer:字段，将其值修改为你喜欢的Footer内容。

1
2
3
4
5
6
footer:
  owner:
    enable: true
    since: 2022# 站点起始时间
  custom_text:# 是一个给你用来在页脚自定义文本的选项。通常你可以在这里写声明文本等,支持 HTML。
  copyright: false # Copyright of theme and framework

十三.右下角按钮

1.繁简体转换

修改主题配置文件_config.butterfly.yml，找到bottom_right:字段，将其值修改为你喜欢的右下角按钮内容。

1
2
3
4
5
6
7
8
9
10
11
12
13
translate:
  enable: false
  # 默认按钮显示文字(网站是简体，应设置为'default: 繁')
  default: 繁
  # the language of website (1 - Traditional Chinese/ 2 - Simplified Chinese）
  # 网站默认语言，1: 繁体中文, 2: 简体中文
  defaultEncoding: 2
  # Time delay 延迟时间,若不在前, 要设定延迟翻译时间, 如100表示100ms,默认为0
  translateDelay: 0
  # 当文字是简体时，按钮显示的文字
  msgToTraditionalChinese: '繁'
  # 当文字是繁体时，按钮显示的文字
  msgToSimplifiedChinese: '簡'

2.夜间模式

修改主题配置文件_config.butterfly.yml，找到bottom_right:字段，将其值修改为你喜欢的右下角按钮内容。

1
2
3
4
5
6
7
8
9
10
11
# dark mode
darkmode:
  enable: false
  # dark 和 light 两种模式切换按钮
  button: true
  # Switch dark/light mode automatically (自動切換 dark mode和 light mode)
  # autoChangeMode: 1  Following System Settings, if the system doesn't support 
  dark mode, it will switch dark mode between 6 pm to 6 am
  # autoChangeMode: 2  Switch dark mode between 6 pm to 6 am
  # autoChangeMode: false
  autoChangeMode: false

3.阅读模式

阅读模式下会去掉除文章外的内容，避免干扰阅读。只会出现在文章页面，右下角会有阅读模式按钮。修改主题配置文件_config.butterfly.yml，找到bottom_right:字段，将其值修改为你喜欢的右下角按钮内容。

1
readmode: true

十四.侧边栏设置

1.排版

可自行决定哪个项目需要显示，可决定位置，也可以设置不显示侧边栏。修改主题配置文件_config.butterfly.yml，下面是本人博客的配置项可以参考

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
aside:
  enable: true
  hide: false
  button: true
  mobile: true # display on mobile
  position: right # left or right
  display:
    archive: true
    tag: true
    category: true
  card_author:
    enable: true
    description:
    button:
      enable: true
      icon: # fab fa-github
      text: 🛴前往小家...
      link: https://github.com/fomalhaut1998
  card_announcement:
    enable: true
    content: <center>主域名：<br><a href="https://www.fomal.cc"><b><font color="#5ea6e5">
    fomal.cc</font></b></a>&nbsp;|&nbsp;<a href="https://www.fomal.cn"><b><font 
    color="#5ea6e5">fomal.cn</font></b></a><br>备用域名：<br><a 
    href="https://blog.fomal.cc"><b><font color="#5ea6e5">blog.fomal.cc</font></b>
    </a><br><a href="https://aa.fomal.cc"><b><font color="#5ea6e5">aa.fomal.cc
    </font></b></a><br><a href="https://bb.fomal.cc"><b><font color="#5ea6e5">
    bb.fomal.cc</font></b></a><br><a href="mailto:admin@fomal.cn">📬：<b><font color="#a591e0">admin@fomal.cn</font></b></a></center>
  card_recent_post:
    enable: false
    limit: 3 # if set 0 will show all
    sort: date # date or updated
    sort_order: # Don't modify the setting unless you know how it works
  card_categories:
    enable: false
    limit: 8 # if set 0 will show all
    expand: none # none/true/false
    sort_order: # Don't modify the setting unless you know how it works
  card_tags:
    enable: false
    limit: 20 # if set 0 will show all
    color: true
    sort_order: # Don't modify the setting unless you know how it works
  card_archives:
    enable: false
    type: monthly # yearly or monthly
    format: MMMM YYYY # eg: YYYY年MM月
    order: -1 # Sort of order. 1, asc for ascending; -1, desc for descending
    limit: 8 # if set 0 will show all
    sort_order: # Don't modify the setting unless you know how it works
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true
    sort_order: # Don't modify the setting unless you know how it works
  card_weibo:
    enable: true

2.访问人数

修改主题配置文件_config.butterfly.yml，找到aside:字段，找到card_webinfo:字段，将其值修改为true，表示可以显示访问人数。

1
2
3
4
busuanzi:
  site_uv: true  # 本站总访客数
  site_pv: true  # 本站总访问量 
  page_pv: true  # 本文总阅读量

3.最新评论

v3.1.0 以上支持。如果未配置任何评论，前先不要开启该功能。

修改主题配置文件_config.butterfly.yml，找到aside:字段，找到card_recent_comments:字段，将其值修改为true，表示可以显示最新评论。

1
2
3
4
card_recent_comments:
  enable: true
  limit: 5 # if set 0 will show all
  sort_order: # Don't modify the setting unless you know how it works

十五.网站背景

修改主题配置文件_config.butterfly.yml，找到background:字段，将其值修改为你喜欢的背景图片地址。

1
2
3
4
# 图片格式 url(http://xxxxxx.com/xxx.jpg)
# 颜色（HEX值/RGB值/颜色单词/渐变色)
# 留空 不显示背景
background: url(https://source.fomal.cc/img/dm1.webp)

如果你的网站根目录不是'/'，使用本地图片时，需加上你的根目录。
例如：网站是 https://yoursite.com/blog，引用一张img/xx.png图片，则设置background为 url(/blog/img/xx.png)

十六.打字效果

详见打字效果配置教程

打字效果是指在输入文字时，屏幕上会出现一些特效，例如火花、爆炸等。这个功能可以让你的网站更加生动有趣。修改主题配置文件_config.butterfly.yml，找到activate_power_mode:字段，将其值修改为true，表示可以开启打字效果。

1
2
3
4
5
6
7
# Typewriter Effect (打字效果)
# https://github.com/disjukr/activate-power-mode
activate_power_mode:
  enable: false
  colorful: true # open particle animation (冒光特效)
  shake: true #  open shake (抖動特效)
  mobile: false

修改主题配置文件_config.butterfly.yml，找到footer:字段，找到background:字段，将其值修改为你喜欢的背景图片地址。

1
2
# footer是否显示图片背景(与top_img一致)
footer_bg: true

十八.背景特效

可设置每次刷新更换彩带，或者每次点击更换彩带。详细配置可查看背景特效详细教学
修改主题配置文件_config.butterfly.yml，找到canvas_ribbon:字段，将其值修改为true，表示可以开启背景特效。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# one.彩带背景特效(静止)
canvas_ribbon:
  enable: false
  size: 150
  alpha: 0.6
  zIndex: -1
  click_to_change: false  #設置是否每次點擊都更換彩带
  mobile: false # false 手機端不顯示 true 手機端顯示

# two.彩带背景特效(动态)

canvas_fluttering_ribbon:
  enable: true
  mobile: true # false 手机端不显示 true 手机端显示

十九.鼠标点击效果

zIndex建议只在-1和9999上选。-1代表烟火效果在底部。9999代表烟火效果在前面。
修改主题配置文件_config.butterfly.yml，找到canvas_fireworks:字段，将其值修改为true，表示可以开启鼠标点击效果。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# one.鼠标点击烟花特效
fireworks:
  enable: true
  zIndex: 9999 # -1 or 9999
  mobile: false

# two.鼠标点击心形特效
# 点击出現爱心
click_heart:
  enable: true
  mobile: false

# three.鼠标点击文字特效
# 点击出现文字，文字可自行修改
ClickShowText:
  enable: false
  text:
    - I
    - LOVE
    - YOU
  fontSize: 15px
  random: false # 文字随机显示
  mobile: false

二十.自定义字体和字体大小

修改主题配置文件_config.butterfly.yml，找到font:字段，将其值修改为你喜欢的字体。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Global font settings
# Don't modify the following settings unless you know how they work (非必要不要修改)
font:
  global-font-size: '15px'
  code-font-size: '14px'
  # -apple-system, BlinkMacSystemFont, "Segoe UI" , "Helvetica Neue" , Lato, Roboto,
  "PingFang SC" , "Microsoft JhengHei" , "Microsoft YaHei" , sans-serif
  # Wenkai, consolas, -apple-system, 'Quicksand', 'Nimbus Roman No9 L', 
  'PingFang SC','Hiragino Sans GB', 'Noto Serif SC', 'Microsoft Yahei', 
  'WenQuanYi Micro Hei', 'ST Heiti', sans-serif;
  font-family: var(--global-font), Consolas_1, -apple-system, 'Quicksand', 
  'Nimbus Roman No9 L', 'PingFang SC', 'Hiragino Sans GB', 'Noto Serif SC', 
  'Microsoft Yahei', 'WenQuanYi Micro Hei', 'ST Heiti', sans-serif;
  # consolas, ZhuZiAWan_light, "Microsoft YaHei", Menlo, "PingFang SC", 
  "Microsoft JhengHei", sans-serif# Consolas_1, ZhuZiAWan_light, 
  "Microsoft YaHei", Menlo, "PingFang SC", "Microsoft JhengHei", sans-serif
  code-font-family: Consolas_1, var(--global-font), "Microsoft YaHei", Menlo, 
  "PingFang SC", "Microsoft JhengHei", sans-serif

二十一.网站副标题

可设置主页中显示的网站副标题或者喜欢的座右铭。修改主题配置文件_config.butterfly.yml，找到subtitle:字段，将其值修改为你喜欢的副标题。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# the subtitle on homepage (主頁subtitle)
subtitle:
  enable: true
  # Typewriter Effect (打字效果)
  effect: true
  # loop (循環打字)
  loop: true
  # source 調用第三方服務
  # source: false 關閉調用
  # source: 1  調用一言網的一句話（簡體） https://hitokoto.cn/
  # source: 2  調用一句網（簡體） http://yijuzhan.com/
  # source: 3  調用今日詩詞（簡體） https://www.jinrishici.com/
  # subtitle 會先顯示 source , 再顯示 sub 的內容
  source: false
  # 如果關閉打字效果，subtitle 只會顯示 sub 的第一行文字
  sub:
    - "Welcome to Fomalhaut🥝のTiny Home!🤣🤣🤣"
    - "Hope you have a nice day!🍭🍭🍭"

二十二.页面加载动画

当进入网页时，因为加载速度的问题，可能会导致top_img图片出现断层显示，或者网页加载不全而出现等待时间，开启preloader后，会显示加载动画，等页面加载完，加载动画会消失。修改主题配置文件_config.butterfly.yml，找到preloader:字段，将其值修改为true，表示可以开启页面加载动画。

1
2
# 加载动画 Loading Animation
preloader: true

二十三.字数统计

注意必须要安装依赖才能设置为true，否则会报错！

  • 安装插件：在你的博客根目录，打开cmd命令窗口执行npm install hexo-wordcount --save。
  • 开启配置：修改主题配置文件_config.butterfly.yml中的wordcount。
1
npm install hexo-wordcount --save
1
2
3
4
5
wordcount:
  enable: true
  post_wordcount: true
  min2read: true
  total_wordcount: true

二十四.图片大图查看模式

只能开启一个。
如果你并不想为某张图片添加大图查看模式，你可以使用 html 格式引用图片，并为图片添加no-lightbox class 名，例如：
<img src="xxxx.jpg" class="no-lightbox">。修改主题配置文件_config.butterfly.yml，找到lightbox:字段，将其值修改为你喜欢的图片大图查看模式。

1
修改主题配置文件_config.butterfly.yml中fancybox属性

二十五.Pjax

当用户点击链接，通过Pjax更新页面需要变化的部分，然后使用 HTML5 的pushState修改浏览器的URL地址。这样可以不用重复加载相同的资源
（css/js）， 从而提升网页的加载速度。注意：使用 Pjax 后，一些自己DIY的js可能会无效，跳转页面时需要重新调用（例如朋友圈、说说等），具体请参考
Pjax文档。
修改主题配置文件_config.butterfly.yml，找到pjax:字段，将其值修改为true，表示可以开启Pjax。

1
2
3
4
5
6
7
8
9
10
11
# Pjax [Beta]
# It may contain bugs and unstable, give feedback when you find the bugs.
# https://github.com/MoOx/pjax
pjax: 
  enable: true
  # 对于一些第三方插件，有些并不支持 pjax 。
  # 你可以把网页加入到 exclude 里，这个网页会被 pjax 排除在外。
  # 点击该网页会重新加载网站。
  exclude: 
    - /music/
    - /no-pjax/

二十六.Inject

你可以通过 Inject 功能向网页注入自定义代码，例如添加第三方统计代码、广告代码等。修改主题配置文件_config.butterfly.yml，找到inject:字段，根据需要添加代码。

1
2
3
4
5
6
7
8
9
# Inject
# Insert the code to head (before '</head>' tag) and the bottom (before '</body>'
tag)
# 插入代码到头部 </head> 之前 和 底部 </body> 之前
inject:
  head:
    - <link rel="stylesheet" href="/xxx.css">
  bottom:
    - <script src="xxxx"></script>

二十七.本地搜索系统

1.安装依赖：前往博客根目录，打开cmd命令窗口执行npm install hexo-generator-search --save

2.注入配置：修改站点配置文件_config.yml，添加如下代码：表示可以开启本地搜索系统。

1
2
3
4
search:
  path: search.xml
  field: post
  content: true

3.主题中开启搜索：在主题配置文件_config.butterfly.yml中修改以下内容：

1
2
3
local_search:
-  enable: false
+  enable: true

4.重新编译运行，即可看到效果：前往博客根目录，打开cmd命令窗口依次执行如下命令：

1
2
hexo cl && hexo generate
hexo s -p 8000

详情可参考 hexo-generator-search

OK老铁！恭喜你，已成功搭建了一款属于自己的静态博客，但是你可能会发现，截止目前你所搭建的博客跟别人一对比好像还缺少了点什么，比如评论系统、动态背景图、电子桌宠、赛博特效、音乐插件、自定义字体······
没错！你只是刚刚踏进赛博空间搭建的大门~~~
接下来就是博客的进阶教程啦，也就是传说中的“魔改”,是不是很期待？
小崔我还得参谋参谋，魔改文档放在这里，感兴趣的小伙伴阔以直接冲，最后祝大家都能搭建出一款独具风格的私人博客！

本文转载自Hexo博客搭建教程，感谢原作者的无私分享。