react-native-dev

React Native 和 Expo 开发指南

构建可用于生产环境的 React Native 和 Expo 应用的实用指南。涵盖 UI、动画、状态、测试、性能和部署。

参考资料

按需查阅以下资源：

• 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 路由、Webhook
• references/performance.md — 性能分析工作流、FlashList + memo、包分析、TTI、内存泄漏、动画性能
• references/testing.md — Jest、React Native Testing Library、使用 Maestro 进行端到端测试
• references/native-capabilities.md — 相机、位置、权限（use*Permissions hooks）、触觉反馈、通知、生物识别
• references/engineering.md — 项目布局（components/ui/、stores/、services/）、路径别名、SDK 升级、EAS 构建／提交、CI/CD、DOM 组件

快速参考

组件选择建议

用途	使用	替代方案
列表	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	使用 source="sf:name" 的 expo-image	expo-symbols

扩展应用

情况	可考虑
长列表滚动卡顿	虚拟化列表库（例如 FlashList）
希望使用 Tailwind 风格的类	NativeWind v4
高频读取存储	基于同步的存储（例如 MMKV）
使用 Expo 开启新项目	选择 Expo Router，而不是裸用 React Navigation

状态管理

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

性能优先事项

优先级	问题	修复方案
CRITICAL	长列表卡顿	FlashList + 使用 memo 的列表项
CRITICAL	包体积过大	避免使用 barrel imports，启用 R8
HIGH	重渲染过多	Zustand 选择器、React Compiler
HIGH	启动缓慢	禁用包压缩、使用原生导航
MEDIUM	动画掉帧	仅对 transform/opacity 设置动画

新建项目初始化

# 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

然后进行配置：

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）

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

核心原则

编写前先查阅参考资料：实现导航、列表、网络功能或项目配置时，请先阅读上方对应的参考文件，了解相关模式和注意事项。

先尝试 Expo Go（npx expo start）。只有在使用本地 Expo 模块、Apple 平台目标或 Expo Go 不包含的第三方原生模块时，才需要自定义构建（eas build）。

条件渲染：使用 {count > 0 && <Text />}，不要使用 {count && <Text />}（会渲染出「0」）。

动画规则：仅对 transform 和 opacity 添加动画——它们由 GPU 合成，不会造成布局抖动。

导入：始终直接从源文件导入，不要从 barrel 文件导入，以避免打包体积膨胀。

列表和图像：使用 FlatList 或 RN Image 前，请查看上方的组件偏好表——FlashList 和 expo-image 几乎总是更合适的选择。

路由文件：始终使用 kebab-case，切勿在 app/ 中放置组件、类型或工具函数。

检查清单

新建项目设置

• 已配置 tsconfig.json 路径别名
• 已按环境设置 EXPO_PUBLIC_API_URL 环境变量
• 根布局包含 GestureHandlerRootView（如使用手势）
• 所有滚动视图均设置了 contentInsetAdjustmentBehavior="automatic"
• 对于超过 20 项的列表，使用 FlashList 而非 FlatList

发布前

• 在 --profile 模式下进行性能分析，修复耗时超过 16ms 的帧
• 已分析打包内容（source-map-explorer），且没有 barrel 导入
• 已为 Android 启用 R8
• 已为关键路径编写单元测试和组件测试
• 已为登录、核心功能和结账流程编写 E2E 测试

---

Flutter 开发 → 请参阅 flutter-dev 技能。 iOS 原生开发（UIKit/SwiftUI）→ 请参阅 ios-application-dev 技能。 Android 原生开发（Kotlin/Compose）→ 请参阅 android-native-dev 技能。

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