Popper.js项目中React 17与Floating UI的兼容性问题解析

问题背景

在React生态系统中，JSX运行时模块的导入方式在不同版本间存在差异。当开发者将Floating UI从0.26.25升级到0.27.5版本时，在React 17环境下遇到了模块解析问题。这个问题特别出现在使用Vite和Vitest构建工具链的项目中，测试运行时抛出"找不到react/jsx-runtime模块"的错误。

技术细节分析

问题的核心在于React 17和React 18/19对JSX运行时模块的导入路径处理方式不同：

1. React 17：使用react/jsx-runtime作为导入路径
2. React 18/19：使用react/jsx-runtime.js作为导入路径

Floating UI 0.27.5版本构建的模块系统(.mjs文件)默认采用了React 18/19的导入方式，这导致在React 17环境中无法正确解析模块路径。

解决方案

针对不同的构建工具，有以下几种解决方案：

1. Vitest解决方案

在Vitest配置中添加以下内容：

test: {
  deps: {
    inline: [/@floating-ui/],
  },
}

这个配置告诉Vitest将Floating UI相关依赖内联处理，避免模块解析问题。

2. Webpack解决方案

对于使用Webpack的项目，可以通过别名(alias)配置解决：

resolve: {
  alias: {
    "react/jsx-dev-runtime": "react/jsx-dev-runtime.js",
    "react/jsx-runtime": "react/jsx-runtime.js"
  }
}

3. 升级React版本

长期来看，将项目升级到React 18或19版本是最彻底的解决方案，因为这些版本已经统一了JSX运行时的导入路径规范。

兼容性考虑

对于大型项目或需要保持稳定性的项目，直接升级React主版本可能不可行。在这种情况下，采用构建工具配置的解决方案更为合适。这些方案不会影响生产环境的运行，只解决开发和测试阶段的模块解析问题。

总结

这类问题在JavaScript生态系统中并不罕见，特别是在不同版本的库之间存在导入规范差异时。理解模块解析机制和构建工具的配置选项，能够帮助开发者快速定位和解决类似问题。对于使用React 17和Floating UI的项目，上述解决方案提供了灵活的选择，既保证了项目的稳定性，又能够利用新版本库的特性。