react-native-worklets 特性开关Feature Flags完全指南静态与动态配置、三个内置开关与跨运行时堆栈追踪【免费下载链接】react-native-reanimatedReact Natives Animated library reimplemented项目地址: https://gitcode.com/GitHub_Trending/re/react-native-reanimated导读本文围绕react-native-worklets的 Feature Flags特性开关机制展开完整讲解其设计目标、静态与动态两类开关的定义与配置方法并逐一剖析当前库中内置的三个静态开关IOS_DYNAMIC_FRAMERATE_ENABLED、FETCH_PREVIEW_ENABLED、ENABLE_CROSS_RUNTIME_STACK_TRACES的实际作用与源码级实现。读完本文你将掌握如何在应用的package.json中通过编译期配置启用/停用实验性能力、如何通过运行时 JS API 读写动态开关以及如何在自身代码中新增一个符合规范的 feature flag。本文基于仓库中的官方文档 docs/docs-worklets/docs/guides/feature-flags.md 编写并结合react-native-worklets包的源码packages/react-native-worklets/src/featureFlags/与原生侧实现进行印证。Feature Flags 的设计目标与整体分类Feature Flags 允许开发者对实验性改动选择「主动启用」opt-in或对已经默认开启的新改动选择「主动退出」opt-out。它服务于新实现的增量发布策略在不动摇库整体稳定性的前提下把新行为逐步灰度给早期采用者收集反馈。库中把 feature flags 分为两类静态staticfeature flags在代码编译阶段解析应用运行期间无法改变。动态dynamicfeature flags在运行期间可随时修改其值在整个应用生命周期内都可能变化。在react-native-worklets中静态开关的默认值与类型定义统一维护在 packages/react-native-worklets/src/featureFlags/staticFlags.json 与 packages/react-native-worklets/src/featureFlags/types.ts 中动态开关的注册表与读写逻辑位于 packages/react-native-worklets/src/featureFlags/featureFlags.native.ts。当前可用的 Feature Flags 一览仓库文档给出了当前内置 feature flags 的总览表如下信息以 docs/docs-worklets/docs/guides/feature-flags.md 及staticFlags.json为准Feature flag 名称类型引入版本移除版本默认值IOS_DYNAMIC_FRAMERATE_ENABLED静态0.6.0–trueFETCH_PREVIEW_ENABLED静态0.8.0–falseENABLE_CROSS_RUNTIME_STACK_TRACES静态0.9.0–true在源码侧packages/react-native-worklets/src/featureFlags/staticFlags.json 中的默认值与文档一致另外还包含一个仅供内部测试使用的RUNTIME_TEST_FLAG默认false它不面向最终用户仅用于运行时测试场景{ RUNTIME_TEST_FLAG: false, FETCH_PREVIEW_ENABLED: false, IOS_DYNAMIC_FRAMERATE_ENABLED: true, ENABLE_CROSS_RUNTIME_STACK_TRACES: true }内置静态开关逐个解析IOS_DYNAMIC_FRAMERATE_ENABLED默认true自 0.6.0该开关用于改善计算密集型动画的视觉感知与平滑度。启用后系统会根据 UI 线程的当前负载自动调整帧率例如当设备在 120fps 下出现不规则掉帧时机制会自动回退到稳定的 60fps避免「看似高刷、实则跳帧」的糟糕体验。在原生实现中该开关在 iOS 的 packages/react-native-worklets/apple/worklets/apple/AnimationFrameQueue.mm 中生效初始化WorkletsDisplayLink时通过worklets::StaticFeatureFlags::getFlag(IOS_DYNAMIC_FRAMERATE_ENABLED)判断是否启用 ProMotion 适配第 40–51 行启用时若屏幕maximumFramesPerSecond 60则使用 ProMotion 帧回调否则使用标准回调。帧调度循环中还会基于最近若干帧的平均计算耗时阈值 8ms / 16ms / 33ms动态选择BEST/STANDARD/LOW/POOR四个CAFrameRateRange档位并把结果写入displayLink_.preferredFrameRateRange第 115–135 行。也就是说该机制本质上是用「负载感知的帧率分级」替代「固定 120fps 随机掉帧」。从源码结构看这是一个典型的「默认开启、允许 opt-out」的静态开关对绝大多数动画场景保持默认true即可若在特定设备/业务上遇到异常帧率行为可在package.json中将其显式置为false后重新构建原生应用。FETCH_PREVIEW_ENABLED默认false自 0.8.0该开关在Bundle Mode下启用 Worklet Runtime 上的fetchAPI 预览实现。React Native 生态中新的 JavaScript 运行时默认不具备联网能力react-native-worklets提供了一版简化的fetch但可能无法覆盖所有用例因此必须通过该静态开关显式开启详见 docs/docs-worklets/docs/bundleMode/usage.mdx 的「Running network requests in Worklets」一节。该开关仅在 Bundle Mode 下生效且启用后还需要完成 Bundle Mode 的其余设置步骤包括安装所需的 patch。原生侧的实现印证在 packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/RuntimeBindings.h 中SendRequest/AbortRequest/ClearCookies等网络绑定字段整体包裹在#ifdef WORKLETS_FETCH_PREVIEW_ENABLED条件编译块内packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/WorkletRuntimeDecorator.cpp 也在同名的条件编译块中才向 Worklet Runtime 注入 fetch 相关能力。对应的编译宏由构建脚本根据 feature flags 配置生成iOS 侧CocoaPods 辅助脚本 packages/react-native-worklets/scripts/worklets_utils.rb 中get_flag_from_feature_flags会把FETCH_PREVIEW_ENABLED转换为-DWORKLETS_FETCH_PREVIEW_ENABLED编译参数Android 侧Gradle 脚本 packages/react-native-worklets/android/build.gradle.kts 中FETCH_PREVIEW_ENABLED isFlagEnabled(featureFlags, FETCH_PREVIEW_ENABLED)决定是否启用对应宏。ENABLE_CROSS_RUNTIME_STACK_TRACES默认true自 0.9.0启用后调度 worklet 的 JavaScript 调用点通过scheduleOnUI、scheduleOnRuntime等会被捕获并附加到 worklet 上。若 worklet 随后在 worklet runtime 中抛错最终的错误堆栈会与原始的调度堆栈拼接使 LogBox 中的报错能直接指回调度它的那一行代码而不是止步于 worklet runtime 边界。这让深埋在 worklet 内部的错误更容易追溯到应用代码中的源头。两个重要约束仅在开发构建__DEV__中生效发布构建无论开关取值如何都会跳过调度堆栈的捕获以避免运行时开销。性能警示捕获额外堆栈数据会显著拖慢大量异步/调度调用的代码路径官方建议这类场景显式关闭该开关。JS 侧实现印证在 packages/react-native-worklets/src/threads.native.ts 中SHOULD_CAPTURE_SCHEDULE_STACK __DEV__ getStaticFeatureFlag(ENABLE_CROSS_RUNTIME_STACK_TRACES)第 16–17 行enqueueUI据此决定是否为每个待调度的 job 记录new Error().stack第 318–320 行随后随WorkletsModule.scheduleOnUI(..., scheduleStacks)一并传给原生侧第 361–367 行。runtimes.native.ts中的scheduleOnRuntime也遵循同样的模式。用示例理解「跨运行时堆栈拼接」假设有如下代码节选自原文档import { scheduleOnUI } from react-native-worklets; function hardToDebug(callback: () void) { worklet; callback(); } function functionThatThrows() { worklet; throw new Error(Im not!); } function functionThatDoesntThrow() { worklet; console.log(Im okay); } export default function App() { // Which invocation throws? scheduleOnUI(hardToDebug, functionThatDoesntThrow); scheduleOnUI(hardToDebug, functionThatThrows); scheduleOnUI(hardToDebug, functionThatDoesntThrow); return null; }开关开启与关闭时的 LogBox 差异下方两张对比图展示了同一段代码在开关开启/关闭时 LogBox 报出的调用栈差异。可以看到启用时调用栈中既包含[UI]:前缀的帧如[UI]: functionThatThrows、[UI]: hardToDebug也包含调度侧贡献的帧——enqueueUI与scheduleOnUI以及App等 RN runtime 侧帧能一眼定位到「是哪一次scheduleOnUI调用引发的异常」。禁用时堆栈止步于 worklet runtime 边界只剩[UI]:前缀的帧enqueueUI、scheduleOnUI、App等调度侧帧全部消失难以判断三次调度中哪一次真正抛错。静态 Feature Flags配置方式与读取 API静态 flags 旨在编译期解析运行期间不可改变。启用一个静态 feature flag 需要两步在应用根目录的package.json中追加如下配置{ // ... worklets: { staticFeatureFlags: { EXAMPLE_STATIC_FLAG: true } } }执行pod install仅 iOS 需要让 CocoaPods 重新读取配置并生成编译参数。重新构建原生应用Android 直接重新 Gradle 构建即可。前置条件警告在 Worklets 以默认配置预编译的环境中如 Expo Go、RNRepo不支持修改静态 feature flags。此时要么改用 Expo Prebuild 走 continuous native generation 流程要么RNRepo 项目将 Worklets 加入 deny list 强制从源码构建。这是因为静态开关的取值在构建期就已固化进原生二进制运行期无法覆盖。在 JavaScript 中读取静态开关使用getStaticFeatureFlag函数import { getStaticFeatureFlag } from react-native-worklets; const enabled getStaticFeatureFlag(IOS_DYNAMIC_FRAMERATE_ENABLED);从构建脚本到原生宏的完整链路静态开关的「编译期解析」体现在构建工具链中配置合并CocoaPods 侧packages/react-native-worklets/scripts/worklets_utils.rb 的get_static_feature_flags先读取src/featureFlags/staticFlags.json得到默认值再用应用package.json中的worklets.staticFeatureFlags覆盖同名键Android 侧 packages/react-native-worklets/android/build.gradle.kts 的getStaticFeatureFlags()逻辑与之完全对应。宏生成iOS 将所有开关序列化为-DWORKLETS_FEATURE_FLAGS[KEY:value]...并针对FETCH_PREVIEW_ENABLED单独生成-DWORKLETS_FETCH_PREVIEW_ENABLEDAndroid 通过WORKLETS_FEATURE_FLAGS与FETCH_PREVIEW_ENABLED两个 Gradle 变量进入 CMake 宏。原生读取packages/react-native-worklets/Common/cpp/worklets/Tools/FeatureFlags.h 中StaticFeatureFlags::getFlag在WORKLETS_FEATURE_FLAGS宏内解析[name:true]子串来返回constexpr布尔值未知开关名会抛出logic_error因此 C 侧可以在if constexpr中做编译期分支例如 AnimationFrameQueue.mm 第 40 行的用法。JS 读取packages/react-native-worklets/src/featureFlags/featureFlags.native.ts 中的getStaticFeatureFlag首次读取时通过WorkletsModule.getStaticFeatureFlag(name)从原生侧取值并缓存到staticFeatureFlags局部对象中第 59–70 行后续读取直接命中缓存。非原生平台如 Web的占位实现 packages/react-native-worklets/src/featureFlags/featureFlags.ts 一律返回false。动态 Feature Flags运行时读写动态 flags 可以在运行期任意时刻修改无需重新构建。启用/禁用一个动态开关需要调用setDynamicFeatureFlagimport { setDynamicFeatureFlag } from react-native-worklets; setDynamicFeatureFlag(EXAMPLE_DYNAMIC_FLAG, true);读取动态开关则使用getDynamicFeatureFlagimport { getDynamicFeatureFlag } from react-native-worklets; const value getDynamicFeatureFlag(EXAMPLE_DYNAMIC_FLAG);JS 侧的动态开关注册表实现在 packages/react-native-worklets/src/featureFlags/featureFlags.native.ts 中DynamicFlags对象维护「开关名 → 布尔值」的映射当前内置EXAMPLE_DYNAMIC_FLAG仅作示例用途模块加载时通过DynamicFlags.init()把全部开关同步到原生WorkletsModule.setDynamicFeatureFlagsetFlag/getFlag在开关名不存在时会通过 logger 输出一条提示「该开关已不存在可以安全地从代码中移除对应调用」而不是静默失败。getStaticFeatureFlag、setDynamicFeatureFlag、getDynamicFeatureFlag均已从 packages/react-native-worklets/src/index.ts 导出属公开 API。静态 vs 动态选型对比静态 Feature Flags动态 Feature Flags构建应用时即可确定取值✅❌应用生命周期内可改变取值❌✅改变取值需要重新构建应用✅❌可通过公开 JavaScript API 修改❌✅可通过应用package.json修改✅❌在 Expo Go / RNRepo 中可修改❌✅选择建议需要彻底移除某段编译产物如原生绑定、网络能力注入时用静态开关让不启用的代码根本不出现在二进制中需要线上热切换、AB 实验、按设备/用户灰度时用动态开关避免发版周期。给贡献者的开关规范Remarks for contributors仓库文档对新增 feature flag 的规范给出了明确要求贡献者在提交新开关前应当遵守开关只在启用时才切换到新的实验行为初始阶段默认值应为false让用户按需 opt-in实验行为稳定后将默认值改为true仍允许用户 opt-out默认开启的开关在运行一段时间后应从代码库中移除避免长期累积死配置静态与动态开关命名均使用大写下划线upper snake case例如EXAMPLE_FEATURE_FLAG开关名中不得包含FEATURE_FLAG字样本身建议为「启用/禁用某段代码」的开关显式添加ENABLE_或DISABLE_前缀提升可读性。这些规范与源码中的既有实践一致三个内置开关均以ENABLE_结尾语义化命名且在 types.ts 的类型层面对开关名做了强约束DynamicFlagName由DynamicFlagsType的键推导StaticFeatureFlagsSchema由staticFlags.json的结构约束拼错开关名在编译期即可被发现并在运行期得到 logger 的友好提示。小结Feature Flags 是react-native-worklets进行增量发布与实验能力灰度的核心机制静态开关IOS_DYNAMIC_FRAMERATE_ENABLED、FETCH_PREVIEW_ENABLED、ENABLE_CROSS_RUNTIME_STACK_TRACES通过package.json在编译期固化链路贯穿 JS 类型约束、CocoaPods/Gradle 构建脚本直至原生if constexpr条件编译动态开关通过setDynamicFeatureFlag/getDynamicFeatureFlag实现运行期热切换。理解两者的差异与内置开关的语义既能帮你按需启用或退出实验特性、精确定位跨运行时错误也能指导你在自己的库/业务中设计出规范、可演进的功能开关体系。【免费下载链接】react-native-reanimatedReact Natives Animated library reimplemented项目地址: https://gitcode.com/GitHub_Trending/re/react-native-reanimated创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考