如何在Next.js 13中正确配置Splide.js自动滚动轮播？

你遗漏的关键步骤 #

• 未导入Splide核心样式：Splide依赖默认样式渲染布局，缺失会导致轮播结构错乱但无控制台报错
• 未挂载自动滚动扩展：安装@splidejs/splide-extension-auto-scroll后，需将其传入mount()方法才能启用autoScroll配置
• 未等待DOM加载完成就初始化：直接在组件顶层执行Splide初始化代码，Next.js渲染阶段DOM元素尚未生成，无法找到.splide容器
• 未使用React适配版组件（可选但更优）：原生Splide写法与React生命周期不完全兼容，官方提供的React专属包能避免多数DOM时机问题

修正后的实现方案 #

方案1：原生Splide适配Next.js13 #

'use client'; // App Router下必填
import { useEffect } from 'react';
import Splide from '@splidejs/splide';
import AutoScroll from '@splidejs/splide-extension-auto-scroll';
import '@splidejs/splide/dist/css/splide.min.css';

export default function ImageCarousel() {
  useEffect(() => {
    // 确保DOM存在后初始化
    const splide = new Splide('.splide', {
      type: 'loop',
      drag: 'free',
      focus: 'center',
      perPage: 3,
      autoScroll: { speed: 1 },
    });

    // 挂载自动滚动扩展
    splide.mount({ AutoScroll });

    // 组件卸载时清理实例，防止内存泄漏
    return () => splide.destroy();
  }, []);

  return (
    <div className="splide">
      <div className="splide__track">
        <ul className="splide__list">
          <li className="splide__slide"><img src="/image1.jpg" alt="Slide 1" /></li>
          <li className="splide__slide"><img src="/image2.jpg" alt="Slide 2" /></li>
          <li className="splide__slide"><img src="/image3.jpg" alt="Slide 3" /></li>
          <li className="splide__slide"><img src="/image4.jpg" alt="Slide 4" /></li>
        </ul>
      </div>
    </div>
  );
}

方案2：使用React专属Splide组件（推荐） #

1. 安装React版依赖：

npm install @splidejs/react-splide

2. 组件代码：

'use client'; // App Router下必填
import { Splide, SplideSlide } from '@splidejs/react-splide';
import '@splidejs/react-splide/css';
import { AutoScroll } from '@splidejs/splide-extension-auto-scroll';

export default function ImageCarousel() {
  return (
    <Splide
      options={{
        type: 'loop',
        drag: 'free',
        focus: 'center',
        perPage: 3,
        autoScroll: { speed: 1 },
      }}
      extensions={{ AutoScroll }}
    >
      <SplideSlide><img src="/image1.jpg" alt="Slide 1" /></SplideSlide>
      <SplideSlide><img src="/image2.jpg" alt="Slide 2" /></SplideSlide>
      <SplideSlide><img src="/image3.jpg" alt="Slide 3" /></SplideSlide>
      <SplideSlide><img src="/image4.jpg" alt="Slide 4" /></SplideSlide>
    </Splide>
  );
}

Next.js13 特殊注意事项 #

• 客户端组件标记：App Router目录下的组件必须添加'use client';指令，Splide依赖DOM操作，无法在服务器组件中运行
• 服务器端渲染限制：禁止在服务器组件中直接初始化Splide，必须将轮播逻辑放在客户端组件的useEffect中，或使用React版组件
• 样式导入正确性：不同Splide包的样式路径不同，原生包用@splidejs/splide/dist/css/splide.min.css，React包用@splidejs/react-splide/css
• 实例清理：用原生方式时，必须在组件卸载时调用splide.destroy()，避免内存泄漏
• 响应式适配：可通过media选项针对不同屏幕调整配置，适配Next.js响应式布局：

options={{
  perPage: 3,
  media: {
    768: { perPage: 2 },
    480: { perPage: 1 },
  },
}}

内容的提问来源于stack exchange，提问作者Kisakye Moses