react-native-best-practices
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseReact Native Best Practices
React Native 性能优化最佳实践
Overview
概述
Performance optimization guide for React Native applications, covering JavaScript/React, Native (iOS/Android), and bundling optimizations. Based on Callstack's "Ultimate Guide to React Native Optimization".
React Native应用性能优化指南，涵盖JavaScript/React、原生（iOS/Android）和打包优化。基于Callstack的《React Native优化终极指南》。
Skill Format
技能格式
Each reference file follows a hybrid format for fast lookup and deep understanding:
- Quick Pattern: Incorrect/Correct code snippets for immediate pattern matching
- Quick Command: Shell commands for process/measurement skills
- Quick Config: Configuration snippets for setup-focused skills
- Quick Reference: Summary tables for conceptual skills
- Deep Dive: Full context with When to Use, Prerequisites, Step-by-Step, Common Pitfalls
Impact ratings: CRITICAL (fix immediately), HIGH (significant improvement), MEDIUM (worthwhile optimization)
每个参考文件采用混合格式，便于快速查找和深入理解：
- 快速模式：错误/正确代码片段，用于即时匹配模式
- 快速命令：用于流程/测量技能的Shell命令
- 快速配置：用于设置类技能的配置片段
- 快速参考：用于概念类技能的汇总表格
- 深入解析：包含适用场景、前提条件、分步指南、常见陷阱的完整内容
影响等级：CRITICAL（立即修复）、HIGH（显著提升）、MEDIUM（值得优化）
When to Apply
适用场景
Reference these guidelines when:
- Debugging slow/janky UI or animations
- Investigating memory leaks (JS or native)
- Optimizing app startup time (TTI)
- Reducing bundle or app size
- Writing native modules (Turbo Modules)
- Profiling React Native performance
- Reviewing React Native code for performance
在以下场景中参考本指南：
- 调试缓慢/卡顿的UI或动画
- 排查内存泄漏问题（JS或原生）
- 优化应用启动时间（TTI）
- 减小包或应用体积
- 编写原生模块（Turbo Modules）
- 分析React Native性能
- 评审React Native代码的性能
Priority-Ordered Guidelines
优先级排序的优化指南
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | FPS & Re-renders | CRITICAL | |
| 2 | Bundle Size | CRITICAL | |
| 3 | TTI Optimization | HIGH | |
| 4 | Native Performance | HIGH | |
| 5 | Memory Management | MEDIUM-HIGH | |
| 6 | Animations | MEDIUM | |
| 优先级 | 分类 | 影响等级 | 前缀 |
|---|---|---|---|
| 1 | FPS与重渲染 | CRITICAL | |
| 2 | 包体积 | CRITICAL | |
| 3 | TTI优化 | HIGH | |
| 4 | 原生性能 | HIGH | |
| 5 | 内存管理 | MEDIUM-HIGH | |
| 6 | 动画 | MEDIUM | |
Quick Reference
快速参考
Critical: FPS & Re-renders
关键：FPS与重渲染
Profile first:
bash
undefined先分析性能：
bash
undefinedOpen React Native DevTools
打开React Native DevTools
Press 'j' in Metro, or shake device → "Open DevTools"
在Metro中按'j'，或摇晃设备 → "Open DevTools"
**Common fixes:**
- Replace ScrollView with FlatList/FlashList for lists
- Use React Compiler for automatic memoization
- Use atomic state (Jotai/Zustand) to reduce re-renders
- Use `useDeferredValue` for expensive computations
**常见修复方案：**
- 用FlatList/FlashList替代ScrollView实现列表
- 使用React Compiler自动进行记忆化处理
- 使用原子状态（Jotai/Zustand）减少重渲染
- 用`useDeferredValue`处理昂贵的计算Critical: Bundle Size
关键：包体积
Analyze bundle:
bash
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-checksCommon fixes:
- Avoid barrel imports (import directly from source)
- Remove unnecessary Intl polyfills (Hermes has native support)
- Enable tree shaking (Expo SDK 52+ or Re.Pack)
- Enable R8 for Android native code shrinking
分析包内容：
bash
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常见修复方案：
- 避免桶式导入（直接从源文件导入）
- 移除不必要的Intl polyfills（Hermes原生支持）
- 启用摇树优化（Expo SDK 52+ 或 Re.Pack）
- 为Android原生代码启用R8压缩
High: TTI Optimization
重要：TTI优化
Measure TTI:
- Use for markers
react-native-performance - Only measure cold starts (exclude warm/hot/prewarm)
Common fixes:
- Disable JS bundle compression on Android (enables Hermes mmap)
- Use native navigation (react-native-screens)
- Preload commonly-used expensive screens before navigating to them
测量TTI：
- 使用添加标记
react-native-performance - 仅测量冷启动（排除暖启动/热启动/预启动）
常见修复方案：
- 在Android上禁用JS包压缩（启用Hermes内存映射）
- 使用原生导航（react-native-screens）
- 在导航前预加载常用的复杂页面
High: Native Performance
重要：原生性能
Profile native:
- iOS: Xcode Instruments → Time Profiler
- Android: Android Studio → CPU Profiler
Common fixes:
- Use background threads for heavy native work
- Prefer async over sync Turbo Module methods
- Use C++ for cross-platform performance-critical code
分析原生性能：
- iOS：Xcode Instruments → Time Profiler
- Android：Android Studio → CPU Profiler
常见修复方案：
- 用后台线程处理繁重的原生任务
- 优先选择异步而非同步的Turbo Module方法
- 用C++编写跨平台的性能关键代码
References
参考资料
Full documentation with code examples in [references/][references]:
包含代码示例的完整文档见 [references/][references]：
JavaScript/React (js-*
)
js-*JavaScript/React (js-*
)
js-*| File | Impact | Description |
|---|---|---|
| [js-lists-flatlist-flashlist.md][js-lists-flatlist-flashlist] | CRITICAL | Replace ScrollView with virtualized lists |
| [js-profile-react.md][js-profile-react] | MEDIUM | React DevTools profiling |
| [js-measure-fps.md][js-measure-fps] | HIGH | FPS monitoring and measurement |
| [js-memory-leaks.md][js-memory-leaks] | MEDIUM | JS memory leak hunting |
| [js-atomic-state.md][js-atomic-state] | HIGH | Jotai/Zustand patterns |
| [js-concurrent-react.md][js-concurrent-react] | HIGH | useDeferredValue, useTransition |
| [js-react-compiler.md][js-react-compiler] | HIGH | Automatic memoization |
| [js-animations-reanimated.md][js-animations-reanimated] | MEDIUM | Reanimated worklets |
| [js-uncontrolled-components.md][js-uncontrolled-components] | HIGH | TextInput optimization |
| 文件 | 影响等级 | 描述 |
|---|---|---|
| [js-lists-flatlist-flashlist.md][js-lists-flatlist-flashlist] | CRITICAL | 用虚拟化列表替代ScrollView |
| [js-profile-react.md][js-profile-react] | MEDIUM | React DevTools性能分析 |
| [js-measure-fps.md][js-measure-fps] | HIGH | FPS监控与测量 |
| [js-memory-leaks.md][js-memory-leaks] | MEDIUM | JS内存泄漏排查 |
| [js-atomic-state.md][js-atomic-state] | HIGH | Jotai/Zustand使用模式 |
| [js-concurrent-react.md][js-concurrent-react] | HIGH | useDeferredValue、useTransition |
| [js-react-compiler.md][js-react-compiler] | HIGH | 自动记忆化处理 |
| [js-animations-reanimated.md][js-animations-reanimated] | MEDIUM | Reanimated工作流 |
| [js-uncontrolled-components.md][js-uncontrolled-components] | HIGH | TextInput优化 |
Native (native-*
)
native-*原生 (native-*
)
native-*| File | Impact | Description |
|---|---|---|
| [native-turbo-modules.md][native-turbo-modules] | HIGH | Building fast native modules |
| [native-sdks-over-polyfills.md][native-sdks-over-polyfills] | HIGH | Native vs JS libraries |
| [native-measure-tti.md][native-measure-tti] | HIGH | TTI measurement setup |
| [native-threading-model.md][native-threading-model] | HIGH | Turbo Module threads |
| [native-profiling.md][native-profiling] | MEDIUM | Xcode/Android Studio profiling |
| [native-platform-setup.md][native-platform-setup] | MEDIUM | iOS/Android tooling guide |
| [native-view-flattening.md][native-view-flattening] | MEDIUM | View hierarchy debugging |
| [native-memory-patterns.md][native-memory-patterns] | MEDIUM | C++/Swift/Kotlin memory |
| [native-memory-leaks.md][native-memory-leaks] | MEDIUM | Native memory leak hunting |
| [native-android-16kb-alignment.md][native-android-16kb-alignment] | CRITICAL | Third-party library alignment for Google Play |
| 文件 | 影响等级 | 描述 |
|---|---|---|
| [native-turbo-modules.md][native-turbo-modules] | HIGH | 构建高性能原生模块 |
| [native-sdks-over-polyfills.md][native-sdks-over-polyfills] | HIGH | 原生库与JS库的选择 |
| [native-measure-tti.md][native-measure-tti] | HIGH | TTI测量设置 |
| [native-threading-model.md][native-threading-model] | HIGH | Turbo Module线程模型 |
| [native-profiling.md][native-profiling] | MEDIUM | Xcode/Android Studio性能分析 |
| [native-platform-setup.md][native-platform-setup] | MEDIUM | iOS/Android工具指南 |
| [native-view-flattening.md][native-view-flattening] | MEDIUM | 视图层级调试 |
| [native-memory-patterns.md][native-memory-patterns] | MEDIUM | C++/Swift/Kotlin内存管理 |
| [native-memory-leaks.md][native-memory-leaks] | MEDIUM | 原生内存泄漏排查 |
| [native-android-16kb-alignment.md][native-android-16kb-alignment] | CRITICAL | 适配Google Play的第三方库16KB对齐要求 |
Bundling (bundle-*
)
bundle-*打包 (bundle-*
)
bundle-*| File | Impact | Description |
|---|---|---|
| [bundle-barrel-exports.md][bundle-barrel-exports] | CRITICAL | Avoid barrel imports |
| [bundle-analyze-js.md][bundle-analyze-js] | CRITICAL | JS bundle visualization |
| [bundle-tree-shaking.md][bundle-tree-shaking] | HIGH | Dead code elimination |
| [bundle-analyze-app.md][bundle-analyze-app] | HIGH | App size analysis |
| [bundle-r8-android.md][bundle-r8-android] | HIGH | Android code shrinking |
| [bundle-hermes-mmap.md][bundle-hermes-mmap] | HIGH | Disable bundle compression |
| [bundle-native-assets.md][bundle-native-assets] | HIGH | Asset catalog setup |
| [bundle-library-size.md][bundle-library-size] | MEDIUM | Evaluate dependencies |
| [bundle-code-splitting.md][bundle-code-splitting] | MEDIUM | Re.Pack code splitting |
| 文件 | 影响等级 | 描述 |
|---|---|---|
| [bundle-barrel-exports.md][bundle-barrel-exports] | CRITICAL | 避免桶式导出 |
| [bundle-analyze-js.md][bundle-analyze-js] | CRITICAL | JS包可视化分析 |
| [bundle-tree-shaking.md][bundle-tree-shaking] | HIGH | 无用代码消除 |
| [bundle-analyze-app.md][bundle-analyze-app] | HIGH | 应用体积分析 |
| [bundle-r8-android.md][bundle-r8-android] | HIGH | Android代码压缩 |
| [bundle-hermes-mmap.md][bundle-hermes-mmap] | HIGH | 禁用包压缩 |
| [bundle-native-assets.md][bundle-native-assets] | HIGH | 资源目录设置 |
| [bundle-library-size.md][bundle-library-size] | MEDIUM | 依赖库体积评估 |
| [bundle-code-splitting.md][bundle-code-splitting] | MEDIUM | Re.Pack代码拆分 |
Searching References
查找参考资料
bash
undefinedbash
undefinedFind patterns by keyword
按关键词查找相关模式
grep -l "reanimated" references/
grep -l "flatlist" references/
grep -l "memory" references/
grep -l "profil" references/
grep -l "tti" references/
grep -l "bundle" references/
undefinedgrep -l "reanimated" references/
grep -l "flatlist" references/
grep -l "memory" references/
grep -l "profil" references/
grep -l "tti" references/
grep -l "bundle" references/
undefinedProblem → Skill Mapping
问题→技能映射
| Problem | Start With |
|---|---|
| App feels slow/janky | js-measure-fps.md → js-profile-react.md |
| Too many re-renders | js-profile-react.md → js-react-compiler.md |
| Slow startup (TTI) | native-measure-tti.md → bundle-analyze-js.md |
| Large app size | bundle-analyze-app.md → bundle-r8-android.md |
| Memory growing | js-memory-leaks.md or native-memory-leaks.md |
| Animation drops frames | js-animations-reanimated.md |
| List scroll jank | js-lists-flatlist-flashlist.md |
| TextInput lag | js-uncontrolled-components.md |
| Native module slow | native-turbo-modules.md → native-threading-model.md |
| Native library alignment issue | native-android-16kb-alignment.md |
| 问题 | 从以下开始排查 |
|---|---|
| 应用感觉缓慢/卡顿 | 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-lists-flatlist-flashlist.md |
| TextInput响应延迟 | js-uncontrolled-components.md |
| 原生模块缓慢 | native-turbo-modules.md → native-threading-model.md |
| 原生库对齐问题 | native-android-16kb-alignment.md |
Attribution
致谢
Based on "The Ultimate Guide to React Native Optimization" by Callstack.
基于Callstack的《The Ultimate Guide to React Native Optimization》改编。