从CRA迁移至Vite+React+TS时的第三方包构建问题求助

问题根源 #

从CRA（Webpack）迁移到Vite后，Rollup对CommonJS模块的解析规则更严格，部分第三方包的CJS导出格式不符合ES模块规范，导致yarn build时出现导出错误，而yarn dev因为用Esbuild处理依赖、兼容度更高，所以能正常运行。

可行解决方案 #

1. 配置Vite强制兼容CommonJS模块

在vite.config.js中通过optimizeDeps和rollupOptions直接解决导出解析问题，无需修改第三方包源码：

import { defineConfig } from 'vite';
import commonjs from '@rollup/plugin-commonjs';

export default defineConfig({
  optimizeDeps: {
    // 强制指定@socket.io/component-emitter使用ESM版本
    esbuildOptions: {
      plugins: [
        {
          name: 'force-esm-for-emitter',
          setup(build) {
            build.onResolve({ filter: /@socket.io\/component-emitter/ }, () => {
              return { 
                path: require.resolve('@socket.io/component-emitter/lib/esm/index.js') 
              };
            });
          }
        }
      ]
    }
  },
  build: {
    rollupOptions: {
      plugins: [
        commonjs({
          // 明确指定有问题包的导出项，帮助Rollup正确解析
          namedExports: {
            '@socket.io/component-emitter': ['Emitter'],
            'form-data': ['default', 'FormData']
          }
        })
      ]
    }
  }
});

• 注意：需要先安装依赖：yarn add -D @rollup/plugin-commonjs

2. 用patch-package做持久化补丁替代手动修改

如果配置方式无效，用patch-package将临时修改转为持久化补丁，团队成员安装依赖时自动应用：

• 安装工具：yarn add -D patch-package
• 修改package.json的scripts，添加依赖安装后的钩子：

  "scripts": {
    // ...其他脚本
    "postinstall": "patch-package"
  }
  

• 手动修改node_modules里的对应文件后，运行命令生成补丁：

  npx patch-package @socket.io/component-emitter form-data
  

• 将生成的patches文件夹提交到版本库，后续其他开发者执行yarn install时会自动应用补丁。

3. 升级或替换问题包

检查包的新版本是否修复了ESM兼容问题：

• 升级socket.io：yarn upgrade socket.io@latest
• 升级axios：yarn upgrade axios@latest
  如果升级后仍有问题，可以考虑替换为更适配ESM的替代方案：比如用ky替代axios，或直接使用浏览器原生fetch；Socket.io可考虑替换为原生WebSocket（业务场景允许的话）。

4. 统一封装导入逻辑

针对axios的form-data问题，创建全局封装文件统一处理导入，避免逐个文件修改：

// src/utils/axios.js
import axios from 'axios';
import * as FormDataModule from 'form-data';

// 全局挂载FormData，覆盖默认导入逻辑
window.FormData = FormDataModule.default || FormDataModule.FormData;

// 导出封装后的axios
export default axios;

项目中所有使用axios的地方，都导入这个封装文件即可。

优先级建议 #

优先尝试方案1（Vite配置），这是最优雅的无侵入解决方案；若无效再用方案2做持久化补丁；最后考虑方案3升级/替换包。

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