如何使用hexo-butterfly-swiper-x

📦 第一步：安装插件

在博客根目录下打开终端，先卸载原版（如果装过），再安装增强版：

1 2	npm uninstall hexo-butterfly-swiper npm install hexo-butterfly-swiper-x --save

💡 为什么用增强版？ 增强版支持默认封面图和随机排序功能，比原版更灵活。

⚙️ 第二步：添加配置

在博客根目录的 _config.butterfly.yml（或 _config.yml）中添加以下配置：

# hexo-butterfly-swiper-x 配置
swiper:
  enable: true                    # 开启轮播图
  priority: 5                     # 优先级，数字越小越靠前
  enable_page: /                  # '/' 表示仅在首页显示
  timemode: date                  # 显示日期（date=创建日期）
  
  # 轮播图挂载的位置
  layout:
    type: id                      # 挂载容器类型（id 或 class）
    name: recent-posts            # 挂载到 id 为 recent-posts 的元素之前
    index: 0
  
  # ✨ 增强版特有：默认图（当文章没有封面时使用）
  default_img: https://cdn.jsdelivr.net/gh/你的用户名/图片仓库/default.jpg
  default_img_mode: false         # 设为 true 则强制所有文章都用默认图
  
  # CDN 链接
  swiper_css: "https://cdn.jsdelivr.net/npm/hexo-butterfly-swiper-x/lib/swiper.min.css"
  swiper_js: "https://cdn.jsdelivr.net/npm/hexo-butterfly-swiper-x/lib/swiper.min.js"
  custom_css: "https://cdn.jsdelivr.net/npm/hexo-butterfly-swiper-x/lib/swiperstyle.css"
  custom_js: "https://cdn.jsdelivr.net/npm/hexo-butterfly-swiper-x/lib/swiper_init.js"

⚠️ 注意：name: recent-posts 是针对 Butterfly 主题的默认设置，如果你用的是其他主题，可能需要修改这个值。

✏️ 第三步：在文章中启用轮播

在你想展示到轮播图的文章 front-matter 中添加 swiper_index 参数：

---
title: 我的第一篇文章
date: 2026-06-01
cover: https://cdn.jsdelivr.net/gh/你的用户名/图片仓库/cover.jpg
description: 这是一篇精彩的文章摘要
swiper_index: 1          # 轮播顺序，数字越大越靠前
---

💡 小技巧：cover 可以是本地路径（如 /images/cover.jpg），也可以是完整 URL。推荐使用 CDN 链接以获得更快的加载速度。

🎲 第四步（可选）：开启随机排序

如果你想让每次刷新页面时轮播图的顺序都不一样，可以在文章中添加 random_swiper_index 参数：

---
title: 随机展示的文章
date: 2026-06-01
cover: https://cdn.jsdelivr.net/gh/你的用户名/图片仓库/cover.jpg
random_swiper_index: true    # 开启随机排序
---

⚠️ 注意：random_swiper_index 和 swiper_index 可以同时存在，插件会自动处理排序逻辑。

🚀 第五步：重新部署

完成以上配置后，在终端依次运行：

1
2
3

hexo clean
hexo generate
hexo deploy

刷新你的博客首页，轮播图就会出现啦！

📋 参数速查表

参数	类型	说明
`swiper_index`	非负整数	轮播顺序，数字越大越靠前
`random_swiper_index`	true/false	开启后该文章参与随机排序
`cover`	图片URL	轮播图显示的封面
`description`	文本	轮播图上显示的文章摘要

❓ 常见问题

Q1：轮播图不显示怎么办？

按顺序排查：

是否有至少 2-3 篇文章添加了 swiper_index？（单篇文章不会触发轮播）
enable: true 是否设置？
layout.name: recent-posts 与你主题的容器 ID 是否匹配？

Q2：轮播切换速度怎么调整？

有两种方法：

方法一：下载 /lib/swiper_init.js 文件放到本地，修改其中的 delay 参数（单位毫秒），然后修改配置中的 custom_js 路径。
方法二：直接在配置中添加 delay: 5000（部分版本支持）。

Q3：可以用本地图片吗？

可以。把图片放在 source/images/ 目录下，配置时用 /images/xxx.jpg 的相对路径即可。

Q4：和原版 `hexo-butterfly-swiper` 有什么区别？

特性	原版	增强版
默认封面图	❌	✅
随机排序	❌	✅
维护状态	官方	第三方

🔗 相关资源

🎉 结语

恭喜！你的博客首页现在有了一个漂亮的轮播图。如果遇到任何问题，欢迎在评论区留言交流～