Tamagui 项目中 React 版本冲突导致 useState 报错问题解析

问题背景

在 Tamagui 1.116.0 版本发布后，部分开发者报告了一个严重问题：当项目从 1.115.5 升级到 1.116.* 版本时，出现了 @tamagui/use-did-finish-ssr 模块无法解析的问题。更严重的是，当开发者手动添加该依赖后，应用启动时会抛出 TypeError: Cannot read property 'useState' of null 的错误。

问题表现

该问题主要出现在以下环境中：

• iOS 和 Android 平台上的 Expo 应用
• 使用 React 18.2.0 版本的项目
• 使用不同包管理器（包括 yarn、pnpm 和 npm）的项目

错误通常发生在 TamaguiProvider 组件初始化阶段，导致整个应用无法正常渲染。

问题根源

经过深入分析，问题源于以下几个方面：

1. 依赖解析问题：Tamagui 1.116.0 版本中，@tamagui/sheet 组件依赖的 use-did-finish-ssr 模块未能正确解析。

2. React 版本冲突：更根本的原因是 React 版本兼容性问题。当项目中使用 React 18.2.0 时，Tamagui 内部组件尝试访问 React 的 useState hook 时遇到了 null 引用错误。这表明 React 实例未能正确初始化或存在多个 React 版本冲突。

3. 包管理器行为差异：不同包管理器（yarn、pnpm、npm）对依赖解析和版本锁定的处理方式不同，加剧了问题的复杂性。

解决方案

Tamagui 团队经过多次测试和验证，最终确定了以下解决方案：

1. 升级 React 版本：将项目中的 React 和 React DOM 升级到 18.3.1 版本可以解决此问题。对于 Expo 项目，可以通过在 expo 配置中添加排除项来防止 expo-doctor 自动降级 React 版本。

2. 放宽版本限制：Tamagui 团队在后续版本中放宽了对 React 版本的严格限制，将依赖声明从特定版本改为更宽松的范围（如 >=18.0.0），甚至考虑使用 * 通配符来避免版本冲突。

3. 清理锁文件：开发者可以尝试删除项目中的锁文件（如 yarn.lock 或 package-lock.json）并重新安装依赖，这有助于解决因锁文件导致的版本不一致问题。

技术深度解析

这个问题揭示了前端生态系统中一个常见但容易被忽视的问题：依赖版本管理。当多个库对同一核心库（如 React）有不同版本要求时，包管理器会尝试找到一个满足所有要求的版本。如果版本范围定义过于严格，就可能导致兼容性问题。

在 Tamagui 的案例中，虽然库本身理论上兼容 React 18.2.0 和 18.3.1，但由于包管理器的解析行为和项目配置的复杂性，实际运行中可能出现意外行为。这提醒我们：

1. 库开发者应该尽可能放宽对核心依赖的版本限制
2. 应用开发者应该定期更新项目依赖，保持相对一致的版本
3. 当遇到类似问题时，检查是否存在多个版本的 React 实例是重要的排查步骤

最佳实践建议

基于这次问题的经验，我们建议开发者：

1. 在升级 Tamagui 或其他 UI 库时，同时检查并更新 React 和 React DOM 到较新版本
2. 使用单一包管理器并定期清理和重新生成锁文件
3. 对于 Expo 项目，合理配置 expo-doctor 的排除项以避免不必要的版本降级
4. 遇到类似问题时，使用 yarn why react 或类似命令检查项目中是否存在多个 React 版本

总结

Tamagui 项目中的这次版本冲突问题是一个典型的前端依赖管理案例。通过放宽版本限制和保持依赖更新，开发者可以避免大部分类似问题。这也反映了现代前端开发中依赖管理的重要性，以及库开发者在版本兼容性方面需要考虑的复杂因素。