React Native 开发规范

组件性能

• 列表项超过 10 条时，必须使用 FlatList — 使用 ScrollView 配合 map 会将全部内容加载进内存，而 FlatList 支持虚拟化渲染
• keyExtractor 必须返回稳定且唯一的字符串 — 使用数组索引（index）作为 key 会在列表重排序或删除时引发 bug
• React.memo 可防止 props 未变化时的重复渲染 — 应包裹纯展示型组件
• 向子组件传递函数时应使用 useCallback — 每次渲染生成新函数引用会触发子组件重新渲染
• 避免在 render 中使用内联样式 — 每次渲染都会创建新对象，应提取至 StyleSheet.create 中定义

状态管理

• useState 适用于组件级本地状态 — 不应仅为一个开关状态就引入 Redux/Zustand
• 仅将状态提升至最低公共父组件 — 提升过高会导致不必要的重新渲染
• 对开销较大的计算使用 useMemo — 但切勿滥用，缓存本身也存在性能开销
• Context 在任意值变更时会重新渲染所有消费者 — 应按更新频率拆分多个 Context
• 避免在 state 中存储派生数据 — 应在渲染过程中基于源状态动态计算

导航

• React Navigation 是标准导航方案 — Expo 项目中推荐使用 Expo Router 实现基于文件系统的路由
• Stack 屏幕默认保持挂载状态 — 需在 useEffect 的清理函数中手动清除订阅和定时器
• 仅传递可序列化的参数 — 函数和复杂对象会破坏深度链接及状态持久化能力
• 使用 useFocusEffect 处理屏幕专属副作用 — 该 Hook 在屏幕获得焦点时执行，而不仅限于首次挂载
• 认证流程中使用 navigation.reset — 清空返回栈，防止登录成功后仍可返回登录页

样式

• StyleSheet.create 必须定义在组件体外部 — 确保样式对象仅创建一次，而非每次渲染都重建
• Flexbox 默认行为与 Web 不同 — 默认 flexDirection: 'column'，无需显式设置 display: flex
• 尺寸单位为密度无关像素（dp / pt） — 不得直接使用设计工具提供的像素值
• 使用 Platform.select 实现平台特定样式 — 比在样式对象中嵌入条件判断更清晰简洁
• 不支持 CSS 继承机制 — 文本样式不会级联，每个 Text 组件均需显式指定样式

原生模块

• Expo 提供的模块已覆盖绝大多数需求 — 对于相机、定位、通知等常见功能，无需执行 eject 操作
• expo-dev-client 可在不完全 eject 的前提下启用原生模块 — 兼顾开发体验与原生能力
• React Native 新架构（Fabric、TurboModules）为可选特性 — 启用前请确认所用第三方库是否兼容
• 原生层崩溃不会出现在 JS 调试器中 — 需通过 Xcode 或 Android Studio 查看原生日志

性能调试

• 应启用 Hermes 引擎 — 显著提升启动速度并降低内存占用
• 使用 InteractionManager.runAfterInteractions 延迟执行耗时任务 — 保障动画流畅性
• 动画应启用 useNativeDriver: true — 使动画运行于 UI 线程而非 JS 线程
• 生产环境禁用 console.log — 严重影响性能，如需保留请使用 __DEV__ 宏进行条件编译
• 使用 Flipper 进行调试 — 支持网络请求分析、布局检查、性能剖析等功能

图片

• 合理使用 resizeMode — cover 会裁剪图像，contain 会添加黑边/白边，stretch 会导致形变
• 预加载图片以优化用户体验：Image.prefetch(url) 应在图片显示前调用
• 本地图片需显式声明宽高 — 远程图片若已设置其中一个维度，可借助宽高比自动适配
• 图标类 SVG 推荐使用 react-native-svg — 相比 PNG 更具缩放优势
• 远程图片建议使用 react-native-fast-image 缓存 — 原生 Image 组件无持久化缓存机制

常见错误

• 不可直接在 useEffect 中使用 async 函数 — 必须先在内部定义异步函数，再显式调用
• 列表中缺失 key 警告 — 务必为每一项提供唯一且稳定的 key
• 误以为 Web 端 React 的开发模式可直接复用 — React Native 无 DOM、无 CSS、事件系统亦不相同
• 遗漏 useEffect 中的清理逻辑 — 订阅、定时器、监听器等若未通过返回函数清理，将导致内存泄漏
• 仅在单一平台测试 — iOS 与 Android 行为差异显著，应定期双端验证

平台差异

• Android 需显式设置 overflow: 'hidden' 才能实现圆角裁剪 — iOS 默认即支持
• 阴影效果：iOS 使用 shadow* 系列属性，Android 使用 elevation
• 状态栏（StatusBar）行为存在差异 — 需分别测试其可见性与颜色表现
• 返回键（Back Button）为 Android 特有 — 应通过 BackHandler 或导航监听器统一处理
• 推送通知配置方式差异极大 — 各平台需单独完成对应配置

构建与发布

• 遇到无法解释的构建失败时，运行 npx react-native clean — 清除缓存与派生数据
• iOS 构建：添加原生依赖后需执行 cd ios && pod install — 此步骤常被遗漏
• Android 构建：遇到顽固构建问题时，执行 cd android && ./gradlew clean
• EAS Build（Expo）可大幅简化 CI/CD 流程 — 自动处理签名、版本管理、应用商店提交等环节
• 提交前务必本地测试发布版构建 — 开发环境与生产环境行为可能存在差异