前言

默认的 Butterfly 主题首页只有文章列表，缺少直观的分类入口。hexo-butterfly-categories-card 插件可以在首页文章列表上方展示一组分类磁贴卡片，每个卡片显示分类名称、描述、文章数量和背景封面，点击即可跳转到对应分类页面。本文介绍插件的安装配置，以及如何通过自定义 CSS 修改图标和悬停效果。

一、安装插件

在博客根目录执行：

1
npm install hexo-butterfly-categories-card --save

二、基础配置

在 _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
# hexo-butterfly-categories-card 首页分类磁贴
categoryBar:
  enable: true
  priority: 5
  enable_page: /
  layout:
    type: id
    name: recent-posts
    index: 0
  column: even # odd：3列 | even：4列
  row: 2
  message:
    - name: "日常"
      descr: "日常记录与随笔"
      cover: "https://images.unsplash.com/photo-1497032628192-86f99bcd76bc?w=400&h=300&fit=crop"
    - name: "AI应用研发"
      descr: "AI与大模型应用"
      cover: "https://images.unsplash.com/photo-1677442136019-21780ecad995?w=400&h=300&fit=crop"
    - name: "暑期实习面经"
      descr: "2026暑期实习面试"
      cover: "https://images.unsplash.com/photo-1434030216411-0b793f4b4173?w=400&h=300&fit=crop"
    - name: "博客搭建"
      descr: "Hexo博客搭建笔记"
      cover: "https://images.unsplash.com/photo-1499750310107-5fef28a66643?w=400&h=300&fit=crop"

配置说明

字段 说明
enable 是否启用分类磁贴
priority 过滤器优先级，一般保持默认
enable_page 应用页面，/ 表示仅首页
layout 挂载容器，绑定到 #recent-posts 的第一个子元素前
column 列数，odd 为 3 列，even 为 4 列
row 显示行数，超出后变为滚动
message 分类列表，name 需与实际分类名一致

三、自定义样式

插件自带基础 CSS，但默认样式较为简单。为了统一博客视觉风格，建议通过独立的 CSS 文件进行覆盖，而非修改 custom.css（保持按功能拆分文件的原则）。

1. 创建独立样式文件

在 source/css/category-tile.css 创建文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/* 分类磁贴自定义样式 */

/* 文章数量图标：将默认的书本图标替换为文件图标 */
span.categoryBar-list-count::before {
  content: "\f15c" !important;
  font-family: "Font Awesome 7 Free" !important;
  font-weight: 900 !important;
}

/* 悬停效果优化 */
li.categoryBar-list-item {
  transition: all 0.4s cubic-bezier(0.25, 0.46, 0.45, 0.94) !important;
}

li.categoryBar-list-item:hover {
  transform: translateY(-6px) !important;
  box-shadow:
    inset 500px 50px 50px 50px rgba(50, 50, 50, 0.6),
    0 12px 30px rgba(0, 0, 0, 0.2) !important;
}

2. 修改说明

图标替换：插件默认使用 \f02d（fa-book 书本图标），这里替换为 \f15c（fa-file 文件图标），更符合”文章数量”的语义。

悬停优化：

  • 添加 translateY(-6px) 使卡片在悬停时微微上浮
  • 增加外层阴影 0 12px 30px 营造立体感
  • 使用 cubic-bezier(0.25, 0.46, 0.45, 0.94) 缓动函数使动画更平滑

3. 注入样式文件

在 _config.butterfly.yml 的 inject.head 中添加：

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

四、踩坑记录

1. Font Awesome 版本问题

插件默认 CSS 中的字体声明：

1
2
3
4
5
6
/* 插件原样式 — 写死了 FA6 */
span.categoryBar-list-count::before {
  content: "\f02d" !important;
  font-family: "Font Awesome 6 Free";
  font-weight: 600;
}

但 Butterfly 主题当前使用的是 Font Awesome 7.1.0，字体族名称为 Font Awesome 7 Free，而非 Font Awesome 6 Free。因此自定义覆盖时必须使用正确的字体族名和字重：

1
2
font-family: "Font Awesome 7 Free" !important;
font-weight: 900 !important;

排查方法：检查 plugins.yml 中 fontawesome 的版本号，或从 CDN 拉取对应版本的 CSS 查看 @font-face 声明中的 font-family 名称。

2. Emoji 在 content 中不可用

最初尝试用 emoji 📄 替换图标：

1
2
/* 不可行 */
content: 📄 !important;

CSS 的 content 属性对 emoji 的浏览器兼容性很差，最终改用 Font Awesome 图标码。

五、插件默认样式参考

以下是 hexo-butterfly-categories-card@1.0.0 的完整默认 CSS，可作为自定义覆盖的参考：

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
li.categoryBar-list-item {
  height: 180px;
  background-image: linear-gradient(
    rgba(0, 0, 0, 0.4) 25%,
    rgba(16, 16, 16, 0) 100%
  );
  border-radius: 10px;
  background-size: 100%;
  background-position: center;
}

li.categoryBar-list-item:hover {
  background-size: 110%;
  box-shadow: inset 500px 50px 50px 50px rgba(50, 50, 50, 0.6);
}

a.categoryBar-list-link {
  color: #fff;
  font-size: 20px;
}

a.categoryBar-list-link:hover:after {
  width: 90%;
  transition: all 0.5s;
}

span.categoryBar-list-count::before {
  content: "\f02d"; /* fa-book 图标 */
  font-family: "Font Awesome 6 Free";
  font-weight: 600;
}

如需进一步自定义（如修改卡片高度、渐变方向、文字大小等），直接在 category-tile.css 中用 !important 覆盖即可。

总结

分类磁贴通过 hexo-butterfly-categories-card 插件实现，配置简单，关键踩坑点是 Font Awesome 版本差异导致的字体族名不匹配。自定义样式建议按功能拆分为独立 CSS 文件，通过 inject 注入，便于维护。

参考资料: