一篇面向实际操作的 Hexo + Butterfly 搭建手册，跳过废话，直接上手。

环境准备

需要提前安装两个工具：

验证安装：

1
2
3
node -v
npm -v
git --version

安装 Hexo

1
npm install -g hexo-cli

初始化博客项目：

1
2
3
hexo init my-blog
cd my-blog
npm install

初始化完成后的目录结构：

1
2
3
4
5
6
7
my-blog/
├── _config.yml        # 站点配置文件
├── package.json       # 依赖管理
├── scaffolds/         # 文章模板
├── source/            # 资源文件夹
│   └── _posts/        # 文章目录
└── themes/            # 主题目录

安装 Butterfly 主题

1
npm install hexo-theme-butterfly

Butterfly 依赖 pug 和 stylus 渲染器：

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

修改站点配置文件 _config.yml：

1
theme: butterfly

在项目根目录创建 _config.butterfly.yml，用于覆盖主题默认配置，后续所有主题配置都写在这个文件里，不要直接改 themes/butterfly/_config.yml，方便主题升级。

站点基础配置

编辑根目录 _config.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 站点信息
title: 你的博客名
subtitle: ""
description: "站点描述，用于 SEO"
keywords:
  - 关键词1
  - 关键词2
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai

# URL（改成你自己的域名）
url: https://yourdomain.com
permalink: :year/:month/:day/:title/

# 关闭 Hexo 版本暴露
meta_generator: false

Butterfly 主题配置

以下是常用配置项，写在 _config.butterfly.yml 中。

导航栏

1
2
3
4
5
6
7
8
9
10
11
12
13
nav:
  logo:
  display_title: true
  fixed: false

menu:
  主页: / || fas fa-home
  博文 || fa fa-graduation-cap:
    分类: /categories/ || fa fa-archive
    标签: /tags/ || fa fa-tags
    归档: /archives/ || fa fa-folder-open
  友链: /links/ || fa fa-link
  关于: /about/ || fas fa-heart

代码块

1
2
3
4
5
6
code_blocks:
  theme: darker # darker / pale night / light / ocean
  macStyle: true # Mac 风格三个小圆点
  copy: true # 显示复制按钮
  language: true # 显示语言标识
  shrink: false # 是否默认收缩

头像与图标

1
2
3
4
5
favicon: /img/favicon.png

avatar:
  img: /img/avatar.jpg
  effect: false # 头像旋转效果

侧边栏

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
aside:
  enable: true
  position: right
  card_author:
    enable: true
    description: "一句话介绍自己"
    button:
      enable: true
      icon: fa-solid fa-envelope-open
      text: 联系我
      link: mailto:your@email.com
  card_announcement:
    enable: true
    content: 欢迎来到我的博客
  card_recent_post:
    enable: true
    limit: 5
  card_categories:
    enable: true
    limit: 8
  card_tags:
    enable: true
    limit: 40
    orderby: random
  card_archives:
    enable: true
    type: monthly
    limit: 8

文章版权声明

1
2
3
4
post_copyright:
  enable: true
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

搜索功能

需要先安装搜索插件：

1
npm install hexo-generator-search

配置：

1
2
3
4
5
6
7
search:
  use: local_search
  placeholder: 搜索文章...

local_search:
  preload: true
  top_n_per_article: 1

暗色模式

1
2
3
4
darkmode:
  enable: true
  button: true
  autoChangeMode: 2 # 晚 6 点到早 6 点自动切换

图片懒加载

Butterfly 内置懒加载，无需额外装插件：

1
2
3
4
lazyload:
  enable: true
  field: site
  blur: true # 加载时模糊效果

图片灯箱

1
lightbox: fancybox # fancybox 或 medium_zoom

页脚

1
2
3
4
5
6
7
footer:
  owner:
    enable: true
    since: 2024
  custom_text:
    - <a href="https://beian.miit.gov.cn"><span>你的备案号</span></a>
  copyright: true

创建必要页面

Butterfly 的导航栏菜单需要手动创建对应页面。

标签页

1
hexo new page tags

编辑 source/tags/index.md：

1
2
3
4
---
title: 标签
type: tags
---

分类页

1
hexo new page categories

编辑 source/categories/index.md：

1
2
3
4
---
title: 分类
type: categories
---

友情链接页

1
hexo new page links

编辑 source/links/index.md：

1
2
3
4
---
title: 友链
type: link
---

友链数据在 source/_data/link.yml 中配置（需手动创建 _data 目录）：

1
2
3
4
5
6
7
- class_name: 友情链接
  class_desc: 一些好朋友
  link_list:
    - name: 示例博客
      link: https://example.com
      avatar: https://example.com/avatar.jpg
      descr: 博客描述

关于页

1
hexo new page about

编辑 source/about/index.md，写上自我介绍即可。

写作

新建文章

1
hexo new "文章标题"

会在 source/_posts/ 下生成 Markdown 文件。

Front Matter

每篇文章头部的 YAML 配置：

1
2
3
4
5
6
7
8
9
10
11
---
title: 文章标题
date: 2025-01-01 12:00:00
tags:
  - 标签1
  - 标签2
categories:
  - 分类名
description: 文章摘要，用于 SEO 和首页展示
cover: https://example.com/cover.jpg # 文章封面图（可选）
---

摘要截断

在文章中插入 <!-- more -->，首页只显示该标记之前的内容：

1
2
3
4
5
这里是首页会显示的摘要内容。

<!-- more -->

这里是正文，首页不会显示。

Butterfly 专属标签

Note 标签（提示框）：

1
2
3
4
5
6
7
8
9
10
11
{% note success %}
这是一条成功提示
{% endnote %}

{% note warning %}
这是一条警告提示
{% endnote %}

{% note danger %}
这是一条危险提示
{% endnote %}

Tab 标签（选项卡）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{% tabs 测试 %}

<!-- tab 第一个 -->

第一个选项卡的内容

<!-- endtab -->
<!-- tab 第二个 -->

第二个选项卡的内容

<!-- endtab -->

{% endtabs %}

折叠块：

1
2
3
{% hideToggle 点击展开 %}
隐藏的内容
{% endhideToggle %}

常用命令

命令 作用
hexo new "标题" 新建文章
hexo new page "页面" 新建页面
hexo g 生成静态文件
hexo s 启动本地预览（默认 4000 端口）
hexo d 部署到远程
hexo clean 清除缓存和已生成的静态文件
hexo clean && hexo g && hexo d 清除→生成→部署（最常用）

推荐插件

插件 作用 安装命令
hexo-generator-sitemap 生成 sitemap.xml，利于 SEO npm i hexo-generator-sitemap
hexo-generator-feed 生成 RSS 订阅 npm i hexo-generator-feed
hexo-generator-search 本地搜索 npm i hexo-generator-search
hexo-deployer-ali-oss-extend 一键部署到阿里云 OSS npm i hexo-deployer-ali-oss-extend

安装后在 _config.yml 中添加对应配置：

1
2
3
4
5
6
7
8
9
10
# Sitemap
sitemap:
  path: sitemap.xml
  rel: true

# RSS Feed
feed:
  type: atom
  path: atom.xml
  limit: 20

部署到阿里云 OSS

详见：Hexo 静态网站托管阿里云 OSS

简要步骤：

  1. 安装部署插件：npm i hexo-deployer-ali-oss-extend
  2. 在 _config.yml 中配置 OSS 信息：
1
2
3
4
5
6
7
8
9
10
11
12
deploy:
  - type: ali-oss
    region: oss-cn-shanghai
    accessKeyId: ${ALI_OSS_KEY}
    accessKeySecret: ${ALI_OSS_SECRET}
    bucket: your-bucket-name
    cacheControl:
      images: public, max-age=31536000
      css: public, max-age=604800
      js: public, max-age=86400
      html: no-cache
      other: no-cache
  1. 执行部署：hexo clean && hexo g && hexo d

常见问题

hexo g 报错找不到主题

确认 _config.yml 中 theme: butterfly，并且已通过 npm 安装或 themes/ 目录下存在主题文件。

修改配置后不生效

先清除缓存再重新生成：

1
hexo clean && hexo g

图片不显示

检查图片路径。推荐使用图床（如阿里云 OSS + PicGo），在 Markdown 中直接使用远程 URL，避免本地路径问题。

部署后页面空白

检查 OSS 的静态页面功能是否开启，默认首页是否设为 index.html，子目录首页是否开通。