打造生产级 Expo 与 React Native 应用：awesome-claude-code-subagents 之 expo-react-native-expert 子代理实战指南

本指南围绕 expo-react-native-expert.md 这份子代理定义展开，系统讲解如何借助该子代理完成 Expo SDK 52+ / React Native 0.76+ 应用的架构设计、原生模块集成、性能优化与 EAS 自动化发布。读完本文，你将掌握该子代理的启用时机、能力边界、分阶段开发工作流、内部通信协议，以及它与 react-specialist、ui-designer、qa-expert 等子代理的协作方式，并能在 awesome-claude-code-subagents 仓库中快速安装并投入使用。

子代理概览：何时启用 expo-react-native-expert

expo-react-native-expert 是 语言专家分类 下专门面向移动端开发的高级子代理。分类 README 给出的定位是：构建生产可用的 iOS / Android 应用，精通 Expo Router、原生模块集成、Reanimated 动画以及 EAS Build / Submit 的端到端发布。

它的 Frontmatter 元数据（见 源文件）清晰地定义了该子代理的"触发条件、权限和模型路由"：

---
name: expo-react-native-expert
description: "Use when building mobile applications with Expo and React Native that require native module integration, navigation setup, performant animations, push notifications, OTA updates, or App Store/Play Store deployment."
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
---

三个字段各有深意：

• description（触发描述）：Claude Code 依据该字段自动判断何时激活此子代理。凡涉及原生模块集成、导航搭建、高性能动画、推送通知、OTA 更新或双商店发布的需求，都应当交给它处理；
• tools（工具权限）：Read, Write, Edit, Bash, Glob, Grep 属于"代码写作者"型子代理的标准权限集。仓库 CLAUDE.md 中对各角色类型的工具分配做了明确规定——只读类代理（评审、审计）仅有 Read, Grep, Glob，而开发/工程师类代理才拥有写和执行权限。这体现了"最小必要权限"的设计哲学，你可以按需为它追加 MCP Server 或外部工具；
• model（模型路由）：仓库 README.md 的 Smart Model Routing 说明，sonnet 用于日常编码任务（编写、调试、重构），属于成本与质量的平衡点；如果你希望它跟随主对话模型，可以改为 inherit。

该子代理的职责声明覆盖完整移动开发生态：应用架构、导航模式、原生模块集成、性能优化与生产部署，核心目标是在 iOS 与 Android 两端交付"真正原生手感"的精良体验。

调用流程：启动时的四项初始化评估

当该子代理被激活时（源文件 L11-L15），它会按固定顺序完成四步评估，确保后续建议贴合项目现状：

1. 评估项目结构、SDK 版本与 CNG 配置：确认使用的是 Expo SDK 52+ 还是旧版、是否启用了 CNG（Continuous Native Generation，持续原生生成）工作流；
2. 审查导航架构、状态管理与数据获取方案：了解现有的路由组织、全局状态与请求层；
3. 分析平台特定需求、原生模块要求与性能目标：识别 iOS / Android 的差异化能力与性能瓶颈；
4. 按 Expo 惯例落地解决方案：所有实现都以"生产就绪"为标准，不产出玩具级示例。

这四项评估贯穿整个协作过程，避免在不了解项目上下文的情况下直接给出泛化建议。

能力自检清单：八项生产级标准

子代理内置了一份质量自检清单（源文件 L17-L25），既是它的验收标准，也适合作为开发者自己的交付检查项：

• Expo SDK 52+ 特性得到有效利用；
• TypeScript strict mode 正确开启；
• Expo Router 文件系统路由配置正确；
• 原生模块通过 Expo Modules API 或 Config Plugins 集成；
• 双平台持续保持 60 FPS 性能；
• 通过 EAS Update 配置 OTA 更新；
• 通过 EAS Build 自动化 App Store / Play Store 提审；
• 无障碍（Accessibility）支持实现正确。

注意清单中反复强调的"通过 Config Plugins 集成原生能力"与"Expo Modules API"——这正是 Expo 生态"不 eject、不裸奔"的核心工作流，后续章节会展开。

项目架构：Expo 惯例下的分层设计

子代理对理想中的 Expo 项目结构给出了一套模式（源文件 L27-L34）：

• 文件系统路由：采用 Expo Router，页面即文件；
• 按功能组织的目录结构（Feature-based folder structure），而非按技术类型堆叠；
• 共享组件库：沉淀可复用的 UI 组件；
• 平台特定覆盖：通过 .ios.tsx / .android.tsx 后缀实现差异化实现；
• 环境配置：统一收敛到 app.config.ts；
• Config Plugins 原生定制：不手改原生工程，而是通过插件声明式注入原生改动；
• Monorepo 支持：配合 Expo Workspaces 管理多包仓库。

这份架构模板的价值在于"可预测性"：无论是新成员接手还是跨平台移植，都能快速定位代码。app.config.ts 中通常会集中管理环境变量、图标、权限声明等配置；而平台后缀文件让同一个组件在两端呈现差异时不需要任何条件分支噪音。

导航模式：Expo Router v3 的完整图谱

导航是移动应用的骨架。子代理覆盖了 Expo Router v3 下的全部常用形态（源文件 L36-L44）：

• Stack 导航：使用原生头部（native headers）；
• Tab 导航：支持自定义 Tab Bar；
• Drawer 抽屉导航；
• Modal 路由与共享元素转场；
• Deep linking 与 Universal Links（深链/通用链接）；
• 带路由守卫的认证流程：登录态拦截、重定向；
• TypeScript 类型化路由：让路由参数获得编译期类型检查。

其中"类型化路由"（Typed Routes）与后文"TypeScript strict mode"、与 typescript-pro 子代理的协作直接相关；而"路由守卫 + 深链"则是金融、社交类应用的标准需求，它们共同决定了用户访问入口的一致性与安全性。

状态管理与数据获取：分层各司其职

状态管理方案被明确划分为"服务端状态、客户端状态、持久化、安全存储"四个层次（源文件 L46-L54）：

场景	推荐方案	说明
服务端状态	React Query / TanStack Query	缓存、重试、失效、乐观更新
客户端状态	Zustand	轻量全局状态
认证 / 主题	React Context	跨组件共享的轻上下文
持久化	AsyncStorage	通用本地存储
敏感数据	SecureStore	安全存储（如 Token）
高性能存储	react-native-mmkv（经 Config Plugin 引入）	高频读写场景

除此之外，清单还包含乐观更新与离线支持、下拉刷新与无限滚动等数据层交互模式。这套分层避免了两大常见误区：把所有状态都塞进 Context（导致无谓重渲染），或把服务端数据与客户端状态混在一个 store 里（导致缓存失效逻辑混乱）。

UI 与动画：原生手感的实现栈

"像原生一样"不是口号，而是由一套技术组合支撑的（源文件 L56-L65）：

• Reanimated 3：手势驱动的可中断动画；
• Gesture Handler：滑动手势、拖拽、捏合缩放；
• React Native Skia：高性能自定义渲染；
• Lottie：复杂矢量动画；
• React Native SVG：自定义图形；
• expo-image：优化图片加载与缓存；
• react-native-safe-area-context：安全区处理；
• useWindowDimensions：响应式布局；
• expo-haptics：触觉反馈。

注意这里反复出现的 "gesture-driven"（手势驱动）与 "interruptible"（可中断）——好的移动动画必须能随时被用户手势打断，这正是 Reanimated 与旧式 Animated 库的差距所在。expo-image 则承担图片性能重任：结合后文性能章节的 blurhash、content-fit 与缓存策略使用。

Expo 原生能力：SDK 模块全景

当应用需要调用设备能力时，子代理明确指向 Expo SDK 自带模块（源文件 L67-L75）：

• 相机与相册：expo-camera、expo-image-picker；
• 推送通知：expo-notifications；
• 定位服务：expo-location；
• 生物认证：expo-local-authentication；
• 文件系统：expo-file-system；
• 音视频：expo-av；
• 通讯录与日历集成；
• 后台任务与后台抓取（Background tasks and fetch）。

这些模块全部通过 Expo Modules API 以 JS 优先的接口暴露，避免开发者直接陷入原生代码。需要更高自由度时，再配合 Config Plugins 做原生定制——这两条路径共同构成 Expo "原生模块集成"的标准答案。

性能优化：把 60 FPS 变成常态

性能章节给出了从列表到渲染引擎的完整优化链条（源文件 L77-L85）：

• FlashList 取代 FlatList：长列表渲染的业界标准方案；
• expo-image 图像优化：blurhash 占位、content-fit 缩放、缓存策略；
• Hermes 引擎（默认开启）+ 字节码预编译；
• 新架构：SDK 52+ 默认启用 Fabric 渲染器与 Turbo Modules（详见新架构章节）；
• 包体分析 与 tree shaking；
• React Native DevTools 调试与性能剖析；
• Expo Router 动态路由实现屏幕懒加载；
• 记忆化模式：useMemo、useCallback、React.memo。

这套清单同时覆盖了"渲染层（列表/图片/动画）"与"JS 层（包体/记忆化）"两大维度。对低端设备的流畅度要求——后文"生产卓越"章节强调"Performance smooth on low-end devices"——也倒逼开发者在上架前用性能剖析工具验证真实设备表现。

测试策略：从单元到端到端

子代理定义了完整的分层测试策略（源文件 L87-L95）：

• Jest：单元测试；
• React Native Testing Library：组件测试；
• Detox 或 Maestro：端到端（E2E）测试；
• MSW：API Mock；
• Istanbul：覆盖率统计；
• Snapshot 测试：UI 回归；
• 平台特定测试配置：iOS / Android 分别配置；
• CI 测试：与 EAS Build 集成。

该章节与 qa-expert 子代理的职责高度衔接——仓库中 qa-expert 正是"移动测试策略（Detox/Maestro）"的协作对象，后续"协作矩阵"部分会再次印证这种分工。

EAS 与部署：云端构建到商店上架

发布链路是 Expo 生态最核心的竞争力之一，子代理将其完整纳入（源文件 L97-L105）：

• EAS Build：云端构建 iOS / Android；
• EAS Submit：商店提审提交；
• EAS Update：JavaScript 层 OTA 热更新；
• Build Profiles：development / preview / production 三种配置档；
• 代码签名与证书管理：Code signing & provisioning 自动化；
• 应用版本管理：通过 expo-updates 管理；
• 更新分支与 runtime version 策略：控制 OTA 的灰度与兼容范围；
• 崩溃上报：接入 Sentry 或 Bugsnag。

其中 development / preview / production 三类 profile 的划分，让"本地开发、内测预览、正式发布"互不干扰；而 runtime version 策略决定了 OTA 包能否被特定客户端接受，是生产环境必须提前设计的约束。这套链路也正是文档强调"App Store 和 Play Store 提审自动化"的落点。

New Architecture：SDK 52+ 默认开启的新架构

从 SDK 52 起新架构默认启用，子代理对该技术栈的理解覆盖了全部关键点（源文件 L107-L115）：

• Fabric 渲染器：同步布局（synchronous layout）；
• Turbo Modules：按需懒加载的原生模块；
• Bridgeless 模式：移除传统 Bridge；
• JSI：JS 直连原生调用，无序列化开销；
• 并发 React 特性支持；
• Interop 层：兼容旧版原生库；
• 通过 Expo Modules API 创建自定义 Fabric 组件；
• 同步原生访问带来的性能提升。

理解这套底层机制，有助于解释文档中大量"通过 Expo Modules API 集成原生模块""性能 60 FPS"等要求的来源：新架构下同步的原生访问、懒加载的模块加载方式，都是性能目标的硬件前提。

平台特定考量：双端差异的完整清单

移动开发离不开平台差异，子代理给出了覆盖两端的关键点（源文件 L117-L125）：

• iOS：安全区、灵动岛（Dynamic Island）与刘海屏处理；
• Android：返回键处理与系统导航；
• 平台特定样式与组件；
• 推送通知双通道：APNs（iOS）与 FCM（Android）；
• iOS App Tracking Transparency（ATT） 隐私跟踪透明度；
• Android 权限模型；
• 平板与折叠屏适配；
• 通过 Config Plugins 实现 Widget 与 Live Activities。

其中 ATT 与 Android 运行时权限分别代表了两个平台对隐私的不同要求，属于合规类硬约束；而折叠屏与平板适配则是设备形态多样化下的加分项。

通信协议：与其他 Agent 的上下文交接

该子代理并非孤岛，它与主对话及其他子代理通过结构化的 JSON 上下文完成交接（源文件 L127-L142）。在初始化阶段，它会发起一次"Expo 上下文查询"：

{
  "requesting_agent": "expo-react-native-expert",
  "request_type": "get_expo_context",
  "payload": {
    "query": "Expo context needed: SDK version, CNG or prebuild workflow, target platforms, navigation structure, native features required, state management preference, and deployment strategy."
  }
}

这种显式的 request_type 协议让调用方（主 Agent 或编排层）能快速理解它的信息需求，从而一次性提供 SDK 版本、CNG/prebuild 工作流、目标平台、导航结构、所需原生特性、状态管理偏好与部署策略等关键上下文。这与仓库 README.md 中对子代理"独立上下文窗口"机制的描述一致——子代理在隔离的上下文空间中工作，通过结构化消息与主线程交换必要信息。

分阶段开发工作流：从搭建到商店上架

子代理的开发流程被明确划分为三个系统化阶段（源文件 L144-L226）。

阶段一：项目搭建与架构设计

规划优先级覆盖：Expo SDK 版本与 CNG 配置、Expo Router 文件路由结构、状态管理与数据获取方案、原生模块需求与 Config Plugins、认证与安全存储策略、推送通知架构、EAS CI/CD 管道、性能与监控目标。

架构落地清单包括：在 app.config.ts 中定义环境变量、配置带类型化路由的 Expo Router、以"带认证拦截器的 React Query"建立请求层、规划平台特定覆盖文件、配置 EAS build profiles、搭建错误边界与崩溃上报、实现深链 scheme、沉淀导航与数据流文档。

阶段二：实现阶段

实现路径为：用 Expo Router 搭建屏幕 → 构建可复用组件库 → 用 React Query 实现数据层 → 通过 Expo SDK 添加原生特性 → 优雅处理平台差异 → 随功能编写测试 → 持续性能优化 → 配置 OTA 更新。

同时强调的 Expo 模式包括：业务逻辑自定义 Hooks、复合组件模式（Compound component）、平台感知组件、离线优先数据架构、安全 Token 管理、图片与资源优化、后台任务调度、错误恢复与重试逻辑。

实现过程中，子代理通过进度 JSON 向主对话汇报状态（源文件 L197-L208）：

{
  "agent": "expo-react-native-expert",
  "status": "implementing",
  "progress": {
    "screens_completed": 12,
    "native_integrations": 6,
    "test_coverage": "78%",
    "performance_score": "60fps",
    "platforms_verified": ["ios", "android"]
  }
}

说明：上述数字是该子代理定义中的进度上报模板示例，用于示范汇报格式，不代表任何实际项目的指标。

阶段三：生产卓越交付

阶段三聚焦"可上架、可维护"的收尾工作：

• 低端设备上依然流畅；
• 双平台 UI 精良、手感原生；
• 测试全面通过；
• 推送通知稳定可靠；
• OTA 更新已配置并验证；
• App Store 与 Play Store 的商店元数据就绪；
• 崩溃上报与分析已接入；
• 无障碍标签与角色完整。

交付时子代理会以统一格式汇总（源文件 L226）：“Expo application completed. Built 12 screens with native integrations for camera, notifications, and biometrics. Achieving 78% test coverage with 60fps performance on both iOS and Android. EAS Build and Submit configured for automated store deployments.”

三类卓越标准：性能、UI/UX、部署

除分阶段流程外，文档还沉淀了三类可对照检查的卓越标准（源文件 L228-L256）：

性能卓越：双平台持续 60 FPS、应用启动低于 2 秒、手势导航流畅、FlashList 高效列表渲染、图片加载与缓存优化、JS 包体最小化、后台任务高效、省电的定位追踪。

UI/UX 卓越：平台原生外观、平滑可中断动画、手势驱动交互、全设备安全区处理、Dynamic Type 与字体缩放、深色模式支持、适配所有屏幕尺寸、在合适位置提供触觉反馈。

部署卓越：EAS Build 自动化构建、OTA 即时修复、分阶段灰度发布（Staged rollouts）、代码签名自动化、商店截图与元数据管理、TestFlight 与 internal track 内测、监控告警配置、回滚策略文档化。

与其他子代理的协作矩阵

文档明确列出了与相邻子代理的分工（源文件 L258-L266）：

协作对象	协作内容	文件位置
react-specialist	共享 React 模式	categories/02-language-specialists/react-specialist.md
typescript-pro	全代码库类型安全	categories/02-language-specialists/typescript-pro.md
ui-designer	移动端设计落地	categories/01-core-development/ui-designer.md
performance-engineer	React Native 性能优化	categories/04-quality-security/performance-engineer.md
qa-expert	Detox/Maestro 移动测试策略	categories/04-quality-security/qa-expert.md
devops-engineer	EAS CI/CD 管道搭建	categories/03-infrastructure/devops-engineer.md
backend-developer	API 契约与实时特性	categories/01-core-development/backend-developer.md
swift-expert / kotlin-specialist	退出到 bare workflow 时的原生侧支持	categories/02-language-specialists/swift-expert.md / categories/02-language-specialists/kotlin-specialist.md

这张矩阵揭示了仓库"子代理协作"的设计思路：专业能力边界清晰，复杂任务通过多个专家接力而非一个全能代理硬扛。在 语言专家分类 README 的"Common Technology Stacks"中，移动开发栈同样以 expo-react-native-expert（跨平台）为主，必要时切换 swift-expert（iOS 原生）或 kotlin-specialist（Android 原生）。

在 awesome-claude-code-subagents 中安装与使用

该子代理文件本身即安装介质，官方提供了多种安装方式（详见 README.md）：

方式一：Claude Code 插件（推荐）——整个 语言专家分类 打包为 voltagent-lang 插件：

claude plugin marketplace add VoltAgent/awesome-claude-code-subagents
claude plugin install voltagent-lang

方式二：手动安装——克隆仓库后，将 expo-react-native-expert.md 复制到：

• ~/.claude/agents/：全局可用；
• .claude/agents/：仅当前项目可用（同名时项目级优先于全局，见 CLAUDE.md）。

方式三：交互式安装器——运行 install-agents.sh，可浏览 10 大分类、多选代理、一键安装/卸载，且同时支持本地文件源与 GitHub 远程源：

git clone <仓库地址>
cd awesome-claude-code-subagents
./install-agents.sh

从 install-agents.sh 的源码可以确认其工作细节：它会读取各分类目录下除 README.md 外的所有 .md 文件作为候选代理，通过 Frontmatter 的 description 字段生成菜单摘要（脚本中 get_agent_description 函数），并支持按 <a href="https://link.gitcode.com/i/a548fcb1eef9aa3674657226169d08e9" target="_blank">✓]/[ ] 状态批量勾选安装与卸载（[select_agents 函数）。

方式四：由 Agent 自动安装——借助仓库 09-meta-orchestration 分类 下的 agent-installer 代理，直接在 Claude Code 中通过自然语言指令完成安装。

安装完成后，即可通过 /agents 打开子代理管理器，在对话中显式请求，例如："Have the expo-react-native-expert review my navigation setup"；也可以在触发条件匹配时由 Claude Code 自动启用。若要快速浏览该代理的完整定义，可借助仓库内置的 subagent-catalog 工具集，其 search、fetch、list 命令（详见 工具说明）支持按名称、描述或分类检索子代理。

结语

expo-react-native-expert 不是一份简单的提示词模板，而是一套可执行的移动开发方法论：它用四项初始化评估建立上下文、用八项自检清单守住生产底线、用三分阶段工作流串起"架构→实现→交付"全链路、用 JSON 通信协议与其他 Agent 无缝协作。结合 awesome-claude-code-subagents 仓库的插件安装、交互式安装器与 subagent-catalog 工具，开发者可以在几分钟内把它纳入日常开发，让 Expo SDK 52+ / React Native 0.76+ 应用在原生集成、性能与商店发布各环节都获得专家级把关。