Floating-UI 在浏览器环境中遇到 process 未定义问题的分析与解决方案

2025-05-04 12:53:53作者：董灵辛Dennis

问题背景

在使用 Floating-UI 这个流行的 React 定位库时，开发者可能会遇到一个常见问题：当尝试通过 SystemJS 等模块加载器在浏览器环境中直接运行 Floating-UI 时，控制台会抛出 ReferenceError: process is not defined 的错误。这个问题的根源在于 Floating-UI 的 ESM 模块中包含了 Node.js 环境特有的 process.env 引用。

技术原理分析

Floating-UI 的构建配置默认针对的是现代前端构建工具链（如 Webpack、Rollup 或 Vite）的使用场景。在这些构建工具中，process.env 通常会被特殊处理：

构建时替换：构建工具会在打包过程中将 process.env.NODE_ENV 这样的表达式直接替换为字符串常量（如 "production" 或 "development"）
代码消除：基于环境变量的条件代码会被 Dead Code Elimination（DCE）优化掉，不会出现在生产环境的包中

然而，当开发者尝试在浏览器中直接加载 ESM 格式的 Floating-UI 模块时，由于浏览器环境没有 Node.js 的 process 对象，就会导致运行时错误。

解决方案

方案一：使用构建工具

最推荐的解决方案是使用标准的前端构建工具链：

通过 npm/yarn/pnpm 安装 Floating-UI
使用 Webpack、Rollup 或 Vite 等工具构建你的应用
构建工具会自动处理 process.env 的转换和优化

方案二：浏览器环境下的变通方案

如果必须在浏览器中直接运行（如某些特殊场景或快速原型开发），可以采用以下方法：

全局变量垫片：在 HTML 的 <head> 中添加以下代码：
```
<script>
  window.process = { env: {} };
</script>
```
使用 UMD 格式：Floating-UI 也提供了 UMD 格式的构建产物，可以直接在浏览器中使用：
```
<script src="path/to/floating-ui.umd.js"></script>
```

最佳实践建议

生产环境使用构建工具：即使是小型项目，也建议使用构建工具，这不仅能解决环境变量问题，还能获得代码分割、tree-shaking 等优化优势
开发环境灵活处理：在快速原型开发时，可以使用垫片方案，但要注意这会导致所有 process.env 检查都返回 undefined，可能影响某些开发环境特有的警告信息
库开发者注意事项：如果是开发自己的库并需要兼容直接浏览器使用，可以考虑使用 esm-env 等更健壮的环境检测方案