企业官网建设流程全解析

开头先聊点实际感受。这几年做 React Native，我一直被一个问题困扰：原生写的动画随便动都顺，RN 里一旋转缩放就掉帧，手指在屏幕上拖卡片总觉得慢半拍。后来把底层逻辑翻了个底朝天，才发现根子不在某个方法写得不对，而是大多数动画默认跑在 JS 线程上。直到我在一个电商项目里大规模换用 Reanimated 3 和 Gesture Handler，才真正找到 React Native 里做丝滑交互的正确姿势。

所以这篇文章我不想写成 API 文档。我想从一个踩过不少坑的开发者角度，把 Reanimated 3 的设计思路、和 Gesture Handler 的分工协作讲清楚，然后给你几段能直接抄的项目代码，最后把调试工具和常见坑一次性说透。无论你是刚接触 RN 的小白，还是被动画卡顿折磨过的老手，这篇文章应该都能帮你省下不少时间。

1. 先理清楚：React Native 动画为什么经常“卡”

1.1 罪魁祸首只有一个：JS 线程瓶颈

React Native 应用运行时，默认有两条核心线程：UI 线程（负责原生渲染）和 JS 线程（负责业务逻辑和 React 计算）。如果你用传统的 Animated API 做动画，每帧动画回调都会从 UI 线程发消息给 JS 线程，JS 线程计算完毕后，再把新的样式值通过 Bridge 发回 UI 线程。

问题就出在这个“来回传消息”的过程上。一次传递可能有几百微秒开销，但一帧只有 16.6 毫秒（60fps），如果 JS 线程同时在处理复杂的列表渲染、网络回调、Redux 状态更新，动画帧就被活活挤掉。结果就是掉帧、卡顿、跟手不及时。这就是为什么你在原生应用里随便做个拖拽都顺畅，在 RN 里却总觉得有层“果冻”的原因。

1.2 传统 Animated 的“原生驱动”为什么不通用

很多接触过 Animated API 的开发者会问：Animated 不是也有useNativeDriver: true吗？为什么我不能全用这个？

确实，在动画逼近“使用原生驱动模式”时，动画会直接跑在 UI 线程，不再经过 JS。但这个模式有很多限制：它只支持 transform、opacity 这类可序列化的属性，不支持更新 borderRadius、boxShadow 这类布局样式，也不支持动态计算依赖其它动画值的复杂动画。一旦遇到“拖动这张卡片，后方列表要跟着缩放”的场景，原生驱动根本无能为力。

所以原生驱动的本质是把动画声明“翻译”成原生代码，但它只是一个受限的翻译器，不是完整的动画引擎。真正的丝滑，需要让 JS 的灵活性跑进 UI 线程，而不是把每帧数据派人送过桥。

1.3 丝滑的本质：把计算从 JS 线程挪走

Reanimated 3 的思路非常直接：与其每帧在 JS 和 UI 之间通信，不如把动画代码本身“搬”到 UI 线程去跑。你在 JS 侧写的动画逻辑，经过 Babel 编译后变成一个 Worklet 函数，直接运行在 UI 线程的 JavaScript 运行时上。UI 线程自己就能完成计算、插值、更新样式，JS 线程根本不用参与每帧的动画计算。

这样一来，“滑动时手势每帧回调 -> 更新共享值 -> 样式立即变化”这条链路，全部发生在 UI 线程内部，延迟极低，掉帧自然大幅减少。这也是“丝滑”最核心的技术秘密。

2. Reanimated 3 的设计思路与老版本差异

2.1 Worklet：让 JS 代码“跑”在 UI 线程

我们先理解 Worklet（工作程序）。我试过用一句话给同事解释：Worklet 是一段被 Babel 插件在构建期“剪下来”并“移植”到 UI 线程的 JavaScript 函数。

具体流程是：你在 JS 代码里写useSharedValue、useAnimatedStyle、useAnimatedGestureHandler，Babel 插件会识别这些 hook 里的回调，把它们编译成字符串并通过eval在 UI 运行时中执行。这个 UI 运行时拥有一个独立的 JavaScript 上下文，和主 JS 线程不共享全局变量，但能共享 Reanimated 的“共享值”（Shared Value）。

共享值是一个实时对象，它的.value属性被改动时，会用最快的速度同步到 UI 线程和 JS 线程。在 Worklet 里修改.value，UI 线程立刻就能感知。这个过程不经过 React 组件的重新渲染，所以不会触发 JS 侧的开销。

这里有一个容易让新手绕晕的点：你在 JS 线程读取共享值，读到的是一个代理对象，修改时通过调用原生方法完成同步；而你在 Worklet 里读取共享值，读到的就是当前线程的实时数值。所以写代码时要养成习惯，动画相关逻辑尽量留在 Worklet 内，不要在 JS 线程高频读写共享值，否则又回到了“过桥”的老路。

2.2 从 v2 到 v3：API 收敛与架构简化

很多项目是从 React Native Reanimated v2 升级到 v3 的，我刚开始也觉得 v3 只是小版本改动，但用下来发现变化挺大。

Reanimated v3 最大的调整是：移除了useCode函数，把动画回调进一步收敛到useAnimatedStyle、useAnimatedReaction、useAnimatedProps等 hook 中。同时加强了与 React Native New Architecture（Fabric）的兼容性，动画直接作用于 Fabric Shadow Tree，不需要再通过旧 Bridge。

另外，Reanimated v3 的useSharedValue设计更加稳定，不再存在 v2 早期版本中偶发的“共享值在 JS 线程读取时没初始化”的问题。内置动画函数withSpring、withTiming的 API 也保持一贯风格，还新增了一些辅助函数，例如cancelAnimation、useAnimatedReaction。

如果要从源码层面去理解 v3 的变化，我觉得核心是“UI 运行时变得更加原生化”，它和 React Native 渲染器的结合从“桥接调用”变成了“直接注入”，这也是为什么在 Fabric 上 Reanimated 3 性能更好的原因。对于绝大多数项目，v2 升级到 v3 的适配成本不大，一般为数不多的useCode逻辑需要重构成 hook 组合。

2.3 Babel 插件编译流程：容易忽略的配置细节

Reanimated 3 能跑起来，Babel 插件是命门。你只需要在babel.config.js里加一行：

module.exports = { presets: ['module:@react-native/babel-preset'], plugins: [ 'react-native-reanimated/plugin', ], };

但要注意两点：

1. 这个插件必须放在plugins列表的最后一位。因为 Worklet 的提取编译发生在其它 Babel 转换之后，如果顺序乱了，插件可能拿不到正确的 AST。
2. 在 Metro 的extraNodeModules或自定义resolver里如果做了路径别名，可能干扰插件解析 Worklet，遇到问题可以先关掉别名再排查。

如果你用的是 Reanimated 3.x 需要配合 React Native 0.72 以上的版本，0.7x 的旧版建议直接升级到 3.15+，部分 3.3 以前的版本在 Fabric 上存在样式不同步的问题。

3. Gesture Handler：手势识别为什么也要“离 JS”

3.1 PanResponder 的痛点

聊完动画，再来聊聊手势。React Native 自带的PanResponder和TouchableOpacity等组件，在大多数简单点击场景下够用，但一旦要做复杂的拖拽、缩放、多指手势，你会发现它们是基于 JS 事件模拟出来的，底层其实是 Touch 事件在 JS 线程的派发。

这意味着什么？当你手指在屏幕上滑动时，原生层面先是收到触摸事件，然后通过 Bridge 发给 JS 线程，JS 计算完响应决策后再反馈给原生层。如果 JS 线程本身很忙，手势响应就会延迟，手指已经停了，卡片还在继续动，跟手性很差。而且 PanResponder 很难处理同时识别多个手势，例如“拖动卡片的同时，左屏幕还做了一个缩放”，代码复杂度会直线上升。

3.2 RNGH 与 Reanimated 3 的分工

react-native-gesture-handler（RNGH）就是为了解决手势响应问题而诞生的原生手势库。它把手势识别放到原生层完成，Gesture Handler 在原生层监听触摸事件并直接判断手势类型，判断结果再通过事件机制告诉 JS 侧。

不过这里还有一个细节：如果每个手势事件都要从原生回调到 JS 线程，仍然会有一定的延迟。所以 RNGH 官方提供了和 Reanimated 配合的 API，让手势事件直接进入 Worklet 中。你在 Reanimated 的 Worklet 里注册的Gesture.Pan().onUpdate(...)，它的事件回调在 UI 线程执行，完全避开 JS 线程。

所以你可以理解为：Gesture Handler 负责“在原生层识别手势”，Reanimated 负责“在 UI 线程消费手势事件并驱动动画”。两者结合，手势和动画的整条链路都在原生层 + UI 线程运行，这才是真正的高效协奏。

3.3 版本与 React Native 新老架构兼容性

我用的是 RNGH 2.16+ 配合 Reanimated 3.10+，在 React Native 0.74 的 Fabric + TurboModule 模式下没有任何兼容问题。如果你还在旧架构，RNGH 2.x 依然支持老 Bridge 模式。

但这里有个版本坑：RNGH 2.0 以后，手势组件的用法发生了 breaking changes，例如GestureHandlerRootView必须在根组件中包裹，否则手势可能不生效。还有，withSpring的配置项在不同 Reanimated 3 小版本里略有调整，建议锁版本用~范围，避免自动升级引入意外。

4. 实战：用 Reanimated 3 + Gesture Handler 做一个完全跟手的拖拽卡片

4.1 依赖安装与初始化配置

我先带你走一遍完整安装流程。我这里用的是 React Native 0.74 + Reanimated 3.10 + RNGH 2.18，你可以直接用：

npm install react-native-reanimated react-native-gesture-handler cd ios && pod install

然后在入口文件（通常是index.js或App.js）的第一行引入手势库：

import 'react-native-gesture-handler';

这一步很多新手会漏，如果不加，Android 真机上会出现手势不响应的诡异问题。接下来按第 2 节说的，把 Babel 插件配上，重启 Metro 缓存：

npm start -- --reset-cache

4.2 核心代码：共享值 + 手势 + 动画样式

下面这段代码我直接从一个博客示例项目里摘出来的，实现一个“手指拖到哪儿，卡片就跟到哪儿，松手回弹”的效果：

import { StyleSheet, View, Text } from 'react-native'; import { Gesture, GestureDetector } from 'react-native-gesture-handler'; import Animated, { useSharedValue, useAnimatedStyle, withSpring, runOnJS, } from 'react-native-reanimated'; function DraggableCard() { const translateX = useSharedValue(0); const translateY = useSharedValue(0); const isDragging = useSharedValue(false); const dragGesture = Gesture.Pan() .onStart(() => { isDragging.value = true; }) .onUpdate((event) => { // 直接在当前能用到的 UI 线程 Worklet 里赋值 translateX.value = event.translationX; translateY.value = event.translationY; }) .onEnd(() => { // 松手以后回到初始位置，带上一点弹性和阻尼 translateX.value = withSpring(0, { damping: 18, stiffness: 180 }); translateY.value = withSpring(0, { damping: 18, stiffness: 180 }); isDragging.value = false; }); const animatedStyle = useAnimatedStyle(() => { return { transform: [ { translateX: translateX.value }, { translateY: translateY.value }, ], }; }); return ( <GestureDetector gesture={dragGesture}> <Animated.View style={[styles.card, animatedStyle]}> <Text style={styles.text}>拖我</Text> </Animated.View> </GestureDetector> ); }

这段代码里最核心的只有三块：GestureDetector把手势对象绑定到 View 上；useSharedValue定义两个共享值；useAnimatedStyle把共享值映射为样式。每次手指移动，onUpdate在 UI 线程执行，直接修改translateX.value，渲染层同步更新，没有经过 React render 和 diff，因此延迟极低。

4.3 松手回弹：withSpring 的阻尼与刚度调参

你注意看onEnd里的withSpring(0, { damping: 18, stiffness: 180 })，这个参数我调过很多次，这里分享几个经验值。

• stiffness（刚度）控制回弹的速度，越大回弹越快。默认是 100，如果做卡片拖拽，我建议 180~220，感觉更脆更跟手。
• damping（阻尼）控制弹跳程度，越大越“无弹性”。默认是 10，回弹会有明显的颤动；调到 18~20 以上，基本只剩轻微震荡，手感偏“粘”。
• 如果只想要一个干脆的回位，不想要任何震荡，可以调成{ damping: 50, stiffness: 300 }，回位很快但不跳。

这里有一件让我抓狂过的小事：withSpring的回调函数是在动画结束后才在 UI 线程执行，如果你想通知 JS 线程“动画结束了”，必须在回调里调用runOnJS。直接在回调里 setState 是不生效的。

4.4 运行时验证：JS 线程开销对比

为了验证到底丝滑在哪里，我做了个粗暴的测试：把动画负责写在传统Animated.timing的useNativeDriver: false版本，对比现在这个 Reanimated 3 版本，在 Android 性能模式（低端机）上观察帧率。

我录下两版数据：

低端 Android 机上效果差距最明显。原因是 Reanimated 3 的动画计算完全不在 JS 线程，即使列表在加载图片、JS 线程在做数据解析，动画帧率也基本不受影响。这也是我后来敢把首页所有交互都交给它的原因。

5. 进阶：商品列表滑动删除与自动吸附

5.1 滑动卡片背后的状态机

拖拽卡片是入门，生产环境里更常见的场景是“滑动删除”，比如消息列表、购物车商品列表。你说到底，它的本质就是：横向拖拽卡片，超过阈值则删除，没超过则自动回弹。

我用 Reanimated 3 实现这个功能时，提炼出一个简单的状态机：idle -> dragging -> settling -> deleted。在 Worklet 里维护一个isDeleting共享值，当手势结束且位移大于阈值时，先让卡片动画滑出，动画结束后调用runOnJS真正执行删除。

5.2 手势回调里的 runOnJS 陷阱

当你真正动手写删除时，一定会遇到这个坑。看下面这段简化的代码：

import { runOnJS } from 'react-native-reanimated'; function SwipeableRow({ children, onDelete }) { const translateX = useSharedValue(0); const gesture = Gesture.Pan() .onUpdate((event) => { // 向左最多滑出 120 translateX.value = Math.max(-120, Math.min(0, event.translationX)); }) .onEnd((event) => { if (translateX.value < -70) { translateX.value = withTiming(-120, { duration: 180 }, () => { runOnJS(onDelete)(); }); } else { translateX.value = withSpring(0); } }); const animatedStyle = useAnimatedStyle(() => ({ transform: [{ translateX: translateX.value }], })); return ( <GestureDetector gesture={gesture}> <Animated.View style={[styles.row, animatedStyle]}> {children} </Animated.View> </GestureDetector> ); }

注意，withTiming的第三个参数是一个callback，它运行在 UI 线程的 Worklet 里。你想在动画结束后调用onDelete（这是一个 JS 函数），就必须用runOnJS(onDelete)包一层，否则会出现“Tried to synchronously call a non-worklet function”之类的报错。

另一个常见问题是：onEnd里读取的translateX.value在极快速滑动时，可能小于你阈值判断的数值，但实际用户感受到的却是“我已经滑到位了”。我建议在onEnd里用event.translationX和event.velocityX联合判断：如果速度很大，就算位移不够，也视为要删除。

5.3 列表性能：为什么用 onLayout 比 measure 稳

滑动删除的列表还要考虑一个细节：如果删除后需要调整后面项的高度，常规做法是让下一行往上移动。用measure去动态量测高度很麻烦，在 Fabric 下还偶尔会拿到错误值。

我更推荐的做法是，每一项在onLayout时把高度存到一个共享值或 React state 里。这样删除动画结束后，可以直接把列表的数据源更新，Reanimated 内置的 Layout Animations（例如LinearTransition、FadingTransition）会自动处理后面视图的平滑位移，代码量少很多。

import { LinearTransition } from 'react-native-reanimated'; <Animated.FlatList data={data} renderItem={renderItem} itemLayoutAnimation={LinearTransition} />

这个LinearTransition在列表删除、插入时会自动驱动布局变化的动画，非常丝滑。不过在大列表里要注意，如果频繁插入删除大图片项，建议只对固定高度的行用，避免触发重新布局的性能损耗。

6. 丝滑性能自查指南与常见坑

6.1 性能调优第一步：分清掉帧发生在哪条线程

遇到卡顿别盲目调参，先确定掉帧发生在哪条线程。Reanimated 3 本身跑在 UI 线程，它越快，UI 线程占用就越高。如果 JS 线程也在大量计算，旧架构里 JS 线程和 UI 线程的总时间是叠加的。所以两步走：

1. 把 JS 线程的负载降下来：检查setState是否被频繁调用，大列表是否在无谓渲染，业务代码里是不是有死循环的useEffect。
2. 再看动画本身有没有过度计算：如果useAnimatedStyle里写了太复杂的 interpolate、三角函数，每帧计算仍然会有开销。把能缓存的值预先算好，或者缩小动画范围，都是有效手段。

我用 iOS 的 Performance Monitor 和 Android 的 Flipper 一起看帧率。如果在 low-end Android 上依然能保持 55fps 以上，基本就够看。

6.2 三个让我抓狂的坑

第一个坑：Babel 插件没放最后。有一次同事升级依赖后动画失效，报错显示Reanimated was installed but the Babel plugin isn't configured properly，结果一看是双人改配置时把插件顺序弄错了。这种问题一定要先检查 babel 配置，再排查其它。

第二个坑：在 class 组件里用 Worklet 的串台问题。Reanimated 的 Worklet 在编译时对函数有一定要求，如果你在 class 方法里直接写useAnimatedStyle的回调，且回调引用了this，很容易出现 Worklet 无法捕获this导致运行时崩溃。我后来统一改用函数组件 + hooks，干净利落。

第三个坑：手势库和动画库版本不匹配。RNGH 官方文档每次发布都会标注支持的 Reanimated 版本，但很多人在安装时不看 peerDependencies，导致手势事件进不了 Worklet。解决方式是先定好 React Native 版本，再按官方文档的兼容矩阵安装，尽量用两边的最近稳定版。

6.3 建议的项目配置与调试工具组合

再分享一套我自己项目里在用的配置组合：

调试工具方面，我推荐：

• Reanimated 官方文档的 Flipper 插件：可以看到 Worklet 日志。
• React Native DevTools 性能面板：定位 JS 线程执行时间。
• 真机测试：在低端 Android 上跑动画，比模拟器有参考价值得多。

那段“打开手势库的日志”的操作也值得提一下：在GestureHandlerRootView上设置style={{ flex: 1 }}，否则手势区域可能永远只有屏幕左上角那一小块，这个错有段时间天天有人踩。

7. 我的实战体会，以及一些“非官方”经验

最后换个轻松的节奏，说些项目里总结出来的非官方经验。

一是“丝滑”不是一个人闷头调参调出来的，它需要前后端配合。后端接口返回数据拆分得细，列表渲染不卡，动画的价值才能被感知。如果首页数据加载慢了 3 秒，动画再顺也没用。

二是动画性能要提前设好护栏。我在团队里定了一个规则：凡是有滚动、拖拽、缩放交互的页面，默认使用 Reanimated 3 + Gesture Handler，其他页面可以用普通 RN 组件。简单页面用 Reanimated 3 反而有点重，因为每个 Worklet 在启动时有创建 UI 运行时的开销，但页面一多，这点开销影响就明显了。所以“该快的地方快，该稳的地方稳”。

三是和设计师沟通时，我会把“跟手”和“丝滑”拆开说。跟手是指手指移动时动画延迟低，丝滑是指动画过程本身帧率稳定、不跳变。有时候设计师想要“果冻回弹”，我把withSpring的阻尼调低就能实现；有时候想要“顺滑到位”，我会用withTiming配合适当的缓动函数。两者不是一回事，别混着调。

四是别过度依赖动画库里现成的“手势组件”。官方提供的Swipeable虽然开箱即用，但在高度定制的 UI 里反而难改，不如用GestureDetector自己搭，学习和维护成本在前期投入一点，后面收益很大。

五是注意 HMR（热更新）的问题。我经常在改完动画参数后不重启 Metro，结果界面卡得不像话，后来发现是 Reanimated 的 Worklet 在热更新场景下偶尔会残留旧代码。所以遇到动画参数改了没效果，先重启 Metro 再谈其它。

如果你刚入门，我建议先照着第 4 节的拖拽卡片做一遍，再把手势换成双指缩放、旋转，感受一下“所有计算都在 UI 线程”是什么体验。等你把runOnJS、withSpring、GestureDetector这几个 API 用熟练，React Native 交互性能这块基本上就打通了。

这个方向其实还能往下延伸很多：比如把 Reanimated 3 用在 skia 动画上、做复杂的图表拖拽交互、和 react-native-vision-camera 联动做手势变焦。我自己的计划是接下来把团队里的列表页统一迁移到 Reanimated 3 的 Layout Animations 上，到时候有新的坑和经验，再来更新分享。