Butterfly教程怎么学？新手入门指南？-杰瑞科技汇

准备工作

在开始之前,请确保你已经完成了以下环境搭建：

安装 Node.js: Node.js 官网下载并安装 LTS (长期支持) 版本。
安装 Git: Git 官网下载并安装。
安装 Hexo: 在你的电脑上打开终端（命令提示符或 PowerShell），运行以下命令全局安装 Hexo。
```
npm install -g hexo-cli
```
创建 Hexo 博客: 如果你还没有博客，可以创建一个新的博客文件夹。
```
hexo init my-blog
cd my-blog
npm install
```
安装 Pug 和 Stylus: Butterfly 依赖 Pug (模板引擎) 和 Stylus (CSS 预处理器)，你需要安装 Hexo 的渲染器插件。
```
npm install hexo-render-pug hexo-render-stylus --save
```

安装 Butterfly

有两种方式可以安装 Butterfly：Git 方式（推荐） 和 手动下载。Git 方式可以方便地通过 git pull 来更新主题。

Git 方式 (推荐)

进入你的 Hexo 博客根目录。
```
cd /path/to/your/hexo-blog
```

克隆 Butterfly 主题到 themes 文件夹下。

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

安装主题依赖：Butterfly 的一些功能需要额外的依赖,请务必安装。
```
npm install hexo-renderer-markdown-it-plus hexo-offline
```

手动下载

访问 Butterfly 主题的 GitHub Releases 页面。
下载最新的 Source code (zip) 文件。
解压下载的文件，将其重命名为 Butterfly，然后放入你博客的 themes 文件夹中。

基础配置

安装完成后，你需要配置 Hexo 和 Butterfly。

配置 Hexo: 打开博客根目录下的 _config.yml 文件，找到 theme 字段，将其值修改为 Butterfly。
```
# _config.yml
theme: Butterfly
```
配置 Butterfly: 在博客根目录下，复制 themes/Butterfly 文件夹下的 _config.yml 文件，并将其粘贴到博客根目录下，重命名为 _config.butterfly.yml。
- 重要：这个文件是 Butterfly 的主题配置文件，Hexo 在渲染时会优先使用根目录下的 _config.butterfly.yml，而不是 themes/Butterfly 内部的那个，这样做的好处是，主题更新时,你的自定义配置不会被覆盖。
启动本地服务器：在终端中，确保你在博客根目录下,运行以下命令。
```
hexo s
```
现在在浏览器中打开 http://localhost:4000，你应该能看到一个使用 Butterfly 主题的博客了！

页面与菜单配置

Butterfly 提供了丰富的页面和菜单选项。

1 创建页面

Butterfly 推荐的页面包括：首页、文章列表、标签、分类、归档、友链等，使用 hexo new page 命令创建。

# 创建标签页
hexo new page tags
# 创建分类页
hexo new page categories
# 创建归档页
hexo new page archives
# 创建友链页
hexo new page links
# 创建关于页
hexo new page about

2 配置菜单

打开 _config.butterfly.yml，找到 menu 部分,这里的配置决定了导航栏显示哪些链接。

# _config.butterfly.yml
menu:
  home: / || fa fa-home
  archives: /archives/ || fa fa-archive
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-folder-open
  list: /list/ || fa fa-list
  link: /links/ || fa fa-link
  about: /about/ || fa fa-heart

home: 显示的文字
链接地址
分隔符
fa fa-home: Font Awesome 图标，可以去 Font Awesome 官网查找你喜欢的图标。

3 配置页面内容

以 tags 页面为例：

打开 source/tags/index.md 文件。
在最上方添加 type: "tags"，这是 Butterfly 识别这个页面的关键。
删除文件中的所有内容（默认的 "Welcome to..."），或者保留，但 Butterfly 会用自己的方式渲染。

---
type: "tags" "所有标签"
date: 2025-10-27 15:30:00
---
会被 Butterfly 的模板覆盖，可以留空或写一些说明性文字

对 categories, archives, links, about 等页面也进行类似操作。

增强

1 新建文章

hexo new "我的第一篇 Butterfly 博客"

这会在 source/_posts 目录下创建一个 .md 文件，你可以使用任何 Markdown 编辑器（如 Typora, VS Code）来编辑它。

2 文章 Front-matter

文章开头的和之间的部分是 Front-matter，用于定义文章的元数据，Butterfly 支持丰富的 Front-matter。

--- 我的标题
date: 2025-10-27 15:30:00
updated: 2025-10-27 16:00:00
tags:
  - 教程
  - Butterfly
  - Hexo
categories:
  - 前端
  - Hexo
description: 这是文章的简要描述，会显示在文章列表和 SEO 中。
cover: /img/cover.jpg # 文章封面图
top: true # 置顶文章
password: 1234 # 文章密码
toc: true # 是否显示目录
mathjax: true # 是否开启数学公式
katex: true # 是否开启 KaTeX 数学公式
mermaid: true # 是否开启流程图
---

3 内容增强

在 _config.butterfly.yml 中,你可以开启许多内容增强功能。

图片灯箱: lightbox: true
图片懒加载: lazyload: true
复制提示: copy_btn: true
代码块增强: highlight: 和 prismjs: 部分,可以配置代码高亮主题。
字数统计: word_count: true
阅读进度: reading_progress: true
相关文章: related_post:
Markdown-it 渲染器: 已在安装部分配置，可以支持更多 Markdown 语法，如表格、脚注等。

主题外观定制

这是 Butterfly 最强大的部分，通过修改 _config.butterfly.yml,你可以深度定制博客的外观。

1 主题色

在 theme_color 部分,你可以自定义主题的各种颜色。

# _config.butterfly.yml
theme_color:
  primary: #FF6B6B # 主色调
  success: #4ECDC4 # 成功色
  default: #95A5A6 # 默认色
  info: #3498DB # 信息色
  warning: #F39C12 # 警告色
  danger: #E74C3C # 危险色
  light: #F8F9FA # 浅色
  dark: #343A40 # 深色

2 布局

首页布局: index_layout 可以设置为 banner (大图横幅) 或 auto (自动)。
文章页布局: post_layout 可以设置为 layout-1, layout-2, layout-3 等,每种布局的侧边栏位置和宽度不同。
侧边栏: aside 部分可以控制侧边栏的显示和隐藏，以及每个小部件（头像、社交链接、目录等）的顺序。

3 自定义样式

如果你想添加 CSS 样式，可以在 _config.butterfly.yml 中开启自定义 CSS 文件功能。

# _config.butterfly.yml
inject:
  head:
    - <link rel="stylesheet" href="/css/my-style.css">
  bottom:
    - <script src="/js/my-script.js"></script>

在 source 目录下创建 css 和 js 文件夹，并将你的 my-style.css 和 my-script.js 放入其中，Hexo 在部署时会自动将这些文件复制到 public 目录。

高级功能与插件

1 评论系统

Butterfly 支持多种评论系统，如 Valine, Gitalk, Disqus 等，在 _config.butterfly.yml 的 comments 部分进行配置。

以 Valine 为例：

在 LeanCloud 注册并创建一个应用。
在应用的 “设置” -> “应用 Key” 中获取 AppID 和 AppKey。
在 _config.butterfly.yml 中配置 Valine。

# _config.butterfly.yml
comments:
  enable: true
  type: valine
  appid: YOUR_APP_ID
  appkey: YOUR_APP_KEY
  # ...其他配置

2 数据分析

集成 Google Analytics, Baidu Analytics 等，在 analytics 部分配置。

3 搜索

集成 hexo-generator-searchdb 插件,实现本地搜索。

安装插件：npm install hexo-generator-searchdb --save

在 _config.yml 中配置：

# _config.yml
search:
  path: search.xml
  field: post
  format: html
  limit: 10000

在 _config.butterfly.yml 中开启搜索功能：local_search: true

4 不蒜子 / busuanzi

用于显示站点访问量，在 sitebusuanzi 部分配置。

常见问题与解决

Q: 为什么我修改了配置文件后没有效果？
- A: 1. 确认修改的是根目录下的 _config.butterfly.yml，而不是主题内部的，2. 保存文件后，重新运行 hexo clean && hexo s 清理缓存并重启服务器。
Q: 图片无法显示？
- A: 1. 检查图片路径是否正确，推荐将图片放在 source/images 或 source/img 目录下，然后通过 /img/your-image.jpg 引用，2. 确保你已开启 lazyload 和 lightbox 功能，3. 检查 Hexo 的 post_asset_folder 设置是否正确。
Q: 如何更新 Butterfly 主题？
- A: 如果你使用的是 Git 方式安装，只需在博客根目录下执行：
```
cd themes/Butterfly
git pull
```
  如果有冲突，可能需要手动解决，更新后，检查 _config.butterfly.yml 是否有新的配置项需要添加。
Q: 想要自定义某个页面的内容，About 页面？
- A: 直接编辑 source/about/index.md 文件，Butterfly 会读取这个文件的内容，并根据 type: "about" 来渲染成“关于我”的页面，你可以在这里写任何 HTML 或 Markdown 内容。