hexo-butterfly-build

Hexo + Butterfly 博客搭建指南

补充说明

基于 Hexo 静态框架 + Butterfly 主题构建的博客搭建指南。欢迎访问本站。

• Hexo 7.3.0
• Butterfly 4.3.1

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

安装 Git

下载地址

• Windows winget 安装 Git

winget install -e --id Git.Git --silent --accept-package-agreements --accept-source-agreements

winget list -e --id Git.Git

• -e：精确匹配包 ID，杜绝装错
• --silent：静默安装，不弹出向导窗口
• --accept-package-agreements：自动同意许可协议
• --accept-source-agreements：同意源协议，批量部署必备

• Windows winget 卸载 Git

# 静默无弹窗彻底卸载（管理员 PowerShell）
winget uninstall -e --id Git.Git --silent

# 彻底清理缓存 / 用户配置（--purge）（管理员 PowerShell）
winget uninstall -e --id Git.Git --silent --purge

• Linux 安装 Git

# Ubuntu/Debian 系
sudo apt update
sudo apt install git -y
git --version

# CentOS/RHEL 系
# CentOS 7/RHEL 7 及以下
sudo yum install git -y
# CentOS 8+/RHEL 9+ 使用 dnf
sudo dnf install git -y

安装 Node.js

下载地址

• Windows winget 安装 Node.js

winget install -e --id OpenJS.NodeJS.LTS --silent --accept-package-agreements --accept-source-agreements

winget list -e --id OpenJS.NodeJS.LTS

• -e：精确匹配包 ID，杜绝装错
• --silent：静默安装，不弹出向导窗口
• --accept-package-agreements：自动同意许可协议
• --accept-source-agreements：同意源协议，批量部署必备

• Windows winget 卸载 Node.js

# 静默无弹窗彻底卸载（管理员 PowerShell）
winget uninstall -e --id OpenJS.NodeJS.LTS --silent

# 彻底清理缓存 / 用户配置（--purge）（管理员 PowerShell）
winget uninstall -e --id OpenJS.NodeJS.LTS --silent --purge

切换淘宝镜像加速

npm config set registry http://registry.npm.taobao.org/
npm get registry

切换回官方源：

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

二、安装 Hexo

全局安装 Hexo CLI

npm install -g hexo-cli

局部安装

npm install hexo

升级 Hexo

npm update hexo -g

查看版本

npm list hexo

三、Hexo 常用命令

初始化博客

hexo init blog
cd blog && npm install

常用命令组合

四、安装与配置 Butterfly 主题

克隆主题仓库

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

安装渲染器

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

启用主题

修改根目录 _config.yml：

theme: butterfly

主题配置优化

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

五、设置导航菜单

配置菜单项

编辑 _config.butterfly.yml：

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

创建菜单页面

hexo new page tags
hexo new page categories
hexo new page link
hexo new page about
hexo new page comment

友链数据配置

编辑 source/_data/link.yml：

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

文章模板优化

编辑 scaffolds/post.md：

---
title: {{ title }}
date: {{ date }}
description: {{ description }}
top_img: {{ top_img }}
sticky: {{ sticky }}
categories:
  -
tags:
  -
cover: {{ cover }}
updated: {{ date }}
---

六、动态特效与功能增强

动态彩带效果

canvas_fluttering_ribbon:
  enable: true
  mobile: false

鼠标点击特效

fireworks:
  enable: false
  zIndex: 9999
  mobile: false

页面加载动画

preloader:
  enable: true
  source: 1

source 1 为全屏加载动画，2 为进度条。

七、数据统计与搜索

字数统计插件

npm install hexo-wordcount --save

配置主题文件：

wordcount:
  enable: true
  post_wordcount: true
  min2read: true
  total_wordcount: true

本地搜索功能

安装搜索插件：

npm install hexo-generator-search --save

在 _config.yml 主配置文件中添加：

search:
  path: search.xml
  field: post
  format: html
  limit: 10000

在 _config.butterfly.yml 主题配置中启用：

use: local_search
local_search:
  enable: true

八、随机封面图 API

创建随机图脚本

在 themes/butterfly/scripts/ 下创建 random_img.js：

'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');
    }

    if (data.cover === false) {
        data.randomcover = getRandomCover();
    } else {
        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;
}

配置封面设置

在 _config.butterfly.yml 主题配置中修改：

cover:
  index_enable: true
  aside_enable: true
  archives_enable: true
  position: both
  suffix: 1
  default_cover:
    - https://api.mobufan.eu.org:666

九、副标题与侧边栏优化

动态副标题设置

_config.butterfly.yml：

subtitle:
  enable: true
  effect: true
  source: 1
  sub:
    - 你在抱怨什么呢
    - 为明天到来的事，说人生像是没有意义

effect true 开启打字机效果，source 1 调用一言 API。

侧边栏配置

_config.butterfly.yml：

aside:
  enable: true
  hide: false
  button: true
  mobile: true
  position: 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">www.meimolihan.eu.org</a>&nbsp;|&nbsp;<a href="https://meimolihan.eu.org">meimolihan.eu.org</a></b></center>

十、永久链接生成

插件：hexo-abbrlink

安装 abbrlink 插件

npm install hexo-abbrlink --save

配置永久链接

permalink_defaults:
permalink: posts/:abbrlink.html

abbrlink:
  alg: crc32
  rep: 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
  trailing_html: true

alg 可选 crc16 或 crc32，rep 可选 dec（十进制）或 hex（十六进制）。

配置示例

crc16 & hex：

http://localhost:4000/posts/66c8

crc16 & dec：

http://localhost:4000/posts/65535

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 版本

关闭 SSL 严格模式：

npm set strict-ssl false

迁移项目文件

拷贝以下文件到新项目：

_config.yml
_config.butterfly.yml
themes/
source/
scaffolds/
package.json
.gitignore

SSH 密钥重新配置

git config --global user.name "YourName"
git config --global user.email "your@email.com"
ssh-keygen -t rsa -C "your@email.com"

将新公钥添加到 GitHub。

部署测试

npm install hexo-cli -g
npm install
npm install hexo-deployer-git --save
hexo clean; hexo g; hexo s

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

全局安装或升级 Hexo 及相关工具

npm i hexo-cli -g
npm install -g npm-check
npm install -g npm-upgrade

检查与升级依赖

npm-check
npm-upgrade
npm update -g
npm update --save

常用插件列表