导读：你可以把这篇当成 Hexo + Butterfly 排障流程来用。它不是泛泛的问题列表，而是我在维护 PromptNet 这个 Hexo + Butterfly 博客时实际遇到、排查过或需要长期关注的问题清单。你可以按“先复现 → 再定位配置 → 最后验证构建”的顺序排查。

系列文章导航

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

先确认问题属于哪一类

This section is the decision table for the whole troubleshooting 流程: identify the symptom, check the likely layer, then verify the fix with a build or browser test.

Hexo + Butterfly 的问题通常不是“Hexo 坏了”，而是以下几层之一出了偏差：

问题表现优先检查位置常见原因验证方式
目录点击不高亮_config.butterfly.yml、主题 JS固定导航栏和 TOC 偏移不一致本地预览点击右侧目录
H1 或标题显示异常文章 frontmatter、主题配置页面标题被主题隐藏或被布局覆盖查看生成 HTML 的 h1
封面图/图标不显示source/img、public/img、路径大小写路径写错、大小写不一致、缓存未更新浏览器直接打开图片 URL
Vercel 部署后仍是旧页面构建缓存、仓库分支、Hexo clean没有清理旧 public 或构建源不对重新构建并检查部署日志
本地正常线上异常Node 版本、依赖锁文件、环境变量本地和 CI 环境不一致对比 node -v 与构建日志

建议先跑一遍本地基础命令：

1
2
3
4
npm install
npx hexo clean
npx hexo generate
npx hexo server

如果本地 generate 都失败，先不要看 Vercel 或 CDN；如果本地正常、线上异常，再看部署日志和缓存。

TOC 目录高亮错位问题

问题描述

在开启固定导航栏（nav.fixed: true）时，点击右侧目录链接可能出现：

  1. 页面能滚动到对应标题；
  2. 右侧目录项没有立即高亮；
  3. 手动继续滚动一小段后才高亮。

这个问题影响阅读体验，尤其是长教程文章。读者点了目录以后，看不到当前位置反馈，会误以为目录失效。

原因分析

Butterfly 的目录高亮依赖滚动位置和标题位置的偏移判断。固定导航栏会改变标题在视口中的实际位置，而 TOC 高亮逻辑仍可能按照固定偏移判断。

我的处理原则是：优先用配置规避，而不是直接改主题源码。因为主题源码改动在后续升级时最容易丢失。

推荐修复

在 _config.butterfly.yml 中关闭固定导航：

1
2
nav:
  fixed: false

修复后验证：

  1. npx hexo clean && npx hexo generate && npx hexo server；
  2. 打开一篇有 5 个以上 H2 的长文；
  3. 点击右侧目录的中间章节；
  4. 确认页面跳转和目录高亮一致。

如果你必须保留固定导航栏，再考虑自定义 CSS 或 JS 偏移，但这类方案要记录清楚，否则后续升级主题时很难维护。

H1 标题消失或层级异常

现象

文章页面看起来有标题，但源码里没有标准 H1，或者正文直接从 H2 开始。SEO 审计工具会提示：

  • 缺少 H1；
  • H1 过多；
  • 标题层级跳跃。

排查顺序

  1. 检查文章 frontmatter 是否有 title；
  2. 检查主题是否在文章页输出标题；
  3. 检查自定义 layout 或 CSS 是否隐藏了标题；
  4. 检查正文是否手动写了 # 一级标题，导致页面出现多个 H1。

推荐写法

文章正文不要再写一个 # 标题。让 frontmatter 的 title 作为页面标题，正文从 ## 开始：

1
2
3
4
5
6
7
8
---
title: Hexo + Butterfly 博客搭建指南
description: ...
---

## 准备工作

## 部署步骤

验证方式：打开浏览器开发者工具，搜索 <h1，文章页应该只有一个主标题。

封面图、横幅图或 favicon 不显示

常见原因

原因表现修复方式
路径大小写不一致Windows 本地正常，线上 404文件名和引用路径完全一致
图片没有放到 source/构建后 public 没有图片放到 source/img/...
主题配置路径少了 /某些页面相对路径错误使用 /img/... 绝对路径
缓存未刷新图片替换后仍显示旧图hexo clean 后重建

验证方法

不要只看页面是否显示，直接打开图片 URL：

1
https://www.promptnet.cn/img/covers/cover3.webp

如果图片 URL 直接 404，就不是文章问题，而是资源路径或构建产物问题。

Vercel 部署后页面仍然是旧内容

先判断是不是本地没生成

1
2
npx hexo clean
npx hexo generate

然后到 public/ 目录中搜索文章标题。如果 public/ 里还是旧内容，说明问题在本地生成阶段；如果 public/ 是新内容但线上旧，说明问题在部署或缓存。

常见排查表

检查项判断方法处理方式
分支是否正确Vercel 部署日志里的 commit确认推送的是绑定分支
构建命令是否正确Vercel Build Command使用 hexo generate 或项目脚本
是否清理缓存日志是否重新安装/构建必要时 Redeploy with Clear Cache
是否 CDN 缓存加随机参数访问页面等待缓存或手动清理

如果你在改主题配置，建议每次部署前都执行：

1
npx hexo clean && npx hexo generate

这能避免旧模板、旧资源残留在 public/。

Butterfly 主题配置不生效

Butterfly 有两类配置：Hexo 根目录 _config.yml 和主题配置 _config.butterfly.yml。很多问题来自“改错配置文件”。

要改的内容优先修改
站点标题、URL、permalink_config.yml
菜单、封面、侧边栏、TOC、版权_config.butterfly.yml
主题源码行为尽量避免，必要时记录 patch

排查方式：

  1. 确认修改的是根目录的 _config.butterfly.yml，不是主题目录里的示例配置；
  2. 修改后执行 hexo clean；
  3. 如果仍不生效，检查是否有同名配置被 _config.yml 覆盖。

官方参考与 资料来源：

这些 official documents 是排查 Hexo 命令、主题配置和构建行为时的主要依据。遇到版本差异时，优先以当前官方文档和本地 package.json 版本为准。

我的建议排查顺序

遇到 Hexo + Butterfly 问题时，不要直接改主题源码。按这个顺序来：

  1. 复现问题：本地和线上是否都能复现；
  2. 看生成结果：检查 public/ 里生成的 HTML/图片是否正确；
  3. 查配置层：根配置、主题配置、文章 frontmatter；
  4. 查缓存层：hexo clean、Vercel Clear Cache、浏览器缓存；
  5. 最后才看源码层：确认不是配置能解决的问题后，再考虑主题源码。

相关内链

如果你还在搭建阶段，建议按顺序读：

总结

Hexo + Butterfly 的多数问题都可以通过“配置 → 构建 → 缓存”三层定位出来。真正需要改主题源码的情况并不多。我的经验是：每次修改配置后都执行 hexo clean && hexo generate，再检查生成后的 HTML 和资源路径，比直接在线上猜问题更可靠。