Butterfly 是 Hexo 里配置最细致的主题之一，好处是几乎什么都能改，代价是配置文件长得让人迷路。这篇把常用改动按「改哪里 → 改什么 → 效果」的方式记下来，配的正是本站（Butterfly 4.x）。

一、先分清两个配置文件

新手最容易改错文件，先记住这张表：

文件 管什么 什么时候动
_config.yml 站点：标题、作者、URL、部署、插件 换域名、改部署、装插件时
_config.butterfly.yml 主题外观：导航、配色、侧边栏、评论 改样式、加功能时

主题配置要放在 _config.butterfly.yml（根目录），不要直接改 themes/butterfly/_config.yml —— 主题一升级就会被覆盖，改动全丢。

改完记得重新生成：

1
npx hexo clean && npx hexo generate && npx hexo server   # 本地预览 http://localhost:4000

二、搜索功能配置

Butterfly 内置三种搜索方案，按推荐度排序：

零依赖、最省心，文章量在几百篇以内足够用。

  1. 安装生成索引的插件：
1
npm install hexo-generator-search --save
  1. 在 _config.butterfly.yml 里开启：
1
2
3
4
local_search:
  enable: true
  preload: true          # 进入页面就预加载索引
  top_n_per_article: 1
  1. 站点 _config.yml 补上生成器配置（默认一般即可）：
1
2
3
4
search:
  path: search.xml
  field: post            # 可选 post / page / all
  content: true

搜索体验最好（实时、支持高亮），但需要注册账号并每次部署上传索引，配置稍繁琐。

1
npm install hexo-algoliasearch --save
1
2
3
4
algolia_search:
  enable: true
  hits:
    per_page: 6
1
2
3
4
5
# 站点 _config.yml
algolia:
  appId: '你的 appId'
  apiKey: '你的 apiKey'
  indexName: '你的 indexName'

部署前需要执行 hexo algolia 上传索引（要配 HEXO_ALGOLIA_INDEXING_KEY 环境变量）。

Algolia 官方为开源文档提供的免费搜索服务，需申请通过（站点需公开且内容合规）。原笔记里记的就是它：

  1. 在 _config.butterfly.yml 中加入：
1
2
3
4
5
6
docsearch:
  enable: false
  appId:
  apiKey:
  indexName:
  option:
  1. 到 DocSearch 官网 提交申请，通过后 Algolia 会把 appId / apiKey / indexName 发到你的邮箱
  2. 填进上面的配置并把 enable 改为 true

DocSearch 靠爬虫抓取线上站点建索引，所以必须先把博客部署到公网并提交申请；本地 hexo server 是测不出搜索结果的。

三、导航菜单

1
2
3
4
5
6
7
8
menu:
  首页: / || fas fa-home
  归档: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder-open
  追番: /bangumis/ || fas fa-film
  友链: /link/ || fas fa-link
  关于: /about/ || fas fa-heart

格式是 显示名: 路径 || 图标类名。图标从 Font Awesome 找，写完整类名即可。

菜单里的路径必须有对应页面，否则点进去是 404。创建页面用：

1
2
3
npx hexo new page categories
npx hexo new page tags
npx hexo new page link

会在 source/categories/index.md 生成页面，确认里面的 type 字段正确：

1
2
3
4
---
title: 文章分类
type: "categories"      # tags 页写 "tags"，友链页写 "link"
---

四、站点基础信息

_config.yml（站点配置）：

1
2
3
4
5
6
7
title: 你的站名
subtitle: 副标题
description: 站点描述（SEO 与分享卡片会用到）
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai
url: https://www.example.com      # ⭐ 必须带 https，否则生成的 sitemap 链接不对

url 一定要和最终访问域名完全一致（含 www 与否）。它决定 sitemap、RSS、文章永久链接，填错会让百度收录失败。

五、头图、封面与头像

1
2
3
4
5
6
7
8
9
10
11
12
13
# _config.butterfly.yml
avatar:
  img: /img/avatar.png
  effect: true          # 鼠标悬停时头像旋转

index_img: /img/home.jpg           # 首页顶部大图
default_top_img: /img/default.jpg  # 没指定 cover 的文章用这张
archive_img: /img/archive.jpg      # 归档页头图

cover:
  index_enable: true
  aside_enable: true               # 侧栏最新文章是否显示缩略图
  archives_enable: true

单篇文章指定封面（front-matter）：

1
2
3
4
---
title: 文章标题
cover: /img/cover.jpg
---

头图建议尺寸 1920×1080 左右、控制在 300KB 以内。太大的话首屏会先白一下，体验很差。统一裁成相同比例，翻页时观感更整齐。

六、侧边栏卡片

aside 控制侧栏显示哪些卡片及排序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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: 一句自我介绍
  card_announcement:
    enable: true
    content: 公告内容，支持 HTML
  card_recent_post:
    enable: true
    limit: 5
  card_newest_comments:
    enable: false         # 需要评论系统支持
  card_tags / card_categories / card_webinfo ...

card_webinfo 能显示运行时间、文章字数、访问量（访问量需配合不蒜子等统计）。

七、评论系统

本站用的是 Twikoo（免费、基于云函数、国内访问快）：

1
2
3
4
5
6
7
8
9
10
comments:
  use: Twikoo        # 多个用数组： - Twikoo
  text: true
  lazyload: true     # 滚动到评论区才加载，提速
  count: true        # 文章列表显示评论数

twikoo:
  envId: https://xxx.vercel.app     # 你部署的云函数地址
  region:
  visitor: true

其它可选方案对比：

方案 优点 缺点
Twikoo 免费、部署简单、支持邮件通知 依赖云函数（Vercel / 腾讯云）
Waline 界面现代、支持多数据库 同样需服务端
Giscus 基于 GitHub Discussions，零后端 评论者需 GitHub 账号
Disqus 老牌、功能全 国内访问不稳定

八、代码高亮与代码块

1
2
3
4
5
6
7
8
9
10
11
highlight:
  enable: true
  line_number: true         # 显示行号
  auto_detect: false
  tab_replace:
  wrap: true                # 代码过长自动换行还是横向滚动
  height_limit: false       # 也可写 300，超出折叠
  theme: mac                # 代码块顶部的样式风格

prismjs:
  enable: false             # 与 highlight 二选一

美化代码块（本站用的这类效果）可以写在自定义 CSS 里：

1
2
3
4
5
/* source/css/custom.css */
#article-container figure.highlight {
  border-radius: 12px;
  box-shadow: 0 4px 16px rgba(0, 0, 0, .06);
}

九、主题色与深色模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
theme_color:
  enable: true
  main: "#5b5bd6"            # 主色调，全站按钮/链接/下划线都会跟着变
  paginator: "#5b5bd6"
  button_hover: "#ff7242"
  text_selection: true
  link_color: "#5b5bd6"
  meta_color: "#858585"

darkmode:
  enable: true
  start: 0                   # 0:00 开始
  end: 6                     # 6:00 结束
  autoChangeMode: false      # true = 跟随系统/时间自动切换

改主色最快的方式就是 theme_color.main 一个值。想做更细的定制（比如三档主题切换），可以用 CSS 变量覆盖 + 注入 JS，参考本站 source/css/theme-tri.css 的做法，不动主题源文件。

十、自定义 CSS / JS（关键技能）

想改样式但不想动主题源码，用注入：

1
2
3
4
5
inject:
  head:
    - <link rel="stylesheet" href="/css/custom.css">
  bottom:
    - <script src="/js/custom.js"></script>

对应文件放在 source/css/ 和 source/js/，Hexo 会原样拷贝到 public/。

CSS 覆盖不生效时的排查顺序：

  1. 文件是否真的被引用（看页面源码里有没有这个 <link>）
  2. 加载顺序 —— 自定义 CSS 必须在主题 CSS 之后
  3. 选择器特异性不够 —— 去 public/css/index.css 里搜原规则，看它用了几层选择器，照着补齐（比如主题写 #nav .site-page:not(.child):after，你只写 #nav .site-page::after 就压不过它）
  4. 浏览器缓存 —— 强制刷新 Cmd + Shift + R

十一、常用功能开关速查

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
# 文章相关
post_meta:                # 文章 meta 信息显示哪些
  post: true              # 作者、日期、分类
  categories: true
  tags: true
  date_type: created      # created / updated

toc:                      # 文章目录
  enable: true
  number: false
  expand: true

related_post:             # 相关文章推荐
  enable: true
  limit: 6

wordcount:                # 字数统计（需装 hexo-wordcount）
  enable: true

# 效果类
beautify:
  enable: true
  field: post             # site / post
  title-prefix-icon: '\f0c1'
  title-prefix-icon-color: '#5b5bd6'

anchor:                   # 标题锚点
  enable: true

lazyload:                 # 图片懒加载
  enable: true
  field: site
  placeholder:
  blur: false

pjax:
  enable: true            # 站内跳转无刷新，体感更快

十二、值得装的插件

插件 作用
hexo-abbrlink 生成短链接（/posts/xxxx.html），比中文路径友好
hexo-wordcount 字数与阅读时长统计
hexo-generator-sitemap / hexo-generator-baidu-sitemap 生成 sitemap，提交搜索引擎用
hexo-bilibili-bangumi 追番页面
hexo-butterfly-swiper 首页轮播图（本站用了 swiper_index）
hexo-filter-nofollow 外链加 nofollow，有利于 SEO 
1
npm install hexo-abbrlink hexo-wordcount hexo-generator-sitemap --save

十三、常见坑

现象 原因 解法
改了配置没生效 没执行 hexo clean 清缓存后重新生成
菜单点进去 404 没创建对应 page hexo new page xxx
样式改了不生效 选择器特异性不够 / 缓存 见第十节排查顺序
部署后文章链接变了 permalink 或 abbrlink 配置变了 改链接后必须配 301 重定向
图片不显示 路径大小写、中文文件名 用相对路径 /img/x.png，避免中文名
搜索无结果 本地搜索索引未生成 确认装了 hexo-generator-search

改动原则：能用配置解决的不写代码，能靠 CSS 覆盖的不改主题源文件。这样主题升级时一条 git pull 就能跟上，自己的定制也不会丢。