Hexo + Butterfly 博客搭建指南 🎨

✨ 特别说明
欢迎访问本站！本博客基于 Hexo 静态框架 + Butterfly 主题构建，兼具简洁美观与强大功能。
📌 本站内容仅供学习交流，不承担因版本差异导致的问题。已适配版本：

  • Hexo 7.3.0
  • Butterfly 5.5.0

📑 导航目录

🛠️ 一、下载安装基础运行程序

搭建博客前，需安装以下基础工具：

  1. Git：下载地址
    📌 安装时注意勾选“Add Git Bash Here”和“Add to PATH”选项。
  2. Node.js：下载地址
    📌 建议选择 LTS 版本，确保环境稳定性。

🔄 切换淘宝镜像加速

1
2
3
npm config set registry http://registry.npm.taobao.org/
# 验证是否切换成功
npm get registry

🔧 如需切换回官方源：

1
npm config set registry https://registry.npmmirror.com/

⚙️ 二、安装 Hexo

🌍 全局安装 Hexo CLI

1
npm install -g hexo-cli

📦 局部安装（可选）

1
npm install hexo

🔄 升级 Hexo

1
npm update hexo -g

查看当前版本

1
npm list hexo

🔧 三、Hexo 常用命令

1. 初始化博客

1
2
hexo init blog  # 创建名为 blog 的目录并初始化
cd blog && npm install  # 进入目录并安装依赖

2. 常用命令组合

组合命令 说明
hexo clean && hexo g && hexo s 清除缓存 → 生成静态文件 → 启动本地服务器（推荐）
hexo clean && hexo g && hexo d 清除缓存 → 生成静态文件 → 部署到远程仓库
hexo clean && hexo g -d 清除缓存后直接生成并部署（简化版）
hexo new "文章标题" && hexo s 创建新文章后立即启动本地服务器预览
hexo clean && hexo g && hexo s -p 5000 清除缓存 → 生成 → 在指定端口(5000)启动服务器

🎨 四、安装与配置 Butterfly 主题

1. 克隆主题仓库

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

2. 安装渲染器

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

3. 启用主题

修改根目录 _config.yml：

1
theme: butterfly

4. 主题配置优化

将主题配置文件 themes/butterfly/_config.yml 移动至根目录并重命名为 _config.butterfly.yml，便于统一管理。

🧭 五、设置导航菜单

1. 配置菜单项

  • 编辑 _config.butterfly.yml
1
2
3
4
5
6
7
8
menu:
  主页: / || fas fa-home
  标签: /tags/ || fa fa-tags
  分类: /categories/ || fa fa-archive
  归档: /archives/ || fa fa-folder-open
  友链: /link/ || fa fa-link
  关于: /about/ || fas fa-heart
  留言板: /comment/ || fa fa-paper-plane

2. 创建菜单页面

使用 Hexo 页面生成命令：

1
2
3
4
5
6
hexo new page tags      # 创建“标签”页面
hexo new page categories # 创建“分类”页面
hexo new page archives   # 创建“归档”页面
hexo new page link       # 创建“友链”页面
hexo new page about      # 创建“关于”页面
hexo new page comment    # 创建“留言板”页面

3. 友链数据配置

在 source/_data/link.yml 中配置友链信息（示例）：

1
2
3
4
5
6
7
- class_name: 友情链接
  class_desc: 那些人，那些事
  link_list:
    - name: Hexo
      link: https://hexo.io/zh-tw/
      avatar: https://d33wubrfki0l68.cloudfront.net/6657ba50e702d84afb32fe846bed54fba1a77add/827ae/logo.svg
      descr: 快速、简单且强大的网志框架

4. 文章模板优化

编辑 scaffolds/post.md 可自定义文章 Front Matter：

1
2
3
4
5
6
7
8
9
10
11
12
13
---
title: {{ title }}
date: {{ date }}
description: {{ description }}
top_img: {{ top_img }}
sticky: {{ sticky }}
categories:
  - 
tags:
  - 
cover: {{ cover }}
updated: {{ date }}
---

✨ 六、动态特效与功能增强

1. 动态彩带效果

1
2
3
canvas_fluttering_ribbon:
  enable: true
  mobile: false  # 移动端禁用

2. 鼠标点击特效

1
2
3
4
fireworks:
  enable: false  # 可开启烟花特效
  zIndex: 9999
  mobile: false

3. 页面加载动画

1
2
3
preloader:
  enable: true
  source: 1  # 1=全屏加载动画，2=进度条

📊 七、数据统计与搜索

1. 字数统计插件

1
npm install hexo-wordcount --save or yarn add hexo-wordcount

配置主题文件：

1
2
3
4
5
wordcount:
  enable: true
  post_wordcount: true    # 文章字数
  min2read: true          # 阅读时间
  total_wordcount: true   # 总字数统计

2. 本地搜索功能

  • 安装搜索插件
1
npm install hexo-generator-search --save
  • 在 _config.yml 主配置文件中添加
1
2
3
4
5
search:
  path: search.xml
  field: post
  format: html
  limit: 10000
  • 在 _config.butterfly.yml 主题配置中启用
1
2
3
use: local_search
local_search:
  enable: true

🖼️ 八、随机封面图 API

1. 创建随机图脚本

  • 在 themes/butterfly/scripts/ 下创建 random_img.js
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
/**
 * Butterfly
 * random cover
 */

'use strict'

// 提取正则表达式作为常量，避免每次调用时都重新创建
const IMG_TEST_REG = /\.(png|jpe?g|gif|svg|webp)(\?.*)?$/;

// 注册过滤器，在文章渲染前处理文章数据
hexo.extend.filter.register('before_post_render', function (data) {
    const { config } = this;
    const { post_asset_folder } = config;

    // 如果启用了文章资源文件夹
    if (post_asset_folder) {
        processImagePath(data, 'top_img');
        processImagePath(data, 'cover');
    }

    // 如果文章的 cover 为 false，使用随机封面
    if (data.cover === false) {
        data.randomcover = getRandomCover();
    } else {
        // 否则，使用文章的 cover 或者随机封面
        data.cover = data.cover || getRandomCover();
    }

    return data;
}, 0);

// 处理图片路径的函数
function processImagePath(data, key) {
    const image = data[key];
    if (image && image.indexOf('/') === -1 && IMG_TEST_REG.test(image)) {
        data[key] = data.path + image;
    }
}

// 获取随机封面的函数
function getRandomCover() {
    const theme = hexo.theme.config;
    let cover;
    let num;

    const defaultCovers = theme.cover && theme.cover.default_cover;
    if (defaultCovers) {
        if (!Array.isArray(defaultCovers)) {
            cover = defaultCovers;
        } else {
            num = Math.floor(Math.random() * defaultCovers.length);
            cover = defaultCovers[num];
        }
    } else {
        cover = theme.default_top_img || 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
    }

    // 根据配置添加随机后缀
    if (theme.cover && theme.cover.suffix) {
        const randomValue = Math.ceil(Math.random() * 10000);
        if (theme.cover.suffix === 1) {
            cover += `?${randomValue}`;
        } else if (theme.cover.suffix === 2) {
            cover += `&${randomValue}`;
        }
    }

    return cover;
}

效果

2. 配置封面设置

  • 在 _config.butterfly.yml 主题配置中修改
1
2
3
4
5
6
7
8
cover:
  index_enable: true
  aside_enable: true
  archives_enable: true
  position: both
  suffix: 1
  default_cover: 
    - https://api.mobufan.eu.org:666  # 随机图API

💫 九、副标题与侧边栏优化

1. 动态副标题设置 _config.butterfly.yml

1
2
3
4
5
6
7
subtitle:
  enable: true
  effect: true  # 打字机效果
  source: 1     # 调用一言API
  sub:
    - 你在抱怨什么呢
    - 为明天到来的事，说人生像是没有意义

2. 侧边栏配置 _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
# --------------------------------------
# 侧边栏设置
# --------------------------------------

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: GitHub  # 按钮文本
      link: https://github.com/meimolihan  # 按钮链接
  
  # 公告卡片
  card_announcement:
    enable: true    # 显示公告卡片
    content: <center><b>--- 主域名 ---<br><a href="https://www.meimolihan.eu.org" title="此线路部署于Vercel" class="anno_content"><font color="#5ea6e5">www.meimolihan.eu.org</font></a>&nbsp;|&nbsp;<a href="https://meimolihan.eu.org" title="此线路部署于Vercel" class="anno_content"><font color="#5ea6e5">meimolihan.eu.org</font></a></b></center>

🔗 十、永久链接生成

插件链接: xo-abbrlink

1
npm install hexo-abbrlink --save

2. 配置永久链接

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
permalink_defaults: # 默认永久链接格式
permalink: posts/:abbrlink.html

# abbrlink 文章缩写链接生成配置
abbrlink:
  alg: crc32       # 生成算法：可选 crc16（默认）或 crc32
  rep: hex         # 链接格式：dec（十进制）或 hex（十六进制）
  drafts: false    # 是否处理草稿文章
  auto_category:
    enable: true   # 是否自动从文件路径生成分类
    depth: 3       # 生成分类的最大目录深度
    over_write: false # 是否覆盖已有分类
  auto_title: false # 是否根据路径自动生成标题
  auto_date: false  # 是否自动填充当前日期
  force: false      # 是否强制重新生成所有链接（忽略缓存）

# 永久链接美化设置
pretty_urls:
  trailing_index: true  # false：链接中移除 index.html
  trailing_html: true  # false：移除链接末尾的 .html 后缀
🟡 警告：谨慎修改，不然部署到 Vercel 文章无法解析

3. 配置说明

crc16

1
2
3
4
5
crc16 & hex
http://localhost:4000/posts/66c8

crc16 & dec
http://localhost:4000/posts/65535

crc32

1
2
3
4
5
crc32 & hex
http://localhost:4000/posts/8ddf18fb

crc32 & dec
http://localhost:4000/posts/1690090958

🔄 十一、博客迁移指南

🖥️ 新电脑环境配置

  1. Git：下载地址
    📌 安装时注意勾选“Add Git Bash Here”和“Add to PATH”选项。
  2. Node.js：下载地址
    📌 建议选择 LTS 版本，确保环境稳定性。
  3. 关闭 SSL 严格模式（解决证书问题）： 
    1
    npm set strict-ssl false

📦 迁移项目文件

  • 拷贝以下文件到新项目：
1
2
3
4
5
6
7
- `_config.yml`
- `_config.butterfly.yml`
- `themes/`
- `source/`
- `scaffolds/`
- `package.json`
- `.gitignore`

🔑 SSH密钥重新配置

1
2
3
4
git config --global user.name "YourName"
git config --global user.email "your@email.com"
ssh-keygen -t rsa -C "your@email.com"
# 将新公钥添加到GitHub

🚀 部署测试

1
2
3
4
npm install hexo-cli -g 
	npm install
	npm install hexo-deployer-git --save
	hexo clean; hexo g; hexo s

📦 十二、插件列表与升级指南

🔄 全局安装/升级 Hexo 及相关工具常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 1. 全局安装 Hexo 命令行工具（hexo-cli）
npm i hexo-cli -g

# 2. 全局安装 npm-check：检查过时、未使用、可升级的依赖
npm install -g npm-check

# 3. 全局安装 npm-upgrade：交互式批量升级依赖版本
npm install -g npm-upgrade

# 4. 运行 npm-check，查看当前项目依赖的健康状况
npm-check

# 5. 运行 npm-upgrade，交互式选择要升级的依赖
npm-upgrade

# 6. 升级所有**全局**安装的包到最新版本
npm update -g

# 7. 根据 package.json 范围规则，升级**当前项目**的依赖，并自动修改 package.json 与 package-lock.json
npm update --save

🧩 常用插件列表

插件名称 功能描述 安装命令
hexo-wordcount 字数统计 npm install hexo-wordcount --save
hexo-abbrlink 永久链接 npm install hexo-abbrlink --save
hexo-generator-search 本地搜索 npm install hexo-generator-search --save
hexo-deployer-git Git部署 npm install hexo-deployer-git --save

📝 更多插件请参考原文中的完整插件表格，按需安装使用。

🎉 恭喜！ 您已完成 Hexo 博客的搭建与美化。如有问题，欢迎在评论区留言交流。