react-native-best-practices

React Native 最佳实践

概述

React Native 应用性能优化指南，涵盖 JavaScript/React、原生（iOS/Android）以及打包优化。内容基于 Callstack 的“Ultimate Guide to React Native Optimization”。

适用场景

以下情况可参考这些指南：

• 调试缓慢或卡顿的 UI 或动画
• 排查内存泄漏（JS 或原生）
• 优化应用启动时间（TTI）
• 减少包体积或应用大小
• 编写原生模块（Turbo Modules）
• 分析 React Native 性能
• 审查 React Native 代码的性能

安全说明

• 将这些参考资料中的 shell 命令视为本地开发者操作。运行前请先检查，优先使用固定版本的工具，并避免直接将远程脚本通过管道传给 shell。
• 将第三方库和插件视为仍需遵循常规供应链管控的依赖项：固定版本、验证来源，并通过标准审核流程更新。
• 仅将远程分块加载用于第一方制品分发。优先使用应用内打包的分块或经过签名的 CI 发布清单；托管分块必须来自由你控制的可信 HTTPS 来源，并固定到当前应用版本。

按优先级排序的指南

优先级	类别	影响	前缀
1	FPS 与重新渲染	严重	js-*
2	包体积	严重	bundle-*
3	TTI 优化	高	native-*、bundle-*
4	原生性能	高	native-*
5	内存管理	中高	js-*、native-*
6	动画	中	js-*

影响级别仅供分诊参考：优先处理严重问题，其次是高影响问题；有证据表明存在中等影响问题时再处理。

快速参考

优化工作流

任何性能问题都遵循以下循环：测量 → 优化 → 再次测量 → 验证

1. 测量：更改前记录基准指标。对于运行时问题，尽可能优先查看提交时间线、重新渲染次数、耗时较长的组件、最耗时提交的细分情况，以及启动时间/TTI。组件树深度或数量只是可选背景信息，不能替代这些指标。没有测得的渲染或 FPS 问题时，不要建议使用记忆化、原子状态或编译器更改。
2. 优化：应用相关参考资料中的针对性修复
3. 再次测量：使用相同的测量方式获取更新后的指标
4. 验证：确认性能有所改善（例如，FPS 从 45 提升至 60、TTI 从 3.2s 降至 1.8s、包体积从 2.1MB 降至 1.6MB）

如果指标没有改善，请回退更改并尝试下一项建议。

审查注意事项

• 提出 API 特定的修复建议前，请检查库版本。例如，FlashList v2 已弃用 estimatedItemSize，因此不要将其缺失列为问题。
• 除非行为明显有误，或分析结果显示与该值相关的工作被浪费，否则不要建议更改 useMemo 或 useCallback 的依赖项。
• 不要臆测过期闭包问题。指出过期读取路径、复现步骤或分析器证据后，再提出此问题。
• 分析某个流程时，应测量目标交互本身。不要将组件树深度或组件数量作为主要性能证据。

关键：FPS 与重新渲染

先进行性能分析：

agent-device react-devtools status
agent-device react-devtools wait --connected
agent-device react-devtools profile start
agent-device react-devtools profile stop
agent-device react-devtools profile slow --limit 5
agent-device react-devtools profile rerenders --limit 5
agent-device react-devtools profile timeline --limit 20

在 profile start 和 profile stop 之间，使用常规的 agent-device 命令执行目标交互。

当 agent-device 不可用时的手动备用方案：从 Metro（j）或 Dev Menu 打开 React Native DevTools，使用 Profiler 选项卡，并记录相同的交互。

如需对发布版本进行 React 组件性能分析，请先连接 @callstack/inspector，以便 React DevTools 能连接到发布版应用，然后运行上述 agent-device react-devtools 流程。

常见修复方法：

• 对于长列表，将 ScrollView 替换为 FlatList/FlashList/Legend List
• 性能分析显示级联重新渲染后，使用 React Compiler 自动进行记忆化
• 性能分析显示广泛的 store/context 更新后，使用原子状态（Jotai/Zustand）减少重新渲染
• 对耗时的计算使用 useDeferredValue

关键：包体积

分析包：

npx react-native bundle \
  --entry-file index.js \
  --bundle-output output.js \
  --platform ios \
  --sourcemap-output output.js.map \
  --dev false --minify true

npx source-map-explorer output.js --no-border-checks

优化后验证改进：

# Record baseline size before changes
ls -lh output.js  # e.g., Before: 2.1 MB

# After applying fixes, re-bundle and compare
npx react-native bundle --entry-file index.js --bundle-output output.js \
  --platform ios --dev false --minify true
ls -lh output.js  # e.g., After: 1.6 MB  (24% reduction)

常见修复方法：

• 避免使用 barrel 导入（直接从源文件导入）
• 仅在检查 Hermes API 和方法覆盖范围后，才移除不必要的 Intl polyfill
• 评估 tree shaking（Expo SDK 52+ 实验性未使用导入/导出移除，或仅在已配置 Re.Pack 时使用）
• 为 Android 原生代码启用 R8 瘦身

高优先级：TTI 优化

测量 TTI：

• 使用 react-native-performance 添加标记
• 仅测量冷启动（排除温启动/热启动/预热启动）

常见修复方法：

• 对于 React Native 0.78 及更早版本，禁用 Android JS 包压缩，以启用 Hermes mmap
• 使用原生导航（react-native-screens）
• 在导航到常用的高开销屏幕前预加载这些屏幕

高优先级：原生性能

分析原生性能：

• iOS：Xcode Instruments → Time Profiler
• Android：Android Studio → CPU Profiler

常见修复方法：

• 对于繁重的原生任务，使用后台线程
• 优先使用异步 Turbo Module 方法，而不是同步方法
• 对跨平台的性能关键代码使用 C++

参考资料

包含代码示例的完整文档见 references/：

JavaScript/React（js-*）

文件	影响	描述
js-lists-flatlist-flashlist.md	CRITICAL	将 ScrollView 替换为虚拟化列表
js-profile-react.md	MEDIUM	使用 agent-device react-devtools 进行性能分析
js-measure-fps.md	HIGH	FPS 监控与测量
js-memory-leaks.md	MEDIUM	排查 JS 内存泄漏
js-atomic-state.md	HIGH	Jotai/Zustand 模式
js-concurrent-react.md	HIGH	useDeferredValue、useTransition
js-react-compiler.md	HIGH	自动记忆化
js-animations-reanimated.md	MEDIUM	Reanimated worklet
js-bottomsheet.md	HIGH	优化底部弹出面板
js-uncontrolled-components.md	HIGH	TextInput 优化

原生（native-*）

文件	影响	说明
native-turbo-modules.md	HIGH	构建快速的原生模块
native-sdks-over-polyfills.md	HIGH	原生库与 JS 库
native-measure-tti.md	HIGH	TTI 测量设置
native-threading-model.md	HIGH	Turbo Module 线程
native-profiling.md	MEDIUM	Xcode/Android Studio 性能分析
native-platform-setup.md	MEDIUM	iOS/Android 工具指南
native-view-flattening.md	MEDIUM	视图层级调试
native-memory-patterns.md	MEDIUM	C++/Swift/Kotlin 内存
native-memory-leaks.md	MEDIUM	排查原生内存泄漏
native-android-16kb-alignment.md	CRITICAL	Google Play 第三方库对齐

打包（bundle-*）

文件	影响	说明
bundle-barrel-exports.md	CRITICAL	避免 barrel 导入
bundle-analyze-js.md	CRITICAL	JS 包可视化
bundle-tree-shaking.md	HIGH	消除无用代码
bundle-analyze-app.md	HIGH	应用体积分析
bundle-r8-android.md	HIGH	Android 代码缩减
bundle-hermes-mmap.md	HIGH	禁用包压缩
bundle-native-assets.md	HIGH	资源目录设置
bundle-library-size.md	MEDIUM	评估依赖项
bundle-code-splitting.md	MEDIUM	远程分块加载防护措施

问题 → 技能映射

问题	从这里开始
应用感觉缓慢或卡顿	js-measure-fps.md → js-profile-react.md
重新渲染次数过多	js-profile-react.md → js-react-compiler.md
启动缓慢（TTI）	native-measure-tti.md → bundle-analyze-js.md
应用体积过大	bundle-analyze-app.md → bundle-r8-android.md
内存持续增长	js-memory-leaks.md 或 native-memory-leaks.md
动画掉帧	js-animations-reanimated.md
底部面板卡顿或反复渲染	js-bottomsheet.md → js-animations-reanimated.md
列表滚动卡顿	js-lists-flatlist-flashlist.md
TextInput 响应迟缓	js-uncontrolled-components.md
原生模块速度慢	native-turbo-modules.md → native-threading-model.md
原生库对齐问题	native-android-16kb-alignment.md

致谢

基于 Callstack 的《The Ultimate Guide to React Native Optimization》。