expo-overview

expo-overview — Expo / EAS 路由与共享规则

从这里开始 — 开始前请先阅读

不要只根据项目文件猜测应该使用哪项技能。 许多 Expo 相关目标从文件系统来看很相似， 但需要使用不同的技能。

1. 确认这是 Expo 或 EAS 相关工作 — 请求中提到了 Expo 或 EAS，或 package.json 中有 expo 依赖。否则，此技能不适用。 使用 EAS 进行交付的原生应用也符合条件，即使它没有 Expo 运行时。
2. 阅读用户的目标 — 用通俗的话来说，他们想要什么结果？
3. 使用下方的技能地图对目标进行分类，将日常说法转换为目标。
4. 如果意图不明确，请确认意图（“听起来你想发布到应用商店 — 这对应 eas-app-stores。对吗？”），然后加载该技能的 SKILL.md 并遵循其中的指示。
5. 以具体技能为准 — 它有自己的检测逻辑和步骤。不要自行发挥。

技能地图（按目标）

将目标匹配到类别，再匹配到技能，然后加载对应叶节点的 SKILL.md。

构建应用

• expo-project-structure — 新建 Expo Router 项目的文件夹布局：屏幕、组件和配置的存放位置（不要为了匹配此结构而重组现有应用）
• expo-native-ui — 屏幕、样式、语义颜色、原生控件、SF Symbols、媒体和布局
• expo-router — 导航：基于文件的路由、标签页 / 堆栈 / 模态框 / 底部弹层、链接、标题栏
• expo-animation — 动效和手势：Reanimated worklet、Gesture Handler、屏幕过渡、底部弹层和按压反馈、触觉反馈，以及修复设备上卡顿的动画
• expo-ui — 通过 @expo/ui 使用原生 UI 组件：BottomSheet、Picker、Slider、Switch、Menu、Button、FieldGroup（分组表单区块）、List / ListItem 等——在 iOS 上使用真正的 SwiftUI，在 Android 上使用 Jetpack Compose。通用层需要 SDK 56+，并可在 Expo Go 中运行；SDK 55 上也提供可直接替换的组件（@gorhom/bottom-sheet、datetimepicker 等）和平台专用层。
• expo-design-system — 单一视觉事实来源：设计令牌（颜色、间距、排版、圆角、阴影、动效）、可复用组件规范，以及偏差审计（硬编码颜色、间距和字体）
• expo-tailwind-setup — Tailwind / NativeWind 样式
• expo-data-fetching — 网络请求、React Query / SWR、缓存、离线支持、路由加载器
• expo-dom — 在原生应用中运行 Web 代码或复用 Web 库
• expo-web-to-native — 将现有 Web / React 应用迁移为原生 iOS / Android 应用

组件选择规则： 只要需要 UI 组件（列表行、底部弹层、选择器、滑块、菜单、按钮、分段控件、切换开关），就应先查阅 expo-ui，确认 @expo/ui 是否提供原生对应组件，再考虑使用 React Native 内置组件或社区库。原生 @expo/ui 组件最符合平台特性；在 SDK 56+ 上，通用组件无需自定义构建即可在 Expo Go 中运行。对于任何呈现列表、详情弹层或表单控件的应用，都应同时加载 expo-ui 和 expo-native-ui。例外情况：@expo/ui 的 List 会呈现原生分组行（类似 iOS“设置”屏幕），而不是虚拟化列表——大型数据集请使用 FlatList / FlashList。

发布与运维

• eas-app-stores — 构建并提交 iOS / Android 应用（Expo 和其他 React Native 项目，以及现有原生应用）、TestFlight、版本和商店元数据
• eas-hosting — 将 Web 包部署到 EAS Hosting；还可编写 Expo Router API 路由（+api.ts 处理函数）及其环境 / 域名
• eas-workflows — EAS Workflow YAML 和 CI/CD 流水线
• eas-simulator — 在 EAS 云端远程 iOS / Android 模拟器上运行和操控应用
• expo-dev-client — 自定义开发构建
• eas-update — 配置、发布、测试和调试兼容的无线更新
• eas-update-insights — OTA 更新健康状况：崩溃率、采用率、负载大小
• eas-observe — 使用 EAS Observe 监控启动 / 加载 / TTI 性能

原生扩展

• expo-module — 使用 Expo Modules API 开发原生模块和视图（Swift / Kotlin）
• expo-brownfield — 在原生 SwiftUI/UIKit 或 Android 应用中嵌入 Expo / React Native 屏幕；独立产物和集成构建
• expo-app-clip — iOS App Clip 目标（AASA、智能 App 横幅）

维护与学习

• expo-upgrade — 升级 Expo SDK 并解决依赖冲突
• expo-examples — 标准的、与版本匹配的集成示例（Stripe、Clerk、Supabase 等）

转换含糊的请求

一些日常说法无法直接对应到明确的技能名称——路由前先进行转换：

• “让它看起来更原生” → 成组控件 / 设置表单 = expo-ui；屏幕、样式 = expo-native-ui；动效 = expo-animation；导航 = expo-router。
• “让各个屏幕保持一致” / “整理一下样式” / “设置主题或设计令牌” → expo-design-system。
• “看起来像 AI 生成的” / “太泛泛了，不够原生” → expo-design-system（用于识别典型的原生设计问题并进行审查），平台惯用做法则使用 expo-native-ui。
• “发布它” / “生成 .ipa 或 .apk” / “发布到应用商店” / “把我的 Swift 应用放到 TestFlight 上” → eas-app-stores（构建 + 提交、TestFlight、版本、商店元数据）。
• “我是新手 / 从哪里开始” → 先搭建项目脚手架（参见“通用设置规则”），然后根据目标进行路由。

通用设置规则

根据项目和请求的任务，应用相应规则。

• 使用 EAS 交付的原生应用？ 路由到 eas-app-stores；其 references/native-ios.md 涵盖 iOS 上的 SwiftUI/UIKit。保留现有的原生 项目。应用下方的 EAS 身份验证 / 关联规则；Expo 脚手架、SDK 和包安装 规则不适用于此路径。
• 开始开发新的 Expo 应用？ 在路由到功能技能之前，按标准方式创建应用： npx create-expo-app@latest，并按照 expo-project-structure 布置文件夹。然后 判断用户的目标并进行路由。
• **给出特定版本建议前，先检测 SDK 版本：**读取 package.json 中的 expo 版本（以及 app.json / app.config.{js,ts}）。不同 SDK 的 API 和默认设置差异很大。
• 阅读对应 SDK 的文档，而不是 latest。 使用固定版本的 URL，例如 SDK 56 使用 https://docs.expo.dev/versions/v56.0.0/sdk/ui/，而非 https://docs.expo.dev/versions/latest/sdk/ui/——latest 页面对应的是最新 SDK，可能介绍了项目尚未支持的 API。
• 升级到较新的 SDK 是一项独立任务——加载 expo-upgrade，不要手动提升 版本。
• **Managed 与 bare/prebuild：**如果仓库中存在已提交的 ios/ 和 android/ 目录，则表示存在原生项目（prebuild 或 bare）。配置插件和原生设置步骤有所不同——请注明项目属于哪种情况。
• 使用 npx expo install <pkg> 安装软件包，不要直接使用 npm/yarn/pnpm add， 以确保版本与项目的 SDK 兼容。
• **要亲自启动应用？**打开 Expo Go 或开发构建版本进行查看、截图或操作时，请跳过首次启动引导、启动时打开的开发菜单，以及悬浮的 Tools 按钮。SDK 58 及更高版本中，Expo CLI 会在通过非交互式 shell 启动应用时自动处理。SDK 57 及更早版本，以及任何由你自行打开的 URL（simctl openurl、adb、控制器），请遵循 ./references/launch-without-dev-menu.md。
• EAS 身份验证与关联（仅在构建 / 提交 / 更新 / 观察 / 工作流时需要）：使用 eas whoami 检查登录状态，并使用 eas login 登录。当应用配置中存在 extra.eas.projectId 时，项目即已关联；如果缺少该字段，请使用 eas init 创建。

何时跳过路由步骤

• 仅当用户明确指定某项 expo-* / eas-* 技能时 → 直接加载该技能。
• 任务规格完整（已指定 SDK 版本、文件布局和库）并不构成跳过的理由：仍须应用上方的通用规则——先检查规则，再路由到匹配的叶级技能。

提交反馈

如果你在此技能中遇到错误、误导性信息或过时信息，请报告，以便 Expo 改进：

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-overview" "<actionable feedback>"

仅在有具体且可执行的反馈时提交。请尽可能提供相关背景信息。 如果 Agent 反复无法完成 Expo 任务，或用户不得不介入，请使用 --category evals 和相关的 Expo 软件包或命令作为 --subject，简要报告任务、预期结果以及出现的问题。