mobile-framework-expo

Expo 开发模式

快速指南： 使用 Expo 构建可用于生产环境的 React Native 应用。大多数项目应采用带持续原生生成的托管工作流，使用 Expo Router 进行基于文件的导航，并使用 EAS 进行构建和更新。开发构建取代 Expo Go，用于生产环境测试。

---

<critical_requirements>

关键：使用此技能前

所有代码都必须遵循项目在 CLAUDE.md 中的约定（kebab-case、命名导出、导入顺序、import type、命名常量）

（生产环境测试必须使用开发构建——Expo Go 仅用于原型开发）

（更改原生依赖时必须更新 runtimeVersion，以防止 OTA 更新导致崩溃）

（必须使用配置插件进行原生自定义——在托管工作流中绝不要手动编辑 android/ios 目录）

（客户端环境变量必须使用 EXPO_PUBLIC_ 前缀——绝不要在这些变量中存储机密）

</critical_requirements>

---

自动检测： Expo、expo-router、EAS Build、EAS Update、expo-dev-client、app.config.js、app.json、expo prebuild、npx expo、eas.json、expo-constants、expo-notifications、持续原生生成、CNG

适用场景：

• 快速开发需求下启动新的 React Native 项目
• 构建需要 OTA（空中下载）更新的应用
• 使用基于文件的路由，实现约定优于配置
• 管理原生代码，同时无需维护 android/ios 目录
• 通过云端构建部署到应用商店

涵盖的关键模式：

• 带持续原生生成（CNG）的托管工作流
• Expo Router 基于文件的导航
• EAS Build、Submit 和 Update 工作流
• 开发构建与 Expo Go
• 用于原生自定义的配置插件
• 环境配置与机密
• 推送通知设置

不适用场景：

• 需要超出 Expo Modules API 范围的复杂自定义原生代码的应用
• 应用大小必须小于 15MB 的情况（Expo 会增加额外开销）
• 尚未准备好迁移的旧版 React Native 项目

---

理念

Expo 将 React Native 开发从“一次编写，到处调试”转变为“一次编写，放心部署”。核心要点是，大多数应用不需要直接访问原生功能——它们需要的是维护良好、API 一致的原生模块。

核心原则：

1. 默认采用托管模式——让 Expo 处理原生复杂性；仅在必要时执行 prebuild
2. 持续原生生成——将 android/ios 视为构建产物，而非源代码
3. 以开发构建为准——Expo Go 用于学习；开发构建展现生产环境的真实情况
4. 通过 OTA 提升效率——无需等待应用商店审核即可发布 JavaScript 更新
5. 优先使用配置插件，而非退出托管模式——需要时以声明式方式自定义原生代码

思维模型：

Expo 并非对 React Native 的限制——它是面向专业用途的抽象层。你始终可以通过 Expo Modules API 或 prebuild 深入使用原生代码，但大多数应用都不需要这样做。

---

核心模式

模式 1：使用 app.config.ts 进行动态配置

使用 app.config.ts 构建特定于环境的应用。使用命名常量定义 SDK 版本和构建编号。

// app.config.ts - Environment-aware config
const IS_PRODUCTION = process.env.APP_ENV === "production";
const BUILD_NUMBER = 1;

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: IS_PRODUCTION ? "MyApp" : "MyApp (Dev)",
  ios: {
    bundleIdentifier: IS_PRODUCTION ? "com.app" : "com.app.dev",
    buildNumber: String(BUILD_NUMBER),
  },
  android: {
    package: IS_PRODUCTION ? "com.app" : "com.app.dev",
    versionCode: BUILD_NUMBER,
  },
});

完整示例：examples/core.md - 应用配置章节

---

模式 2：使用配置插件进行原生自定义

以声明式方式修改原生代码——更改在运行 expo prebuild --clean 后仍会保留。使用配置插件管理权限、SDK 版本和原生设置。

// app.config.ts plugins array
plugins: [
  [
    "expo-camera",
    { cameraPermission: "Allow $(PRODUCT_NAME) to access your camera." },
  ],
  [
    "expo-build-properties",
    { android: { minSdkVersion: 24 }, ios: { deploymentTarget: "15.1" } },
  ],
];

完整示例：examples/core.md - 配置插件章节

---

模式 3：环境变量

客户端变量使用 EXPO_PUBLIC_ 前缀。Metro 要求直接访问属性——解构和方括号表示法都不起作用。

// MUST use direct access - Metro static analysis requirement
const API_URL = process.env.EXPO_PUBLIC_API_URL; // Works
// const { EXPO_PUBLIC_API_URL } = process.env;  // BROKEN - undefined at runtime

完整示例：examples/core.md - 环境变量章节

---

模式 4：开发构建

使用 expo-dev-client 进行符合生产环境的测试。Expo Go 仅用于原型开发——它缺少你的原生依赖、推送通知和准确的启动屏幕。

# Cloud build
eas build --profile development --platform ios
# Local build
npx expo run:ios

完整配置：examples/eas.md - 开发构建部分

---

模式 5：资源管理

加载字体时阻止启动屏幕显示；使用 expo-image 加载远程图片，并提供模糊哈希占位图和磁盘缓存。

SplashScreen.preventAutoHideAsync();
// Load fonts, then call SplashScreen.hideAsync() when ready

完整示例：examples/core.md - 字体加载和图片处理部分

---

<red_flags>

危险信号

• 使用 Expo Go 进行生产测试——缺少原生模块、推送通知和准确的启动屏幕。始终使用开发构建。
• 原生更改后未更新 runtimeVersion——OTA 更新会导致原生代码不兼容的应用崩溃。使用 "fingerprint" 策略自动检测。
• 在 EXPO_PUBLIC_ 变量中存储机密——这些内容会嵌入 JS 包中，任何反编译应用的人都能看到。请使用 EAS Secrets 和后端代理。
• 手动编辑 android/ios 目录——执行 expo prebuild --clean 后，更改会丢失。请使用配置插件。
• 解构 process.env——Metro 要求直接访问属性（process.env.EXPO_PUBLIC_*）。解构和方括号表示法会导致值为 undefined。
• 使用 expo-av——它已在 SDK 55 中移除。迁移到 expo-video 和 expo-audio。
• 旧版架构——它已在 SDK 54 之后移除。React Native 0.82+ 要求使用新架构。

完整的反模式和注意事项：reference.md

</red_flags>

---

详细资源：

• examples/core.md - 项目配置、环境变量、字体、图片
• examples/router.md - 基于文件的路由、选项卡、身份验证流程、模态框
• examples/eas.md - 云构建、应用商店提交、OTA 更新
• reference.md - 决策框架、SDK 兼容性、反模式

---

<critical_reminders>

关键提醒

所有代码都必须遵循 CLAUDE.md 中的项目约定

（生产测试必须使用开发构建——Expo Go 仅用于原型开发）

（更改原生依赖时必须更新 runtimeVersion，以防止 OTA 更新崩溃）

（自定义原生功能必须使用配置插件——在托管工作流中绝不能手动编辑 android/ios 目录）

（客户端环境变量必须使用 EXPO_PUBLIC_ 前缀——绝不能在这些变量中存储机密）

不遵循这些规则会导致 OTA 更新崩溃、构建失败和安全漏洞。

</critical_reminders>