Hexo Butterfly 5.4 分页问题 & YAML 错误 解决方法总结

Hexo Butterfly 5.4 分页问题 & YAML 错误 解决方法总结

本次问题核心是 “首页分页显示不全（仅 1、2…11）” 与 “hexo clean 报错 YAML 重复键”，最终通过配置文件修正 + 主题模板调整解决，具体步骤如下：

一、先解决「YAML 重复键报错」（基础前提）

问题原因

_config.yml 中 index_generator 节点下重复定义了 per_page 键（同时写了per_page: 6和per_page: 10），YAML 语法不允许同一层级重复键，导致 Hexo 命令无法执行。

解决步骤

1. 打开 Hexo 根目录的 _config.yml，找到 index_generator 配置段：

index_generator:
  per_page: 6          # 重复的键，删除
  path: ''             # 保留
  per_page: 10         # 保留需要的数值（如10）
  order_by: -date      # 保留

1. 删除重复的 per_page: 6，最终修正为：

index_generator:
  per_page: 10         # 每页文章数量（与全局分页保持一致）
  path: ''             # 首页路径（默认根目录）
  order_by: -date      # 文章按日期倒序排序

1. 保存文件，此时执行 hexo clean 不会再报 YAML 错误。

二、解决「首页分页显示不全」（核心需求）

问题原因

Butterfly 5.4 主题无 page_display 配置项，分页显示逻辑由 themes/butterfly/layout/includes/pagination.pug 模板控制，默认 mid_size: 1（仅显示当前页前后 1 个页码），多余页码会被省略为 ...。

解决步骤

1. 打开主题模板文件：themes/butterfly/layout/includes/pagination.pug

2. 找到分页配置的 options 变量，重点修改 mid_size 参数：

-
  var options = {
    prev_text: '<i class="fas fa-chevron-left fa-fw"></i>',  # 上一页图标
    next_text: '<i class="fas fa-chevron-right fa-fw"></i>', # 下一页图标
    mid_size: 999,  # 关键修改：设为超大值（覆盖所有页码数量），避免省略
    escape: false
  }

• • 原默认 mid_size: 1 → 改为 mid_size: 999（确保覆盖你博客的总页数，比如 11 页就足够）。

1. 执行 Hexo 命令刷新配置与静态文件：

hexo clean  # 清理旧缓存（必须执行，避免旧模板残留）
hexo g      # 重新生成静态文件
hexo s      # 启动本地服务预览

1. 验证效果：

• • 浏览器访问 http://localhost:4000，下拉到首页底部，分页条会显示所有页码（如 1、2、3…11），可直接点击任意中间页码（如 5）跳转。
• • 若样式无变化，按 Ctrl+F5 强制刷新浏览器（清除浏览器缓存）。

三、关键注意事项

1. 版本适配：此方法仅针对 Butterfly 5.4（无 home.page_display 配置的版本），旧版本（如 4.x）可能需调整 _config.butterfly.yml，但 5.4 需改模板。

2. 缓存必清：修改配置 / 模板后，必须执行 hexo clean，否则 Hexo 会沿用旧缓存，导致修改不生效。

3. 语法规范：_config.yml 严格遵循 YAML 语法（缩进用 2 空格、不重复键），避免类似 “重复 per_page” 的低级错误。

通过以上两步，先解决配置文件的语法错误，再通过修改主题模板的分页参数，即可实现 “首页分页显示所有页码、直接点击任意页跳转” 的需求。