Hexo Butterfly 主题详细配置指南
还记得第一次看到默认的 Butterfly 主题时，那种”好看但不够像我”的感觉。为了让这个博客真正成为我的小屋，通过翻遍文档、调试配置，终于把 Butterfly 调成了现在这个模样。
这篇文章就是我这段时间摸索的一些基础设置。它不是一份冰冷的说明书，而是我亲身实践后的配置心得。我会带你走过我走过的路，从最关键的配置文件分离开始，到那些让博客变得贴心好用的小功能为止。
如果你也和我一样，希望自己的博客既能保持 Butterfly 的美观，又能充满个人痕迹，那这篇指南应该能帮到你。让我们开始吧！
创建主题配置文件
配置Butterfly主题时，我强烈建议你把它的配置单独拿出来，这样管理和以后修改起来会特别方便，也不怕主题更新时弄丢自己的设置。操作很简单：
- 先进入你博客根目录下的
themes/butterfly文件夹。 - 找到里面的
_config.yml文件，复制它。 - 然后回到博客根目录，把复制好的文件粘贴在这里，并把名字改成
_config.butterfly.yml。
千万注意哦：是新建一个文件，不要覆盖掉根目录里原来的那个 _config.yml！
搞定后，根目录里就有两个配置文件啦，它们分工明确：
_config.yml：管 Hexo 博客本身的设置。_config.butterfly.yml：专门管 Butterfly 主题的样式和功能。
这样分开来，以后想改点什么，或者主题升级了，不会乱。
修改Hexo博客配置文件
接下来，我们来设置Hexo博客本身。这里所有的修改，都是在博客根目录下的 _config.yml 文件里完成的。
修改博客基本信息
这部分配置定义了博客的核心身份信息，比如名称、作者和语言。请在 _config.yml 中找到 # Site 部分，并参照下面的示例进行修改：
1 | # Site |
修改博客地址
这个配置项至关重要，因为它直接影响博客所有资源的加载路径和链接的正确生成。
1 | url: https://blog.ios1.top # 网站域名，必须以 http:// 或 https:// 开头 |
实用提示：
- 本地预览：如果你在本地使用
hexo s命令预览，可以暂时将此项改为http://localhost:4000，等部署到服务器前再改回你的域名，这样可以避免本地开发时资源加载失败。 - 注意后果：如果这里设置错误，很可能会导致博客的CSS样式、图片等所有资源都无法正常显示。
添加RSS订阅
为你的博客添加RSS订阅功能，可以让读者通过订阅器及时获取到内容更新，有助于培养忠实的读者群体。
- 安装插件
在博客的根目录下，运行以下命令来安装RSS生成插件：
1 | npm install hexo-generator-feed --save |
- 配置参数
接下来，在站点的 _config.yml 配置文件末尾，添加以下设置。你通常只需要关注 enable, type, limit 等前几项，其余的保持默认即可。
1 | # RSS 订阅配置 |
主页（文章列表）设置
这部分配置决定了博客首页如何展示文章列表，比如每页显示多少篇文章。
1 | # Home page setting |
归档页与分类/标签页分页设置
注意，这里的 per_page 配置专门用于控制归档页、分类页和标签页等页面的文章列表，它与首页的设置是相互独立的。
1 | # Pagination |
完成以上这些基本配置后，你的Hexo博客核心设置就差不多了。
建议的后续操作：
- 在终端执行
hexo clean && hexo g来清理并重新生成博客静态文件。 - 使用
hexo s启动本地服务器，在浏览器中预览配置效果。 - 确认一切正常后，再部署到你的线上服务器。
如果你想探索更多配置选项，可以参考 Hexo 官方中文文档。
修改Butterfly 主题配置文件
从这部分开始，我们就进入主题美化的核心环节了。_config.butterfly.yml 文件里的选项非常丰富，你可以根据自己的审美进行大量个性化设置。下面我会以我自己的博客配置为例，带你一步步配置。
导航栏
导航栏是网站的门面，我们先来调整它。
1 | nav: |
导航栏目录
接下来我们配置导航栏的菜单项，也就是网站上方的这些导航链接。下图是我配置好的效果：
对应的配置如下，你可以参考我的结构来设计你的菜单：
1 | # Menu 目錄 |
格式说明：
菜单名称: 链接路径 || 图标类名- 使用
||hide可以创建一个下拉菜单
所有图标均来自 FontAwesome 图标库，您可以在其官网搜索并替换为您喜欢的图标。
创建基础页面
配置好菜单后，你会发现有些链接（比如标签、分类）点进去是 404。这是因为对应的页面还没创建。别担心，创建它们非常简单。
在博客的根目录下，分别执行以下命令来生成这些页面的源文件（每个命令执行一次即可）：
1 | hexo new page tags |
这样就会在 source 目录下生成对应的文件夹和 index.md 文件。
对于菜单中你自定义的其他页面（例如 charts, comment 等），创建方法也是一样的，只需将命令中的页面名称替换掉即可。
配置页面类型
页面创建好后，我们还需要告诉 Butterfly 主题每个页面的具体类型，这样主题才能用正确的样式和布局来渲染它们。方法是在每个页面的 index.md 文件里，通过 type 字段来指定。
标签页
打开刚生成的 source/tags/index.md 文件，添加 type: "tags"。修改后的文件内容应该是这样的：
1 | --- |
注意：这里的 type 值必须严格设置为 "tags"，主题才会把它识别为标签云页面。
分类页
同样地，打开 source/categories/index.md 文件，添加 type: "categories"。
1 | --- |
友链页
打开 source/link/index.md 文件，添加 type: "link"。
1 | --- |
仅仅创建友链页面是不够的，我们还需要一个专门的文件来存放所有友情链接的信息。
操作步骤：
- 在博客根目录下，找到或创建
source/_data文件夹。 - 在这个文件夹里，新建一个名为
link.yml的文件。
接下来，将你的友链信息按照下面的格式填入这个文件。这是一个YAML列表，允许你设置多个友链分组：
1 | - class_name: 优质博客 # 这个分组的名称 |
保存文件后，你的友链页面就会按照这个配置来展示啦。
社交图标
你可以在侧边栏和首页头图下方展示你的社交媒体链接，方便访客找到你。
1 | social: |
你可以参考这个格式，替换成你自己的社交平台链接和喜欢的图标。
图片与图标
这部分我们来设置一些重要的视觉元素，让博客更具个人特色。
网站图标
网站图标（Favicon）会显示在浏览器标签页和书签栏里。下图显示了它的位置：
配置起来很简单，只需指定你的图标文件路径：
1 | favicon: /img/favicon.ico # 这里修改为自己的图标路径 |
头像
设置你的个人头像，它会显示在侧边栏等位置。
1 | avatar: |
下图展示了头像在侧边栏的显示效果：
顶部图
顶部图是位于页面顶部的大横幅，可以是图片、纯色或渐变背景，它能极大地影响博客的视觉风格。
1 | # 顶部图全局开关 |
配置值可以这样设置：
| 配置示例 | 效果说明 |
|---|---|
图片路径 |
使用指定图片作为顶部图 |
颜色值 |
显示为纯色背景 |
渐变代码 |
显示为渐变背景 |
transparent |
顶部图区域变为透明 |
false |
不显示当前页面的顶部图 |
| 留空不填 | 遵循上一级的设置，最终回退到default_top_img |
需要注意的几点：
- 文章页的顶部图，优先级最高的是在文章Markdown文件的Front-matter里设置
top_img。 - 对于自定义页面（如Tags、Categories页），它们的顶部图也是在各自页面的Front-matter里设置的。
如果不想显示任何顶部图，最直接的方法是将全局开关设置为：disable_top_img: true
顶部图的生效优先级
了解优先级可以帮你更好地管理它们：
- 普通页面：
页面自身配置>default_top_img - 文章页面：
文章Front-matter中的top_img>文章Front-matter中的cover>default_top_img
文章封面
你可以为每篇文章设置一张封面图，并控制它在不同页面的显示方式。
1 | cover: |
小提示：每篇文章的封面图可以在其Markdown文件的Front-matter中，通过 cover 字段来单独指定。
404页面
设置一个个性化的404页面，可以在用户访问到不存在链接时，提供更友好的体验，引导他们返回你的网站。
1 | error_404: |
配置好后，当访客遇到失效链接时，就能看到这个你精心准备的页面了。
首页
文章副标题
你可以在首页头图区域，设置一段吸引人的副标题文字，并可以开启酷炫的打字机效果。
1 | subtitle: |
文章卡片布局
Butterfly 提供了 7 种不同的首页文章列表布局，你可以通过修改 index_layout 的值来切换，找到最喜欢的一款。
1 | index_layout: 6 # 范围 1-7 |
下面是每种布局的简要介绍，你可以根据喜好选择：
| 布局 | 样式描述 | 特点 |
|---|---|---|
| 1 | 封面在左，信息在右 | 传统博客布局 |
| 2 | 封面在右，信息在左 | 传统博客布局 |
| 3 | 封面和信息左右交替 | 错落有致，视觉丰富 |
| 4 | 封面在上，信息在下 | 卡片式布局，整齐划一 |
| 5 | 信息叠加在封面上 | 杂志风，视觉冲击力强 |
| 6 | 瀑布流 - 封面在上 | 本站同款，不同高度卡片错位排列 |
| 7 | 瀑布流 - 信息叠加 | 杂志风与瀑布流结合 |
文章摘要显示
这个配置决定了在首页的文章卡片上，如何显示文章的摘要内容。
1 | # Display the article introduction on homepage |
关于 method 参数的详细说明：
- 1: 只显示你在文章Front-matter中手动填写的
description。 - 2: 优先显示手动填写的
description；如果没写，则自动从文章内容中节选一段。 - 3: 总是自动从文章内容中节选一段（如上例配置）。
- false: 在首页卡片上不显示任何文章摘要。
如果你选择了自动节选（2或3），就可以通过 length 来控制节选的大致长度。
文章页
文章版权
你可以在每篇文章的末尾自动添加一个版权声明框，用于声明文章出处和采用的许可协议，这对于保护原创很有帮助。
1 | post_copyright: |
文章赞助（打赏）
如果你愿意，可以开启打赏功能，在文章末尾展示你的收款二维码，以此鼓励和感谢读者的支持。
1 | reward: |
配置后，在文章下方会出现一个打赏按钮，鼠标移过去就会浮现出你设置的二维码啦。
相关文章推荐
开启此功能后，在每篇文章的末尾，系统会自动推荐内容相关的其他文章给你的读者。这不仅能增加读者的停留时间，也能让你的旧文章获得更多曝光。
1 | related_post: |
它是如何工作的？
系统会智能地分析当前文章的标签，然后找出拥有相同或相似标签的其他文章进行推荐。
文章过期提醒
对于更新不那么频繁的博客，这个功能很实用。它可以为长时间未更新的文章自动添加一个提醒横幅，提示读者内容可能不是最新的。
1 | noticeOutdate: |
提醒一下：这个功能是根据文章的最后更新时间来计算的。如果你的博客内容时效性不强，可以考虑不开启。
页脚
页脚是网站最下方的区域，你可以在这里展示一些基础信息和声明。
1 | footer: |
右下角按钮
这个区域可以放置一些实用的全局功能按钮。
繁/简切换
为你的网站添加一个简体中文与繁体中文的一键切换按钮，方便不同阅读习惯的访客。
1 | translate: |
需要注意：这个转换是基于词库的简单映射，对于一词多义等情况可能不够精准，但能满足基本的阅读需求。
夜间模式
现在很多访客都喜欢深色主题，这个功能可以让他们自由切换日间和夜间模式，保护眼睛的同时也更省电。
1 | darkmode: |
小提示：只有当你把 autoChangeMode 设置为 true 时，下面设置的 start 和 end 时间才会起作用。
复制与版权
这个设置关系到读者能否复制你的文章内容，以及复制时是否自动添加版权信息，帮你保护劳动成果。
1 | copy: |
关于版权声明：如果开启 copyright，当读者复制你的内容时，系统会自动在末尾加上一段类似“本文发表于「你的博客名」…”的声明。
字数与阅读时间
在文章中和侧边栏显示字数统计与预估的阅读时间，能让读者对阅读量有个心理预期。
首先，需要安装插件：
这个功能需要借助一个插件来实现。请在博客的根目录下，运行下面的安装命令：
1 | npm install hexo-wordcount --save |
然后，进行配置：
安装好后，你就可以在主题配置文件中启用并控制它的显示了：
1 | wordcount: |
计算标准：阅读时间基于平均阅读速度（约 300 字/分钟）估算。
本地搜索功能
为你的博客添加一个站内搜索引擎，让访客可以快速通过关键词找到他们想看的文章，大大提升浏览体验。
首先，安装必备插件：
和字数统计一样，这个功能也需要先安装一个插件。在你的博客根目录下运行：
1 | npm install hexo-generator-searchdb --save |
然后，修改主题配置：
安装完成后，在 _config.butterfly.yml 中找到搜索相关的配置，主要是将搜索方式指定为 local_search。
1 | # 搜索系统 |
配置完成后，你的博客就会出现一个搜索按钮，点击它就可以开始搜索了！
总结
你的美化之旅才刚刚开始
到这里，我们一起完成了博客的“基础装修”。希望这份详尽的记录，能让你在配置自己的 Butterfly 主题时少走一些弯路，像我一样享受从零到一搭建的乐趣。
需要说明的是：
这篇教程更像是我的一份个人配置笔记，它追求的是对核心功能的详细解说。Butterfly 主题的潜力远不止于此，还有更多有趣的配置项和更深入的定制技巧等待你去发掘。
当你想要更进一步时，我强烈建议你：
- 查阅 Butterfly 官方文档：这是最权威、最全面的信息来源，任何本文未提及的配置，这里都有标准答案。
- 善用搜索引擎：当你遇到特定问题或想实现某个具体效果时，比如“如何添加音乐播放器”或“修改悬浮按钮样式”，通常都能在网上找到前辈们分享的解决方案。
配置博客是一个不断学习和折腾的过程，永远有新的玩法。如果这篇指南为你提供了哪怕一点点的帮助，那便是我最大的荣幸。享受你的博客美化之旅吧！
微信
QQ
