React-Toastify 项目中混合使用 CJS 和 ESM 导入的兼容性问题分析

问题背景

在 React-Toastify 项目中，当开发者同时使用 CommonJS (CJS) 和 ES Module (ESM) 两种模块系统导入库时，可能会遇到一个特殊的兼容性问题。具体表现为：在最终的打包结果中，库会被重复包含两次，导致 Toast 功能无法正常工作。

问题现象

当项目中同时存在以下两种导入方式时：

// ESM 导入方式
import { toast } from "react-toastify";

// CJS 导入方式
const { toast } = require("react-toastify");

打包工具（如 Webpack 或 esbuild）可能会将 react-toastify 库的两个不同版本包含在最终包中。这会导致 Toast 功能只能在一个模块系统中正常工作，而另一个模块系统中的调用则不会显示任何提示。

根本原因分析

经过深入研究，这个问题源于 package.json 文件中的"exports"字段与"main"/"module"字段的共存。根据 esbuild 开发者 Evan Wallace 的解释，当 package.json 同时包含这些字段时，某些打包工具会错误地将同一个库的不同模块系统版本视为两个独立的依赖。

技术影响

这种重复包含会导致以下问题：

1. 增加最终打包体积
2. 可能导致内存中维护两个独立的 Toast 实例
3. 破坏 Toast 功能的统一管理
4. 在混合模块系统的项目中产生不一致的行为

解决方案与建议

长期解决方案

1. 统一使用 ESM 模块系统：这是推荐的解决方案，ESM 是现代 JavaScript 的标准模块系统，具有更好的静态分析和 tree-shaking 能力。

2. 修改库的 package.json：移除"exports"字段可以解决此问题，但这需要库作者进行权衡，因为"exports"字段提供了其他有用的功能。

临时解决方案

对于无法立即迁移到 ESM 的项目：

1. 统一使用 CJS 导入：

const { toast } = require('react-toastify');

2. 配置 ESLint 规则：防止团队成员意外使用 ESM 导入方式

{
  'no-restricted-imports': [
    'error',
    {
      name: 'react-toastify',
      message: 'Please use CommonJS importing syntax for this lib - require',
    },
  ]
}

3. Webpack 自定义插件：通过修改 node_modules 中的 package.json 临时解决问题

// 自定义 Webpack 插件示例
class DualCjsEsmWorkaroundPlugin {
  // 实现细节...
}

最佳实践建议

1. 在新项目中优先使用 ESM 模块系统
2. 对于依赖第三方库的组件库，建议统一输出 ESM 格式
3. 如果必须支持 CJS，考虑提供明确的文档说明
4. 定期检查项目中的模块系统使用情况，避免混合使用

总结

React-Toastify 项目中混合使用 CJS 和 ESM 导入方式会导致库重复包含的问题，这主要是由 package.json 配置引起的。虽然存在临时解决方案，但从长远来看，迁移到纯 ESM 模块系统是最佳选择。开发者应当根据项目实际情况选择合适的解决方案，并在团队中建立统一的模块系统使用规范。