修复 Font Awesome 图标无法显示问题

问题描述：
博客的标题图标（如 h1、h2 前的图标）、hr 分割线的美化标记、以及菜单图标等 Font Awesome 图标无法正常显示。

wrong show

问题原因

Butterfly 主题默认使用 jsDelivr CDN 加载 Font Awesome：

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free/css/all.min.css">

由于 jsDelivr 在国内访问不稳定，经常被墙或速度很慢，导致字体文件无法正常加载，从而使图标显示为空白或乱码。

解决方案

将 Font Awesome CDN 更换为国内访问更稳定的 Cloudflare CDN。

修改配置文件

打开 themes/butterfly/_config.yml，找到 CDN 配置部分（大约在 1180 行左右）：

1
2
3
4
5
6
7
8
CDN:
  # The CDN provider for internal and third-party scripts
  internal_provider: local
  third_party_provider: jsdelivr

  option:
    # ... 其他配置 ...
    # fontawesome:

修改为：

1
2
3
4
5
6
7
CDN:
  internal_provider: local
  third_party_provider: jsdelivr

  option:
    # ... 其他配置 ...
    fontawesome: https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css

其他可选 CDN 方案

如果 Cloudflare 仍不稳定，可以尝试以下国内 CDN：

BootCDN（国内推荐）：

1
fontawesome: https://cdn.bootcdn.net/ajax/libs/font-awesome/6.4.0/css/all.min.css

字节跳动 CDN：

1
fontawesome: https://lf9-cdn-tos.bytecdntp.com/cdn/expire-1-M/font-awesome/6.0.0/css/all.min.css

七牛云 CDN：

1
fontawesome: https://cdn.staticfile.org/font-awesome/6.4.0/css/all.min.css

修改右侧滚动按钮为”回到底部”

默认的 Butterfly 主题右下角按钮功能是”回到顶部”，这个和footer的返回顶部功能重复了，本人不太喜欢😫，本节将介绍如何将其改为”回到底部”功能，并在接近底部时自动隐藏按钮🤗。

修改步骤

1. 修改按钮点击行为

打开 themes/butterfly/source/js/main.js，找到大约 630 行的 go-up 函数：

1
2
3
'go-up': () => { // Back to top
  btf.scrollToDest(0, 500)
},

修改为：

1
2
3
4
5
6
7
8
9
10
11
'go-up': () => { // Back to bottom
  const scrollHeight = Math.max(
    document.body.scrollHeight,
    document.documentElement.scrollHeight,
    document.body.offsetHeight,
    document.documentElement.offsetHeight,
    document.body.clientHeight,
    document.documentElement.clientHeight
  )
  btf.scrollToDest(scrollHeight, 500)
},

2. 修改按钮图标和提示文字

打开 themes/butterfly/layout/includes/rightside.pug，找到大约 59 行的按钮定义：

1
2
3
button#go-up(type="button" title=_p("rightside.back_to_top"))
  span.scroll-percent
  i.fas.fa-arrow-up

修改为：

1
2
3
button#go-up(type="button" title=_p("rightside.back_to_bottom"))
  span.scroll-percent
  i.fas.fa-arrow-down

3. 添加中文提示文字

打开 themes/butterfly/languages/zh-CN.yml，在 rightside 部分添加：

1
2
3
4
5
6
7
8
rightside:
  readmode_title: 阅读模式
  translate_title: 简繁转换
  night_mode_title: 日间和夜间模式切换
  back_to_top: 回到顶部
  back_to_bottom: 回到底部  # 添加这一行
  toc: 目录
  scroll_to_comment: 前往评论

4. 优化按钮显示逻辑（可选）

在 themes/butterfly/source/js/main.js 中，找到 scrollTask 函数（大约 424 行），可以添加以下逻辑让按钮在接近底部时自动隐藏：

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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
let flag = ''
const scrollTask = btf.throttle(() => {
  const currentTop = window.scrollY || document.documentElement.scrollTop
  const isDown = scrollDirection(currentTop)
  const scrollHeight = Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)
  const isNearBottom = currentTop + window.innerHeight >= scrollHeight - 100
  
  if (currentTop > 56) {
    if (flag === '') {
      $header.classList.add('nav-fixed')
      if (!isNearBottom) {
        $rightside.classList.add('rightside-show')
      }
    }

    if (isDown) {
      if (flag !== 'down') {
        $header.classList.remove('nav-visible')
        isChatBtn && window.chatBtn.hide()
        flag = 'down'
      }
    } else {
      if (flag !== 'up') {
        $header.classList.add('nav-visible')
        isChatBtn && window.chatBtn.show()
        flag = 'up'
      }
    }
  } else {
    flag = ''
    if (currentTop === 0) {
      $header.classList.remove('nav-fixed', 'nav-visible')
    }
    $rightside.classList.remove('rightside-show')
  }
  
  // 在接近底部时隐藏按钮，其他地方显示按钮
  if (isNearBottom && currentTop > 56) {
    $rightside.classList.remove('rightside-show')
  } else if (currentTop > 56) {
    $rightside.classList.add('rightside-show')
  }

  isShowPercent && rightsideScrollPercent(currentTop)
  checkDocumentHeight()
}, 300)

添加 Giscus 评论系统

为什么选择 Giscus？

Giscus 是基于 GitHub Discussions 的评论系统，相比其他评论系统有以下优势：

  1. GitHub 原生风格：与 GitHub 完美融合，界面统一美观
  2. OAuth 登录：使用 GitHub 账号登录，安全可靠
  3. Markdown 支持：完整支持 Markdown 语法和代码高亮
  4. 表情反应：支持 GitHub 表情 👍 ❤️ 😄
  5. 永久存储：评论存储在 GitHub，永不丢失
  6. 免费开源：完全免费，无广告
  7. 主题自适应：自动跟随博客日间/夜间模式

实现效果如下：

res show

准备工作

这里我选择再创建一个新的仓库用于存评论

1. 创建评论专用仓库

访问 https://github.com/new 创建新仓库：

  • Repository name: blog-comments
  • Description: Comments for my blog powered by Giscus
  • Visibility: ✅ Public（必须是公开的）
  • ✅ 勾选 Add a README file

2. 启用 Discussions 功能

  1. 进入刚创建的仓库
  2. 点击 Settings 标签
  3. 向下滚动到 Features 部分
  4. 勾选 ✅ Discussions
  5. 点击 Save changes

3. 安装 Giscus App

  1. 访问：https://github.com/apps/giscus
  2. 点击绿色的 Install 按钮
  3. 选择 Only select repositories
  4. 在下拉菜单中选择 blog-comments
  5. 点击 Install

获取配置参数

访问 Giscus 配置页面

访问：https://giscus.app/zh-CN

填写配置信息

  1. 语言：选择 简体中文

  2. 仓库：填写 你的GitHub用户名/blog-comments

    • 等待验证通过（会显示绿色的 ✅）

  3. 页面 ↔️ discussion 映射关系：

    • 选择 Discussion 的标题包含页面的 pathname ⭐ 推荐
    • ✅ 勾选 使用严格的标题匹配

为什么选择 pathname？

因为你的博客使用了 hexo-abbrlink 插件，每篇文章有固定的短链接（如 /posts/bb2feb5d.html）。使用 pathname 映射可以确保：

  • 修改文章标题不会影响评论
  • 每篇文章有唯一的评论讨论
  • 本地测试和线上环境都能正常工作

  1. Discussion 分类：选择 Announcements 📣

  2. 特性：

    • ✅ 启用主帖子上的反应
    • ✅ 将输入框放在评论上方
    • ✅ 按时间倒序加载评论

  3. 主题：

    • 选择 light（浅色模式，这个只是预览，实际会自动切换）

获取配置参数

页面底部会生成类似这样的代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<script src="https://giscus.app/client.js"
        data-repo="你的用户名/blog-comments"
        data-repo-id="R_kgDOQAXbjw"
        data-category="Announcements"
        data-category-id="DIC_kwDOQAXbj84CwgFy"
        data-mapping="pathname"
        data-strict="1"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="top"
        data-theme="light"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

记录下这两个重要参数：

  • data-repo-id="R_kgDOQAXbjw"
  • data-category-id="DIC_kwDOQAXbj84CwgFy"

配置 Butterfly 主题

打开 themes/butterfly/_config.yml，进行以下修改：

1. 启用 Giscus 评论系统

找到 comments 部分（大约 605 行）：

1
2
3
4
5
6
7
8
9
10
11
12
comments:
  # Up to two comments system, the first will be shown as default
  # Leave it empty if you don't need comments
  use: Giscus  # 修改这里，原来是空的
  # Display the comment name next to the button
  text: true
  # Lazyload: The comment system will be load when comment element enters the browser's viewport.
  lazyload: false
  # Display comment count in post's top_img
  count: false
  # Display comment count in Home Page
  card_post_count: false

2. 配置 Giscus 参数

找到 giscus 部分（大约 706 行）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Giscus
# https://giscus.app/
giscus:
  repo: 你的用户名/blog-comments
  repo_id: R_kgDOQAXbjw  # 替换为你的 repo_id
  category_id: DIC_kwDOQAXbj84CwgFy  # 替换为你的 category_id
  light_theme: light
  dark_theme: dark_dimmed  # 柔和的深色主题
  js:
  option:
    data-mapping: pathname
    data-strict: 1
    data-reactions-enabled: 1
    data-emit-metadata: 0
    data-input-position: top
    data-lang: zh-CN

主题说明：

  • light_theme: 博客浅色模式时使用的 Giscus 主题
  • dark_theme: 博客深色模式时使用的 Giscus 主题
  • Butterfly 会自动根据博客的日间/夜间模式切换评论主题

可选的主题配置

如果你想使用其他主题风格：

浅色主题可选：

  • light - 默认浅色
  • light_high_contrast - 高对比度浅色
  • noborder_light - 无边框浅色

深色主题可选：

  • dark - GitHub 标准深色
  • dark_dimmed - 柔和深色（推荐，护眼）
  • dark_high_contrast - 高对比度深色
  • transparent_dark - 透明深色
  • noborder_dark - 无边框深色

测试评论系统

1. 生成并启动博客

1
2
3
hexo clean
hexo generate
hexo server

2. 测试步骤

  1. 访问 http://localhost:4000
  2. 打开任意文章
  3. 滚动到文章底部
  4. 应该能看到 Giscus 评论区，显示”使用 GitHub 登录”按钮

3. 测试评论功能

  1. 点击”使用 GitHub 登录”
  2. 授权 Giscus 应用
  3. 发表一条测试评论
  4. 切换博客的日间/夜间模式，观察评论区主题是否同步切换

4. 查看评论存储

访问：https://github.com/你的用户名/blog-comments/discussions

你会看到每篇文章对应一个 Discussion，评论都存储在这里。

常见问题

Q: 评论区一直显示加载中？

A: 检查以下几点：

  1. 仓库是否是 Public（公开的）
  2. Discussions 功能是否已启用
  3. Giscus App 是否已正确安装到仓库
  4. repo_id 和 category_id 是否正确

Q: 本地测试时评论无法加载？

A: 这是正常的。Giscus 需要通过 canonical URL 来识别页面，本地的 localhost 地址可能无法正确匹配。部署到线上后就能正常工作了。

Q: 如何修改评论区的样式？

A: Giscus 使用 iframe 加载，样式受限。但你可以：

  1. 选择不同的主题（light、dark、dark_dimmed 等）
  2. 通过 option 配置其他参数
  3. Giscus 会自动跟随博客主题切换

参考资源：