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 命令无法执行。
解决步骤
- 打开 Hexo 根目录的 _config.yml，找到 index_generator 配置段：
index_generator:per_page: 6 # 重复的键，删除path: '' # 保留per_page: 10 # 保留需要的数值（如10）order_by: -date # 保留
- 删除重复的 per_page: 6，最终修正为：
index_generator:per_page: 10 # 每页文章数量（与全局分页保持一致）path: '' # 首页路径（默认根目录）order_by: -date # 文章按日期倒序排序
- 保存文件，此时执行 hexo clean 不会再报 YAML 错误。
二、解决「首页分页显示不全」（核心需求）
问题原因
Butterfly 5.4 主题无 page_display 配置项，分页显示逻辑由 themes/butterfly/layout/_partials/pagination.pug 模板控制，默认 mid_size: 1（仅显示当前页前后 1 个页码），多余页码会被省略为 ...。
解决步骤
-
打开主题模板文件：themes/butterfly/layout/_partials/pagination.pug
-
找到分页配置的 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 页就足够）。
- 执行 Hexo 命令刷新配置与静态文件：
hexo clean # 清理旧缓存（必须执行，避免旧模板残留）
hexo g # 重新生成静态文件
hexo s # 启动本地服务预览
- 验证效果：
-
- 浏览器访问 http://localhost:4000，下拉到首页底部，分页条会显示所有页码（如 1、2、3…11），可直接点击任意中间页码（如 5）跳转。
-
- 若样式无变化，按 Ctrl+F5 强制刷新浏览器（清除浏览器缓存）。
三、关键注意事项
-
版本适配：此方法仅针对 Butterfly 5.4（无 home.page_display 配置的版本），旧版本（如 4.x）可能需调整 _config.butterfly.yml，但 5.4 需改模板。
-
缓存必清：修改配置 / 模板后，必须执行 hexo clean，否则 Hexo 会沿用旧缓存，导致修改不生效。
-
语法规范：_config.yml 严格遵循 YAML 语法（缩进用 2 空格、不重复键），避免类似 “重复 per_page” 的低级错误。
通过以上两步，先解决配置文件的语法错误，再通过修改主题模板的分页参数，即可实现 “首页分页显示所有页码、直接点击任意页跳转” 的需求。