🚨 问题现象

昨天我的博客突然出现了问题：文章页面显示为空白，从首页点击文章链接后，页面内容完全为空。

具体表现：

  • 首页文章列表正常显示
  • 点击文章标题进入详情页
  • 文章页面返回 HTTP 200，但 content-length: 0
  • 本地 hexo generate 生成的 public/文章路径/index.html 文件大小为 0 字节

文章页面为空

🔍 诊断过程

第一步：检查本地生成文件

1
2
3
cd blog-source
ls -la public/2026/02/11/hello-world/
# 输出：-rw-rw-r-- 1 admin admin 0 Feb 11 18:14 index.html

发现：本地生成的文件大小为 0 字节！说明问题出在生成阶段，而不是部署阶段。

第二步：查看构建日志

1
hexo generate --debug 2>&1 | grep -E "(ERROR|WARN|TypeError)"

发现关键错误：

1
2
ERROR TypeError: Cannot read property 'wordcount' of undefined
    at /themes/butterfly/layout/includes/header/post-info.pug:46

第三步：定位问题根源

错误指向 post-info.pug 第 46 行，代码试图调用 wordcount 函数，但该函数未定义。

查看 Butterfly 主题配置：

1
2
3
4
5
6
# _config.butterfly.yml
wordcount:
  enable: true
  post_wordcount: true
  min2read: true
  total_wordcount: false

发现问题：主题启用了字数统计功能，但没有安装 hexo-wordcount 插件！

🎯 根本原因

Hexo Butterfly 主题的 wordcount 功能依赖 hexo-wordcount 插件。当主题配置启用该功能但插件未安装时，Pug 模板渲染会抛出 TypeError 错误，导致整个文章页面渲染失败，生成空文件。

相关知识：

  • Hexo 渲染是管道式的，如果某个模板渲染失败，不会报错退出，而是生成空文件
  • 这解释了为什么只有文章页面有问题，而首页正常（首页模板不需要 wordcount）

✅ 解决方案

方案一：禁用字数统计（推荐）

编辑 _config.butterfly.yml：

1
2
3
4
5
wordcount:
  enable: false
  post_wordcount: false
  min2read: false
  total_wordcount: false

然后重新生成：

1
2
hexo clean
hexo generate

方案二：安装缺失插件

如果你确实需要字数统计功能：

1
npm install hexo-wordcount --save

然后重新生成博客。

验证修复

1
2
du -h public/2026/02/11/hello-world/index.html
# 输出：16K    public/2026/02/11/hello-world/index.html

文件大小从 0 字节变为 16KB，问题解决！

🐛 GitHub Pages 缓存问题

修复后本地正常，但部署到 GitHub Pages 后发现线上还是空的。

症状

  • 本地文件：16KB ✅
  • GitHub 仓库：文件正常 ✅
  • GitHub Pages 访问：空文件（content-length: 0）❌

诊断

1
2
curl -I https://yadinae.github.io/2026/02/11/hello-world/
# 输出：last-modified: Thu, 12 Feb 2026 05:31:03 GMT

发现：last-modified 时间未更新，说明 GitHub Pages 拿的是缓存版本。

解决方案

方法1：添加新文件触发重新构建

1
2
echo "$(date)" > public/REFRESH.txt
hexo deploy

方法2：修改自定义域名配置

如果你配置了自定义域名：

  1. 访问 GitHub Pages Settings
  2. 删除并重新添加自定义域名
  3. 这会强制触发 GitHub Pages 重新构建

方法3：等待自动刷新

GitHub Pages 通常会在 5-10 分钟后自动刷新缓存。

验证

1
2
3
curl -I https://yadinae.github.io/2026/02/11/hello-world/
# 输出：last-modified: Thu, 12 Feb 2026 12:17:33 GMT
#       content-length: 14550

GitHub Pages 已更新！

🛡️ 预防措施

1. 构建前本地验证

1
2
3
hexo clean
hexo generate
hexo server

访问 http://localhost:4000 确认所有页面正常后再部署。

2. 检查文件大小

1
find public -name "index.html" -exec du -h {} \; | sort -h

如果某个 index.html 大小接近 0，说明该页面渲染失败。

3. 启用调试模式

1
hexo generate --debug 2>&1 | tee build.log

保存完整构建日志便于排查。

4. 主题配置备份

修改主题配置前先备份：

1
cp _config.butterfly.yml _config.butterfly.yml.bak

5. 依赖管理

定期检查和更新依赖：

1
2
npm outdated
npm update

📝 总结

问题 原因 解决方案
文章页面为空（0字节） Butterfly 主题 wordcount 配置缺少依赖 禁用 wordcount 或安装 hexo-wordcount 插件
GitHub Pages 显示旧版本 CDN 缓存未刷新 添加新文件或修改域名配置触发重新构建

🔧 常用调试命令

1
2
3
4
5
6
7
8
9
10
11
# 检查生成文件大小
find public -name "index.html" -exec du -h {} \;

# 查看构建日志
hexo generate --debug 2>&1 | grep -E "(ERROR|WARN|TypeError)"

# 检查 GitHub Pages 返回信息
curl -I https://your-site.github.io/path/to/post/

# 本地测试
hexo server

📚 相关资源

踩坑时间：2026-02-12
解决时间：2小时
经验等级：★★★★☆

💡 技术踩坑不可避免，关键是要形成知识沉淀，下次遇到类似问题时能快速定位解决。