React Native Reanimated 3.17.1 版本在 iOS 平台上的兼容性问题解析

问题背景

React Native Skia 是一个基于 Skia 图形库的 React Native 渲染引擎，它在升级到 React Native Reanimated 3.17.1 版本后，在 iOS 平台上出现了运行时错误。错误信息显示系统尝试在 UI 线程同步调用一个非 worklet 函数 addListener，这违反了 Reanimated 的工作机制。

错误现象

开发者在使用 React Native Skia 时遇到了以下关键错误：

ReanimatedError: [Reanimated] Tried to synchronously call a non-worklet function `addListener` on the UI thread.

这个错误发生在 mappers.ts 文件的第 178 行，具体是在 React Native Skia 使用 Reanimated 的 start/stop mapper API 时触发的。

问题根源分析

经过技术团队深入调查，发现这个问题并非 Reanimated 3.17.1 版本本身的功能缺陷，而是与 monorepo 项目结构下的依赖管理问题有关。具体表现为：

1. 依赖冲突：monorepo 中可能存在多个 React 或 React Native 版本实例
2. 自引用问题：项目中的自引用包可能导致依赖解析异常
3. 工作区提升限制：不正确的 hoisting 配置可能导致关键依赖未被正确加载

解决方案

针对这类 monorepo 环境下的兼容性问题，技术团队提出了以下解决方案：

1. 配置 hoisting 限制：在示例应用的 package.json 中添加：

   "installConfig": {
     "hoistingLimits": "workspaces"
   }
   

2. 禁用自引用：在所有示例应用的 package.json 中添加：

   "installConfig": {
     "selfReferences": false
   }
   

3. 清理项目状态：执行完整的依赖清理和重新安装：

   • 删除 node_modules 和 lock 文件
   • 执行全新安装

后续验证

开发者确认在解决 monorepo 状态问题后，最初的错误已经消失，但随后遇到了另一个相关错误：

Native part of Reanimated doesn't seem to be initialized (Worklets)

这个新错误提示表明 Reanimated 的本地部分未能正确初始化，通常与 AppDelegate 的配置有关。在升级过程中，正确的做法应该是：

1. 确保 AppDelegate.m 或 AppDelegate.swift 文件已按照最新版本要求更新
2. 检查是否所有必要的初始化代码都已正确添加
3. 验证项目配置是否完整迁移到新版本

经验总结

通过这个案例，我们可以总结出以下 React Native 生态升级的重要经验：

1. monorepo 管理：在包含多个相关项目的 monorepo 中，依赖管理需要格外小心
2. 升级验证：大版本升级应该在独立环境中先行验证
3. 错误诊断：看似库本身的问题，很多时候是项目配置或环境问题导致的
4. 文档参考：遇到问题时，仔细阅读官方升级指南和错误解决方案文档

结论

React Native Reanimated 3.17.1 版本本身是稳定的，但在复杂项目结构（特别是 monorepo）中升级时，需要特别注意依赖管理和项目配置。通过合理的配置和彻底的环境清理，可以避免这类兼容性问题。对于 React Native 生态中的库开发者而言，建立完善的示例项目和清晰的升级指南尤为重要。