react-native-best-practices

React Native 最佳實務

概述

React Native 應用程式的效能優化指南，涵蓋 JavaScript/React、原生端（iOS/Android）以及打包優化。基於 Callstack 的「React Native 優化終極指南」。

技能格式

每個參考檔案採用混合格式，方便快速查閱與深入理解：

• 快速模式：錯誤/正確的程式碼片段，便於立即比對
• 快速指令：用於流程或測量技能的 Shell 指令
• 快速設定：用於設定類技能的設定片段
• 快速參考：用於概念性技能的摘要表格
• 深入探討：完整上下文，包含使用時機、前置條件、逐步步驟、常見陷阱

影響評級：CRITICAL（立即修復）、HIGH（顯著改善）、MEDIUM（值得優化）

何時套用

在以下情況參考這些指南：

• 除錯緩慢或卡頓的 UI 或動畫
• 調查記憶體洩漏（JS 或原生）
• 優化應用程式啟動時間（TTI）
• 減少 Bundle 或應用程式大小
• 撰寫原生模組（Turbo Modules）
• 分析 React Native 效能
• 審查 React Native 程式碼的效能

安全注意事項

• 將這些參考中的 Shell 指令視為本機開發操作。執行前請先審查，建議使用固定版本的工具，並避免將遠端腳本直接 pipe 到 Shell。
• 將第三方函式庫與外掛視為仍需正常供應鏈控制的依賴項：固定版本、驗證來源，並透過標準審查流程更新。
• 將 Re.Pack 程式碼拆分視為僅限第一方 artifact 傳遞。遠端 chunk 必須來自您控制的受信任 HTTPS 來源，並固定至當前應用程式版本。

優先順序指南

優先級	類別	影響	前綴
1	FPS 與重新渲染	CRITICAL	js-*
2	Bundle 大小	CRITICAL	bundle-*
3	TTI 優化	HIGH	native-*, bundle-*
4	原生效能	HIGH	native-*
5	記憶體管理	MEDIUM-HIGH	js-*, native-*
6	動畫	MEDIUM	js-*

快速參考

優化工作流程

針對任何效能問題，遵循以下循環：測量 → 優化 → 重新測量 → 驗證

1. 測量：在變更前擷取基準指標。對於執行時期問題，優先使用 commit 時間軸、重新渲染次數、慢速元件、最重 commit 分解，以及啟動/TTI（若可用）。元件樹深度或數量為選用上下文，不能取代主要指標。
2. 優化：套用相關參考中的目標修復
3. 重新測量：執行相同測量以取得更新指標
4. 驗證：確認改善（例如 FPS 45→60、TTI 3.2s→1.8s、bundle 2.1MB→1.6MB）

若指標未改善，還原並嘗試下一個建議修復。

審查防護措施

• 在建議特定 API 修復前，先檢查函式庫版本。例如：FlashList v2 已棄用 estimatedItemSize，因此不要將其標記為缺失。
• 除非行為明顯錯誤，或分析顯示浪費的工作與該值相關，否則不要建議修改 useMemo 或 useCallback 的依賴項。
• 不要推測性地報告過時閉包。在指出問題前，請顯示過時讀取路徑、重現步驟或分析器證據。
• 分析流程時，請測量目標互動本身。不要將元件樹深度或元件數量當作主要效能證據。

關鍵：FPS 與重新渲染

先分析：

# 開啟 React Native DevTools
# 在 Metro 中按 'j'，或搖晃裝置 → "Open DevTools"

常見修復：

• 將 ScrollView 替換為 FlatList/FlashList 處理列表
• 使用 React Compiler 進行自動記憶化
• 使用原子狀態（Jotai/Zustand）減少重新渲染
• 使用 useDeferredValue 處理昂貴計算

關鍵：Bundle 大小

分析 Bundle：

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

優化後驗證改善：

# 記錄變更前的基準大小
ls -lh output.js  # 例如 Before: 2.1 MB

# 套用修復後，重新打包並比較
npx react-native bundle --entry-file index.js --bundle-output output.js \
  --platform ios --dev false --minify true
ls -lh output.js  # 例如 After: 1.6 MB  (減少 24%)

常見修復：

• 避免 barrel import（直接從來源匯入）
• 僅在確認 Hermes API 與方法覆蓋率後，移除不必要的 Intl polyfill
• 啟用 tree shaking（Expo SDK 52+ 或 Re.Pack）
• 啟用 R8 進行 Android 原生程式碼縮減

高：TTI 優化

測量 TTI：

• 使用 react-native-performance 設定標記
• 僅測量冷啟動（排除溫啟動/熱啟動/預啟動）

常見修復：

• 在 Android 上停用 JS Bundle 壓縮（啟用 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	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 worklets
js-bottomsheet.md	HIGH	Bottom sheet 優化
js-uncontrolled-components.md	HIGH	TextInput 優化

原生 (native-*)

檔案	影響	說明
native-turbo-modules.md	HIGH	建立快速的原生模組
native-sdks-over-polyfills.md	HIGH	原生 vs 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	View 層級除錯
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 import
bundle-analyze-js.md	CRITICAL	JS Bundle 視覺化
bundle-tree-shaking.md	HIGH	死碼消除
bundle-analyze-app.md	HIGH	應用程式大小分析
bundle-r8-android.md	HIGH	Android 程式碼縮減
bundle-hermes-mmap.md	HIGH	停用 Bundle 壓縮
bundle-native-assets.md	HIGH	Asset 目錄設定
bundle-library-size.md	MEDIUM	評估依賴項
bundle-code-splitting.md	MEDIUM	Re.Pack 程式碼拆分

搜尋參考資料

# 依關鍵字搜尋模式
grep -l "reanimated" references/
grep -l "flatlist" references/
grep -l "memory" references/
grep -l "profil" references/
grep -l "tti" references/
grep -l "bundle" references/

問題 → 技能對應

問題	從此開始
應用程式感覺緩慢/卡頓	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
Bottom sheet 卡頓/重新渲染	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 的「React Native 優化終極指南」。