非Create React App的React项目如何支持纯ESM包升级Swiper到V7

错误根源：你的项目构建（尤其是服务端构建环节）当前默认将node_modules下的依赖用CommonJS规范的require()加载，但Swiper v7+是纯ESM包，不支持CommonJS加载方式。你可以按照以下优先级调整配置：

1. 调整构建转译配置 #

你需要将Swiper相关包加入你的转译白名单，避免构建工具直接用CommonJS加载它：

• 如果你使用Webpack构建：在webpack配置的module.rules中，修改处理js/ts的babel-loader规则，将exclude中的node_modules调整为排除除swiper外的所有包，示例配置：

module: {
  rules: [
    {
      test: /\.(js|ts|jsx|tsx)$/,
      exclude: /node_modules\/(?!(swiper|ssr-window|dom7)\/)/,
      use: ['babel-loader']
    }
  ]
}

注：ssr-window和dom7是Swiper的依赖，同样为纯ESM包，需要一起加入转译白名单

• 如果你使用Babel单独配置：在babel.config.json或.babelrc中添加对以上三个包的转译规则即可。

2. 调整TypeScript配置（如使用TS） #

修改tsconfig.json中的模块相关配置，适配ESM导入：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler", // 旧版TS可配置为NodeNext
    "allowSyntheticDefaultImports": true
  }
}

3. SSR场景额外配置 #

如果你的项目是服务端渲染架构，还需要做以下任一配置：

• 方案A：将Swiper组件改为客户端动态导入，避免服务端加载该ESM包：

// Slideshow.tsx
import { lazy, Suspense, useState, useEffect } from 'react';
const Swiper = lazy(() => import('swiper/react/swiper-react').then(mod => ({ default: mod.Swiper })));
const SwiperSlide = lazy(() => import('swiper/react/swiper-react').then(mod => ({ default: mod.SwiperSlide })));

// 渲染时用Suspense包裹，且仅在客户端渲染
function Slideshow() {
  const [isClient, setIsClient] = useState(false);
  const [modules, setModules] = useState([]);
  
  useEffect(() => {
    setIsClient(true);
    import('swiper').then(mod => {
      setModules([mod.Autoplay, mod.EffectFade, mod.Pagination])
    })
  }, []);
  
  return isClient && modules.length ? (
    <Suspense fallback={<div>加载中</div>}>
      <Swiper modules={modules}>
        {/* 轮播内容 */}
      </Swiper>
    </Suspense>
  ) : null;
}

• 方案B：在服务端构建配置中，将swiper、ssr-window、dom7标记为外部ESM依赖，启用服务端ESM导入支持。

4. 低版本Webpack兼容方案 #

如果你使用Webpack 4（不支持package.json的exports字段），可以配置别名直接指向Swiper的对应文件：

resolve: {
  alias: {
    'swiper/react': 'swiper/react/swiper-react.js',
    'swiper': 'swiper/swiper.esm.js'
  }
}

注意：不要手动修改node_modules下swiper包的package.json配置，该修改会在重装依赖后失效，不推荐使用。

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