开发 React Native 应用时,有两件独立的事。一件是原生工程 android 与 ios 由谁维护;另一件是安装包在哪台机器上编译。裸 React Native、Expo、在已有工程里接入 Expo,回答的是第一件事。Expo 本地构建、EAS 本地构建、EAS 云构建,回答的是第二件事。
Expo 是一组开源工具,包括 Expo CLI、Expo SDK 和持续原生生成(Continuous Native Generation)。Expo 应用服务(Expo Application Services,EAS)是可选的托管服务,负责构建、提交和更新。使用这些开源工具时,可以不使用 EAS。尚未安装这些开源工具的 React Native 工程,也可以使用 EAS Build。
本文依据 2026-10-08 核对的 Expo 官方文档。当前文档把原生目录按需生成作为统一做法;需要原生目录时运行 npx expo prebuild。expo eject 已从 SDK 46 移除。
三种工程形态
一个仓库属于哪种形态,看两样东西:有没有提交 android 与 ios,以及有没有安装 expo 包。
| 对比项 | 裸 React Native | Expo(持续原生生成) | 已有工程接入 Expo |
|---|---|---|---|
| 对比项常见起点 | 裸 React NativeReact Native 社区 CLI 初始化 | Expo(持续原生生成)npx create-expo-app |
已有工程接入 Expo在已有工程中运行 npx install-expo-modules |
| 对比项原生目录 | 裸 React Native提交到 Git,直接修改 | Expo(持续原生生成)默认不提交,需要时生成 | 已有工程接入 Expo继续提交,直接修改 |
| 对比项配置源头 | 裸 React Nativeandroid 与 ios 中的工程文件 |
Expo(持续原生生成)应用配置、依赖和配置插件 | 已有工程接入 Expo已提交的原生目录 |
| 对比项本地编译命令 | 裸 React Native社区 CLI 自带的运行命令 | Expo(持续原生生成)npx expo run:android、npx expo run:ios |
已有工程接入 Expo接入后使用 Expo CLI 的这两条命令 |
| 对比项EAS Build | 裸 React Native可以使用 | Expo(持续原生生成)可以使用 | 已有工程接入 Expo可以使用 |
开发流程概览把下面三条初始化命令视为大体相同的起点。三者执行完,工程里都会有原生目录:
npx create-expo-app@latest MyApp && cd MyApp && npx expo prebuild
npx create-expo-app --template bare-minimum
npx @react-native-community/cli@latest init MyApp && cd MyApp && npx install-expo-modules
差别出现在初始化之后:是继续用应用配置生成原生目录,还是把生成结果留下、以后手工修改。
裸 React Native
裸 React Native 指用社区 CLI 创建、并把 android 与 ios 当作源码维护的工程。原生权限、启动画面、Bundle ID 和应用 ID 写在这两份目录里。Xcode、Android Studio、Gradle 和 CocoaPods 的升级也由仓库自己承接。
这里还没有 Expo CLI。本地编译使用社区 CLI 提供的运行命令。要使用 Expo SDK、Expo CLI 或配置插件,先进入下面的接入步骤。EAS Build 本身可以在这一步之前使用。EAS Build 简介
Expo 与持续原生生成
npx create-expo-app 创建的默认工程里看不到 android 和 ios。这两份目录写在 .gitignore 中,地位类似 node_modules:应用配置和 package.json 是源头,目录是生成物。
生成命令是 npx expo prebuild。它按当前 Expo SDK 的模板创建原生工程,再把应用配置和配置插件应用到工程上。增加带原生代码的依赖、修改会影响原生工程的应用配置,或升级 SDK 时,在持续原生生成的工程里运行:
npx expo prebuild --clean
--clean 会先删除已有的 android 与 ios,再重新生成。因此这两份目录应保持不被提交。直接改过其中的文件之后,再运行预构建会覆盖那些修改。持续原生生成
配置插件用来表达权限、系统授权(entitlement)、原生入口文件和第三方 SDK 需要的工程修改。插件随预构建重新执行,所以升级 React Native 时不必手工合并整个原生工程。
在已有工程中接入 Expo
已有 React Native 工程可以保留自己的原生目录,再安装 Expo。入口是:
npx install-expo-modules@latest
安装之后可以使用 Expo SDK、Expo CLI、开发客户端(expo-dev-client)和 EAS。原生目录仍然提交,修改仍然直接落在 Xcode 和 Gradle 工程里。npx expo run:android 与 npx expo run:ios 发现目录已经存在时,会跳过预构建,直接编译现有工程。在已有工程中安装 Expo 模块
这种工程再运行 npx expo prebuild --clean,会删掉现有原生目录并按模板重新生成,手工修改随之丢失。目录已经承载业务相关的原生改动时,把改动留在目录里,或逐步收成配置插件之后再改回持续原生生成。
先分开的几个名字
后面的三种构建,都是在编译你自己的原生工程。下面几个名字经常和它们叠在一起。
Expo Go 是一个预装了固定原生模块的客户端,适合学习。 准备安装任意原生库或提交商店时,使用包含开发客户端的调试包。开发构建(development build)就是安装了 expo-dev-client 的调试包,里面带有 Expo Go 风格的开发工具界面。开发构建简介
npx expo start 只启动 Metro,用来向已经装好的应用提供 JavaScript 和 TypeScript。它不编译 android 或 ios。界面和业务逻辑的日常修改停在这条命令;原生依赖、应用配置和 SDK 版本变了,才需要重新编译。
EAS 也分成几项服务。本文讨论的是 EAS Build。EAS Submit 负责把安装包提交到商店,EAS Update 负责向已安装的应用下发 JavaScript 更新。三件事可以分开使用。
三种构建方式
三种方式编译的是同一类原生工程。 差别在于编译发生在哪台机器、产物交给谁,以及是否读取 eas.json。
| 对比项 | Expo 本地构建 | EAS 本地构建 | EAS 云构建 |
|---|---|---|---|
| 对比项命令 | Expo 本地构建npx expo run:android、npx expo run:ios |
EAS 本地构建eas build --platform android --local 或把平台换成 ios |
EAS 云构建eas build --platform android、ios 或 all |
| 对比项编译位置 | Expo 本地构建开发者自己的电脑 | EAS 本地构建自己的电脑或自有基础设施,步骤与云构建相同 | EAS 云构建EAS 的构建机。Android 使用 Linux,iOS 使用 macOS |
| 对比项直接产物 | Expo 本地构建Android 生成调试 APK 并安装;iOS 生成 .app,不生成 IPA。Release 变体未按商店签名 |
EAS 本地构建按 eas.json 留在本机:Android 为 APK 或 AAB,iOS 为 IPA |
EAS 云构建同一类文件,并可以生成分享链接 |
| 对比项本机工具 | Expo 本地构建Android 需要 Android SDK;iOS 需要 Mac 上的 Xcode | EAS 本地构建另需 EAS CLI 和 Expo 账号。iOS 还需要 fastlane 与 CocoaPods;Android 还需要 NDK | EAS 云构建不需要本机安装 Xcode 或 Android Studio |
| 对比项登录 EAS | Expo 本地构建不需要 | EAS 本地构建需要 eas login 或 EXPO_TOKEN |
EAS 云构建需要 |
| 对比项常见用途 | Expo 本地构建修改原生代码后立刻在本机调试 | EAS 本地构建复现云构建失败,或要求编译留在自有环境 | EAS 云构建交给测试人员、打上架包、统一环境和签名凭据 |
Expo 本地构建
Expo 本地构建对应文档中的本地调试编译。在已安装 expo 包的工程里运行:
npx expo run:android
npx expo run:ios
每条命令做两件事:用本机的 Android SDK 或 Xcode 编译并安装调试包,然后启动 Metro。原生目录还不存在时,命令会先为对应平台执行一次 npx expo prebuild;目录已经存在时跳过这一步。真机可以追加 --device。本地调试构建
标准工程里,Android 调试 APK 写在 android/app/build/outputs/apk/debug/。iOS 产物是 .app,不是 IPA。模拟器构建可以用下面的命令把包拷到指定目录,得到 MyApp.app:
npx expo run:ios --device generic --output ./build
第一次安装完成之后,只改 JavaScript 或 TypeScript 时运行 npx expo start,再在终端按 a 或 i 打开已经装好的应用。安装 expo-dev-client 之后,这个调试包就带有开发客户端界面,也就是一份开发构建。
这两条命令也可以生成发布包:
npx expo run:android --variant release
npx expo run:ios --configuration Release
这样得到的发布包没有按商店要求签名,不能直接提交。它们也不生成 IPA;Android 这边得到的是 Release APK,不是 Play 商店要的已签名 AAB。Android 从 SDK 54 起还可以用 --variant debugOptimized 缩短调试编译时间。
EAS 本地构建
EAS 本地构建在自己的机器上执行云构建的同一套步骤:
eas build --platform android --local
eas build --platform ios --local
它适合两件事。一是云构建失败而日志不够定位,需要在本机保留中间文件。二是公司政策要求源码编译留在自有环境。编译过程中与 EAS 服务器的通信限于确认 @account/slug 项目存在;使用托管签名凭据时,还会下载这些凭据。在本地运行 EAS Build
本地构建有一组明确限制:
- 一次只能构建一个平台,
--platform all不可用。 eas.json里的node、yarn、fastlane、cocoapods、ndk和image会被忽略,实际使用本机安装的版本。因此它能复现构建步骤,不保证与云端镜像的工具版本一致。- 不支持 EAS 构建缓存。
- 可见性为 Secret 的 EAS 环境变量不可用,需要写进本机环境。
- 官方支持 macOS 和 Linux。Windows 不在官方支持范围内;WSL 可以尝试,但文档说明官方未对此测试。
- 工具由自己安装:Node.js 与包管理器、Android SDK 与 NDK、以及 iOS 所需的 fastlane 和 CocoaPods。iOS 编译仍要使用 Mac 上的 Xcode。
调试云构建失败时,可以让本机保留工作目录,并把产物放到指定位置:
export EAS_LOCAL_BUILD_SKIP_CLEANUP=1
export EAS_LOCAL_BUILD_WORKINGDIR=/tmp/my-app-build
export EAS_LOCAL_BUILD_ARTIFACTS_DIR=/tmp/my-app-artifacts
eas build --platform ios --local
iOS 构建保留工作目录后,Xcode 日志在该目录的 logs 子目录中。
EAS 云构建
EAS 云构建把项目交给 EAS 的构建机:
eas build --platform all
Android 构建运行在 Google Cloud 的 Linux 构建机上,每次使用新的容器。iOS 构建运行在 Expo 的 macOS 构建机上,每次使用新的虚拟机。本机可以不安装 Xcode 和 Android Studio。首次配置时运行 eas build:configure,它会创建 eas.json。Expo 工程里的默认内容是:
{
"build": {
"development": {
"developmentClient": true,
"distribution": "internal"
},
"preview": {
"distribution": "internal"
},
"production": {}
}
}
已有 React Native 工程生成的文件会略有差别。三个名字的分工是:development 打包含开发客户端的内部分发包,preview 打给测试人员安装的内部分发包,production 打商店包。指定配置时加上 --profile,例如 eas build --platform android --profile development。用 eas.json 配置构建
Android 的 production 默认产出 Android App Bundle(.aab)。.aab 用于提交 Google Play,不能直接装到设备或模拟器上。distribution 设为 internal、developmentClient 设为 true,或把 android.buildType 设为 apk 时,Android 构建改为产出可以直接安装的 APK。iOS 内部分发使用 ad hoc 描述文件,设备需要先登记;要装进 iOS 模拟器,还要在配置里把 ios.simulator 设为 true。内部分发
签名凭据可以由 EAS 生成并保管,也可以换成自己提供的 keystore、证书和描述文件。构建成功后可以继续用 EAS Submit 提交商店。
云构建和本地构建对原生目录使用同一条规则。上传内容里没有 android 和 ios 时,构建机先运行 npx expo prebuild,再编译。目录已经包含在上传内容中时,构建机跳过预构建,直接编译上传的工程,避免覆盖其中的修改。持续原生生成的默认工程把这两份目录放进 .gitignore,因此云构建看到的是由应用配置重新生成的工程,不是某台电脑上未提交的本地目录。Android 构建过程、iOS 构建过程
按场景选择
日常改界面和业务逻辑
调试包已经安装在模拟器或真机上时,运行 npx expo start。Metro 会把新的 JavaScript 送进现有安装包。这一步不区分安装包最初来自 Expo 本地构建还是 EAS。
改了原生依赖或应用配置
新增带原生代码的库、修改应用配置中影响原生工程的字段、修改配置插件或升级 SDK 之后,需要重新编译。
持续原生生成的工程先执行 npx expo prebuild --clean,再运行 npx expo run:android 或 npx expo run:ios。没有 Mac 或不想在本机安装 Android Studio 时,用 EAS 云构建的 development 配置产出新的开发构建。
原生目录已经提交、并且里面有手工修改时,直接修改那些文件,然后重新编译。此时不再运行 npx expo prebuild --clean。
把包交给别人安装
使用 EAS 云构建。测试人员安装现成包时用 preview;对方还要连接 Metro 调试时用 development。Android 内部分发得到 APK。iOS 内部分发得到 ad hoc 包,只能安装到已经登记的设备;模拟器包要单独开 ios.simulator。
提交应用商店
常规路径是 eas build --platform all --profile production,再使用 EAS Submit。Google Play 接收已签名的 .aab,Android 这里应保持默认的 AAB。iOS 的 production 配置产出 IPA。
也可以在本机用 Gradle 和 Xcode 制作已签名的上架包。这是另一条发布流程,命令不是 npx expo run,也不是 eas build --local。使用持续原生生成时,先运行 npx expo prebuild 得到原生目录。Android 在配置上传密钥后,于 android 目录执行 ./gradlew app:bundleRelease。产物路径是:
android/app/build/outputs/bundle/release/app-release.aab
已经在 EAS 生成过上传密钥时,用 eas credentials -p android 下载原有凭据,避免再生成一把新密钥。得到的 .aab 可以用下面的命令提交:
eas submit --platform android --path ./my-app.aab
同一套签名配置下,./gradlew app:assembleRelease 会在 android/app/build/outputs/apk/release/ 生成 APK。这个 APK 用于直接安装,不能代替提交 Google Play 的 AAB。
iOS 在 Xcode 中签名并执行 Product > Archive。分发时选择 Export 会留下 .ipa;选择 App Store Connect 则直接上传。npx expo run:ios --configuration Release 不能代替这一步。已有 IPA 可以执行:
eas submit --platform ios --path ./my-app.ipa
云构建失败,或编译必须留在内网
云端日志不足以说明失败原因时,在本机执行同一配置的 eas build --platform <平台> --local,并保留工作目录查看原生日志。由于本机会忽略 eas.json 中的工具版本和镜像字段,本地结果与云端不一致时,要同时比较两边的 Node、CocoaPods、NDK 和 Xcode 版本。
政策要求源码不能上传到第三方构建服务时,同样使用 --local。编译留在自有机器上;账号校验和托管凭据下载仍然会访问 EAS。
打开仓库时先看的三件事
android和ios有没有提交。已提交时,Expo 本地构建和 EAS 构建都会编译这份目录,预构建不会重新生成它。未提交时,缺少目录的那一次构建会先执行npx expo prebuild;本机未提交的原生修改不会进入云构建。package.json里有没有expo。有,才使用npx expo run:android和npx expo run:ios。没有,本地编译仍走社区 CLI;EAS Build 可以直接配置这个工程。eas.json里这次要用的配置叫什么。developmentClient决定包里有没有开发客户端,distribution和android.buildType决定 Android 产物是可直接安装的 APK,还是提交商店的 AAB。
命令、eas.json 字段和签名规则以 Expo 文档的当前页面为准。本文核对日期是 2026-10-08。