React Native 与 Expo 开发指南

一份实用的指南，用于构建生产就绪的 React Native 和 Expo 应用程序。涵盖 UI、动画、状态管理、测试、性能优化及部署。

参考资料

根据需要查阅以下资源：

• [references/navigation.md](references/navigation.md) — Expo Router：堆栈导航、标签页、原生标签页（headerLargeTitle、headerBackButtonDisplayMode）、链接、模态框、弹出面板、上下文菜单
• [references/components.md](references/components.md) — FlashList 使用模式、expo-image、安全区域（contentInsetAdjustmentBehavior）、原生控件、模糊/玻璃效果、本地存储
• [references/styling.md](references/styling.md) — StyleSheet、NativeWind/Tailwind、平台样式、主题化、深色模式
• [references/animations.md](references/animations.md) — Reanimated 3：进入/退出动画、共享值、手势、滚动驱动动画
• [references/state-management.md](references/state-management.md) — Zustand（选择器、持久化）、Jotai（原子、派生状态）、React Query、Context
• [references/forms.md](references/forms.md) — React Hook Form + Zod：表单验证、多步表单、动态数组
• [references/networking.md](references/networking.md) — fetch 封装、React Query（乐观更新）、认证令牌、离线支持、API 路由、Webhook
• [references/performance.md](references/performance.md) — 性能分析流程、FlashList + memo、包体积分析、首次内容渲染时间（TTI）、内存泄漏、动画性能
• [references/testing.md](references/testing.md) — Jest、React Native Testing Library、Maestro 实现端到端测试
• [references/native-capabilities.md](references/native-capabilities.md) — 相机、位置、权限（use*Permissions 钩子）、触觉反馈、通知、生物识别
• [references/engineering.md](references/engineering.md) — 项目结构（components/ui/、stores/、services/）、路径别名、SDK 升级、EAS 构建/提交、CI/CD、DOM 组件

快速参考

组件使用建议

项目扩展建议

状态管理方案

性能优化优先级

新项目初始化

# 1. 创建项目
npx create-expo-app@latest my-app --template blank-typescript
cd my-app

# 2. 安装 Expo Router 及核心依赖
npx expo install expo-router react-native-safe-area-context react-native-screens

# 3. （可选）安装常用附加模块
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 作为根堆栈布局
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

核心开发原则

在编写代码前先查阅参考文档：涉及导航、列表、网络请求或项目搭建时，请先阅读对应参考文件，了解最佳实践与常见陷阱。

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

条件渲染：使用 {count > 0 && <Text />} 而非 {count && <Text />}（后者会将 0 当作真值渲染“0”）。

动画规则：仅对 transform 和 opacity 进行动画——这些属性由 GPU 合成，不会引发布局重排。

导入规范：始终直接从源文件导入，避免使用通配符导入（barrel files），以减少包体积。

列表与图片：在使用 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 分析包体积，确认无通配符导入
• [ ] Android 启用 R8 压缩
• [ ] 关键路径完成单元测试与组件测试
• [ ] 登录、核心功能、结账流程完成端到端测试

React Native 开发 → 请参阅 flutter-dev 技能。

iOS 原生（UIKit/SwiftUI）→ 请参阅 ios-application-dev 技能。

Android 原生（Kotlin/Compose）→ 请参阅 android-native-dev 技能。

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