中文网
🌐 Nodejs.cn
首页指南EAS参考教程

使用 Expo 开发应用

概述构建 Expo 应用的开发过程，以帮助构建核心开发循环的思维模型。

无论你是刚接触 Expo 和 React Native，还是已经在这个生态系统中有一段时间了，这份文档都能帮助你更好地理解构建 Expo 应用的开发过程。它将帮助你建立对核心开发循环的整体认知，以及 Expo 工具在其中的作用。

🌐 If you're new to Expo and React Native or you've been around the ecosystem for a while, this document will be useful to help you to better understand the development process of building an Expo app. It will help you build a mental model of the core development loop and how Expo tools fit into it.

关键概念

🌐 Key concepts

以下概念对于理解很有价值，我们建议你在阅读本指南的其余部分以及使用 Expo 工具时回顾这些定义。

🌐 The following concepts are valuable to understand, and we recommend referring back to these definitions as you read through the rest of this guide and also as you use Expo tools.

What is an "Expo app"?

这是我们用来描述一个使用 Expo 工具的 React Native 应用 的简写术语。一个 “Expo 应用” 可以使用 Expo SDK 的单个包，或者使用 Expo Router，或者使用 Expo CLI，或者使用连续原生生成（Continuous Native Generation），也可以是它们的组合，或者使用任何其他 Expo 工具。

🌐 This is a shorthand term we use for describing a React Native app that uses Expo tools. An "Expo app" can use a single package from the Expo SDK, or Expo Router, or Expo CLI, or Continuous Native Generation, a combination of them, or any other Expo tools.

我们说“Expo 应用”，因为“使用 Expo 工具的 React Native 应用”说出来或经常输入太不方便了。

🌐 We say "Expo app" because React Native app that uses Expo tools is incredibly inconvenient to frequently type and speak out loud.

“Expo 应用”和“不使用 Expo 工具的 React Native 应用”的开发流程是否不同？

Expo 提供了多种可以独立使用的工具和服务，因此答案取决于你选择使用哪些工具。对于 Expo 提供的大多数功能，Meta 提供的 React Native 工具没有可比性。

🌐 Expo provides a variety of tools and services that can be adopted independently, so the answer depends on which tools you choose to use. For most of what Expo provides, there is no React Native tooling provided by Meta that is comparable.

What is the difference between "Expo" and "Expo Application Services (EAS)"?

Expo 是一个开源项目，为开发者提供强大的工具，帮助构建和维护任意规模的 React Native 应用。例如，Expo CLI、Expo Router 和 Expo SDK 包。所有 Expo 开源工具都是完全免费使用，并且采用 MIT 许可证。

🌐 Expo is an open-source project that gives developers powerful tools to assist in building and maintaining React Native apps at any scale. For example, Expo CLI, Expo Router, and Expo SDK packages. All Expo open-source tools are entirely free to use and carry the MIT license.

Expo 应用服务 (EAS) 是一套托管服务，你可以在 Expo 和 React Native 项目中使用这些服务来：

🌐 Expo Application Services (EAS) is a suite of hosted services that you can use with Expo and React Native projects to:

  • 构建、提交并更新你的应用
  • 为所有这些流程建立自动化
  • 与你的团队合作

EAS 解决了一系列需要物理资源的问题，例如用于空中更新的应用服务器和 CDN，以及用于运行构建的物理服务器。EAS 提供了一个非常慷慨的免费计划，适合许多学生和爱好者项目使用。

🌐 EAS solves a set of problems that require physical resources, such as application servers and CDNs for serving over-the-air updates and physical servers for running builds. EAS has a generous free plan that will work for many student and hobby projects.

你不必使用 GitHub 就能使用 git，但在很多情况下它确实很有帮助。EAS 和 Expo 也是同样的道理。

🌐 You don't have to use GitHub to use git, but it certainly helps for many cases. The same goes for EAS and Expo.

如果我使用 Expo 开源工具，必须使用 EAS 吗？

不！你的 Expo 项目其实就是一个 React Native 应用，而 React Native 应用就是一个原生应用。你可以使用 Fastlane 或者任何你喜欢的原生构建、更新等工具。

🌐 Nope! Your Expo project is just a React Native app, which is just a native app. You can use Fastlane or any native build, update, and more, tools you like.

大多数 EAS 服务也允许你在自己的基础设施上运行，我们提供了如何实现这一点的说明。例如，自托管更新（而不是使用 EAS 更新），或在本地运行构建 或在你自己的 CI 上运行（而不是使用我们的 EAS 构建工作节点）。

🌐 Most EAS services also allow you to run them on your own infrastructure, and we provide instructions for how you can accomplish this. For example, self-hosting updates (rather than using EAS Update), or running builds locally or on your own CI (rather than using our EAS Build worker fleet).

对于大多数团队来说，使用 EAS 比花费工程时间和资源去获取、设置以及维护其他基础设施上的服务更为合理。此外，EAS 提供了服务之间的深度集成，例如用于监控应用版本采用情况的部署页面、将更新分配到特定构建以及逐步推出这些更新——这又与使用 EAS Insights 进行监控相关联。

🌐 For most teams, it makes sense to use EAS rather than spending the engineering time and resources on acquiring, setting up, and maintaining the services on other infrastructure. Additionally, EAS provides deep integration between services, such as the deployments page for monitoring app version adoption, assigning updates to specific builds, and rolling those updates out incrementally — which ties back into monitoring with EAS Insights.

如果我没有使用任何 Expo 开源工具，我可以使用 EAS 吗？

是的！我们认为 EAS 非常适合任何 React Native 项目。

🌐 Yes! We think EAS is a great fit for any React Native project.

Expo Go：学生和学习者的乐园

Expo Go 是开始使用 React Native 的最快方式，特别是与 Snack 结合使用时。它非常适合学生和初学者理解基础知识。

然而，Expo Go 是一个有限的试玩环境，对于构建生产级项目并不实用。如果你计划将应用发布到商店，则 开发构建 将提供更灵活、可靠且完整的开发环境。本指南不会详细介绍 Expo Go，这也是唯一提到它的部分。

🌐 However, Expo Go is a limited playground and not useful for building production-grade projects. If you plan on deploying your app to the store, then development builds will provide a more flexible, reliable, and complete development environment. This guide does not go into any detail about Expo Go, and this is the only section that mentions it.

开发构建

开发构建是包含 expo-dev-client 库的应用调试构建版本。它可以帮助你尽可能快速地迭代，并提供比 Expo Go 更灵活、可靠且完整的开发环境。你可以安装任何原生库，并使用 应用配置 或创建 配置插件 来配置或应用对 原生项目 的更改。你可以在 本地 创建开发构建，也可以使用 EAS Build 在云端创建构建。

🌐 A development build is a debug build of your app that contains expo-dev-client library. It helps you iterate as quickly as possible and provides a more flexible, reliable, and complete development environment than Expo Go. You can install any native library and configure or apply changes to a native project using app config or by creating a config plugin. You can create a development build locally or use EAS Build to create a build in the cloud.

Android 和 iOS 原生项目

移动平台的 React Native 应用由两个相互关联的部分组成：

🌐 React Native apps for mobile platforms are made of two interconnected parts:

1. 应用 JavaScript

这里包含了你的 React 组件以及大部分（如果不是全部的话）应用逻辑。它的作用或多或少与 React 网站上的 app JavaScript 相同。

🌐 This contains your React components and most, if not all, of your application logic. It has more or less the same role as the app JavaScript on React websites.

2. 本地项目

打包 JavaScript 应用的 Android 和 Xcode 项目，作为每个平台上 JavaScript 应用的启动平台。它们还负责原生组件的渲染，并提供访问特定平台功能和集成任何已安装原生库的方式。应用配置，例如名称（在主屏幕上显示的名称）、图标、所需权限、相关域、支持的屏幕方向等，都在原生项目中进行配置。

🌐 Android and Xcode projects that bundle the JavaScript app, serve as the launchpad for the JavaScript app on each platform. They also handle the rendering of native components and provide the means to access platform-specific functionalities and integrate with any installed native libraries. App configuration, such as the name (as it appears on the home screen), icon, required permissions, associated domains, supported orientations, and so on, is configured in the native project.

和任何移动应用一样，分发给用户的应用都是通过编译（“构建”）Android Studio 或 Xcode 项目创建的。

🌐 Like any mobile app, the application that is distributed to users is created by compiling ("building") the Android Studio or Xcode project.

当你使用 npx create-expo-app 初始化一个新应用时，你不会看到任何 android 或 ios 目录。你可以通过 运行 npx expo prebuild 来生成原生项目，这将初始化原生项目，然后将项目的 Expo 应用配置（app.json/app.config.js）应用到它们上面。

🌐 When you initialize a new app with npx create-expo-app, you will not see any android or ios directories. You can generate the native projects by running npx expo prebuild, which will initialize the native projects and then apply the project Expo app config (app.json/app.config.js) to them.

如果你使用基于云的开发工作流程，你可能永远不需要在自己的机器上运行预构建或安装 Android Studio 或 Xcode（尽管你可能会觉得这样做很有用）。下面在 本地和基于云的开发工作流程 中对此进行了说明。

🌐 If you use a cloud-based development workflow, you may never need to run prebuild or install Android Studio or Xcode on your own machine (although you may find this useful). This is explained below in the Local and cloud-based development workflows.

Why aren't the native projects created by default when you initialize a project with create-expo-app?

默认行为鼓励在需要时使用连续原生生成（CNG）来生成原生项目，这可以显著简化升级和项目维护。以下三个命令生成的项目或多或少是相同的：

🌐 The default behavior encourages the use of Continuous Native Generation (CNG) to generate the native projects when needed, which can make upgrades and project maintenance significantly easier. The following three commands result in more or less the same project:

Terminal
- npx create-expo-app 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
持续的原生生成 (CNG)

连续原生生成（CNG）是一种构建 Expo 应用的流程，其中你的原生项目会根据你的 app.json 和 package.json 按需生成，类似于你的 node_modules 是根据 package.json 生成的方式。

🌐 Continuous Native Generation (CNG) is a process for building an Expo app where your native projects are generated on-demand from your app.json and package.json, similar to how your node_modules are generated from your package.json.

当你创建一个新项目时，native project 目录（android 和 ios）会自动添加到你的 .gitignore 中，你可以随时删除它们，然后根据需要使用 npx expo prebuild 从 Expo 应用配置重新生成它们。如果你使用基于云的开发工作流，你甚至可能从不在自己的开发机器上运行 prebuild。

🌐 The native project directories (android and ios) are automatically added to your .gitignore when you create a new project, and you can delete them at any time, then re-generate them from the Expo app config with npx expo prebuild whenever required. You might never even run prebuild on your own development machine if you use a cloud-based development workflow.

使用 CNG 可以使升级到新的 React Native 版本变得更加容易。它可以简化项目维护，并有助于设置诸如 App Clips、分享扩展 和 错误报告 等复杂功能。这一切都得益于 配置插件。了解更多关于 CNG 的信息。

🌐 Using CNG can make upgrading to new versions of React Native much easier. It can simplify project maintenance and facilitate setting up complex features such as App Clips, share extensions, and error reporting. This is all made possible with config plugins. Learn more about CNG.

如果我想在 Android Studio 或 Xcode 中编辑原生项目配置，而不是使用预构建生成项目，该怎么办？

CNG 已被证明对许多团队有帮助。然而，它可能并不适合你的项目，而在许多情况下以这种方式使用 Expo 工具也是完全合理的。

🌐 CNG has proven to be helpful to many teams. However, it may not be the best fit for your project and this is a perfectly reasonable way to use Expo tools in many cases.

你可以在项目中运行 npx expo prebuild，然后直接对 android 和 ios 目录进行修改，而无需使用 Expo 应用配置。如果你决定这样做，请记住你将无法再使用 prebuild 重新生成项目 —— 在直接进行本地修改后再次运行 prebuild 将会覆盖所有这些修改。

🌐 You can run npx expo prebuild in the project and then make changes directly to the android and ios directories, instead of using Expo app config. If you decide to do this, then keep in mind that you won't be able to re-generate your projects using prebuild any longer — running prebuild after making native changes directly will overwrite all of those modifications.

请注意，你可以使用 config plugins 修改原生项目配置，而无需直接修改原生项目，如果你决定在某个时候切换回 CNG。

🌐 Note that you can use config plugins to modify the native project configuration without having to modify the native projects directly, and if you decide to move back to CNG at some point.

我怎么知道什么时候需要再次运行预构建？

如果你在项目中添加了新的原生依赖或更改了 Expo 应用配置（app.json/app.config.js），你可以运行 npx expo prebuild --clean 来重新生成原生项目目录。

🌐 If you add a new native dependency to your project or change the project configuration in Expo app config (app.json/app.config.js), you can run npx expo prebuild --clean to re-generate the native project directories.

有关如何确定新依赖是否需要本地代码更改的更多信息，请参阅 确定第三方库兼容性。

🌐 See Determining third-party library compatibility for more information on how to determine if a new dependency requires native code changes.

基于云和本地的开发工作流程

无论你选择基于云还是本地，这对你的开发循环影响不大。关键在于你如何生成和分发你的应用二进制文件，这些二进制文件是你的 JavaScript 代码运行的对象。每次进行新的原生构建时，你都可以选择使用云端还是本地开发环境。

🌐 Whether you choose cloud-based or local doesn't significantly alter your development loop. It's about how you produce and distribute your app binaries that your JavaScript code runs against. Choosing a cloud-based or local development is a choice you can make each time you run a new native build.

使用 EAS Build 在云端编译你的应用就像运行一个命令一样简单，无需安装 Android Studio 或 Xcode。云端构建让与其他团队成员或利益相关者分享你的应用变得更容易，以及其他好处。

🌐 Compiling your app in the cloud with EAS Build is as easy as running a single command, no need to install Android Studio or Xcode. Cloud builds make it easier to share your app with other teammates or stakeholders, among other benefits.

要在本地编译你的应用，你需要在你的电脑上安装 Android Studio 和 Xcode，然后你可以通过这些工具运行构建，或者使用 npx expo run:[android|ios]。当你想在物理设备或模拟器/模拟器上使用原生调试工具调试应用时，这最为有用。

🌐 To compile your app locally, you will need to install Android Studio and Xcode on your machine, and then you can either run the build from those tools or use npx expo run:[android|ios]. This is most useful when you want to debug your app on a physical device or emulator/simulator using the native debugging tools.

了解更多关于 使用 EAS Build 的云端工作流程 和 本地开发 的信息。

🌐 Learn more about cloud-based workflows with EAS Build and local development.

初始化并运行项目

🌐 Initialize and run a project

创建新项目最简单的方法是 create-expo-app。创建项目后，你可以立即在真实设备上的 Expo Go 中启动它，或者如果你想进行实验或快速构建原型，也可以在模拟器/模拟器中启动。

🌐 The easiest way to create a new project is with create-expo-app. After creating your project, you can immediately launch it directly in Expo Go on your physical device or in an emulator/simulator if you want to experiment or build a quick prototype.

在大多数情况下，你将创建并使用项目的开发版本。你将安装 expo-dev-client 库。开发版本可以通过 EAS Build 创建，也可以在你的本地机器上创建：

🌐 In most cases, you will create and use a development build of your project. You will install the expo-dev-client library. Development builds can be created with EAS Build or locally on your machine:

使用 EAS 创建开发构建

学习如何使用 EAS 为你的项目创建开发版本。
在本地创建开发构建

了解如何使用自己的电脑、Android Studio 和 Xcode 在本地编译你的应用。

核心开发循环

🌐 The core development loop

Core development loop diagram

上图所示的核心开发循环是一个包含四个主要活动的周期，你在开发应用时通常会经历这些活动。

🌐 The core development loop described in the diagram above is a cycle of four main activities that you typically go through when developing an app.

  • 编写并运行 JavaScript 代码

    这涉及创建组件、编写业务逻辑或安装不需要本地代码更改的 npm 库。你在这里所做的更改会直接反映在你的应用中，无需与应用的本地部分进行任何交互。

  • 更新应用配置

    这涉及使用应用配置文件（app.json 或 app.config.js）修改你的应用配置。它包括更新应用的名称、图标、启动画面和其他属性。这些更改并不全都会直接影响原生项目。但如果你做了会影响原生项目的更改，你可以使用 app config 来修改原生项目配置，或者创建或使用 config plugin。有关 app 配置文件中可用属性的完整列表，请参见 app config reference。

  • 编写原生代码或修改原生项目配置

    这包括直接编写原生代码或修改原生代码配置。你需要访问原生代码项目目录以进行这些更改，或者可以使用本地 Expo 模块编写原生代码。

  • 安装需要本地代码修改的库

    这包括库需要对原生代码项目配置进行更改。要么库提供配置插件，要么提供用于更新应用配置的步骤。像之前的活动一样，这也需要你创建一个开发构建。

在创建开发构建时，你有两个选项。你可以使用EAS Build创建基于云的构建，也可以在本地进行。如果选择在本地进行，可以使用CNG然后使用npx expo prebuild --clean，或者你可以使用npx expo run android|ios或 Android Studio 和 Xcode创建开发构建。

🌐 When creating a development build, you have two options. You can create a cloud-based build using EAS Build or do it locally. If you choose to do it locally, you can use CNG and then npx expo prebuild --clean, or you can create a development build using npx expo run android|ios or Android Studio and Xcode.

注意：在本地创建开发构建时，npx expo run 命令将在构建应用之前生成本地目录。如果在第一次构建后修改了项目的配置或本地代码，则必须重新构建项目。再次运行 npx expo prebuild 会在现有文件的基础上叠加更改。构建后可能还会产生不同的结果。为避免这种情况，请将本地目录添加到项目的 .gitignore 中，并使用 npx expo prebuild --clean 命令。

在应用开发循环中，你还可以在同一设备上安装应用的不同版本（开发版、预览版或生产版）。

🌐 During your app's development loop, you can also install different variants (development, preview or production) of your app on the same device.

开发循环的另一个关键部分是调试。有关调试应用的更多信息，请参阅 调试运行时问题，并了解可用的不同 调试工具。

🌐 Another key part of the development loop is debugging. See Debugging runtime issues for more information about debugging your app and learn about different debugging tools available.

与测试器共享应用

🌐 Share app with testers

开发应用的下一步是与团队、测试人员分享你的应用，或者在多个测试设备上运行它。传统的方法是将应用的二进制文件上传到 Google Play Beta（安卓）或 TestFlight（iOS）。这可能是一项耗时的工作，而且一次只能发布一个活动版本（例如，在 TestFlight 的情况下）。

🌐 The next step to developing an app is to share your app with your team, with beta testers, or run it on multiple test devices. A traditional approach is to upload your app's binary to the Google Play Beta (Android) or TestFlight (iOS). This can be a time-consuming effort and is limited to only one active build at a time (for example, in the case of TestFlight).

如果你正在使用 EAS Build，我们建议通过内部分发了解更多关于共享你的应用进行测试的信息。

🌐 If you are using EAS Build, we recommend going through Internal distribution to learn more about sharing your app for testing.

如果你在本地编译应用，可以在本地创建生产版本。

🌐 If you compile your app locally, you can create production builds locally.

向商店发布应用

🌐 Release app to stores

要在应用商店发布你的应用，你可以使用 EAS 提交。有关使用 EAS 提交的更多信息，请参阅 提交到 Google Play 商店 和 提交到 Apple App Store。

🌐 To release your app on the app stores, you can use EAS Submit. For more information on using EAS Submit, see Submit to Google Play Store and Submit to Apple App Store.

要在本地创建生产版本，请参阅关于此的指南，然后按照应用商店的指南提交你的应用。

🌐 To create a production build locally, see the guide on the same and then go through the app stores guide to submit your app.

监控生产中的应用

🌐 Monitor app in production

监控生产应用的两种方法是崩溃报告和分析。崩溃报告可以帮助你了解用户在使用应用时遇到的异常或错误。你可以使用 Sentry 或 BugSnag 来启用崩溃报告。

🌐 Two ways to monitor your production app are crash reports and analytics. Crash reports help you learn about exceptions or errors that your users run into while using your app. You can use Sentry or BugSnag to enable crash reports.

分析功能可以让你跟踪用户如何与你的应用交互。查看 分析概览 以了解有关 Expo 和 React Native 生态系统中可用服务的更多信息。

🌐 Analytics allows you to track how users interact with your app. See analytics overview to learn more about the services available in the Expo and React Native ecosystem.

更新应用

🌐 Update the app

expo-updates 库允许你以编程方式将即时更新推送到你的应用 JavaScript，使其可在生产应用中使用。

🌐 The expo-updates library allows you to programmatically make instant updates to your app's JavaScript available to your production app.

你可以使用 EAS 更新，它为 React Native 应用提供一流的即时更新支持。它通过全球 CDN 的边缘节点提供更新，并为支持的客户端使用现代网络协议，如 HTTP/3。它也专为使用 EAS Build 的开发者量身打造 开发者。你也可以将其用于你 本地 创建的构建。

🌐 You can use EAS Update which provides first-class support for instant updates in a React Native app. It serves updates from the edge of a global CDN and uses modern networking protocols such as HTTP/3 for clients that support them. It is also tailored for developers who use EAS Build. You can also use it for builds you have created locally.