react-native-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Native & Expo Development Guide

React Native & Expo 开发指南

A practical guide for building production-ready React Native and Expo applications. Covers UI, animations, state, testing, performance, and deployment.

一份用于构建生产级React Native与Expo应用的实用指南，涵盖UI、动画、状态、测试、性能及部署等内容。

References

参考资料

Consult these resources as needed:

references/navigation.md — Expo Router: Stack, Tabs, NativeTabs (
```
headerLargeTitle
```
,
```
headerBackButtonDisplayMode
```
), links, modals, sheets, context menus
references/components.md — FlashList patterns,
```
expo-image
```
, safe areas (
```
contentInsetAdjustmentBehavior
```
), native controls, blur/glass effects, storage
references/styling.md — StyleSheet, NativeWind/Tailwind, platform styles, theming, dark mode
references/animations.md — Reanimated 3: entering/exiting, shared values, gestures, scroll-driven
references/state-management.md — Zustand (selectors, persist), Jotai (atoms, derived), React Query, Context
references/forms.md — React Hook Form + Zod: validation, multi-step, dynamic arrays
references/networking.md — fetch wrapper, React Query (optimistic updates), auth tokens, offline, API routes, webhooks
references/performance.md — Profiling workflow, FlashList +
```
memo
```
, bundle analysis, TTI, memory leaks, animation perf
references/testing.md — Jest, React Native Testing Library, E2E with Maestro
references/native-capabilities.md — Camera, location, permissions (
```
use*Permissions
```
hooks), haptics, notifications, biometrics
references/engineering.md — Project layout (
```
components/ui/
```
,
```
stores/
```
,
```
services/
```
), path aliases, SDK upgrades, EAS build/submit, CI/CD, DOM components

按需查阅以下资源：

references/navigation.md — Expo Router：Stack、Tabs、NativeTabs（
```
headerLargeTitle
```
、
```
headerBackButtonDisplayMode
```
）、链接、模态框、底部弹窗、上下文菜单
references/components.md — FlashList模式、
```
expo-image
```
、安全区域（
```
contentInsetAdjustmentBehavior
```
）、原生控件、模糊/毛玻璃效果、存储
references/styling.md — StyleSheet、NativeWind/Tailwind、平台样式、主题、暗黑模式
references/animations.md — Reanimated 3：入场/退场动画、共享值、手势、滚动驱动动画
references/state-management.md — Zustand（选择器、持久化）、Jotai（原子、派生状态）、React Query、Context
references/forms.md — React Hook Form + Zod：验证、多步骤表单、动态数组
references/networking.md — fetch封装、React Query（乐观更新）、认证令牌、离线处理、API路由、Webhooks
references/performance.md —性能分析流程、FlashList +
```
memo
```
、包分析、TTI、内存泄漏、动画性能
references/testing.md — Jest、React Native Testing Library、Maestro端到端测试
references/native-capabilities.md — 相机、定位、权限（
```
use*Permissions
```
钩子）、触觉反馈、通知、生物识别
references/engineering.md — 项目布局（
```
components/ui/
```
、
```
stores/
```
、
```
services/
```
）、路径别名、SDK升级、EAS构建/提交、CI/CD、DOM组件

Quick Reference

快速参考

Component Preferences

组件偏好

Purpose	Use	Instead of
Lists	`FlashList` ( `@shopify/flash-list` ) + `memo` items	`FlatList` (no view recycling)
Images	`expo-image`	RN `<Image>` (no cache, no WebP)
Press	`Pressable`	`TouchableOpacity` (legacy)
Audio	`expo-audio`	`expo-av` (deprecated)
Video	`expo-video`	`expo-av` (deprecated)
Animations	Reanimated 3	RN Animated API (limited)
Gestures	Gesture Handler	PanResponder (legacy)
Platform check	`process.env.EXPO_OS`	`Platform.OS`
Context	`React.use()`	`React.useContext()` (React 18)
Safe area scroll	`contentInsetAdjustmentBehavior="automatic"`	`<SafeAreaView>`
SF Symbols	`expo-image` with `source="sf:name"`	`expo-symbols`

用途	推荐使用	替代方案
列表	`FlashList` （ `@shopify/flash-list` ） + `memo` 包裹子项	`FlatList` （无视图复用）
图片	`expo-image`	RN `<Image>` （无缓存、不支持WebP）
点击交互	`Pressable`	`TouchableOpacity` （旧版）
音频	`expo-audio`	`expo-av` （已废弃）
视频	`expo-video`	`expo-av` （已废弃）
动画	Reanimated 3	RN Animated API（功能有限）
手势	Gesture Handler	PanResponder（旧版）
平台检测	`process.env.EXPO_OS`	`Platform.OS`
Context	`React.use()`	`React.useContext()` （React 18）
安全区域滚动	`contentInsetAdjustmentBehavior="automatic"`	`<SafeAreaView>`
SF Symbols	使用 `expo-image` 并设置 `source="sf:name"`	`expo-symbols`

Scaling Up

规模扩展建议

Situation	Consider
Long lists with scroll jank	Virtualized list libraries (e.g. FlashList)
Want Tailwind-style classes	NativeWind v4
High-frequency storage reads	Sync-based storage (e.g. MMKV)
New project with Expo	Expo Router over bare React Navigation

场景	考虑方案
长列表滚动卡顿	虚拟化列表库（如FlashList）
想要Tailwind风格的类名	NativeWind v4
高频存储读取	同步存储（如MMKV）
新Expo项目	使用Expo Router而非原生React Navigation

State Management

状态管理

State Type	Solution
Local UI state	`useState` / `useReducer`
Shared app state	Zustand or Jotai
Server / async data	React Query
Form state	React Hook Form + Zod

状态类型	解决方案
本地UI状态	`useState` / `useReducer`
全局共享状态	Zustand或Jotai
服务端/异步数据	React Query
表单状态	React Hook Form + Zod

Performance Priorities

性能优化优先级

Priority	Issue	Fix
CRITICAL	Long list jank	`FlashList` + memoized items
CRITICAL	Large bundle	Avoid barrel imports, enable R8
HIGH	Too many re-renders	Zustand selectors, React Compiler
HIGH	Slow startup	Disable bundle compression, native nav
MEDIUM	Animation drops	Only animate `transform` / `opacity`

优先级	问题	修复方案
关键	长列表滚动卡顿	`FlashList` + 记忆化子项
关键	包体积过大	避免桶导入、启用R8
高	重渲染过多	Zustand选择器、React Compiler
高	启动缓慢	禁用包压缩、使用原生导航
中	动画掉帧	仅对 `transform` / `opacity` 属性做动画

New Project Init

新项目初始化

bash

undefined

bash

undefined

1. Create project

npx create-expo-app@latest my-app --template blank-typescript cd my-app

2. Install Expo Router + core deps

npx expo install expo-router react-native-safe-area-context react-native-screens

3. (Optional) Common extras

npx expo install expo-image react-native-reanimated react-native-gesture-handler


Then configure:

1. Set entry point in `package.json`: `"main": "expo-router/entry"`
2. Add scheme in `app.json`: `"scheme": "my-app"`
3. Delete `App.tsx` and `index.ts`
4. Create `app/_layout.tsx` as root Stack layout
5. Create `app/(tabs)/_layout.tsx` for tab navigation
6. Create route files in `app/(tabs)/` (see [navigation.md](references/navigation.md))

For web support, also install: `npx expo install react-native-web react-dom @expo/metro-runtime`

npx expo install expo-image react-native-reanimated react-native-gesture-handler


然后进行配置：

1. 在`package.json`中设置入口文件：`"main": "expo-router/entry"`
2. 在`app.json`中添加scheme：`"scheme": "my-app"`
3. 删除`App.tsx`和`index.ts`
4. 创建`app/_layout.tsx`作为根Stack布局
5. 创建`app/(tabs)/_layout.tsx`用于标签页导航
6. 在`app/(tabs)/`目录下创建路由文件（详见[navigation.md](references/navigation.md)）

如需支持Web平台，还需安装：`npx expo install react-native-web react-dom @expo/metro-runtime`

Core Principles

核心原则

Consult references before writing: when implementing navigation, lists, networking, or project setup, read the matching reference file above for patterns and pitfalls.

Try Expo Go first (

npx expo start

). Custom builds (

eas build

) only needed when using local Expo modules, Apple targets, or third-party native modules not in Expo Go.

Conditional rendering: use

{count > 0 && <Text />}

not

{count && <Text />}

(renders "0").

Animation rule: only animate

transform

and

opacity

— GPU-composited, no layout thrash.

Imports: always import directly from source, not barrel files — avoids bundle bloat.

Lists and images: before using

FlatList

or RN

Image

, check the Component Preferences table above —

FlashList

and

expo-image

are almost always the right choice.

Route files: always use kebab-case, never co-locate components/types/utils in

app/

编写代码前先查阅参考资料：在实现导航、列表、网络或项目搭建时，先阅读上述对应的参考文档，了解最佳实践和常见陷阱。

优先使用Expo Go（

npx expo start

）。仅当使用本地Expo模块、Apple目标平台或Expo Go不支持的第三方原生模块时，才需要自定义构建（

eas build

）。

条件渲染：使用

{count > 0 && <Text />}

而非

{count && <Text />}

（后者会渲染"0"）。

动画规则：仅对

transform

和

opacity

属性做动画——这些属性由GPU合成，不会导致布局抖动。

导入规则：始终直接从源文件导入，而非从桶文件导入——避免包体积膨胀。

列表与图片：在使用

FlatList

或RN

Image

前，先查看上方的组件偏好表——

FlashList

和

expo-image

几乎总是更好的选择。

路由文件：始终使用短横线命名法（kebab-case），不要在

app/

目录下存放组件/类型/工具类文件。

Checklist

检查清单

New Project Setup

新项目搭建

```
tsconfig.json
```
path aliases configured
```
EXPO_PUBLIC_API_URL
```
env var set per environment
Root layout has
```
GestureHandlerRootView
```
(if using gestures)

contentInsetAdjustmentBehavior="automatic"

on all scroll views

```
FlashList
```
instead of
```
FlatList
```
for lists > 20 items

配置
```
tsconfig.json
```
中的路径别名
为不同环境设置
```
EXPO_PUBLIC_API_URL
```
环境变量
根布局中包含
```
GestureHandlerRootView
```
（如果使用手势）

所有滚动视图设置

contentInsetAdjustmentBehavior="automatic"

对于超过20项的列表，使用
```
FlashList
```
替代
```
FlatList
```

Before Shipping

发布前检查

Profile in
```
--profile
```
mode, fix frames > 16ms
Bundle analyzed (
```
source-map-explorer
```
), no barrel imports
R8 enabled for Android
Unit + component tests for critical paths
E2E flows for login, core feature, checkout

Flutter development → see

flutter-dev

skill. iOS native (UIKit/SwiftUI) → see

ios-application-dev

skill. Android native (Kotlin/Compose) → see

android-native-dev

skill.

React Native is a trademark of Meta Platforms, Inc. Expo is a trademark of 650 Industries, Inc. All other product names are trademarks of their respective owners.

使用
```
--profile
```
模式进行性能分析，修复帧耗时超过16ms的问题
分析包体积（
```
source-map-explorer
```
），移除桶导入
为Android启用R8
为关键路径编写单元测试和组件测试
为登录、核心功能、结账流程编写端到端测试

Flutter开发 → 查看

flutter-dev

技能文档。 iOS原生（UIKit/SwiftUI）→ 查看

ios-application-dev

技能文档。 Android原生（Kotlin/Compose）→ 查看

android-native-dev

技能文档。

React Native是Meta Platforms, Inc.的商标。Expo是650 Industries, Inc.的商标。所有其他产品名称均为其各自所有者的商标。