导读：整理 Hexo + Butterfly 博客搭建过程中的常见问题和解决方案。

系列文章导航

  1. Hexo + Butterfly 博客搭建指南(一)：本地环境配置与运行
  2. Hexo + Butterfly 博客搭建指南(二)：部署到 Vercel
  3. Hexo + Butterfly 博客搭建指南(三)：评论系统与功能扩展
  4. Hexo + Butterfly 博客搭建指南(四)：常见问题汇总

TOC 目录高亮错位问题

问题描述

在开启固定导航栏（nav.fixed: true）的情况下，点击右侧目录链接时会出现以下现象：

  1. 页面滚动正常 - 点击目录后，页面会正确滚动到对应标题的位置，标题位于导航栏下方
  2. 目录不高亮 - 虽然滚动到了正确位置，但右侧目录中对应的项没有高亮显示
  3. 手动滚动才高亮 - 只有手动继续向下滚动，让标题到达视口顶部时，目录才会高亮

这个问题会导致用户体验不佳，因为用户点击目录后看不到当前阅读位置的指示。

原因分析

Butterfly 主题的 TOC 高亮逻辑使用了硬编码的偏移量 80px。具体实现在 themes/butterfly/source/js/main.js 第 580 行：

1
2
3
if (top > item.top - 80) {
  // 高亮当前标题
}

这个逻辑的意思是：当滚动位置超过标题位置减去 80px 时，就高亮该标题。

问题的根源：

  1. 点击目录时的行为 - Butterfly 主题会将标题滚动到导航栏下方（考虑了导航栏高度），所以标题不会到达窗口顶部
  2. 高亮检测的条件 - TOC 高亮检测的是标题是否接近视口顶部（偏移 80px）
  3. 两者不匹配 - 点击后标题在导航栏下方，但没有到达检测区域，所以不高亮

简单来说：点击目录把标题放在了导航栏下面，但高亮逻辑要求标题在视口顶部附近，两者位置不一致导致不高亮。

解决方案

取消固定导航栏

在 _config.butterfly.yml 中设置：

1
2
nav:
  fixed: false  # 不固定导航栏

这样滚动时标题会真正到达视口顶部，TOC 高亮就能正常工作。

总结

以上就是我在搭建和使用 Hexo + Butterfly 博客过程中遇到的常见问题。大部分问题都有简单的解决方案，关键是找到问题的根源。

如果你是从头开始搭建博客，建议按顺序阅读整个系列：

  • 第一篇：本地环境配置、主题安装、插件配置
  • 第二篇：部署到 Vercel、自定义域名配置
  • 第三篇：评论系统、统计分析、功能扩展
  • 本篇：常见问题汇总与故障排除

希望这篇文章能帮到你！如果有其他问题，欢迎在评论区交流。