expo-examples

Expo 示例

expo/examples 是 Expo 官方的约 70 个集成示例库——目录名称为 with-<library>（例如 with-stripe、with-maps），每个示例都围绕一个库或服务构建。这些并非完整应用，而是托管式项目（没有 ios//android/ 目录——原生设置通过配置插件完成），通常只有一个约 100–200 行代码的屏幕。可从中借鉴规范的集成模式——依赖项、app.json 配置插件，以及 Expo 针对当前 SDK 维护的最简接线方式——并将其应用到用户的应用中。不要指望从中直接套用应用架构。

手动编写集成前，先查找示例。（示例类型——全栈、展示和起步项目——见 ./references/catalog.md。）

两种模式

1. 借鉴 / 改编（最常见）——用户已有项目。找到匹配的示例，阅读关键文件，并将其模式应用到用户的代码中。
2. 搭建脚手架——从零开始。直接基于示例创建新项目。

工作流

1. 找到合适的示例

将用户的需求对应到示例名称（例如，支付 → with-stripe，身份验证 → with-clerk）。./references/catalog.md 是按类别整理的快照，便于快速筛选，但内容可能过时，因此要根据实时列表进行确认：

# Live example names:
gh api repos/expo/examples/contents --jq '.[] | select(.type=="dir" and (.name|startswith(".")|not)) | .name'
# Aliases (renamed) + deprecated (dead/moved) examples — check before recommending:
gh api repos/expo/examples/contents/meta.json --jq '.content' | base64 -d

meta.json 是示例重命名或失效情况的事实来源（已弃用的示例会从仓库树中移除，但仍会列在这里，每个示例都带有一条 message）。如果示例位于其 deprecated 映射中，不要推荐它；按照 message 指向的现代方案操作。如果它位于 aliases 中，则使用 destination。

2a. 借鉴模式——研究示例，不动用户项目

最常见的情况：用户已有应用，想了解 Expo 如何实现某项功能。将示例作为参考阅读，手动应用其中的模式——绝不要在用户项目中直接搭建示例。

**首先，一次性列出整个示例。**集成代码通常嵌套较深（例如，Stripe 的服务端路由位于 app/api/），只列出一层会漏掉重要文件：

gh api 'repos/expo/examples/git/trees/master?recursive=1' \
  --jq '.tree[].path | select(startswith("with-stripe/"))'

然后优先阅读高价值文件：README.md（设置）→ package.json（依赖项）→ app.json（配置插件 / 权限）→ 清单中显示的集成代码 → .env（必需的密钥）。每个文件：

gh api repos/expo/examples/contents/with-stripe/utils/stripe-server.ts --jq '.content' | base64 -d
# No gh? Raw URL (branch is master):
curl -s https://raw.githubusercontent.com/expo/examples/master/with-stripe/utils/stripe-server.ts

**要阅读的文件不止两三个？许多集成分布在服务端路由、客户端 Provider 和配置中（Stripe 就是如此）。跳过逐个读取文件的操作——将整个示例拉取到一个临时 / 被 git 忽略的目录（不是用户项目）**中，然后使用 Grep/Read 随意阅读，再手动应用：

npx degit expo/examples/with-stripe /tmp/expo-ref/with-stripe   # clean copy, no git history
# fallback without degit (sparse-checkout, no full ~64 MB clone):
git clone --depth 1 --filter=blob:none --sparse https://github.com/expo/examples.git /tmp/expo-ref/examples \
  && (cd /tmp/expo-ref/examples && git sparse-checkout set with-stripe)

使用 Grep/Read 阅读该目录中的内容；完成后删除临时目录。

2b. 搭建脚手架模式——基于示例创建新项目

npx create-expo --example with-stripe   # short form:  npx create-expo -e with-stripe
bun create expo --example with-stripe    # with bun

3. 将其改编到用户的应用中——以非破坏性方式操作（至关重要）

用户已有应用时，只添加示例引入的内容；绝不要覆盖用户现有的设置。

• 对齐版本——不要复制固定版本。示例会追踪最新 SDK，因此其 package.json 中固定的版本可能与较旧项目不匹配。只通过 npx expo install <pkg> 添加缺少的依赖项（该命令会解析与 SDK 兼容的版本），而不要照搬确切版本。
• **合并配置，不要替换。**只添加示例引入且用户尚未配置的 app.json/app.config.* 插件和权限——保留现有配置块不变。
• 移植集成代码。
• 根据示例的 .env 格式重新创建环境变量——其中包含占位符，不包含可用的密钥。

**完成标准：**已移植集成代码，并且用户的应用中已落实其所需的每项依赖项、配置插件、权限和环境变量——而不只是看起来已完成接线。

注意事项

• 默认分支是 master， 不是 main（这对原始 URL 和稀疏检出很重要）。
• 一键部署。 每个示例都有一个启动 URL：https://launch.expo.dev/?github=https://github.com/expo/examples/tree/master/<example>。

相关技能

• 原生 UI 组件（@expo/ui package）→ expo-ui
• 样式设计和原生风格的屏幕 → expo-native-ui
• 导航和路由 → expo-router
• 编写原生模块 → expo-module
• 在采用最新 SDK 示例前升级 SDK → expo-upgrade

参考资料

• ./references/catalog.md — 示例库的分类快照，便于快速筛选。

提交反馈

如果你发现此技能中有错误、误导性或过时的信息，请报告，以便 Expo 改进：

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

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