Swiper不是HTML标签，必须引入JS文件、初始化实例且HTML结构严格符合DOM约束；v11+需ESM导入，禁用UMD，最简结构为<div class="swiper"><div class="swiper-wrapper"><div class="swiper-slide">…</div></div></div>。
Swiper 不是 HTML 标签，不能靠写 <swiper> 或加个 class="swiper" 就跑起来——必须引入 JS 文件、初始化实例、且 HTML 结构要严格符合 Swiper 的 DOM 约束。
Swiper v11+ 必须用 ESM 方式导入，CDN 直引 script 会报错
Swiper v11 起彻底移除 UMD/全局变量支持，<script src="https://cdn.jsdelivr.net/npm/swiper@11"></script> 引入后直接调用 new Swiper(...) 会抛 Uncaught ReferenceError: Swiper is not defined。
- 必须用
<script type="module">包裹初始化代码 - 或在已有模块环境（如 Vite、Webpack）中用
import { Swiper } from 'swiper' - CDN 推荐用 esm.sh：
import { Swiper, Navigation, Pagination } from 'https://esm.sh/swiper@11' - 如果硬要用传统 script 标签，只能降级到 v10.4.1（最后支持 UMD 的版本）
HTML 结构不按 Swiper 规范写，轮播直接不渲染
Swiper v11 对 DOM 层级和 class 名敏感，哪怕少一个 swiper-wrapper 或多一层 <div>，都会导致 slidesPerView 失效、导航按钮无响应、甚至整个容器空白。
- 最简合法结构必须包含：
<div class="swiper"><div class="swiper-wrapper"><div class="swiper-slide">...</div></div></div> -
.swiper-slide必须是.swiper-wrapper的**直接子元素**，嵌套<div>会破坏 slide 计数 - 导航按钮（prev/next）需带
class="swiper-button-prev"和class="swiper-button-next"，且放在.swiper内部任意位置 - 分页器（pagination）需额外声明
class="swiper-pagination"，并传入pagination: { el: '.swiper-pagination' }
自动播放失效的三个高频原因
设了 autoplay: { delay: 3000 } 却没反应，大概率卡在这三处：
立即学习“前端免费学习笔记（深入）”；
- 没启用
Autoplay模块：v11 必须显式 import 并use([Autoplay])，否则配置被忽略 - 轮播容器初始
display: none或父级visibility: hidden：Swiper 初始化时读不到尺寸，autoplay直接静默跳过 - 页面切到后台标签页后恢复，出现连播：需配合
disableOnInteraction: false+ 手动监听visibilitychange重置 timer
移动端 touch 滑动卡顿或失效
PC 上拖拽正常，手机上滑不动/一卡一卡，不是性能问题，而是 Swiper 默认关闭了部分移动端行为：
- 确认是否启用了
TouchEvents模块（v11 已内置，但若手动删了use([])里的默认项就可能丢失） -
threshold值太小（如设成 1），手指轻微抖动就触发滑动；建议设为10或20 - 父容器或 body 上有
touch-action: none或passive: false的事件监听器，会拦截原生 touch 事件 - 图片未设
width/height或object-fit，导致 layout shift，Swiper 无法稳定计算 slide 宽度
Swiper 的坑不在 API 多难记，而在它对 HTML 结构、模块加载顺序、CSS 可见性这些“边缘条件”极其敏感——漏掉一个 swiper-wrapper，或 import 少一个模块，轮播就只是静态盒子。
