前言

  • 目标：先以更加简化的方式完成主题的优化搭建，后续做进一步改造和优化

安装Butterfly主题

下载butterfly主题

  • 安装hexo主题有两种方式：通过 npm 安装和通过 Git 克隆。由于通过 Git 克隆主题，可以将主题完整地下载到 themes 文件夹中，便于管理和修改。虽然相比 npm 安装稍显繁琐，但是我还是选择通过 Git 克隆。
  • 从GitHub克隆Butterfly主题到主题目录
1
git clone -b master <https://github.com/jerryc127/hexo-theme-butterfly.git> themes/butterfly

配置主题

  • 从butterfly主题下复制config.yml文件，放到hexo博客的根目录下面，并重新命名为：butterfly.config.yml
  • 打开根目录下的 _config.yml，修改字段 theme 为:
1
theme: butterfly

语言

网站资料

导航

代码块

社交图标

Butterfly 自定义图标，可以从 font-awesome v6 选择合适的图标。例如：

1
2
3
social:
   fab fa-github: https://github.com/mingnify || Github || '#24292e'
   fas fa-envelope: mailto:mingnify@gmail.com || Email || '#4a7dbe'

图片设置

favicon/网站图标设置

  • 通过 在线工具favicon （https://favicon.io/favicon-generator/）生成网站图标
  • 根目录，source 下新增文件夹：images，添加图片：favicon-Almendra.ico
  • _config.butterfly.yml文件，配置：
1
favicon: /images/favicon-Almendra.ico

头像

  • 根目录，source 下images中，添加图片：dmindie-icon.png
  • _config.butterfly.yml文件，配置：
1
2
3
4
5
avatar:
  # 头像图片链接
  img: /images/dmindie-icon.png 
  # 是否启用头像效果
  effect: false

文章封面

页面 meta 显示

首页

文章页

文章置顶

基础配置

  • 检查并确认插件，hexo-generator-index
  • 在文章中添加 sticky 参数，如下所示。数字越大，排序越高。
1
2
3
4
5
6
---
title: 打造产品指南
date: 2025-07-08 10:00:00
tags:
sticky: 100
---

elog对应配置

  • notion添加一列数据，sticky
  • elog.config.js，notion和deploy部分分别添加：sticky

页脚

Aside侧边栏

右下角按钮

全局配置

Math 数学

搜索

评论

使用waline

准备工作

1）注册 Vercel 账号

  • 前往 Vercel 官网。
  • 使用 GitHub 或其他社交账号注册并登录。

2）获取 Waline 服务端代码

image.png

部署 Waline 服务端

1）配置 Vercel 项目

  1. 在 Vercel 页面中设置项目名称并点击 “Create”。
  2. 等待部署完成（通常需要 1-2 分钟）。
  3. 部署完成后，进入项目的 “Settings” -> “Environment Variables”，配置以下环境变量：
    • LEAN_ID: LeanCloud 的 App ID（如果使用 LeanCloud 存储）。
    • LEAN_KEY: LeanCloud 的 App Key。
    • LEAN_MASTER_KEY: LeanCloud 的 Master Key。
    • 如果您使用的是国内版 LeanCloud，还需额外配置：
      • LEAN_SERVER: 绑定的域名。
    • LeanCloud找到如上变量的路径：LeanCloud首页>> 应用>> 设置 >> 应用凭证
  4. 保存环境变量后，点击 “Deployments”，选择最新的一次部署，点击右侧的 “Redeploy” 按钮重新部署。

2）获取服务端地址

  • 部署完成后，进入 Vercel 项目页面，找到 DOMAINS 中的域名地址，例如：

    text
    1
    <https://your-waline.vercel.app>

配置 Hexo + Butterfly

1）修改 Butterfly 配置文件

打开 Hexo 博客目录下的主题配置文件 _config.butterfly.yml，找到 comments 部分并修改如下：

1
2
3
4
5
6
7
8
9
10
11
comments:
  use: Waline # 启用 Waline 评论系统

waline:
  serverURL: <https://your-waline.vercel.app> # 替换为您的 Waline 服务端地址
  placeholder: 请文明发言~ # 评论框默认提示文字
  avatar: monsterid # 设置头像样式（可选值：gravatar, wavatar, monsterid 等）
  meta: [nick, mail] # 评论框必填项（昵称和邮箱）
  pageSize: 10 # 每页显示的评论数量
  lang: zh-CN # 设置语言为中文
  visitor: true # 是否启用文章阅读统计

测试与验证

  1. 在终端运行以下命令重新生成并部署博客：

    1
    hexo clean && hexo g && hexo d

  2. 打开您的博客，进入任意文章页面，检查评论框是否正常显示。

  3. 测试提交一条评论，并检查是否成功存储到 Waline 服务端。

管理评论(待完成）

1）注册管理员账号

  • 在浏览器中访问：

    text
    1
    <https://your-waline.vercel.app/ui/register>

  • 第一个注册的用户将自动成为管理员。

  • 登录后即可进入评论管理界面，对评论进行审核、删除或标记。

2）启用邮件通知

  • 在 Vercel 的环境变量中添加以下配置：
    • SMTP_HOST: 邮件服务器地址（如 smtp.gmail.com）。
    • SMTP_PORT: 邮件服务器端口（通常为 587 或 465）。
    • SMTP_USER: 邮箱地址。
    • SMTP_PASS: 邮箱密码或授权码。
    • MAIL_FROM: 发件人邮箱地址。
    • MAIL_TO: 接收通知的邮箱地址。

常见问题及优化

1）国内访问速度慢

  • 如果使用 Vercel 部署，建议绑定自定义域名并配置 CDN 加速。
    • 在vercel绑定自定义域名，例如：waline.mingnify.com
    • 在cloudflare进一步配置CDN加速
      • 类型： CNAME，正在将一个子域名指向另一个服务。
      • 名称： waline，仅填写子域名部分，即 waline。（Cloudflare 会自动将其补全为 waline.mingnify.com）。
      • 内容： cname.vercel-dns.com
  • 或者选择腾讯云、Docker 等国内服务器部署方式。

2）评论加载失败 (Failed to Fetch)

  • 检查是否正确配置了服务端地址 (serverURL)。
  • 确保博客域名已添加到 Waline 服务端的安全域名列表中。

3）美化评论区样式

  • 修改 _config.butterfly.yml 中的 waline.option 配置，例如：

    1
    2
    3
    4
    5
    waline:
      option:
        requiredMeta: [nick, mail] # 设置昵称和邮箱为必填项
        emoji: true # 启用表情包功能
        dark: auto # 根据网站主题自动切换深色模式

总结

Waline 是一个功能丰富且易于部署的评论系统。通过以上步骤，您可以在 Hexo + Butterfly 中快速集成 Waline，并享受其匿名评论、邮件通知和垃圾过滤等功能。如果您希望更高效地管理博客评论数据，还可以进一步优化服务端性能或切换到其他数据库存储方案。

在线聊天

分析统计

访问情况

方案

  • 最终方案：busuanzi 记录 site 的访问量，waline 记录page的访问量
    • 自建busuanzi
  • 原因：busuanzi 统计 page 的访问量，容易出现错误，例如：博客所有页面的访问量一样等

配置：

  • _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
32
# Busuanzi count for PV / UV in site
busuanzi:
  site_uv: true
  site_pv: true
  page_pv: true

# --------------------------------------
# Comments System 评论
# --------------------------------------

comments:
  # Up to two comments system, the first will be shown as default
  # Leave it empty if you don't need comments
  # Choose: Disqus/Disqusjs/Livere/Gitalk/Valine/Waline/Utterances/Facebook Comments/Twikoo/Giscus/Remark42/Artalk
  # Format of two comments system : Disqus,Waline
  use: Waline
  # Display the comment name next to the button
  text: false
  # Lazyload: The comment system will be load when comment element enters the browser's viewport.
  # If you set it to true, the comment count will be invalid
  lazyload: false #必须设置为 false，不然无法启用 waline 的页面访问统计
  # Display comment count in post's top_img
  count: true
  # Display comment count in Home Page
  card_post_count: true
  
  
waline:
  serverURL: 'https://my-blog-waline-three.vercel.app'
  bg:
  # Use Waline pageview count as the page view count
  pageview: true

广告

网站验证

美化特效

图片大图查看模式

标签外挂

Series系列文章

  • 适应场景：
    • 教程系列文章、深度分析或评测、游记或活动记录、读书笔记、项目开发日志
  • 使用方法：
    • 开启开关，enable，从false改为 true
    • Aside Settings 侧边栏配置，开启侧边栏展示
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Series  系列文章
series:
  enable: false # 开启要改为 true
  # Order by title or date
  orderBy: 'title'
  # Sort of order. 1, asc for ascending; -1, desc for descending
  order: 1
  number: true
  
# Aside Settings 侧边栏配置
aside: 
  card_post_series: #文章系列卡片
    enable: true
    # The title shows the series name
    series_title: false
    # Order by title or date
    orderBy: 'date'
    # Sort of order. 1, asc for ascending; -1, desc for descending
    order: -1

Mermaid

Pjax

Snackbar 弹窗

Instantpage PWA

Open Graph

CSS 前缀

Inject(无需修改主题文件，插入自定义内容）（待配置）

Inject 是 Hexo 的某些主题（如 Butterfly）中提供的功能，用于在生成的页面中插入额外的 HTML 代码，例如 JavaScript、CSS 或 Meta 标签。通过 Inject，您可以轻松地在页面的 或 的底部插入自定义内容，而无需直接修改主题的模板文件。

基本配置

1
2
3
4
5
inject:
  head:
    - <link rel="stylesheet" href="/self.css">
  bottom:
    - <script src="xxxx"></script>
  • head：将内容插入到页面的 <head> 标签中，适合添加 CSS 文件、Meta 标签等。
  • bottom：将内容插入到页面的 </body> 标签之前，适合添加 JavaScript 文件或脚本。

示例解析

  1. 添加自定义 CSS

    1
    2
    3
    inject:
      head:
        - <link rel="stylesheet" href="/blog/css/custom.css">
    • 将 /blog/css/custom.css 文件作为样式表引入。
    • 如果您的网站根目录不是 '/'，需要包含完整路径。例如，您的博客托管在 https://yoursite.com/blog/ 下，则路径需为 /blog/css/custom.css。

  2. 添加自定义 JavaScript

    1
    2
    3
    inject:
      bottom:
        - <script src="/blog/js/custom.js"></script>
    • 将 /blog/js/custom.js 文件作为脚本引入，放置在页面底部以优化加载性能。

  3. 添加 Meta 信息

    1
    2
    3
    inject:
      head:
        - <meta name="author" content="Your Name">
    • 在 <head> 中插入 Meta 标签，用于指定页面作者信息。

使用场景

  1. SEO 优化：
    • 添加自定义 Meta 标签，例如 canonical 或 description。
  2. 加载第三方资源：
    • 引入外部字体、分析脚本（如 Google Analytics）或广告代码。
  3. 样式定制和功能扩展：
    • 引入自定义 CSS 或 JavaScript 文件以实现额外的样式或功能。

注意事项

  1. 根目录设置：如果您的博客不在根目录 / 下（例如托管在 /blog/），请确保资源路径包含根目录前缀。例如：

    xml<link rel="stylesheet" href="/blog/css/style.css">

  2. HTML 格式要求：插入内容必须是标准 HTML 格式，否则可能导致页面渲染问题。

  3. 缓存问题：如果修改了 CSS 或 JS 文件，可能需要清除浏览器缓存以查看最新效果。

通过 Inject 配置，您可以轻松为 Hexo 博客添加额外的 JS、CSS 或 Meta 信息，而无需直接修改主题模板文件。这种方法简单灵活，非常适合需要定制化的场景。

CDN

参考

Butterfly 文檔(三) 主題配置