Swiper初始化失败主因是DOM未就绪就调用new Swiper()，应确保在DOMContentLoaded事件或</body>前执行；同时需严格遵循swiper-wrapper、swiper-slide等HTML结构及CSS引入要求。
Swiper 初始化失败：DOM 元素未就绪就调用 new Swiper()
常见错误是把 new Swiper() 写在 <script> 标签里，且放在 <head> 中或 DOM 元素上方。浏览器还没解析到轮播容器，document.querySelector('.swiper') 就返回 null，直接报错 Cannot initialize Swiper with null selector。
解决方法只有两个可靠时机：
- 把
<script>放在</body>前，确保 HTML 已加载完毕 - 用
DOMContentLoaded包裹初始化逻辑：document.addEventListener('DOMContentLoaded', () => { new Swiper('.swiper', { /* 配置 */ }); }); - 若使用模块导入（如 ES import），仍需确保调用时 DOM 已就绪，不能依赖模块加载顺序
触摸滑动无效：缺少必需的 CSS 类与结构
Swiper 不是纯 JS 库，它严重依赖预设的 HTML 结构和 CSS 类名。漏掉任意一个关键类，触摸事件、过渡动画、分页器都会失效。
最简可用结构必须包含：
立即学习“前端免费学习笔记（深入）”；
- 外层容器带
class="swiper" - 内部包裹容器带
class="swiper-wrapper" - 每个幻灯片为
class="swiper-slide"的子元素 - 必须引入 Swiper 的 CSS 文件（如
swiper-bundle.min.css），否则transform和touch-action等样式缺失，iOS/Android 触摸会直接穿透或卡顿
错误示例（少 wrapper）：
<div class="swiper"> <div class="swiper-slide">Slide 1</div> <div class="swiper-slide">Slide 2</div> </div>正确写法：
<div class="swiper">
<div class="swiper-wrapper">
<div class="swiper-slide">Slide 1</div>
<div class="swiper-slide">Slide 2</div>
</div>
</div>
移动端滑动卡顿或跳变：disableOnInteraction 与 loop 模式冲突
启用 loop: true 后，Swiper 会在首尾自动插入复制幻灯片实现无缝循环。此时若同时设置 disableOnInteraction: true（默认值），用户手动滑动一次后，所有交互（包括触摸拖拽、分页点击）会被禁用，表现为“滑一下就卡住”。
真实场景中，绝大多数触控轮播需要持续交互，应显式关闭该限制：
- 设
disableOnInteraction: false—— 允许用户反复滑动、点击分页器、调用slideTo()等 - 注意：iOS Safari 在
loop模式下快速来回滑可能触发回弹抖动，可加shortSwipes: true和longSwipes: true平衡灵敏度 - 若不需要无限循环，直接关掉
loop，能省去复制节点、减少内存占用，也避免部分安卓 WebView 的渲染异常
自定义导航按钮不响应：事件绑定时机与作用域问题
很多人用 querySelector 找到 .swiper-button-next 后直接绑 click，再调用 swiper.slideNext()，结果点不动。原因通常是：
- 按钮 DOM 节点在 Swiper 初始化前就绑了事件，但此时
swiper实例还没创建，swiper.slideNext()报undefined is not a function - 按钮不在 Swiper 容器内，且未手动初始化（Swiper 不自动接管外部按钮）
- 用了
navigation: { nextEl: '.my-next' }配置，却还额外手写 click 监听，造成重复调用或上下文丢失
推荐做法：交给 Swiper 自动管理导航 —— 只需配置并确保元素存在：
new Swiper('.swiper', {
navigation: {
nextEl: '.swiper-button-next',
prevEl: '.swiper-button-prev',
},
});
对应 HTML 必须有：<div class="swiper-button-next"></div> <div class="swiper-button-prev"></div>Swiper 会在初始化时自动绑定事件，并处理禁用态、焦点、键盘支持等细节。
Swiper 的触摸行为高度依赖结构、样式、初始化时机三者的严格配合；漏掉任一环，表面看只是“滑不动”，实际根源可能分散在 HTML、CSS、JS 三个层面。
