Swiper滑动时SwiperSlide组件不显示问题求助

问题描述 #

安装SwiperJs后，复制官方文档代码实现图片轮播，出现以下异常：

• 仅首张图片可见，其余滑块隐藏；
• 滑动时Swiper内容区域变为空白；
• 浏览器开发者工具中可查看到组件及正确的图片URL；
• 代码在CodeSandBox中可正常运行，但直接写入项目App.tsx失效。

代码示例 #

import "./styles.css";
import { Swiper, SwiperSlide } from "swiper/react";
import { Navigation, Pagination } from "swiper/modules";
import "swiper/css";
import "swiper/css/navigation";
import "swiper/css/pagination";

const picturesData = [
  "https://s1.qwant.com/thumbr/474x355/9/c/d04da36fa6514683e4f28b1af1eec6b12caf9afa325d6c5fa63594b4ee8bb6/th.jpg?u=https%3A%2F%2Ftse.mm.bing.net%2Fth%3Fid%3DOIP.DQQvjgN8K2-7UV2g2CrnjwHaFj%26pid%3DApi&q=0&b=1&p=0&a=0",
  "https://s2.qwant.com/thumbr/474x474/6/7/8ecfe76ab151109b6d09c817e53af064fa9112084cd9abf283d3cb69cdffd7/th.jpg?u=https%3A%2F%2Ftse.mm.bing.net%2Fth%3Fid%3DOIP.xklM3kSc5GdzZ5N_w54vaQHaHa%26pid%3DApi&q=0&b=1&p=0&a=0",
  "https://s1.qwant.com/thumbr/474x266/a/6/18d93d8fd9d37a7b0a9b5b3a3112ce4cc90ede3d7f39c8bb5aae36f677122a/th.jpg?u=https%3A%2F%2Ftse.mm.bing.net%2Fth%3Fid%3DOIP.3hUwEcr8mssPw6qhMeAEQwHaEK%26pid%3DApi&q=0&b=1&p=0&a=0",
];

export default function App() {
  const year = 2025;
  return (
    <div className="App">
      <section>
        <h2>{year}</h2>
        <Swiper
          spaceBetween={50}
          slidesPerView={1}
          onSlideChange={() => console.log("slide change")}
          onSwiper={(swiper) => console.log(swiper)}
          modules={[Navigation, Pagination]}
          pagination={{ clickable: true }}
        >
          {picturesData.map((singleImage, index) => {
            return (
              <SwiperSlide>
                <img src={singleImage} alt="picture" key={index} />
              </SwiperSlide>
            );
          })}
        </Swiper>
      </section>
    </div>
  );
}

可能的原因及解决方案 #

1. CSS样式冲突或未正确加载 #

• 排查全局样式是否覆盖了Swiper核心样式：比如全局img设置display: none、.swiper-slide被强制设置overflow: hidden等；
• 确认Swiper样式导入是否生效：有些打包工具会对未“直接使用”的样式做Tree Shaking，可尝试将样式导入移至全局样式文件，或在组件中确保导入语句被执行。

2. Swiper初始化时机问题 #

如果项目使用SSR（如Next.js、Gatsby），DOM未完全挂载时Swiper无法正确计算容器尺寸：

import { useEffect, useState } from 'react';

export default function App() {
  const [isMounted, setIsMounted] = useState(false);
  
  useEffect(() => {
    setIsMounted(true);
  }, []);

  if (!isMounted) return null;

  // 原组件渲染逻辑
}

3. 版本不一致 #

CodeSandBox与本地项目的Swiper版本可能存在差异，新版本API或样式结构有变化：

• 执行npm list swiper查看本地版本，对比CodeSandBox中的版本；
• 若版本不一致，升级/降级本地Swiper至匹配版本，或根据本地版本调整代码（如模块导入方式、配置参数）。

4. 容器尺寸未明确设置 #

Swiper需要固定尺寸的容器才能正常计算滑块位置：

/* 在styles.css中添加 */
.custom-swiper {
  width: 100%;
  height: 400px;
}

// 在Swiper组件上添加类名
<Swiper className="custom-swiper" {...otherProps}>
  {/* 滑块内容 */}
</Swiper>

5. 图片加载导致布局重绘异常 #

图片加载完成后改变滑块尺寸，导致Swiper布局计算错误：

import { useRef } from 'react';

export default function App() {
  const swiperRef = useRef(null);

  const handleImageLoad = () => {
    swiperRef.current?.update();
  };

  return (
    <Swiper ref={swiperRef} {...otherProps}>
      {picturesData.map((imgUrl, index) => (
        <SwiperSlide key={index}>
          <img src={imgUrl} alt="picture" onLoad={handleImageLoad} />
        </SwiperSlide>
      ))}
    </Swiper>
  );
}

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