如何修复 Swiper.js 轮播图无法循环播放的问题

swiper.js 启用 `loop: true` 时仍无法无缝循环，通常是因启用了不兼容的 `cssmode: true` 导致——该模式依赖 css scroll snap api，会禁用包括 loop 在内的多项核心功能。

在使用 Swiper.js 构建作品集轮播图时，许多初学者会遇到“滑动到最后一个幻灯片后无法自动回到第一个”的问题，即使已明确配置 loop: true。根本原因在于：cssMode: true 与 loop 功能互斥。

根据 Swiper 官方文档，启用 cssMode 会强制 Swiper 使用原生 CSS Scroll Snap 实现滚动，牺牲了大量高级特性（如无限循环、动态 slide 增删、自定义过渡动画等）。因此，只要保留 cssMode: true，loop: true 将完全失效。

✅ 正确做法是：移除 cssMode: true 配置项，并确保 HTML 结构与 Swiper v10 的类名规范一致：

let swiperPortfolio = new Swiper('.portfolio__container', {
  loop: true, // ✅ 保持启用
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
  pagination: {
    el: '.swiper-pagination',
    clickable: true,
  },
  autoplay: {
    delay: 5000,
    disableOnInteraction: false // 推荐添加：用户操作后继续自动播放
  },
  mousewheel: true,
  keyboard: true,
  // ❌ 删除这一行：cssMode: true,
});

同时注意以下关键细节：

• HTML 类名更新：Swiper v10 已弃用 .swiper-container，应改用 .swiper（否则初始化可能失败）：

  
  
    
  
      
  ...
      
    
    
  

• 引入 CSS 文件：必须加载 Swiper 样式表，否则分页器、导航按钮等 UI 元素将不可见或错位：

  

  DeepSider

  浏览器AI侧边栏对话插件，集成多个AI大模型

  下载

• 最小 slide 数量要求：Swiper 的 loop 模式要求至少 3 个 slide 才能生效（你当前有 3 个，符合要求）。若后续减少为 2 个，需手动添加 loopAdditionalSlides: 1 配置以保证稳定性。

• 避免重复配置项：你的原始代码中 autoplay: true 和 autoplay: { delay: 5000 } 同时存在，后者会覆盖前者；建议统一使用对象形式，并补充 disableOnInteraction: false 提升用户体验。

最后提醒：loop: true 会在 DOM 中自动克隆首尾 slide（生成 swiper-slide-duplicate），这是实现无缝循环的必要机制。请勿在 CSS 中对 .swiper-slide-duplicate 做隐藏或样式干扰，否则会导致视觉跳变。

完成以上调整后，轮播图即可实现平滑、无限循环，完美适配个人作品集展示场景。