Supabase-js 在 React Native/Expo 中的 WebSocket 兼容性问题解析

问题背景

Supabase-js 是一个流行的 JavaScript 客户端库，用于与 Supabase 后端服务交互。近期，许多使用 React Native 和 Expo 的开发者报告了一个令人困扰的问题：即使没有使用 Supabase 的实时功能，项目构建时仍然会出现与 WebSocket 相关的模块解析错误。

核心问题表现

开发者在使用 Supabase-js 时遇到两种典型错误：

1. 无法解析 stream 模块的错误，该模块是 ws 包的依赖项
2. 即使配置了忽略 ws 模块，仍然会出现 RealtimeClient 对 ws 的依赖错误

值得注意的是，这些问题出现在开发者仅使用基本的 CRUD 和认证功能时，完全没有涉及任何实时功能。

技术根源分析

这个问题源于几个深层次的技术因素：

1. 模块解析机制变更：React Native 0.79 版本中，Metro 打包工具默认启用了对 package.json 中 exports 字段的支持。这一变更影响了模块解析方式。

2. 依赖树问题：Supabase-js 的依赖结构中，即使不使用实时功能，某些底层依赖仍然会引入对 WebSocket 相关模块的需求。

3. React Native 环境限制：React Native 环境本身并不完全支持 Node.js 的核心模块（如 stream），而这些模块是 WebSocket 实现的基础。

解决方案

开发者可以采用以下几种方法解决此问题：

1. 版本降级方案

使用经过验证可工作的特定版本：

npm install @supabase/supabase-js@2.49.6

2. Metro 配置调整

修改 metro.config.js 文件，禁用 package.json 的 exports 字段解析：

const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);
config.resolver.unstable_enablePackageExports = false;

module.exports = config;

3. 使用最新修复版本

Supabase 团队在 v2.49.9 版本中提供了官方修复方案：

npm install @supabase/supabase-js@latest

最佳实践建议

1. 版本选择：对于生产环境，建议使用经过充分测试的稳定版本而非 next 版本。

2. 依赖审查：定期检查项目依赖关系，了解各依赖项的用途和必要性。

3. 环境隔离：考虑将 Supabase 客户端相关代码封装在特定模块中，便于统一管理和问题排查。

4. 长期维护：关注 Supabase 官方更新日志，及时获取关于兼容性改进的信息。

技术深度解析

这个问题实际上反映了现代 JavaScript 生态系统中几个关键挑战：

1. 模块系统的复杂性：随着 ESM 和 CJS 模块系统的并存，加上各种打包工具的不同实现，模块解析变得异常复杂。

2. 环境差异处理：同一套代码需要在浏览器、Node.js 和 React Native 等不同环境中运行，对库开发者提出了更高要求。

3. 依赖管理：深层依赖树中的一个小问题可能引发连锁反应，影响整个应用。

Supabase 团队通过版本迭代解决了这个问题，体现了开源社区响应问题和修复问题的典型流程。对于开发者而言，理解这些底层机制有助于更快地诊断和解决类似问题。