# Expo Documentation

Expo is an open-source React Native framework for apps that run natively on Android, iOS, and the web. Expo brings together the best of mobile and the web and enables many important features for building and scaling an app such as live updates, instantly sharing your app, and web support. The company behind Expo also offers Expo Application Services (EAS), which are deeply integrated cloud services for Expo and React Native apps.

# 开始使用

## 介绍

开始使用 Expo 创建应用。

Expo 是一个使开发 Android 和 iOS 应用更容易的框架。我们的框架提供基于文件的路由、标准的原生模块库等等。Expo 是开源的，在 [GitHub](https://github.com/expo/expo) 和 [Discord](https://chat.expo.dev) 上有一个活跃的社区。
¥Expo is a framework that makes developing Android and iOS apps easier. Our framework provides file-based routing, a standard library of native modules, and much more. Expo is open source with an active community on [GitHub](https://github.com/expo/expo) and [Discord](https://chat.expo.dev).
我们还制作了 [Expo 应用服务（EAS）](https://expo.dev/eas)，这是一组在开发过程的每个步骤中补充 Expo 框架的服务。
¥We also make [Expo Application Services (EAS)](https://expo.dev/eas), a set of services that complement the Expo framework in each step of the development process.
要开始使用，请访问：
¥To get started visit:


## 创建项目

了解如何创建新的 Expo 项目。

系统要求：
¥System requirements:
* [Node.js (LTS)](https://nodejs.cn/)。
* 支持 macOS、Windows（Powershell 和 [WSL 2](https://expo.fyi/wsl)）和 Linux。
  ¥macOS, Windows (Powershell and [WSL 2](https://expo.fyi/wsl)), and Linux are supported.
我们建议从 `create-expo-app` 创建的默认项目开始。默认项目包含示例代码以帮助你入门。
¥We recommend starting with the default project created by `create-expo-app`. The default project includes example code to help you get started.
要创建新项目，请运行以下命令：
¥To create a new project, run the following command:
```sh
$ npx create-expo-app@latest
```
> 你可以通过添加 [`--template` 选项](/more/create-expo/#--template) 来选择不同的模板。
>
> ¥You can choose a different template by adding the [`--template` option](/more/create-expo/#--template).
<a id="next-step"></a>
## 下一步
¥Next step
你有一个项目。现在是时候设置你的开发环境，以便你可以开始开发了。
¥You have a project. Now it's time to set up your development environment so that you can start developing.


## 设置你的环境

了解如何设置开发环境以开始使用 Expo 进行构建。

让我们设置一个本地开发环境以在 Android 和 iOS 上运行你的项目。
¥Let's set up a local development environment for running your project on Android and iOS.
<a id="where-would-you-like-to-develop"></a>
## 你想在哪里开发？
¥Where would you like to develop?
我们建议使用真实设备进行开发，因为你将能够准确地看到用户将看到的内容。
¥We recommend using a real device to develop, since you'll get to see exactly what your users will see.
<a id="how-would-you-like-to-develop"></a>
## 你想如何开发？
¥How would you like to develop?
Expo Go 是一个用于快速试用 Expo 的沙盒。开发版本是你自己的应用的版本，其中包括 Expo 的开发者工具。
¥Expo Go is a sandbox for trying out Expo quickly. A development build is a build of your own app that includes Expo's developer tools.
***
# Android Emulator Setup

## Set up an emulator
Step 1: 
On the Android Studio main screen, click **More Actions**, then **Virtual Device Manager** in the dropdown.
Step 2: 
Click the **Create device** button.
Step 3: 
Under **Select Hardware**, choose the type of hardware you'd like to emulate. We recommend testing against a variety of devices, but if you're unsure where to start, the newest device in the Pixel line could be a good choice.
Step 4: 
Select an OS version to load on the emulator (probably one of the system images in the **Recommended** tab), and download the image.
Step 5: 
Change any other settings you'd like, and press **Finish** to create the emulator. You can now run this emulator anytime by pressing the Play button in the AVD Manager window.


# Android Studio Environment Setup

## Install Watchman and JDK
<Tab label='macOS'>
#### Prerequisites
Use a package manager such as [Homebrew](https://brew.sh/) to install the following dependency.
#### Install dependencies
Step 1: 
[Install Watchman](https://facebook.github.io/watchman/docs/install#macos) using a tool such as Homebrew:
```sh
$ brew install watchman
```
Step 2: 
Install OpenJDK distribution called Azul Zulu using Homebrew. This distribution offers JDKs for both Apple Silicon and Intel Macs.
Run the following commands in a terminal:
```sh
$ brew install --cask zulu@17
```
After you install the JDK, add the `JAVA_HOME` environment variable in **~/.bash_profile** (or **~/.zshrc** if you use Zsh):
```bash
export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
```
<Tab label='Windows'>
#### Prerequisites
Use a package manager such as [Chocolatey](https://chocolatey.org/) to install the following dependencies.
#### Install dependencies
Install [Java SE Development Kit (JDK)](https://openjdk.org/):
```sh
$ choco install -y microsoft-openjdk17
```
For Linux: 
#### Install dependencies
Step 1: 
Follow [instructions from the Watchman documentation](https://facebook.github.io/watchman/docs/install#linux) to compile and install it from the source.
Step 2: 
Install [Java SE Development Kit (JDK)](https://openjdk.org/):
You can download and install [OpenJDK@17](http://openjdk.java.net/) from [AdoptOpenJDK](https://adoptopenjdk.net/) or your system packager.


# Android Studio Setup

## Set up Android Studio
For macOS: 
Step 1: 
Download and install [Android Studio](https://developer.android.com/studio).
Step 2: 
Open the **Android Studio** app, click **More Actions** and select **SDK Manager**.
Step 3: 
Open Android Studio, go to **Settings** &gt; **Languages & Frameworks** &gt; **Android SDK**. From the **SDK Platforms** tab, select the latest Android version (API level).
Then, click on the **SDK Tools** tab and make sure you have at least one version of the **Android SDK Build-Tools** and **Android Emulator** installed.
Step 4: 
Copy or remember the path listed in the box that says **Android SDK Location**.
Step 5: 
Click **Apply** and **OK** to install the Android SDK and related build tools.
Step 6: 
If you are on macOS or Linux, add an [environment variable](https://developer.android.com/studio/command-line/variables#envar) pointing to the Android SDK location in **~/.bash_profile** (or **~/.zshrc** if you use Zsh). For example: `export ANDROID_HOME=/your/path/here`.
Add the following lines to your **/.zprofile** or **~/.zshrc** (if you are using bash, then **~/.bash_profile** or **~/.bashrc**) config file:
```sh
$ export ANDROID_HOME=$HOME/Library/Android/sdk
$ export PATH=$PATH:$ANDROID_HOME/emulator
$ export PATH=$PATH:$ANDROID_HOME/platform-tools
```
Step 7: 
Reload the path environment variables in your current shell:
```sh
$ source $HOME/.zshrc
$ source $HOME/.bashrc
```
Step 8: 
Finally, make sure that you can run `adb` from your terminal.
Note: Troubleshooting: Android Studio not recognizing JDK
---
If Android Studio doesn't recognize your homebrew installed JDK, you can create a Gradle configuration file to explicitly set the Java path:
1.  Create a Gradle properties file in your home directory:
    ```sh
$ touch ~/.gradle/gradle.properties
```
2.  Add the following line to the **gradle.properties** file, replacing the path with your actual Java installation path:
    ```bash gradle.properties
    java.home=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
    ```
3.  If you have an existing `.gradle` folder in your project directory, delete it and reopen your project in Android Studio:
    ```sh
$ rm -rf .gradle
```
This should resolve issues with Android Studio not detecting your JDK installation.
---
For Windows: 
Step 1: 
Download [Android Studio](https://developer.android.com/studio).
Step 2: 
Open **Android Studio Setup**. Under **Select components to install**, select Android Studio and Android Virtual Device. Then, click **Next**.
Step 3: 
In the Android Studio Setup Wizard, under **Install Type**, select **Standard** and click **Next**.
Step 4: 
The Android Studio Setup Wizard will ask you to verify the settings, such as the version of Android SDK, platform-tools, and so on. Click **Next** after you have verified.
Step 5: 
In the next window, accept licenses for all available components.
Step 6: 
After the tools installation is complete, configure the `ANDROID_HOME` environment variable. Go to **Windows Control Panel** > **User Accounts** > **User Accounts** (again) > **Change my environment variables** and click **New** to create a new `ANDROID_HOME` user variable. The value of this variable will point to the path to your Android SDK:
Note: How to find installed SDK location?
---
By default, the Android SDK is installed at the following location:
```bash
%LOCALAPPDATA%\Android\Sdk
```
To find the location of the SDK in Android Studio manually, go to **Settings** > **Languages & Frameworks** > **Android SDK**. See the location next to **Android SDK Location**.
---
Step 7: 
To verify that the new environment variable is loaded, open **PowerShell**, and copy and paste the following command:
```sh
$ Get-ChildItem -Path Env: 
```
The command will output all user environment variables. In this list, see if `ANDROID_HOME` has been added.
Step 8: 
To add platform-tools to the Path, go to **Windows Control Panel** > **User Accounts** > **User Accounts** (again) > **Change my environment variables** > **Path** > **Edit** > **New** and add the path to the platform-tools to the list as shown below:
Note: How to find installed platform-tools location
---
By default, the platform-tools are installed at the following location:
```bash
%LOCALAPPDATA%\Android\Sdk\platform-tools
```
---
Step 9: 
Finally, make sure that you can run `adb` from the PowerShell. For example, run the `adb --version` to see which version of the `adb` your system is running.


# Xcode Setup

Step 1: 
### Install Xcode
Open up the Mac App Store, search for [Xcode](https://apps.apple.com/us/app/xcode/id497799835), and click **Install** (or **Update** if you have it already).
Step 2: 
### Install Xcode Command Line Tools
Open Xcode, choose **Settings...** from the Xcode menu (or press <kbd>cmd ⌘</kbd> + <kbd>,</kbd>). Go to the **Locations** and install the tools by selecting the most recent version in the **Command Line Tools** dropdown.
Step 3: 
### Install an iOS Simulator in Xcode
To install an iOS Simulator, open **Xcode > Settings... > Components**, and under **Platform Support > iOS ...**, click **Get**.
Step 4: 
### Install Watchman
[Watchman](https://facebook.github.io/watchman/docs/install#macos) is a tool for watching changes in the filesystem. Installing it will result in better performance. You can install it with:
```sh
$ brew update
$ brew install watchman
```


# Create a development build for a physical Android device with EAS

## Set up an Android device with a development build
<BuildEnvironmentSwitch />
Step 1: 
### Install EAS CLI
To build your app, you will need to install EAS CLI. You can do this by running the following command in your terminal:
```sh
$ npm install -g eas-cli
```
Step 2: 
### Create an Expo account and login
To build your app, you will need to create an Expo account and login to the EAS CLI.
1. [Sign up](https://expo.dev/signup) for an Expo account.
2. Run the following command in your terminal to log in to the EAS CLI:
   ```sh
$ eas login
```
Step 3: 
### Configure your project
Run the following command to create an EAS config in your project:
```sh
$ eas build:configure
```
Step 4: 
### Create a build
Run the following command to create a development build:
```sh
$ eas build --platform android --profile development
```
Step 5: 
### Install the development build on your device
After the build is complete, scan the QR code in your terminal or open the link on your device. Tap **Install** to download the build on your device, then tap **Open** to install it.


# Create a development build for a physical Android device locally

## Set up an Android device with a development build
<BuildEnvironmentSwitch />
<AndroidStudioEnvironmentInstructions />
<AndroidStudioInstructions />
## Running your app on an Android device
Step 1: 
### Install expo-dev-client
Run the following command in your project's root directory:
```sh
$ npx expo install expo-dev-client
```
Step 2: 
### Enable debugging over USB
Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device to install your app during development.
To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to **Settings** > **About phone** > **Software information** and then tapping the `Build number` row at the bottom seven times. You can then go back to **Settings** > **Developer options** to enable "USB debugging".
Step 3: 
### Plug in your device via USB
Plug in your Android device via USB to your computer.
Check that your device is properly connecting to ADB, the Android Debug Bridge, by running `adb devices` in your terminal. You should see your device listed with `device` listed next to it. For example:
```sh
$ adb devices
List of devices attached
8AHX0T32K	device
```
Step 4: 
### Run your app
Run the following from your terminal:
```sh
$ npx expo run:android
```
> This command runs a development server after building your app. You can skip running `npx expo start` on the next page.


# Run on a physical Android device with Expo Go

## Set up an Android device with Expo Go
Scan the QR code to download the app from the Google Play Store, or visit the Expo Go page on the [Google Play Store](https://play.google.com/store/apps/details?id=host.exp.exponent&referrer=docs).
<div className="inline-block rounded-lg border border-default bg-palette-white p-4">
  <QRCodeReact
    value="https://play.google.com/store/apps/details?id=host.exp.exponent&referrer=docs"
    size={228}
  />
</div>


# Create a development build for Android Emulator with EAS

## Set up an Android Emulator with a development build
<BuildEnvironmentSwitch />
<AndroidStudioInstructions />
<AndroidEmulatorInstructions />
## Create a development build
Step 1: 
### Install EAS CLI
To build your app, you will need to install EAS CLI. You can do this by running the following command in your terminal:
```sh
$ npm install -g eas-cli
```
Step 2: 
### Create an Expo account and login
To build your app, you will need to create an Expo account and login to the EAS CLI.
1. [Sign up](https://expo.dev/signup) for an Expo account.
2. Run the following command in your terminal to log in to the EAS CLI:
   ```sh
$ eas login
```
Step 3: 
### Configure your project
Run the following command to create an EAS config in your project:
```sh
$ eas build:configure
```
Step 4: 
### Create a build
Run the following command to create a development build:
```sh
$ eas build --platform android --profile development
```
Step 5: 
### Install the development build on your emulator
After the build is complete, the CLI will prompt you to automatically download and install it on the Android Emulator. When prompted, press <kbd>Y</kbd> to directly install it on the emulator.
If you miss this prompt, you can download the build from the link provided in the terminal and drag and drop it onto the Android Emulator to install it.


# Create a development build for Android Emulator locally

## Set up an Android Emulator with a development build
<BuildEnvironmentSwitch />
<AndroidStudioEnvironmentInstructions />
<AndroidStudioInstructions />
<AndroidEmulatorInstructions />
## Running your app on an Android Emulator
Step 1: 
### Install expo-dev-client
Run the following command in your project's root directory:
```sh
$ npx expo install expo-dev-client
```
Step 2: 
Run the following from your terminal:
```sh
$ npx expo run:android
```
> This command runs a development server after building your app. You can skip running `npx expo start` on the next page.


# Run on Android Emulator with Expo Go

## Set up an Android Emulator with Expo Go
<AndroidStudioInstructions />
<AndroidEmulatorInstructions />
## Install Expo Go
When you start a development server with `npx expo start` on the [start developing](/get-started/start-developing) page, press <kbd>a</kbd> to open the Android Emulator. Expo CLI will install Expo Go automatically.


# Create a development build for a physical iOS device with EAS

## Set up an iOS device with a development build
<BuildEnvironmentSwitch />
Step 1: 
### Enroll in the Apple Developer Program
To install a development build on your iOS device, you will need an active subscription to the Apple Developer Program. Sign up for the [Apple Developer Program here](https://developer.apple.com/programs/).
Step 2: 
### Install EAS CLI
To build your app, you will need to install EAS CLI. You can do this by running the following command in your terminal:
```sh
$ npm install -g eas-cli
```
Step 3: 
### Create an Expo account and login
Next, you will need to create an Expo account and login to the EAS CLI.
1. [Sign up](https://expo.dev/signup) for an Expo account.
2. Run the following command in your terminal to log in to the EAS CLI:
   ```sh
$ eas login
```
Step 4: 
### Configure your project
Run the following command to create an EAS config in your project:
```sh
$ eas build:configure
```
Step 5: 
### Create an ad hoc provisioning profile
To install a development build on your iOS device, you will need to create an ad hoc provisioning profile. Create one by running the following command in your terminal:
```sh
$ eas device:create
```
Step 6: 
### Create a development build
Run the following command to create a development build:
```sh
$ eas build --platform ios --profile development
```
Step 7: 
### Install the development build on your device
After the build is complete, scan the QR code in your terminal and tap **Open with iTunes** when it appears inside the Camera app. Alternatively, open the link displayed in the terminal on your device.
After confirming the installation, the app will appear in your device's app library.
Step 8: 
### Turn on developer mode
1. Open **Settings** > **Privacy & Security**, scroll down to the **Developer Mode** list item and navigate into it.
2. Tap the switch to enable **Developer Mode**. After you do so, Settings presents an alert to warn you that Developer Mode reduces your device's security. To continue enabling **Developer Mode**, tap the alert's **Restart** button.
3. After the device restarts and you unlock it, the device shows an alert confirming that you want to enable Developer Mode. Tap **Turn On**, and enter your device passcode when prompted.
> Alternatively, if you have Xcode installed on your Mac, you can use it to [enable iOS developer mode](/guides/ios-developer-mode/#connect-an-ios-device-with-a-mac).


# Create a development build for a physical iOS device locally

## Set up an iOS device with a development build
<BuildEnvironmentSwitch />
## Set up Xcode and Watchman
<XcodeInstructions />
## Configure your project
Step 1: 
### Install expo-dev-client
Run the following command in your project's root directory:
```sh
$ npx expo install expo-dev-client
```
Step 2: 
### Plug in your device via USB and enable developer mode
1. Connect your iOS device to your Mac using a USB cable. Unlock the device and tap **Trust** if prompted.
2. Open Xcode. From the menu bar, select **Window** > **Devices and Simulators**. You will see a warning in Xcode to enable developer mode.
3. On your iOS device, open **Settings** > **Privacy & Security**, scroll down to the **Developer Mode** list item and navigate into it.
4. Tap the switch to enable **Developer Mode**. After you do so, Settings presents an alert to warn you that Developer Mode reduces your device's security. To continue enabling **Developer Mode**, tap the alert's **Restart** button.
5. After the device restarts and you unlock it, the device shows an alert confirming that you want to enable Developer Mode. Tap **Turn On**, and enter your device passcode when prompted.
Step 3: 
### Run the project on your device
1. Add the `ios.bundleIdentifier` in the **app.json** file in the root directory to a unique value so that Xcode generates the provisioning profile for the app signing step.
2. Run the following command in your project's root directory and select your plugged in device from the list:
```sh
$ npx expo run:ios --device
```
> This command runs a development server after building your app. You can skip running `npx expo start` on the next page.


# Run on a physical iOS device with Expo Go

## Set up an iOS device with Expo Go
Scan the QR code to download the app from the App Store, or visit the Expo Go page on the [App Store](https://itunes.apple.com/app/apple-store/id982107779).
<div className="inline-block rounded-lg border border-default bg-palette-white p-4">
  <QRCodeReact value="https://itunes.apple.com/app/apple-store/id982107779" size={228} />
</div>


# Create a development build for iOS Simulator with EAS

## Set up an iOS Simulator with a development build
<BuildEnvironmentSwitch />
## Set up Xcode
<XcodeInstructions />
## Create a development build
Step 1: 
### Install EAS CLI
To build your app, you will need to install EAS CLI. You can do this by running the following command in your terminal:
```sh
$ npm install -g eas-cli
```
Step 2: 
### Create an Expo account and login
Next, you will need to create an Expo account and login to the EAS CLI.
1. [Sign up](https://expo.dev/signup) for an Expo account.
2. Run the following command in your terminal to log in to the EAS CLI:
   ```sh
$ eas login
```
Step 3: 
### Configure your project
Run the following command to create an EAS config in your project:
```sh
$ eas build:configure
```
Step 4: 
### Adjust your build profile
To create a simulator-compatible development build, you'll need to update your build profile in **eas.json** to set the `ios.simulator` property to `true`:
```json eas.json
{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": {
        "simulator": true
      }
    }
  }
}
```
Step 6: 
### Create a development build
Run the following command to create a development build:
```sh
$ eas build --platform ios --profile development
```
Step 7: 
### Install the development build on your simulator
After the build is complete, the CLI will prompt you to automatically download and install it on the iOS Simulator. When prompted, press <kbd>Y</kbd> to directly install it on the simulator.
If you miss this prompt, you can download the build from the link provided in the terminal and drag and drop it onto the iOS Simulator to install it.


# Create a development build for iOS Simulator locally

## Set up an iOS Simulator with a development build
<BuildEnvironmentSwitch />
## Set up Xcode and Watchman
<XcodeInstructions />
## Running your app on an iOS Simulator
Step 1: 
### Install expo-dev-client
Run the following command in your project's root directory:
```sh
$ npx expo install expo-dev-client
```
Step 2: 
Run the following from your terminal:
```sh
$ npx expo run:ios
```
> This command runs a development server after building your app. You can skip running `npx expo start` on the next page.


# Run on iOS Simulator with Expo Go

## Set up an iOS Simulator with Expo Go
## Set up Xcode
<XcodeInstructions />
## Install Expo Go
When you start a development server with `npx expo start` on the [start developing](/get-started/start-developing) page, press <kbd>i</kbd> to open the iOS Simulator. Expo CLI will install Expo Go automatically.



<a id="next-step"></a>
## 下一步
¥Next step
你有一个项目和一个开发环境。现在是时候开始开发了。
¥You have a project and a development environment. Now it's time to start developing.


## 开始开发

对 Expo 项目进行第一次更改并在你的设备上实时查看。

Step 1: 
## Start a development server
To start the development server, run the following command:
```sh
$ npx expo start
```
Step 2: 
## Open the app on your device
After running the command above, you will see a QR code in your terminal. Scan this QR code to open the app on your device.
If you're using an Android Emulator or iOS Simulator, you can press <kbd>a</kbd> or <kbd>i</kbd> respectively to open the app.
Note: Having problems?
---
Make sure you are on the same Wi-Fi network on your computer and your device.
If it still doesn't work, it may be due to the router configuration &mdash; this is common for public networks. You can work around this by choosing the **Tunnel** connection type when starting the development server, then scanning the QR code again.
```sh
$ npx expo start --tunnel
```
> Using the **Tunnel** connection type will make the app reloads considerably slower than on **LAN** or **Local**, so it's best to avoid tunnel when possible. You may want to install and use an emulator or simulator to speed up development if **Tunnel** is required to access your machine from another device on your network.
---
Step 3: 
## Make your first change
Open the **app/(tabs)/index.tsx** file in your code editor and make a change.
```diff
diff --git a/app/(tabs)/index.tsx b/app/(tabs)/index.tsx
index 45cfa0e..4d1b384 100644
--- a/app/(tabs)/index.tsx
+++ b/app/(tabs)/index.tsx
@@ -17,7 +17,7 @@ export default function HomeScreen() {
      }
    >
      <ThemedView style={styles.titleContainer}>
-       <ThemedText type="title">Welcome!</ThemedText>
+       <ThemedText type="title">Hello World!</ThemedText>
        <HelloWave />
      </ThemedView>
      <ThemedView style={styles.stepContainer}>
```
Note: Changes not showing up on your device?
---
Expo Go is configured by default to automatically reload the app whenever a file is changed, but let's make sure to go over the steps to enable it in case somehow things aren't working.
- Make sure you have the [development mode enabled in Expo CLI](/workflow/development-mode#development-mode).
- Close the Expo app and reopen it.
- Once the app is open again, shake your device to reveal the developer menu. If you are using an emulator, press <kbd>Ctrl</kbd> + <kbd>M</kbd> for Android or <kbd>Cmd ⌘</kbd> + <kbd>D</kbd> for iOS.
- If you see **Enable Fast Refresh**, press it. If you see **Disable Fast Refresh**, dismiss the developer menu. Now try making another change.
---
---
## File structure
Below, you can get familiar with the default project's file structure:
<ProjectStructure />
## Features
The default project template has the following features:
<TemplateFeatures />


## 下一步

开发、审查和提交你的项目。

以下是继续构建应用的后续步骤：
¥Here are next steps to continue building your app:
<a id="reset-your-project"></a>
### 重置你的项目
¥Reset your project
你可以删除样板代码并重新开始新项目。运行以下命令重置你的项目：
¥You can remove the boilerplate code and start fresh with a new project. Run the following command to reset your project:
```sh
$ npm run reset-project
```
此命令将应用中的现有文件移动到 app-example，然后创建一个带有新 index.tsx 文件的新应用目录。
¥This command will move the existing files in **app** to **app-example**, then create a new **app** directory with a new **index.tsx** file.
<a id="develop-review-and-deploy"></a>
### 开发、审查和部署
¥Develop, review, and deploy
通过阅读“开发”部分中的文档来了解如何开发。你将学习如何创建 [UI 元素](/develop/user-interface/splash-screen-and-app-icon/)、添加 [单元测试](/develop/unit-testing/)、包含 [原生模块](/config-plugins/introduction/) 等。
¥Learn how to develop by reading the docs in the Develop section. You'll learn how to create [UI elements](/develop/user-interface/splash-screen-and-app-icon/), add [unit tests](/develop/unit-testing/), include [native modules](/config-plugins/introduction/), and more.
开发完应用后，你可以将其与 [review](/review/overview) 的队友共享。
¥Once you've developed your app, you can share it with your teammates for [review](/review/overview).
最后，你可以将你的项目 [build](/deploy/build-project/) 和 [submit](/deploy/submit-to-app-stores/) 到应用商店。
¥Finally, you can [build](/deploy/build-project/) and [submit](/deploy/submit-to-app-stores/) your project to the app stores.
<a id="step-by-step-guide"></a>
### 分步指南
¥Step-by-step guide
有关从头到尾使用 Expo 构建应用的指导性分步演练，请查看 [tutorial](/tutorial/introduction/)。
¥For a guided, step-by-step walkthrough of building an app with Expo from start to finish, check out the [tutorial](/tutorial/introduction/).


# 开发

## 开发工具

Expo 工具和网站的概述，它们将帮助你完成项目构建过程的各个方面。

当你使用 Expo 创建新项目时，了解以下基本工具和网站可以帮助你完成应用开发之旅。此页面概述了推荐工具列表。
¥When you create a new project with Expo, learning about the following essential tools and websites can help you during your app development journey. This page provides an overview of a list of recommended tools.
<a id="expo-cli"></a>
## Expo CLI
Expo CLI 是一种开发工具，当你创建新项目时会自动与 `expo` 包一起安装。你可以通过利用 `npx`（Node.js 包运行器）来使用它。
¥Expo CLI is a development tool and is installed automatically with `expo` package when you create a new project. You can use it by leveraging `npx` (a Node.js package runner).
它旨在帮助你在应用开发阶段更快地行动。例如，你与 Expo CLI 的第一次交互是通过运行以下命令启动开发服务器：`npx expo start`。
¥It is designed to help you move faster during the app development phase. For example, your first interaction with Expo CLI is starting the development server by running the command: `npx expo start`.
以下是你在开发应用时将使用 Expo CLI 的常用命令列表：
¥The following is a list of common commands that you will use with Expo CLI while developing your app:
| 命令                              | 描述                                                                                                    |
| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `npx expo start`                | 启动开发服务器（无论你使用的是开发版本还是 Expo Go）。                                                                       |
| `npx expo prebuild`             | 使用 [预建](/workflow/prebuild/) 生成原生 Android 和 iOS 目录。                                                   |
| `npx expo run:android`          | 在本地编译原生 Android 应用。                                                                                   |
| `npx expo run:ios`              | 在本地编译原生 iOS 应用。                                                                                       |
| `npx expo install package-name` | 用于通过向此命令添加 `--fix` 选项来安装新库或验证和更新项目中的特定库。                                                              |
| `npx expo lint`                 | [设置和配置](/guides/using-eslint/) ESLint。如果 ESLint 已配置，此命令将 [本地与全局 URL 参数](/guides/using-eslint/#usage)。 |
简而言之，Expo CLI 允许你开发、编译、启动应用等。有关你可以使用 CLI 执行的更多可用选项和操作，请参阅 [Expo CLI 参考](/more/expo-cli/)。
¥In a nutshell, Expo CLI allows you to develop, compile, start your app, and more. See [Expo CLI reference](/more/expo-cli/) for more available options and actions you can perform with the CLI.
<a id="eas-cli"></a>
## EAS 命令行接口
¥EAS CLI
EAS CLI 用于登录你的 Expo 账户并使用不同的 EAS 服务（例如 Build、Update 或 Submit）编译你的应用。你还可以使用此工具来：
¥EAS CLI is used to log in to your Expo account and compile your app using different EAS services such as Build, Update, or Submit. You can also use this tool to:
* 将你的应用发布到应用商店
  ¥Publish your app to the app stores
* 创建应用的开发、预览或生产版本
  ¥Create a development, preview, or production build of your app
* 创建无线 (OTA) 更新
  ¥Create over-the-air (OTA) updates
* 管理你的应用凭据
  ¥Manage your app credentials
* 为 iOS 设备创建临时配置文件
  ¥Create an ad hoc provisioning profile for an iOS device
要使用 EAS CLI，你需要通过运行以下命令在本地计算机上全局安装它：
¥To use EAS CLI, you need to install it globally on your local machine by running the command:
```sh
$ npm install -g eas-cli
```
你可以在终端窗口中使用 `eas --help` 来了解有关可用命令的更多信息。有关完整参考，请参阅 [`eas-cli` npm 页面](https://www.npmjs.com/package/eas-cli)。
¥You can use `eas --help` in your terminal window to learn more about the available commands. For a complete reference, see [`eas-cli` npm page](https://www.npmjs.com/package/eas-cli).
<a id="expo-doctor"></a>
## Expo Doctor
Expo Doctor 是一个命令行工具，用于诊断 Expo 项目中的问题。要使用它，请在项目的根目录中运行以下命令：
¥Expo Doctor is a command line tool used to diagnose issues in your Expo project. To use it, run the following command in your project's root directory:
```sh
$ npx expo-doctor
```
此命令执行检查并分析项目的代码库，以查找 [应用配置](/workflow/configuration/) 和 package.json 文件、依赖兼容性、配置文件和项目整体运行状况中的常见问题。检查完成后，Expo Doctor 会输出结果。
¥This command performs checks and analyzes your project's codebase for common issues in [app config](/workflow/configuration/) and **package.json** files, dependency compatibility, configuration files, and the overall health of the project. Once the check is complete, Expo Doctor outputs the results.
如果 Expo Doctor 发现问题，它会提供问题描述以及如何修复或在哪里寻求帮助的建议。
¥If Expo Doctor finds an issue, it provides a description of the problem along with advice on how to fix it or where to find help.
默认情况下，Expo Doctor 会根据 [React Native 目录](https://reactnative.directory/) 验证你项目的包，并在存在原生目录时检查应用配置属性是否正确同步。你可以在项目的 package.json 文件中配置这些检查。有关更多详细信息，请参阅 [`reactNativeDirectoryCheck`](/versions/latest/config/package-json/#reactnativedirectorycheck) 和 [`appConfigFieldsNotSyncedCheck`](/versions/latest/config/package-json/#appconfigfieldsnotsynced)。
¥By default, Expo Doctor validates your project's packages against the [React Native directory](https://reactnative.directory/) and checks if app config properties are properly synced when native directories exist. You can configure these checks in your project's **package.json** file. See [`reactNativeDirectoryCheck`](/versions/latest/config/package-json/#reactnativedirectorycheck) and [`appConfigFieldsNotSyncedCheck`](/versions/latest/config/package-json/#appconfigfieldsnotsynced) for more details.
你还可以使用 `npx expo-doctor --help` 显示使用信息。
¥You can also use `npx expo-doctor --help` to display usage information.
<a id="orbit"></a>
## Orbit
Orbit 是一款 macOS 和 Windows 应用，可实现：
¥Orbit is a macOS and Windows app that enables:
* 在物理设备和模拟器上安装并启动来自 EAS 的构建。
  ¥Install and launch builds from EAS on physical devices and emulators.
* 在 Android 模拟器或 iOS 模拟器上安装并启动来自 EAS 的更新。
  ¥Install and launch updates from EAS on Android Emulators or iOS Simulators.
* 在 Android 模拟器或 iOS 模拟器上启动零食项目。
  ¥Launch snack projects on Android Emulators or iOS Simulators.
* 使用本地文件安装和启动应用。Orbit 支持任何 Android .apk、iOS Simulator 兼容的 .app 或临时签名的应用。
  ¥Use local files to install and launch apps. Orbit supports any Android **.apk**, iOS Simulator compatible **.app**, or ad hoc signed apps.
* 查看 EAS 仪表板中的固定项目列表。
  ¥See a list of pinned projects from your EAS dashboard.
<a id="installation"></a>
### 安装
¥Installation
For macOS: 
你可以使用 Homebrew for macOS 下载 Orbit，也可以直接从 [GitHub 发布](https://github.com/expo/orbit/releases) 下载。
¥You can download Orbit with Homebrew for macOS, or directly from the [GitHub releases](https://github.com/expo/orbit/releases).
```sh
$ brew install expo-orbit
```
如果你希望 Orbit 在你登录时自动启动，请单击菜单栏中的 Orbit 图标，然后单击“设置”并选择“登录时启动”选项。
¥If you want Orbit to start when you log in automatically, click on the Orbit icon in the menu bar, then **Settings** and select the **Launch on Login** option.
For Windows: 
> 注意：Windows 版 Orbit 处于预览阶段，仅与 x64 和 x86 机器兼容。将来会添加对其他架构的兼容性。
>
> ¥**Note**: Orbit for Windows is in preview and is only compatible with x64 and x86 machines. Compatibility for other architectures will be added in the future.
你可以直接从 [GitHub 发布](https://github.com/expo/orbit/releases) 下载适用于 Windows 的 Orbit。
¥You can download Orbit for Windows directly from the [GitHub releases](https://github.com/expo/orbit/releases).
>  **info** Orbit 依赖于 macOS 和 Windows 上的 Android SDK，以及 macOS 上仅用于设备管理的 `xcrun`，这需要同时设置 [安卓工作室](/workflow/android-studio-emulator/) 和 [Xcode](/workflow/ios-simulator/)。
>
> ¥Orbit relies on the Android SDK on both macOS and Windows and `xcrun` for device management only on macOS, which requires setting up both [Android Studio](/workflow/android-studio-emulator/) and [Xcode](/workflow/ios-simulator/).
{/* ### Usage */}
<a id="expo-tools-for-vs-code"></a>
## VS Code 的 Expo 工具
¥Expo Tools for VS Code
Expo Tools 是一个 VS Code 扩展，可在使用应用配置文件时改善你的开发体验。它为应用配置、EAS 配置、存储配置和 Expo Module 配置文件等文件提供自动补齐和智能感知等功能。
¥Expo Tools is a VS Code extension to improve your development experience when working with app config files. It provides features such as autocomplete and intellisense for files such as app config, EAS config, store config and Expo Module config files.
你还可以使用它来调试你的应用，使用 VS Code 的内置调试器设置断点、检查变量、通过调试控制台执行代码等。有关如何使用此扩展进行调试，请参阅 [使用 VS Code 进行调试](/debugging/tools/#debugging-with-vs-code)。
¥You can also use it to debug your app using VS Code's built-in debugger to set breakpoints, inspect variables, execute code through the debug console, and more. See [Debugging with VS Code](/debugging/tools/#debugging-with-vs-code) for how to use this extension for debugging.
<a id="test-prototypes-with-snack-and-expo-go"></a>
## 使用测试原型小样和 Expo Go
¥Test prototypes with Snack and Expo Go
<a id="snack"></a>
### Snack
Snack 是一个浏览器内开发环境，其工作原理与 Expo Go 类似。这是共享代码片段和试验 React Native 的好方法，无需在计算机上下载任何工具。
¥Snack is an in-browser development environment that works similarly to Expo Go. It's a great way to share code snippets and experiment with React Native without downloading any tools on your computer.
要使用它，请转到 [snack.expo.dev](https://snack.expo.dev/)，在 App.js 中编辑 `<Text>` 组件，在右侧面板中选择一个平台（Android、iOS 或 Web）并实时查看更改。
¥To use it, go to [snack.expo.dev](https://snack.expo.dev/), edit the `<Text>` component in **App.js**, choose a platform (Android, iOS, or web) in the right panel and see the changes live.
<a id="expo-go"></a>
### Expo
[Expo](https://expo.dev/go) 是一个免费的开源沙盒，用于学习和试验 React Native。它适用于 Android 和 iOS。
¥[Expo Go](https://expo.dev/go) is a free open-source, sandbox for learning and experimenting with React Native. It works with Android and iOS.
有关如何使用它的更多信息：
¥For more information on how to use it:
* 单击 [树摇动](/get-started/set-up-your-environment/?mode=expo-go) 转到“设置你的环境”指南
  ¥Click [this link](/get-started/set-up-your-environment/?mode=expo-go) to go to Set up your environment guide
* 在“你想在哪里开发？”下选择要开发的平台
  ¥Select a platform to develop under **Where would you like to develop?**
* 在“你想如何开发？”下选择 Expo Go
  ¥Select Expo Go under **How would you like to develop?**
* 按照该指南中描述的说明操作
  ¥Follow the instructions described in that guide
> 注意：不建议构建生产应用并将其分发到应用商店。请改用 [开发构建](/get-started/set-up-your-environment/?mode=development-build)。
>
> ¥**Note:** Not recommended for building and distributing production apps to the app stores. Instead, use [development builds](/get-started/set-up-your-environment/?mode=development-build).
Note: What if I open a project with an unsupported SDK version?
---
When running a project that was created for an unsupported SDK version in Expo Go, you'll see the following error:
```sh
"Project is incompatible with this version of Expo Go"
```
To fix this, upgrading your project to a [supported SDK version](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version) is recommended. If you want to learn how to do it, see [Upgrade the project to a new SDK Version](#how-do-i-upgrade-my-project-from).
---
Note: How do I upgrade my project from an unsupported SDK version?
---
See [Upgrading Expo SDK guide](/workflow/upgrading-expo-sdk-walkthrough) for instructions for upgrading to a specific SDK version.
---
<a id="react-native-directory"></a>
## React Native 目录
¥React Native directory
当你使用开发版本创建项目时，任何与 React Native 兼容的库都可以在 Expo 项目中使用。
¥Any library that is compatible with React Native works in an Expo project when you use a development build to create your project.
[reactnative.directory](https://reactnative.directory/) 是一个可搜索的 React Native 库数据库。如果你要查找的库未包含在 Expo SDK 中，请使用目录查找与你的项目兼容的库。
¥[reactnative.directory](https://reactnative.directory/) is a searchable database for React Native libraries. If a library you are looking for is not included in Expo SDK, use the directory to find a compatible library for your project.


## 验证

了解如何在 Expo 项目中设置身份验证。

Expo 可用于登录 Android、iOS 和 Web 上的许多流行提供商。[`expo-auth-session`](/versions/latest/sdk/auth-session/) 包允许 [基于浏览器的身份验证](/versions/latest/sdk/auth-session/#how-web-browser-based-authentication-flows-work)（使用 OAuth 或 OpenID Connect）到你的 Android、iOS 和 Web 项目。你还可以使用 [开发构建](/develop/development-builds/create-a-build) 的第三方提供商的原生库来实现身份验证。
¥Expo can be used to login to many popular providers on Android, iOS, and web. [`expo-auth-session`](/versions/latest/sdk/auth-session/) package allows [browser-based authentication](/versions/latest/sdk/auth-session/#how-web-browser-based-authentication-flows-work) (using OAuth or OpenID Connect) to your project for Android, iOS, and the web. You can also implement authentication using native libraries for third-party providers with [development builds](/develop/development-builds/create-a-build).


## 使用 Jest 进行单元测试

了解如何设置和配置 jest-expo 库以使用 Jest 为项目编写单元和快照测试。

[Jest](https://jest.nodejs.cn) 是最广泛使用的单元和快照 JavaScript 测试框架。在本指南中，你将学习如何在项目中设置 Jest、编写单元测试、编写快照测试，以及在将 Jest 与 React Native 结合使用时构建测试的最佳实践。
¥[Jest](https://jest.nodejs.cn) is the most widely used unit and snapshot JavaScript testing framework. In this guide, you will learn how to set up Jest in your project, write a unit test, write a snapshot test, and best practices for structuring your tests when using Jest with React Native.
你还将使用 [`jest-expo`](https://github.com/expo/expo/tree/main/packages/jest-expo) 库，这是一个 Jest 预设，可模拟 Expo SDK 的原生部分并处理 Expo 项目所需的大部分配置。
¥You will also use the [`jest-expo`](https://github.com/expo/expo/tree/main/packages/jest-expo) library, which is a Jest preset that mocks the native part of the Expo SDK and handles most of the configuration required for your Expo project.
<a id="installation-and-configuration"></a>
## 安装和配置
¥Installation and configuration
创建 Expo 项目后，请按照以下说明在你的项目中安装和配置 `jest-expo`：
¥After creating your Expo project, follow the instructions below to install and configure `jest-expo` in your project:
Step 1: 
Install `jest-expo` and other required dev dependencies in your project. Run the following command from your project's root directory:
For macOS/Linux: 
```sh
$ npx expo install jest-expo jest @types/jest --dev
```
For Windows: 
```sh
$ npx expo install jest-expo jest @types/jest "--" --dev
```
> **Note:** If your project is not using TypeScript, you can skip installing `@types/jest`.
Step 2: 
Open **package.json**, add a script for running tests, and add the preset for using the base configuration from `jest-expo`:
```json package.json
{
  "scripts": {
  },
  "jest": {
    "preset": "jest-expo"
  }
}
```
Step 3: 
In **package.json**, add `jest-expo` as a preset so that a base for Jest's configuration is set up:
```json package.json
{
  "jest": {
    "preset": "jest-expo"
  }
}
```
Note: Additional configuration for using 
---
You can transpile node modules your project uses by configuring [`transformIgnorePatterns`](https://jest.nodejs.cn/docs/configuration#transformignorepatterns-arraystring) in your **package.json**. This property takes a regex pattern as its value:
For npm/Yarn: 
```json package.json
"jest": {
  "preset": "jest-expo",
  "transformIgnorePatterns": [
    "node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|@sentry/react-native|native-base|react-native-svg)"
  ]
}
```
For pnpm: 
```json package.json
"jest": {
  "preset": "jest-expo",
  "transformIgnorePatterns": [
    "node_modules/(?!(?:.pnpm/)?((jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|@sentry/react-native|native-base|react-native-svg))"
  ]
}
```
Jest has many configuration options, but the above configuration should cover most of your needs. However, you can always add to this pattern list. For more details, see [Configuring Jest](https://jest.nodejs.cn/docs/configuration).
---
## Install React Native Testing Library
The [React Native Testing Library (`@testing-library/react-native`)](https://callstack.github.io/react-native-testing-library/) is a lightweight solution for testing React Native components. It provides utility functions and works with Jest.
To install it, run the following command:
For macOS/Linux: 
```sh
$ npx expo install @testing-library/react-native --dev
```
For Windows: 
```sh
$ npx expo install @testing-library/react-native "--" --dev
```
> **warning** **Deprecated:** `@testing-library/react-native` replaces the deprecated `react-test-renderer` because `react-test-renderer` does not support React 19 and above. Remove the deprecated library from your project if you are currently using it. See [React's documentation for more information](https://react.nodejs.cn/warnings/react-test-renderer).
## Unit test
A unit test checks the smallest unit of code, usually a function. To write your first unit test, take a look at the following example:
Step 1: 
Inside the **app** directory of your project, create a new file called **index.tsx**, and the following code to render a simple component:
```tsx index.tsx
import { PropsWithChildren } from 'react';
import { StyleSheet, Text, View } from 'react-native';
export const CustomText = ({ children }: PropsWithChildren) => <Text>{children}</Text>;
export default function HomeScreen() {
  return (
    <View style={styles.container}>
      <CustomText>Welcome!</CustomText>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
Step 2: 
Create a **\_\_tests\_\_** directory at the root of your project's directory. If this directory already exists in your project, use that. Then, create a new file called **HomeScreen-test.tsx**. The `jest-expo` preset customizes the Jest configuration to also identify files with **-test.ts|tsx** extensions as tests.
Add the following example code in **HomeScreen-test.tsx**:
```tsx HomeScreen-test.tsx
import { render } from '@testing-library/react-native';
import HomeScreen, { CustomText } from '@/app/index';
describe('<HomeScreen />', () => {
  test('Text renders correctly on HomeScreen', () => {
    const { getByText } = render(<HomeScreen />);
    getByText('Welcome!');
  });
});
```
In the above example, the `getByText` query helps your tests find relevant element in your app's user interface and make assertion whether or not the certain element exists. The React Native Testing Library provides this query, and each [query variant](https://callstack.github.io/react-native-testing-library/docs/api/queries#query-variant) differs in its return type. For more examples and detailed API information, see the React Native Testing Library's [Queries API reference](https://callstack.github.io/react-native-testing-library/docs/api/queries).
Step 3: 
Run the following command in a terminal window to execute the test:
```sh
$ npm run test
```
You will see one test being passed.
## Structure your tests
Organizing your test files is important to make them easier to maintain. A common pattern is creating a **\_\_tests\_\_** directory and putting all your tests inside.
An example structure of tests next to the **components** directory is shown below:
Alternatively, you can have multiple **\_\_tests\_\_** sub-directories for different areas of your project. For example, create a separate test directory for **components**, and so on:
It's all about preferences, and it is up to you to decide how you want to organize your project directory.
## Snapshot test
> **info** **Note:** For UI testing, we recommend end-to-end tests instead of snapshot unit tests. See the [E2E tests with Maestro](/eas/workflows/examples/e2e-tests/) guide.
A [snapshot test](https://jest.nodejs.cn/docs/en/snapshot-testing) is used to make sure that UI stays consistent, especially when a project is working with global styles that are potentially shared across components.
To add a snapshot test for `<HomeScreen />`, add the following code snippet in the `describe()` in **HomeScreen-test.tsx**:
```tsx HomeScreen-test.tsx
describe('<HomeScreen />', () => {
  test('CustomText renders correctly', () => {
    const tree = render(<CustomText>Some text</CustomText>).toJSON();
    expect(tree).toMatchSnapshot();
  });
});
```
Run `npm run test` command, and you will see a snapshot created inside **\_\_tests\_\_\\\_\_snapshots\_\_** directory, and two tests passed.
## Code coverage reports
Code coverage reports can help you understand how much of your code is tested. To see the code coverage report in your project using the HTML format, in **package.json**, under `jest`, set the `collectCoverage` to true and use `collectCoverageFrom` to specify a list of files to ignore when collecting the coverage.
```json package.json
"jest": {
  ...
  "collectCoverage": true,
  "collectCoverageFrom": [
    "**/*.{ts,tsx,js,jsx}",
    "!**/coverage/**",
    "!**/node_modules/**",
    "!**/babel.config.js",
    "!**/expo-env.d.ts",
    "!**/.expo/**"
  ]
}
```
Run `npm run test`. You will see a **coverage** directory created in your project. Find the **lcov-report/index.html** and open it in a browser to see the coverage report.
>
通常，我们不建议将 index.html 文件上传到 git。在 .gitignore 文件中添加 `coverage/**/*` 以防止被跟踪。
¥Usually, we don't recommend uploading **index.html** file to git. Add `coverage/**/*` in the **.gitignore** file to prevent it from being tracked.
<a id="jest-flows-optional"></a>
## Jest 流程（可选）
¥Jest flows (optional)
你还可以使用不同的流程来运行测试。以下是你可以尝试的一些示例脚本：
¥You can also use different flows to run your tests. Below are a few example scripts that you can try:
```json package.json
"scripts": {
  "test": "jest --watch --coverage=false --changedSince=origin/main",
  "testDebug": "jest -o --watch --coverage=false",
  "testFinal": "jest",
  "updateSnapshots": "jest -u --coverage=false"
}
```
有关更多信息，请参阅 Jest 文档中的 [CLI 选项](https://jest.nodejs.cn/docs/en/cli)。
¥For more information, see [CLI Options](https://jest.nodejs.cn/docs/en/cli) in Jest documentation.
<a id="additional-information"></a>
## 附加信息
¥Additional information


# 导航

## 基于文件的路由

了解 Expo Router，它是一个基于文件的路由系统，以及如何在你的项目中使用它。

本指南提供了 Expo Router 和导航模式（堆栈和选项卡）的基本约定和指导。要继续，你可以在现有项目中 [使用默认模板创建项目](/get-started/create-a-project/) 或安装 [Expo Router 库手动](/router/installation/#manual-installation)。
¥This guide provides basic conventions and guidance for Expo Router and navigation patterns (stack and tabs). To follow along, you can [create a project by using the default template](/get-started/create-a-project/) or install [Expo Router library manually](/router/installation/#manual-installation) in your existing project.
<a id="what-is-expo-router"></a>
## 什么是 Expo Router？
¥What is Expo Router?
Expo Router 是用于 React Native 和 Web 应用的路由框架。它允许你管理应用中屏幕之间的导航，并在多个平台（Android、iOS 和 Web）上使用相同的组件。它使用基于文件的方法来确定应用内的路由。它还提供原生导航并建立在 [React 导航](https://react-navigation.nodejs.cn/) 之上。
¥Expo Router is a routing framework for React Native and web applications. It allows you to manage navigation between screens in your app and use the same components on multiple platforms (Android, iOS and web). It uses a file-based method to determine routes inside your app. It also provides native navigation and is built on top of [React Navigation](https://react-navigation.nodejs.cn/).
<a id="app-directory"></a>
## app 目录
¥app directory
该应用是一个特殊目录。你添加到此目录的任何文件都将成为原生应用内的路由，并在网络上反映该路由的相同 URL。
¥The **app** is a special directory. Any file you add to this directory becomes a route inside the native app and reflects the same URL for that route on the web.
<a id="create-a-route"></a>
## 创建路由
¥Create a route
在 app 目录中，通过添加包含 index.tsx 文件的文件或嵌套目录来创建路由。
¥In the **app** directory, a route is created by adding a file or a nested directory that includes **index.tsx** file.
例如，要创建应用的初始路由，你可以使用以下代码将 index.tsx 添加到应用目录：
¥For example, to create an initial route of your app, you can add **index.tsx** to the **app** directory with the following code:
```tsx app/index.tsx|collapseHeight=280
import { View, Text, StyleSheet } from 'react-native';
export default function HomeScreen() {
  return (
    <View style={styles.container}>
      <Text>Home</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
app/index.tsx 文件将与 `/` 路由匹配，创建此文件后，应用目录结构为：
¥The **app/index.tsx** file will match the `/` route and after creating this file the **app** directory structure is:
<a id="file-name-conventions"></a>
### 文件名约定
¥File name conventions
名为 index 的文件与父目录匹配，并且不添加路径段。例如，如果你通过添加 app/settings/index.tsx 来扩展应用的文件结构，它将匹配 `/settings` 路由。
¥Files named **index** match the parent directory and do not add a path segment. For example, if you expand the app's file structure by adding **app/settings/index.tsx**, it will match the `/settings` route.
> 注意：通过将 React 组件导出为默认值来定义路由文件。该文件必须使用 `.js`、`.jsx`、`.ts` 或 `.tsx` 扩展名。
>
> ¥**Note:** A route file is defined by exporting a React component as the default value. The file must use either `.js`, `.jsx`, `.ts`, or `.tsx` extension.
<a id="_layout-file"></a>
## \_layout 文件
¥\_layout file
目录中的布局文件用于定义共享 UI 元素（例如标题、标签栏），以便它们在不同路由之间保持不变。
¥Layout files in a directory are used to define shared UI elements such as headers, tab bars so that they persist between different routes.
每次你创建新项目时，默认情况下，应用目录将包含一个根布局文件（app/_layout）。
¥Any time you create a new project, by default the **app** directory will contain a **root layout** file (**app/_layout**).
<a id="root-layout"></a>
### 根布局
¥Root layout
传统上，React Native 项目由单个根组件构成（定义为 App.js 或 index.js）。类似地，应用目录中的第一个布局文件（_layout.tsx）被视为单个根组件。
¥Traditionally, React Native projects are structured with a single root component (defined as **App.js** or **index.js**). Similarly, the first layout file (**_layout.tsx**) inside the **app** directory is considered to be the single root component.
在多个路由之间，Expo Router 中的 Root 布局文件用于在多个路由之间共享 UI，例如注入全局提供程序、主题、样式、延迟启动画面渲染直到加载资源和字体，或定义应用的根导航结构。
¥Between multiple routes, a Root layout file in Expo Router is used to share UI between multiple routes such as injecting global providers, themes, styles, delay splash screen rendering until assets and fonts are loaded, or defining your app's root navigation structure.
例如，以下代码导出一个名为 `RootLayout` 的默认 React 组件：
¥For example, the following code exports a default React component called `RootLayout`:
```tsx app/_layout.tsx
export default function RootLayout() {
  return (
  )
}
```
>  **info** 使用 Expo Router，app/_layout.tsx 中定义的任何 React 提供程序都可以通过应用中的任何路由访问。要提高性能并减少渲染次数，请尝试将提供程序的范围缩小到仅需要它们的路由。
>
> ¥With Expo Router, any React providers defined inside **app/_layout.tsx** are accessible by any route in your app. To improve performance and cause fewer renders, try to reduce the scope of your providers to only the routes that need them.
<a id="stack-navigator"></a>
## 堆栈导航器
¥Stack navigator
堆栈导航器是一种在应用中的不同路由之间导航的模式。它允许在屏幕之间转换并管理导航历史记录。它在概念上类似于 Web 浏览器处理导航状态的方式。
¥A stack navigator is a pattern to navigate between different routes in an app. It allows transitioning between screens and managing the navigation history. It is conceptually similar to how a web browser handles the navigation state.
例如，如果你想添加新路由 `/details`，请创建 details.tsx 文件。这将允许应用用户从 `/` 路由导航到 `/details`：
¥For example, if you want to add a new route `/details`, create **details.tsx** file. This will allow the app user to navigate from the `/` route to `/details`:
```tsx app/details.tsx|collapseHeight=300
import { View, Text, StyleSheet } from 'react-native';
export default function DetailsScreen() {
  return (
    <View style={styles.container}>
      <Text>Details</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
创建此路由文件后，当前文件结构如下：
¥After creating this route file, the current file structure looks like:
要允许在两个路由（`/` 和 `/details`）之间导航，请更新 Root 布局文件并向其中添加 `Stack` 组件：
¥To allow navigation between two routes (`/` and `/details`), update the Root layout file and add a `Stack` component to it:
```tsx app/_layout.tsx|collapseHeight=440
import { Stack } from 'expo-router';
export default function RootLayout() {
  return (
    <Stack
      screenOptions={{
        headerStyle: {
          backgroundColor: '#f4511e',
        },
        headerTintColor: '#fff',
        headerTitleStyle: {
          fontWeight: 'bold',
        },
      }}>
      <Stack.Screen name="index" />
      <Stack.Screen name="details" />
    </Stack>
  );
}
```
布局文件中的 `<Stack.Screen name={routeName} />` 组件允许在堆栈中定义路由。
¥`<Stack.Screen name={routeName} />` component in the layout file allows defining routes in a stack.
> 注意：上面示例中的 `screenOptions` 允许为堆栈内的所有路由配置选项。请参阅 [静态配置路由选项](/router/advanced/stack/#statically-configure-route-options) 了解更多信息。
>
> ¥**Note:** The `screenOptions` in the above example allows configuring options for all the routes inside a stack. See [Statically configure route options](/router/advanced/stack/#statically-configure-route-options) for more information.
<a id="navigating-between-routes"></a>
## 在路由之间导航
¥Navigating between routes
Expo Router 使用名为 `Link` 的内置组件在应用中的路由之间移动。这在概念上类似于 Web 使用 `<a>` 标签和 `href` 属性的方式。
¥Expo Router uses a built-in component called `Link` to move between routes in an app. This is conceptually similar to how web works with the `<a>` tag and the `href` attribute.
你可以通过从 Expo Router 库导入它，然后将 `href` 属性与要导航的路由一起传递作为属性的值来使用它。例如，要从 `/` 导航到 `/details`，请在 index.tsx 文件中添加 `Link` 组件：
¥You can use it by importing it from Expo Router library and then passing the `href` prop with the route to navigate as the value of the prop. For example, to navigate from `/` to `/details`, add a `Link` component in the **index.tsx** file:
```tsx app/index.tsx|collapseHeight=300
import { Link } from 'expo-router';
import { View, Text, StyleSheet } from 'react-native';
export default function HomeScreen() {
  return (
    <View style={styles.container}>
      <Text>Home</Text>
      <Link href="/details">View details</Link>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
<a id="how-does-link-work"></a>
### `Link` 如何工作？
¥How does `Link` work?
`Link` 默认将子项封装在 `<Text>` 中。你可以自定义使用不同的按钮组件。
¥`Link` wraps the children in a `<Text>` by default. You can customize to use a different button component.
使用 `Link` 组件封装自定义按钮组件和 `asChild` 属性，将所有属性转发到 `Link` 组件的第一个子项。有关 `Link` 组件的 props 的更多信息，请参阅 [在页面之间导航](/router/navigating-pages/)。
¥Use the `Link` component to wrap the custom button component and the `asChild` prop which forwards all props to the first child of the `Link` component. For more information on the `Link` component's props, see [Navigate between pages](/router/navigating-pages/).
<a id="groups"></a>
## 群组
¥Groups
创建一个组来组织类似的路由或应用的一部分。每个组都有一个布局文件，分组目录需要在括号 `(group)` 内命名。
¥A group is created to organize similar routes or a section of the app. Each group has a layout file, and the grouped directory requires a name inside parentheses `(group)`.
例如，你有 `/` 和 `/details` 路由，它们可以在 app/(home) 目录中分组。这会将文件结构更新为：
¥For example, you have the `/` and `/details` routes which can be grouped inside **app/(home)** directory. This updates the file structure to:
你还需要添加 (home)/_layout.tsx，它用于定义 `/` 和 `/details` 路由的 `Stack` 导航器。
¥You also need to add **(home)/_layout.tsx** which is used to define the `Stack` navigator for `/` and `/details` routes.
```tsx app/(home)/_layout.tsx|collapseHeight=440
import { Stack } from 'expo-router';
export default function HomeLayout() {
  return (
    <Stack
      screenOptions={{
        headerStyle: {
          backgroundColor: '#f4511e',
        },
        headerTintColor: '#fff',
        headerTitleStyle: {
          fontWeight: 'bold',
        },
      }}>
      <Stack.Screen name="index" />
      <Stack.Screen name="details" />
    </Stack>
  );
}
```
Root 布局文件也发生了变化，现在包括 (home) 组，该组进一步使用 (home)/index 作为应用的初始路由。
¥The Root layout file also changes and now includes the **(home)** group which further uses **(home)/index** as the initial route of the app.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="(home)" />
    </Stack>
  );
}
```
> 注意：在上面的例子中，屏幕选项被移动到 (home)/_layout.tsx 文件。这意味着如果你在 Root 布局中向 Stack 导航器添加任何路由，它将不会使用与 Home 布局中的路由相同的屏幕选项。
>
> ¥**Note:** In the above example, the screen options are moved to **(home)/_layout.tsx** file. This means if you add any route to the Stack navigator inside the Root layout, it will not use the same screen options as the routes inside the Home layout.
<a id="tab-navigator"></a>
## 标签导航器
¥Tab navigator
选项卡导航器是一种使用选项卡栏在应用的不同部分之间导航的常见模式。Expo Router 提供 `Tabs` 导航组件。
¥A tab navigator is a common pattern to navigate between different sections of an app using a tab bar. Expo Router provides a `Tabs` navigation component.
例如，在当前文件结构中，你有两个不同的部分：主页（`/` 和 `/details` 路由）和设置（`/settings` 路由）。添加一个特殊目录（tabs），你可以将现有的 Home 路由文件移动到其中并创建一个 settings.tsx。
¥For example, in the current file structure, you have two different sections: Home (`/` and `/details` routes) and Settings (`/settings` route). Adding a special directory **(tabs)**, you can move the existing Home route files inside it and create a **settings.tsx**.
(选项卡) 内的任何文件或目录都将成为选项卡导航器中的路由。要使用标签栏在不同路由之间切换，你需要在此目录 (tabs)/_layout 中创建布局文件并导出 `TabLayout` 组件：
¥Any file or directory inside **(tabs)** becomes a route in the tab navigator. To switch between different routes using the tab bar, you need to create a layout file inside this directory **(tabs)/_layout** and export a `TabLayout` component:
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs>
      <Tabs.Screen name="(home)" />
      <Tabs.Screen name="settings" />
    </Tabs>
  );
}
```
> 注意：在 `TabLayout` 中，`(home)` 的现有 Stack 导航器现已嵌套。
>
> ¥**Note:** In `TabLayout`, the existing Stack navigator for `(home)` is now nested.
要使其工作，请通过添加 (tabs) 作为第一条路由来更新 app/_layout.tsx 文件。
¥To make this work, update the **app/_layout.tsx** file by adding **(tabs)** as the first route.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="(tabs)" />
    </Stack>
  );
}
```
<a id="not-found-routes"></a>
## 未找到路由
¥Not found routes
Expo Router 提供了一个特殊文件 +not-found.tsx，用于处理 404 路由。此路由文件匹配嵌套级别中所有不匹配的路由。
¥Expo Router provides a special file **+not-found.tsx** which is used to handle routes that are 404s. This route file matches all unmatched routes from a nested level.
在应用目录中创建此文件：
¥Create this file in the **app** directory:
```tsx +not-found.tsx|collapseHeight=320
import { Link, Stack } from 'expo-router';
import { View, StyleSheet } from 'react-native';
export default function NotFoundScreen() {
  return (
    <>
      <Stack.Screen options={{ title: "Oops! This screen doesn't exist." }} />
      <View style={styles.container}>
        <Link href="/">Go to home screen</Link>
      </View>
    </>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```


## 动态路由

了解动态路由以及如何使用 Expo Router 库创建它们。

动态路由允许根据 URL 中嵌入的动态段匹配一个或多个路径。此段采用变量的形式，例如唯一标识符，并且你的应用事先不知道确切的段。
¥A **dynamic route** allows matching one or multiple paths based on a dynamic segment embedded in the URL. This segment is in the form of a variable, such as a unique identifier, and your app doesn't know the exact segment ahead of time.
本指南介绍如何使用 Expo Router 处理动态路由。
¥This guide explains how to handle dynamic routes with Expo Router.
> 本指南继续在上一个 [基于文件的路由](/develop/file-based-routing/) 中使用的示例和应用目录结构的基础上构建。
>
> ¥This guide continues to build on top of the example and the **app** directory structure used in the previous [File-based routing](/develop/file-based-routing/).
<a id="dynamic-route-convention"></a>
## 动态路由约定
¥Dynamic route convention
通过将文件名称括在方括号中来创建路由的动态段。例如，[id].tsx。
¥A dynamic segment of a route is created by wrapping a file's name in square brackets. For example, **[id].tsx**.
> 什么是动态段？URL 中路径的任何部分都是动态的。例如，在显示用户列表的应用屏幕中，你可能有一个路径，例如 `/details/[id]`，其中 `[id]` 是动态段，并根据用户的 `id` 显示详细信息。
>
> ¥**What is a dynamic segment?** Any segment of a path in a URL that is dynamic. For example, in an app screen where it displays a users list, you might have a path such as `/details/[id]` where the `[id]` is the dynamic segment and displays details based on the `id` of the user.
<a id="create-a-dynamic-route"></a>
## 创建动态路由
¥Create a dynamic route
让我们考虑以下应用目录结构：
¥Let's consider the following **app** directory structure:
在上面的文件结构中，`[id]` 用于显示路由 details/[id].tsx 的信息。相同的路由将根据 `id` 的值显示唯一信息：
¥In the above file structure, the `[id]` is used to display information for the route **details/[id].tsx**. The same route will display unique information based on the value of the `id`:
| 路由                    | 匹配的网址        |
| --------------------- | ------------ |
| **details/\[id].tsx** | `/details/1` |
| **details/\[id].tsx** | `/details/2` |
此动态段约定确保当应用用户从主屏幕导航到详细信息屏幕时，他们会看到路由动态段的正确信息。
¥This dynamic segment convention makes sure that when an app user navigates from the home screen to the details screen, they view the correct information for the dynamic segment of the route.
<a id="use-link-to-navigate-to-a-dynamic-route"></a>
## 使用 `Link` 导航到动态路由
¥Use `Link` to navigate to a dynamic route
通过静态或使用 `href` 对象向 `Link` 组件提供查询参数，可以从一条路由导航到一条动态路由。
¥Navigating from one route to a dynamic route is done by providing query parameters to the `Link` component either statically or using the `href` object.
例如，以下代码允许你使用查询参数静态导航到动态路由：
¥For example, the following code allows you to navigate to the dynamic route statically using query parameters:
```tsx app/(home)/index.tsx|collapseHeight=300
import { Link } from 'expo-router';
import { View, Text, StyleSheet } from 'react-native';
export default function HomeScreen() {
  return (
    <View style={styles.container}>
      <Text>Home</Text>
      <Link href="/details/1">View first user details</Link>
      <Link href="/details/2">View second user details</Link>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
你还可以使用 `href` 对象提供一个 `pathname`，它获取动态路由的值并传递 `params`：
¥You can also use the `href` object to provide a `pathname` which takes the value of the dynamic route and passes `params`:
```tsx app/(home)/index.tsx
import { Link } from 'expo-router';
import { View, Text, StyleSheet } from 'react-native';
export default function HomeScreen() {
  return (
    <View style={styles.container}>
      <Text>Home</Text>
      <Link
        href={{
          pathname: '/details/[id]',
          params: { id: 'bacon' },
        }}>
        View user details
      </Link>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
<a id="access-parameters-from-dynamic-segments"></a>
## 从动态段访问参数
¥Access parameters from dynamic segments
URL 的动态段可以通过路由组件中的 [路由参数](/router/reference/url-parameters/) 访问。例如，你可以使用 [`useLocalSearchParams`](/router/reference/hooks/#uselocalsearchparams) 钩子，它返回所选路由的 URL 参数。
¥Dynamic segments of a URL are accessible with a [route parameter](/router/reference/url-parameters/) in the route component. For example, you can use the [`useLocalSearchParams`](/router/reference/hooks/#uselocalsearchparams) hook which returns the URL parameters for the selected route.
```tsx app/(home)/details/[id].tsx|collapseHeight=300
import { useLocalSearchParams } from 'expo-router';
import { View, Text, StyleSheet } from 'react-native';
export default function DetailsScreen() {
  const { id } = useLocalSearchParams();
  return (
    <View style={styles.container}>
      <Text>Details of user {id} </Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
当 `/` 推送 `/details/1` 时，`useLocalSearchParams` 返回 `{ id: '1' }`，因为 `/details/1` 是选定的路由。
¥When `/` pushes `/details/1`, the `useLocalSearchParams` returns `{ id: '1' }` because `/details/1` is the selected route.


## 下一步

有关 Expo Router 的指南和参考列表，供进一步阅读。

如果你是第一次深入研究基于文件的路由框架，那么有很多关于 Expo Router 的知识需要学习。以下指南和参考资料将帮助你深入了解：
¥There's much to learn about Expo Router if you are diving into the file-based routing framework for the first time. The following guides and references will help you dive deep:
<a id="navigation-patterns"></a>
## 导航模式
¥Navigation patterns
<a id="references"></a>
## 参考资料
¥References


# 用户界面

## 启动画面和应用图标

了解如何向 Expo 项目添加启动画面和应用图标。

启动画面和应用图标是移动应用的基本元素。它们在用户体验和应用品牌推广中发挥着重要作用。本指南提供了如何创建它们并将其添加到你的应用的步骤。
¥A splash screen and an app icon are fundamental elements of a mobile app. They play an important role in the user experience and branding of the app. This guide provides steps on how to create and add them to your app.
Video Tutorial: [Create an App Icon and Splash Screen](https://www.youtube.com/watch?v=3Bsw8a1BJoQ)
***
<a id="splash-screen"></a>
## 启动画面
¥Splash screen
启动屏幕，也称为启动屏幕，是用户打开你的应用时看到的第一个屏幕。当应用加载时它保持可见。你还可以使用原生 [启动画面 API](/versions/latest/sdk/splash-screen) 来控制启动屏幕消失时的行为。
¥A splash screen, also known as a launch screen, is the first screen a user sees when they open your app. It stays visible while the app is loading. You can also control the behavior of when a splash screen disappears by using the native [SplashScreen API](/versions/latest/sdk/splash-screen).
[`expo-splash-screen`](/versions/latest/sdk/splash-screen) 有一个内置的 [配置插件](/config-plugins/introduction)，可让你配置属性，例如启动图标和背景颜色。
¥The [`expo-splash-screen`](/versions/latest/sdk/splash-screen) has a built-in [config plugin](/config-plugins/introduction) that lets you configure properties such as the splash icon and background color.
>  **warning** 请勿使用 Expo Go 或开发版本来测试你的启动画面。Expo Go 在启动画面可见时渲染你的应用图标，这可能会干扰测试。开发版本包括 `expo-dev-client`，它有自己的启动画面，可能会导致冲突。相反，使用 [预览版本](/build/eas-json/#preview-builds) 或 [生产构建](/build/eas-json/#production-builds)。
>
> ¥**Do not use Expo Go or a development build to test your splash screen**. Expo Go renders your app icon while the splash screen is visible, which can interfere with testing. Development builds include `expo-dev-client`, which has its own splash screen and may cause conflicts. **Instead, use a [preview build](/build/eas-json/#preview-builds) or a [production build](/build/eas-json/#production-builds)**.
Step 1: 
### Create a splash screen icon
To create a splash screen icon, you can use this [Figma template](https://www.figma.com/community/file/1466490409418563617). It provides a bare minimum design for an icon and splash images for Android and iOS.
**Recommended:**
- Use a 1024x1024 image.
- Use a **.png** file.
- Use a transparent background.
Step 2: 
### Export the splash icon as a .png
After creating a splash screen icon, export it as a **.png** and save it in the **assets/images** directory. By default, Expo uses **splash-icon.png** as the file name. If you decide to change the name of your splash screen file, make sure to use that in the next step.
> **Note:** **Currently, only .png images are supported** to use as a splash screen icon in an Expo project. If you use another image format, making a production build of your app will fail.
Step 3: 
### Configure the splash screen icon
Open the app config file, and under plugins, set the following properties:
!!!IG0!!!
To test your new splash screen, build your app for [internal distribution](/tutorial/eas/internal-distribution-builds) or for production, see guides on [Android](/tutorial/eas/android-production-build/) and [iOS](/tutorial/eas/ios-production-build/).
!!!IG4!!!
Note: Configuring  properties separately for Android and iOS
---
[`expo-splash-screen`](/versions/latest/sdk/splash-screen) also supports `android` and `ios` properties for configuring the splash screen for a specific platform. See the following example:
!!!IG1!!!
---
Note: Not using prebuild?
---
If your app does not use [Expo Prebuild](/workflow/prebuild) (formerly the _managed workflow_) to generate the native **android** and **ios** directories, then changes in the app config will have no effect. For more information, see [how you can customize the configuration manually](https://github.com/expo/expo/tree/main/packages/expo-splash-screen#-installation-in-bare-react-native-projects).
---
Note: Troubleshooting: New splash screen not appearing on iOS
---
For SDK 51 and below, in iOS development builds, launch screens can sometimes remain cached between builds, making it harder to test new images. Apple recommends clearing the _derived data_ directory before rebuilding, this can be done with Expo CLI by running:
```sh
$ npx expo run:ios --no-build-cache
```
See [Apple's guide on testing launch screens](https://developer.apple.com/documentation/technotes/tn3118-debugging-your-apps-launch-screen) for more information.
---
## App icon
An app's icon is what your app users see on their device's home screen and app stores. Android and iOS have different and strict requirements.
Step 1: 
### Create an app icon
To create an app icon, you can use this [Figma template](https://www.figma.com/community/file/1466490409418563617). It provides a bare minimum design for an icon and splash images for Android and iOS.
Step 2: 
### Export the icon image as a .png
After creating an app icon, export it as **.png** and save it in the **assets/images** directory. By default, Expo uses **icon.png** as the file name. If you decide to use a different file name, make sure to use that in the next step.
Step 3: 
### Add the icon in app config
Open the app config and add the local path as the value of [`icon`](/versions/latest/config/app/#icon) property to point it to your new app icon:
!!!IG2!!!
Note: Custom configuration tips for Android and iOS
---
#### Android
Further customization of the Android icon is possible using the [`android.adaptiveIcon`](/versions/latest/config/app/#adaptiveicon) property, which will override both of the previously mentioned settings.
The Android Adaptive Icon is formed from two separate layers &mdash; a foreground image and a background color or image. This allows the OS to mask the icon into different shapes and also supports visual effects. For Android 13 and later, the OS supports a themed app icon that uses a wallpaper and theme to determine the color set by the device's theme.
The design you provide should follow the [Android Adaptive Icon Guidelines](https://developer.android.com/develop/ui/views/launch/icon_design_adaptive) for launcher icons. You should also:
- Use **.png** files.
- Use the `android.adaptiveIcon.foregroundImage` property to specify the path to your foreground image.
- Use the `android.adaptiveIcon.monochromeImage` property to specify the path to your monochrome image.
- The default background color is white; to specify a different background color, use the `android.adaptiveIcon.backgroundColor` property. You can instead specify a background image using the `android.adaptiveIcon.backgroundImage` property. Make sure that it has the same dimensions as your foreground image.
You may also want to provide a separate icon for older Android devices that do not support Adaptive Icons. You can do so with the `android.icon` property. This single icon would be a combination of your foreground and background layers.
> See [Apple best practices](https://developer.apple.com/design/human-interface-guidelines/app-icons/#Best-practices) to ensure your icon looks professional, such as testing your icon on different wallpapers and avoiding text beside your product's wordmark. Provide an icon that's at least 512x512 pixels.
#### iOS
For iOS, your app's icon should follow the [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/app-icons/). You should also:
- Use a **.png** file.
- 1024x1024 is a good size. If you have an Expo project created using `npx create-expo-app`, [EAS Build](/build/setup/) will generate the other sizes for you. In case of a bare React Native project, generate the icons on your own. The largest size EAS Build generates is 1024x1024.
- The icon must be exactly square. For example, a 1023x1024 icon is not valid.
- Make sure the icon fills the whole square, with no rounded corners or other transparent pixels. The operating system will mask your icon when appropriate.
- Use `ios.icon` to specify different icons for various system appearances (for example, dark and tinted) can be provided. If specified, this overrides the top-level icon key in the app config file. See the example below:
!!!IG3!!!
---


## 安全区域

了解如何在 Expo 项目中添加屏幕组件的安全区域。

创建安全区域可确保你的应用屏幕内容定位正确。这意味着它不会被凹口、状态栏、主页指示器和其他属于设备物理硬件或由操作系统控制的界面元素重叠。当内容重叠时，它会被这些界面元素隐藏。
¥Creating a safe area ensures your app screen's content is positioned correctly. This means it doesn't get overlapped by notches, status bars, home indicators, and other interface elements that are part of the device's physical hardware or are controlled by the operating system. When the content gets overlapped, it gets concealed by these interface elements.
以下是 Android 上应用屏幕内容被状态栏隐藏的示例。在 iOS 上，相同的内容被圆角、凹口和状态栏隐藏。
¥Here's an example of an app screen's content getting concealed by the status bar on Android. On iOS, the same content is concealed by rounded corners, notch, and the status bar.
<a id="use-react-native-safe-area-context-library"></a>
## 使用 `react-native-safe-area-context` 库
¥Use `react-native-safe-area-context` library
[`react-native-safe-area-context`](https://github.com/th3rdwave/react-native-safe-area-context) 提供了一个灵活的 API 来处理 Android 和 iOS 设备的安全区域插入。它还提供了一个 `SafeAreaView` 组件，你可以使用它代替 [`<View>`](https://rn.nodejs.cn/docs/view) 自动考虑屏幕组件中的安全区域。
¥[`react-native-safe-area-context`](https://github.com/th3rdwave/react-native-safe-area-context) provides a flexible API for handling Android and iOS device's safe area insets. It also provides a `SafeAreaView` component that you can use instead of a [`<View>`](https://rn.nodejs.cn/docs/view) to account for safe areas automatically in your screen components.
使用该库，上一个示例的结果会发生变化，因为它会在安全区域内显示内容，如下所示：
¥Using the library, the result of the previous example changes as it displays the content inside a safe area, as shown below:
<a id="installation"></a>
### 安装
¥Installation
如果你使用 [这篇博文](/get-started/create-a-project/) 创建了项目，则可以跳过安装 `react-native-safe-area-context`。此库作为 Expo Router 库的对等依赖安装。否则，请通过运行以下命令进行安装：
¥You can skip installing `react-native-safe-area-context` if you have created a project using [the default template](/get-started/create-a-project/). This library is installed as peer dependency for Expo Router library. Otherwise, install it by running the following command:
```sh
$ npx expo install react-native-safe-area-context
```
<a id="usage"></a>
### 用法
¥Usage
你可以直接使用 [`SafeAreaView`](https://github.com/th3rdwave/react-native-safe-area-context#safeareaview) 来封装屏幕组件的内容。它是一个常规的 `<View>`，安全区域插入应用为额外的填充或边距。
¥You can directly use [`SafeAreaView`](https://github.com/th3rdwave/react-native-safe-area-context#safeareaview) to wrap the content of your screen's component. It is a regular `<View>` with the safe area insets applied as extra padding or margin.
```tsx app/index.tsx
import { Text } from 'react-native';
import { SafeAreaView } from 'react-native-safe-area-context';
export default function HomeScreen() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <Text>Content is in safe area.</Text>
    </SafeAreaView>
  );
}
```
Note: Using a different Expo template and don't have Expo Router installed?
---
Import and add [`SafeAreaProvider`](https://github.com/th3rdwave/react-native-safe-area-context#safeareaprovider) to the root component file (such as **App.tsx**) before using `SafeAreaView` in your screen component.
```tsx App.tsx
import { SafeAreaProvider } from 'react-native-safe-area-context';
export default function App() {
  return (
    return <SafeAreaProvider>...</SafeAreaProvider>;
  );
}
```
---
## Alternate: `useSafeAreaInsets` hook
Alternate to `SafeAreaView`, you can use [`useSafeAreaInsets`](https://github.com/th3rdwave/react-native-safe-area-context#usesafeareainsets) hook in your screen component. It provides direct access to the safe area insets, allowing you to apply padding for each edge of the `<View>` using an inset from this hook.
The example below uses the `useSafeAreaInsets` hook. It applies top padding to a `<View>` using `insets.top`.
```tsx app/index.tsx
import { Text, View } from 'react-native';
import { useSafeAreaInsets } from 'react-native-safe-area-context';
export default function HomeScreen() {
  const insets = useSafeAreaInsets();
  return (
    <View style={{ flex: 1, paddingTop: insets.top }}>
      <Text>Content is in safe area.</Text>
    </View>
  );
}
```
The hook provides the insets in the following object:
```ts
{
  top: number,
  right: number,
  bottom: number,
  left: number
}
```
## Additional information
### Minimal example
Below is a minimal working example that uses the `useSafeAreaInsets` hook to apply top padding to a view.
#### Using react-native-safe-area-context
```tsx collapseHeight=320
import { Text, View } from 'react-native';
import { SafeAreaProvider, useSafeAreaInsets } from 'react-native-safe-area-context';
function HomeScreen() {
  const insets = useSafeAreaInsets();
  return (
    <View style={{ flex: 1, paddingTop: insets.top }}>
      <Text style={{ fontSize: 28 }}>Content is in safe area.</Text>
    </View>
  );
}
export default function App() {
  return (
    <SafeAreaProvider>
      <HomeScreen />
    </SafeAreaProvider>
  );
}
```
<a id="usage-with-react-navigation"></a>
### 与 React 导航一起使用
¥Usage with React Navigation
默认情况下，React Navigation 支持安全区域并使用 `react-native-safe-area-context` 作为对等依赖。有关详细信息，请参阅 [React 导航文档](https://react-navigation.nodejs.cn/docs/handling-safe-area/)。
¥By default, React Navigation supports safe areas and uses `react-native-safe-area-context` as a peer dependency. For more information, see the [React Navigation documentation](https://react-navigation.nodejs.cn/docs/handling-safe-area/).
<a id="usage-with-web"></a>
### 与 Web 一起使用
¥Usage with web
如果你的目标是 Web，请按照 [使用 Expo CLI 内置的 Chrome DevTools](#usage) 中的说明设置 `SafeAreaProvider`。如果你正在进行服务器端渲染 (SSR)，请参阅库文档中的 [Web SSR 部分](https://github.com/th3rdwave/react-native-safe-area-context#web-ssr)。
¥If you are targeting the web, set up `SafeAreaProvider` as described in the [usage section](#usage). If you are doing server-side rendering (SSR), see the [Web SSR section](https://github.com/th3rdwave/react-native-safe-area-context#web-ssr) in the library's documentation.


## 系统栏

了解如何在你的 Expo 项目中处理和自定义系统栏，以实现安全区域和无边框布局。

系统栏是位于屏幕边缘的 UI 元素，提供必要的设备信息和导航控件。根据移动操作系统的不同，它们包括状态栏（[安卓](https://developer.android.com/design/ui/mobile/guides/foundations/system-bars) 和 [iOS 系统](https://developer.apple.com/design/human-interface-guidelines/status-bars)）、标题栏（仅限 [安卓](https://medium.com/androiddevelopers/insets-handling-tips-for-android-15s-edge-to-edge-enforcement-872774e8839b#:~:text=or%20SHORT_EDGES.-,Caption%20bars,-When%20your%20app)）、导航栏（[安卓](https://developer.android.com/design/ui/mobile/guides/foundations/system-bars#navigation-bar) 和 [iOS 系统](https://developer.apple.com/design/human-interface-guidelines/navigation-bars)）以及主页指示器（仅限 iOS）。
¥System bars are the UI elements at the edges of the screen that provide essential device information and navigation controls. Depending on the mobile OS, they include the status bar ([Android](https://developer.android.com/design/ui/mobile/guides/foundations/system-bars) and [iOS](https://developer.apple.com/design/human-interface-guidelines/status-bars)), caption bar ([Android](https://medium.com/androiddevelopers/insets-handling-tips-for-android-15s-edge-to-edge-enforcement-872774e8839b#:~:text=or%20SHORT_EDGES.-,Caption%20bars,-When%20your%20app) only), navigation bar ([Android](https://developer.android.com/design/ui/mobile/guides/foundations/system-bars#navigation-bar) and [iOS](https://developer.apple.com/design/human-interface-guidelines/navigation-bars)), and home indicator (iOS only).
这些组件用于显示设备信息，例如电池电量、时间、通知提醒，并提供从设备界面任何位置与设备的直接交互。例如，无论应用用户当前正在使用哪个应用，都可以下拉状态栏来访问快速设置和通知。
¥These components are used to display device information such as battery level, time, notification alerts, and provide direct interaction with the device from anywhere in the device's interface. For example, an app user can pull down the status bar to access quick settings and notifications regardless of which app they're currently using.
系统栏是移动体验的基础，了解如何正确使用它们对于创建你的应用至关重要。
¥System bars are fundamental to the mobile experience, and understanding how to work with them properly is important for creating your app.
<a id="handling-overlaps-using-safe-areas"></a>
## 使用安全区域处理重叠
¥Handling overlaps using safe areas
你的部分应用内容可能会绘制在系统栏后面。为此，你需要正确定位应用内容，避免重叠并确保系统栏中的控件可见。
¥Some of your app's content may draw behind the system bars. To handle this, you need to position your app's content correctly by avoiding the overlap and ensuring that the controls from the system bars are present.
以下指南将引导你了解如何使用 `SafeAreaView` 或钩子直接在屏幕的每个边缘应用内嵌图 (Insets)。
¥The following guide walks you through how to use `SafeAreaView` or a hook to apply insets directly for each edge of the screen.
<a id="safe-areas-and-edge-to-edge-layout-on-android"></a>
### Android 上的安全区域和无边框布局
¥Safe areas and edge-to-edge layout on Android
在 [Android 上的边到边](https://expo.dev/blog/edge-to-edge-display-now-streamlined-for-android) 之前，半透明的状态栏和导航栏很常见。采用这种方法，这些状态栏后面绘制的内容已经位于其下方，通常无需考虑安全区域。
¥Before [edge-to-edge on Android](https://expo.dev/blog/edge-to-edge-display-now-streamlined-for-android), it was common to have a translucent status bar and navigation bar. With this approach, the content drawn behind these bars was already underneath them, and it was typically not necessary to factor in safe areas.
现在，[Android 上的边到边](https://expo.dev/blog/edge-to-edge-display-now-streamlined-for-android)，你需要使用安全区域来确保内容不会与系统栏重叠。
¥Now, [with edge-to-edge on Android](https://expo.dev/blog/edge-to-edge-display-now-streamlined-for-android), you will need to use safe areas to ensure that content does not overlap with system bars.
<a id="customizing-system-bars"></a>
## 自定义系统栏
¥Customizing system bars
系统栏可以自定义，以匹配你的应用设计，并在不同场景下提供更好的可视性。使用 Expo 时，有两个库可用于此操作：`expo-status-bar` 和 `expo-navigation-bar`（仅限 Android）。
¥System bars can be customized to match your app's design and provide better visibility in different scenarios. When using Expo, there are two libraries available for this: `expo-status-bar` and `expo-navigation-bar` (Android only).
<a id="status-bar-configuration"></a>
### 状态栏配置
¥Status bar configuration
状态栏显示在 Android 和 iOS 屏幕的顶部。你可以使用 [`expo-status-bar`](/versions/latest/sdk/status-bar) 对其进行自定义。它提供了一个 `StatusBar` 组件，你可以使用该组件的 [`style`](/versions/latest/sdk/status-bar/#style) 属性或 [`setStatusBarStyle`](/versions/latest/sdk/status-bar/#statusbarsetstatusbarstylestyle-animated) 方法在应用运行时控制状态栏的外观：
¥The status bar appears at the top of the screen on both Android and iOS. You can customize it using [`expo-status-bar`](/versions/latest/sdk/status-bar). It provides a `StatusBar` component that you can use to control the appearance of the status bar while your app is running using the [`style`](/versions/latest/sdk/status-bar/#style) property or the [`setStatusBarStyle`](/versions/latest/sdk/status-bar/#statusbarsetstatusbarstylestyle-animated) method:
```tsx app/_layout.tsx
import { StatusBar } from 'expo-status-bar';
export default function RootLayout() {
  <>
    {/* Use light text instead of dark text in the status bar to provide more contrast with a dark background. */}
    <StatusBar style="light" />
  </>;
}
```
> 注意：在 Expo 默认模板中，`style` 属性设置为 `auto`。它会根据你应用当前使用的配色方案（亮色或暗色模式）自动选择合适的样式。
>
> ¥**Note:** In Expo default template, the `style` property is set to `auto`. It automatically picks the appropriate style depending on the color scheme (light or dark mode) currently used by your app.
要控制 `StatusBar` 的可见性，可以将 [`hidden`](/versions/latest/sdk/status-bar/#hidden) 属性设置为 `true` 或使用 [`setStatusBarHidden`](/versions/latest/sdk/status-bar/#statusbarsetstatusbarhiddenhidden-animation) 方法。
¥To control the `StatusBar` visibility, you can set the [`hidden`](/versions/latest/sdk/status-bar/#hidden) property to `true` or use the [`setStatusBarHidden`](/versions/latest/sdk/status-bar/#statusbarsetstatusbarhiddenhidden-animation) method.
在 Android 上启用无边框屏幕后，`expo-status-bar` 中依赖于不透明状态栏 [不可用](https://developer.android.com/about/versions/15/behavior-changes-15#edge-to-edge) 的功能将无法使用。只能自定义样式和可见性。其他属性将不执行任何操作并发出警告。
¥**With edge-to-edge enabled on Android, features from `expo-status-bar` that depend on an opaque status bar [are unavailable](https://developer.android.com/about/versions/15/behavior-changes-15#edge-to-edge)**. It's only possible to customize the style and visibility. Other properties will no-op and warn.
<a id="navigation-bar-configuration-android-only"></a>
### 导航栏配置（仅限 Android）
¥Navigation bar configuration (Android only)
在 Android 设备上，导航栏会显示在屏幕底部。你可以使用 [`expo-navigation-bar`](/versions/latest/sdk/navigation-bar) 库对其进行自定义。它提供了一个 `NavigationBar` 组件，你可以使用该组件的 [`setStyle`](/versions/latest/sdk/navigation-bar/#navigationbarsetstylestyle) 方法设置导航栏的样式：
¥On Android devices, the Navigation Bar appears at the bottom of the screen. You can customize it using the [`expo-navigation-bar`](/versions/latest/sdk/navigation-bar) library. It provides a `NavigationBar` component that you can use to set the style of the navigation bar using the [`setStyle`](/versions/latest/sdk/navigation-bar/#navigationbarsetstylestyle) method:
```tsx app/_layout.tsx
import { NavigationBar } from 'expo-navigation-bar';
import { useEffect } from 'react';
useEffect(() => {
  if (Platform.OS === 'android') {
    // Set the navigation bar style
    NavigationBar.setStyle('dark');
  }
}, []);
```
要控制 `NavigationBar` 的可见性，可以使用 [`setVisibilityAsync`](/versions/latest/sdk/navigation-bar/#navigationbarsetvisibilityasyncvisibility) 方法。
¥To control the `NavigationBar` visibility, you can use the [`setVisibilityAsync`](/versions/latest/sdk/navigation-bar/#navigationbarsetvisibilityasyncvisibility) method.
在 Android 上启用无边框屏幕后，`expo-navigation-bar` 中依赖于不透明导航栏 [不可用](https://developer.android.com/about/versions/15/behavior-changes-15#edge-to-edge) 的功能将无法使用。只能自定义样式和可见性。其他属性将不执行任何操作并发出警告。
¥**With edge-to-edge enabled on Android, features from `expo-navigation-bar` that depend on an opaque navigation bar [are unavailable](https://developer.android.com/about/versions/15/behavior-changes-15#edge-to-edge)**. It's only possible to customize the style and visibility. Other properties will no-op and warn.


## 字体

了解如何使用本地文件或 Google Font 包将自定义字体集成到应用中

Android 和 iOS 都有自己的一套平台字体。为了提供一致的用户体验并增强应用的品牌，你可以使用自定义字体。
¥Android and iOS come with their own set of platform fonts. To provide a consistent user experience and enhance your app's branding, you can use custom fonts.
本指南介绍了向项目中添加和加载自定义字体的不同方法，还提供了与字体相关的其他信息。
¥This guide covers different ways you can add and load a custom font into your project and also provides additional information related to fonts.
<a id="add-a-custom-font"></a>
## 添加自定义字体
¥Add a custom font
有两种方法可以将自定义字体添加到项目中：
¥There are two ways you can add a custom font into your project:
* 将字体文件添加到你的本地资源中。例如，assets/fonts 目录中的字体文件。
  ¥Add a font file into your local assets. For example, a font file in the **assets/fonts** directory.
* 安装 Google 字体包。例如，安装 [`@expo-google-fonts/inter`](https://www.npmjs.com/package/@expo-google-fonts/inter) 包。
  ¥Install a Google Font package. For example, installing [`@expo-google-fonts/inter`](https://www.npmjs.com/package/@expo-google-fonts/inter) package.
<a id="supported-font-formats"></a>
### 支持的字体格式
¥Supported font formats
Expo SDK 正式支持 Android、iOS 和 Web 平台上的 OTF 和 TTF 字体格式。如果你的字体是其他字体格式，则必须设置高级配置以在你的项目中支持该格式。
¥Expo SDK officially supports OTF and TTF font formats across Android, iOS and web platforms. If your font is in another font format, you have to set up advanced configuration to support that format in your project.
<a id="variable-fonts"></a>
### 可变字体
¥Variable fonts
可变字体（包括 OTF 和 TTF 格式的可变字体实现）并非所有平台都支持。为了获得完整的平台支持，请使用静态字体。或者，使用 [fontTools](https://fonttools.readthedocs.io/en/latest/varLib/mutator.html) 等实用程序从变量字体中提取你想要使用的特定轴配置，并将其保存为单独的字体文件。
¥Variable fonts, including variable font implementations in OTF and TTF, do not have support across all platforms. For full platform support, use static fonts. Alternatively, use a utility such as [fontTools](https://fonttools.readthedocs.io/en/latest/varLib/mutator.html) to extract the specific axis configuration you want to use from the variable font and save it as a separate font file.
<a id="how-to-choose-between-otf-and-ttf"></a>
### 如何在 OTF 和 TTF 之间进行选择
¥How to choose between OTF and TTF
如果你使用的字体同时具有 OTF 和 TTF 版本，则最好使用 OTF。.otf 文件比 .ttf 文件小。有时，OTF 在某些情况下也会渲染得更好一些。
¥If the font you're using has both OTF and TTF versions, prefer OTF. The **.otf** files are smaller than **.ttf** files. Sometimes, OTF also renders slightly better in certain contexts.
<a id="use-a-local-font-file"></a>
## 使用本地字体文件
¥Use a local font file
将文件复制到项目的 assets/fonts 目录中。
¥Copy the file into your project's **assets/fonts** directory.
>  **info** assets/fonts 目录路径是 React Native 应用中放置字体文件的常见约定。如果你遵循自定义约定，你可以将这些文件放在其他地方。
>
> ¥**assets/fonts** directory path is a common convention in React Native apps to put font files. You can place these files elsewhere if you follow a custom convention.
在项目中使用本地字体文件的两种方法：
¥Two ways to use the local font file in your project:
* 使用 [`expo-font` 配置插件](/versions/latest/sdk/font/#configuration-in-app-config) 嵌入字体文件。
  ¥Embed the font file with [`expo-font` config plugin](/versions/latest/sdk/font/#configuration-in-app-config).
* 在运行时使用 [`useFonts`](/versions/latest/sdk/font/#usefontsmap) 钩子异步加载字体文件。
  ¥Loading the font file with [`useFonts`](/versions/latest/sdk/font/#usefontsmap) hook at runtime asynchronously.
<a id="with-expo-font-config-plugin"></a>
### 使用 `expo-font` 配置插件
¥With `expo-font` config plugin
`expo-font` 配置插件允许在项目的原生代码中嵌入一个或多个字体文件。它支持 Android 和 iOS 的 `ttf` 和 `otf`，而 `woff` 和 `woff2` 仅在 iOS 上受支持。这是向你的应用添加字体的推荐方法，因为它具有以下优点：
¥The `expo-font` config plugin allows embedding one or more font files in your project's native code. It supports `ttf` and `otf` for both Android and iOS, and `woff` and `woff2` are supported on iOS only. This is the recommended method for adding fonts to your app due to its benefits:
* 当应用在设备上启动时，字体立即可用。
  ¥Fonts are available immediately when the app starts on a device.
* 应用启动时，无需额外代码即可异步加载项目中的字体。
  ¥No additional code required to load fonts in a project asynchronously when the app starts.
* 由于字体已打包在应用中，因此它们在安装应用的所有设备上始终可用。
  ¥Fonts are consistently available across all devices where the app is installed because they're bundled within the app.
但是，这种方法也有一些限制：
¥However, this method also has some limitations:
* 不适用于 Expo Go，因为此方法需要 [创建开发构建](/develop/development-builds/create-a-build/)。
  ¥Doesn't work with Expo Go since this method requires [creating a development build](/develop/development-builds/create-a-build/).
要在项目中嵌入字体，请按照以下步骤操作：
¥To embed a font in a project, follow the steps below:
Step 1: 
After adding a custom font file in your project, install the `expo-font` library.
```sh
$ npx expo install expo-font
```
Step 2: 
Add the config plugin to your [app config](/versions/latest/config/app/#plugins) file. The configuration must contain the path to the font file using [`fonts`, `android` or `ios`](/versions/latest/sdk/font/#configurable-properties) properties which take an array of one or more font definitions. The path to each font file is relative to the project's root.
The example below showcases all valid ways a font can be specified: as an array of objects that specify `fontFamily` and other properties, or an array of paths to font files.
For Android, you can specify the `fontFamily`, `weight`, and optionally `style` (defaults to `"normal"`), which will embed the fonts as native [XML resources](https://developer.android.com/develop/ui/views/text-and-emoji/fonts-in-xml). If you provide only the font file paths in an array, the file name becomes the font family name on Android. iOS always extracts the font family name from the font file itself.
If you plan to refer to fonts using just the `fontFamily`, provide an array of font paths (see `FiraSans-MediumItalic.ttf` below) and follow our [recommendation for file naming](#how-to-determine-which-font-family-name-to-use).
If you want to refer to fonts using a combination of `fontFamily`, `weight`, and `style`, provide an array of objects (see `Inter` below).
!!!IG3!!!
Step 3: 
After embedding the font with the config plugin, create a [new development build](/develop/development-builds/create-a-build/) and install it on your device or Android Emulator or iOS Simulator.
You can use the font with `<Text>` by specifying the `fontFamily` style prop. The examples below correspond to the fonts defined in the configuration above.
!!!IG4!!!
<ConfigReactNative title="Using this method in an existing React Native project?">
- **Android:** Copy font files to **android/app/src/main/assets/fonts**.
- **iOS:** See [Adding a Custom Font to Your App](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app) in the Apple Developer documentation.
</ConfigReactNative>
#### How to determine which font family name to use
- If you provide fonts as an array of file paths (as described above), on Android, the file name (without the extension) becomes the font family name. On iOS, the font family name is read from the font file itself. We recommend naming the font file same as its [PostScript name](#what-is-postscript-name-of-a-font) so the font family name is consistent on both platforms.
- If you use the object syntax, provide the "Family Name". This can be found in the Font Book app on macOS, [fontdrop.info](https://fontdrop.info/) or other programs.
Note: What is PostScript name of a font file?
---
The **PostScript name** of a font file is a unique identifier assigned to the font that follows Adobe's PostScript standard. It is used by operating systems and apps to refer to the font. It is not a font's **display name**.
For example, Inter Black font file's PostScript name is `Inter-Black`.
_Screenshot from Font Book app on macOS._
---
### With `useFonts` hook
The `useFonts` hook from `expo-font` library allows loading the font file asynchronously. This hook keeps track of the loading state and loads the font when an app is initialized.
It works with all Expo SDK versions and with Expo Go. To load a font in a project using `useFonts` hook, follow the steps below:
Step 1: 
After adding a custom font file in your project, install the `expo-font` and `expo-splash-screen` libraries.
```sh
$ npx expo install expo-font expo-splash-screen
```
The [`expo-splash-screen`](/versions/latest/sdk/splash-screen/) library provides `SplashScreen` component that you can use to prevent rendering the app until the font is loaded and ready.
Step 2: 
Map the font file using the `useFonts` hook in a top level component such as the root layout (**app/layout.tsx**) file in your project:
!!!IG5!!!
Step 3: 
Use the font on the `<Text>` by using `fontFamily` style prop in a React component:
!!!IG6!!!
## Use Google Fonts
Expo has first-class support for all fonts listed in [Google Fonts](https://fonts.google.com/). They are available using [`@expo-google-fonts`](https://github.com/expo/google-fonts) library. With any of the font package from this library, you can quickly integrate that font and its variants.
Two ways to use a Google Font in your project:
- Embed the installed font with [`expo-font` config plugin](/versions/latest/sdk/font/#configuration-in-appjsonappconfigjs).
- Load the installed font with [`useFonts`](/versions/latest/sdk/font/#usefontsmap) hook at runtime asynchronously.
### With `expo-font` config plugin
> **Note:** Embedding a Google Font using `expo-font` config plugin has same benefits and limitations as embedding a custom font on your own. See [using a local font file with `expo-font` config plugin](#with-expo-font-config-plugin) for more information.
Step 1: 
Install the font package. For example, to use Inter Black font, install the [`@expo-google-fonts/inter`](https://www.npmjs.com/package/@expo-google-fonts/inter) package with the command below.
```sh
$ npx expo install expo-font @expo-google-fonts/inter
```
Step 2: 
Add the config plugin to your [app config](/versions/latest/config/app/#plugins) file. The configuration must contain the path to the font file using [`fonts`](/versions/latest/sdk/font/#configurable-properties) property which takes an array of one or more font files. The path to the font file is defined from the font package inside the `node_modules` directory. For example, if you have a font package named `@expo-google-fonts/inter`, then the name of the file is **Inter_900Black.ttf**.
!!!IG7!!!
Step 3: 
After embedding the font with the config plugin, create a [new development build](/develop/development-builds/create-a-build/) and install it on your device or Android Emulator or iOS Simulator.
On Android, you can use the font file name. For example, `Inter_900Black`. On iOS, use the font and its weight name ([PostScript name](#what-is-postscript-name-of-a-font)). The example below demonstrates how to use [`Platform`](https://rn.nodejs.cn/docs/platform-specific-code#platform-module) to select the correct font family name for each platform:
!!!IG14!!!
!!!IG8!!!
### With `useFonts` hook
> **Note:** Loading a Google Font using `useFonts` hook has same benefits and limitations as embedding a custom font on your own. See [using a local font file with `useFonts` hook](#with-usefonts-hook) for more information.
Each google Fonts package provides the `useFonts` hook to load the fonts asynchronously. This hook keeps track of the loading state and loads the font when an app is initialized. The font package also imports the font file so you don't have to explicitly import it.
Step 1: 
Install the Google Fonts package, `expo-font` and `expo-splash-screen` libraries.
```sh
$ npx expo install @expo-google-fonts/inter expo-font expo-splash-screen
```
The [`expo-splash-screen`](/versions/latest/sdk/splash-screen/) library provides `SplashScreen` component that you can use to prevent rendering the app until the font is loaded and ready.
Step 2: 
After installing the font package, map the font using the `useFonts` hook in a top level component such as the root layout (**app/layout.tsx**) file in your project:
!!!IG9!!!
Step 3: 
Use the font on the `<Text>` by using `fontFamily` style prop in a React component:
!!!IG10!!!
## Additional information
### Minimal example
!!!IG15!!!
### Beyond OTF and TTF
If your font is in format other than OTF or TTF, you have to [customize the Metro bundler configuration to include it as an extra asset](/guides/customizing-metro#adding-more-file-extensions-to-assetexts) for it to work. In some cases, rendering a font format that a platform doesn't support may cause your app to crash.
For reference, the following table provides the list formats that work on each native platform:
| Format | Android     | iOS         | Web         |
| ------ | ----------- | ----------- | ----------- |
| bdf    | <NoIcon />  | <NoIcon />  | <NoIcon />  |
| dfont  | <YesIcon /> | <NoIcon />  | <NoIcon />  |
| eot    | <NoIcon />  | <NoIcon />  | <YesIcon /> |
| fon    | <NoIcon />  | <NoIcon />  | <NoIcon />  |
| otf    | <YesIcon /> | <YesIcon /> | <YesIcon /> |
| ps     | <NoIcon />  | <NoIcon />  | <NoIcon />  |
| svg    | <NoIcon />  | <NoIcon />  | <YesIcon /> |
| ttc    | <NoIcon />  | <NoIcon />  | <NoIcon />  |
| ttf    | <YesIcon /> | <YesIcon /> | <YesIcon /> |
| woff   | <NoIcon />  | <YesIcon /> | <YesIcon /> |
| woff2  | <NoIcon />  | <YesIcon /> | <YesIcon /> |
### Platform built-in fonts
If you don't want to use a custom font by specifying a `fontFamily`, platform's default font will be used. Each platform has a set of built in fonts. On Android, the default font is Roboto. On iOS, it's SF Pro.
A platform's default font is usually easy-to-read. However, don't be surprised when the system default font is changed to use another font that is not easy to read. In this case, use your custom font so you have precise control over what the user will see.
### Handle `@expo/vector-icons` initial load
When the icons from `@expo/vector-icons` library load for the first time, they appear as invisible icons in your app. Once they load, they're cached for all the app's subsequent usage. To avoid showing invisible icons on your app's first load, preload during the initial loading screen with [`useFonts`](/versions/latest/sdk/font/#usefontsmap). For example:
!!!IG11!!!
Now, you can use any icon from the `Ionicons` library in a React component:
!!!IG12!!!
!!!IG16!!!
### Loading a remote font directly from the web
> **warning** **If you're loading remote fonts, make sure they are being served from an origin with CORS properly configured**. If you don't do this, your remote font might not load properly on the web platform.
Loading fonts from a local asset is the safest way to load a font in your app. When including fonts as local assets, after you submit your app to the app stores, these fonts are bundled with the app download and will be available immediately. You don't have to worry about CORS or other potential issues.
However, loading a font file directly from web is done by replacing the `require('./assets/fonts/FontName.otf')` with the URL of your font as shown in the example below.
#### Using a remote font
!!!IG13!!!


## 资源

了解如何在项目中使用静态资源，包括图片、视频、声音、数据库文件和字体。

静态资源是与应用的二进制文件（原生二进制文件）打包在一起的文件。此文件类型不是包含应用代码的应用 JavaScript 打包包的一部分。常见的静态资源类型包括图片、视频、声音、SQLite 的数据库文件和字体。这些资源可以从你的项目本地提供，也可以通过网络远程提供。
¥A **static asset** is a file that is bundled with your app's binary (native binary). This file type is not part of your app's JavaScript bundle which contain your app's code. Common types of static assets include images, videos, sounds, database files for SQLite, and fonts. These assets can be served locally from your project or remotely over the network.
本指南介绍了在项目中加载和使用静态资源的不同方式，还提供了有关如何优化和最小化资源的其他信息。
¥This guide covers different ways you can load and use static assets in your project and also provides additional information on how to optimize and minify assets.
<a id="serve-an-asset-locally"></a>
## 在本地提供资源
¥Serve an asset locally
当资源存储在项目的文件系统中时，它可以在构建时嵌入到应用二进制文件中或在运行时加载。你可以使用 `require` 或 `import` 语句将其像 JavaScript 模块一样导入。
¥When an asset is stored in your project's file system, it can be embedded in your app binary at build time or loaded at runtime. You can import it like a JavaScript module using `require` or `import` statements.
例如，要在 App.js 中渲染名为 example.png 的图片，你可以使用 `require` 从项目的 assets/images 目录导入图片并将其传递给 `<Image>` 组件：
¥For example, to render an image called **example.png** in **App.js**, you can use `require` to import the image from the project's **assets/images** directory and pass it to the `<Image>` component:
```tsx app/index.tsx
<Image source={require('./assets/images/example.png')} />
```
在上面的例子中，打包器读取导入图片的元数据并自动提供宽度和高度。欲了解更多信息，请参阅 [静态图片资源](https://rn.nodejs.cn/docs/images#static-image-resources)。
¥In the above example, the bundler reads the imported image's metadata and automatically provides the width and height. For more information, see [Static Image Resources](https://rn.nodejs.cn/docs/images#static-image-resources).
`expo-image` 和 `expo-file-system` 等库的工作方式与使用本地资源的 `<Image>` 组件类似。
¥Libraries such as `expo-image` and `expo-file-system` work similarly to the `<Image>` component with local assets.
<a id="how-are-assets-served-locally"></a>
### 资源如何在本地提供服务
¥How are assets served locally
在开发过程中，本地存储的资源通过 HTTP 提供服务。它们会在生产应用的构建时自动打包到你的应用二进制文件中，并从设备上的磁盘提供服务。
¥Locally stored assets are served over HTTP in development. They are automatically bundled into your app binary at the build time for production apps and served from disk on a device.
<a id="load-an-asset-at-build-time-with-expo-asset-config-plugin"></a>
### 使用 `expo-asset` 配置在构建时加载资源插件
¥Load an asset at build time with `expo-asset` config plugin
> 注意：`expo-asset` 配置插件仅适用于 SDK 51 及更高版本。如果你使用的是较旧的 SDK，则可以加载 [使用 `useAssets` 钩子](#load-an-asset-at-runtime-with-useassets-hook)。
>
> ¥**Note:** The `expo-asset` config plugin is only available for SDK 51 and above. If you are using an older SDK, you can load a [using the `useAssets` hook](#load-an-asset-at-runtime-with-useassets-hook).
要在构建时加载资源，你可以使用 `expo-asset` 库中的 [配置插件](/versions/latest/sdk/asset/#example-appjson-with-config-plugin)。该插件会将资源文件嵌入到你的原生项目中。
¥To load an asset at build time, you can use the [config plugin](/versions/latest/sdk/asset/#example-appjson-with-config-plugin) from the `expo-asset` library. This plugin will embed the asset file in your native project.
Step 1: 
Install the `expo-asset` library.
```sh
$ npx expo install expo-asset
```
Step 2: 
Add the config plugin to your project's [app config](/versions/latest/config/app/#plugins) file. The configuration must contain the path to the asset file using [`assets`](/versions/latest/sdk/asset/#configurable-properties) property which takes an array of one or more files or directories to link to the native project.
The path to each asset file must be relative to your project's root since the app config file is located in the project's root directory.
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-asset",
        {
          "assets": ["./assets/images/example.png"]
        }
      ]
    ]
  }
}
```
Step 3: 
After embedding the asset with the config plugin, [create a new development build](/develop/development-builds/create-a-build/). Now, you can import and use the asset in your project without using a `require` or an `import` statement.
For example, the **example.png** is linked by the above config plugin. You can directly import it into your component and use its resource name as the URI. Note that when rendering assets without using `require`, you need to explicitly provide a width / height.
```tsx app/index.tsx
import { Image } from 'expo-image';
export default function HomeScreen() {
  return <Image source={{ uri: 'example' }} style={{ width: 100, height: 100 }} />;
}
```
> **info** Different file formats are supported with the `expo-asset` config plugin. For more information on these formats, see [Assets API reference](/versions/latest/sdk/asset/#configurable-properties). If you don't see a file format supported by the config plugin, you can use the [`useAssets`](#load-an-asset-at-runtime-with-useassets-hook) hook to load the asset at runtime.
### Load an asset at runtime with `useAssets` hook
The `useAssets` hook from `expo-asset` library allows loading assets asynchronously. This hook downloads and stores an asset locally and after the asset is loaded, it returns a list of that asset's instances.
Step 1: 
Install the `expo-asset` library.
```sh
$ npx expo install expo-asset
```
Step 2: 
Import the [`useAssets`](/versions/latest/sdk/asset/#useassetsmoduleids) hook from the `expo-asset` library in your screen component:
```tsx app/index.tsx
import { useAssets } from 'expo-asset';
export default function HomeScreen() {
  const [assets, error] = useAssets([
    require('path/to/example-1.jpg'),
    require('path/to/example-2.png'),
  ]);
  return assets ? <Image source={assets[0]} /> : null;
}
```
## Serve an asset remotely
When an asset is served remotely, it is not bundled into the app binary at build time. You can use the URL of the asset resource in your project if it is hosted remotely. For example, pass the URL to the `<Image>` component to render a remote image:
```jsx App.js
import { Image } from 'expo-image';
function App() {
  return (
    <Image source={{ uri: 'https://example.com/logo.png' }} style={{ width: 50, height: 50 }} />
  );
}
```
There is no guarantee about the availability of images served remotely using a web URL because an internet connection may not be available, or the asset might be removed.
Additionally, loading assets remotely also requires you to provide an asset's metadata. In the above example, since the bundler cannot retrieve the image's width and height, those values are passed explicitly to the `<Image>` component. If you don't, the image will default to 0px by 0px.
## Additional information
### Manual optimization methods
#### Images
You can compress images using the following:
- [`guetzli`](https://github.com/google/guetzli)
- [`pngcrush`](https://pmt.sourceforge.io/pngcrush/)
- [`optipng`](http://optipng.sourceforge.net/)
Some image optimizers are lossless. They re-encode your image to be smaller without any change or loss in the pixels displayed. When you need each pixel to be untouched from the original image, a lossless optimizer and a lossless image format like PNG are a good choice.
Other image optimizers are lossy. The optimized image differs from the original image. Often, lossy optimizers are more efficient because they discard visual information that reduces file size while making the image look nearly identical to humans. Tools like `imagemagick` can use comparison algorithms like [SSIM](https://en.wikipedia.org/wiki/Structural_similarity) to show how similar two images look. It's quite common for an optimized image that is over 95% similar to the original image to be far less than 95% of the original file size.
#### Other assets
For assets like GIFs or videos, or non-code and non-image assets, it's up to you to optimize and minify those assets.
>
注意：GIF 是一种非常低效的格式。现代视频编解码器可以生成更小、质量更好的文件。
¥**Note**: GIFs are a very inefficient format. Modern video codecs can produce significantly smaller file sizes with better quality.
<a id="fonts"></a>
### 字体
¥Fonts
有关如何向应用添加自定义字体的更多信息，请参阅 [添加自定义字体](/develop/user-interface/fonts/#add-a-custom-font)。
¥See [Add a custom font](/develop/user-interface/fonts/#add-a-custom-font) for more information on how to add a custom font to your app.


## 颜色主题

了解如何在你的应用中支持浅色和夜间模式。

应用支持浅色和深色配色方案很常见。以下是 Expo 项目中支持两种模式的示例：
¥It's common for apps to support light and dark color schemes. Here is an example of how supporting both modes looks in an Expo project:
<a id="configuration"></a>
## 配置
¥Configuration
>  **info** 对于 Android 和 iOS 项目，需要进行其他配置才能支持在明夜间模式之间切换。对于 Web，无需额外配置。
>
> ¥For Android and iOS projects, additional configuration is required to support switching between light and dark mode. For web, no additional configuration is required.
要配置支持的外观样式，你可以在项目的 [应用配置](/versions/latest/config/app) 中使用 [`userInterfaceStyle`](/versions/latest/config/app/#userinterfacestyle) 属性。默认情况下，当你使用 [默认模板](/get-started/create-a-project/) 创建新项目时，此属性默认设置为 `automatic`。
¥To configure supported appearance styles, you can use the [`userInterfaceStyle`](/versions/latest/config/app/#userinterfacestyle) property in your project's [app config](/versions/latest/config/app). By default, this property is set to `automatic` when you create a new project with the [default template](/get-started/create-a-project/).
这是一个配置示例：
¥Here is an example configuration:
```json app.json
{
  "expo": {
    "userInterfaceStyle": "automatic"
  }
}
```
你还可以通过将 [`android.userInterfaceStyle`](/versions/latest/config/app/#userinterfacestyle-2) 或 [`ios.userInterfaceStyle`](/versions/latest/config/app/#userinterfacestyle-1) 设置为首选值来为特定平台配置 `userInterfaceStyle` 属性。
¥You can also configure `userInterfaceStyle` property for a specific platforms by setting either [`android.userInterfaceStyle`](/versions/latest/config/app/#userinterfacestyle-2) or [`ios.userInterfaceStyle`](/versions/latest/config/app/#userinterfacestyle-1) to the preferred value.
>  **info** 如果此属性不存在，应用将默认为 `light` 样式。
>
> ¥The app will default to the `light` style if this property is absent.
创建开发版本时，你必须安装 [`expo-system-ui`](/versions/latest/sdk/system-ui/#installation) 以支持 Android 的外观样式。否则，`userInterfaceStyle` 属性将被忽略。
¥When you are creating a development build, you have to install [`expo-system-ui`](/versions/latest/sdk/system-ui/#installation) to support the appearance styles for Android. Otherwise, the `userInterfaceStyle` property is ignored.
```sh
$ npx expo install expo-system-ui
```
如果项目配置错误且未安装 `expo-system-ui`，则终端中将显示以下警告：
¥If the project is misconfigured and doesn't have `expo-system-ui` installed, the following warning will be shown in the terminal:
```sh
» android: userInterfaceStyle: Install expo-system-ui in your project to enable this feature.
```
还可以使用以下命令检查项目是否配置错误：
¥You can also use the following command to check if the project is misconfigured:
```sh
$ npx expo config --type introspect
```
Note: Using bare React Native app?
---
#### Android
Ensure that the `uiMode` flag is present on your `MainActivity` (and any other activities where this behavior is desired) in **AndroidManifest.xml**:
```xml
<activity android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode">
```
Implement the `onConfigurationChanged` method in **MainActivity.java**:
```java
import android.content.Intent;
import android.content.res.Configuration;
public class MainActivity extends ReactActivity {
  @Override
  public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    Intent intent = new Intent("onConfigurationChanged");
    intent.putExtra("newConfig", newConfig);
    sendBroadcast(intent);
  }
}
```
#### iOS
You can configure supported styles with the [`UIUserInterfaceStyle`](https://developer.apple.com/documentation/bundleresources/information_property_list/uiuserinterfacestyle) key in your app **Info.plist**. Use `Automatic` to support both light and dark modes.
---
### Supported appearance styles
The `userInterfaceStyle` property supports the following values:
- `automatic`: Follow system appearance settings and notify about any change the user makes.
- `light`: Restrict the app to support light theme only.
- `dark`: Restrict the app to support dark theme only.
## Detect the color scheme
To detect the color scheme in your project, use `Appearance` or `useColorScheme` from `react-native`:
```tsx app/index.tsx
import { Appearance, useColorScheme } from 'react-native';
```
Then, you can use `useColorScheme()` hook as shown below:
```tsx app/index.tsx
function MyComponent() {
  let colorScheme = useColorScheme();
  if (colorScheme === 'dark') {
    // render some dark thing
  } else {
    // render some light thing
  }
}
```
In some cases, you will find it helpful to get the current color scheme imperatively with [`Appearance.getColorScheme()` or listen to changes with `Appearance.addChangeListener()`](https://rn.nodejs.cn/docs/appearance).
## Additional information
### Minimal example
#### useColorScheme example
```tsx
import { StatusBar } from 'expo-status-bar';
export default function App() {
  const colorScheme = useColorScheme();
  const themeTextStyle = colorScheme === 'light' ? styles.lightThemeText : styles.darkThemeText;
  const themeContainerStyle =
    colorScheme === 'light' ? styles.lightContainer : styles.darkContainer;
  return (
    <View style={[styles.container, themeContainerStyle]}>
      <Text style={[styles.text, themeTextStyle]}>Color scheme: {colorScheme}</Text>
      <StatusBar />
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  text: {
    fontSize: 20,
  },
  lightContainer: {
    backgroundColor: '#d0d0c0',
  },
  darkContainer: {
    backgroundColor: '#242c40',
  },
  lightThemeText: {
    color: '#242c40',
  },
  darkThemeText: {
    color: '#d0d0c0',
  },
});
```
### Tips
While you are developing your project, you can change your simulator's or device's appearance by using the following shortcuts:
- If using an Android Emulator, you can run `adb shell "cmd uimode night yes"` to enable dark mode, and `adb shell "cmd uimode night no"` to disable dark mode.
- If using a physical Android device or an Android Emulator, you can toggle the system dark mode setting in the device's settings.
- If working with an iOS emulator locally, you can use the <kbd>Cmd ⌘</kbd> + <kbd>Shift</kbd> + <kbd>a</kbd>
用于在亮夜间模式之间切换的快捷方式。
¥shortcut to toggle between light and dark modes.


## 动画

了解如何集成 React Native 动画并将其用于你的 Expo 项目。

动画是增强和提供更好用户体验的好方法。在你的 Expo 项目中，你可以使用 React Native 中的 [动画 API](https://rn.nodejs.cn/docs/next/animations)。但是，如果你想使用性能更好的更高级动画，可以使用 [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/) 库。它提供了一个 API，可以简化创建流畅、强大且可维护的动画的过程。
¥Animations are a great way to enhance and provide a better user experience. In your Expo projects, you can use the [Animated API](https://rn.nodejs.cn/docs/next/animations) from React Native. However, if you want to use more advanced animations with better performance, you can use the [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/) library. It provides an API that simplifies the process of creating smooth, powerful, and maintainable animations.
<a id="installation"></a>
## 安装
¥Installation
如果你使用 [这篇博文](/get-started/create-a-project/) 创建了项目，则可以跳过安装 `react-native-reanimated`。此库已安装。否则，请通过运行以下命令进行安装：
¥You can skip installing `react-native-reanimated` if you have created a project using [the default template](/get-started/create-a-project/). This library is already installed. Otherwise, install it by running the following command:
```sh
$ npx expo install react-native-reanimated
```
<a id="usage"></a>
## 用法
¥Usage
<a id="minimal-example"></a>
### 最小的例子
¥Minimal example
下面的例子展示了如何使用 `react-native-reanimated` 库创建一个简单的动画。有关 API 和高级用法的更多信息，请参阅 [`react-native-reanimated` 文档](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/your-first-animation)。
¥The following example shows how to use the `react-native-reanimated` library to create a simple animation. For more information on the API and advanced usage, see [`react-native-reanimated` documentation](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/your-first-animation).
#### Using react-native-reanimated
  ```tsx
import Animated, {
  useSharedValue,
  withTiming,
  useAnimatedStyle,
  Easing,
} from 'react-native-reanimated';
import { View, Button, StyleSheet } from 'react-native';
export default function AnimatedStyleUpdateExample() {
  const randomWidth = useSharedValue(10);
  const config = {
    duration: 500,
    easing: Easing.bezier(0.5, 0.01, 0, 1),
  };
  const style = useAnimatedStyle(() => {
    return {
      width: withTiming(randomWidth.value, config),
    };
  });
  return (
    <View style={styles.container}>
      <Animated.View style={[styles.box, style]} />
      <Button
        title="toggle"
        onPress={() => {
          randomWidth.value = Math.random() * 350;
        }}
      />
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  box: {
    width: 100,
    height: 80,
    backgroundColor: 'black',
    margin: 30,
  },
});
```
<a id="other-animation-libraries"></a>
## 其他动画库
¥Other animation libraries
你可以在 Expo 项目中使用其他动画包，例如 [莫蒂](https://moti.fyi/)。它适用于 Android、iOS 和 Web。
¥You can use other animation packages such as [Moti](https://moti.fyi/) in your Expo project. It works on Android, iOS, and web.


## 存储数据

了解可用于在 Expo 项目中存储数据的不同库。

存储数据对于移动应用中实现的功能至关重要。根据你要存储的数据类型和应用的安全要求，可以使用不同的方法在 Expo 项目中保存数据。此页面列出了各种库，可帮助你确定哪种解决方案最适合你的项目。
¥Storing data can be essential to the features implemented in your mobile app. There are different ways to save data in your Expo project depending on the type of data you want to store and the security requirements of your app. This page lists a variety of libraries to help you decide which solution is best for your project.
<a id="expo-securestore"></a>
## Expo 安全存储
¥Expo SecureStore
`expo-secure-store` 提供了一种在设备本地加密和安全存储键值对的方法。
¥`expo-secure-store` provides a way to encrypt and securely store key-value pairs locally on the device.
<a id="expo-filesystem"></a>
## Expo 文件系统
¥Expo FileSystem
`expo-file-system` 提供对设备本地存储的文件系统的访问。在 Expo Go 中，每个项目都有一个单独的文件系统，并且无法访问其他 Expo 项目的文件。但是，它可以将其他项目共享的内容保存到本地文件系统，并与其他项目共享本地文件。它还能够从网络 URL 上传和下载文件。
¥`expo-file-system` provides access to a file system stored locally on the device. Within Expo Go, each project has a separate file system and no access to other Expo projects' files. However, it can save content shared by other projects to the local filesystem and share local files with other projects. It is also capable of uploading and downloading files from network URLs.
<a id="expo-sqlite"></a>
## Expo SQLite
`expo-sqlite` 包使你的应用可以访问可通过类似 WebSQL 的 API 进行查询的数据库。数据库在应用重新启动后保留。你可以使用它来导入现有数据库、打开数据库、创建表、插入项目、查询和显示结果以及使用准备好的语句。
¥`expo-sqlite` package gives your app access to a database that can be queried through a WebSQL-like API. The database is persisted across restarts of your app. You can use it for importing an existing database, opening databases, creating tables, inserting items, querying and displaying results, and using prepared statements.
<a id="async-storage"></a>
## 异步存储
¥Async Storage
[异步存储](https://react-native-async-storage.github.io/async-storage/) 是 React Native 应用的异步、未加密、持久键值存储。它有一个简单的 API，是存储少量数据的不错选择。对于存储不需要加密的数据（例如用户首选项或应用状态）来说，它也是一个不错的选择。
¥[Async Storage](https://react-native-async-storage.github.io/async-storage/) is an asynchronous, unencrypted, persistent key-value storage for React Native apps. It has a simple API and is a good choice for storing small amounts of data. It is also a good choice for storing data that does not need encryption, such as user preferences or app state.
<a id="other-libraries"></a>
## 其他库
¥Other libraries
还有其他库可用于存储不同目的的数据。例如，你的项目可能不需要加密，或者正在寻找类似于异步存储的更快的解决方案。
¥There are other libraries available for storing data for different purposes. For example, you might not need encryption in your project or are looking for a faster solution similar to Async Storage.
我们建议查看 [React Native 获取库列表](https://reactnative.directory/?search=storage) 来帮助你存储项目数据。
¥We recommend checking out [React Native for a list of libraries](https://reactnative.directory/?search=storage) to help you store your project's data.


## 下一步

有用资源列表，可帮助你了解有关在应用中实现导航和 UI 的更多信息。

# 开发构建

## 开发构建简介

为什么使用开发版本以及如何开始使用。

“开发构建”是指包含 [`expo-dev-client`](/versions/latest/sdk/dev-client/) 库的应用的 "调试" 构建版本。此库增强了内置的 React Native 开发工具，并提供了额外的功能，例如支持检查网络请求和 "launcher" UI，可让你在不同的开发服务器（例如在你机器或队友机器上运行的服务器之间切换）和应用部署（例如使用 EAS 更新发布的更新）。
¥**Development build** is the term that we use for a "Debug" build of an app that includes the [`expo-dev-client`](/versions/latest/sdk/dev-client/) library. This library augments the built-in React Native development tooling with additional capabilities, such as support for inspecting network requests and a "launcher" UI that lets you switch between different development servers (such as between a server running on your machine or a teammate's machine) and deployments of your app (such as published updates with EAS Update).
Note: Difference between Expo Go and development builds
---
When you create your first React Native project with `npx create-expo-app` and ran it with `npx expo start`, you most likely start off using the [Expo Go](https://expo.dev/go) app for development. Expo Go is a native app that the Expo team built and submitted to the [Google Play Store](https://play.google.com/store/apps/details?id=host.exp.exponent) and [Apple App Store](https://apps.apple.com/us/app/expo-go/id982107779) so you can get coding quickly. It is a sandbox app with a number of native libraries included within (see the [dependencies list](https://github.com/expo/expo/blob/main/apps/expo-go/package.json#L23)). This means that developers may update their app's JavaScript code on their local machine and see the changes on Expo Go.
A React Native app consists of two parts: the **native app (Expo Go)** and the **JavaScript bundle (`npx expo start`)**. It is immutable and when you're using the Expo Go app for development, you can only rely on the native code and tools that exist in Expo Go. The only way to get around it is to build your native app yourself instead of using Expo's pre-packaged sandbox. This is exactly what a **Development Build is, your own version of Expo Go**, where you are free to use any native libraries and change any native config.
---
Note: Native app and JavaScript bundle
---
The **native app (Expo Go)** is immutable once installed. Native build tools are required to create this bundle, and it needs to be signed to be installable on real devices. To add a new library with native code or change metadata that is shipped with the app (for example app name, icon, splash screen) the app needs to be rebuilt and re-installed on the device.
The **JavaScript bundle (`npx expo start`)** is where your app's UI code and business logic are. In production apps, there is one **main.js** bundle that is shipped with the app itself. In development, this JS bundle is live reloaded from your local machine. The main role of React Native is to provide a way for the JavaScript code to access the native APIs (Image, Camera, Notifications, and more). However, only APIs and libraries that were bundled in the **native app** can be used.
---
Video Tutorial: [Expo Go & Development Builds: which should you use?](https://www.youtube.com/watch?v=FdjczjkwQKE)
## Why use a development build (a.k.a what _can't_ you do in Expo Go and why)
Expo Go is the perfect tool for learning, prototyping, and experimenting, but most production apps will convert to using development builds sooner rather than later. It helps to know exactly what is _impossible_ in Expo Go and _why_, so you can make an informed decision on when and why to make this move.
Note: Use libraries with native code that aren't in Expo Go
---
Consider [`react-native-webview`](/versions/latest/sdk/webview/) as an example, a library that contains native code, but [is included in Expo Go](https://github.com/expo/expo/blob/main/apps/expo-go/package.json#L23). When you run `npx expo install react-native-webview` command in your project, it will install the library in your **node_modules** directory, which includes both the JS code and the native code. But the JS bundle you are building _only_ uses the JS code. Then, your JS bundle gets uploaded to Expo Go, and it interacts with the native code that was already bundled with the app.
Instead, when you try to use a library that is not included, for example, [`react-native-firebase`](/guides/using-firebase/#using-react-native-firebase), then you can use the JS code and hot reload the new bundle into Expo Go but it will immediately error because the JS code tries to call the native code from the React Native Firebase package that does not exist in Expo Go. There is no way to get the native code into the Expo Go app unless it was already included in the bundle that was uploaded to the app stores.
---
Note: Test changes in app icon, name, splash screen
---
If you're developing your app in Expo Go only, you can build a store version that will use your provided values and images; it just won't be possible to test it in Expo Go.
These native assets are shipped with the native bundle and are immutable once the app is installed. The Expo Go app does show a splash screen, which is your app icon on a solid color background. This is a dev-only emulation to view how the splash screen will probably look. However, it is limited, for example, you cannot test `SplashScreen.setOptions` to animate the splash screen.
---
Note: Remote push notifications
---
While [in-app notifications](/versions/latest/sdk/notifications/) are available in Expo Go, remote push notifications (that is, sending a push notification from a server to the app) are not. This is because a push notification service should be tied to your own push notification certificates, and while it is possible to make it work in Expo Go, it often causes confusion for production builds. It is recommended to test remote push notifications in development builds so you can ensure parity in behavior between development and production.
---
Note: Implementing App/Universal links
---
Both [Android App Links](/linking/android-app-links/) and [iOS Universal Links](/linking/ios-universal-links/) require a two-way association between the native app and the website. In particular, it requires the native app to include the linked website's URL. This is impossible with Expo Go due to the aforementioned native code immutability.
---
Note: Open projects using older SDKs (iOS device only)
---
Expo Go can only support one SDK version at a time. When a new SDK version is released, Expo Go is updated to support the newer version, and this will be the only version of Expo Go available to install from the stores.
If you're developing on an Android Device, Android Emulator, or iOS Simulator, a compatible version of Expo Go can be [downloaded and installed](https://expo.dev/go). The only platform where this is impossible is iPhone devices because Apple does not support side-loading older versions of apps.
---


## 从 Expo 转换到开发版本

如何迁移你的 Expo Go 项目以使用开发版本。

要从 Expo Go 迁移到开发版本，你需要按照以下步骤操作：
¥To migrate from Expo Go to a development build, you'll need to follow the steps below:
Step 1: 
## Install the `expo-dev-client`
The Expo Dev Client library includes the launcher UI (shown in the screenshots below), dev menu, extensions to test over-the-air updates, and more. The Expo Go app has the dev menu built in, and that's why you need to install it separately for a development build.
```sh
$ npx expo install expo-dev-client
```
> We recommend using the `expo-dev-client` for the best development experience, but it is possible to use development builds without installing this library. If not using the dev client, in [Step 3](/develop/development-builds/expo-go-to-dev-build/#start-the-dev-client), start the bundler with `--dev-client`. Otherwise, it will default to opening in Expo Go.
Step 2: 
## Build your native app
With Expo Go, you only needed to build the JavaScript bundle, but with development builds you also need to compile the native app. With Expo, there are two parts to building your native app:
1. Generate the native **android** and/or **ios** directories ([read more](/develop/development-builds/expo-go-to-dev-build/#cng-and-prebuild) on when and how you'll need to do this)
2. Use native build tools to compile the native app(s)
Once you've built your native app, you won't need to build it again unless you add or update a library with native code, or change any native code or configuration, such as the app name.
> After generating your **android** and/or **ios** directories, make sure you add them to **.gitignore** instead of checking them into Git. This ensures you can always regenerate the code locally or on CI when needed and never have to edit native code manually.
### Option 1: Build on your local machine
To build a native app on your local machine, follow the setup your environment guides for [Android](/workflow/android-studio-emulator/) and [iOS](/workflow/ios-simulator/) platforms. This involves setting up and configuring native build tools like Android Studio for Android and Xcode for iOS.
Once you have everything set up, run the following command:
For Build for Android: 
```sh
$ npx expo run:android
```
For Build for iOS: 
```sh
$ npx expo run:ios
```
By default, this will build and install the app on an Android Emulator/iOS Simulator. If you need to run the build on your phone, plug it into your computer (on Android, select trust device and allow USB debugging if prompted, and on iOS, enable [developer mode](/get-started/set-up-your-environment/?mode=development-build&buildEnv=local&platform=ios&device=physical#plug-in-your-device-via-usb-and-enable-developer-mode)) and run the above commands with the `--device` flag.
### Option 2: Build on EAS
Building on EAS servers is useful when:
- You can't or don't want to set up your local development environment
- You want to build an iOS app but don't own a Mac
- You want to share the development builds with your team
Step 3: 
## Start the bundler
After building locally, `npx expo run:android|ios` will start the bundler automatically. But if you closed the bundler or are working on a dev client you built earlier, (re)start the Metro bundler with:
```sh
$ npx expo start
```
When your project has `expo-dev-client` installed, the bundler will print out **Using development build**, and the QR code it shows will link into the development build you created instead of Expo Go.
## Prebuild
[**Prebuild** ](/workflow/continuous-native-generation/#prebuild) is a concept unique to Expo projects. It refers to the process of generating the **android** and **ios** directories based on your local configuration and properties.
### When should you run prebuild
You will need to run prebuild locally if you are building via `npx expo run:android|ios`, and change any native dependencies or configuration, such as:
- Installing or updating a library containing native code
- Changing [app config](/workflow/configuration/)(`app.json`)
- Upgrading your Expo SDK version
In these cases, you'll want to rebuild the native directories with:
```sh
$ npx expo prebuild --clean
```
Then, rebuild your app with the updated native code, with:
For Build for Android: 
```sh
$ npx expo run:android
```
For Build for iOS: 
```sh
$ npx expo run:ios
```
<a id="when-you-dont-need-to-run-prebuild"></a>
### 何时不需要运行预构建
¥When you don't need to run prebuild
如果未找到现有的原生文件夹，所有 Expo 构建工具（`npx expo run:android|ios` 和 `eas build`）都将自动预构建。这意味着你首次运行 `npx expo run:android|ios` 或 `eas build` 时无需手动运行预构建。
¥All Expo build tools (`npx expo run:android|ios` and `eas build`) will **prebuild** automatically if no existing native folders are found. This means that there is no need to run prebuild manually when you're running `npx expo run:android|ios` for the first time or `eas build`.


## 在 EAS 上创建开发版本

了解如何为项目创建开发版本。

使用 `npx create-expo-app` 创建新的 Expo 应用时，你将从一个项目开始，在该项目中更新本地计算机上的 JavaScript 代码，并在 Expo Go 应用中查看更改。开发版本本质上是你自己的 Expo Go 版本，你可以自由使用任何原生库并更改任何原生配置。在本指南中，你将学习如何将运行在 Expo Go 上的项目转换为开发版本，这将使你的应用的原生端完全可定制。
¥When you create a new Expo app with `npx create-expo-app`, you start off with a project where you update the JavaScript code on your local machine and view the changes in the Expo Go app. A **development build** is essentially **your own version of Expo Go** where you are free to use any native libraries and change any native config. In this guide, you will learn how to convert your project that runs on Expo Go into a development build, which will make the native side of your app fully customizable.
Video Tutorial: [How to create a development build](https://www.youtube.com/watch?v=uQCE9zl3dXU)
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
这些说明假设你已经有一个在 Expo Go 上运行的 Expo 项目。
¥The instructions assume you already have an existing Expo project that runs on Expo Go.
构建原生应用的要求取决于你使用的平台、构建的目标平台以及你是在 EAS 上构建还是在本地机器上构建。
¥The requirements for building the native app depend on which platform you are using, which platform you are building for, and whether you want to build on EAS or on your local machine.
Note: Build on EAS
---
This is the easiest way to build your native app, as it requires no native build tools on your side. The builds happen on the EAS servers, which makes it possible to trigger iOS builds from non-macOS platforms.
|             | Android    | iOS Simulator | iPhone device   |
| ----------- | ---------- | ------------- | --------------- |
| **macOS**   | <YesIcon/> | <YesIcon/>    | <YesIcon/> (\*) |
| **Windows** | <YesIcon/> | <YesIcon/>    | <YesIcon/> (\*) |
| **Linux**   | <YesIcon/> | <YesIcon/>    | <YesIcon/> (\*) |
(\*) All builds that run on an iPhone device require a paid [Apple Developer](https://developer.apple.com) account for build signing.
---
Note: Build locally using the EAS CLI
---
Any EAS CLI command can be built on your local machine with the `--local` flag. This requires your local [development environment](https://rn.nodejs.cn/docs/set-up-your-environment?os=macos&platform=ios) to be set up with native build tools. Read more about [local app development](/build-reference/local-builds/).
|             | Android           | iOS Simulator | iPhone device   |
| ----------- | ----------------- | ------------- | --------------- |
| **macOS**   | <YesIcon/>        | <YesIcon/>    | <YesIcon/> (\*) |
| **Windows** | <YesIcon/> (\*\*) | <NoIcon />    | <NoIcon />      |
| **Linux**   | <YesIcon/>        | <NoIcon />    | <NoIcon />      |
(\*) All builds that run on an iPhone device require a paid [Apple Developer](https://developer.apple.com) account for build signing.
(\*\*) No first-class support, but possible with [WSL](http://expo.fyi/wsl.md).
---
Note: Build locally without EAS
---
To build locally without EAS requires your local [development environment](https://rn.nodejs.cn/docs/set-up-your-environment?os=macos&platform=ios) to be set up with native build tools. This is the only way to test your iOS build on an iPhone device without a paid Apple Developer Account (only possible on macOS). Read more about [local app compilation](/guides/local-app-development/#local-app-compilation) and see the [Expo Go to Development Build](/develop/development-builds/expo-go-to-dev-build/) guide.
|             | Android    | iOS Simulator | iPhone device |
| ----------- | ---------- | ------------- | ------------- |
| **macOS**   | <YesIcon/> | <YesIcon/>    | <YesIcon/>    |
| **Windows** | <YesIcon/> | <NoIcon />    | <NoIcon />    |
| **Linux**   | <YesIcon/> | <NoIcon />    | <NoIcon />    |
---
## Get started
For detailed, step-by-step instructions, see our [EAS Tutorial](/tutorial/eas/introduction). Available also as a [tutorial series](https://www.youtube.com/playlist?list=PLsXDmrmFV_AS14tZCBin6m9NIS_VCUKe2) on YouTube.
Step 1: 
### Install expo-dev-client
```sh
$ npx expo install expo-dev-client
```
Note: Are you using this library in a existing (bare) React Native apps?
---
Apps that don't use [Continuous Native Generation](/workflow/continuous-native-generation/) or are created with `npx react-native`, require further configuration after installing this library. See steps 1 and 2 from [Install `expo-dev-client` in an existing React Native app](/bare/install-dev-builds-in-bare/).
---
Step 2: 
### Build the native app (Android)
<Prerequisites numberOfRequirements={3}>
  <Requirement number={1} title="Expo account">
    Sign up for an [Expo](https://expo.dev/signup) account, if you haven't already.
  </Requirement>
  <Requirement number={2} title="EAS CLI">
    The [EAS CLI](/build/setup/#install-the-latest-eas-cli) installed and logged in.
    ```sh
$ npm install -g eas-cli && eas login
```
  </Requirement>
  <Requirement number={3} title="An Android Emulator (optional)">
    An [Android Emulator](/workflow/android-studio-emulator/) is optional if you want to test your
    app on an emulator.
  </Requirement>
</Prerequisites>
```sh
$ eas build --platform android --profile development
```
Read more about [Android builds on EAS](/tutorial/eas/android-development-build).
Step 2: 
### Build the native app (iOS Simulator)
<Prerequisites numberOfRequirements={3}>
  <Requirement number={1} title="Expo account">
    Sign up for an [Expo](https://expo.dev/signup) account, if you haven't already.
  </Requirement>
  <Requirement number={2} title="EAS CLI">
    The [EAS CLI](/build/setup/#install-the-latest-eas-cli) installed and logged in.
    ```sh
$ npm install -g eas-cli && eas login
```
  </Requirement>
  <Requirement number={3} title="macOS with iOS Simulator installed">
    iOS Simulators are available only on macOS. Make sure you have the [iOS
    Simulator](/workflow/ios-simulator/) installed.
  </Requirement>
</Prerequisites>
Edit `development` profile in **eas.json** and set the [`simulator`](/eas/json/#simulator) option to `true` (you have to create a separate profile for simulator builds if you also want to create iOS device builds for this project).
```json eas.json
{
  "build": {
    "development": {
      "ios": {
        "simulator": true
      }
    }
  }
}
```
```sh
$ eas build --platform ios --profile development
```
iOS Simulator builds can only be installed on simulators and not on real devices.
Read more about [iOS Simulator builds on EAS](/tutorial/eas/ios-development-build-for-simulators/).
Step 2: 
### Build the native app (iOS device)
<Prerequisites numberOfRequirements={3}>
  <Requirement number={1} title="Expo account">
    Sign up for an [Expo](https://expo.dev/signup) account, if you haven't already.
  </Requirement>
  <Requirement number={2} title="EAS CLI">
    The [EAS CLI](/build/setup/#install-the-latest-eas-cli) installed and logged in.
    ```sh
$ npm install -g eas-cli && eas login
```
  </Requirement>
  <Requirement number={3} title="Apple Developer account">
    A paid [Apple Developer](https://developer.apple.com/) account for creating [signing
    credentials](/app-signing/managed-credentials/#generating-app-signing-credentials) so the app
    could be installed on an iOS device.
  </Requirement>
</Prerequisites>
```sh
$ eas build --platform ios --profile development
```
iOS device builds can only be installed on iPhone devices and not on iOS Simulators.
Read more about [iOS device builds on EAS](/tutorial/eas/ios-development-build-for-devices/).
Step 3: 
### Install the app
You'll need to install the native app on your device, emulator, or simulator.
#### When building on EAS
If you create your development build on EAS, the CLI will prompt you to install the app after the build is finished. You can also install previous builds from the [expo.dev](https://expo.dev/) dashboard or using [Expo Orbit](https://expo.dev/orbit).
#### When building locally using EAS CLI
When building locally the output of the build will be an archive. You may drag and drop this on your Android Emulator/iOS Simulator to install it, or use [Expo Orbit](https://expo.dev/orbit) to install a build from your local machine.
Step 4: 
### Start the bundler
The development client built in **step 2** is the native side of your app (basically your own version of Expo Go). To continue developing, you'll also want to start the JavaScript bundler.
Depending on how you built the app, this may already be running, but if you close the process for any reason, there is no need to rebuild your development client. Simply restart the JavaScript bundler with:
```sh
$ npx expo start
```
This is the same command you would have used with Expo Go. It detects whether your project has `expo-dev-client` installed, in which case it will default to targeting your development build instead of Expo Go.
<a id="video-walkthroughs"></a>
## 视频演练
¥Video walkthroughs


## 使用开发版本

了解如何使用项目的开发版本。

通常，从头开始创建新的原生构建需要很长时间，以至于你可能会想切换任务并失去注意力。但是，在你的设备或模拟器/模拟器上安装了开发版本后，你无需等待原生构建过程，直到你 [更改底层原生代码](#rebuild-a-development-build) 为你的应用提供支持。
¥Usually, creating a new native build from scratch takes long enough that you'll be tempted to switch tasks and lose your focus. However, with the development build installed on your device or an emulator/simulator, you won't have to wait for the native build process until you [change the underlying native code](#rebuild-a-development-build) that powers your app.
<a id="add-error-handling"></a>
## 添加错误处理
¥Add error handling
在 App.&lbrace;js|tsx&rbrace; 或 [**app/_layout.tsx**](/router/basics/layout/#root-layout) 的顶部导入 `expo-dev-client`，以添加超出 React Native 默认提供的某些错误的额外上下文。特别是，`expo-dev-client` 将有助于检测与 JavaScript 和原生代码不匹配相关的情况，例如当缺少原生模块时，你应该进行新的开发构建。
¥Import `expo-dev-client` at the top of the **App.&lbrace;js|tsx&rbrace;** or [**app/_layout.tsx**](/router/basics/layout/#root-layout) to add additional context for certain errors beyond what is provided by default in React Native. In particular, `expo-dev-client` will help detect situations related to a mismatch between your JavaScript and native code, such as when a native module is missing and you should make a new development build.
```js App.js
import 'expo-dev-client';
```
> 这只会影响你进行此更改的应用。如果你想从单个开发应用加载多个项目，则需要将此导入语句添加到每个项目中。
>
> ¥This will only affect the application in which you make this change. If you want to load multiple projects from a single development app, you'll need to add this import statement to each project.
<a id="start-the-development-server"></a>
## 启动开发服务器
¥Start the development server
要开始开发，请运行以下命令来启动开发服务器：
¥To start developing, run the following command to start the development server:
```sh
$ npx expo start
```
要在开发客户端中打开项目：
¥To open the project inside your development client:
* 按 <kbd>a</kbd> 或 <kbd>i</kbd> 键在 Android 模拟器或 iOS 模拟器上打开你的项目。
  ¥Press <kbd>a</kbd> or <kbd>i</kbd> keys to open your project on an Android Emulator or an iOS Simulator.
* 在物理设备上，通过系统摄像头或 QR 码阅读器扫描 QR 码，以在设备上打开项目。
  ¥On a physical device, scan the QR code from your system's camera or a QR code reader to open the project on your device.
<a id="the-launcher-screen"></a>
## 启动器屏幕
¥The launcher screen
如果你从设备的主屏幕启动开发版本，你将看到启动器屏幕，如下所示：
¥If you launch the development build from your device's Home screen, you will see your launcher screen, which looks similar to the following:
如果在你的本地网络上检测到打包程序，或者你已在 Expo CLI 和开发版本中登录 Expo 账户，则可以直接从此屏幕连接到它。否则，你可以通过扫描 Expo CLI 显示的二维码进行连接。
¥If a bundler is detected on your local network, or if you have signed in to an Expo account in both Expo CLI and your development build, you can connect to it directly from this screen. Otherwise, you can connect by scanning the QR code displayed by the Expo CLI.
<a id="rebuild-a-development-build"></a>
## 重建开发版本
¥Rebuild a development build
如果你向项目添加包含原生代码 API 的库（例如 [`expo-secure-store`](/versions/latest/sdk/securestore/)），则必须重新构建开发客户端。这是因为当将库作为项目的依赖安装时，库的原生代码不会自动包含在开发客户端中。
¥If you add a library to your project that contains native code APIs, for example, [`expo-secure-store`](/versions/latest/sdk/securestore/), you will have to rebuild the development client. This is because the native code of the library is not included in the development client automatically when installing the library as a dependency on your project.
<a id="debug-a-development-build"></a>
## 调试开发版本
¥Debug a development build
当你需要时，你可以通过在 Expo CLI 中按 <kbd>Cmd ⌘</kbd> + <kbd>d</kbd> 或 <kbd>Ctrl</kbd> + <kbd>d</kbd> 或摇动手机或平板电脑来访问菜单。在这里，你将能够访问开发版本的所有功能、你需要的任何调试功能，或者切换到应用的不同版本。
¥When you need to, you can access the menu by pressing <kbd>Cmd ⌘</kbd> + <kbd>d</kbd> or <kbd>Ctrl</kbd> + <kbd>d</kbd> in Expo CLI or by shaking your phone or tablet. Here you'll be able to access all of the functions of your development build, any debugging functionality you need, or switch to a different version of your app.
有关详细信息，请参阅 [调试](/debugging/runtime-issues/) 指南。
¥See [Debugging](/debugging/runtime-issues/) guide for more information.


## 与你的团队共享开发构建

了解如何安装并与你的团队共享开发或在多个设备上运行它。

Android 和 iOS 都提供了直接在设备上安装应用版本的方法。这使你可以完全控制在设备上放置特定版本，从而使你能够快速迭代并同时让应用的多个版本可供审查。你还可以与你的团队共享它或在多个测试设备上运行它。
¥Android and iOS both offer ways to install a build of your application directly on devices. This gives you full control of putting specific builds on devices, allowing you to iterate quickly and have multiple builds of your application available for review at the same time. You can also share it with your team or run it on multiple test devices.
<a id="share-the-url"></a>
## 共享网址
¥Share the URL
当开发构建准备就绪时，将为你的构建生成一个可共享的 URL，其中包含有关如何启动和运行它的说明。你可以与队友一起使用此 URL 或将其发送到你的测试设备以安装构建版本。生成的 URL 对于你的项目构建是唯一的。
¥When a development build is ready, a shareable URL is generated for your build with instructions on how to get it up and running. You can use this URL with a teammate or send it to your test device to install the build. The URL generated is unique to the build for your project.
> 如果你在创建开发版本后注册任何新的 iOS 设备，则需要创建新的开发版本才能将其安装在这些设备上。欲了解更多信息，请参阅 [内部分配](/build/internal-distribution/)。
>
> ¥If you register any new iOS devices after creating a development build, you'll need to create a new development build to install it on those devices. For more information, see [internal distribution](/build/internal-distribution/).
<a id="use-the-eas-dashboard"></a>
### 使用 EAS 仪表盘
¥Use the EAS dashboard
你还可以将你的队友引导至 EAS 仪表板中的构建页面。从那里，他们可以直接在其设备上下载构建工件。
¥You can also direct your teammate to the build page in the EAS dashboard. From there, they can download the build artifact directly on their device.
<a id="use-eas-cli"></a>
### 使用 EAS CLI
¥Use EAS CLI
你的队友也可以使用 EAS CLI 下载和安装开发版本。他们必须确保它们是从与开发版本相关联的 Expo 账户签名的，然后才能运行以下命令：
¥Your teammate can also download and install the development build using EAS CLI. They have to make sure that they are signed from the Expo account associated with the development build and then can run the following command:
```sh
$ eas build:run --profile development
```
如果开发版本的配置文件名称与 `development` 不同，则将其与 `--profile` 一起使用。
¥If the profile name for the development build is different from `development`, use it instead with `--profile`.
<a id="ios-only-instructions"></a>
### 仅限 iOS 的说明
¥iOS-only instructions
> 如果你运行的是 iOS 16 或更高版本并且尚未打开开发者模式，则需要 [启用它](/guides/ios-developer-mode) 才能运行构建。（如果你使用的是企业配置，则这不适用。）
>
> ¥If you're running iOS 16 or above and haven't yet turned on Developer Mode, you'll need to [enable it](/guides/ios-developer-mode) before you can run your build. (This doesn't apply if you're using enterprise provisioning.)
你可以使用 `eas build:resign` 将适用于 iOS 的现有 .ipa 共同设计为新的临时配置文件。这有助于减少与团队分发的时间。例如，如果你想将新的测试设备添加到现有版本中，则可以使用此命令更新配置文件以包含该设备，而无需从头开始重建整个应用。欲了解更多信息，请参阅 [重新签署新凭证](/app-signing/app-credentials/#re-signing-new-credentials)。
¥You can use `eas build:resign` to codesign an existing **.ipa** for iOS to a new ad hoc provisioning profile. This helps reduce time when distributing with your team. For example, if you want to add a new test device to an existing build, you can use this command to update the provisioning profile to include the device without rebuilding the entire app from scratch. For more information, see [Re-signing new credentials](/app-signing/app-credentials/#re-signing-new-credentials).
<a id="next-steps"></a>
## 下一步
¥Next steps


## 工具、工作流程和扩展

详细了解使用开发版本时可用的不同工具、工作流程和扩展。

开发构建允许你快速迭代。但是，你可以扩展开发构建的功能，以便在团队工作时提供更好的开发者体验，或者自定义构建以满足你的需求。
¥Development builds allow you to iterate quickly. However, you can extend the capabilities of your development build to provide a better developer experience when working in teams or customize the build to suit your needs.
<a id="tools"></a>
## 工具
¥Tools
<a id="tunnel-urls"></a>
### 通道 URL
¥Tunnel URLs
有时，限制性网络条件导致难以连接到开发服务器。`npx expo start` 命令将你的开发服务器公开在可通过全球防火墙访问的公开 URL 上。如果你无法使用默认 LAN 选项连接到开发服务器，或者你想在开发过程中获得有关实现的反馈，则此选项会很有帮助。
¥Sometimes, restrictive network conditions make it difficult to connect to the development server. The `npx expo start` command exposes your development server on a publicly available URL that is accessible through firewalls from around the globe. This option is helpful if you are not able to connect to your development server with the default LAN option or if you want to get feedback on your implementation while you are developing.
要获取隧道 URL，请从命令行将 [`--tunnel` 旗](/more/expo-cli/#tunneling) 传递到 `npx expo start`。
¥To get a tunneled URL, pass the [`--tunnel` flag](/more/expo-cli/#tunneling) to `npx expo start` from the command line.
<a id="published-updates"></a>
### 已发布的更新
¥Published updates
EAS CLI 的 `eas update` 命令将 JavaScript 和资源文件的当前状态打包到优化的 "update" 中。此更新存储在 Expo 的托管服务上。应用的开发版本可以加载已发布的更新，而无需检查特定提交或让开发计算机保持运行。
¥EAS CLI's `eas update` command bundles the current state of your JavaScript and asset files into an optimized "update". This update is stored on a hosting service by Expo. A development build of your app can load published updates without needing to check out a particular commit or leave a development machine running.
<a id="manually-entering-an-updates-url"></a>
### 手动输入更新的 URL
¥Manually entering an update's URL
当开发版本启动时，它将公开 UI 以加载开发服务器或 "手动输入网址"。你可以手动提供将启动特定分支的 URL。URL 遵循以下模式：
¥When a development build launches, it will expose UI to load a development server, or to "Enter URL manually". You can provide a URL manually that will launch a specific branch. The URL follows this pattern:
```text
https://u.expo.dev/[your-project-id]?channel-name=[channel-name]
# Example
https://u.expo.dev/F767ADF57-B487-4D8F-9522-85549C39F43F?channel-name=main
```
要获取项目的 ID，请使用 [应用配置的 `expo.updates.url`](/versions/latest/config/app/#url) 字段中的 URL。要查看通道列表，请运行 `eas channel:list`。
¥To get your project's ID, use the URL in the [app config's `expo.updates.url`](/versions/latest/config/app/#url) field. To see a list of channels, run `eas channel:list`.
<a id="deep-linking-to-an-updates-url"></a>
### 深层链接到更新的 URL
¥Deep linking to an update's URL
你可以通过打开 `{scheme}://expo-development-client/?url={manifestUrl}` 形式的 URL 将应用加载到具有兼容的自定义客户端版本的设备上。你需要传递以下参数：
¥You can load your app on a device that has a compatible build of your custom client by opening a URL of the form `{scheme}://expo-development-client/?url={manifestUrl}`. You'll need to pass the following parameters:
| 参数            | value                                                                                        |
| ------------- | -------------------------------------------------------------------------------------------- |
| `scheme`      | 客户端的 URL 方案（默认为 `exp+{slug}`，其中 [`slug`](/versions/latest/config/app/#slug) 是应用配置中设置的值）      |
| `manifestUrl` | 要加载的更新清单的 URL 编码 URL。网址将为 `https://u.expo.dev/[your-project-id]?channel-name=[channel-name]` |
示例：
¥Example:
```text
exp+app-slug://expo-development-client/?url=https%3A%2F%2Fu.expo.dev%2F767ADF57-B487-4D8F-9522-85549C39F43F%2F%3Fchannel-name%3Dmain
```
上例中，`scheme` 为 `exp+app-slug`，`manifestUrl` 为项目，项目 ID 为 `F767ADF57-B487-4D8F-9522-85549C39F43F`，通道为 `main`。
¥In the example above, the `scheme` is `exp+app-slug`, and the `manifestUrl` is a project with an ID of `F767ADF57-B487-4D8F-9522-85549C39F43F` and a channel of `main`.
<a id="using-updates-deep-links-in-automation-scenarios"></a>
#### 在自动化场景中使用更新深层链接
¥Using updates deep links in automation scenarios
在模拟器或模拟器上使用自动化功能（例如在 CI/CD 工作流中）启动开发构建中的更新 URL 时，你可以将 `disableOnboarding=1` 查询参数添加到 URL，以跳过安装后首次启动开发构建时出现的入门屏幕。
¥When launching an update URL in a development build on an emulator or simulator using automation, such as in a CI/CD workflow, you can add the `disableOnboarding=1` query parameter to the URL to skip the onboarding screen that appears on the first launch of a development build after installation.
<a id="app-specific-deep-links"></a>
#### 应用特定的深层链接
¥App-specific deep links
在开发版本中测试深层链接时，例如导航到 Expo Router 应用中的特定屏幕或在 Oauth 登录流程中测试重定向回你的应用时，请按照与深层链接到某个应用时完全相同的方式构造 URL。 你的应用的独立构建（例如，`myscheme://path/to/screen`）。
¥When testing deep links in your development build, such as when navigating to a specific screen in an Expo Router app or testing redirecting back to your app during an Oauth login flow, construct the URL exactly as you would if you were deep-linking into a standalone build of your app (for example, `myscheme://path/to/screen`).
你的项目必须已在开发版本中打开，特定于应用的深层链接才能工作。目前不支持使用特定于应用的深层链接冷启动开发版本。避免在路径中特定于应用的深层链接中使用 `expo-development-client`，因为它是用于启动更新的 URL 的保留路径。
¥Your project must be already open in the development build for an app-specific deep link to work. Cold-launching a development build with an app-specific deep link is not currently supported. Avoid using `expo-development-client` in your app-specific deep links in the path, as it is a reserved path used for launching an updated URL.
<a id="qr-codes"></a>
### 二维码
¥QR codes
你可以使用我们的端点生成可以通过开发版本轻松加载的二维码。
¥You can use our endpoint to generate a QR code that can be easily loaded by a development build.
当提供查询参数（例如 `appScheme` 和 `url`）时，发送到 `https://qr.expo.dev/development-client` 的请求将收到带有 SVG 图片的响应，其中包含 QR 代码，可以轻松扫描该 QR 代码以在开发版本中加载项目版本。
¥Requests send to `https://qr.expo.dev/development-client` when supplied the query parameters such as `appScheme` and `url` will receive a response with an SVG image containing a QR code that can be easily scanned to load a version of your project in your development build.
| 参数          | value                                                                                          |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `appScheme` | 开发版本的 URL 编码深度链接方案（默认为 `exp+{slug}`，其中 [`slug`](/versions/latest/config/app/#slug) 是应用配置中设置的值） |
| `url`       | 要加载的更新清单的 URL 编码 URL。网址将为 `https://u.expo.dev/[your-project-id]?channel-name=[channel-name]`   |
示例：
¥Example:
```text
https://qr.expo.dev/development-client?appScheme=exp%2Bapps-slug&url=https%3A%2F%2Fu.expo.dev%2FF767ADF57-B487-4D8F-9522-85549C39F43F0%3Fchannel-name%3Dmain
```
上例中，`scheme` 为 `exp+app-slug`，`url` 为项目，项目 ID 为 `F767ADF57-B487-4D8F-9522-85549C39F43F`，通道为 `main`。
¥In the example above, the `scheme` is `exp+app-slug`, and the `url` is a project with an ID of `F767ADF57-B487-4D8F-9522-85549C39F43F` and a channel of `main`.
<a id="example-workflows"></a>
## 工作流程示例
¥Example workflows
这些是一些工作流程示例，可帮助你的团队充分利用你的开发构建。如果你想出对其他团队有用的其他别名，[提交 PR](https://github.com/expo/expo/tree/main/CONTRIBUTING.md#-updating-documentation) 将分享你的知识！
¥These are a few examples of workflows to help your team get the most out of your development build. If you come up with others that would be useful for other teams, [submit a PR](https://github.com/expo/expo/tree/main/CONTRIBUTING.md#-updating-documentation) to share your knowledge!
<a id="pr-previews"></a>
### PR 预览
¥PR previews
你可以将 CI 流程设置为在拉取请求更新时发布 EAS 更新，并添加用于查看兼容开发版本中的更改的 QR 代码。
¥You can set up your CI process to publish an EAS Update whenever a pull request is updated and add a QR code that is used to view the change in a compatible development build.
请参阅 [关于根据拉取请求发布应用预览的说明](/eas-update/github-actions/#publish-previews-on-pull-requests)，使用 GitHub Actions 在你的项目中实现此工作流程，或在你选择的 CI 中用作模板。
¥See [instructions for publishing app previews on pull requests](/eas-update/github-actions/#publish-previews-on-pull-requests) to implement this workflow in your project using GitHub Actions or serve as a template in your CI of choice.
<a id="extensions"></a>
## 扩展
¥Extensions
扩展允许你使用附加功能来扩展你的开发客户端。
¥Extensions allow you to extend your development client with additional capabilities.
<a id="extending-the-dev-menu"></a>
### 扩展开发菜单
¥Extending the dev menu
可以使用 `registerDevMenuItems` API 扩展开发菜单以包含额外的按钮：
¥The dev menu can be extended to include extra buttons by using the `registerDevMenuItems` API:
```tsx
import { registerDevMenuItems } from 'expo-dev-menu';
const devMenuItems = [
  {
    name: 'My Custom Button',
    callback: () => console.log('Hello world!'),
  },
];
registerDevMenuItems(devMenuItems);
```
这将在开发菜单中创建一个新部分，其中包含你已注册的按钮：
¥This will create a new section in the dev menu that includes the buttons you have registered:
> `registerDevMenuItems` 的后续调用将覆盖所有先前的条目。
>
> ¥Subsequent calls of `registerDevMenuItems` will override all previous entries.
<a id="eas-update"></a>
### EAS 更新
¥EAS Update
EAS 更新扩展提供了在开发客户端中查看和加载已发布更新的功能。
¥The EAS Update extension provides the ability to view and load published updates in your development client.
它适用于所有 `v0.9.0` 及以上的开发客户端。要安装它，你需要最新发布的 `expo-updates`：
¥It's available for all development clients `v0.9.0` and above. To install it, you'll need the most recent publish of `expo-updates`:
```sh
$ npx expo install expo-dev-client expo-updates
```
<a id="configure-eas-update"></a>
#### 配置 EAS 更新
¥Configure EAS Update
如果你的项目中尚未配置 EAS 更新，你可以找到 [有关如何执行此操作的其他说明，请参见此处。](/eas-update/getting-started/)
¥If you have not yet configured EAS Updates in your project, you can find [additional instructions on how to do so here.](/eas-update/getting-started/)
你现在可以通过 `Extensions` 面板在开发版本中查看和加载 EAS 更新。
¥You can now view and load EAS Updates in your development build via the `Extensions` panel.
<a id="set-runtimeversion-in-app-config"></a>
## 在应用配置中设置运行时版本
¥Set runtimeVersion in app config
当你创建项目的开发版本时，你将获得一个稳定的环境来加载在 JavaScript 中定义的应用的任何更改或其他与资源相关的更改。对应用的其他更改，无论是直接在 android 和 ios 目录中定义，还是通过你选择安装的包或 SDK 定义，都将要求你创建开发版本的新版本。
¥When you create a development build of your project, you'll get a stable environment to load any changes to your app that are defined in JavaScript or other asset-related changes. Other changes to your app, whether defined directly in **android** and **ios** directories or by packages or SDKs you choose to install, will require you to create a new build of your development build.
要在应用的 JavaScript 层和原生层之间强制执行 API 协定，你应该在应用配置中设置 [`runtimeVersion`](/eas-update/runtime-versions) 值。你制作的每个构建都将嵌入此值，并且在开发和生产中仅加载具有相同 `runtimeVersion` 的打包包。
¥To enforce an API contract between the JavaScript and native layers of your app, you should set the [`runtimeVersion`](/eas-update/runtime-versions) value in the app config. Each build you make will have this value embedded and will only load bundles with the same `runtimeVersion`, in both development and production.


## 下一步

有用资源列表，可帮助你了解有关开发构建和 EAS 构建的更多信息。

# 配置插件

## 配置插件简介

Expo 配置插件简介。

在项目中使用 [持续的原生生成 (CNG)](/workflow/continuous-native-generation/) 时，原生项目（Android 和 iOS 目录）的更改无需直接与原生项目文件交互即可实现。此外，你可以使用配置插件自动配置原生项目，而无需使用默认应用配置属性进行配置。
¥When using [Continuous Native Generation (CNG)](/workflow/continuous-native-generation/) in a project, native project (**android** and **ios** directories) changes are implemented without directly interacting with the native project files. Instead, you can use a config plugin to automatically configure your native project beyond what can be configured using the default app config props.
<a id="what-is-a-config-plugin"></a>
## 什么是配置插件
¥What is a config plugin
配置插件是一个顶层自定义配置点，它未内置于 [应用配置](/workflow/configuration) 中。使用配置插件，你可以在 CNG 项目中修改在 [prebuild](/workflow/continuous-native-generation/#usage) 过程中创建的原生项目。
¥A config plugin is a top-level custom configuration point that is not built into the [app config](/workflow/configuration). Using a config plugin, you can modify native projects created during the [prebuild](/workflow/continuous-native-generation/#usage) process in CNG projects.
配置插件在 [应用配置](/workflow/configuration) 文件的 `plugins` 属性中引用，由一个或多个插件函数组成。这些插件函数用 JavaScript 编写，并在预构建过程中执行。
¥A config plugin is referenced in the `plugins` property of the [app config](/workflow/configuration) file and is made up of one or more plugin functions. These plugin functions are written in JavaScript and are executed during the prebuild process.
<a id="glossary"></a>
## 词汇表
¥Glossary
一个典型的配置插件由一个或多个协同工作的插件函数组成。下图展示了配置插件各个部分之间的交互方式：
¥A typical config plugin is made up of one or more plugin functions that work together. The following diagram shows how the different parts of a config plugin interact with each other:
<ConfigPluginHierarchy highlightedNodeId="1" />
在以下指南中，我们将使用上图高亮下文解释的特定术语：
¥In the following guides, we will use the above diagram to highlight specific terminology explained below:
<a id="plugin"></a>
### 插件
¥Plugin
顶层配置插件，在你的应用配置的 `plugins` 数组中引用。这是插件的入口点。通常，它被命名为 `with<Plugin Name>`。例如，`withMyPlugin`。它由一个或多个 [插件功能](#plugin-function) 组成。
¥The top-level config plugin which is referenced in your app config's `plugins` array. This is the entry point for your plugin. Conventionally, it is named `with<Plugin Name>`. For example, `withMyPlugin`. It is made of one or more [plugin functions](#plugin-function).
<a id="plugin-function"></a>
### 插件功能
¥Plugin function
配置插件中的一个或多个函数称为插件函数。它们封装了执行平台特定修改的底层逻辑。从技术上讲，插件函数看起来与顶层插件本身的函数一样，并且可以独立用作插件。将插件拆分成更小的函数通常有助于测试和调试。
¥One or more functions inside a config plugin that are called *plugin functions*. They wrap the underlying logic of performing platform-specific modifications. Technically, plugin functions look just like the function for the top-level plugin itself, and could be used as a plugin independently. Breaking plugins into smaller functions is often helpful for testing and debugging.
<a id="mod-plugin-function"></a>
### Mod 插件功能
¥Mod plugin function
来自 `expo/config-plugins` 库的封装函数，提供使用 `mods` 修改原生文件的安全方法。作为开发者，你将在配置插件中使用这些功能，而不是在底层 `mods` 中。
¥Wrapper functions from `expo/config-plugins` library that provide a safe way to modify native files using `mods`. As a developer, you will use these functions in your config plugin instead of underlying `mods`.
<a id="mod"></a>
### Mod
在预构建期间直接修改原生项目文件的底层平台特定修饰符（例如 `mods.android.manifest` 和 `mods.ios.infoplist`）。
¥The underlying platform-specific modifiers (like `mods.android.manifest` and `mods.ios.infoplist`) that directly modify native project files during prebuild.
<a id="why-use-a-config-plugin"></a>
## 为什么使用配置插件
¥Why use a config plugin
配置插件可以向你的项目添加默认情况下不包含的原生配置。它们可用于生成应用图标、设置应用名称、配置 AndroidManifest.xml 和 Info.plist 等等。
¥Config plugins can add native configuration to your project that isn't included by default. They can be used to generate app icons, set the app name, configure **AndroidManifest.xml** and **Info.plist**, and so on.
在 CNG 项目中，最好避免手动修改这些原生项目，因为你无法安全地重新生成它们，否则可能会覆盖手动修改。配置插件允许你以可预测的方式修改这些原生项目，方法是将原生项目的更改合并到配置文件中，并在运行 `npx expo prebuild`（在 CI/CD 过程中手动或自动）时应用这些更改。例如，当你在应用配置中更改应用名称并运行 `npx expo prebuild` 时，该名称将在你的原生项目中自动更改，无需手动更新 AndroidManifest.xml 和 Info.plist 文件。
¥In CNG projects, it is best to avoid modifying these native projects manually, because you cannot regenerate them safely without potentially overwriting manual modifications. Config plugins allow you to modify these native projects in a *predictable way* by consolidating your native project changes into a configuration file and applying them when you run `npx expo prebuild` (either manually or automatically during a CI/CD process). For example, when you change the name of your app in app config and run `npx expo prebuild`, the name will change in your native projects automatically without the need to manually update **AndroidManifest.xml** and **Info.plist** files.
<a id="characteristics-of-a-config-plugin"></a>
## 配置插件的特点
¥Characteristics of a config plugin
配置插件具有以下特点：
¥Config plugins have the following characteristics:
* 插件是同步函数，接受 [ExpoConfig](/workflow/configuration) 并返回修改后的 `ExpoConfig`。在极少数情况下，如果与原生项目通信的可用方法是异步的，则插件也可以是异步的，但性能不佳。
  ¥Plugins are **synchronous** functions that accept an [ExpoConfig](/workflow/configuration) and return a modified `ExpoConfig`. In rare cases, plugins can also be asynchronous if available methods to communicate with native projects are asynchronous, but they won't be performant.
* 插件应使用以下约定命名：`with<Plugin Functionality>`，例如 `withFacebook`
  ¥Plugins should be named using the following convention: `with<Plugin Functionality>`, for example, `withFacebook`
* 插件应同步运行，并且其返回值应可序列化，但添加任何 [`mods`](#mods) 除外。
  ¥Plugins should be synchronous and their return value should be serializable, except for adding any [`mods`](#mods)
* 插件始终在应用配置评估阶段进行评估。
  ¥Plugins are always evaluated during the app config evaluation phase.
* （可选）可以将第二个参数传递给插件进行配置。
  ¥Optionally, a second argument can be passed to the plugin to configure it
* 模块仅在 `npx expo prebuild`（预构建过程）的同步阶段进行评估，并在代码生成期间修改原生文件。因此，在配置插件中对应用配置所做的任何修改都应在模块之外进行，以确保它们在非预构建配置场景中执行。
  ¥Mods are only evaluated during the **syncing** phase of `npx expo prebuild` (prebuild process) and modify native files during code generation. Because of that, any modifications made to app config in a config plugin should be outside of a mod to ensure that they are executed in non-prebuild configuration scenarios.
<a id="get-started"></a>
## 开始使用
¥Get started


## 创建和使用配置插件

了解如何在 Expo 项目中创建和使用配置插件。

本指南涵盖了如何创建配置插件、如何向配置插件传递参数以及如何将多个配置插件链接在一起等章节。它还介绍了如何使用 Expo 库中的配置插件。
¥This guide covers sections how to create a config plugin, how to pass parameters to a config plugin, and how to chain multiple config plugins together. It also covers how to use a config plugin from an Expo library.
在本指南中，通过下图，你将了解配置插件层次结构的前两部分：
¥Using the diagram below, in this guide, you will learn the first two parts of the config plugin hierarchy:
<ConfigPluginHierarchy highlightedNodeIds={['1', '2']} />
>  **info** 注意：以下部分使用动态 [应用配置](/workflow/configuration/)（app.config.js/app.config.ts 而不是 app.json），使用简单配置插件时无需使用动态 [应用配置](/workflow/configuration/)。但是，当你想要创建/使用接受参数的基于函数的配置插件时，必须使用动态应用配置。
>
> ¥**Note:** The following sections use dynamic [app config](/workflow/configuration/) (**app.config.js/app.config.ts** instead of **app.json**), which is not required to use a simple config plugin. However, it is required to use dynamic app config when you want to create/use a function-based config plugin that accepts parameters.
<a id="creating-a-config-plugin"></a>
## 创建配置插件
¥Creating a config plugin
在下一节中，我们将创建一个本地配置插件，该插件将任意属性 `HelloWorldMessage` 添加到 Android 的 AndroidManifest.xml 和 iOS 的 Info.plist 中。
¥In the following section, let's create a local config plugin that adds an arbitrary property `HelloWorldMessage` to the **AndroidManifest.xml** for Android and **Info.plist** for iOS.
此示例将创建和修改以下文件。要继续操作，请在项目根目录中创建一个 plugins 目录，并在其中创建 withAndroidPlugin.ts、withIosPlugins.ts 和 withPlugin.ts 文件。
¥This example will create and modify the following files. To follow along, create a **plugins** directory in the root of your project, and inside it, create **withAndroidPlugin.ts**, **withIosPlugins.ts**, and **withPlugin.ts** files.
Step 1: 
### Create Android plugin
In **withAndroidPlugin.ts**, add the following code:
```ts withAndroidPlugin.ts
import { ConfigPlugin, withAndroidManifest } from 'expo/config-plugins';
const withAndroidPlugin: ConfigPlugin = config => {
  // Define a custom message
  const message = 'Hello world, from Expo plugin!';
  return withAndroidManifest(config, config => {
    const mainApplication = config?.modResults?.manifest?.application?.[0];
    if (mainApplication) {
      // Ensure meta-data array exists
      if (!mainApplication['meta-data']) {
        mainApplication['meta-data'] = [];
      }
      // Add the custom message as a meta-data entry
      mainApplication['meta-data'].push({
        $: {
          'android:name': 'HelloWorldMessage',
          'android:value': message,
        },
      });
    }
    return config;
  });
};
export default withAndroidPlugin;
```
The example code above adds a meta-data entry `HelloWorldMessage` to the **android/app/src/main/AndroidManifest.xml** file by importing `ConfigPlugin` and `withAndroidManifest` from the `expo/config-plugins` library. The [`withAndroidManifest`](/config-plugins/mods/#mod-plugins) mod plugin is an asynchronous function that accepts a config and a data object and modifies the value before returning an object.
Step 2: 
### Create iOS plugin
In **withIosPlugin.ts**, add the following code:
```ts withIosPlugin.ts
import { ConfigPlugin, withInfoPlist } from 'expo/config-plugins';
const withIosPlugin: ConfigPlugin = config => {
  // Define the custom message
  const message = 'Hello world, from Expo plugin!';
  return withInfoPlist(config, config => {
    // Add the custom message to the Info.plist file
    config.modResults.HelloWorldMessage = message;
    return config;
  });
};
export default withIosPlugin;
```
The example code above adds `HelloWorldMessage` as the custom key with a custom message in **ios/\<your-project-name\>/Info.plist** file by importing the `ConfigPlugin` and `withInfoPlist` from the `expo/config-plugins` library. The [`withInfoPlist`](/config-plugins/mods/#mod-plugins) mod plugin is an asynchronous function that accepts a config and a data object and modifies the value before returning an object.
Step 3: 
### Create a combined plugin
Now you can create a combined plugin that applies both platform-specific plugins. This approach allows the maintenance of platform-specific code separately while providing a single entry point.
In **withPlugin.ts**, add the following code:
```ts withPlugin.ts
import { ConfigPlugin } from 'expo/config-plugins';
import withAndroidPlugin from './withAndroidPlugin';
import withIosPlugin from './withIosPlugin';
const withPlugin: ConfigPlugin = config => {
  // Apply Android modifications first
  config = withAndroidPlugin(config);
  // Then apply iOS modifications and return
  return withIosPlugin(config);
};
export default withPlugin;
```
Step 4: 
### Add TypeScript support and convert to dynamic app config
We recommend writing config plugins in TypeScript, since this will provide intellisense for the configuration objects. However, your app config is ultimately evaluated by Node.js, which does not recognize TypeScript code by default. Therefore, you will need to add a parser for the TypeScript files from the the **plugins** directory to **app.config.ts** file.
Install `tsx` library by running the following command:
```sh
$ npm install --save-dev tsx
```
Then, change the static app config (**app.json**) to the [dynamic app config (**app.config.ts**)](/workflow/configuration/#dynamic-configuration) file. You can do this by renaming the **app.json** file to **app.config.ts** and changing the content of the file as shown below. Ensure to add the following import statement at the top of your **app.config.ts** file:
```ts app.config.ts
import 'tsx/cjs';
module.exports = () => {
};
```
Step 5: 
### Call the config plugin from your dynamic app config
Now, you can call the config plugin from your dynamic app config. To do this, you need to add the path to the **withPlugin.ts** file to the plugins array in your app config:
```ts app.config.ts
import "tsx/cjs";
import { ExpoConfig } from "expo/config";
  plugins: [
      ["./plugins/withPlugin.ts"],
    ],
};
```
To see the custom config applied in native projects, run the following command:
```sh
$ npx expo prebuild --clean --no-install
```
To verify the custom config plugins applied, open **android/app/src/main/AndroidManifest.xml** and **ios/\<your-project-name\>/Info.plist** files:
```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<!-- ... rest of the configuration-->
	<application ...>
		<meta-data android:name="HelloWorldMessage" android:value="Hello world, from Expo plugin!"/>
		<!-- ... -->
	</application>
</manifest>
```
```xml
<plist version="1.0">
  <dict>
  <!-- ... -->
    <key>HelloWorldMessage</key>
    <string>Hello world, from Expo plugin!</string>
	<!-- ... -->
	</dict>
</plist>
```
## Passing a parameter to a config plugin
Your config plugin can accept parameters passed from your app config. To do so, you will need to read the parameter in your config plugin function, and then pass an object containing the parameter along with the config plugin function in your app config.
Step 1: 
Considering the previous example, let's pass a custom message to the plugin. Add an `options` object in **withAndroidPlugin.ts** and update the `message` variable to use the `options.message` property:
```ts withAndroidPlugin.ts
type AndroidProps = {
  message?: string;
};
const withAndroidPlugin: ConfigPlugin<AndroidProps> = (
  config,
) => {
  const message = options.message || 'Hello world, from Expo plugin!';
  return withAndroidManifest(config, config => {
  });
};
export default withAndroidPlugin;
```
Step 2: 
Similarly, add an `options` object in **withIosPlugin.ts** and update the `message` variable to use the `options.message` property:
```ts withIosPlugin.ts
type IosProps = {
  message?: string;
};
  const message = options.message || 'Hello world, from Expo plugin!';
};
export default withIosPlugin;
```
Step 3: 
Update the **withPlugin.ts** file to pass the `options` object to both plugins:
```ts withPlugin.ts
  config = withAndroidPlugin(config, options);
  return withIosPlugin(config, options);
};
```
Step 4: 
To pass a value dynamically to the plugin, you can pass an object with the `message` property to the plugin in your app config:
```ts app.config.ts
{
  plugins: [
    [
      "./plugins/withPlugin.ts",
      { message: "Custom message from app.config.ts" },
    ],
  ],
}
```
## Chaining config plugins
Config plugins can be chained together to apply multiple modifications. Each plugin in the chain runs in the order it appears, with the output of one plugin becoming the input for the next. This sequential execution ensures that dependencies between plugins are respected and allows you to control the precise order of modifications to your native code.
To chain config plugins, you can pass an array of plugins to the `plugins` array property in your app config. This is also supported in JSON app config file format (**app.json**).
```ts app.config.ts
module.exports = ({ config }: { config: ExpoConfig }) => {
  name: 'my app',
  plugins: [
    [withFoo, 'input 1'],
    [withBar, 'input 2'],
    [withDelta, 'input 3'],
  ],
};
```
The `plugins` array uses `withPlugins` method under the hood to chain the plugins. If your plugins array is getting long or has complex configuration, you can use the `withPlugins` method directly to make your configuration easier to read. `withPlugins` will chain the plugins together and execute them in order.
```ts app.config.ts
import { withPlugins } from 'expo/config-plugins';
// Create a base config object
const baseConfig = {
  name: 'my app',
};
// ❌ Hard to read
withDelta(withFoo(withBar(config, 'input 1'), 'input 2'), 'input 3');
// ✅ Easy to read
withPlugins(config, [
  [withFoo, 'input 1'],
  [withBar, 'input 2'],
  // When no input is required, you can just pass the method
  withDelta,
]);
// Export the base config with plugins applied
module.exports = ({ config }: { config: ExpoConfig }) => {
  return withPlugins(baseConfig, plugins);
};
```
## Using a config plugin
Expo config plugins are usually included in Node.js modules. You can install them just like other libraries in your project.
For example, `expo-camera` has a plugin that adds camera permissions to the **AndroidManifest.xml** and **Info.plist**. To install it in your project, run the following command:
```sh
$ npx expo install expo-camera
```
In your [app config](/versions/latest/config/app/), you can add `expo-camera` to the list of plugins:
```json app.json
{
  "expo": {
    "plugins": ["expo-camera"]
  }
}
```
Some config plugins offer flexibility by allowing you to pass options to customize their configuration. To do this, you can pass an array with the Expo library name as the first argument, and an object containing the options as the second argument. For example, the `expo-camera` plugin allows you to customize the camera permission message:
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-camera",
        {
          "cameraPermission": "Allow $(PRODUCT_NAME) to access your camera."
        }
      ]
    ]
  }
}
```
>
info 提示：对于每个具有配置插件的 Expo 库，你都可以在库的 API 参考中找到有关它的更多信息。例如，[`expo-camera` 库有一个配置插件部分](/versions/latest/sdk/camera/#configuration-in-appjsonappconfigjs)。
¥**info** **Tip**: For every Expo library that has a config plugin, you'll find more information about that in the library's API reference. For example, the [`expo-camera` library has a config plugin section](/versions/latest/sdk/camera/#configuration-in-appjsonappconfigjs).
运行 `npx expo prebuild` 时，会编译 [`mods`](/config-plugins/introduction/#mods)，并且原生文件会发生变化。
¥On running the `npx expo prebuild`, the [`mods`](/config-plugins/introduction/#mods) are compiled, and the native files change.
直到你重建原生项目（例如使用 Xcode）后，更改才会生效。如果你在没有原生目录的项目（CNG 项目）中使用配置插件，它们将在 EAS Build 的预构建步骤中或在本地运行 `npx expo prebuild|android|ios` 时应用。
¥The changes don't take effect until you rebuild the native project, for example, with Xcode. **If you're using config plugins in a project without native directories (CNG projects), they will be applied during the prebuild step in EAS Build** or when running `npx expo prebuild|android|ios` locally.


## Mods

了解模块以及如何在创建配置插件时使用它们。

本指南解释了什么是 mod 和 mod 插件、它们的工作原理以及如何在为你的 Expo 项目创建配置插件时有效地使用它们。
¥This guide explains what mods and mod plugins are, how they work, and how to use them effectively when creating config plugins for your Expo project.
在本指南中，通过下图，你将了解配置插件层次结构的后两部分：
¥Using the diagram below, in this guide, you will learn the last two parts of the config plugin hierarchy:
<ConfigPluginHierarchy highlightedNodeIds={['3', '4']} />
<a id="mod-plugins"></a>
## 模组插件
¥Mod plugins
Mod 插件提供了一种在预构建过程中修改原生项目文件的方法。它们由 `expo/config-plugins` 库提供，封装了顶层 mod（也称为默认 [mods](#mods)），因为顶层 mod 是平台相关的，并且执行各种一开始可能难以理解的任务。
¥Mod plugins provide a way to modify native project files during the prebuild process. They are made available from `expo/config-plugins` library and wrap top-level mods (also known as *default [mods](#mods)*) because top-level mods are platform-specific and perform various tasks that can be difficult to understand at first.
>  **info** 提示：如果你正在开发需要 mod 的功能，则应该使用 mod 插件，而不是直接与顶层 mod 交互。
>
> ¥**Tip:** If you are developing a feature that requires mods, you should use *mod plugins* instead of interacting with top-level mods directly.
<a id="available-mod-plugins"></a>
### 可用的 mod 插件
¥Available mod plugins
`expo/config-plugins` 库中提供以下 mod 插件：
¥The following mod plugins are available in the `expo/config-plugins` library:
<a id="android"></a>
#### 安卓
¥Android
| 默认 Android 版本                     | 模组插件                                                                                                                                                                             | 危险的 | 描述                                                                                     |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | -------------------------------------------------------------------------------------- |
| `mods.android.manifest`           | `withAndroidManifest`([示例](https://github.com/expo/expo/blob/main/packages/expo-notifications/plugin/src/withNotificationsAndroid.ts))                                           |  *  | 将 android/app/src/main/AndroidManifest.xml 修改为 JSON（使用 [`xml2js`][xml2js] 解析）          |
| `mods.android.strings`            | `withStringsXml`([示例](https://github.com/expo/expo/blob/d7fb5d254d5cb57ab06055136db72b9347d3db1e/packages/expo-navigation-bar/plugin/src/withNavigationBar.ts))                  |  *  | 修改 android/app/src/main/res/values/strings.xml 为 JSON（用 [`xml2js`][xml2js] 解析）。        |
| `mods.android.colors`             | `withAndroidColors`([示例](https://github.com/expo/expo/blob/main/packages/%40expo/config-plugins/src/android/StatusBar.ts#L8))                                                    |  *  | 将 android/app/src/main/res/values/colors.xml 修改为 JSON（使用 [`xml2js`][xml2js] 解析）。       |
| `mods.android.colorsNight`        | `withAndroidColorsNight`([示例](https://github.com/expo/expo/blob/main/packages/%40expo/prebuild-config/src/plugins/unversioned/expo-splash-screen/withAndroidSplashStyles.ts#L5)) |  *  | 将 android/app/src/main/res/values-night/colors.xml 修改为 JSON（使用 [`xml2js`][xml2js] 解析）。 |
| `mods.android.styles`             | `withAndroidStyles`([示例](https://github.com/expo/expo/blob/main/packages/%40expo/prebuild-config/src/plugins/unversioned/expo-splash-screen/withAndroidSplashStyles.ts#L5))      |  *  | 修改 android/app/src/main/res/values/styles.xml 为 JSON（用 [`xml2js`][xml2js] 解析）。         |
| `mods.android.gradleProperties`   | `withGradleProperties`([示例](https://github.com/expo/expo/blob/main/packages/%40expo/config-plugins/src/android/BuildProperties.ts#L5))                                           |  *  | 修改 android/gradle.properties 为 `Properties.PropertiesItem[]`。                          |
| `mods.android.mainActivity`       | `withMainActivity`([示例](https://github.com/expo/expo/blob/main/packages/install-expo-modules/src/plugins/android/withAndroidModulesMainActivity.ts#L2))                          |     | 将 android/app/src/main/&lt;package&gt;/MainActivity.java 修改为字符串。               |
| `mods.android.mainApplication`    | `withMainApplication`([示例](https://github.com/expo/expo/blob/main/packages/expo-web-browser/plugin/src/withWebBrowserAndroid.ts#L8))                                             |     | 将 android/app/src/main/&lt;package&gt;/MainApplication.java 修改为字符串。            |
| `mods.android.appBuildGradle`     | `withAppBuildGradle`([示例](https://github.com/expo/expo/blob/main/packages/%40expo/config-plugins/src/android/GoogleServices.ts#L5))                                              |     | 将 android/app/build.gradle 修改为字符串。                                                     |
| `mods.android.projectBuildGradle` | `withProjectBuildGradle`([示例](https://github.com/expo/expo/blob/main/packages/%40expo/config-plugins/src/android/GoogleServices.ts#L5))                                          |     | 将 android/build.gradle 修改为字符串。                                                         |
| `mods.android.settingsGradle`     | `withSettingsGradle`([示例](https://github.com/expo/expo/blob/main/packages/install-expo-modules/src/plugins/android/withAndroidSettingsGradle.ts#L2))                             |     | 将 android/settings.gradle 修改为字符串。                                                      |
<a id="ios"></a>
#### iOS 系统
¥iOS
| 默认 iOS 版本                    | 模组插件                                                                                                                                    | 危险的 | 描述                                                                                                               |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --- | ---------------------------------------------------------------------------------------------------------------- |
| `mods.ios.infoPlist`         | `withInfoPlist`([示例](https://github.com/expo/expo/blob/main/packages/expo-location/plugin/src/withLocation.ts))                         | *   | 修改 ios/&lt;name&gt;/Info.plist 为 JSON（用 [`@expo/plist`][expo-plist] 解析）。                                 |
| `mods.ios.entitlements`      | `withEntitlementsPlist`([示例](https://github.com/expo/expo/blob/main/packages/expo-apple-authentication/plugin/src/withAppleAuthIOS.ts)) | *   | 将 ios/&lt;name&gt;/&lt;product-name&gt;.entitlements 修改为 JSON（用 [`@expo/plist`][expo-plist] 解析）。 |
| `mods.ios.expoPlist`         | `withExpoPlist`([示例](https://github.com/expo/expo/blob/main/packages/%40expo/config-plugins/src/ios/Updates.ts#L6))                     | *   | 将 ios/&lt;name&gt;/Expo.plist 修改为 JSON（Expo 更新 iOS 配置）（使用 [`@expo/plist`][expo-plist] 解析）。               |
| `mods.ios.xcodeproj`         | `withXcodeProject`([示例](https://github.com/expo/expo/blob/main/packages/expo-asset/plugin/src/withAssetsIos.ts))                        | *   | 修改 ios/&lt;name&gt;.xcodeproj 为 `XcodeProject` 对象（用 [`xcode`](https://www.npmjs.com/package/xcode) 解析）。  |
| `mods.ios.podfile`           | `withPodfile` ([示例](https://github.com/expo/expo/blob/main/packages/%40expo/config-plugins/src/ios/Maps.ts#L6)                          | *   | 将 ios/Podfile 修改为字符串。                                                                                            |
| `mods.ios.podfileProperties` | `withPodfileProperties`([示例](https://github.com/expo/expo/blob/main/packages/%40expo/config-plugins/src/ios/BuildProperties.ts#L4))     | *   | 将 ios/Podfile.properties.json 修改为 JSON。                                                                          |
| `mods.ios.appDelegate`       | `withAppDelegate`([示例](https://github.com/expo/expo/blob/main/packages/%40expo/config-plugins/src/ios/Maps.ts#L6))                      |     | 将 ios/&lt;name&gt;/AppDelegate.m 修改为字符串。                                                                 |
>  **info** 关于默认 Android 和 iOS 模块的说明： 默认模块由模块编译器提供，用于常见的文件操作。危险的修改依赖正则表达式（regex）来修改应用代码，这可能会导致构建中断。正则表达式 mod 也很难进行版本控制，因此应谨慎使用。始终选择使用应用代码来修改应用代码，即 [Expo 模块](https://github.com/expo/expo/tree/main/packages/expo-modules-core) 原生 API。
>
> ¥**Note about default Android and iOS mods:** 
> Default mods are provided by the mod compiler for common file manipulation. Dangerous modifications rely on regular expressions (regex) to modify application code, which may cause the build to break. Regex mods are also difficult to version, and therefore should be used sparingly. Always opt towards using application code to modify application code, that is, [Expo Modules](https://github.com/expo/expo/tree/main/packages/expo-modules-core) native API.
<a id="mods"></a>
## Mods
配置插件使用 mods（修改器的缩写）在预构建过程中修改原生项目文件。模块是异步函数，允许你更改平台特定文件（例如 AndroidManifest.xml 和 Info.plist）以及其他原生配置文件，而无需手动编辑它们。它们仅在 `npx expo prebuild` 的同步阶段（预构建过程）执行。
¥Config plugins use **mods** (short for modifiers) to modify native project files during the prebuild process. Mods are asynchronous functions that allow you to make changes to platform-specific files such as **AndroidManifest.xml** and **Info.plist**, and other native configuration files without having to manually edit them. They execute only during the **syncing** phase of `npx expo prebuild` (prebuild process).
它们接受一个配置和一个数据对象，然后修改它们并将其作为单个对象返回。例如，在原生项目中，`mods.android.manifest` 修改 AndroidManifest.xml，`mods.ios.plist` 修改 Info.plist。
¥They accept a config and a data object, then modify and return both of them as a single object. For example, in native projects, `mods.android.manifest` modifies **AndroidManifest.xml** and `mods.ios.plist` modifies **Info.plist**.
你不能在配置插件中直接将 mods 用作顶层函数（例如 `with.android.manifest`）。当你需要使用模组时，你可以在配置插件中使用模组插件。这些 mod 插件由 `expo/config-plugins` 库提供，封装了顶层 mod 函数，并在后台执行各种任务。要查看可用模组列表，请查看 [修改 `expo/config-plugins` 提供的插件](#available-mod-plugins)。
¥**You don't use mods as top-level functions (for example `with.android.manifest`) directly in your config plugin.** When you need to use a mod, you use *mod plugins* in your config plugins. These mod plugins are provided by the `expo/config-plugins` library and wrap top-level mod functions and behind the scenes they perform various tasks. To see a list of available mods, check out the [mod plugins provided by `expo/config-plugins`](#available-mod-plugins).
Note: How default mods work and their key characteristics
---
When a default mod resolves, it is added to the `mods` object of the app config. This `mods` object is different from the rest of the app config
because it doesn't get serialized, which means you can use it to perform actions _during_ code generation. Whenever possible, you should use available mod plugins instead of default mods since they are easier to work with.
Here is a high-level overview of how default mods work:
- The config is read using [`getPrebuildConfig`](https://github.com/expo/expo/blob/efc2db4eb1c909544e28792a15c89f8d22113c5b/packages/%40expo/prebuild-config/src/getPrebuildConfig.ts#L28) from `@expo/prebuild-config`
- All of the core functionality supported by Expo is added via plugins in `withIosExpoPlugins`. This includes name, version, icons, locales, and so on.
- The config is passed to the compiler `compileModsAsync`
- The compiler adds base mods that are responsible for reading data (like **Info.plist**), executing a named mod (like `mods.ios.infoPlist`), then writing the results to the file system
- The compiler iterates over all the mods and asynchronously evaluates them, providing some base props like the `projectRoot`
  - After each mod, error handling asserts if the mod chain was corrupted by an invalid mod
Here are some key characteristics of default mods:
- `mods` are omitted from the manifest and **cannot** be accessed via `Updates.manifest`. Mods exist for the sole purpose of modifying native project files during code generation!
- `mods` can be used to read and write files safely during the `npx expo prebuild` command. This is how Expo CLI modifies the **Info.plist**, entitlements, xcproj, and so on.
- `mods` are platform-specific and should always be added to a platform-specific object:
```ts app.config.ts
  module.exports = {
    name: 'my-app',
    mods: {
      ios: {
        /* iOS mods... */
      },
      android: {
        /* Android mods... */
      },
    },
  };
  ```
After mods are resolved, the contents of each mod will be written to disk. Custom mods can be added to support new native files. For example, you can create a mod to support the **GoogleServices-Info.plist**, and pass it to other mods.
---
### How mod plugins work
When a mod plugin is executed, it gets passed a `config` object with additional properties: `modResults` and `modRequest`.
#### `modResults`
The `modResults` object contains the data to modify and return. Its type depends on the mod that's being used.
#### `modRequest`
The `modRequest` object contains the following additional properties supplied by the mod compiler.
| Property              | Type          | Description                                                                                                   |
| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------- |
| `projectRoot`         | `string`      | Project root directory for the universal app.                                                                 |
| `platformProjectRoot` | `string`      | Project root for the specific platform.                                                                       |
| `modName`             | `string`      | Name of the mod.                                                                                              |
| `platform`            | `ModPlatform` | Name of the platform used in the mods config.                                                                 |
| `projectName`         | `string`      | (iOS only) The path component used for querying project files. For example, `projectRoot/ios/[projectName]/`. |
## Create your own mod
For example, if you want to write a mod to update the Xcode Project's "product name", you'll create a config plugin file that uses the [`withXcodeProject`](#ios) mod plugin.
```ts my-config-plugin.ts
import { ConfigPlugin, withXcodeProject, IOSConfig } from 'expo/config-plugins';
const withCustomProductName: ConfigPlugin<string> = (config, customName) => {
  return withXcodeProject(
    config,
    async (
    ) => {
      config.modResults = IOSConfig.Name.setProductName({ name: customName }, config.modResults);
      return config;
    }
  );
};
// Usage:
/// Create a config
const config = {
  name: 'my app',
};
/// Use the plugin
export default withCustomProductName(config, 'new_name');
```
## Plugin module resolution
When implementing plugins, there are two fundamental approaches to consider:
1. **Plugins defined within your app's project**: These plugins live locally within your project, making them easy to customize and maintain alongside your app's code. They are ideal for project-specific customizations.
2. **Standalone package plugins**: These plugins exist as separate packages and are published to npm. This approach is ideal for reusable plugins that can be shared across multiple projects.
Both approaches provide the same capabilities for modifying your native configuration, but differ in how they're structured and imported. The sections below explain how module resolution works for each approach.
> Any resolution pattern that isn't specified below is unexpected behavior, and subject to breaking changes.
### Plugins defined within your app's project
With plugins defined within your app's project, you can implement plugins directly in your project in several ways:
#### File import
You can quickly create a plugin in your project by creating a JavaScript/TypeScript file and use it in your config like any other JS/TS file.
 Imported from config
      </>,
    ],
  ]}
/>
In the above example, the config plugin file contains a bare minimum function:
```ts my-config-plugin.ts
module.exports = ({ config }: { config: ExpoConfig }) => {};
```
#### Inline function inside of dynamic app config
Expo config objects also support passing functions as-is to the `plugins` array. This is useful for testing, or if you want to use a plugin without creating a file.
```js app.config.ts
const withCustom = (config, props) => config;
const config = {
  plugins: [
    [
      withCustom,
      {
        /* props */
      },
    ],
    withCustom,
  ],
};
```
One caveat to using functions instead of strings is that serialization will replace the function with the function's name. This keeps **manifests** (kind of like the **index.html** for your app) working as expected. Here is what the serialized config would look like:
```json
{
  "plugins": [["withCustom", {}], "withCustom"]
}
```
### Standalone package plugins
> **info** See [Create a module with a config plugin](/modules/config-plugin-and-native-module-tutorial/) for a step-by-step guide on how to create a standalone package plugin.
Standalone package plugins can be implemented in two ways:
#### 1. Dedicated config plugin packages
These are npm packages whose sole purpose is to provide a config plugin. For a dedicated config plugin package, you can export your plugin using `app.plugin.js`:
 Entry file for custom plugins
      </>,
    ],
    [
      'node_modules/expo-splash-screen/build/index.js',
      <>
        <NoIcon /> Skipped in favor of <code>app.plugin.js</code>
      </>,
    ],
  ]}
/>
#### 2. Config plugins with companion packages
When a config plugin is part of a Node module without an **app.plugin.js**, it uses the package's `main` entry point:
 Node resolve to this file
      </>,
    ],
  ]}
/>
### Plugin resolution order
When you import a plugin package, files are resolved in this specific order:
1. **app.plugin.js in package root**
 Entry file for custom plugins
      </>,
    ],
    ['node_modules/expo-splash-screen/build', ''],
    [
      'node_modules/expo-splash-screen/build/index.js',
      <>
        <NoIcon /> Skipped in favor of app.plugin.js
      </>,
    ],
  ]}
/>
2. **Package's main entry (from package.json)**
 Node resolve to this file
      </>,
    ],
  ]}
/>
3. **Direct internal imports** (not recommended)
>
错误：避免直接导入模块内部代码，因为它会绕过标准解析顺序，并且可能会在将来的更新中中断。
¥**error** Avoid importing module internals directly as it bypasses the standard resolution order and may break in future updates.
 Ignored due to direct import
      </>,
    ],
    [
      'node_modules/expo-splash-screen/build/index.js',
      <>
        <YesIcon /> <code>expo-splash-screen/build/index.js</code>
      </>,
    ],
  ]}
/>
<a id="why-use-apppluginjs-for-plugins"></a>
### 为什么使用 app.plugin.js 插件
¥Why use app.plugin.js for plugins
`app.plugin.js` 方法是配置插件的首选，因为它允许与主包代码使用不同的转译设置。这一点尤为重要，因为 Node 环境通常需要与 Android、iOS 或 Web JS 环境不同的转译预设（例如，`module.exports` 而不是 `import/export`）。
¥The `app.plugin.js` approach is preferred for config plugins as it allows different transpilation settings from the main package code. This is particularly important because Node environments often require different transpilation presets compared to Android, iOS, or web JS environments (for example, `module.exports` instead of `import/export`).
[xml2js]: https://www.npmjs.com/package/xml2js
[expo-plist]: https://www.npmjs.com/package/@expo/plist


## 使用危险模块

了解危险模块以及如何在创建配置插件时使用它们。

Expo 中的危险模块可通过字符串操作和正则表达式直接访问原生项目文件。虽然 [现有模组插件](/config-plugins/mods) 是推荐的方法，但危险的 mods 可以充当现有 mod 插件无法实现的修改的逃生舱。
¥Dangerous mods in Expo provide direct access to native project files through string manipulation and regular expressions. While [existing mod plugins](/config-plugins/mods) are the recommended approach, dangerous mods serve as an escape hatch for modifications that cannot be achieved through existing mod plugins.
Note: Why are they considered dangerous?
---
Automated direct source code manipulation does not typically compose well. For example, if a dangerous mod replaces text in a source file, and a subsequent dangerous mod expects the original text to be there (perhaps it uses the original text as an anchor for a regular expression) then it is unlikely produce the desired result — depending on how it is written, it may either throw an error or log. Other types of mods are less prone to this type of problem, although it can happen with mods that manipulate source files directly like `withAndroidManifest` and `withPodfile`.
Unlike standard mods, which can run multiple times safely, dangerous mods are rarely guaranteed to be idempotent. Running the same dangerous mod multiple times may produce different results, cause duplicate modifications, or break the target file entirely.
---
<a id="when-to-use-a-dangerous-mod"></a>
## 何时使用危险模块
¥When to use a dangerous mod
在以下情况下，请考虑使用危险模块：
¥Consider using a dangerous mod when:
* 无法使用标准 mod 进行修改：你需要的修改不受现有修改插件（如 [`withAndroidManifest`](/config-plugins/mods/#android)、[`withPodfile`](/config-plugins/mods/#ios) 等）支持，或者库需要标准插件未涵盖的特定原生修改。
  ¥**Can't make the modification with a standard mod**: The modification you need isn't supported by existing mod plugins like [`withAndroidManifest`](/config-plugins/mods/#android), [`withPodfile`](/config-plugins/mods/#ios), and so on, or if a library requires specific native modifications that aren't covered by standard plugins.
* 与旧版 Expo SDK 的兼容性：你使用的是旧版 Expo SDK，其中不包含所需的 mod 插件。
  ¥**Legacy Expo SDK compatibility:** You are targeting an older Expo SDK version that doesn't include the mod plugin you need.
* 需要使用正则表达式或替换函数修改文本：你需要执行现有 mod 插件不支持的复杂文本操作。Expo 在内部使用危险的模块进行大型文件系统重构，例如，当库的名称更改时。
  ¥**Need to modify text with regexes or replace functions**: You need to perform intricate text manipulations that existing mod plugins do not support. Expo uses dangerous mods internally for large file system refactoring, for example, when a library's name changes.
<a id="how-to-use-a-dangerous-mod"></a>
## 如何使用危险模块
¥How to use a dangerous mod
在实际场景中，你可以按照 [创建配置插件部分](/config-plugins/plugins/#creating-a-config-plugin) 中的标准配置插件使用模式，直接在项目中使用本节中描述的示例配置插件。但是，有了现有的名为 [`withPodfile`](/config-plugins/mods/#ios) 的 mod 插件，你无需使用这个危险的 mod。以下示例仅用于演示如何创建和使用危险的模态框。
¥In a real-world scenario, you can use the example config plugin described in this section directly in your project by following the standard config plugin usage pattern from the [Creating a config plugin section](/config-plugins/plugins/#creating-a-config-plugin). However, with the existing mod plugin called [`withPodfile`](/config-plugins/mods/#ios), you don't have to use the dangerous mod. The example below is just for demonstration of how a dangerous mod can be created and used.
让我们看一个配置插件示例，该插件用于修改原生目录（ios）中的文件。当你在 Expo 项目中使用持续原生生成时，这非常有用。借助此配置插件，原生文件 (ios/Podfile) 将在 `npx expo prebuild` 命令运行时随时更新，无论你是手动运行还是使用 EAS Build。当现有 mod 插件无法编辑和更新原生目录中的文件时，此示例是一个理想的用例。
¥Let's take a look at an example config plugin to modify a file inside a native directory (**ios**). This is useful when you are using Continuous Native Generation in your Expo project. With the help of this config plugin, the native file (**ios/Podfile**) will update anytime the `npx expo prebuild` command runs, whether you run it manually or using EAS Build). This example is an ideal use case when an existing mod plugin cannot edit and update a file inside a native directory.
按照 [创建配置插件部分](/config-plugins/plugins/#creating-a-config-plugin) 中创建配置插件的目录结构和步骤（步骤 3、4 和 5），假设此配置插件是在 Expo 项目的 plugins 目录中创建的：
¥Following the directory structure and steps to create a config plugin (steps 3, 4, and 5) from [Creating a config plugin section](/config-plugins/plugins/#creating-a-config-plugin), let's assume this config plugin is created inside the **plugins** directory of your Expo project:
```tsx withCustomPodfile.ts
import { ConfigPlugin, IOSConfig, withDangerousMod } from 'expo/config-plugins';
import fs from 'fs/promises';
import path from 'path';
const withCustomPodfile: ConfigPlugin = config => {
  return withDangerousMod(config, [
    'ios',
    async config => {
      const podfilePath = path.join(config.modRequest.platformProjectRoot, 'Podfile');
      try {
        let contents = await fs.readFile(podfilePath, 'utf8');
        const projectName = IOSConfig.XcodeUtils.getProjectName(config.modRequest.projectRoot);
        contents = addCustomPod(contents, projectName);
        await fs.writeFile(podfilePath, contents);
        console.log('✅ Successfully added custom pod to Podfile');
      } catch (error) {
        console.warn('⚠️ Podfile not found, skipping modification');
      }
      return config;
    },
  ]);
};
function addCustomPod(contents: string, projectName: string): string {
  if (contents.includes("pod 'Alamofire'")) {
    console.log('Alamofire pod already exists, skipping');
    return contents;
  }
  const targetRegex = new RegExp(
    `(target ['"]${projectName}['"] do[\\s\\S]*?use_expo_modules!)`,
    'm'
  );
  return contents.replace(targetRegex, `$1\n  pod 'Alamofire', '~> 5.6'`);
}
export default withCustomPodfile;
```
在上面的示例中，withCustomPodfile 插件会在预构建过程中自动将 CocoaPod 依赖添加到项目的原生 ios/Podfile 中。它使用 `withDangerousMod` 直接提供对原生文件系统的访问，并在原生项目生成后、安装任何 CocoaPod 依赖之前运行。
¥In the example above, the plugin **withCustomPodfile** will add a CocoaPod dependency automatically to your project's native **ios/Podfile** during the prebuild process. It uses `withDangerousMod` to provide access to the native file system directly and run after the native project is generated, but before any CocoaPod dependency is installed.
Podfile 需要直接文本操作，这可以通过在 `addCustomMod` 函数中使用正则表达式模式来实现。此过程还需要将 CocoaPod 依赖插入到 Podfile 中的特定位置，该位置位于 `use_expo_modules!` 语句之后。
¥The **Podfile** requires direct text manipulation, which is done using a regex pattern inside `addCustomMod` function. This process also requires that the CocoaPod dependency is inserted into the **Podfile** at a specific location, which is after the `use_expo_modules!` statement.
<a id="withdangerousmod-syntax-and-requirements"></a>
## `withDangerousMod` 语法和要求
¥`withDangerousMod` syntax and requirements
使用 `withDangerousMod` 需要特定参数：
¥Using `withDangerousMod` requires certain parameters:
1. 原生平台（Android 或 iOS）
   ¥A native platform (**android** or **ios**)
2. 一个异步函数，接收具有文件系统访问权限的 `config` 对象
   ¥An asynchronous function that receives `config` object with file system access
3. 在原生目录中访问的相对文件名/路径
   ¥Relative file name/path to access inside the native directory
4. 读取现有文件，修改其内容，并写回文件
   ¥Reading the existing file, modifying its contents, and writing back to the file
5. （可选）在预构建过程中执行插件时，记录成功和失败状态的自定义消息。
   ¥(Optional) Log custom messages for success and failure state when a plugin executes during the prebuild process
以下代码片段提供了必填字段的框架，以及使用 `withDangerousMod` 时配置插件的结构：
¥The code snippet below provides a skeleton of the required field and how the config plugin can be structured when using `withDangerousMod`:
```tsx
import { ConfigPlugin, withDangerousMod } from 'expo/config-plugins';
import fs from 'fs/promises';
import path from 'path';
const myPlugin: ConfigPlugin = config => {
  return withDangerousMod(config, [
    'platform', // 1. "ios" | "android"
    async config => {
      // 2. Async modification function
      // 3. Build file paths
      const filePath = path.join(
        config.modRequest.platformProjectRoot, // Native project root
        'path/to/file' // Relative path to target file
      );
      try {
        // 4. Read existing file, modify its contents, and write back to the file
        let contents = await fs.readFile(filePath, 'utf8');
        contents = modifyContents(contents);
        await fs.writeFile(filePath, contents);
        // 5. Log success and failure states
        console.log('✅ Successfully modified file');
      } catch (error) {
        console.warn('⚠️ File modification failed:', error);
      }
      return config;
    },
  ]);
};
// Helper functions to use regex to modify the contents of the file
```
<a id="available-paths-in-config-plugins"></a>
### 配置插件中的可用路径
¥Available paths in config plugins
配置插件中可用的不同路径属性：
¥Different path properties available in config plugins:
| 路径                                            | 类型        | 描述                                                                                                                   |
| --------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------- |
| `config.modRequest.projectRoot`               | `string`  | package.json 所在的通用应用项目根目录。用于解析资源、读取 package.json 和跨平台操作。请务必验证目录是否存在且包含 package.json 文件。                              |
| `config.modRequest.platformProjectRoot`       | `string`  | 特定于平台的项目根目录（projectRoot/android 或 projectRoot/ios）。用于平台特定的文件操作，例如修改原生配置文件。确保平台目录相对于主 `projectRoot` 存在。               |
| `config.modRequest.projectName`               | `string`  | \[仅限 iOS] 用于构建 iOS 文件路径的项目名称组件（例如，projectRoot/ios/\[projectName]/）。用于 iOS 特定的文件路径构建。仅适用于 iOS 平台，且应与实际的 Xcode 项目结构匹配。 |
| `config.modRequest.introspect`                | `boolean` | 是否在内省模式下运行，该模式不应进行任何文件系统更改。使用 `true` 时，模块应该只读取和分析文件，而不能写入。用于配置分析和验证。                                                 |
| `config.modRequest.ignoreExistingNativeFiles` | `boolean` | 是否忽略现有的原生文件。用于基于模板的操作，尤其会影响授权和其他原生配置，以确保与预构建预期保持一致。                                                                  |
<a id="considerations-when-using-a-dangerous-mod"></a>
## 使用危险模块时的注意事项
¥Considerations when using a dangerous mod
使用危险模块时，请考虑以下事项：
¥When using a dangerous mod, consider the following:
* 有限的幂等性保证。标准模组通常是幂等的，无需使用 clean 标志即可运行，而危险模组很少能保证幂等。这意味着多次运行相同的危险模块可能会产生不同的结果或导致问题。
  ¥**Limited idempotency guarantees.** Unlike standard mods, which are generally idempotent and can work without the clean flag, dangerous mods are **rarely guaranteed to be idempotent**. This means running the same dangerous mod multiple times may produce different results or cause issues.
* 此功能尚处于实验阶段，容易出现问题。请谨慎使用 `withDangerousMod`，因为它将来可能会发生变化。在每次 SDK 发布时，请彻底测试你的危险模块，因为当原生模板发生更改时，它们特别容易损坏。
  ¥**Experimental and prone to breakage.** Be careful using `withDangerousMod` as it is subject to change in the future. Test your dangerous mods thoroughly with each SDK release, as they are especially prone to breakage when native template changes occur.
* 使用标准 mod 插件。Android 和 iOS 都提供 `withAndroidManifest`、`withPodfile`、`withPodfileProperties` 等 mod 插件，用于执行常见的原生文件修改。仅在没有 [可用的现有模组插件](/config-plugins/mods/#available-mod-plugins) 来处理你的用例时，才使用危险模块。
  ¥**Use standard mod plugins**. Both Android and iOS offer mod plugins like `withAndroidManifest`, `withPodfile`, `withPodfileProperties`, and so on, to perform common native file modifications. Only use a dangerous mod when there are no [existing mod plugins available](/config-plugins/mods/#available-mod-plugins) to handle your use case.
* 不要假设文件存在。在读取/写入文件之前，请务必检查原生目录及其相对路径。如果你使用 CNG，你可以随时运行 `npx expo prebuild` 来创建原生 android 和 ios 目录并手动验证文件的存在。
  ¥**Don't assume a file exists**. Always check the native directory and the relative path to the file before reading/writing to it. If you use CNG, you can always run `npx expo prebuild` to create native **android** and **ios** directories and manually verify a file's existence.
* 危险模组优先运行。危险修改的执行顺序可能不可靠，因为危险修改会先于其他修改器运行。这可能会影响构建过程的可预测性，并可能与其他修改发生冲突。
  ¥**Dangerous mods run first**. The order in which dangerous mods execute might be unreliable since dangerous mods run before other modifiers. This can affect the predictability of your build process and may cause conflicts with other modifications.


## 开发和调试插件

了解 Expo 配置插件的开发最佳实践和调试技术。

开发插件是扩展 Expo 生态系统的好方法。然而，有时你会想要调试你的插件。本页面提供了一些开发和调试插件的最佳实践。
¥Developing a plugin is a great way to extend the Expo ecosystem. However, there are times you'll want to debug your plugin. This page provides some of the best practices for developing and debugging a plugin.
<a id="plugin-development"></a>
## 插件开发
¥Plugin development
> 使用 [修改器预览](https://github.com/expo/vscode-expo#expo-preview-modifier) 实时调试插件的结果。
>
> ¥Use [modifier previews](https://github.com/expo/vscode-expo#expo-preview-modifier) to debug the results of your plugin live.
为了使插件开发更容易，我们在 [`expo-module-scripts`](https://www.npmjs.com/package/expo-module-scripts) 中添加了插件支持。有关使用 TypeScript 和 Jest 构建插件的更多信息，请参阅 [配置插件指南](https://github.com/expo/expo/tree/main/packages/expo-module-scripts#-config-plugin)。
¥To make plugin development easier, we've added plugin support to [`expo-module-scripts`](https://www.npmjs.com/package/expo-module-scripts).
Refer to the [config plugins guide](https://github.com/expo/expo/tree/main/packages/expo-module-scripts#-config-plugin) for more info on using TypeScript, and Jest to build plugins.
<a id="install-dependencies"></a>
### 安装依赖
¥Install dependencies
在提供配置插件的库中使用以下依赖：
¥Use the following dependencies in a library that provides a config plugin:
```json package.json
{
  "dependencies": {},
  "devDependencies": {
    "expo": "^53.0.0"
  },
  "peerDependencies": {
    "expo": ">=53.0.0"
  },
  "peerDependenciesMeta": {
    "expo": {
      "optional": true
    }
  }
}
```
* 你可以更新 `expo` 的确切版本以针对特定版本进行构建。
  ¥You may update the exact version of `expo` to build against a specific version.
* 对于依赖于核心、稳定 API 的简单配置插件（例如仅修改 AndroidManifest.xml 或 Info.plist 的插件），你可以使用松散依赖，如上例所示。
  ¥For simple config plugins that depend on core, stable APIs, such as a plugin that only modifies **AndroidManifest.xml** or **Info.plist**, you can use a loose dependency such as in the example above.
* 你可能还想安装 [`expo-module-scripts`](https://github.com/expo/expo/blob/main/packages/expo-module-scripts/README.md) 作为开发依赖，但这不是必需的。
  ¥You may also want to install [`expo-module-scripts`](https://github.com/expo/expo/blob/main/packages/expo-module-scripts/README.md) as a development dependency, but it's not required.
<a id="import-the-config-plugins-package"></a>
### 导入配置插件包
¥Import the config plugins package
`expo/config-plugins` 和 `expo/config` 包是从 `expo` 包重新导出的。
¥The `expo/config-plugins` and `expo/config` packages are re-exported from the `expo` package.
```js
const { ... } = require('expo/config-plugins');
const { ... } = require('expo/config');
```
通过 `expo` 包导入可确保你使用 `expo` 包所依赖的 `expo/config-plugins` 和 `expo/config` 包的版本。
¥Importing through the `expo` package ensures that you are using the version of the `expo/config-plugins` and `expo/config` packages that are depended on by the `expo` package.
如果你不通过这种方式通过 `expo` 重新导出导入包，你可能会意外导入不兼容的版本（取决于使用该模块的开发者使用的包管理器中模块提升的实现细节）或者无法 完全导入模块（如果使用包管理器（例如 Yarn Berry 或 pnpm）的 "即插即用" 功能）。
¥If you do not import the package through the `expo` re-export in this way, you may accidentally be importing an incompatible version
(depending on the implementation details of module hoisting in the package manager used by the developer consuming the module) or be unable to import the module at all (if using "plug and play" features of a package manager such as Yarn Berry or pnpm).
配置类型直接从 `expo/config` 导出，因此无需安装或从 `expo/config-types` 导入：
¥Config types are exported directly from `expo/config`, so there is no need to install or import from `expo/config-types`:
```ts
import { ExpoConfig, ConfigContext } from 'expo/config';
```
<a id="plugin-development-best-practices"></a>
### 插件开发最佳实践
¥Plugin development best practices
* 自述文件中的说明：如果插件与 React Native 模块绑定，那么你应该记录该包的手动设置说明。如果插件出现任何问题，开发者应该能够手动添加插件自动执行的项目修改。这也允许你支持未使用 [CNG](/workflow/continuous-native-generation/) 的项目。
  ¥**Instructions in your README**: If the plugin is tied to a React Native module, then you should document manual setup instructions for the package. If anything goes wrong with the plugin, developers should be able to manually add the project modifications that were automated by the plugin. This also allows you to support projects that are not using [CNG](/workflow/continuous-native-generation/).
  * 记录插件的可用属性，并指定是否有任何必需的属性。
    ¥Document the available properties for the plugin, specifying if any of the properties are required.
  * 如果可能，插件应该是幂等的，这意味着无论它们是在新的原生项目模板上运行，还是在已经存在更改的项目模板上再次运行，它们所做的更改都是相同的。这允许开发者在不使用 `--clean` 标志的情况下运行 `npx expo prebuild` 来同步配置更改，而无需完全重新创建原生项目。对于危险的模块，这可能更加困难。
    ¥If possible, plugins should be idempotent, meaning the changes they make are the same whether they are run on a fresh native project template or run again on a project template where its changes already exist. This allows developers to run `npx expo prebuild` without the `--clean` flag to sync changes to the config, rather than recreating the native project entirely. This may be more difficult with dangerous mods.
* 命名约定：如果插件函数名称适用于所有平台，请使用 `withFeatureName` 作为函数名称。如果插件是平台特定的，请使用驼峰式命名法，并在 "with" 之后紧跟平台名称。例如，`withAndroidSplash`、`withIosSplash`。
  ¥**Naming conventions**: Use `withFeatureName` for the plugin function name if it applies to all platforms. If the plugin is platform-specific, use a camel case naming with the platform right after "with". For example, `withAndroidSplash`, `withIosSplash`.
* 利用内置插件：如果 [应用配置](/versions/latest/config/app/) 和 [预构建配置](https://github.com/expo/expo/blob/main/packages/%40expo/prebuild-config/src/plugins/withDefaultPlugins.ts) 中已经有可用的配置，则无需为其编写配置插件。
  ¥**Leverage built-in plugins**: If there's already a configuration available in [app config](/versions/latest/config/app/) and [prebuild config](https://github.com/expo/expo/blob/main/packages/%40expo/prebuild-config/src/plugins/withDefaultPlugins.ts), you don't need to write a config plugin for it.
* 按平台拆分插件：在配置插件中使用函数时，请按平台拆分它们。例如，`withAndroidSplash`、`withIosSplash`。这使得在 `npx expo prebuild` 模式下使用 `--platform` 标志在 `EXPO_DEBUG` 模式下更容易遵循，因为日志将显示正在执行哪些特定于平台的功能。
  ¥**Split up plugins by platform**: When using functions within the config plugin, split them by platform. For example, `withAndroidSplash`, `withIosSplash`. This makes using the `--platform` flag in `npx expo prebuild` a bit easier to follow in `EXPO_DEBUG` mode, as the logging will show which platform-specific functions are being executed.
* 对你的插件进行单元测试：为复杂的修改编写 Jest 测试。如果你的插件需要访问文件系统，请使用模拟系统（我们强烈推荐 [`memfs`][memfs]），你可以在 [`expo-notifications`](https://github.com/expo/expo/blob/fc3fb2e81ad3a62332fa1ba6956c1df1c3186464/packages/expo-notifications/plugin/src/__tests__/withNotificationsAndroid-test.ts#L34) 插件测试中看到这方面的示例。
  ¥**Unit test your plugin**: Write Jest tests for complex modifications. If your plugin requires access to the filesystem,
  use a mock system (we strongly recommend [`memfs`][memfs]), you can see examples of this in the [`expo-notifications`](https://github.com/expo/expo/blob/fc3fb2e81ad3a62332fa1ba6956c1df1c3186464/packages/expo-notifications/plugin/src/__tests__/withNotificationsAndroid-test.ts#L34) plugin tests.
  * 请注意根 [**/**mocks**/**/*](https://github.com/expo/expo/tree/main/packages/expo-notifications/plugin/__mocks__) 目录和 [**plugin/jest.config.js**](https://github.com/expo/expo/tree/main/packages/expo-notifications/plugin/jest.config.js)。
    ¥Notice the root [**/__mocks__/**/*](https://github.com/expo/expo/tree/main/packages/expo-notifications/plugin/__mocks__) directory and [**plugin/jest.config.js**](https://github.com/expo/expo/tree/main/packages/expo-notifications/plugin/jest.config.js).
* TypeScript 插件总是比 JavaScript 插件更好。查看 [`expo-module-scripts` 插件][ems-plugin] 工具了解更多信息。
  ¥A TypeScript plugin is always better than a JavaScript plugin. Check out the [`expo-module-scripts` plugin][ems-plugin] tooling for more info.
* 不要通过配置插件修改 `sdkVersion`，这可能会破坏 `expo install` 等命令并导致其他意外问题。
  ¥Do not modify the `sdkVersion` via a config plugin, this can break commands like `expo install` and cause other unexpected issues.
<a id="best-practices-for-mods"></a>
### Mod 的最佳实践
¥Best practices for mods
* 避免使用正则表达式：[静态修改](#static-modification) 是关键。如果你想修改 Android gradle 文件中的值，请考虑使用 `gradle.properties`。如果你想修改 Podfile 中的某些代码，请考虑写入 JSON 并让 Podfile 读取静态值。
  ¥Avoid regex: [static modification](#static-modification) is key. If you want to modify a value in an Android gradle file, consider using `gradle.properties`. If you want to modify some code in the Podfile, consider writing to JSON and having the Podfile read the static values.
* 避免执行长时间运行的任务，例如发出网络请求或在 mod 中安装 Node 模块。
  ¥Avoid performing long-running tasks like making network requests or installing Node modules in mods.
* 不要在 mod 中添加交互式终端提示。
  ¥Do not add interactive terminal prompts in mods.
* 仅在危险模组中生成、移动和删除新文件。否则将会破坏 [introspection](#introspection)。
  ¥Generate, move, and delete new files in dangerous mods only. Failing to do so will break [introspection](#introspection).
* 利用 `withXcodeProject` 等内置配置插件来最大限度地减少文件读取和解析的次数。
  ¥Utilize built-in config plugins like `withXcodeProject` to minimize the amount of times a file is read and parsed.
* 坚持使用预构建内部使用的 XML 解析库，这有助于防止不必要地重新排列代码的更改。
  ¥Stick with the XML parsing libraries that prebuild uses internally, this helps prevent changes where code is rearranged needlessly.
<a id="plugin-structure-and-scaffolding"></a>
## 插件结构和搭建
¥Plugin structure and scaffolding
<a id="versioning"></a>
### 版本控制
¥Versioning
默认情况下，`npx expo prebuild` 在与项目正在使用的 Expo SDK 版本关联的 [源模板][source-template] 上运行转换。SDK 版本在 app.json 中定义或从项目安装的 `expo` 版本推断。
¥By default, `npx expo prebuild` runs transformations on a [source template][source-template] associated with the Expo SDK version that a project is using. The SDK version is defined in the **app.json** or inferred from the installed version of `expo` that the project has.
例如，当 Expo SDK 升级到 React Native 的新版本时，模板可能会发生重大变化，以适应 React Native 或 Android 或 iOS 新版本的变化。
¥When Expo SDK upgrades to a new version of React Native for instance, the template may change significantly to account for changes in React Native or new releases of Android or iOS.
如果你的插件主要使用 [静态修改](#static-modification)，那么它通常可以跨 SDK 版本正常运行。如果它使用正则表达式来转换应用代码，那么你肯定需要记录你的插件适用于哪个 Expo SDK 版本。在 SDK 发布周期中，有一个 [测试期](https://github.com/expo/expo/blob/main/guides/releasing/Release%20Workflow.md#stage-4---beta-release)，你可以在新版本发布之前测试插件是否兼容新版本。
¥If your plugin is mostly using [static modifications](#static-modification) then it will usually work well across SDK versions. If it's using a regular expression to transform application code, then you'll definitely want to document which Expo SDK version your plugin is intended for. During the SDK release cycle, there is a [beta period](https://github.com/expo/expo/blob/main/guides/releasing/Release%20Workflow.md#stage-4---beta-release) where you can test if your plugin works with the new version before it's released.
<a id="plugin-properties"></a>
### 插件属性
¥Plugin properties
属性用于自定义插件在预构建期间的工作方式。它们必须始终为静态值（无函数或 promise）。考虑以下类型：
¥Properties are used to customize the way a plugin works during prebuild. They must always be static values (no functions, or promises). Consider the following types:
```ts
type StaticValue = boolean | number | string | null | StaticArray | StaticObject;
type StaticArray = StaticValue[];
interface StaticObject {
  [key: string]: StaticValue | undefined;
}
```
需要静态属性，因为应用配置必须可序列化为 JSON 才能用作应用清单。
¥Static properties are required because the app config must be serializable to JSON for use as the app manifest.
如果可能的话，尝试让你的插件在没有 props 的情况下工作，这将有助于像 [`expo install`](#expo-install) 或 [VS Code Expo 工具][vscode-expo] 这样的解析工具更好地工作。请记住，你添加的每个属性都会增加复杂性，使其将来更难更改，并增加你需要测试的功能数量。在可行的情况下，良好的默认值优于强制配置。
¥If possible, attempt to make your plugin work without props, this will help resolution tooling like [`expo install`](#expo-install) or [VS Code Expo Tools][vscode-expo] work better. Remember that every property you add increases complexity, making it harder to change in the future and increases the amount of features you'll need to test. Good default values are preferred over mandatory configuration when feasible.
<a id="development-environment"></a>
## 开发环境
¥Development environment
<a id="tooling"></a>
### 工具
¥Tooling
我们强烈建议安装 [Expo 工具 VS Code 扩展][vscode-expo]，因为这将对插件执行自动验证并显示错误信息以及配置插件开发的其他生活质量改进。
¥We highly recommend installing the [Expo Tools VS Code extension][vscode-expo]
as this will perform automatic validation on the plugins and surface error information along with other quality of life improvements for Config Plugin development.
<a id="set-up-a-playground-environment"></a>
### 设置 Playground 环境
¥Set up a playground environment
你可以使用 JS 轻松开发插件，但如果你想设置 Jest 测试并使用 TypeScript，则需要一个 monorepo。
¥You can develop plugins easily using JS, but if you want to set up Jest tests and use TypeScript, you will want a monorepo.
monorepo 将使你能够处理节点模块并将其导入你的应用配置中，就像将其发布到 npm 一样。Expo 配置插件内置了完整的 monorepo 支持，因此你只需设置一个项目即可。
¥A monorepo will enable you to work on a node module and import it in your app config like you would if it were published to npm. Expo config plugins have full monorepo support built-in so all you need to do is set up a project.
在你的 monorepo 的 `packages/` 目录中，创建一个模块，并在其中创建 [引导配置插件](https://github.com/expo/expo/tree/main/packages/expo-module-scripts#-config-plugin)。
¥In your monorepo's `packages/` directory, create a module, and [bootstrap a config plugin](https://github.com/expo/expo/tree/main/packages/expo-module-scripts#-config-plugin) in it.
<a id="manually-run-a-plugin"></a>
### 手动运行插件
¥Manually run a plugin
如果你不习惯设置 monorepo，可以尝试手动运行插件：
¥If you aren't comfortable setting up a monorepo, you can try manually running a plugin:
* 使用配置插件运行包中的 `npm pack`
  ¥Run `npm pack` in the package with the config plugin
* 在你的测试项目中，运行 `npm install path/to/react-native-my-package-1.0.0.tgz`，这会将包添加到你的 package.json `dependencies` 对象中。
  ¥In your test project, run `npm install path/to/react-native-my-package-1.0.0.tgz`, this will add the package to your **package.json** `dependencies` object.
* 将包添加到 app.json 中的 `plugins` 数组中：`{ "plugins": ["react-native-my-package"] }`
  ¥Add the package to the `plugins` array in your **app.json**: `{ "plugins": ["react-native-my-package"] }`
  * 如果你安装了 [VS Code Expo 工具][vscode-expo]，自动补齐功能应该适用于该插件。
    ¥If you have [VS Code Expo Tools][vscode-expo] installed, autocomplete should work for the plugin.
* 如果需要更新包，请更改包的 package.json 中的 `version` 并重复该过程。
  ¥If you need to update the package, change the `version` in the package's **package.json** and repeat the process.
<a id="modifying-native-files-with-plugins"></a>
## 使用插件修改原生文件
¥Modifying native files with plugins
<a id="modify-androidmanifestxml"></a>
### 修改 AndroidManifest.xml
¥Modify AndroidManifest.xml
在使用配置插件之前，包应尝试使用内置的 AndroidManifest.xml [合并系统](https://developer.android.com/studio/build/manage-manifests)。这可用于静态的、非可选的功能，例如权限。这将确保功能在构建时合并，而不是在预构建时合并，从而最大限度地减少用户因忘记预构建而导致配置丢失的可能性。缺点是用户无法使用 [introspection](#introspection) 预览更改并调试任何潜在问题。
¥Packages should attempt to use the built-in **AndroidManifest.xml** [merging system](https://developer.android.com/studio/build/manage-manifests) before using a config plugin. This can be used for static, non-optional features like permissions. This will ensure features are merged during build-time and not prebuild-time, which minimizes the possibility of the configuration being missed due to users forgetting to prebuild. The drawback is that users cannot use [introspection](#introspection) to preview the changes and debug any potential issues.
下面是一个包的 AndroidManifest.xml 示例，它注入了所需的权限：
¥Here is an example of a package's **AndroidManifest.xml**, which injects a required permission:
```xml AndroidManifest.xml
<!-- @info Include <code>xmlns:android="..."</code> to use <code>android:*</code> properties like <code>android:name</code> in your manifest. -->
<manifest package="expo.modules.filesystem" xmlns:android="http://schemas.android.com/apk/res/android">
  <!-- @end -->
  <uses-permission android:name="android.permission.INTERNET"/>
</manifest>
```
如果你正在为本地项目构建插件，或者你的包需要更多控制，那么你应该实现一个插件。
¥If you're building a plugin for your local project, or if your package needs more control, then you should implement a plugin.
你可以使用内置类型和助手来简化处理复杂对象的过程。下面是将 `<meta-data android:name="..." android:value="..."/>` 添加到默认 `<application android:name=".MainApplication" />` 的示例。
¥You can use built-in types and helpers to ease the process of working with complex objects.
Here's an example of adding a `<meta-data android:name="..." android:value="..."/>` to the default `<application android:name=".MainApplication" />`.
```ts my-config-plugin.ts
import { AndroidConfig, ConfigPlugin, withAndroidManifest } from 'expo/config-plugins';
import { ExpoConfig } from 'expo/config';
// Using helpers keeps error messages unified and helps cut down on XML format changes.
const { addMetaDataItemToMainApplication, getMainApplicationOrThrow } = AndroidConfig.Manifest;
export const withMyCustomConfig: ConfigPlugin = config => {
  return withAndroidManifest(config, async config => {
    // Modifiers can be async, but try to keep them fast.
    config.modResults = await setCustomConfigAsync(config, config.modResults);
    return config;
  });
};
// Splitting this function out of the mod makes it easier to test.
async function setCustomConfigAsync(
  config: Pick<ExpoConfig, 'android'>,
  androidManifest: AndroidConfig.Manifest.AndroidManifest
): Promise<AndroidConfig.Manifest.AndroidManifest> {
  const appId = 'my-app-id';
  // Get the <application /> tag and assert if it doesn't exist.
  const mainApplication = getMainApplicationOrThrow(androidManifest);
  addMetaDataItemToMainApplication(
    mainApplication,
    // value for `android:name`
    'my-app-id-key',
    // value for `android:value`
    appId
  );
  return androidManifest;
}
```
<a id="modify-infoplist"></a>
### 修改 Info.plist
¥Modify Info.plist
使用 `withInfoPlist` 比静态修改 app.json 中的 `expo.ios.infoPlist` 对象更安全，因为它会读取 Info.plist 的内容并将其与 `expo.ios.infoPlist` 合并，这意味着你可以尝试防止更改被覆盖。
¥Using the `withInfoPlist` is a bit safer than statically modifying the `expo.ios.infoPlist` object in the **app.json** because it reads the contents of the Info.plist and merges it with the `expo.ios.infoPlist`, this means you can attempt to keep your changes from being overwritten.
下面是将 `GADApplicationIdentifier` 添加到 Info.plist 的示例：
¥Here's an example of adding a `GADApplicationIdentifier` to the **Info.plist**:
```ts my-config-plugin.ts
import { ConfigPlugin, withInfoPlist } from 'expo/config-plugins';
// Pass `<string>` to specify that this plugin requires a string property.
export const withCustomConfig: ConfigPlugin<string> = (config, id) => {
  return withInfoPlist(config, config => {
    config.modResults.GADApplicationIdentifier = id;
    return config;
  });
};
```
<a id="modify-ios-podfile"></a>
### 修改 iOS Podfile
¥Modify iOS Podfile
iOS Podfile 是 CocoaPods（iOS 上的依赖管理器）的配置文件。它类似于 iOS 的 package.json。Podfile 是一个 Ruby 文件，这意味着你无法从 Expo 配置插件安全地修改它，而应该选择另一种方法，例如 [Expo 自动链接](/modules/autolinking) 钩子。
¥The iOS **Podfile** is the config file for CocoaPods, the dependency manager on iOS. It is similar to **package.json** for iOS.
The **Podfile** is a Ruby file, which means you **cannot** safely modify it from Expo config plugins and should opt for another approach, such as [Expo Autolinking](/modules/autolinking) hooks.
我们确实公开了一种与 Podfile 安全交互的机制，但它非常有限。版本化的 [模板 Podfile](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum/ios/Podfile) 被硬编码为从静态 JSON 文件 Podfile.properties.json 中读取，我们公开了一个 mod (`ios.podfileProperties`, `withPodfileProperties`) 来安全地从此文件中读取和写入。这由 [expo-build-properties](/versions/latest/sdk/build-properties) 使用并配置 JavaScript 引擎。
¥We do expose one mechanism for safely interacting with the Podfile, but it's very limited.
The versioned [template Podfile](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum/ios/Podfile) is hard coded to read
from a static JSON file **Podfile.properties.json**, we expose a mod (`ios.podfileProperties`, `withPodfileProperties`) to safely read and write from this file.
This is used by [expo-build-properties](/versions/latest/sdk/build-properties) and to configure the JavaScript engine.
<a id="add-plugins-to-pluginhistory"></a>
### 添加插件到 `pluginHistory`
¥Add plugins to `pluginHistory`
创建 `_internal.pluginHistory` 是为了防止在从旧版未版本插件迁移到版本化插件时运行重复插件。
¥`_internal.pluginHistory` was created to prevent duplicate plugins from running while migrating from legacy UNVERSIONED plugins to versioned plugins.
```ts my-config-plugin.ts
import { ConfigPlugin, createRunOncePlugin } from 'expo/config-plugins';
// Keeping the name, and version in sync with it's package.
const pkg = require('my-cool-plugin/package.json');
const withMyCoolPlugin: ConfigPlugin = config => config;
// A helper method that wraps `withRunOnce` and appends items to `pluginHistory`.
export default createRunOncePlugin(
  // The plugin to guard.
  withMyCoolPlugin,
  // An identifier used to track if the plugin has already been run.
  pkg.name,
  // Optional version property, if omitted, defaults to UNVERSIONED.
  pkg.version
);
```
<a id="configure-android-app-startup"></a>
### 配置 Android 应用启动
¥Configure Android app startup
你可能会发现你的项目需要在 JS 引擎启动之前进行配置。例如，在 Android 上的 `expo-splash-screen` 中，我们需要在 MainActivity.java 的 `onCreate` 方法中指定调整大小模式。我们没有尝试通过危险的 mod 将这些更改危险地正则表达式到 `MainActivity` 中，而是使用生命周期钩子和静态设置系统来安全地确保该功能在所有受支持的 Android 语言（Java、Kotlin）、Expo 版本以及 配置插件。
¥You may find that your project requires configuration to be setup before the JS engine has started.
For example, in `expo-splash-screen` on Android, we need to specify the resize mode in the **MainActivity.java**'s `onCreate` method.
Instead of attempting to dangerously regex these changes into the `MainActivity` via a dangerous mod, we use a system of lifecycle hooks and static settings
to safely ensure the feature works across all supported Android languages (Java, Kotlin), versions of Expo, and combination of config plugins.
该系统由三个组件组成：
¥This system is made up of three components:
* `ReactActivityLifecycleListeners`：`expo-modules-core` 公开的接口，用于在调用项目 `ReactActivity` 的 `onCreate` 方法时获取原生回调。
  ¥`ReactActivityLifecycleListeners`: An interface exposed by `expo-modules-core` to get a native callback when the project `ReactActivity`'s `onCreate` method is invoked.
* `withStringsXml`：`expo/config-plugins` 公开的 mod，它将属性写入 Android strings.xml 文件，该库可以安全地读取 strings.xml 值并进行初始设置。字符串 XML 值遵循指定的格式以保持一致性。
  ¥`withStringsXml`: A mod exposed by `expo/config-plugins` which writes a property to the Android **strings.xml** file, the library can safely read the strings.xml value and do initial setup. The string XML values follow a designated format for consistency.
* `SingletonModule`（可选）：`expo-modules-core` 公开的接口，用于在原生模块和 `ReactActivityLifecycleListeners` 之间创建共享接口。
  ¥`SingletonModule` (optional): An interface exposed by `expo-modules-core` to create a shared interface between native modules and `ReactActivityLifecycleListeners`.
考虑这个例子：我们希望在调用 `onCreate` 方法后立即将自定义 "value" 字符串设置为 Android `Activity` 上的属性。我们可以通过创建节点模块 `expo-custom`、实现 `expo-modules-core` 和 Expo 配置插件来安全地做到这一点：
¥Consider this example: We want to set a custom "value" string to a property on the Android `Activity`, directly after the `onCreate` method was invoked.
We can do this safely by creating a node module `expo-custom`, implementing `expo-modules-core`, and Expo config plugins:
首先，我们在 Android 原生模块中注册 `ReactActivity` 监听器，只有当用户在其项目中设置了 `expo-modules-core` 支持时才会调用此监听器（默认在使用 Expo CLI、Create React Native App、Ignite CLI 和 Expo 预构建引导的项目中） 。
¥First, we register the `ReactActivity` listener in our Android native module, this will only be invoked if the user has `expo-modules-core` support, setup in their project (default in projects bootstrapped with Expo CLI, Create React Native App, Ignite CLI, and Expo prebuilding).
```kotlin expo-custom/android/src/main/java/expo/modules/custom/CustomPackage.kt
package expo.modules.custom
import android.content.Context
import expo.modules.core.BasePackage
import expo.modules.core.interfaces.ReactActivityLifecycleListener
class CustomPackage : BasePackage() {
  override fun createReactActivityLifecycleListeners(activityContext: Context): List<ReactActivityLifecycleListener> {
    return listOf(CustomReactActivityLifecycleListener(activityContext))
  }
  // ...
}
```
接下来我们实现 `ReactActivity` 监听器，它传递给 `Context` 并且能够从项目 strings.xml 文件中读取。
¥Next we implement the `ReactActivity` listener, this is passed the `Context` and is capable of reading from the project **strings.xml** file.
```kotlin expo-custom/android/src/main/java/expo/modules/custom/CustomReactActivityLifecycleListener.kt
package expo.modules.custom
import android.app.Activity
import android.content.Context
import android.os.Bundle
import android.util.Log
import expo.modules.core.interfaces.ReactActivityLifecycleListener
class CustomReactActivityLifecycleListener(activityContext: Context) : ReactActivityLifecycleListener {
  override fun onCreate(activity: Activity, savedInstanceState: Bundle?) {
    // Execute static tasks before the JS engine starts.
    // These values are defined via config plugins.
    var value = getValue(activity)
    if (value != "") {
      // Do something to the Activity that requires the static value...
    }
  }
  // Naming is node module name (`expo-custom`) plus value name (`value`) using underscores as a delimiter
  // i.e. `expo_custom_value`
  // `@expo/vector-icons` + `iconName` -> `expo__vector_icons_icon_name`
  private fun getValue(context: Context): String = context.getString(R.string.expo_custom_value).toLowerCase()
}
```
我们必须定义默认的 string.xml 值，用户将通过在 strings.xml 文件中使用相同的 `name` 属性在本地覆盖这些值。
¥We must define default **string.xml** values which the user will overwrite locally by using the same `name` property in their **strings.xml** file.
```xml expo-custom/android/src/main/res/values/strings.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="expo_custom_value" translatable="false"></string>
</resources>
```
此时，裸用户可以通过在本地 strings.xml 文件中创建字符串来配置此值（假设他们也有 `expo-modules-core` 支持设置）：
¥At this point, bare users can configure this value by creating a string in their local **strings.xml** file (assuming they also have `expo-modules-core` support setup):
```xml ./android/app/src/main/res/values/strings.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="expo_custom_value" translatable="false">I Love Expo</string>
</resources>
```
对于托管用户，我们可以通过 Expo 配置插件公开此功能（安全！）：
¥For managed users, we can expose this functionality (safely!) via an Expo config plugin:
```js expo-custom/app.plugin.js
const { AndroidConfig, withStringsXml } = require('expo/config-plugins');
function withCustom(config, value) {
  return withStringsXml(config, config => {
    config.modResults = setStrings(config.modResults, value);
    return config;
  });
}
function setStrings(strings, value) {
  // Helper to add string.xml JSON items or overwrite existing items with the same name.
  return AndroidConfig.Strings.setStringItem(
    [
      // XML represented as JSON
      // <string name="expo_custom_value" translatable="false">value</string>
      { $: { name: 'expo_custom_value', translatable: 'false' }, _: value },
    ],
    strings
  );
}
```
托管 Expo 用户现在可以与此 API 进行交互，如下所示：
¥Managed Expo users can now interact with this API like so:
```json app.json
{
  "expo": {
    "plugins": [["expo-custom", "I Love Expo"]]
  }
}
```
通过重新运行 `npx expo prebuild -p`（`eas build -p android` 或 `npx expo run:ios`），用户现在可以看到更改，并安全地应用到他们的托管项目中！
¥By re-running `npx expo prebuild -p` (`eas build -p android`, or `npx expo run:ios`) the user can now see the changes, safely applied in their managed project!
正如你从示例中看到的，我们严重依赖应用代码 (expo-modules-core) 与应用代码（原生项目）进行交互。这确保了我们的配置插件安全可靠，希望在很长一段时间内都是安全可靠的！
¥As you can see from the example, we rely heavily on application code (expo-modules-core) to interact with application code (the native project). This ensures that our config plugins are safe and reliable, hopefully for a very long time!
<a id="debugging-config-plugins"></a>
## 调试配置插件
¥Debugging config plugins
你可以通过运行 `EXPO_DEBUG=1 expo prebuild` 来调试配置插件。如果启用了 `EXPO_DEBUG`，将打印插件堆栈日志，这些日志对于查看运行了哪些 mod 以及它们运行的顺序非常有用。要查看所有静态插件解析错误，请启用 `EXPO_CONFIG_PLUGIN_VERBOSE_ERRORS`，只有插件作者需要这样做。默认情况下，一些自动插件错误是隐藏的，因为它们通常与版本控制问题相关并且不是很有帮助（也就是说，旧版包还没有配置插件）。
¥You can debug config plugins by running `EXPO_DEBUG=1 expo prebuild`. If `EXPO_DEBUG` is enabled, the plugin stack logs will be printed, these are useful for viewing which mods ran, and in what order they ran in. To view all static plugin resolution errors, enable `EXPO_CONFIG_PLUGIN_VERBOSE_ERRORS`, this should only be needed for plugin authors. By default, some automatic plugin errors are hidden because they're usually related to versioning issues and aren't very helpful (that is, legacy package doesn't have a config plugin yet).
运行 `npx expo prebuild --clean` 将在编译之前删除生成的原生目录。
¥Running `npx expo prebuild --clean` will remove the generated native directories before compiling.
你还可以运行 `npx expo config --type prebuild` 来打印未评估 mod 的插件结果（不生成代码）。
¥You can also run `npx expo config --type prebuild` to print the results of the plugins with the mods unevaluated (no code is generated).
可以使用 `EXPO_PROFILE=1` 来分析 Expo CLI 命令。
¥Expo CLI commands can be profiled using `EXPO_PROFILE=1`.
<a id="introspection"></a>
## 内省
¥Introspection
内省是一种高级的技术，用于读取修饰符的评估结果，而无需在项目中生成任何代码。这可用于快速调试 [静态修改](#static-modification) 的结果，而无需运行预构建。你可以使用 [预览功能](https://github.com/expo/vscode-expo#expo-preview-modifier) 或 `vscode-expo` 与内省进行实时交互。
¥Introspection is an advanced technique used to read the evaluated results of modifiers without generating any code in the project.
This can be used to quickly debug the results of [static modifications](#static-modification) without needing to run prebuild.
You can interact with introspection live, by using the [preview feature](https://github.com/expo/vscode-expo#expo-preview-modifier) of `vscode-expo`.
你可以通过在项目中运行 `expo config --type introspect` 来尝试内省。
¥You can try introspection by running `expo config --type introspect` in a project.
内省仅支持修饰符的子集：
¥Introspection only supports a subset of modifiers:
* `android.manifest`
* `android.gradleProperties`
* `android.strings`
* `android.colors`
* `android.colorsNight`
* `android.styles`
* `ios.infoPlist`
* `ios.entitlements`
* `ios.expoPlist`
* `ios.podfileProperties`
> 自省仅适用于安全修饰符（静态文件，如 JSON、XML、plist、属性），但 `ios.xcodeproj` 除外，它通常需要更改文件系统，因此不具有幂等性。
>
> ¥Introspection only works on safe modifiers (static files like JSON, XML, plist, properties), except `ios.xcodeproj` which often requires file system changes, making it non idempotent.
内省通过创建自定义基本 mod 来工作，这些自定义基本 mod 的工作方式与默认基本 mod 类似，只是它们最后不会将 `modResults` 写入磁盘。他们没有保留结果，而是将结果保存到 `_internal.modResults` 下的应用配置中，后跟 mod 的名称，例如 `ios.infoPlist` mod 保存到 `_internal.modResults.ios.infoPlist: {}`。
¥Introspection works by creating custom base mods that work like the default base mods, except they don't write the `modResults` to disk at the end.
Instead of persisting, they save the results to the app config under `_internal.modResults`, followed by the name of the mod
such as the `ios.infoPlist` mod saves to `_internal.modResults.ios.infoPlist: {}`.
作为一个现实世界的示例，`eas-cli` 使用内省来确定托管应用中的最终 iOS 权利，因此它可以在构建之前将它们与 Apple 开发者门户同步。Introspection 还可以用作方便的调试和开发工具。
¥As a real-world example, introspection is used by `eas-cli` to determine what the final iOS entitlements will be in a managed app, so it can sync them with the Apple Developer Portal before building. Introspection can also be used as a handy debugging and development tool.
<a id="legacy-plugins"></a>
## 旧版插件
¥Legacy plugins
为了使 `eas build` 与经典 `expo build` 服务一样工作，我们添加了对 "旧版插件" 的支持，当它们安装在项目中时，它们会自动应用于项目。
¥To make `eas build` work the same as the classic `expo build` service, we added support for "legacy plugins" which are applied automatically to a project when they're installed in the project.
例如，假设一个项目安装了 `expo-camera`，但其 app.json 中没有 `plugins: ['expo-camera']`。Expo CLI 会自动将 `expo-camera` 添加到插件中，以确保将所需的摄像头和麦克风权限添加到项目中。用户仍然可以通过手动将 `expo-camera` 插件添加到 `plugins` 数组来自定义 `expo-camera` 插件，并且手动定义的插件将优先于自动插件。
¥For instance, say a project has `expo-camera` installed but doesn't have `plugins: ['expo-camera']` in their **app.json**.
Expo CLI would automatically add `expo-camera` to the plugins to ensure that the required camera and microphone permissions are added to the project.
The user can still customize the `expo-camera` plugin by adding it to the `plugins` array manually, and the manually defined plugins will take precedence over the automatic plugins.
你可以通过运行 `expo config --type prebuild` 并查看 `_internal.pluginHistory` 属性来调试添加了哪些插件。
¥You can debug which plugins were added by running `expo config --type prebuild` and seeing the `_internal.pluginHistory` property.
这将显示一个对象，其中包含使用 `expo/config-plugins` 中的 `withRunOnce` 插件添加的所有插件。
¥This will show an object with all plugins that were added using `withRunOnce` plugin from `expo/config-plugins`.
请注意，`expo-location` 使用 `version: '11.0.0'`，`react-native-maps` 使用 `version: 'UNVERSIONED'`。这意味着以下内容：
¥Notice that `expo-location` uses `version: '11.0.0'`, and `react-native-maps` uses `version: 'UNVERSIONED'`. This means the following:
* `expo-location` 和 `react-native-maps` 都安装在项目中。
  ¥`expo-location` and `react-native-maps` are both installed in the project.
* `expo-location` 正在使用项目 `node_modules/expo-location/app.plugin.js` 中的插件
  ¥`expo-location` is using the plugin from the project's `node_modules/expo-location/app.plugin.js`
* 项目中安装的 `react-native-maps` 版本没有插件，因此它依靠 `expo-cli` 附带的未版本化插件来提供旧版支持。
  ¥The version of `react-native-maps` installed in the project doesn't have a plugin, so it's falling back on the unversioned plugin that is shipped with `expo-cli` for legacy support.
```json
{
  _internal: {
    pluginHistory: {
      'expo-location': {
        name: 'expo-location',
        version: '11.0.0',
      },
      'react-native-maps': {
        name: 'react-native-maps',
        version: 'UNVERSIONED',
      },
    },
  },
};
```
为了获得最稳定的体验，你应该尝试在项目中没有 `UNVERSIONED` 插件。这是因为 `UNVERSIONED` 插件可能不支持你项目中的原生代码。例如，假设你的项目中有一个 `UNVERSIONED` Facebook 插件，如果 Facebook 原生代码或插件有重大更改，这将破坏你的项目预构建方式并导致构建时出错。
¥For the most *stable* experience, you should try to have no `UNVERSIONED` plugins in your project. This is because the `UNVERSIONED` plugin may not support the native code in your project.
For instance, say you have an `UNVERSIONED` Facebook plugin in your project, if the Facebook native code or plugin has a breaking change, that will break the way your project prebuilds and cause it to error on build.
<a id="static-modification"></a>
## 静态修改
¥Static modification
插件可以使用正则表达式转换应用代码，但如果模板随着时间的推移而发生变化，那么这些修改就会很危险，那么正则表达式将变得难以预测（同样，如果用户手动修改文件或使用自定义模板）。以下是一些不应手动修改的文件示例以及替代方案。
¥Plugins can transform application code with regular expressions, but these modifications are dangerous if the template changes over time then the regex becomes hard to predict (similarly if the user modifies a file manually or uses a custom template). Here are some examples of files you shouldn't modify manually, and alternatives.
<a id="android-gradle-files"></a>
### Android Gradle 文件
¥Android Gradle Files
Gradle 文件是用 Groovy 或 Kotlin 编写的。它们用于管理 Android 应用中的依赖、版本控制和其他设置。不要直接使用 `withProjectBuildGradle`、`withAppBuildGradle` 或 `withSettingsGradle` mods 修改它们，而是使用静态 `gradle.properties` 文件。
¥Gradle files are written in either Groovy or Kotlin. They are used to manage dependencies, versioning, and other settings in the Android app.
Instead of modifying them directly with the `withProjectBuildGradle`, `withAppBuildGradle`, or `withSettingsGradle` mods, utilize the static `gradle.properties` file.
`gradle.properties` 是一个静态键/值对，groovy 文件可以从中读取。例如，假设你想控制 Groovy 中的某些切换：
¥The `gradle.properties` is a static key/value pair that groovy files can read from. For example, say you wanted to control some toggle in Groovy:
```properties gradle.properties
# @info Safely modified using the <code>withGradleProperties()</code> mod. #
expo.react.jsEngine=hermes
# @end #
```
然后在 Gradle 文件中：
¥Then later in a Gradle file:
```groovy app/build.gradle
```
* 对于 `gradle.properties` 中的键，使用驼峰式大小写，以 `.` 分隔，并且通常以 `expo` 前缀开头，表示该属性由预构建管理。
  ¥For keys in the `gradle.properties`, use camel case separated by `.`s, and usually starting with the `expo` prefix to denote that the property is managed by prebuild.
* 要访问该属性，请使用两种全局方法之一：
  ¥To access the property, use one of two global methods:
  * `property`：获取一个属性，如果该属性未定义则抛出错误。
    ¥`property`: Get a property, throw an error if the property is not defined.
  * `findProperty`：如果属性丢失，则获取属性而不引发错误。这通常可以与 `?:` 运算符一起使用来提供默认值。
    ¥`findProperty`: Get a property without throwing an error if the property is missing. This can often be used with the `?:` operator to provide a default value.
一般来说，你应该只通过 Expo [自动链接][autolinking] 与 Gradle 文件交互，这提供了与项目文件的编程接口。
¥Generally, you should only interact with the Gradle file via Expo [Autolinking][autolinking], this provides a programmatic interface with the project files.
<a id="ios-appdelegate"></a>
### iOS 应用代理
¥iOS AppDelegate
某些模块可能需要向项目的 AppDelegate 添加委托方法。这可以通过使用 [AppDelegate 订阅者](/modules/appdelegate-subscribers/) 安全地完成，也可以通过 `withAppDelegate` 模块（强烈不建议）危险地完成。使用 AppDelegate 订阅者允许原生 Expo 模块以安全可靠的方式响应重要事件。
¥Some modules may need to add delegate methods to the project AppDelegate. This can be done safely by using [AppDelegate subscribers](/modules/appdelegate-subscribers/) or dangerously via the `withAppDelegate` mod (*strongly discouraged*).
Using AppDelegate subscribers allows native Expo modules to react to important events in a safe and reliable way.
以下是一些 AppDelegate 订阅者的实际示例。此外，你还可以在 GitHub ([一个这样的例子](https://github.com/bamlab/react-native-app-security/blob/c1a861cbd348f404ec18ffae90d1c9bdc66bc00d/ios/RNASAppLifecyleDelegate.swift)) 的社区代码库中找到许多示例。
¥Below are some examples of the AppDelegate subscribers in action. Additionally, you will find many examples in community repositories on GitHub ([one such example](https://github.com/bamlab/react-native-app-security/blob/c1a861cbd348f404ec18ffae90d1c9bdc66bc00d/ios/RNASAppLifecyleDelegate.swift)).
* `expo-linking`：[**LinkingAppDelegateSubscriber.swift**](https://github.com/expo/expo/blob/b4ca25a4319d7148258ebd5121d1df40a3b1333e/packages/expo-linking/ios/LinkingAppDelegateSubscriber.swift#L14) (openURL)
* `expo-notifications`：[**NotificationsAppDelegateSubscriber.swift**](https://github.com/expo/expo/blob/bd469e421856f348d539b1b57325890147935dbc/packages/expo-notifications/ios/EXNotifications/PushToken/EXPushTokenManager.m) (didRegisterForRemoteNotificationsWithDeviceToken、didFailToRegisterForRemoteNotificationsWithError、didReceiveRemoteNotification)
<a id="ios-cocoapods-podfile"></a>
### iOS CocoaPods Podfile
Podfile 可以使用正则表达式进行自定义（这被认为是危险的，因为这些类型的更改无法很好地组合，并且多个更改可能会发生冲突），但更可靠的方法是在名为 Podfile.properties.json 的 JSON 文件中设置配置值。请参阅下文如何使用 `podfile_properties` 自定义 Podfile：
¥The **Podfile** can be customized with a regular expression (this is considered dangerous because these types of changes do not compose well and multiple changes are likely to collide), but it's more reliable to instead set configuration values in JSON file called **Podfile.properties.json**. See how `podfile_properties` is used to customize the **Podfile** below:
```ruby Podfile
require 'json'
# @info Import a JSON file and parse it in Ruby #
podfile_properties = JSON.parse(File.read(File.join(__dir__, 'Podfile.properties.json'))) rescue {}
# @end #
platform :ios, podfile_properties['ios.deploymentTarget'] || '15.1'
target 'yolo27' do
  use_expo_modules!
  # ...
  # podfile_properties['your_property']
end
```
一般来说，你应该只通过 Expo [自动链接][autolinking] 与 Podfile 交互，这提供了与项目文件的编程接口。
¥Generally, you should only interact with the Podfile via Expo [Autolinking][autolinking], this provides a programmatic interface with the project files.
<a id="custom-base-modifiers"></a>
### 自定义基础修饰符
¥Custom base modifiers
Expo CLI `npx expo prebuild` 命令使用 [`@expo/prebuild-config`][prebuild-config] 来获取默认的基本修饰符。这些默认值仅管理公共文件的子集，如果你想管理自定义文件，你可以通过添加新的基本修饰符在本地执行此操作。
¥The Expo CLI `npx expo prebuild` command uses [`@expo/prebuild-config`][prebuild-config] to get the default base modifiers. These defaults only manage a subset of common files, if you want to manage custom files you can do that locally by adding new base modifiers.
例如，假设你想要添加对管理 `ios/*/AppDelegate.h` 文件的支持，你可以通过添加 `ios.appDelegateHeader` 修饰符来实现。
¥For example, say you wanted to add support for managing the `ios/*/AppDelegate.h` file, you could do this by adding a `ios.appDelegateHeader` modifier.
> 此示例使用 `tsx` 来实现简单的本地 TypeScript 支持，这并不是绝对必要的。[了解更多](/guides/typescript/#appconfigjs)。
>
> ¥This example uses `tsx` for simple local TypeScript support, this isn't strictly necessary. [Learn more](/guides/typescript/#appconfigjs).
```ts withAppDelegateHeaderBaseMod.ts
import { ConfigPlugin, IOSConfig, Mod, withMod, BaseMods } from 'expo/config-plugins';
import fs from 'fs';
/**
 * A plugin which adds new base modifiers to the prebuild config.
 */
export function withAppDelegateHeaderBaseMod(config) {
  return BaseMods.withGeneratedBaseMods<'appDelegateHeader'>(config, {
    platform: 'ios',
    providers: {
      // Append a custom rule to supply AppDelegate header data to mods on `mods.ios.appDelegateHeader`
      appDelegateHeader: BaseMods.provider<IOSConfig.Paths.AppDelegateProjectFile>({
        // Get the local filepath that should be passed to the `read` method.
        getFilePath({ modRequest: { projectRoot } }) {
          const filePath = IOSConfig.Paths.getAppDelegateFilePath(projectRoot);
          // Replace the .m with a .h
          if (filePath.endsWith('.m')) {
            return filePath.substr(0, filePath.lastIndexOf('.')) + '.h';
          }
          // Possibly a Swift project...
          throw new Error(`Could not locate a valid AppDelegate.h at root: "${projectRoot}"`);
        },
        // Read the input file from the filesystem.
        async read(filePath) {
          return IOSConfig.Paths.getFileInfo(filePath);
        },
        // Write the resulting output to the filesystem.
        async write(filePath: string, { modResults: { contents } }) {
          await fs.promises.writeFile(filePath, contents);
        },
      }),
    },
  });
}
/**
 * (Utility) Provides the AppDelegate header file for modification.
 */
export const withAppDelegateHeader: ConfigPlugin<Mod<IOSConfig.Paths.AppDelegateProjectFile>> = (
  config,
  action
) => {
  return withMod(config, {
    platform: 'ios',
    mod: 'appDelegateHeader',
    action,
  });
};
// (Example) Log the contents of the modifier.
export const withSimpleAppDelegateHeaderMod = config => {
  return withAppDelegateHeader(config, config => {
    console.log('modify header:', config.modResults);
    return config;
  });
};
```
要使用这个新的基本模组，请将其添加到插件数组中。基本 mod 必须在使用该 mod 的所有其他插件之后最后添加，这是因为它必须在进程结束时将结果写入磁盘。
¥To use this new base mod, add it to the plugins array. The base mod **MUST** be added last after all other plugins that use the mod, this is because it must write the results to disk at the end of the process.
```js app.config.js
// Required for external files using TS
require('tsx/cjs');
import {
  withAppDelegateHeaderBaseMod,
  withSimpleAppDelegateHeaderMod,
} from './withAppDelegateHeaderBaseMod.ts';
export default ({ config }) => {
  if (!config.plugins) config.plugins = [];
  config.plugins.push(
    withSimpleAppDelegateHeaderMod,
    // Base mods MUST be last
    withAppDelegateHeaderBaseMod
  );
  return config;
};
```
有关详细信息，请参阅 [增加支持的 PR](https://github.com/expo/expo-cli/pull/3852) 了解此功能。
¥For more info, see [the PR that adds support](https://github.com/expo/expo-cli/pull/3852) for this feature.
<a id="expo-install"></a>
## expo 安装
¥expo install
使用 `npx expo install` 命令安装 Node 模块时，如果它包含配置插件，它将自动添加到项目的应用配置中。这使得设置更容易，并有助于防止用户忘记添加插件。但是，这确实有一些注意事项：
¥When a node module is installed with the `npx expo install` command, if it includes a config plugin, it will be added to the project's app config automatically. This makes setup easier and helps prevent users from forgetting to add a plugin. However, this does come with a couple of caveats:
1. `npx expo install` 仅使用根 app.config.js 文件自动将配置插件添加到应用清单中。添加此规则是为了防止将 `lodash` 等流行软件包误认为是配置插件并破坏预构建。
   ¥`npx expo install` only adds config plugins using the root **app.config.js** file automatically to the app manifest. This rule was added to prevent popular packages like `lodash` from being mistaken for a config plugin and breaking the prebuild.
2. 目前没有机制可以检测配置插件是否具有强制属性。因此，`expo install` 只会添加插件，而不会尝试添加任何额外的属性。例如，`expo-camera` 包含可选的额外属性，因此 `plugins: ['expo-camera']` 有效，但如果它包含必需的属性，则 `expo-camera` 会抛出错误。
   ¥There is currently no mechanism for detecting if a config plugin has mandatory props. Because of this, `expo install` will only add the plugin, and not attempt to add any extra props. For example, `expo-camera` has optional extra props, so `plugins: ['expo-camera']` is valid, but if it had mandatory props, then `expo-camera` would throw an error.
3. 仅当用户的项目使用静态应用配置（app.json 和 app.config.json）时，才能自动添加插件。如果用户在带有 app.config.js 的项目中运行 `expo install expo-camera`，他们会看到如下警告：
   ¥Plugins can only be automatically added when the user's project uses a static app config (**app.json** and **app.config.json**). If the user runs `expo install expo-camera` in a project with an **app.config.js**, they'll see a warning like:
```sh
Cannot automatically write to dynamic config at: app.config.js
Please add the following to your app config
{
  "plugins": [
    "expo-camera"
  ]
}
```
[config-docs]: /versions/latest/config/app/
[prebuild-config]: https://github.com/expo/expo-cli/tree/main/packages/prebuild-config#readme
[cli-prebuild]: /more/expo-cli/#prebuild
[source-template]: https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum
[vscode-expo]: https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools
[ems-plugin]: https://github.com/expo/expo/tree/main/packages/expo-module-scripts#-config-plugin
[memfs]: https://www.npmjs.com/package/memfs
[autolinking]: /more/glossary-of-terms/#autolinking


## 使用 patch-project

了解如何使用 patch-project 在 Expo 项目中创建、生成、应用和保存原生更改。

>  **important** 注意：`patch-project` 是一项实验性功能。
>
> ¥**Note**: `patch-project` is an experimental feature.
`patch-package` 是一款 Expo 配置插件和命令行接口 (CLI) 工具，可在运行 `npx expo prebuild` 后生成并应用补丁以保留原生更改。此工具对于希望保留自定义设置而无需了解如何编写配置插件的原生应用开发者非常有用，它可以有效地生成与 [持续的原生生成 (CNG)](/workflow/continuous-native-generation/) 兼容的自动化解决方案。
¥`patch-package` is an Expo config plugin and command-line interface (CLI) tool that generates and applies patches to preserve native changes after running `npx expo prebuild`. This tool is useful for native app developers who want to preserve customizations without needing to know how to write a config plugin, effectively generating an automatic solution that works with [Continuous Native Generation (CNG)](/workflow/continuous-native-generation/).
本指南解释了如何使用 `patch-project`、何时使用它以及它的局限性。
¥This guide explains how to use `patch-project`, when to use it, and its limitations.
<a id="how-patch-project-works"></a>
## patch-project 如何工作
¥How patch-project works
`patch-project` 使用一种受 Git 启发的方法来生成和自动应用补丁。使用此命令行工具需要在你的项目中执行以下步骤：
¥`patch-project` uses an approach to generate and automatically apply patches, which is inspired by Git. Using this command line tool requires the following steps in your project:
<a id="installation"></a>
### 安装
¥Installation
要开始使用，你需要在项目中安装该工具：
¥To get started, you need to install the tool in your project:
```sh
$ npx expo install patch-project
```
此命令会自动将 `patch-project` 配置插件添加到你的 [应用配置](/workflow/configuration/)：
¥This command will automatically add the `patch-project` config plugin to your [app config](/workflow/configuration/):
```json app.json
{
  "expo": {
    "plugins": [
      "patch-project"
    ]
  }
}
```
<a id="generate-patches-from-existing-customizations"></a>
### 从现有自定义项生成补丁
¥Generate patches from existing customizations
假设你手动修改了项目中的原生目录（android 和 ios）。要为这些原生目录生成补丁，你可以运行以下命令：
¥Let's assume you manually modified native directories (**android** and **ios**) in your project. To generate patches for these native directories, you can run the following command:
```sh
$ npx patch-project
```
>  **info** 注意：如果你想要为特定平台生成补丁，可以使用 `--platform` 选项并运行 `npx patch-project --platform android` 或 `npx patch-project --platform ios`。
>
> ¥**Note**: In scenarios where you want to generate patches for a specific platform, you can use the `--platform` option and run `npx patch-project --platform android` or `npx patch-project --platform ios`.
这些补丁生成后会保存在 cng-patches 目录中。
¥These patches, when generated, are saved in the **cng-patches** directory.
每个文件都将以平台名称作为前缀，后跟校验和值。例如：
¥Each file will be prefixed with a platform's name followed by a checksum value. For example:
```bash
ios+eee880ad7b07965271d2323f7057a2b4.patch
```
<a id="apply-patches-during-prebuild"></a>
### 在预构建期间应用补丁
¥Apply patches during prebuild
生成补丁后，它们会在随后运行 `npx expo prebuild` 命令时自动应用。`patch-project` 配置插件可以检测现有补丁并应用它们来恢复你的自定义设置。
¥Once you have generated patches, they are automatically applied when subsequently running the `npx expo prebuild` command. The `patch-project` config plugin detects the existing patches and applies them to restore your customizations.
<a id="when-to-use-patch-project"></a>
## 何时使用 patch-project
¥When to use patch-project
你可以在以下场景中使用 `patch-project`：
¥You can use `patch-project` in the following scenarios:
* 迁移现有的 React Native 应用（由于包含大量原生自定义内容而非常复杂），并将这些原生自定义内容重新创建为配置插件将非常耗时。
  ¥**Migrating existing React Native apps** that are complex because they contain extensive native customizations and re-creating these native customizations as config plugins would be time-consuming.
* 在 Expo 项目中过渡到采用持续原生生成 (CNG) 时，保留对 android 和/或 ios 目录所做的手动更改。
  ¥**Preserving manual changes** made to **android** and/or **ios** directories while transitioning to adopt Continuous Native Generation (CNG) in your Expo project.
* 在编写配置插件之前需要测试原生更改时，可以快速进行原型设计。
  ¥**Quick prototyping** when you need to test native changes before writing config plugins.
* 补丁将在后续运行 `npx expo prebuild` 命令时自动应用。这比 `patch-package`（通常用于为 npm 库生成补丁）等工具更有优势，因为后者不会在预构建过程中保留并自动应用补丁。
  ¥**Patches are applied automatically** when running the `npx expo prebuild` command subsequently. This is an advantage over tools like `patch-package` (commonly used for generating patches for npm libraries), which do not preserve and automatically apply patches during the prebuild process.
<a id="limitations-and-considerations"></a>
## 限制和注意事项
¥Limitations and considerations
补丁在 Expo SDK 版本升级期间可能会失效，原因如下：
¥Patches may become invalid during Expo SDK version upgrades because:
* 模板和/或文件结构更改：预构建模板会随着 SDK 版本的更新而不断演变，包括原生目录中的新变化和文件更新。这将影响 cng-patches 目录中已生成的 diff，这些 diff 可能不再适用。
  ¥**Template and/or file structure changes**: The prebuild template evolves between SDK versions with new changes and file updates in native directories. This will affect the already generated diff in the **cng-patches** directory, which may no longer apply.
* 插件冲突：CNG 补丁可能很危险，当其他插件修改相同的文件时，可能会中断。例如，如果你添加了一个新插件，它会更新 MainApplication.kt 文件，并且与你现有的补丁程序冲突，则补丁程序可能无法正确应用。在这种情况下，你可能需要重新生成补丁。
  ¥**Plugin conflicts**: CNG patches can be dangerous and may break when other plugins modify the same files. For example, if you add a new plugin that updates **MainApplication.kt** and conflicts with your existing patches, the patches may no longer apply correctly. In such cases, you may need to regenerate patches.
* iOS .pbxproj 变更：在 iOS 项目中，将补丁应用于 .pbxproj 文件可能很脆弱，因为该文件包含 UUID，而运行像 `npx expo prebuild --clean` 这样的命令可能会更改这些 ID。例如，如果你添加了一个小部件扩展或进行了其他项目配置更改，基于补丁程序的方法可能无法可靠地工作。你可以查看生成的 cng-patches/ios-* 文件，并仅保留必要的补丁。尽可能减少补丁程序的使用可以降低应用补丁程序时失败的风险。
  ¥**iOS .pbxproj changes**: In iOS projects, applying patches to **.pbxproj** files can be fragile since this file contains UUIDs and running a command like `npx expo prebuild --clean` can change these IDs. For example, if you're adding a widget extension or making other project configuration changes, patch-based approaches may not work reliably. You can review the generated **cng-patches/ios-*** and keep only the necessary patch. Having the patch as minimal as possible would reduce the risk of failures when applying patches.
建议每次 SDK 升级后重新生成补丁。
¥It is recommended to regenerate patches after each SDK upgrade.


# 调试

## 错误和警告

了解 Expo 项目中的 Redbox 错误和堆栈跟踪。

使用 Expo 开发应用时，你会遇到 Redbox 错误或 Yellowbox 警告。这些日志记录经验由 [React Native 中的日志框](https://rn.nodejs.cn/blog/2020/07/06/version-0.63) 提供。
¥When developing an application using Expo, you'll encounter a **Redbox** error or **Yellowbox** warning. These logging experiences are provided by [LogBox in React Native](https://rn.nodejs.cn/blog/2020/07/06/version-0.63).
<a id="redbox-error-and-yellowbox-warning"></a>
## 红盒错误和黄盒警告
¥Redbox error and Yellowbox warning
当致命错误阻止你的应用运行时，会显示 Redbox 错误。将显示黄框警告，通知你可能存在问题，你应该在发布应用之前解决它。
¥A Redbox error is displayed when a fatal error prevents your app from running. A Yellowbox warning is displayed to inform you that there is a possible issue and you should probably resolve it before shipping your app.
你还可以使用 `console.warn("Warning message")` 和 `console.error("Error message")` 自行创建警告和错误。触发红框的另一种方法是抛出错误而不捕获它：`throw Error("Error message")`。
¥You can also create warnings and errors on your own with `console.warn("Warning message")` and `console.error("Error message")`. Another way to trigger the redbox is to throw an error and not catch it: `throw Error("Error message")`.
> 这是使用 Expo CLI 调试 React Native 应用的简要介绍。有关详细信息，请参阅 [调试](/debugging/runtime-issues/)。
>
> ¥This is a brief introduction to debugging a React Native app with Expo CLI. For in-depth information, see [Debugging](/debugging/runtime-issues/).
<a id="stack-traces"></a>
## 堆栈跟踪
¥Stack traces
当你在开发过程中遇到错误时，你将看到错误消息和堆栈跟踪，这是应用崩溃时最近进行的调用的报告。此堆栈跟踪会显示在你的终端和 Expo Go 应用中，或者如果你创建了开发版本。
¥When you encounter an error during development, you'll see the error message and a **stack trace**, which is a report of the recent calls your application made when it crashed. This stack trace is shown both in your terminal and the Expo Go app or if you have created a development build.
该堆栈跟踪非常有价值，因为它为你提供了错误发生的位置。例如，在下图中，错误来自文件 HomeScreen.js，并由该文件的第 7 行引起。
¥This stack trace is **extremely valuable** since it gives you the location of the error's occurrence. For example, in the following image, the error comes from the file **HomeScreen.js** and is caused on line 7 in that file.
当你查看该文件的第 7 行时，你将看到引用了一个名为 `renderDescription` 的变量。错误消息描述未找到该变量，因为该变量未在 HomeScreen.js 中声明。这是一个典型的例子，说明如果你花时间解读错误消息和堆栈跟踪，它们会有多大帮助。
¥When you look at that file, on line 7, you will see that a variable called `renderDescription` is referenced. The error message describes that the variable is not found because the variable is not declared in **HomeScreen.js**. This is a typical example of how helpful error messages and stack traces can be if you take the time to decipher them.
调试错误是开发中最令人沮丧但又令人满意的部分之一。请记住，你永远不会孤单。Expo 社区以及 React 和 React Native 社区是你遇到困难时提供帮助的重要资源。其他人很可能也遇到了与你相同的错误。请务必阅读文档，搜索 [forums](https://chat.expo.dev/)、[GitHub 问题](https://github.com/expo/expo/issues/) 和 [Stack Overflow](https://stackoverflow.com/)。
¥Debugging errors is one of the most frustrating but satisfying parts of development. Remember that you're never alone. The **Expo community** and the React and React Native communities are great resources for help when you get stuck. There's a good chance someone else has run into your exact error. Make sure to read the documentation, search the [forums](https://chat.expo.dev/), [GitHub issues](https://github.com/expo/expo/issues/), and [Stack Overflow](https://stackoverflow.com/).


## 调试运行时问题

了解可用于调试 Expo 项目的不同技术。

无论你是在本地开发应用、将其发送给选定的 Beta 测试人员，还是将应用实时发布到应用商店，你总会发现自己在调试问题。将错误分为两类很有用：
¥Whether you're developing your app locally, sending it out to select beta testers, or launching your app live to the app stores, you'll always find yourself debugging issues. It's useful to split errors into two categories:
* 开发中遇到的错误
  ¥Errors you encounter in the development
* 你（或你的用户）在生产中遇到的错误
  ¥Errors you (or your users) encounter in production
让我们来看看处理上述每种情况时的推荐做法。
¥Let's go through recommended practices when dealing with each of the above situations.
<a id="development-errors"></a>
## 开发错误
¥Development errors
它们是你在开发应用时遇到的常见错误。深入研究它们并不总是那么简单。通常，在使用 [Expo CLI](/more/expo-cli/) 运行应用时进行调试就足够了。
¥They are common errors that you encounter while developing your app. Delving into them isn't always straightforward. Usually, debugging when running your app with [Expo CLI](/more/expo-cli/) is enough.
调试这些问题的一种方法是查看 [堆栈跟踪](/debugging/errors-and-warnings/#stack-traces)。但是，在某些情况下，仅查看堆栈跟踪还不够，因为跟踪的错误消息可能更加神秘。对于此类错误，请按照以下步骤操作：
¥One way you can debug these issues is by looking at the [stack trace](/debugging/errors-and-warnings/#stack-traces). However, in some scenarios, looking at the stack trace isn't enough as the error message traced might be a little more cryptic. For such errors, follow the steps below:
* 在 Google 和 [Stack Overflow](https://stackoverflow.com/questions) 中搜索错误消息，你可能不是第一个遇到此问题的人。
  ¥Search for the error message in Google and [Stack Overflow](https://stackoverflow.com/questions), it's likely you're not the first person to ever run into this.
* 隔离引发错误的代码。此步骤对于修复模糊错误至关重要。去做这个：
  ¥**Isolate the code that's throwing the error**. This step is *vital* in fixing obscure errors. To do this:
  * 恢复到代码的工作版本。这甚至可能是一个完全空白的 `npx create-expo-app` 项目。
    ¥Revert to a working version of your code. This may even be a completely blank `npx create-expo-app` project.
  * 一点一点地应用你最近的更改，直到它崩溃。
    ¥Apply your recent changes piece by piece, until it breaks.
  * 如果你在每个 "piece" 中添加的代码很复杂，你可能希望简化你正在做的事情。例如，如果你使用 Redux 等状态管理库，你可以尝试将其从等式中完全删除，以查看问题是否出在你的状态管理中（这在 React 应用中很常见）。
    ¥If the code you're adding in each "piece" is complex, you may want to simplify what you're doing. For example, if you use a state management library such as Redux, you can try removing that from the equation completely to see if the issue lies in your state management (which is common in React apps).
  * 这应该可以缩小错误的可能来源，并为你提供更多信息，以便你在互联网上搜索遇到相同问题的其他人。
    ¥This should narrow down the possible sources of the error, and provide you with more information to search the internet for others who have had the same problem.
* 使用断点（或 `console.log`）来检查并确保特定代码正在运行，或者变量具有特定值。使用 `console.log` 进行调试并不被认为是最佳实践，但是，它快速、简单，并且常常提供一些有启发性的信息。
  ¥Use breakpoints (or `console.log`s) to check and make sure a certain piece of code is being run, or that a variable has a certain value. Using `console.log` for debugging isn't considered the best practice, however, it's fast, easy, and oftentimes provides some illuminating information.
尽可能简化代码以追踪错误源是调试应用的好方法，并且它会变得更加容易。这就是为什么许多开源存储库在你提出问题时需要 [最小可重复示例](https://stackoverflow.com/help/minimal-reproducible-example)。它可确保你隔离问题并准确识别问题发生的位置。如果你的应用太大且太复杂，无法执行此操作，请尝试提取你要在空白 `npx create-expo-app` 项目中添加的功能，然后从那里开始。
¥Simplifying code as much as possible to track down the source of error is a great way to debug your app and it gets exponentially easier. That's why many open-source repositories require a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) when you open an issue. It ensures you have isolated the issue and identified exactly where the problem occurs. If your app is too large and complex to do that, try and extract the functionality you're trying to add in a blank `npx create-expo-app` project, and go from there.
<a id="native-debugging"></a>
### 原生调试
¥Native debugging
你可以通过在本地生成源代码并从该源构建来使用 Android Studio 和 Xcode 执行完整的原生调试。
¥You can perform full native debugging with Android Studio and Xcode by generating source code locally and building from that source.
<a id="android-studio"></a>
#### 安卓工作室
¥Android Studio
Step 1: 
Generate the native code for your project by running the following command:
```sh
$ npx expo prebuild -p android
```
This will add an **android** directory at the root of your project.
Step 2: 
Open the project in Android Studio by running the command:
```sh
$ open -a "/Applications/Android Studio.app" ./android
```
Step 3: 
Build the app from Android Studio and connect the debugger. See [Google's documentation](https://developer.android.com/studio/debug#startdebug) for more information.
> You can delete the **android** directory when you are done with this process. This ensures that your project remains managed by Expo CLI. Keeping the directory around and manually modifying it outside of `npx expo prebuild` means you'll need to manually upgrade and configure native libraries yourself.
#### Xcode
> This is only available for macOS users and requires Xcode to be installed.
Step 1: 
Generate the native code for your project by running the following command:
```sh
$ npx expo prebuild -p ios
```
This will add an **ios** directory at the root of your project.
Step 2: 
Open the project in Xcode by running the command which is a shortcut to open the `.xcworkspace` file from your project's **ios** directory in Xcode.
```sh
$ xed ios
```
Step 3: 
Build the app with <kbd>Cmd ⌘</kbd> + <kbd>r</kbd> or by pressing the play button in the upper left corner of Xcode.
Step 4: 
You can now utilize [**Low-level debugger (LLDB)**](https://developer.apple.com/library/archive/documentation/IDEs/Conceptual/gdb_to_lldb_transition_guide/document/Introduction.html) and all of the other [Xcode debugging tools](https://developer.apple.com/documentation/metal/debugging_tools) to examine the native runtime.
> You can delete the **ios** directory when you are done with this process. This ensures that your project remains managed by Expo CLI. Keeping the directory around and manually modifying it outside of `npx expo prebuild` means you'll need to manually upgrade and configure native libraries yourself.
## Production errors
Errors or bugs in your production app can be much harder to solve, mainly because you have less context around the error (that is, where, how, and why did the error occur?).
**The best first step in addressing a production error is to reproduce it locally.** Once you reproduce an error locally, you can follow the [development debugging process](#development-errors) to isolate and address the root cause.
> **info** **Tip**: Sometimes, running your app in **production mode** locally will show errors that normally wouldn't be thrown. You can run the app locally in production by running `npx expo start --no-dev --minify`.
> `--no-dev` tells the server not to be run in development mode, and `--minify` is used to minify your code the same way it is for production JavaScript bundles.
### Production app is crashing
It can be a frustrating scenario when a production app crashes. There is very little information to look into when it happens. It's important to reproduce the issue, and even if you can't do that, to find any related crash reports.
Start by reproducing the crash using your production app and then **find an associated crash report**. For Android, you can use `adb logcat` and for iOS you can use the Console app in Xcode.
Video Tutorial: [How to use Logcat & macOS Console to debug](https://www.youtube.com/watch?v=LvCci4Bwmpc)
#### Crash reports using adb logcat
If your Android app is on Google Play, refer to the crashes section of the [Google Play Console](https://play.google.com/console/about/), or connect your Android device to your computer and run the following command:
```sh
$ adb logcat
```
The Android Debug Bridge (`adb`) program is part of the Android SDK and allows you to view streaming logs. An alternative to avoid installing Android SDK is to use [WebADB](https://webadb.com/) in Chrome.
#### Crash reports using Console app
If your iOS app is on TestFlight or the App Store, you can use the [Crashes Organizer](https://developer.apple.com/news/?id=nra79npr) in Xcode.
If not, you can use the **Console** app in Xcode by connecting your device to your Mac. Follow the steps below on how to access the Console app:
Step 1: 
Open Xcode app, and then open **Devices and Simulators** window by pressing <kbd>Shift</kbd> + <kbd>Cmd ⌘</kbd> + <kbd>2</kbd>.
Step 2: 
If you have connected a physical device, select it under **Devices**. Otherwise, if you are using a simulator, select it under **Simulators**.
Step 3: 
Click on **Open Console** button shown in the window to open the console app.
This will open the console app for you to view logs from your device or simulator.
有关更多信息，请参阅 Apple 的 [使用崩溃报告和设备日志诊断问题](https://developer.apple.com/documentation/xcode/diagnosing-issues-using-crash-reports-and-device-logs) 指南。
¥For more information, see Apple's [Diagnosing Issues Using Crash Reports and Device Logs](https://developer.apple.com/documentation/xcode/diagnosing-issues-using-crash-reports-and-device-logs) guide.
<a id="app-crashes-on-certain-older-devices"></a>
### 应用在某些（较旧）设备上崩溃
¥App crashes on certain (older) devices
这可能表明存在性能问题。你可能需要通过分析器运行你的应用，以更好地了解哪些进程正在终止应用，以及 [React Native 为此提供了一些很棒的文档](https://rn.nodejs.cn/docs/profiling)。我们还建议使用 [React Native DevTools](/debugging/tools/#debugging-with-react-native-devtools) 和内置的 [profiler](/debugging/tools/#profiling-javascript-performance)，这样可以非常轻松地识别应用中的 JavaScript 性能瓶颈。
¥This might indicate that there is a performance issue. You likely need to run your app through a profiler to get a better idea of what processes are killing the app, and [React Native provides some great documentation for this](https://rn.nodejs.cn/docs/profiling). We also recommend using [React Native DevTools](/debugging/tools/#debugging-with-react-native-devtools) and the included [profiler](/debugging/tools/#profiling-javascript-performance), which makes it super easy to identify JavaScript performance sinks in your app.
<a id="using-error-reporting-services"></a>
### 使用错误报告服务
¥Using error reporting services
在生产应用中实现崩溃和错误报告服务有几个好处，例如：
¥Implementing a crash and bug reporting service in your production app offers several benefits, such as:
* 实时洞察生产部署，并提供重现崩溃和错误的信息。
  ¥Real-time insights on production deployments with information to reproduce crashes and bugs.
* 设置警报系统以获取有关致命 JavaScript 错误或你配置的任何其他事件的通知。
  ¥Setting up an alert system to get notified about fatal JavaScript errors or any other event you configure.
* 使用 Web 仪表板查看异常的详细信息，例如堆栈跟踪、设备信息等。
  ¥Using a web dashboard to see details on exceptions such as stack traces, device information, and so on.
使用 Expo，你可以集成 [Sentry](/guides/using-sentry/) 或 [BugSnag](/guides/using-bugsnag/) 等报告服务，以实时获得更多见解。
¥With Expo, you can integrate a reporting service like [Sentry](/guides/using-sentry/) or [BugSnag](/guides/using-bugsnag/) to get more insights in real-time.
<a id="stuck"></a>
## 卡住？
¥Stuck?
Expo 社区以及 React 和 React Native 社区是你遇到困难时提供帮助的重要资源。其他人很可能遇到了与你相同的错误，因此请务必阅读文档，搜索 [forums](https://chat.expo.dev/)、[GitHub 问题](https://github.com/expo/expo/issues/) 和 [Stack Overflow](https://stackoverflow.com/)。
¥The Expo community and the React and React Native communities are great resources for help when you get stuck. There's a good chance someone else has run into the same error as you, so make sure to read the documentation, search the [forums](https://chat.expo.dev/), [GitHub issues](https://github.com/expo/expo/issues/), and [Stack Overflow](https://stackoverflow.com/).


## 调试和分析工具

了解可用于在运行时检查你的 Expo 项目的不同工具。

React Native 由 JavaScript 和原生代码组成。在调试时做出这种区分非常重要。如果 JavaScript 代码抛出错误，你可能无法使用原生代码的调试工具找到它。本页列出了一些可帮助你调试 Expo 项目的工具。
¥React Native consists of both JavaScript and native code. Making this distinction is very important when it comes to debugging. If an error is thrown from the JavaScript code, you might not find it using debugging tools for native code. This page lists a few tools to help you debug your Expo project.
<a id="developer-menu"></a>
## 开发者菜单
¥Developer menu
Developer 菜单提供对有用调试功能的访问。它内置于开发客户端和 Expo Go 中。如果你使用的是模拟器、模拟器或通过 USB 连接的设备，则可以在 Expo CLI 启动开发服务器的终端中按 <kbd>m</kbd> 打开此菜单。
¥The **Developer menu** provides access to useful debugging functions. It is built into dev clients and Expo Go. If you are using an emulator, simulator, or have a device connected via USB, you can open this menu by pressing <kbd>m</kbd> in the terminal where Expo CLI has started the development server.
Note: Alternative options to open the Developer menu
---
- Android device (without USB): Shake the device vertically.
- Android Emulator or device (with USB):
  - Press <kbd>Cmd ⌘</kbd> + <kbd>m</kbd> or <kbd>Ctrl</kbd> + <kbd>m</kbd>.
  - Run the following command in the terminal to simulate pressing the menu button:
    ```sh
$ adb shell input keyevent 82
```
- iOS device (without USB):
  - Shake the device.
  - Touch three fingers to the screen.
- iOS Simulator or device (with USB):
  - Press <kbd>Ctrl</kbd> + <kbd>Cmd ⌘</kbd> + <kbd>z</kbd> or <kbd>Cmd ⌘</kbd> + <kbd>d</kbd>
---
Once the Developer menu is open, it will appear as below:
The Developer menu provides the following options:
- **Copy link**: To copy the dev server address in dev client or [`exp://`](/linking/into-your-app/#test-a-link-using-expo-go) link in Expo of your app.
- **Reload**: To reload you app. Usually, not necessary since Fast Refresh is enabled by default.
- **Go Home**: To leave your app and navigate back to the dev client's or Expo Go app's Home screen.
- **Toggle performance monitor**: To view the performance information about your app.
- **Toggle element inspector**: To enable or disable the element inspector overlay.
- **Open JS debugger**: To open React Native DevTools which provides access to Console, Sources, Network (**Expo only**), Memory, Components, and Profiler, tabs for apps using Hermes. For more information, see the [Debugging with React Native DevTools](#debugging-with-react-native-devtools) section.
- **Fast Refresh**: To toggle automatic refreshing of the JS bundle whenever you make changes to files in your project using a text editor.
Now, let's explore some of these options in details.
### Toggle performance monitor
Opens up a small overlay that provides the following performance information about your app:
- RAM usage of a project.
- JavaScript heap (this is an easy way to know of any memory leaks in your application).
- Two Views. The top indicates the number of views for the screen and the bottom indicates the number of views in the component.
- Frames Per Second for the UI and JS threads. The UI thread is used for native Android or iOS UI rendering. The JS thread is where most of your logic runs, including API calls, touch events, and so on.
### Toggle element inspector
Opens up the element inspector overlay:
This overlay has capabilities to:
- Inspect: Inspect elements
- Perf: Show Performance overlay
- Network: Show network details
- Touchables: Highlight touchable elements
## Debugging with React Native DevTools
> **info** **Starting from React Native 0.76**, React Native DevTools has replaced Chrome DevTools.
**React Native DevTools** is a modern debugging tool for Expo and React Native apps. It allows you to gain insights into the JavaScript code of your app by accessing the [Console](#interacting-with-the-console), [Sources](#pausing-on-breakpoints), [Network](#inspecting-network-requests) (**Expo only**), and [Memory](#insepcting-memory) tabs. It also has **built-in support for React DevTools** such as [Components](#inspecting-components) and [Profiler](#profiling-javascript-performance) tabs. All of these inspectors can be accessed using [dev clients](/more/glossary-of-terms/#dev-clients) or Expo Go.
You can use the React Native DevTools on any app using [Hermes](/guides/using-hermes/). **To open it, start your app and press <kbd>j</kbd> in the terminal where Expo was started**. Once you have opened the React Native DevTools, it will appear as below:
### Pausing on breakpoints
You can pause your app on specific parts of your code. To do this, set the breakpoint under the Sources tab by clicking the line number or add the `debugger` statement in your code.
Once your app is executing code that has a breakpoint, it will entirely pause your app. This allows you to inspect all variables and functions in that scope. You can also execute code in the [Console](#interacting-with-the-console) tab as part of your app.
### Pausing on exceptions
If your app throws unexpected errors, it can be hard to find the source of the error. You can use React Native DevTools to pause your app and inspect the stack trace and variables the moment it throws an error.
> **info** Some errors might be caught by other components in your app, such as Expo Router. In these cases, you can turn on **Pause on caught exceptions**. It will enable you to inspect any thrown error, even when handled properly.
### Interacting with the console
The **Console** tab gives you access to an interactive terminal, connected directly to your app. You can write any JavaScript inside this terminal to execute snippets of code as if it were part of your app. The code is executed in the global scope by default. But, when using breakpoints from the [Sources](#pausing-on-breakpoints) tab, it executes in the scope of the reached breakpoint. This allows you to invoke methods and access variables throughout your app.
### Inspecting network requests (Expo only)
> **info** The Network tab in React Native DevTools is only available when you have `expo` installed in your project.
The **Network** tab gives you insights into the network requests made by your app. You can inspect each request and response by clicking on them. This includes `fetch` requests, external loaded media, and in some cases, even requests made by native modules.
> **info** See the [Inspecting network traffic](#inspecting-network-traffic) for alternative ways to inspect network requests.
### Inspecting memory
The **Memory** tab allows you to inspect the memory usage and take a heap snapshot of your app's JavaScript code.
### Inspecting components
The **Components** tab allows you to inspect the React components in your app. You can view the props, and styles of each component by hovering that component in React Native DevTools. This is a great way to debug your app's UI and understand how your components are structured.
### Profiling JavaScript performance
> **warning** Profiles are not yet symbolicated with sourcemaps, and [can only be used in debug builds](https://github.com/facebook/hermes/issues/760). These limitations will be addressed in upcoming releases.
The **Profiler** tab allows you to record and analyze the performance of your app's JavaScript. You can start recording, interact with your app, and stop recording to analyze the profile.
> **info** To profile the native runtime, use the tools included in Android Studio or Xcode.
## Debugging with VS Code
> **warning** VS Code debugger integration is experimental. For the most stable debugging experience, [use the React Native DevTools](#debugging-with-react-native-devtools).
VS Code is a popular code editor, which has a built-in debugger. This debugger uses the same system as the React Native DevTools &mdash; the inspector protocol.
You can use this debugger with the [Expo Tools](https://github.com/expo/vscode-expo#readme) VS Code extension. This debugger allows you to set breakpoints, inspect variables, and execute code through the debug console.
To start debugging:
- Connect your app
- Open VS Code command palette (based on your computer, it's either <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> or <kbd>Cmd ⌘</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd>)
- Run the **Expo: Debug ...** VS Code command.
This will attach VS Code to your running app.
Alternatively, if you want a fully-featured IDE setup in VS Code, you might want to check out the [Radon IDE](https://ide.swmansion.com/) extension (paid with a 30-day free trial). It turns your editor into a powerful environment designed specifically for React Native and Expo projects, with advanced debugging, a network inspector, router integration, and other built-in tools.
## React Native Debugger
> **warning** The React Native Debugger requires Remote JS debugging, which has been deprecated since [React Native 0.73](https://rn.nodejs.cn/docs/other-debugging-methods#remote-javascript-debugging-deprecated).
The React Native Debugger is a standalone app that wraps the React DevTools, Redux DevTools, and React Native DevTools. Unfortunately, it requires the [deprecated Remote JS debugging workflow](https://github.com/jhen0409/react-native-debugger/discussions/774) and is incompatible with Hermes.
If you are using Expo **SDK 50** or **above**, you can use the [Expo dev tools plugins](/debugging/devtools-plugins) equivalents to the React Native Debugger:
- [React Native DevTools](#debugging-with-react-native-devtools)
- [Redux DevTools](/debugging/devtools-plugins/#redux)
If you are using Expo SDK 49 or below, you can use the React Native Debugger. This section provides quick get started instructions. For in-depth information, check its [documentation](https://github.com/jhen0409/react-native-debugger#documentation).
You can install it via the [release page](https://github.com/jhen0409/react-native-debugger/releases), or if you're on macOS you can run:
```sh
$ brew install react-native-debugger
```
### Startup
After firing up React Native Debugger, you'll need to specify the port (shortcuts: <kbd>Cmd ⌘</kbd> + <kbd>t</kbd> on macOS, <kbd>Ctrl</kbd> + <kbd>t</kbd> on Linux/Windows) to `8081`. After that, run your project with `npx expo start`, and select `Debug remote JS` from the Developer Menu. The debugger should automatically connect.
In the debugger console, you can see the Element tree, as well as the props, state, and children of whatever element you select. You also have the Chrome console on the right, and if you type `$r` in the console, you will see the breakdown of your selected element.
If you right-click anywhere in the React Native Debugger, you'll get some handy shortcuts to reload your JS, enable/disable the element inspector, network inspector, and to log and clear your `AsyncStorage` content.
<a id="inspecting-network-traffic"></a>
### 检查网络流量
¥Inspecting network traffic
使用 React Native 调试器来调试网络请求很容易：右键单击 React Native 调试器中的任意位置并选择 `Enable Network Inspect`。这将启用“网络”选项卡并允许你检查 `fetch` 和 `XMLHttpRequest` 的请求。
¥It's easy to use the React Native Debugger to debug your network request: right-click anywhere in the React Native Debugger and select `Enable Network Inspect`. This will enable the Network tab and allow you to inspect requests of `fetch` and `XMLHttpRequest`.
然而有 [一些限制](https://github.com/jhen0409/react-native-debugger/blob/master/docs/network-inspect-of-chrome-devtools.md#limitations)，所以还有一些其他替代方案，所有这些都需要使用代理：
¥There are however [some limitations](https://github.com/jhen0409/react-native-debugger/blob/master/docs/network-inspect-of-chrome-devtools.md#limitations), so there are a few other alternatives, all of which require using a proxy:
* [Charles 代理](https://www.charlesproxy.com/documentation/configuration/browser-and-system-configuration/)（~50 美元，我们的首选工具）
  ¥[Charles Proxy](https://www.charlesproxy.com/documentation/configuration/browser-and-system-configuration/) (~$50 USD, our preferred tool)
* [代理人](https://proxyman.io)（提供免费版本或 49 至 59 美元）
  ¥[Proxyman](https://proxyman.io) (Free version available or $49 to $59 USD)
* [mitmproxy](https://medium.com/@rotxed/how-to-debug-http-s-traffic-on-android-7fbe5d2a34#.hnhanhyoz)
* [提琴手](http://www.telerik.com/fiddler)
  ¥[Fiddler](http://www.telerik.com/fiddler)
<a id="debugging-production-apps"></a>
## 调试生产应用
¥Debugging production apps
实际上，应用经常附带错误。实现崩溃和错误报告系统可以帮助你实时了解生产应用。详细信息请参见 [使用错误报告服务](/debugging/runtime-issues/#using-error-reporting-services)。
¥In reality, apps often ship with bugs. Implementing a crash and bug reporting system can help you get real-time insights of your production apps. See [Using error reporting services](/debugging/runtime-issues/#using-error-reporting-services) for more details.


## 开发工具插件

了解如何使用开发工具插件来检查和调试你的 Expo 项目。

你的本地开发环境中提供了开发工具插件，可帮助你调试应用。它们由你添加到项目中的少量代码组成，这些代码支持应用和外部 Chrome 窗口之间的双向通信。此设置提供显示工具来检查应用、触发某些测试行为等。
¥Dev tools plugins are available in your local development environment to help you debug your app. They consist of a small amount of code you add to a project that enables two-way communication between the app and an external Chrome window. This setup provides display tools to inspect the app, trigger certain behaviors for testing, and more.
开发工具插件类似于可在开发版本和 Expo Go 中使用的 Flipper 插件，并且不需要向项目添加原生模块或配置插件。
¥Dev tools plugins are similar to Flipper plugins that are available in Development builds and Expo Go, and do not require adding native modules or config plugins to your project.
<a id="add-a-dev-tools-plugin-to-a-project"></a>
## 将开发工具插件添加到项目中
¥Add a dev tools plugin to a project
要将开发工具插件添加到你的应用，请将其作为包安装并添加一个小片段以将代码连接到你的应用。此代码从应用的根组件调用，以在应用和插件之间建立双向通信。然后，该插件可以在应用在开发模式下运行的整个过程中检查应用的各个方面。
¥To add a dev tool plugin to your app, install it as a package and add a small snippet to connect the code to your app. This code is invoked from the app's root component to establish a two-way communication between your app and the plugin. Then, the plugin can inspect aspects of your app for the entire time your app runs in development mode.
所有 [Expo 开发工具插件](#expo-dev-tools-plugins) 和使用 [我们的创作工具](/debugging/create-devtools-plugins) 创建的插件都会导出一个钩子，你可以使用该钩子将插件连接到你的应用。当应用未在开发模式下运行时，钩子及其返回的任何函数都将无操作。
¥All [Expo dev tools plugins](#expo-dev-tools-plugins) and plugins created with [our creation tool](/debugging/create-devtools-plugins) export a hook that you can use to connect the plugin to your app. The hook and any functions returned from it will no-op when the app is not running in development mode.
某些插件钩子需要与插件如何检查你的应用相关的参数。例如，用于检查 React Navigation 状态的插件可能需要引用导航根。
¥Some plugin hooks require parameters that relate to how the plugin inspects your app. For instance, a plugin for inspecting the React Navigation state might require a reference to the navigation root.
要开始使用该插件，请使用应用根组件中的钩子：
¥To start using the plugin, use the hook in your app's root component:
```jsx App.js
import { useMyDevToolsPlugin } from 'my-devtools-plugin';
export default App() {
  useMyDevToolsPlugin();
  return (/* rest of your app */)
}
```
在某些情况下，你可能需要直接与插件交互。所有插件都通过 `expo/devtools` 的导出进行通信，你可以通过 `useDevToolsPluginClient` 发送和收听消息。请务必将与插件的 Web 用户界面使用的插件名称相同的插件名称传递给 `useDevToolsPluginClient`：
¥In some cases, you may need to interact with a plugin directly. All plugins communicate through exports from `expo/devtools`, and you can send and listen to messages through `useDevToolsPluginClient`. Be sure to pass the same plugin name to `useDevToolsPluginClient` as is used by the plugin's web user interface:
```jsx App.js
import { useDevToolsPluginClient } from 'expo/devtools';
export default App() {
  const client = useDevToolsPluginClient('my-devtools-plugin');
   useEffect(() => {
    // receive messages
    client?.addMessageListener("ping", (data) => {
      alert(`Received ping from ${data.from}`);
    });
    // send messages
    client?.sendMessage("ping", { from: "app" });
   }, []);
  return (/* rest of your app */)
}
```
<a id="compatibility-with-expo-go-and-development-builds"></a>
### 与 Expo Go 和 Development 版本的兼容性
¥Compatibility with Expo Go and Development builds
开发工具插件应该只包含 JavaScript 代码。它们通常与 Expo Go 和 [开发构建](/develop/development-builds/introduction/) 兼容，并且不需要创建新的开发版本来添加插件。如果插件检查的包的底层模块包含原生代码并且不是 Expo Go 的一部分，请创建一个新的开发版本以使用该包中的组件和插件。
¥Dev tools plugins should only include JavaScript code. They are generally compatible with Expo Go and [Development builds](/develop/development-builds/introduction/) and should not require creating a new development build to add the plugin. If a package's underlying module that the plugin inspects includes native code and is not part of Expo Go, create a new development build to use both the component and the plugin from that package.
例如，检查 [React Native Firebase](/guides/using-firebase/#using-react-native-firebase) 的开发工具插件将无法与 Expo Go 一起使用。React Native Firebase 包含不属于 Expo Go 的原生代码。要使用开发工具插件和 React Native Firebase，请创建开发版本。
¥For example, a dev tools plugin that inspects [React Native Firebase](/guides/using-firebase/#using-react-native-firebase) will not work with Expo Go. React Native Firebase includes native code that is not part of Expo Go. To use the dev tools plugin and React Native Firebase, create a development build.
<a id="using-a-dev-tools-plugin"></a>
## 使用开发工具插件
¥Using a dev tools plugin
安装开发工具插件并将连接所需的代码添加到你的项目后，你可以使用 `npx expo start` 启动开发服务器。然后按 <kbd>shift</kbd> + <kbd>m</kbd> 打开可用开发工具插件列表。选择你要使用的插件，它将在新的 Chrome 窗口中打开。
¥After installing the dev tools plugin and adding the connecting required code to your project, you can start the dev server up with `npx expo start`. Then press <kbd>shift</kbd> + <kbd>m</kbd> to open the list of available dev tools plugins. Select the plugin you want to use, and it will open in a new Chrome window.
> 使用 Expo CLI 启动开发服务器时，可以选择按 <kbd>?</kbd> 显示所有命令。这显示了其他命令，包括打开更多工具的快捷方式。还可以在此菜单中选择开发工具插件。
>
> ¥When starting the dev server with the Expo CLI, there is an option to press <kbd>?</kbd> to **show all commands**. This shows additional commands, including the shortcut to open **more tools**. Dev tools plugins can also be selected in this menu.
<a id="expo-dev-tools-plugins"></a>
## Expo 开发工具插件
¥Expo dev tools plugins
Expo 提供了一些用于常见调试任务的开发工具插件。请按照以下说明开始在你的应用中使用它们。
¥Expo provides some dev tools plugins for common debugging tasks. Follow the instructions below to start using them in your app.
> 注意：以下每个开发工具插件钩子只会在开发模式下启用插件。它不会影响你的生产包。
>
> ¥**Note**: Each of the following dev tools plugin hooks will only enable the plugin in development mode. It doesn't affect your production bundle.
<a id="react-navigation"></a>
### React 导航
¥React Navigation
受 [`@react-navigation/devtools`](https://github.com/react-navigation/react-navigation/tree/main/packages/devtools) 的启发，React Navigation 开发工具插件允许查看 [React 导航](https://react-navigation.nodejs.cn/) 操作和状态的历史记录。你还可以倒回到导航历史记录中的先前点，并将深层链接发送到你的应用。由于 Expo Router 是基于 React Navigation 构建的，因此该插件与 [Expo 路由](/router/introduction) 完全兼容。
¥Inspired by [`@react-navigation/devtools`](https://github.com/react-navigation/react-navigation/tree/main/packages/devtools), the React Navigation dev tools plugin allows seeing the history of [React Navigation](https://react-navigation.nodejs.cn/) actions and state. You can also rewind to previous points in your navigation history and send deep links to your app. Since Expo Router is built upon React Navigation, this plugin is fully compatible with [Expo Router](/router/introduction).
要使用该插件，请首先安装该软件包：
¥To use the plugin, start by installing the package:
```sh
$ npx expo install @dev-plugins/react-navigation
```
将导航根传递给应用入口点中的插件：
¥Pass the navigation root to the plugin in your app's entry point:
```jsx app/_layout.js
import { useEffect, useRef } from 'react';
import { useNavigationContainerRef, Slot } from 'expo-router';
import { useReactNavigationDevTools } from '@dev-plugins/react-navigation';
export default Layout() {
  const navigationRef = useNavigationContainerRef();
  useReactNavigationDevTools(navigationRef);
  return <Slot />;
}
```
```jsx App.js
import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
import { useReactNavigationDevTools } from '@dev-plugins/react-navigation';
export default function App() {
  const navigationRef = useNavigationContainerRef();
  useReactNavigationDevTools(navigationRef);
return (
    <NavigationContainer ref={navigationRef}>{/* ... */}</NavigationContainer>
  );
}
```
在终端中，运行 `npx expo start`，按 <kbd>shift</kbd> + <kbd>m</kbd> 打开开发工具列表，然后选择 React Navigation 插件。这将打开插件的网络界面，在你浏览应用时显示你的导航历史记录。
¥In the terminal, run `npx expo start`, press <kbd>shift</kbd> + <kbd>m</kbd> to open the list of dev tools, and then select the React Navigation plugin. This will open the plugin's web interface, showing your navigation history as you navigate through your app.
<a id="apollo-client"></a>
### Apollo 客户端
¥Apollo Client
受 [`react-native-apollo-devtools`](https://github.com/razorpay/react-native-apollo-devtools) 的启发，Apollo Client 开发工具插件允许检查 Apollo Client 的缓存、查询和修改。
¥Inspired by [`react-native-apollo-devtools`](https://github.com/razorpay/react-native-apollo-devtools), the Apollo Client dev tools plugin allows inspecting cache, query, and mutation for the Apollo Client.
要使用该插件，请首先安装该软件包：
¥To use the plugin, start by installing the package:
```sh
$ npx expo install @dev-plugins/apollo-client
```
然后将你的客户端实例传递给应用根组件中的插件或将应用的其余部分封装在 `ApolloProvider` 中的位置：
¥Then pass your client instance to the plugin in your app's root component or where you wrap the rest of your app in the `ApolloProvider`:
```jsx App.js
import { ApolloProvider, ApolloClient, InMemoryCache } from '@apollo/client';
import { useApolloClientDevTools } from '@dev-plugins/apollo-client';
const client = new ApolloClient({
  uri: 'https://demo.test.com/',
  cache: new InMemoryCache(),
});
export default function App() {
  useApolloClientDevTools(client);
  return <ApolloProvider>{/* ... */}</ApolloProvider>;
}
```
在终端中，运行 `npx expo start`，按 <kbd>shift</kbd> + <kbd>m</kbd> 打开开发工具列表，然后选择 Apollo Client 插件。这将打开插件的 Web 界面，显示你的应用执行 Apollo 客户端操作时的查询历史记录、缓存和突变。
¥In the terminal, run `npx expo start`, press <kbd>shift</kbd> + <kbd>m</kbd> to open the list of dev tools, and then select the Apollo Client plugin. This will open the plugin's web interface, showing your query history, cache, and mutations as your app performs Apollo Client operations.
<a id="react-query"></a>
### 反应查询
¥React Query
受 [`react-query-native-devtools`](https://github.com/bgaleotti/react-query-native-devtools) 的启发，React Query 开发工具插件可让你探索数据和查询、缓存状态，以及从 [TanStack 查询](https://tanstack.com/query/latest/) 的缓存中重新获取和删除查询。
¥Inspired by [`react-query-native-devtools`](https://github.com/bgaleotti/react-query-native-devtools), the React Query dev tools plugin lets you explore data and queries, cache status, and refetch and remove queries from the cache from [TanStack Query](https://tanstack.com/query/latest/).
要使用该插件，请首先安装该软件包：
¥To use the plugin, start by installing the package:
```sh
$ npx expo install @dev-plugins/react-query
```
然后将你的客户端实例传递给应用根组件中的插件或将应用的其余部分封装在 `QueryClientProvider` 中的位置：
¥Then pass your client instance to the plugin in your app's root component or where you wrap the rest of your app in the `QueryClientProvider`:
```jsx App.js
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useReactQueryDevTools } from '@dev-plugins/react-query';
const queryClient = new QueryClient({});
export default function App() {
  useReactQueryDevTools(queryClient);
  return <QueryClientProvider client={queryClient}>{/* ... */}</QueryClientProvider>;
}
```
在终端中，运行 `npx expo start`，按 <kbd>shift</kbd> + <kbd>m</kbd> 打开开发工具列表，然后选择 React Query 插件。这将打开插件的 Web 界面，显示应用中使用的查询。
¥In the terminal, run `npx expo start`, press <kbd>shift</kbd> + <kbd>m</kbd> to open the list of dev tools, and then select the React Query plugin. This will open the plugin's web interface, displaying queries as they are used in your app.
<a id="redux"></a>
### Redux
`redux-devtools-expo-dev-plugin` 基于 [Redux DevTools](https://github.com/reduxjs/redux-devtools/)（来自 Chrome 扩展）。它提供了一个实时操作列表以及它们如何影响状态，以及从 DevTools 倒带、重播和调度操作的能力。
¥The `redux-devtools-expo-dev-plugin` is based on the [Redux DevTools](https://github.com/reduxjs/redux-devtools/) (from the Chrome extension). It provides a live list of actions and how they affect the state, and the ability to rewind, replay, and dispatch actions from the DevTools.
要使用该插件，请首先安装该软件包：
¥To use the plugin, start by installing the package:
```sh
$ npx expo install redux-devtools-expo-dev-plugin
```
如果你使用的是 `@reduxjs/toolkit`，请通过传入 `devTools: false` 来修改 `configureStore` 调用以禁用内置开发工具。然后，通过连接 `devToolsEnhancer()` 添加 Expo DevTools 插件增强器。`configureStore` 调用将如下所示：
¥If you're using `@reduxjs/toolkit`, modify the `configureStore` call to disable the built-in dev tools by passing in `devTools: false`. Then, add in the Expo DevTools plugin enhancer by concatenating the `devToolsEnhancer()`. The `configureStore` call is going to look like the following:
```js store.js
import devToolsEnhancer from 'redux-devtools-expo-dev-plugin';
const store = configureStore({
  reducer: rootReducer,
  devTools: false,
  enhancers: getDefaultEnhancers => getDefaultEnhancers().concat(devToolsEnhancer()),
});
```
在终端中，运行 `npx expo start`，按 <kbd>shift</kbd> + <kbd>m</kbd> 打开开发工具列表，然后选择 `redux-devtools-expo-dev-plugin`。这将打开插件的 Web 界面，在分派操作时显示商店的操作和内容。
¥In the terminal, run `npx expo start`, press <kbd>shift</kbd> + <kbd>m</kbd> to open the list of dev tools, and then select `redux-devtools-expo-dev-plugin`. This will open the plugin's web interface, displaying the actions and contents of your store as actions are dispatched.
有关完整的安装和使用说明，包括如果你直接使用 `redux` 而不是 `@reduxjs/toolkit`、[设置持久性以使用户在重新加载之间保持登录状态](https://github.com/matt-oakes/redux-devtools-expo-dev-plugin)。
¥For complete installation and usage instructions, including if you're using `redux` directly rather than `@reduxjs/toolkit`, [see the project's README](https://github.com/matt-oakes/redux-devtools-expo-dev-plugin).
<a id="tinybase"></a>
### TinyBase
TinyBase 开发工具插件将 TinyBase Store Inspector 连接到你的应用，允许你查看和更新应用商店的内容。
¥The TinyBase dev tools plugin connects the TinyBase Store Inspector to your app, allowing you to view and update the contents of your app's store.
要使用该插件，请首先安装该软件包：
¥To use the plugin, start by installing the package:
```sh
$ npx expo install @dev-plugins/tinybase
```
然后将你的客户端实例传递给应用根组件中的插件或使用商店的 `Provider` 封装应用其余部分的位置：
¥Then pass your client instance to the plugin in your app's root component or where you wrap the rest of your app with the store's `Provider`:
```jsx App.js
import { createStore } from 'tinybase';
import { useValue, Provider } from 'tinybase/lib/ui-react';
import { useTinyBaseDevTools } from '@dev-plugins/tinybase';
const store = createStore().setValue('counter', 0);
export default function App() {
  useTinyBaseDevTools(store);
  return <Provider store={store}>{/* ... */}</Provider>;
}
```
在终端中，运行 `npx expo start`，按 <kbd>shift</kbd> + <kbd>m</kbd> 打开开发工具列表，然后选择 Tinybase 插件。这将打开插件的网络界面，显示修改后的商店内容。
¥In the terminal, run `npx expo start`, press <kbd>shift</kbd> + <kbd>m</kbd> to open the list of dev tools, and then select the Tinybase plugin. This will open the plugin's web interface, displaying the contents of your store as it is modified.


## 创建开发工具插件

了解如何创建开发工具插件以增强你的开发体验。

> 提示：查看 [Expo DevTools 插件](https://github.com/expo/dev-plugins) 了解完整示例。
>
> ¥**Tip**: Check out the [Expo DevTools Plugins](https://github.com/expo/dev-plugins) for complete examples.
你可以创建一个开发工具插件，无论是用于检查通用框架或库的各个方面，还是特定于你的自定义代码的内容。本指南将引导你创建开发工具插件。
¥You can create a dev tools plugin, whether that's for inspecting aspects of a common framework or library or something specific to your custom code. This guide will walk you through creating a dev tools plugin.
<a id="what-is-a-dev-tools-plugin"></a>
## 什么是开发工具插件？
¥What is a dev tools plugin?
开发工具插件在本地开发环境中的 Web 浏览器中运行，并连接到你的 Expo 应用。
¥A dev tools plugin runs in your web browser in your local development environment and connects to your Expo app.
插件由三个关键元素组成：
¥A plugin consists of three key elements:
* 用于显示开发工具 Web 用户界面的 Expo 应用。
  ¥An Expo app to display the dev tools web user interface.
* 用于 Expo CLI 识别的 expo-module.config.json。
  ¥An **expo-module.config.json** for Expo CLI recognition.
* 调用 `expo/devtools` API 以便应用与开发工具的 Web 界面来回通信。
  ¥Calls to `expo/devtools` API for the app to communicate back and forth with the dev tool's web interface.
插件可以在 npm 上分发或包含在应用的 monorepo 中。它们通常会导出一个钩子，该钩子可在应用的根组件中使用，以便在应用在调试模式下运行时启动与 Web 界面的双向通信。
¥Plugins can be distributed on npm or included inside your app's monorepo. They typically export a single hook that can be used in your app's root component to initiate two-way communication with the web interface when your app is running in debug mode.
Step 1: 
## Create a plugin
### Create a new plugin project
`create-dev-plugin` will set up a new plugin project for you. Run the following command to create a new plugin project:
```sh
$ npx create-dev-plugin@latest
```
`create-dev-plugin` will prompt you for the name of your plugin, a description, and the name of the hook that will be used by consumers of your plugin.
The plugin project will contain the following directories:
- **src** - this exports the hook that will be used inside the consuming app to connect it to the plugin.
- **webui** - this contains the web user interface for the plugin.
### Customize a plugin's functionality
The template includes a simple example of sending and receiving messages between the plugin and the app. `useDevToolsPluginClient`, imported from `expo/devtools`, provides functionality for sending and receiving messages between the plugin and the app.
The client object returned by `useDevToolsPluginClient` includes:
#### addMessageListener
Listens for a message matching the typed string and invokes the callback with the message data.
!!!IG0!!!
#### sendMessage
Listens for a message matching the typed string and invokes the callback with the message data.
!!!IG1!!!
Edit the Expo app inside the **webui** directory to customize the user interface that displays diagnostic information from your app or triggers test scenarios:
!!!IG2!!!
Edit the hook in the **src** directory to customize what diagnostic information is sent to the plugin or how the app should respond to any messages from the web user interface:
!!!IG3!!!
If you update the hook to return functions that will be called by the app, you will also need to update **src/index.ts** so it exports no-op functions when the app is not running in debug mode:
!!!IG4!!!
Step 2: 
## Test a plugin
Since the plugin web UI is an Expo app, you can test it just like you would any other Expo app, with `npx expo start`, except that you will run it in the browser only. The template includes a convenience command to run the plugin in local development mode:
```sh
$ npm run web:dev
```
Step 3: 
## Build a plugin for distribution
To prepare your plugin for distribution or use within your monorepo, you will need to build the plugin with the following command:
```sh
$ npm run build:all
```
This command will build the hook code into the **build** directory, and the web user interface into the **dist** directory.
Step 4: 
## Use the plugin
Import the plugin's hook into your app's root component and call it to connect your app to the plugin:
!!!IG5!!!


# 审核

## 分发应用以供审核的概述

了解如何使用应用商店、内部分发和 EAS 更新分发你的应用以供审核。

本页概述了与你的团队共享应用预览版本以进行 QA 和审核的三种方法：使用 EAS Update 的应用商店测试轨道、内部分发和开发版本。
¥This page outlines three approaches to sharing a preview version of your app with your team for QA and review: app store testing tracks, internal distribution, and development builds with EAS Update.
Note: Can I use Expo Go for reviewing releases?
---
Even though Expo Go is an open-source sandbox that can be good for previewing isolated prototypes on Android and iOS, it is not intended for production apps. It should be avoided during the preview process of your app.
---
## App store testing tracks
When distributing apps through app store testing tracks, you can only use release builds. You cannot use this method to distribute development builds. An alternative approach is to use ["Internal distribution"](#internal-distribution-with-eas-build), which works with both release and development builds.
Note: Android: Google Play Beta
---
Before a complete public release, [Google Play beta](https://support.google.com/googleplay/android-developer/answer/9845334?visit_id=638740965629093187-3840249980&rd=1) is another option to distribute your app to testers. You can set up either an internal, closed, or open test track and control who has access to the app.
Each test track has its own requirements. For the internal track, you can only invite up to 100 testers. Both closed and open tracks support larger groups of testers. In closed tracks, you need to invite testers, while in open tracks, anyone can join your program.
To use Google Play beta, you need to upload your app as an AAB (Android App Bundle) to the Google Play Console, set up a test track, and invite users via email or a shareable link. Testers can install the app through the Play Store, and you can collect feedback and crash reports directly from the Google Play Console.
---
Note: iOS: TestFlight
---
TestFlight is another option to distribute your app to iOS devices. TestFlight also requires a paid Apple Developer account. TestFlight's internal testing option allows you to create test groups that include up to 100 members of your Apple Developer account team, who then download the app through the TestFlight app. Some teams prefer TestFlight because it doesn't require a new build to add new testers, and apps stay updated automatically.
TestFlight also includes an external testing option that allows you to share your app with up to 10,000 users via an email or a public link.
Both internal and external test distribution in TestFlight require you to [upload your app](/submit/ios) to App Store Connect and wait for the automated review before you can share a build. However, external test builds will need to go through a more formal App Store review (which is distinct from the review that your app must undergo before production release) before being distributed.
---
## Internal distribution with EAS Build
[Internal distribution](/build/internal-distribution/) is a feature provided by EAS that allows developers to create builds and easily share them with a URL. The URL can be opened on a device to install the app. The app is provided as an installable APK for Android or an ad hoc provisioned app for iOS.
As soon as an internal distribution build is created, it is available for download and installation &mdash; no need to fill out any forms or wait for approval/processing. You can use internal distribution to share both release and development builds.
## Development builds and EAS Update
You can use [development builds](/develop/development-builds/introduction/) to load previews of your app during the review stage by publishing an update with [EAS Update](/eas-update/introduction/). After sharing a development build through internal distribution and installing it, you can launch any update that you published with EAS Update, as long as it is compatible with the installed build. Learn more about [Runtime versions and updates](/eas-update/runtime-versions/).
Note: You can use the EAS dashboard to launch updates and share a link to a specific update.
---
---
Note: You can explore and launch updates directly from a development build.
---
---
Note: You can configure GitHub Actions to automatically publish updates on PRs and commits.
---
---
这种方法非常强大，因为它允许你以运行 `eas update` 的速度响应反馈。与你的团队共享应用的新版本可能需要几秒钟，你可以这样做而无需重建应用或将其上传到商店测试轨道。
¥This approach is uniquely powerful because it allows you to respond to feedback as quickly as you can run `eas update`. It can take seconds to share a new version of your app with your team, and you can do so without needing to rebuild the app or upload it to a store test track.
  }
  description={
    <>
      Learn how to use  in your project to launch different app versions
      and preview a published update inside a development build.
    </>


## 与你的团队分享预览

通过在分支上发布更新与你的团队共享应用预览。

在分支上做出更改后，你可以通过发布更新与你的团队共享这些更改。这允许你在审核期间获得有关更改的反馈。
¥Once you've made changes on a branch, you can share them with your team by publishing an update. This allows you to get feedback on your changes during review.
以下步骤概述了发布更改预览并与团队共享的基本流程。如需更全面的资源，请参阅 [预览更新](/eas-update/preview/) 指南。
¥The following steps will outline a basic flow for publishing a preview of your changes, and then sharing it with your team. For a more comprehensive resource, see the [Preview updates](/eas-update/preview/) guide.
<a id="publish-a-preview-of-your-changes"></a>
## 发布更改预览
¥Publish a preview of your changes
你可以通过运行以下 [EAS 命令行接口](/develop/tools/#eas-cli) 命令来发布当前更改的预览：
¥You can publish a preview of your current changes by running the following [EAS CLI](/develop/tools/#eas-cli) command:
```sh
$ eas update --auto
```
此命令将在当前分支名称下发布更新。
¥This command will publish an update under the current branch name.
<a id="share-with-your-team"></a>
## 与你的团队共享
¥Share with your team
发布预览后，你将在终端窗口中看到如下输出：
¥Once the preview is published, you'll see output like this in the terminal window:
```sh
✔ Published!
...
EAS Dashboard      https://expo.dev/accounts/your-account/projects/your-project/updates/708b05d8-9bcf-4212-a052-ce40583b04fd
```
与审阅者共享 EAS 仪表板链接。打开链接后，他们可以单击预览按钮。他们将看到一个二维码，可以扫描该二维码在其设备上打开预览。
¥Share the **EAS dashboard** link with a reviewer. After opening the link, they can click on the **Preview** button. They will see a QR code that they can scan to open the preview on their device.
<a id="create-previews-automatically"></a>
## 自动创建预览
¥Create previews automatically
你可以使用 [EAS 工作流程](/eas/workflows/get-started/) 在每次提交时自动创建预览。首先，你需要 [配置你的项目](/eas/workflows/get-started/#configure-your-project)，在项目根目录下添加一个名为 .eas/workflows/publish-preview-update.yml 的文件，然后添加以下工作流配置：
¥You can automatically create previews on every commit with [EAS Workflows](/eas/workflows/get-started/). First, you'll need to [configure your project](/eas/workflows/get-started/#configure-your-project), add a file named **.eas/workflows/publish-preview-update.yml** at the root of your project, then add the following workflow configuration:
```yaml .eas/workflows/publish-preview-update.yml
name: Publish preview update
on:
  push:
    branches: ['*']
jobs:
  publish_preview_update:
    name: Publish preview update
    type: update
    params:
      branch: ${{ github.ref_name || 'test' }}
```
上述工作流程将在每次提交到每个分支时发布更新。你也可以使用以下 EAS CLI 命令手动运行此工作流程：
¥The workflow above will publish an update on every commit to every branch. You can also run this workflow manually with the following EAS CLI command:
```sh
$ eas workflow:run publish-preview-update.yml
```
了解更多关于 [工作流示例指南](/eas/workflows/examples) 的常见模式。
¥Learn more about common patterns with the [workflows examples guide](/eas/workflows/examples).
<a id="learn-more"></a>
## 了解更多
¥Learn more


## 如何使用 Expo Orbit 启动更新

了解如何在审核工作流程中使用 Expo Orbit 打开更新。

[Expo 轨道](https://expo.dev/orbit) 是一款 macOS 和 Windows 应用，旨在加快从 EAS 安装和运行构建的速度。它使运行构建和更新变得像在 Orbit 中按“打开”一样简单。
¥[Expo Orbit](https://expo.dev/orbit) is a macOS and Windows app designed to speed up installing and running builds from EAS. It makes running your builds and updates as easy as pressing **Open in Orbit**.
Note: How does automatic installation and launching of updates work?
---
When you launch an update, Orbit will look for the latest development build that matches the runtime version and target platform of the update. If a compatible build is found, the update will install automatically on the target device and launch with a deep link that points to the update.
If you don't have any development builds available, either because they have all expired, you haven't created one, you don't use EAS Build, or you are [building your app locally](/guides/local-app-development/), then Orbit will prompt you on how to proceed. Click **Launch with deep link** in the prompt to open the update if you already have a compatible development build installed on your target device.
---
## Prerequisites
- **Install the Orbit app** before following the steps in this guide. You can download it directly from [GitHub releases](https://github.com/expo/orbit/releases) or see the [alternative method](/build/orbit/#installation) to install it.
- After installing the app, sign in to your Expo account from **Settings**.
## Preview an update with Expo Orbit
Previewing with Expo Orbit requires you to have an update published. If you haven't published an update, see [Publish an update](/eas-update/getting-started/#publish-an-update) before following the steps in the next section.
### Install and launch the update
>
注意：使用 Expo Orbit 启动更新不支持在物理 iOS 设备上进行。它支持 Android 设备/模拟器或 iOS 模拟器。
¥**Note**: Launching updates using Expo Orbit is not supported on physical iOS devices. It is supported on Android devices/emulators or iOS Simulators.
发布更新后，请按照以下步骤在 Android 模拟器或 iOS 模拟器上打开它：
¥After the update is published, follow these steps to open it on an Android Emulator or iOS Simulator:
* 导航到项目的更新选项卡。
  ¥Navigate your project's **Updates** tab.
* 选择你要预览的更新。
  ¥Select the update you want to preview.
* 单击预览。这将打开预览对话框。
  ¥Click **Preview**. This will open the **Preview** dialog.
* 在使用 Orbit 打开下，选择一个平台来启动更新。
  ¥Under **Open with Orbit**, select a platform to launch the update.
* Orbit 将在选定的 Android 模拟器或 iOS 模拟器上安装并启动更新。
  ¥Orbit will install and launch the update on the selected Android Emulator or iOS Simulator.
你现在可以使用 Expo Orbit 无缝启动和查看更新。
¥You can now seamlessly launch and review updates using Expo Orbit.


# 部署

## 为应用商店构建你的项目

了解如何为你的应用创建生产版本，该版本已准备好使用 EAS Build 从命令行提交到应用商店。

无论你是使用 [EAS](/build/setup/) 还是 [locally](/guides/local-app-development/) 构建了原生应用二进制文件，应用开发之旅的下一步都是将你的应用提交到商店。为此，你需要创建一个生产版本。
¥Whether you have built a native app binary using [EAS](/build/setup/) or [locally](/guides/local-app-development/), the next step in your app development journey is to submit your app to the stores. To do so, you need to create a **production build**.
生产版本提交到应用商店，向公众发布或作为商店辅助测试流程（如 TestFlight）的一部分。本指南介绍如何使用 [EAS](#production-builds-using-eas) 和 [locally](#production-builds-locally) 创建生产版本。还可以使用任何能够编译 Android 和 iOS 应用的 CI 服务为 Expo 应用创建生产版本。
¥Production builds are submitted to app stores for release to the general public or as part of a store-facilitated testing process such as TestFlight. This guide explains how to create production builds with [EAS](#production-builds-using-eas) and [locally](#production-builds-locally). It is also possible to create production builds for Expo apps with any CI service capable of compiling Android and iOS apps.
<a id="production-builds-using-eas"></a>
## 推进推出
¥Production builds using EAS
生产版本必须通过各自的应用商店安装。你无法直接将它们安装在你的 Android 模拟器、iOS 模拟器或设备上。唯一的例外是，如果你在构建配置文件中明确为 Android 设置了 `"buildType": "apk"`。但是，建议在提交到商店时使用 aab，这是默认配置。
¥Production builds must be installed through their respective app stores. You cannot install them directly on your Android Emulator, iOS Emulator, or device. The only exception to this is if you explicitly set `"buildType": "apk"` for Android on your build profile. However, it is recommended to use **aab** when submitting to stores, and this is the default configuration.
<a id="easjson-configuration"></a>
### `eas.json` 配置
¥`eas.json` configuration
当你创建第一个构建时，已经在 eas.json 中创建了用于构建生产构建的最小配置：
¥A minimal configuration for building a production build in **eas.json** is already created when you create your first build:
```json eas.json
{
  "build": {
    "production": {}
  }
}
```
<a id="create-a-production-build"></a>
### 创建生产版本
¥Create a production build
要创建生产版本，请为平台运行以下命令：
¥To create a production build, run the following command for a platform:
```sh
$ eas build --platform android
```
```sh
$ eas build --platform ios
```
你可以通过将 `--message` 传递给构建命令（例如 `eas build --platform ios --message "Some message"`）来将消息附加到构建。该消息将显示在 EAS 仪表板上。当你想要为你的团队指定构建目的时，它会派上用场。
¥You can attach a message to the build by passing `--message` to the build command, for example, `eas build --platform ios --message "Some message"`. The message will appear on the EAS dashboard. It comes in handy when you want to specify the purpose of the build for your team.
或者，你可以使用 `--platform all` 选项同时为 Android 和 iOS 构建：
¥Alternatively, you can use `--platform all` option to build for Android and iOS at the same time:
```sh
$ eas build --platform all
```
<a id="developer-account"></a>
## 开发者账户
¥Developer account
你需要拥有要提交应用的应用商店的开发者账户。
¥You will need to have a developer account for the app store you want to submit your app.
Note: Google Play Developer membership is required to distribute to the Google Play Store.
---
You can build and sign your app using EAS Build, but you can't upload it to the Google Play Store unless you have a membership, a one-time $25 USD fee.
---
Note: Apple Developer Program membership is required to build for the Apple App Store.
---
If you are going to use EAS Build to create production builds for the Apple App Store, you need access to an account with a $99 USD [Apple Developer Program](https://developer.apple.com/programs) membership.
---
## App signing credentials
Before the build process can start for app stores, you need a store developer account and generate or provide app signing credentials.
Whether you have experience with generating app signing credentials or not, EAS CLI can do the heavy lifting. You can opt-in for EAS CLI to handle the app signing credentials process.
### Android app signing credentials
- If you have not yet generated a keystore for your app, use EAS CLI by selecting `Generate new keystore`, and then you are done. The keystore is stored securely on EAS servers.
- If you want to manually generate your keystore, see the [manual Android credentials guide](/app-signing/local-credentials#android-credentials) for more information.
### iOS app signing credentials
- If you have not generated a provisioning profile and/or distribution certificate yet, use EAS CLI by signing in to your Apple Developer Program account and following the prompts.
- If you want to manually generate your credentials, see the [manual iOS credentials guide](/app-signing/local-credentials#ios-credentials) for more information.
## Wait for the build to complete
By default, the `eas build` command will wait for your build to complete, but you can interrupt it if you prefer not to wait. Instead, use the builds details page link prompted by EAS CLI to monitor the build progress and read the build logs. You can also find this page by visiting [your build dashboard](https://expo.dev/builds) or running the following command:
```sh
$ eas build:list
```
If you are a member of an organization and your build is on its behalf, you will find the build details on [the build dashboard for that account](https://expo.dev/accounts/[account]/builds).
## Create builds automatically
You can automatically create builds on commits to specific branches with [EAS Workflows](/eas/workflows/get-started/). First, you'll need to [configure your project](/eas/workflows/get-started/#configure-your-project), add a file named **.eas/workflows/create-builds.yml** at the root of your project, then add the following workflow configuration:
```yaml .eas/workflows/create-builds.yml
name: Create builds
on:
  push:
    branches: ['main']
jobs:
  build_android:
    name: Build Android app
    type: build
    params:
      platform: android
      profile: production
  build_ios:
    name: Build iOS app
    type: build
    params:
      platform: ios
      profile: production
```
The workflow above will create Android and iOS builds on every commit to your project's `main` branch. You can also run this workflow manually with the following EAS CLI command:
```sh
$ eas workflow:run create-builds.yml
```
Learn more about common patterns with the [workflows examples guide](/eas/workflows/examples).
## Production builds locally
To create a production build locally, see the following React Native guides for more information on the necessary steps for Android and iOS.
These guides assume your project has **android** and/or **ios** directories containing the respective native projects. If you use [Continuous Native Generation](/workflow/continuous-native-generation) then you will need to run [prebuild](/workflow/prebuild) to generate the directories before following the guides.
>
注意：按照以下指南，在第四步中，当你为 Android 构建发布 .aab 时，从 android 目录运行 `./gradlew app:bundleRelease` 而不是 `npx react-native build-android --mode=release`。
¥**Note**: Following the guide below, in step four, when you build the release **.aab** for Android, run `./gradlew app:bundleRelease` from the **android** directory instead of `npx react-native build-android --mode=release`.
<a id="next-step"></a>
## 下一步
¥Next step


## 提交至应用商店

了解如何使用 EAS Submit 从命令行将应用提交到 Google Play 商店和 Apple App Store。

EAS Submit 是一项托管服务，允许使用 EAS CLI 上传应用二进制文件并将其提交到应用商店。本指南介绍如何使用 EAS Submit 将你的应用提交到 Google Play Store 和 Apple App Store。
¥**EAS Submit** is a hosted service that allows uploading and submitting app binaries to the app stores using EAS CLI. This guide describes how to submit your app to the Google Play Store and Apple App Store using EAS Submit.
Video Tutorial: [How to quickly publish to the App Store & Play Store with EAS Submit](https://www.youtube.com/watch?v=-KZjr576tuE)
<a id="apple-app-store"></a>
## 苹果应用商店
¥Apple App Store
<Prerequisites numberOfRequirements={4}>
  <Requirement number={1} title="Sign up for an Apple Developer account">
    需要 Apple 开发者账户才能将你的应用提交到 Apple App Store。你可以在 [苹果开发者门户](https://developer.apple.com/account/) 上注册 Apple 开发者账户。
    ¥An Apple Developer account is required to submit your app to the Apple App Store. You can sign up for an Apple Developer account on the [Apple Developer Portal](https://developer.apple.com/account/).
  </Requirement>
  <Requirement number={2} title="Include a bundle identifier in app.json">
    在 app.json 中包含你应用的 bundle identifier：
    ¥Include your app's bundle identifier in **app.json**:
    ```json app.json
    {
      "ios": {
        "bundleIdentifier": "com.yourcompany.yourapp"
      }
    }
    ```
  </Requirement>
  <Requirement number={3} title="Install EAS CLI and authenticate with your Expo account">
    安装 EAS CLI 并使用你的 Expo 账户登录：
    ¥Install EAS CLI and login with your Expo account:
    ```sh
$ npm install -g eas-cli && eas login
```
  </Requirement>
  <Requirement number={4} title="Build a production app">
    你需要一个准备好提交到商店的生产版本。你可以使用 [EAS 构建](/build/introduction/) 创建一个：
    ¥You'll need a production build ready for store submission. You can create one using [EAS Build](/build/introduction/):
    ```sh
$ eas build --platform ios --profile production
```
    或者，你也可以在自己的电脑上使用 `eas build --platform ios --profile production --local` 或 Xcode 构建应用。
    ¥Alternatively, you can build the app on your own computer with `eas build --platform ios --profile production --local` or with Xcode.
  </Requirement>
</Prerequisites>
完成所有先决条件后，即可启动提交流程。
¥Once you have completed all the prerequisites, you can start the submission process.
运行以下命令将构建提交到 Apple App Store：
¥Run the following command to submit a build to the Apple App Store:
```sh
$ eas submit --platform ios
```
该命令将引导你逐步完成提交应用的过程。
¥The command will lead you step by step through the process of submitting the app.
<a id="google-play-store"></a>
## 谷歌应用商店
¥Google Play Store
<Prerequisites numberOfRequirements={7}>
  <Requirement number={1} title="Sign up for a Google Play Developer account">
    需要 Google Play 开发者账户才能将你的应用提交到 Google Play 商店。你可以在 [Google Play 管理中心注册页面](https://play.google.com/apps/publish/signup/) 上注册 Google Play 开发者账户。
    ¥A Google Play Developer account is required to submit your app to the Google Play Store. You can sign up for a Google Play Developer account on the [Google Play Console sign-up page](https://play.google.com/apps/publish/signup/).
  </Requirement>
  <Requirement number={2} title="Create a Google Service Account">
    EAS 要求你上传并配置 Google 服务账户密钥，才能将你的 Android 应用提交到 Google Play 商店。你可以按照 [使用 EAS 上传 Google 服务帐号密钥，用于 Play 商店提交](https://github.com/expo/fyi/blob/main/creating-google-service-account.md) 指南创建一个。
    ¥EAS requires you to upload and configure a Google Service Account Key to submit your Android app to the Google Play Store. You can create one with the [uploading a Google Service Account Key for Play Store submissions with EAS](https://github.com/expo/fyi/blob/main/creating-google-service-account.md) guide.
  </Requirement>
  <Requirement number={3} title="Create an app on Google Play Console">
    点击 [谷歌游戏控制台](https://play.google.com/apps/publish/) 中的“创建应用”创建一个应用。
    ¥Create an app by clicking **Create app** in the [Google Play Console](https://play.google.com/apps/publish/).
  </Requirement>
  <Requirement number={4} title="Install EAS CLI and authenticate with your Expo account">
    安装 EAS CLI 并使用你的 Expo 账户登录：
    ¥Install EAS CLI and login with your Expo account:
    ```sh
$ npm install -g eas-cli && eas login
```
  </Requirement>
  <Requirement number={5} title="Include a package name in app.json">
    在 app.json 中包含你应用的包名：
    ¥Include your app's package name in **app.json**:
    ```json app.json
    {
      "android": {
        "package": "com.yourcompany.yourapp"
      }
    }
    ```
  </Requirement>
  <Requirement number={6} title="Build a production app">
    你需要一个准备好提交到商店的生产版本。你可以使用 [EAS 构建](/build/introduction/) 创建一个：
    ¥You'll need a production build ready for store submission. You can create one using [EAS Build](/build/introduction/):
    ```sh
$ eas build --platform android --profile production
```
    或者，你可以使用 `eas build --platform android --profile production --local` 或 Android Studio 在自己的计算机上构建应用。
    ¥Alternatively, you can build the app on your own computer with `eas build --platform android --profile production --local` or with Android Studio.
  </Requirement>
  <Requirement number={7} title="Upload your app manually at least once">
    你必须至少手动上传一次你的应用。这是 Google Play 商店 API 的限制。
    ¥You have to upload your app manually at least once. This is a limitation of the Google Play Store API.
    请参阅 [首次提交 Android 应用](https://expo.fyi/first-android-submission) 指南了解如何操作。
    ¥Learn how with the [first submission of an Android app](https://expo.fyi/first-android-submission) guide.
  </Requirement>
</Prerequisites>
完成所有先决条件后，即可启动提交流程。
¥Once you have completed all the prerequisites, you can start the submission process.
运行以下命令将构建提交到 Google Play Store：
¥Run the following command to submit a build to the Google Play Store:
```sh
$ eas submit --platform android
```
该命令将引导你逐步完成提交应用的过程。
¥The command will lead you step by step through the process of submitting the app.
<a id="build-and-submit-automatically"></a>
## 自动构建和提交
¥Build and submit automatically
你可以使用 [EAS 工作流程](/eas/workflows/get-started/) 自动创建构建并将其提交到应用商店。首先，你需要 [配置你的项目](/eas/workflows/get-started/#configure-your-project)，在项目根目录下添加一个名为 .eas/workflows/build-and-submit.yml 的文件，然后添加以下工作流配置：
¥You can automatically create builds and submit them to the app stores with [EAS Workflows](/eas/workflows/get-started/). First, you'll need to [configure your project](/eas/workflows/get-started/#configure-your-project), add a file named **.eas/workflows/build-and-submit.yml** at the root of your project, then add the following workflow configuration:
```yaml .eas/workflows/build-and-submit.yml
name: Build and submit
on:
  push:
    branches: ['main']
jobs:
  build_android:
    name: Build Android app
    type: build
    params:
      platform: android
      profile: production
  build_ios:
    name: Build iOS app
    type: build
    params:
      platform: ios
      profile: production
  submit_android:
    name: Submit Android
    type: submit
    needs: [build_android]
    params:
      build_id: ${{ needs.build_android.outputs.build_id }}
  submit_ios:
    name: Submit iOS
    type: submit
    needs: [build_ios]
    params:
      build_id: ${{ needs.build_ios.outputs.build_id }}
```
上述工作流程将在每次提交到项目的 `main` 分支时创建 Android 和 iOS 版本，然后分别将它们提交到 Google Play 和 Apple App Store。你也可以使用以下 EAS CLI 命令手动运行此工作流程：
¥The workflow above will create Android and iOS builds on every commit to your project's `main` branch, then submit them to the Google Play and Apple App Store respectively. You can also run this workflow manually with the following EAS CLI command:
```sh
$ eas workflow:run build-and-submit.yml
```
了解更多关于 [工作流示例指南](/eas/workflows/examples) 的常见模式。
¥Learn more about common patterns with the [workflows examples guide](/eas/workflows/examples).
<a id="manual-submission-to-app-stores"></a>
## 手动提交到应用商店
¥Manual submission to app stores
你也可以手动将你的应用提交到 Google Play 商店和 Apple App Store。
¥You can also submit your app manually to the Google Play Store and Apple App Store.
<a id="next-step"></a>
## 下一步
¥Next step


## 应用存储元数据

简要概述如何使用 EAS 元数据来自动化和维护应用商店的存在。

>  **warning** EAS 元数据处于预览阶段，可能会发生重大更改。
>
> ¥EAS Metadata is in preview and subject to breaking changes.
将应用提交到应用商店时，你需要提供元数据。此过程很漫长，并且通常涉及不适用于你的应用的复杂主题。你提供的信息经过审核后，如果存在任何问题，你需要重新启动此流程。
¥When submitting your app to app stores, you need to provide metadata. This process is lengthy and is often about complex topics that don't apply to your app. After the information you provide gets reviewed and if there is any issue with it, you need to restart this process.
EAS 元数据使你能够从命令行自动化和维护此信息，而不是通过应用商店仪表板中的多个表单。它还可以立即识别众所周知的应用商店限制，这些限制可能会在漫长的审核队列后触发拒绝。本指南展示了如何使用 EAS 元数据来自动化和维护你的应用商店的存在。
¥**EAS Metadata** enables you to automate and maintain this information from the command line instead of going through multiple forms in the app store dashboards. It can also instantly identify well-known app store restrictions that could trigger a rejection after a lengthy review queue. This guide shows how to use EAS Metadata to automate and maintain your app store presence.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
EAS 元数据目前仅支持 Apple App Store。
¥EAS Metadata currently **only supports the Apple App Store**.
> 使用 VS Code？在 store.config.json 文件中安装 [Expo 工具扩展](https://github.com/expo/vscode-expo#readme) 以实现自动补齐、建议和警告。
>
> ¥Using VS Code? Install the [Expo Tools extension](https://github.com/expo/vscode-expo#readme) for auto-complete, suggestions, and warnings in your **store.config.json** files.
<a id="create-a-store-config"></a>
## 创建存储配置
¥Create a store config
EAS 元数据使用 [store.config.json](/eas/metadata/config/) 文件来保存你要上传到应用商店的所有信息。该文件位于 Expo 项目的根目录下。
¥EAS Metadata uses [store.config.json](/eas/metadata/config/) file to hold all the information you want to upload to the app stores. This file is located at the root of your Expo project.
在项目目录的根目录下创建一个新的 store.config.json 文件，如下例所示：
¥Create a new **store.config.json** file at the root of your project directory as shown in the example below:
```json store.config.json
{
  "configVersion": 0,
  "apple": {
    "info": {
      "en-US": {
        "title": "Awesome App",
        "subtitle": "Your self-made awesome app",
        "description": "The most awesome app you have ever seen",
        "keywords": ["awesome", "app"],
        "marketingUrl": "https://example.com/en/promo",
        "supportUrl": "https://example.com/en/support",
        "privacyPolicyUrl": "https://example.com/en/privacy"
      }
    }
  }
}
```
上面的示例文件包含 JSON 架构。将示例值替换为你自己的值。它通常包含你应用的 `title`、`subtitle`、`description`、`keywords` 和 `marketingUrl` 等。
¥The above example file contains JSON schema. Replace the example values with your own. It is usually contains your app's `title`, `subtitle` , `description`, `keywords`, and `marketingUrl` and so on.
从上面的示例中需要记住的重要一点是 `configVersion` 属性。它有助于不向后兼容的版本控制更改。
¥**An important thing to remember from the above example is the `configVersion` property.** It helps with versioning changes that are not backward compatible.
> 有关可在 store.config.json 中定义的属性的更多信息，请参阅 [EAS 元数据架构](/eas/metadata/schema/#config-schema)。
>
> ¥For more information on properties that can be defined in **store.config.json**, see [Schema for EAS Metadata](/eas/metadata/schema/#config-schema).
<a id="upload-the-store-config"></a>
## 上传存储配置
¥Upload the store config
> 在将 store.config.json 推送到应用商店之前，你必须上传应用的新二进制文件。请参阅 [应用商店提交](/deploy/submit-to-app-stores/) 了解更多信息。提交并处理二进制文件后，你可以继续执行以下步骤。
>
> ¥Before pushing the **store.config.json** to the app stores, you must upload a new binary of your app. See [App Store submissions](/deploy/submit-to-app-stores/) for more information. After the binary is submitted and processed, you can continue with the step below.
创建 store.config.json 文件并添加与应用相关的必要信息后，你可以通过运行以下命令将存储配置推送到应用商店：
¥After you have created the **store.config.json** file and added the necessary information related to your app, you can push the store config to the app stores by running the command:
```sh
$ eas metadata:push
```
如果 EAS 元数据在你的存储配置中遇到任何问题，它会在运行此命令时向你发出警告。当没有错误，或者你确认推送但可能存在问题时，它会尝试上传尽可能多的内容。
¥If EAS Metadata runs into any issues with your store config, it will warn you when running this command. When there are no errors, or you confirm to push it with possible issues, it will try to upload as much as possible.
当你修改 store.config.json 文件并希望将最新更改推送到应用商店时，你还可以重复使用此命令。
¥You can also re-use this command when you modify the **store.config.json** file and want to push the latest changes to the app stores.
<a id="next-steps"></a>
## 下一步
¥Next steps


## 发送无线更新

了解如何发送无线更新以向用户推送关键错误修复和改进。

你可以向用户发送包含关键错误修复和改进的无线更新。
¥You can send over-the-air updates containing critical bug fixes and improvements to your users.
<a id="get-started"></a>
## 开始使用
¥Get started
> 如果你之前发布过 [previews](/review/share-previews-with-your-team/) 或创建过 [build](/deploy/build-project/)，则可能已经设置了更新并可以跳过此部分。
>
> ¥If you've published [previews](/review/share-previews-with-your-team/) or created a [build](/deploy/build-project/) before, you may have already set up updates and can skip this section.
要设置更新，请运行以下 [EAS 命令行接口](/develop/tools/#eas-cli) 命令：
¥To set up updates, run the following [EAS CLI](/develop/tools/#eas-cli) command:
```sh
$ eas update:configure
```
命令完成后，你需要进行新构建，然后才能继续下一部分。
¥After the command completes, you'll need to make new builds before continuing to the next section.
<a id="send-an-update"></a>
## 发送更新
¥Send an update
要发送更新，请运行以下 [EAS 命令行接口](/develop/tools/#eas-cli) 命令：
¥To send an update, run the following [EAS CLI](/develop/tools/#eas-cli) command:
```sh
$ eas update --channel production
```
此命令将创建一个更新，并将其提供给配置为在 `production` 通道上接收更新的应用版本。此通道在 [**eas.json**](/eas/json/#channel) 中定义。
¥This command will create an update and make it available to builds of your app that are configured to receive updates on the `production` channel. This channel is defined in [**eas.json**](/eas/json/#channel).
你可以通过强制关闭应用并重新打开两次来验证更新是否有效。更新应在第二次启动时应用。
¥You can verify the update works by force closing the app and reopening it two times. The update should be applied on the second launch.
<a id="send-updates-automatically"></a>
## 自动发送更新
¥Send updates automatically
你可以使用 [EAS 工作流程](/eas/workflows/get-started/) 自动发送更新。首先，你需要执行 [配置你的项目](/eas/workflows/get-started/#configure-your-project) 操作，在项目根目录下添加一个名为 .eas/workflows/send-updates.yml 的文件，然后添加以下工作流配置：
¥You can automatically send updates with [EAS Workflows](/eas/workflows/get-started/). First, you'll need to [configure your project](/eas/workflows/get-started/#configure-your-project), add a file named **.eas/workflows/send-updates.yml** at the root of your project, then add the following workflow configuration:
```yaml .eas/workflows/send-updates.yml
name: Send updates
on:
  push:
    branches: ['main']
jobs:
  send_updates:
    name: Send updates
    type: update
    params:
      channel: production
```
上述工作流程将在每次提交到项目的 `main` 分支时，通过无线方式向 `production` 更新渠道发送更新。你也可以使用以下 EAS CLI 命令手动运行此工作流程：
¥The workflow above will send an over-the-air update for the `production` update channel on every commit to your project's `main` branch. You can also run this workflow manually with the following EAS CLI command:
```sh
$ eas workflow:run send-updates.yml
```
了解更多关于 [工作流示例指南](/eas/workflows/examples) 的常见模式。
¥Learn more about common patterns with the [workflows examples guide](/eas/workflows/examples).
<a id="learn-more"></a>
## 了解更多
¥Learn more
你可以通过我们的 [更新指南](/eas-update/introduction/) 了解如何使用 [推出更新](/eas-update/rollouts/)、[优化资源](/eas-update/optimize-assets/) 等。
¥You can learn how to [rollout an update](/eas-update/rollouts/), [optimize assets](/eas-update/optimize-assets/), and more with our [update guides](/eas-update/introduction/).


## 发布你的 Web 应用

了解如何使用 EAS Hosting 部署你的 Web 应用。

>  **warning** EAS Hosting 处于预览阶段，可能会发生变化。
>
> ¥**EAS Hosting** is in preview and subject to changes.
如果你正在构建通用应用，则可以使用 [EAS 托管](/eas/hosting/introduction/) 快速部署你的 Web 应用。它是一种用于部署使用 Expo Router 和 React 构建的 Web 应用的服务。
¥If you are building a universal app, you can quickly deploy your web app using [EAS Hosting](/eas/hosting/introduction/). It is a service for deploying web apps built with Expo Router and React.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
开始之前，在项目的 app.json 文件中，确保 [`expo.web.output`](/versions/latest/config/app/#output) 属性为 `static` 或 `server`。
¥Before you begin, in your project's **app.json** file, ensure that the [`expo.web.output`](/versions/latest/config/app/#output) property is either `static` or `server`.
<a id="export-your-web-project"></a>
## 导出你的 Web 项目
¥Export your web project
要部署你的 Web 应用，你需要创建 Web 项目的静态构建。通过运行以下命令将你的 Web 项目导出到 dist 目录中：
¥To deploy your web app, you need to create a static build of your web project. Export your web project into a **dist** directory by running the following command:
```sh
$ npx expo export --platform web
```
> 请记住，每次在部署之前对 Web 应用进行更改时，都要重新运行此命令。
>
> ¥Remember to re-run this command every time before deploying when you make changes to your web app.
<a id="initial-deployment"></a>
## 初始部署
¥Initial deployment
要发布你的 Web 应用，请运行以下 [EAS 命令行接口](/develop/tools/#eas-cli) 命令：
¥To publish your web app, run the following [EAS CLI](/develop/tools/#eas-cli) command:
```sh
$ eas deploy
```
首次运行此命令后，系统将提示你为项目选择一个预览子域。此子域是用于创建预览 URL 的前缀，用于生产部署。例如，在 `https://test-app--1234.expo.app` 中，`test-app` 是预览子域。
¥After running this command for the first time, you'll be prompted to select a preview subdomain for your project. This subdomain is a prefix used to create a preview URL and is used for production deployments. For example, in `https://test-app--1234.expo.app`, `test-app` is the preview subdomain.
部署完成后，EAS CLI 将输出预览 URL 以访问你部署的应用。
¥Once your deployment is complete, the EAS CLI will output a preview URL to access your deployed app.
<a id="production-deployment"></a>
## 生产部署
¥Production deployment
要创建生产部署，请运行以下 [EAS 命令行接口](/develop/tools/#eas-cli) 命令：
¥To create a production deployment, run the following [EAS CLI](/develop/tools/#eas-cli) command:
```sh
$ eas deploy --prod
```
部署完成后，EAS CLI 将输出生产 URL 以访问你部署的应用。
¥Once your deployment is complete, the EAS CLI will output a production URL to access your deployed app.
<a id="deploy-automatically"></a>
## 自动部署
¥Deploy automatically
你可以使用 [EAS 工作流程](/eas/workflows/get-started/) 自动将你的应用部署到 Web 上。首先，你需要 [配置你的项目](/eas/workflows/get-started/#configure-your-project)，在项目根目录下添加一个名为 .eas/workflows/deploy-web.yml 的文件，然后添加以下工作流配置：
¥You can automatically deploy your app to the web with [EAS Workflows](/eas/workflows/get-started/). First, you'll need to [configure your project](/eas/workflows/get-started/#configure-your-project), add a file named **.eas/workflows/deploy-web.yml** at the root of your project, then add the following workflow configuration:
```yaml .eas/workflows/deploy-web.yml
name: Deploy web
on:
  push:
    branches: ['main']
jobs:
  deploy_web:
    name: Deploy web
    type: deploy
    params:
      prod: true
```
上述工作流程将在每次提交到项目的 `main` 分支时创建 Web 部署。你也可以使用以下 EAS CLI 命令手动运行此工作流程：
¥The workflow above will create a web deployment on every commit to your project's `main` branch. You can also run this workflow manually with the following EAS CLI command:
```sh
$ eas workflow:run deploy-web.yml
```
了解更多关于 [工作流示例指南](/eas/workflows/examples) 的常见模式。
¥Learn more about common patterns with the [workflows examples guide](/eas/workflows/examples).
<a id="learn-more"></a>
## 了解更多
¥Learn more
你可以了解有关设置 [部署别名](/eas/hosting/deployments-and-aliases/)、使用 [自定义域](/eas/hosting/custom-domain/) 或 [部署 API 路由](/router/reference/api-routes/#deployment) 的更多信息。
¥You can learn more about setting up [deployment aliases](/eas/hosting/deployments-and-aliases/), using a [custom domain](/eas/hosting/custom-domain/), or [deploying an API Route](/router/reference/api-routes/#deployment).


# 监控

## 监控服务

了解如何在发布 Expo 和 React Native 应用后监控其使用情况。

发布应用后，你可以跟踪匿名使用数据，以了解用户如何使用你的应用。此数据包括正在使用哪些更新、用户何时遇到错误等。
¥Once your app is released, you can track anonymized usage data to give you insights on how users use your app. This data includes which updates are in use, when users experience bugs, and more.
<a id="eas-insights"></a>
## EAS Insights
Expo 提供 [`expo-insights`](/eas-insights/introduction/) 库，用于跟踪与 [EAS 更新](/deploy/send-over-the-air-updates/) 相关的信息。此数据包括应用版本、平台、操作系统版本和更新采用情况。安装并在应用商店发布生产版本后，你将能够在项目仪表板上看到其他数据：
¥Expo provides the [`expo-insights`](/eas-insights/introduction/) library, which tracks information related to [EAS Update](/deploy/send-over-the-air-updates/). This data includes the app version, platform, OS version, and update adoption. After you install it and release production builds on the app stores, you'll be able to see additional data on your project dashboard:
从以下指南开始：
¥Get started with the following guide:
<a id="logrocket"></a>
## LogRocket
你可以通过 [LogRocket](https://logrocket.com) 获得更多见解。LogRocket 记录用户会话并在用户使用你的应用时识别错误。你可以按更新 ID 过滤会话，还可以在 EAS 仪表板上连接到你的 LogRocket 账户，以快速访问应用的会话数据。
¥You can get more insights with [LogRocket](https://logrocket.com). LogRocket records user sessions and identifies bugs as your users use your app. You can filter sessions by update IDs and also connect to your LogRocket account on the EAS dashboard to get quick access to your app's session data.
从以下指南开始：
¥Get started with the following guide:
<a id="sentry"></a>
## Sentry
[Sentry](http://getsentry.com/) 是一个崩溃报告平台，它提供对生产部署的实时洞察，并提供重现和修复崩溃的信息。
¥[Sentry](http://getsentry.com/) is a crash reporting platform that provides real-time insight into production deployments with information to reproduce and fix crashes.
它会通知你用户在使用你的应用时遇到的异常或错误，并在网络仪表板上为你组织它们。自动报告的异常包括堆栈跟踪、设备信息、版本和其他相关上下文。你还可以提供特定于你的应用的其他上下文，例如当前路由和用户 ID。
¥It notifies you of exceptions or errors that your users run into while using your app and organizes them for you on a web dashboard. Reported exceptions include stacktraces, device info, version, and other relevant context automatically. You can also provide additional context that is specific to your app, such as the current route and user ID.
从以下指南开始：
¥Get started with the following guide:
<a id="vexo"></a>
## 维克斯
¥Vexo
[维克斯](https://www.vexo.co/) 可帮助你了解用户如何与你的 Expo 应用互动、识别摩擦点并提高参与度。它通过简单的两行集成提供实时用户分析，并提供完整的仪表板，深入了解用户活动、应用性能和采用趋势，以及热图、会话重播等功能。
¥[Vexo](https://www.vexo.co/) helps you understand how users interact with your Expo app, identify friction points, and improve engagement. It provides real-time user analytics with a simple two-line integration and offers a complete dashboard with insights into user activity, app performance, and adoption trends, along with features like heatmaps, session replays, and more.
从以下指南开始：
¥Get started with the following guide:
<a id="bugsnag"></a>
## BugSnag
[BugSnag](https://www.bugsnag.com/) 是一种稳定性监控解决方案，可提供丰富的端到端错误报告和分析，以快速、精确地重现和修复错误。BugSnag 支持全栈，其中包含 50 多个平台的开源库，包括 React Native。
¥[BugSnag](https://www.bugsnag.com/) is a stability monitoring solution that provides rich, end-to-end error reporting and analytics to reproduce and fix errors with speed and precision. BugSnag supports the full stack with open-source libraries for more than 50 platforms, including React Native.
从以下指南开始：
¥Get started with the following guide:


# 更多

## 核心理念

Expo 工具、功能和服务概述。

Expo 是一款 [开源框架](https://github.com/expo/expo/)，适用于在 Android、iOS 和 Web 上原生运行的应用。Expo 汇集了移动和 Web 的精华，并支持构建和扩展应用的许多重要功能。
¥Expo is an [open-source framework](https://github.com/expo/expo/) for apps that run natively on Android, iOS, and the web. Expo brings together the best of mobile and the web and enables many important features for building and scaling an app.
`expo` npm 包为 React Native 应用提供了一系列令人难以置信的功能。`expo` 包几乎可以安装在任何 React Native 项目中。
¥The `expo` npm package enables a suite of incredible features for React Native apps. The `expo` package can be installed in nearly **any React Native project**.
<a id="tools-and-features"></a>
## 工具和特性
¥Tools and features
>  **info** 所有功能都是免费的、可选的，并且可以相互独立使用。未使用的功能不会给你的应用带来额外的臃肿。
>
> ¥All features are free, optional, and can be used independently of each other. Unused features add no additional bloat to your app.
| 特性                                                  | 与 `expo` | 没有 `expo`（裸 React Native） |
| --------------------------------------------------- | -------- | ------------------------- |
| 完全使用 JavaScript 开发复杂的应用。                            |          |                           |
| 使用 Swift 和 Kotlin 编写 JSI 原生模块。                      |          |                           |
| 无需 Xcode 或 Android Studio 即可开发应用。                   |          |                           |
| 使用 [Snack](https://snack.expo.dev/) 在浏览器中创建并共享示例应用。 |          |                           |
| 重大升级，无需原生更改。                                        |          |                           |
| 一流的 TypeScript 支持。                                  |          |                           |
| 从命令行安装原生兼容的库。                                       |          |                           |
| 使用相同的代码库开发高性能网站。                                    |          |                           |
| [隧道](/more/expo-cli/#tunneling) 将你的开发服务器连接到任何设备。    |          |                           |
<a id="services"></a>
## 服务
¥Services
Expo 背后的团队还提供 Expo 应用服务 (EAS)，这是一种深度集成的云服务，用于构建、提交和更新你的 React Native 应用。EAS 可以与任何 React Native 应用一起使用，无论它是否使用 `expo`。
¥The team behind Expo also provides **Expo Application Services (EAS)**, deeply integrated cloud services for building, submitting, and updating your React Native app. EAS can be used with **any React Native app**, regardless of whether it uses `expo` or not.


## 常见问题

有关 Expo 及相关服务的常见问题和限制列表。

本页列出了有关 Expo 及相关服务的一些常见问题和解答。如果此处未解答你的问题，请参阅 [论坛](https://chat.expo.dev/) 了解更多常见问题。
¥This page lists some of the common questions and answers about Expo and related services. If you have a question that is not answered here, see [Forums](https://chat.expo.dev/) for more common questions.
<a id="what-is-expo-used-for"></a>
## Expo 是用来做什么的？
¥What is Expo used for?
Expo 是一款 [开源框架](https://github.com/expo/expo)，适用于在 Android、iOS 和 Web 上原生运行的应用。Expo 汇集了移动和 Web 的优点，并支持构建和扩展应用的许多重要功能，例如实时更新、即时共享应用和网络支持。`expo` npm 包为 React Native 应用提供了一系列令人难以置信的功能。`expo` 包几乎可以安装在任何 React Native 项目中。请参阅 [Expo 提供什么](/core-concepts) 了解更多信息。
¥Expo is an [open-source framework](https://github.com/expo/expo) for apps that run natively on Android, iOS, and the web. Expo brings together the best of mobile and the web and enables many important features for building and scaling an app such as live updates, instantly sharing your app, and web support. The `expo` npm package enables a suite of incredible features for React Native apps. The `expo` package can be installed in nearly any React Native project. See [what Expo offers](/core-concepts) for more information.
<a id="do-companies-use-expo"></a>
## 公司使用 Expo 吗？
¥Do companies use Expo?
是的，Expo 被全球顶层公司使用，为数亿终端用户提供服务。看看我们的 [showcase](https://expo.dev/customers)。
¥Yes, Expo is used by top companies worldwide, serving hundreds of millions of end users. See our [showcase](https://expo.dev/customers).
<a id="why-does-expo-have-its-own-sdk"></a>
## 为什么 Expo 有自己的 SDK？
¥Why does Expo have its own SDK?
当 Expo 首次创建时，React Native 尚未公开发布。这意味着没有第三方软件包。为了使 React Native 的开发者体验合理，我们创建了 [几个库来实现通用功能](/versions/latest)。许多这样的库已经被分叉和修改以满足各种需求。我们欢迎用户混合搭配他们需要的任何 [自定义原生代码](/workflow/customizing)，以使他们的应用变得更加出色。
¥When Expo was first created, React Native had yet to be publicly released. This means there were no third-party packages. To make React Native's developer experience reasonable, we created [several libraries to achieve common functionalities](/versions/latest). Many of these libraries have since been forked and modified to meet various needs. We welcome users to mix and match whichever [custom native code](/workflow/customizing) they need to make their app great.
Expo SDK 经过充分测试，用 TypeScript 编写，有文档记录，并且专为 Android、iOS 和 Web 构建。Expo SDK 中的每个模块协同工作以确保版本控制始终匹配。这创造了良好的升级体验。
¥The Expo SDK is well-tested, written in TypeScript, documented, and built for Android, iOS, and the web. Every module in the Expo SDK works together to ensure versioning always matches. This creates a nice upgrading experience.
Expo SDK 也是用 [Expo 模块 API](/modules) 编写的，以便更轻松地贡献、维护和理解。
¥The Expo SDK is also written with the [Expo Modules API](/modules) to make contributing, maintaining, and understanding easier.
<a id="what-is-the-difference-between-expo-and-react-native"></a>
## Expo 和 React Native 有什么区别？
¥What is the difference between Expo and React Native?
`expo` 包提供了一套功能，可以更轻松地开发和扩展复杂的 React Native 应用。你几乎可以在任何 React Native 应用中安装 `expo`。使用 [Expo 应用服务（EAS）](/eas) 或 React Native 不需要 `expo` 包，但是，强烈建议使用 `expo` 包。请参阅 [Expo 提供什么](/core-concepts) 了解更多信息。
¥The `expo` package provides a suite of features that make it easier to develop, and scale complex React Native applications. You can install `expo` in nearly any React Native app. The `expo` package is not required to use [Expo Application Services (EAS)](/eas) or React Native, however, it is highly recommended. See [what Expo offers](/core-concepts) for more information.
<a id="do-i-need-to-switch-from-react-native-to-use-expo"></a>
## 我需要从 React Native 切换到使用 Expo 吗？
¥Do I need to switch from React Native to use Expo?
不，`expo` npm 包和 CLI 可与任何 React Native 应用配合使用。[Expo 应用服务（EAS）](/eas) 还适用于所有 React Native 应用，对构建、更新、应用商店提交等提供一流的支持。
¥No, the `expo` npm package and CLI work with any React Native app. [Expo Application Services (EAS)](/eas) also works with all React Native apps with first-class support for builds, updates, app store submissions, and more.
<a id="how-much-does-expo-cost"></a>
## Expo 花费多少钱？
¥How much does Expo cost?
Expo 平台为 [免费和开源](https://blog.expo.dev/exponent-is-free-as-in-and-as-in-1d6d948a60dc)。这包括构成用于开发的 [Expo SDK](/versions/latest) 和 [Expo CLI](/more/expo-cli/) 的库。Expo Go 应用是最简单的入门方式，也可从应用商店免费获取。
¥The Expo platform is [free and open source](https://blog.expo.dev/exponent-is-free-as-in-and-as-in-1d6d948a60dc). This includes the libraries that make up the [Expo SDK](/versions/latest) and the [Expo CLI](/more/expo-cli/) used for development. The Expo Go app, the easiest way to get started, is also free from the app stores.
[Expo 应用服务（EAS）](/eas) 是来自 Expo 团队的 React Native 应用的可选云服务套件。EAS 使你可以更轻松地构建应用、将其提交到商店、保持更新、发送推送通知等。如果 [免费计划](https://expo.dev/pricing) 配额足够你的应用使用，你可以免费使用 EAS。更多信息请参见 [定价页面](https://expo.dev/pricing)。
¥[Expo Application Services (EAS)](/eas) is an optional suite of cloud services for React Native apps, from the Expo team. EAS makes it easier to build your app, submit it to the stores, keep it updated, send push notifications, and more. You can use EAS for free if the [Free plan](https://expo.dev/pricing) quotas are sufficient for your app. More information is available on the [pricing page](https://expo.dev/pricing).
<a id="how-do-i-add-custom-native-code-to-my-expo-project"></a>
## 如何将自定义原生代码添加到我的 Expo 项目？
¥How do I add custom native code to my Expo project?
Expo 支持添加自定义原生代码并自定义该原生代码（Android/Xcode 项目）。要使用任何自定义原生代码，你可以创建 [开发构建](/develop/development-builds/introduction/) 和 [配置插件](/config-plugins/introduction)。我们确实建议尽可能使用 [Expo SDK](/versions/latest) 中的模块，以便更轻松地升级并改善开发者体验。
¥Expo supports adding custom native code and customizing that native code (Android/Xcode projects). To use any custom native code, you can create a [development build](/develop/development-builds/introduction/) and [config plugins](/config-plugins/introduction). We do recommend using the modules in the [Expo SDK](/versions/latest) when possible for easier upgrades and improved developer experience.
<a id="can-i-use-expo-in-the-app-that-is-created-with-react-native-cli"></a>
## 我可以在使用 React Native CLI 创建的应用中使用 Expo 吗？
¥Can I use Expo in the app that is created with React Native CLI?
是的！所有 Expo 工具和服务在任何 React Native 应用中都能很好地工作。例如，你可以使用 [Expo SDK](/versions/latest)、[`expo-dev-client`](/develop/development-builds/installation/) 和 EAS 构建、提交和更新的任何部分 - 它们效果很好！了解有关 [在你的项目中安装 `expo`](/bare/installing-expo-modules)、[采用预构建](/guides/adopting-prebuild) 和 [设置 EAS 构建](/build/introduction) 的更多信息。
¥Yes! All Expo tools and services work great in any React Native app. For example, you can use any part of the [Expo SDK](/versions/latest), [`expo-dev-client`](/develop/development-builds/installation/) and EAS Build, Submit, and Update — they work great! Learn more about [installing `expo` in your project](/bare/installing-expo-modules), [adopting prebuild](/guides/adopting-prebuild), and [setting up EAS Build](/build/introduction).
<a id="how-do-i-share-my-expo-project-can-i-submit-it-to-the-app-stores"></a>
## 如何分享我的 Expo 项目？我可以将其提交到应用商店吗？
¥How do I share my Expo project? Can I submit it to the app stores?
共享项目的最快方法是使用 [EAS 更新](/eas-update/introduction) 发布并在 [开发构建](/develop/development-builds/introduction/) 中启动。这为你的应用提供了一个 URL；你可以与任何拥有 Android 或 iOS 版 [开发构建](/develop/development-builds/introduction/) 的人分享此 URL。URL 也可以在 Android 版 Expo Go 中打开。
¥The fastest way to share your project is to publish with [EAS Update](/eas-update/introduction) and launch in a [development build](/develop/development-builds/introduction/). This gives your app a URL; you can share this URL with anybody who has the [development build](/develop/development-builds/introduction/) for Android or iOS. URLs can also be opened in Expo Go for Android.
准备就绪后，你可以创建生产版本（.aab 和 .ipa）以提交到应用商店。你可以使用 [EAS 构建](/build/introduction) 在单个命令中构建应用，然后使用 [EAS 提交](/submit/introduction) 将其提交到商店。
¥When ready, you can create a production build (**.aab** and **.ipa**) to submit to the app stores. You can build your app in a single command with [EAS Build](/build/introduction) and submit it to the stores with [EAS Submit](/submit/introduction).
你还可以使用 [内部分配](/build/internal-distribution) 在 Android 上通过 APK 共享你的应用，在 iOS 上通过临时或企业配置共享你的应用。
¥You can also use [internal distribution](/build/internal-distribution) to share your app with an APK on Android and ad-hoc or enterprise provisioning on iOS.
<a id="can-i-develop-ios-apps-on-a-windows-computer"></a>
## 我可以在 Windows 计算机上开发 iOS 应用吗？
¥Can I develop iOS apps on a Windows computer?
传统上，你需要 macOS 来开发 iOS 应用，但是，你可以使用 [EAS 构建](/build/introduction) 在云中构建你的应用。你还可以使用 [EAS 提交](/submit/introduction) 将你的应用提交到商店。可以使用 [Expo](https://expo.dev/go) 或 [开发构建](/develop/development-builds/introduction/) 在物理 iOS 设备上完成测试。
¥Traditionally you needed a macOS to develop iOS apps, however, you can use [EAS Build](/build/introduction) to build your app in the cloud. You can also use [EAS Submit](/submit/introduction) to submit your app to the stores. Testing can be done on a physical iOS device using [Expo Go](https://expo.dev/go) or a [development build](/develop/development-builds/introduction/).
<a id="what-versions-of-android-and-ios-are-supported-by-the-expo-sdk"></a>
## Expo SDK 支持哪些版本的 Android 和 iOS？
¥What versions of Android and iOS are supported by the Expo SDK?
目前，Expo SDK 支持 Android {latestSdkVersionValues.android} 和 iOS {latestSdkVersionValues.ios}。欲了解更多信息，请参阅 [支持 Android 和 iOS 版本](/versions/latest/#support-for-android-and-ios-versions)。
¥Currently, Expo SDK supports Android {latestSdkVersionValues.android} and iOS {latestSdkVersionValues.ios}. For more information, see [Support for Android and iOS versions](/versions/latest/#support-for-android-and-ios-versions).
<a id="what-is-the-minimal-size-of-a-hello-world-expo-app"></a>
## "你好世界" expo 应用的最小大小是多少？
¥What is the minimal size of a "hello world" expo app?
使用纯 Expo 创建的最小生产应用小于 3 MB。对于 iOS，Expo 的目标是更新的最低 iOS 版本，以实现应用商店优化。
¥A bare minimum production app created using pure Expo is less than 3 MB. For iOS, Expo targets a newer minimum iOS version which enables app store optimizations.
如果你的应用中包含 `expo` 软件包，则它只会一次性为应用商店中应用的最终大小增加 1 MB。`expo` 包具有边际大小成本（例如，Android 上为 150 Kib）。其余的大小来自语言运行时（例如 Android 上的 Kotlin）。
¥If the `expo` package is included in your app, it only adds 1 MB one time to the final size of apps on app stores. The `expo` package has a marginal size cost (for example, 150 Kib on Android). The rest of the size comes from the language runtime (such as Kotlin on Android).
<a id="can-i-use-expo-with-my-native-library"></a>
## 我可以将 Expo 与我的原生库一起使用吗？
¥Can I use Expo with my native library?
你可以通过使用 Swift 和 Kotlin 创建 [自定义原生模块](/modules)，将原生 Android 和 iOS 库与 Expo 结合使用。许多流行的库已经有自定义的原生模块。查看我们的 [React Native 目录](https://reactnative.directory)，找到适合你的用例的流行库。
¥You can use native Android and iOS libraries with Expo by creating a [custom native module](/modules) with Swift and Kotlin. Many popular libraries already have custom native modules. Check out our [React Native directory](https://reactnative.directory) to find popular libraries for your use case.
<a id="can-i-use-expo-with-this-web-library"></a>
## 我可以将 Expo 与此网络库一起使用吗？
¥Can I use Expo with this web library?
许多流行的 Web 包（例如 Three.js）可与 Expo 和 React Native 配合使用。请参阅 [Expo 实例](https://github.com/expo/examples) 了解更多信息。
¥Many popular web packages such as three.js work with Expo and React Native. See [Expo examples](https://github.com/expo/examples) for more information.
<a id="is-expo-similar-to-react-for-web-development"></a>
## Expo 与 Web 开发的 React 类似吗？
¥Is Expo similar to React for web development?
Expo 是一款 [开源框架](https://github.com/expo/expo)，适用于在 Android、iOS 和 Web 上原生运行的应用。React Native 与 Web 开发中的 `react-dom` 类似，使你能够在特定平台上运行 React，但是，它有一些关键区别：
¥Expo is an [open-source framework](https://github.com/expo/expo) for apps that run natively on Android, iOS, and the web. React Native is similar to `react-dom` from web development, enabling you to run React on a particular platform, however, it has a few key differences:
* React Native 不支持 HTML 或 CSS。
  ¥React Native does not support HTML or CSS.
* React Native 不使用 DOM，而是使用原生组件。例如，`<View />` 而不是 `<div />`。原生组件比 DOM 性能更高，并提供更好的用户体验。
  ¥Instead of using the DOM, React Native uses native components. For example, `<View />` instead of `<div />`. Native components are more performant than the DOM and provide a much nicer user experience.
* 与可以访问浏览器 API 的 React.js 不同，React Native 使用自定义原生 API。例如，你使用 `expo-location` 代替 `navigator.geolocation` 来访问用户的位置。自定义原生 API 与浏览器 API 类似，只不过你可以完全控制它们。这意味着你可以在新功能在浏览器中可用之前访问它们。
  ¥Unlike React.js which has access to browser APIs, React Native uses custom native APIs. For example, instead of `navigator.geolocation`, you use `expo-location` to access the user's location. Custom native APIs are similar to browser APIs except you have full control over them. This means you can access new features before they are available in the browser.
就像 React.js 框架帮助用户轻松创建更大的网站一样，Expo 也帮助用户轻松创建更大的应用。Expo 提供了一套经过充分测试的 React Native 模块，可以在 Android、iOS 和 Web 上运行。Expo 还提供了 [工具套件](/eas) 用于构建、部署和更新你的应用。
¥In the same way React.js frameworks help users create larger websites with ease, Expo helps users create larger apps with ease. Expo provides a suite of well-tested React Native modules that run on Android, iOS, and the web. Expo also provides a [suite of tools](/eas) for building, deploying, and updating your app.
<a id="what-are-the-store-policies-regarding-interpreted-code"></a>
## 关于解释代码的商店政策是什么？
¥What are the store policies regarding interpreted code?
React Native 使用 JavaScript 解释器（JSC、V8 或 Hermes）来运行应用代码。直接参考 [Google Play 政策中心](https://play.google/developer-content-policy/) 和 [Apple 开发者计划许可协议](https://developer.apple.com/support/terms/apple-developer-program-license-agreement) 了解最新的政策信息。
¥React Native uses a JavaScript interpreter (JSC, V8, or Hermes) to run your application code. Refer to the [Google Play Policy Center](https://play.google/developer-content-policy/) and [Apple Developer Program License Agreement](https://developer.apple.com/support/terms/apple-developer-program-license-agreement) directly for the most up-to-date policy information.
以下是截至 2024 年 4 月 25 日的相关政策摘录。
¥*The following are excerpts of related policies, as of April 25, 2024.*
<a id="google-play-store"></a>
### 谷歌应用商店
¥Google Play Store
```text
...an app may not download executable code (such as dex, JAR, .so files) from a
source other than Google Play. This restriction does not apply to code that runs
in a virtual machine or an interpreter where either provides indirect access to
Android APIs (such as JavaScript in a webview or browser).
Apps or third-party code, like SDKs, with interpreted languages (JavaScript,
Python, Lua, etc.) loaded at run time (for example, not packaged with the app)
must not allow potential violations of Google Play policies.
```
来源：[Google Play 政策中心](https://support.google.com/googleplay/android-developer/answer/9888379?hl=en)。
¥Source: [Google Play Policy Center](https://support.google.com/googleplay/android-developer/answer/9888379?hl=en).
<a id="apple-app-store"></a>
### 苹果应用商店
¥Apple App Store
```text
...Interpreted code may be downloaded to an Application but only so long as such code:
(a) does not change the primary purpose of the Application by providing features
    or functionality that are inconsistent with the intended and advertised purpose
    of the Application as submitted to the App Store,
(b) does not create a store or storefront for other code or applications, and
(c) does not bypass signing, sandbox, or other security features of the OS.
```
来源：[3.3.1 API 和功能 - B. 可执行代码](https://developer.apple.com/support/terms/apple-developer-program-license-agreement#b331)。
¥Source: [3.3.1 APIs and Functionality - B. Executable Code](https://developer.apple.com/support/terms/apple-developer-program-license-agreement#b331).
<a id="should-i-use-expo-cli-or-react-native-community-cli"></a>
## 我应该使用 Expo CLI 还是 React Native Community CLI？
¥Should I use Expo CLI or React Native Community CLI?
Expo CLI 提供与 React Native Community CLI（也称为 "React Native CLI"）相同的核心功能，并具有自动 [TypeScript 设置](/guides/typescript)、[网络支持](/workflow/web)、[自动安装兼容库](/more/expo-cli/#install)、[改进的原生构建命令](/more/expo-cli#compiling)、[tunneling](/more/expo-cli#tunneling)、[预建](/workflow/prebuild) 和 [more](/more/expo-cli) 等附加功能。
¥Expo CLI offers the same core functionality as React Native Community CLI (also known as "React Native CLI") with additional features such as automatic [TypeScript setup](/guides/typescript), [web support](/workflow/web), [auto installing compatible libraries](/more/expo-cli/#install), [improved native build commands](/more/expo-cli#compiling), [tunneling](/more/expo-cli#tunneling), [Prebuild](/workflow/prebuild), and [more](/more/expo-cli).
它可以与 React Native Community 同时使用。无论你使用哪种 CLI，你都可以在项目中使用 [Expo SDK](/versions/latest/) 和 [Expo 应用服务](/eas) 的任何部分。有关更多信息，请参阅：
¥It can be used simultaneously with React Native Community. Regardless of which CLI you use, you can use any part of the [Expo SDK](/versions/latest/) and [Expo Application Services](/eas) with your project. For more information, see:
* 了解如何迁移以在 [现有的 React Native 项目](/bare/using-expo-cli/) 中使用 Expo CLI。
  ¥Learn how you can migrate to use Expo CLI in an [existing React Native project](/bare/using-expo-cli/).
* 了解 [使用带有 配置插件的本地字体文件](https://rn.nodejs.cn/blog/2024/06/25/use-a-framework-to-build-react-native-apps) 的好处。
  ¥Learn about the benefits of [using a framework to build React Native apps](https://rn.nodejs.cn/blog/2024/06/25/use-a-framework-to-build-react-native-apps).
* 了解迁移到 Expo CLI 的好处，例如提高应用性能、加快发布速度以及在 [此链接](https://expo.dev/blog/from-rnc-cli-to-expo) 中促进团队之间更紧密的协作。
  ¥Learn about the benefits of migrating to Expo CLI such as improved app performance, expedites release, and fostering stronger collaboration across you team in [this blog post](https://expo.dev/blog/from-rnc-cli-to-expo).
> 注意：EAS Build 与现有的 React Native 项目兼容（其中原生目录已签入版本控制）。当这些目录存在时，EAS Build 不会运行预构建步骤，因为这可能会覆盖你对原生项目文件所做的任何手动自定义设置。你必须使用 Android Studio 或 Xcode 等原生工具自行配置原生目录。
>
> ¥**Note:** EAS Build is compatible with existing React Native projects (where native directories are checked into version control). When these directories are present, EAS Build does not run the prebuild step, as that could overwrite any manual customizations you have made to the native project files. You'll have to configure the native directories on your own with native tools such as Android Studio or Xcode.
<a id="is-expo-go-open-source"></a>
## Expo Go 是开源的吗？
¥Is Expo Go open source?
是的，Expo Go 的源代码可以在 apps/expo-go 目录的 [expo/expo GitHub 存储库](https://github.com/expo/expo) 中找到。Expo Go 应用也是使用 Expo 和 React Native 构建的。
¥Yes, the source for Expo Go can be found in the [expo/expo GitHub repository](https://github.com/expo/expo) in the **apps/expo-go** directory. The Expo Go app is also built with Expo and React Native.
<a id="what-can-i-do-or-cannot-do-with-expo-go"></a>
## Expo Go 可以做什么或不能做什么？
¥What can I do or cannot do with Expo Go?
[Expo](/get-started/set-up-your-environment/?redirected=#how-would-you-like-to-develop) 是一个沙盒，可以帮助你快速开始 React Native 开发，以便学习、制作原型或进行实验。它允许你使用 Expo SDK 中包含的库以及不需要自定义原生代码的库。
¥[Expo Go](/get-started/set-up-your-environment/?redirected=#how-would-you-like-to-develop) is a sandbox that can help you get started quickly with React Native development in order to learn, prototype, or experiment. It allows you to use libraries included in the Expo SDK and libraries that don't require custom native code.
Expo Go 无法使用需要自定义原生代码的第三方库，并且你无法在 Expo Go 中直接编辑原生代码。它不适用于生产环境的应用。
¥Expo Go cannot use third-party libraries that require custom native code and you cannot edit native code directly in Expo Go. It cannot be used for production apps.
**我们强烈建议任何需要带有原生代码的附加库的项目迁移到 [开发构建](/develop/development-builds/introduction/)。这就像创建一个专门根据你的应用需求定制的 Expo Go 版本。**
¥**We strongly recommend any projects that require additional libraries with native code to migrate to [development builds](/develop/development-builds/introduction/). It's like creating a version of Expo Go that is specifically customized to your app's needs.**
<a id="is-ejecting-deprecated"></a>
## 弹出功能是否已弃用？
¥Is ejecting deprecated?
是的，eject 是一个已弃用的术语，不再需要。Expo 首次发布时，应用的原生二进制文件较大，并且不支持没有 "ejecting" 的自定义原生代码。2020 年 12 月，随着 [EAS 构建](/build/introduction) 的发布，这种情况发生了改变，[EAS 构建](/build/introduction) 版本支持所有 React Native 应用。在 SDK 41（2021 年 4 月）中，"ejecting" 的概念已被 [`npx expo prebuild`](/workflow/prebuild) 命令取代，该命令会根据项目中的库和应用配置 (app.json) 持续生成原生项目。`expo eject` 命令已在 SDK 46（2022 年 8 月）中完全弃用。
¥Yes, eject is a deprecated term and is no longer necessary. When Expo was first released, apps had larger native binary sizes and didn't support custom native code without "ejecting". This changed in December 2020 with the release of [EAS Build](/build/introduction) which supports any React Native app. The concept of "ejecting" was replaced by the [`npx expo prebuild`](/workflow/prebuild) command in SDK 41 (April 2021), which continuously generates native projects based on the libraries in your project and the app config (**app.json**). The `expo eject` command was fully deprecated in SDK 46 (August 2022).
与之前的弹出工作流程不同，开发者可以通过创建 [配置插件](/config-plugins/introduction/) 来配置他们的库以与 Expo Prebuild 配合使用。这意味着你可以将任何库与 Expo Prebuild 一起使用。你还可以通过创建 [开发构建](/develop/development-builds/introduction/) 文件来将任何自定义原生代码与 Expo Prebuild 结合使用。在 [Expo 预建文档](/workflow/prebuild) 中了解更多信息。
¥Unlike the previous eject workflow, authors can configure their libraries to work with Expo Prebuild by creating a [config plugin](/config-plugins/introduction/). This means you can use any library with Expo Prebuild. You can also use any custom native code with Expo Prebuild by creating a [development build](/develop/development-builds/introduction/). Learn more in the [Expo Prebuild documentation](/workflow/prebuild).


## LLM 文档

可用于大型语言模型 (LLM) 和使用它们的应用的 Expo 和 EAS 文档文件列表。

在 Expo，我们支持 [llms.txt](https://llmstxt.org/) 计划，为大型语言模型 (LLM) 及其使用的应用提供文档。以下是可用文档文件的列表：
¥At Expo, we support the [llms.txt](https://llmstxt.org/) initiative to provide documentation for large language models (LLMs) and apps that use them. Below is a list of documentation files available:
* [/llms.txt](/llms.txt)：所有可用文档文件的列表
  ¥[/llms.txt](/llms.txt): A list of all available documentation files
* [/llms-full.txt](/llms-full.txt)：Expo 的完整文档，包括 Expo Router、Expo Modules API、开发过程等
  ¥[/llms-full.txt](/llms-full.txt): Complete documentation for Expo, including Expo Router, Expo Modules API, development process, and more
* [/llms-eas.txt](/llms-eas.txt)：Expo 应用服务 (EAS) 的完整文档
  ¥[/llms-eas.txt](/llms-eas.txt): Complete documentation for the Expo Application Services (EAS)
* [/llms-sdk.txt](/llms-sdk.txt)：最新 Expo SDK 的完整文档
  ¥[/llms-sdk.txt](/llms-sdk.txt): Complete documentation for the latest Expo SDK
Note: Looking for deprecated Expo SDK versions?
---
- [/llms-sdk-v52.0.0.txt](/llms-sdk-v52.0.0.txt): Documentation for the Expo SDK v52.0.0
- [/llms-sdk-v51.0.0.txt](/llms-sdk-v51.0.0.txt): Documentation for the Expo SDK v51.0.0
---


## 教程和 UI 指南概述

“学习”部分是教程和其他指南的集合，可帮助你了解 Expo 和 EAS。它涵盖以下内容：
¥The **Learn** section is a collection of tutorials and other guides that help you learn about Expo and EAS. It covers the following:


# Expo 教程

## 教程：使用 React Native 和 Expo

介绍如何使用 Expo 构建可在 Android、iOS 和 Web 上运行的通用应用的 React Native 教程。

我们即将踏上构建通用应用的旅程。在本教程中，我们将创建一个在 Android、iOS 和 Web 上运行的 Expo 应用；全部都使用一个代码库。让我们开始吧！
¥We're about to embark on a journey of building universal apps. In this tutorial, we'll create an Expo app that runs on Android, iOS, and web; all with a single codebase. Let's get started!
<a id="about-react-native-and-expo-tutorial"></a>
## 关于 React Native 和 Expo 教程
¥About React Native and Expo tutorial
本教程的目标是开始使用 Expo 并熟悉 Expo SDK。它将涵盖以下主题：
¥The objective of this tutorial is to get started with Expo and become familiar with the Expo SDK. It'll cover the following topics:
* 使用启用 TypeScript 的默认模板创建应用
  ¥Create an app using the default template with TypeScript enabled
* 使用 Expo Router 实现双屏底部标签布局
  ¥Implement a two-screen bottom tabs layout with Expo Router
* 分解应用布局并使用 Flexbox 实现
  ¥Break down the app layout and implement it with flexbox
* 使用每个平台的系统 UI 从媒体库中选择图片
  ¥Use each platform's system UI to select an image from the media library
* 使用 React Native 中的 `<Modal>` 和 `<FlatList>` 组件创建贴纸模式
  ¥Create a sticker modal using the `<Modal>` and `<FlatList>` components from React Native
* 添加触摸手势以与贴纸交互
  ¥Add touch gestures to interact with a sticker
* 使用第三方库截屏并保存到磁盘
  ¥Use third-party libraries to capture a screenshot and save it to the disk
* 处理 Android、iOS 和 Web 之间的平台差异
  ¥Handle platform differences between Android, iOS, and web
* 最后，完成配置状态栏、启动画面和图标的过程以完成应用
  ¥Finally, go through the process of configuring a status bar, a splash screen, and an icon to complete the app
这些主题为学习构建 Expo 应用的基础知识提供了基础。本教程是自定进度的，最多可能需要两个小时才能完成。
¥These topics provide a foundation to learn the fundamentals of building an Expo app. The tutorial is self-paced and can take up to two hours to complete.
为了让它对初学者友好，我们将教程分为九章，以便你可以跟着学习或放下它，稍后再回来。每章都包含完成步骤所需的代码片段，因此你可以按照步骤从头开始创建应用或复制和粘贴它。
¥To keep it beginner friendly, we divided the tutorial into nine chapters so that you can follow along or put it down and come back to it later. Each chapter contains the necessary code snippets to complete the steps, so you can follow along by creating an app from scratch or copy and paste it.
在开始之前，先看看我们将构建什么。这是一个名为 StickerSmash 的应用，可在 Android、iOS 和 Web 上运行：
¥Before we get started, take a look at what we'll build. It's an app named **StickerSmash** that runs on Android, iOS, and the web:
>  **info** 本教程的完整源代码可在 [GitHub](https://github.com/expo/examples/tree/master/stickersmash) 上找到。
>
> ¥The complete source code for this tutorial is available on [GitHub](https://github.com/expo/examples/tree/master/stickersmash).
<a id="how-to-use-this-tutorial"></a>
## 如何使用本教程
¥How to use this tutorial
我们相信 [边干边学](https://en.wikipedia.org/wiki/Learning-by-doing)，所以本教程强调做而不是解释。你可以通过从头开始创建应用来跟踪构建应用的过程。
¥We believe in [learning by doing](https://en.wikipedia.org/wiki/Learning-by-doing), so this tutorial emphasizes doing over explaining. You can follow along the journey of building an app by creating the app from scratch.
在整个教程中，任何重要的代码或示例之间发生更改的代码都将是 <span className="tutorial-code-annotation">highlighted in green</span>。你可以将鼠标悬停在高亮部分上（在桌面上）或点击它们（在移动设备上）以了解有关更改的更多信息。例如，下面代码片段中高亮的代码解释了它的作用：
¥Throughout the tutorial, any important code or code that has changed between examples will be <span className="tutorial-code-annotation">highlighted in green</span>. You can hover over the highlights (on desktop) or tap them (on mobile) to learn more about the change. For example, the code highlighted in the snippet below explains what it does:
```tsx Hello World|collapseHeight=300
import { StyleSheet, Text, View } from 'react-native';
export default function Index() {
  return (
    <View style={styles.container}>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
<a id="next-step"></a>
## 下一步
¥Next step
我们已准备好开始构建我们的应用。
¥We're ready to start building our app.


## 创建你的第一个应用

在本章中，了解如何创建新的 Expo 项目。

在本章中，我们将学习如何创建一个新的 Expo 项目以及如何运行它。
¥In this chapter, let's learn how to create a new Expo project and how to get it running.
Video Tutorial: [Watch: Creating your first universal Expo app](https://www.youtube.com/watch?v=m1-bc53EGh8)
***
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
我们需要以下内容才能开始：
¥We'll need the following to get started:
* [Expo](https://expo.dev/go) 安装在物理设备上
  ¥[Expo Go](https://expo.dev/go) installed on a physical device
* [Node.js（LTS 版本）](https://nodejs.cn/en) 安装
  ¥[Node.js (LTS version)](https://nodejs.cn/en) installed
* [VS Code](https://code.visualstudio.com/) 或已安装的任何其他首选代码编辑器或 IDE
  ¥[VS Code](https://code.visualstudio.com/) or any other preferred code editor or IDE installed
* 打开终端窗口的 macOS、Linux 或 Windows（PowerShell 和 [WSL2](https://expo.fyi/wsl)）
  ¥A macOS, Linux, or Windows (PowerShell and [WSL2](https://expo.fyi/wsl)) with a terminal window open
本教程假设你熟悉 TypeScript 和 React。如果你不熟悉它们，请查看 [TypeScript 手册](https://ts.nodejs.cn/docs/handbook/2/everyday-types.html) 和 [React 官方教程](https://react.nodejs.cn/learn)。
¥The tutorial assumes that you are familiar with TypeScript and React. If you are not familiar with them, check out the [TypeScript Handbook](https://ts.nodejs.cn/docs/handbook/2/everyday-types.html) and [React's official tutorial](https://react.nodejs.cn/learn).
Step 1: 
## Initialize a new Expo app
We'll use [`create-expo-app`](/more/create-expo/) to initialize a new Expo app. It is a command line tool to create a new React Native project. Run the following command in your terminal:
```sh
$ npx create-expo-app@latest StickerSmash
$ cd StickerSmash
```
This command will create a new project directory named StickerSmash, using the [default](/more/create-expo/#--template) template. This template has essential boilerplate code and libraries needed to build our app, including Expo Router. We'll continue to add more libraries throughout this tutorial as needed.
Note: Benefits of using the default template
---
- Creates a new React Native project with `expo` package installed
- Includes recommended tools such as Expo CLI
- Includes a tab navigator from Expo Router to provide a basic navigation system
- Automatically configured to run a project on multiple platforms: Android, iOS, and web
- TypeScript configured by default
---
Step 2: 
## Download assets
!!!IG5!!!
After downloading the archive:
1. Unzip the archive and replace the default assets in the **your-project-name/assets/images** directory.
2. Open the project directory in a code editor or IDE.
Step 3: 
## Run reset-project script
In this tutorial, we'll build our app from scratch and understand the fundamentals of adding a file-based navigation. Let's run the `reset-project` script to remove the boilerplate code:
```sh
$ npm run reset-project
```
After running the above command, there are two files (**index.tsx** and **\_layout.tsx**) left inside the **app** directory. The previous files from **app** and other directories (**components**, **constants**, and **hooks** &mdash; containing boilerplate code) are moved inside the **app-example** directory by the script. We'll create our own directories and component files as we go along.
Note: What does the  script do?
---
`reset-project` script resets the **app** directory structure in a project and copies the previous boilerplate files from the project's root directory to another sub-directory called **app-example**. We can delete it since it is not part of our main app's structure.
---
Step 4: 
## Run the app on mobile and web
In the project directory, run the following command to start the [development server](/more/glossary-of-terms/#development-server) from the terminal:
```sh
$ npx expo start
```
After running the above command:
1. The development server will start, and you'll see a QR code inside the terminal window.
2. Scan that QR code to open the app on the device. On Android, use the Expo Go > **Scan QR code** option. On iOS, use the default camera app.
3. To run the web app, press <kbd>w</kbd> in the terminal. It will open the web app in the default web browser.
Once it is running on all platforms, the app should look like this:
Step 5: 
## Edit the index screen
The **app/index.tsx** file defines the text displayed on the app's screen. It is the entry point of our app and executes when the development server starts. It uses core React Native components such as `<View>` and `<Text>` to display background and text.
Styles applied to these components use JavaScript objects rather than CSS, which is used on web. However, a lot of the properties will look familiar if you've previously used CSS on web. Most React Native components accept a `style` prop that accepts a JavaScript object as its value. For more details, see [Styling in React Native](https://rn.nodejs.cn/docs/style).
Let's modify **app/index.tsx** screen:
1. Import `StyleSheet` from `react-native` and create a `styles` object to define our custom styles.
2. Add a `styles.container.backgroundColor` property to `<View>` with the value of `#25292e`. This changes the background color.
3. Replace the default value of `<Text>` with "Home screen".
4. Add a `styles.text.color` property to `<Text>` with the value of `#fff` (white) to change the text color.
!!!IG4!!!
!!!IG3!!!
> React Native uses the same color format as the web. It supports hex triplets (this is what `#fff` is), `rgba`, `hsl`, and named colors, such as `red`, `green`, `blue`, `peru`, and `papayawhip`. For more information, see [Colors in React Native](https://rn.nodejs.cn/docs/colors).
This change will reflect on all platforms automatically:
## Summary
<ProgressTracker
  currentChapterIndex={0}
  name="GET_STARTED"
  summary="We've successfully created a new Expo project, used React Native core components, and are ready to develop our StickerSmash app."
  nextChapterDescription="In the next chapter, we will learn how to add a stack and a tab navigator to our app."
  nextChapterTitle="Add navigation"
  nextChapterLink="/tutorial/add-navigation/"
/>


## 添加导航

在本章中，了解如何向 Expo 应用添加导航。

在本章中，我们将学习 Expo Router 的基础知识，以创建堆栈导航和带有两个选项卡的底部选项卡栏。
¥In this chapter, we'll learn Expo Router's fundamentals to create stack navigation and a bottom tab bar with two tabs.
Video Tutorial: [Watch: Adding navigation in your universal Expo app](https://www.youtube.com/watch?v=8336fcFV_T4)
<a id="expo-router-basics"></a>
## Expo 路由基础知识
¥Expo Router basics
Expo Router 是一个基于文件的路由框架，适用于 React Native 和 Web 应用。它管理屏幕之间的导航，并在多个平台上使用相同的组件。要开始，我们需要了解以下约定：
¥Expo Router is a file-based routing framework for React Native and web apps. It manages navigation between screens and uses the same components across multiple platforms. To get started, we need to know about the following conventions:
* app 目录:仅包含路由及其布局的特殊目录。添加到此目录的任何文件都将成为我们原生应用内的屏幕和 Web 上的页面。
  ¥**app directory**: A special directory containing only routes and their layouts. Any files added to this directory become a screen inside our native app and a page on the web.
* 根布局：app/_layout.tsx 文件。它定义共享的 UI 元素（例如标题和标签栏），以便它们在不同路由之间保持一致。
  ¥**Root layout**: The **app/_layout.tsx** file. It defines shared UI elements such as headers and tab bars so they are consistent between different routes.
* 文件命名约定：索引文件名（例如 index.tsx）与其父目录匹配，并且不添加路径段。例如，应用目录中的 index.tsx 文件与 `/` 路由匹配。
  ¥**File name conventions**: *Index* file names, such as **index.tsx**, match their parent directory and do not add a path segment. For example, the **index.tsx** file in the **app** directory matches `/` route.
* 路由文件将 React 组件导出为其默认值。它可以使用 `.js`、`.jsx`、`.ts` 或 `.tsx` 扩展。
  ¥A **route** file exports a React component as its default value. It can use either `.js`, `.jsx`, `.ts`, or `.tsx` extension.
* Android、iOS 和 Web 共享统一的导航结构。
  ¥Android, iOS, and web share a unified navigation structure.
> 上述列表足以让我们开始。有关功能的完整列表，请参阅 [Expo 路由简介](/router/introduction/)。
>
> ¥The above list is enough for us to get started. For a complete list of features, see [Introduction to Expo Router](/router/introduction/).
Step 1: 
## Add a new screen to the stack
Let's create a new file named **about.tsx** inside the **app** directory. It displays the screen name when the user navigates to the `/about` route.
!!!IG4!!!
Inside **\_layout.tsx**:
1. Add a `<Stack.Screen />` component and an `options` prop to update the title of the `/about` route.
2. Update the `/index` route's title to `Home` by adding `options` prop.
!!!IG14!!!
!!!IG5!!!
Note: What is a ?
---
A stack navigator is the foundation for navigating between different screens in an app. On Android, a stacked route animates on top of the current screen. On iOS, a stacked route animates from the right. Expo Router provides a `Stack` component to create a navigation stack to add new routes.
---
Step 2: 
## Navigate between screens
We'll use Expo Router's `Link` component to navigate from the `/index` route to the `/about` route. It is a React component that renders a `<Text>` with a given `href` prop.
1. Import the `Link` component from `expo-router` inside **index.tsx**.
2. Add a `Link` component after `<Text>` component and pass `href` prop with the `/about` route.
3. Add a style of `fontSize`, `textDecorationLine`, and `color` to `Link` component. It takes the same props as the `<Text>` component.
!!!IG15!!!
!!!IG6!!!
Let's take a look at the changes in our app. Click on `Link` to navigate to the `/about` route:
Step 3: 
## Add a not-found route
When a route doesn't exist, we can use a `+not-found` route to display a fallback screen. This is useful when we want to display a custom screen when navigating to an invalid route on mobile instead of crashing the app or display a _404_ error on web. Expo Router uses a special **+not-found.tsx** file to handle this case.
1. Create a new file named **+not-found.tsx** inside the app directory to add the `NotFoundScreen` component.
2. Add `options` prop from the `Stack.Screen` to display a custom screen title for this route.
3. Add a `Link` component to navigate to the `/` route, which is our fallback route.
!!!IG16!!!
!!!IG7!!!
To test this, navigate to `http:localhost:8081/123` URL in the web browser since it is easy to change the URL path there. The app should display the `NotFoundScreen` component:
Step 4: 
## Add a bottom tab navigator
At this point, the file structure of our **app** directory looks like the following:
!!!IG12!!!
We'll add a bottom tab navigator to our app and reuse the existing Home and About screens to create a tab layout (a common navigation pattern in many social media apps like X or BlueSky). We'll also use the stack navigator in the Root layout so the `+not-found` route displays over any other nested navigators.
1. Inside the **app** directory, add a **(tabs)** subdirectory. This special directory is used to group routes together and display them in a bottom tab bar.
2. Create a **(tabs)/\_layout.tsx** file inside the directory. It will be used to define the tab layout, which is separate from Root layout.
3. Move the existing **index.tsx** and **about.tsx** files inside the **(tabs)** directory. The structure of **app** directory will look like this:
!!!IG13!!!
Update the Root layout file to add a `(tabs)` route:
!!!IG17!!!
!!!IG8!!!
Inside **(tabs)/\_layout.tsx**, add a `Tabs` component to define the bottom tab layout:
!!!IG18!!!
!!!IG9!!!
Let's take a look at our app now to see the new bottom tabs:
Step 5: 
## Update bottom tab navigator appearance
Right now, the bottom tab navigator looks the same on all platforms but doesn't match the style of our app. For example, the tab bar or header doesn't display a custom icon, and the bottom tab background color doesn't match the app's background color.
Modify the **(tabs)/\_layout.tsx** file to add tab bar icons:
1. Import `Ionicons` icons set from [`@expo/vector-icons`](/guides/icons/#expovector-icons) &mdash; a library that includes popular icon sets.
2. Add the `tabBarIcon` to both the `index` and `about` routes. This function takes `focused` and `color` as params and renders the icon component. From the icon set, we can provide custom icon names.
3. Add `screenOptions.tabBarActiveTintColor` to the `Tabs` component and set its value to `#ffd33d`. This will change the color of the tab bar icon and label when active.
!!!IG19!!!
!!!IG10!!!
Let's also change the background color of the tab bar and header using `screenOptions` prop:
!!!IG11!!!
In the above code:
- The header's background is set to `#25292e` using the `headerStyle` property. We have also disabled the header's shadow using `headerShadowVisible`.
- `headerTintColor` applies `#fff` to the header label
- `tabBarStyle.backgroundColor` applies `#25292e` to the tab bar
Our app now has a custom bottom tabs navigator:
## Summary
<ProgressTracker
  currentChapterIndex={1}
  name="GET_STARTED"
  summary="We've successfully added a stack and a tab navigator to our app."
  nextChapterDescription="In the next chapter, we'll learn how to build the app's first screen."
  nextChapterTitle="Build your app's first screen"
  nextChapterLink="/tutorial/build-a-screen"
/>


## 构建一个屏幕

在本教程中，了解如何使用 React Native 的 Pressable 和 Expo Image 等组件来构建屏幕。

在本章中，我们将创建 StickerSmash 应用的第一个屏幕。
¥In this chapter, we'll create the first screen of the StickerSmash app.
上面的屏幕显示一个图片和两个按钮。应用用户可以使用两个按钮之一选择图片。第一个按钮允许用户从他们的设备中选择图片。第二个按钮允许用户继续使用应用提供的默认图片。
¥The screen above displays an image and two buttons. The app user can select an image using one of the two buttons. The first button allows the user to select an image from their device. The second button allows the user to continue with a default image provided by the app.
一旦用户选择图片，他们就可以向其添加贴纸。那么，让我们开始创建这个屏幕。
¥Once the user selects an image, they can add a sticker to it. So, let's start creating this screen.
Video Tutorial: [Watch: Building a screen in your universal Expo app](https://www.youtube.com/watch?v=3rcOP8xDwTQ)
***
Step 1: 
## Break down the screen
Before we build this screen by writing code, let's break it down into some essential elements.
There are two essential elements:
- There is a large image displayed at the center of the screen
- There are two buttons in the bottom half of the screen
The first button contains multiple components. The parent element provides a yellow border, and contains an icon and text components inside a row.
Now that we've broken down the UI into smaller chunks, we're ready to start coding.
Step 2: 
## Display the image
We'll use `expo-image` library to display the image in the app. It provides a cross-platform `<Image>` component to load and render an image.
Stop the development server by pressing <kbd>Ctrl</kbd> + <kbd>c</kbd> in the terminal. Then, install the `expo-image` library:
```sh
$ npx expo install expo-image
```
The [`npx expo install`](/more/expo-cli/#installation) command will install the library and add it to the project's dependencies in **package.json**.
The Image component takes the source of an image as its value. The source can be either a [static asset](https://rn.nodejs.cn/docs/images#static-image-resources) or a URL. For example, the source required from **assets/images** directory is static. It can also come from [Network](https://rn.nodejs.cn/docs/images#network-images) as a `uri` property.
To use the Image component in **app/(tabs)/index.tsx** file:
1. Import `Image` from the `expo-image` library.
2. Create a `PlaceholderImage` variable to use **assets/images/background-image.png** file as the `source` prop on the `Image` component.
!!!IG7!!!
!!!IG0!!!
Step 3: 
## Divide components into files
Let's divide the code into multiple files as we add more components to this screen. Throughout this tutorial, we'll use the components directory to create custom components.
1. Create a top-level **components** directory, and inside it, create the **ImageViewer.tsx** file.
2. Move the code to display the image in this file along with the `image` styles.
!!!IG8!!!
!!!IG1!!!
> **info** Since **ImageViewer** is a custom component, we are placing it in a separate directory instead of the **app** directory. Every file inside **app** directory is either a layout file or a route file. For more information, see [Non-navigation components live outside of app directory](/router/basics/core-concepts/#5-non-navigation-components-live-outside-of-app-directory).
Import `ImageViewer` and use it in the **app/(tabs)/index.tsx**:
!!!IG9!!!
!!!IG2!!!
Note: What is the  in import statement?
---
The `@` symbol is a custom [path alias](/guides/typescript/#path-aliases-optional) for importing custom components and other modules instead of relative paths. Expo CLI automatically configures it in **tsconfig.json**.
---
Step 4: 
## Create buttons using Pressable
React Native includes a few different components for handling touch events, but [`<Pressable>`](https://rn.nodejs.cn/docs/pressable) is recommended for its flexibility. It can detect single taps, long presses, trigger separate events when the button is pushed in and released, and more.
In the design, there are two buttons we need to create. Each has a different style and label. Let's start by creating a reusable component for these buttons. Create a **Button.tsx** file inside the **components** directory with the following code:
!!!IG10!!!
!!!IG3!!!
The app displays an alert when the user taps any of the buttons on the screen. It happens because `<Pressable>` calls `alert()` on its `onPress` prop. Let's import this component into **app/(tabs)/index.tsx** file and add styles for the `<View>` that encapsulates these buttons:
!!!IG11!!!
!!!IG4!!!
Let's take a look at our app on Android, iOS and the web:
The second button with the label "Use this photo" resembles the actual button from the design. However, the first button needs more styling to match the design.
Step 5: 
## Enhance the reusable button component
The "Choose a photo" button requires different styling than the "Use this photo" button, so we will add a new button theme prop that will allow us to apply a `primary` theme. This button also has an icon before the label. We will use an icon from the `@expo/vector-icons` library.
To load and display the icon on the button, let's use `FontAwesome` from the library. Modify **components/Button.tsx** to add the following code snippet:
!!!IG12!!!
!!!IG5!!!
Let's learn what the above code does:
- The primary theme button uses **inline styles**, which overrides the styles defined in `StyleSheet.create()` with an object directly passed in the `style` prop.
- The `<Pressable>` component in the primary theme uses a `backgroundColor` property with a value `#fff` to set the button's background to white. If we add this property to the `styles.button`, the background color value will be set for both the primary theme and the unstyled one.
- Inline styles use JavaScript and override the default styles for a specific value.
Now, modify the **app/(tabs)/index.tsx** file to use the `theme="primary"` prop on the first button.
!!!IG13!!!
!!!IG6!!!
Let's take a look at our app on Android, iOS and the web:
## Summary
<ProgressTracker
  currentChapterIndex={2}
  name="GET_STARTED"
  summary="We've successfully implemented the initial design to start building our app's first screen."
  nextChapterDescription="In the next chapter, we'll add the functionality to pick an image from the device's media library."
  nextChapterTitle="Use an image picker"
  nextChapterLink="/tutorial/image-picker"
/>


## 使用图片选择器

在本教程中，学习如何使用 Expo Image Picker。

React Native 提供内置组件作为标准构建块，例如 `<View>`、`<Text>` 和 `<Pressable>`。我们正在构建一个从设备的媒体库中选择图片的功能。核心组件无法做到这一点，我们需要一个库来在我们的应用中添加此功能。
¥React Native provides built-in components as standard building blocks, such as `<View>`, `<Text>`, and `<Pressable>`. We are building a feature to select an image from the device's media gallery. This isn't possible with the core components and we'll need a library to add this feature in our app.
我们将使用 [`expo-image-picker`](/versions/latest/sdk/imagepicker)，这是 Expo SDK 中的一个库。
¥We'll use [`expo-image-picker`](/versions/latest/sdk/imagepicker), a library from Expo SDK.
> `expo-image-picker` 提供对系统 UI 的访问，以从手机库中选择图片和视频。
>
> ¥`expo-image-picker` provides access to the system's UI to select images and videos from the phone's library.
Video Tutorial: [Watch: Using an image picker in your universal Expo app](https://www.youtube.com/watch?v=iEQZU58naS8)
***
Step 1: 
## Install expo-image-picker
To install the library, run the following command:
```sh
$ npx expo install expo-image-picker
```
> **info** **Tip:** Any time we install a new library in our project, stop the development server by pressing <kbd>Ctrl</kbd> + <kbd>c</kbd> in the terminal and then run the installation command. After the installation completes, we can start the development server again by running `npx expo start` from the same terminal window.
Step 2: 
## Pick an image from the device's media library
`expo-image-picker` provides `launchImageLibraryAsync()` method to display the system UI by choosing an image or a video from the device's media library. We'll use the primary themed button created in the previous chapter to select an image from the device's media library and create a function to launch the device's image library to implement this functionality.
In **app/(tabs)/index.tsx**, import `expo-image-picker` library and create a `pickImageAsync()` function inside the `Index` component:
!!!IG17!!!
!!!IG1!!!
Let's learn what the above code does:
- The `launchImageLibraryAsync()` receives an object to specify different options. This object is the [`ImagePickerOptions`](/versions/latest/sdk/imagepicker/#imagepickeroptions) object, which we are passing when invoking the method.
- When `allowsEditing` is set to `true`, the user can crop the image during the selection process on Android and iOS.
Step 3: 
## Update the button component
On pressing the primary button, we'll call the `pickImageAsync()` function on the `Button` component. Update the `onPress` prop of the `Button` component in **components/Button.tsx**:
!!!IG18!!!
!!!IG2!!!
In **app/(tabs)/index.tsx**, add the `pickImageAsync()` function to the `onPress` prop on the first `<Button>`.
!!!IG19!!!
!!!IG3!!!
The `pickImageAsync()` function invokes `ImagePicker.launchImageLibraryAsync()` and then handles the result. The `launchImageLibraryAsync()` method returns an object containing information about the selected image.
Here is an example of the `result` object and the properties it contains:
!!!IG9!!!
!!!IG10!!!
!!!IG4!!!
!!!IG11!!!
!!!IG12!!!
!!!IG5!!!
!!!IG13!!!
!!!IG14!!!
!!!IG6!!!
!!!IG15!!!
!!!IG16!!!
Step 4: 
## Use the selected image
The `result` object provides the `assets` array, which contains the `uri` of the selected image. Let's take this value from the image picker and use it to show the selected image in the app.
Modify the **app/(tabs)/index.tsx** file:
1. Declare a state variable called `selectedImage` using the [`useState`](https://react.nodejs.cn/learn/state-a-components-memory#adding-a-state-variable) hook from React. We'll use this state variable to hold the URI of the selected image.
2. Update the `pickImageAsync()` function to save the image URI in the `selectedImage` state variable.
3. Pass the `selectedImage` as a prop to the `ImageViewer` component.
!!!IG20!!!
!!!IG7!!!
Pass the `selectedImage` prop to the `ImageViewer` component to display the selected image instead of a placeholder image.
1. Modify the **components/ImageViewer.tsx** file to accept the `selectedImage` prop.
2. The source of the image is getting long, so let's also move it to a separate variable called `imageSource`.
3. Pass `imageSource` as the value of the `source` prop on the `Image` component.
!!!IG21!!!
!!!IG8!!!
In the above snippet, the Image component uses a conditional operator to load the image's source. The picked image is a [`uri` string](https://rn.nodejs.cn/docs/images#network-images), not a local asset like the placeholder image.
Let's take a look at our app now:
> The images used for the example app in this tutorial were picked from [Unsplash](https://unsplash.com).
## Summary
<ProgressTracker
  currentChapterIndex={3}
  name="GET_STARTED"
  summary="We've successfully added the functionality to pick an image from the device's media library."
  nextChapterDescription="In the next chapter, we'll learn how to create an emoji picker modal component."
  nextChapterTitle="Create an emoji picker modal"
  nextChapterLink="/tutorial/create-a-modal"
/>


## 创建模态

在本教程中，了解如何创建 React Native 模式来选择图片。

React Native 提供了 [`<Modal>` 组件](https://rn.nodejs.cn/docs/modal)，将内容渲染在应用的其余部分之上。一般来说，模态框用于吸引用户对关键信息的注意或指导他们采取行动。例如，在 [第三章](/tutorial/build-a-screen/#step-7-enhance-the-reusable-button-component) 中，按下按钮后，我们使用 `alert()` 显示一些占位符文本。这就是模态组件显示叠加层的方式。
¥React Native provides a [`<Modal>` component](https://rn.nodejs.cn/docs/modal) that presents content above the rest of your app. In general, modals are used to draw a user's attention toward critical information or guide them to take action. For example, in the [third chapter](/tutorial/build-a-screen/#step-7-enhance-the-reusable-button-component), after pressing the button, we used `alert()` to display some placeholder text. That's how a modal component displays an overlay.
在本章中，我们将创建一个显示表情符号选择器列表的模式。
¥In this chapter, we'll create a modal that shows an emoji picker list.
Video Tutorial: [Watch: Creating a modal in your universal Expo app](https://www.youtube.com/watch?v=HRAMzrBwVeo)
***
Step 1: 
## Declare a state variable to show buttons
Before implementing the modal, we are going to add three new buttons. These buttons are visible after the user picks an image from the media library or uses the placeholder image. One of these buttons will trigger the emoji picker modal.
In **app/(tabs)/index.tsx**:
1. Declare a boolean state variable, `showAppOptions`, to show or hide the buttons that open the modal, alongside a few other options. When the app screen loads, we'll set it to `false` so the options are not shown before picking an image. When the user picks an image or uses the placeholder image, we'll set it to `true`.
2. Update the `pickImageAsync()` function to set the value of `showAppOptions` to `true` after the user picks an image.
3. Update the button with no theme by adding an `onPress` prop with the following value.
!!!IG11!!!
!!!IG0!!!
In the above snippet, we're rendering the `Button` component based on the value of `showAppOptions` and moving the buttons in the ternary operator block. When the value of `showAppOptions` is `true`, render an empty `<View>` component. We'll address this state in the next step.
Now, we can remove the `alert` on the `Button` component and update the `onPress` prop when rendering the second button in the **components/Button.tsx**:
!!!IG12!!!
!!!IG1!!!
Step 2: 
## Add buttons
Let's break down the layout of the option buttons we'll implement in this chapter. The design looks like this:
It contains a parent `<View>` with three buttons aligned in a row. The button in the middle with the plus icon (+) will open the modal and is styled differently than the other two buttons.
Inside the **components** directory, create a new **CircleButton.tsx** file with the following code:
!!!IG2!!!
To render the plus icon, this button uses the `<MaterialIcons>` icon set from the `@expo/vector-icons` library.
The other two buttons also use `<MaterialIcons>` to display vertically aligned text labels and icons. Create a file named **IconButton.tsx** inside the **components** directory. This component accepts three props:
- `icon`: the name corresponding to the `MaterialIcons` library icon.
- `label`: the text label displayed on the button.
- `onPress`: this function invokes when the user presses the button.
!!!IG3!!!
Inside **app/(tabs)/index.tsx**:
1. Import the `CircleButton` and `IconButton` components to display them.
2. Add three placeholder functions for these buttons. The `onReset()` function invokes when the user presses the reset button, causing the image picker button to appear again. We'll add the functionality for the other two functions later.
!!!IG13!!!
!!!IG4!!!
Let's take a look at our app on Android, iOS and the web:
Step 3: 
## Create an emoji picker modal
The modal allows the user to choose an emoji from a list of available emoji. Create an **EmojiPicker.tsx** file inside the **components** directory. This component accepts three props:
- `isVisible`: a boolean to determine the state of the modal's visibility.
- `onClose`: a function to close the modal.
- `children`: used later to display a list of emoji.
!!!IG14!!!
!!!IG5!!!
Let's learn what the above code does:
- The `<Modal>` component displays a title and a close button.
- Its `visible` prop takes the value of `isVisible` and controls whether the modal is open or closed.
- Its `transparent` prop is a boolean value, which determines whether the modal fills the entire view.
- Its `animationType` prop determines how it enters and leaves the screen. In this case, it is sliding from the bottom of the screen.
- Lastly, the `<EmojiPicker>` invokes the `onClose` prop when the user presses the close `<Pressable>`.
Now, let's modify the **app/(tabs)/index.tsx**:
1. Import the `<EmojiPicker>` component.
2. Create an `isModalVisible` state variable with the `useState` hook. Its default value is `false`, which hides the modal until the user presses the button to open it.
3. Replace the comment in the `onAddSticker()` function to update the `isModalVisible` variable to `true` when the user presses the button. This will open the emoji picker.
4. Create the `onModalClose()` function to update the `isModalVisible` state variable.
5. Place the `<EmojiPicker>` component at the bottom of the `Index` component.
!!!IG15!!!
!!!IG6!!!
Here is the result after this step:
Step 4: 
## Display a list of emoji
Let's add a horizontal list of emoji in the modal's content. We'll use the [`<FlatList>`](https://rn.nodejs.cn/docs/flatlist) component from React Native for it.
Create a **EmojiList.tsx** file inside the **components** directory and add the following code:
!!!IG16!!!
!!!IG7!!!
Let's learn what the above code does:
- The `<FlatList>` component above renders all the emoji images using the `Image` component, wrapped by a `<Pressable>`. Later, we will improve it so that the user can tap an emoji on the screen to make it appear as a sticker on the image.
- It also takes an array of items provided by the `emoji` array variable as the value of the `data` prop. The `renderItem` prop takes the item from the `data` and returns the item in the list. Finally, we added `Image` and the `<Pressable>` components to display this item.
- The `horizontal` prop renders the list horizontally instead of vertically. The `showsHorizontalScrollIndicator` uses React Native's `Platform` module to check the value and display the horizontal scroll bar on web.
Now, update the **app/(tabs)/index.tsx** to import the `<EmojiList>` component and replace the comments inside the `<EmojiPicker>` component with the following code snippet:
!!!IG17!!!
!!!IG8!!!
In the `EmojiList` component, the `onSelect` prop selects the emoji and after selecting it, the `onCloseModal` closes the modal.
Let's take a look at our app on Android, iOS and the web:
Step 5: 
## Display the selected emoji
Now, we'll put the emoji sticker on the image. Create a new file in the **components** directory and call it **EmojiSticker.tsx**. Then, add the following code:
!!!IG9!!!
This component receives two props:
- `imageSize`: a value defined inside the `Index` component. We will use this value in the next chapter to scale the image's size when tapped.
- `stickerSource`: the source of the selected emoji image.
Import this component in the **app/(tabs)/index.tsx** file and update the `Index` component to display the emoji sticker on the image. We'll check if the `pickedEmoji` state is not `undefined`:
!!!IG18!!!
!!!IG10!!!
Let's take a look at our app on Android, iOS and the web:
## Summary
<ProgressTracker
  currentChapterIndex={4}
  name="GET_STARTED"
  summary="We've successfully created the emoji picker modal and implemented the logic to select an emoji and display it over the image."
  nextChapterDescription="In the next chapter, let's add user interactions with gestures to drag the emoji and scale the size by tapping it."
  nextChapterTitle="Add gestures"
  nextChapterLink="/tutorial/gestures"
/>


## 添加手势

在本教程中，了解如何从 React Native Gesture Handler 和 Reanimated 库实现手势。

手势是在应用中提供直观用户体验的好方法。[React Native 手势处理程序](https://docs.swmansion.com/react-native-gesture-handler/docs/) 库提供可以处理手势的内置原生组件。它使用平台的原生触摸处理系统识别平移、点击、旋转和其他手势。在本章中，我们将使用此库添加两个不同的手势：
¥Gestures are a great way to provide an intuitive user experience in an app. The [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/) library provides built-in native components that can handle gestures. It recognizes pan, tap, rotation, and other gestures using the platform's native touch handling system. In this chapter, we'll add two different gestures using this library:
* 双击可缩放表情符号贴纸的大小，再次双击可缩小比例。
  ¥Double tap to scale the size of the emoji sticker and reduce the scale when double tapped again.
* 平移以在屏幕上移动表情符号贴纸，以便用户可以将贴纸放置在图片上的任何位置。
  ¥Pan to move the emoji sticker around the screen so that the user can place the sticker anywhere on the image.
我们还将使用 [复活](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/handling-gestures/) 库在手势状态之间进行动画处理。
¥We'll also use the [Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/handling-gestures/) library to animate between gesture states.
Video Tutorial: [Watch: Adding gestures to your universal Expo app](https://www.youtube.com/watch?v=0q48LLvTGDU)
***
Step 1: 
## Add GestureHandlerRootView
To get gesture interactions to work in the app, we'll render `<GestureHandlerRootView>` from `react-native-gesture-handler` at the top of `Index` component. Replace the root level `<View>` component in the **app/(tabs)/index.tsx** with `<GestureHandlerRootView>`.
!!!IG9!!!
!!!IG0!!!
Step 2: 
## Use animated components
An `Animated` component looks at the `style` prop of the component and determines which values to animate and apply updates to create an animation. Reanimated exports animated components such as `<Animated.View>`, `<Animated.Text>`, or `<Animated.ScrollView>`. We will apply animations to the `<Animated.Image>` component to make a double tap gesture work.
1. Open the **EmojiSticker.tsx** file in the **components** directory. Inside it, import `Animated` from the `react-native-reanimated` library to use animated components.
2. Replace the `Image` component with `<Animated.Image>`.
!!!IG10!!!
!!!IG1!!!
> For a complete reference of the animated component API, see [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/core/createAnimatedComponent) documentation.
Step 3: 
## Add a tap gesture
React Native Gesture Handler allows us to add behavior when it detects touch input, like a double tap event.
In the **EmojiSticker.tsx** file:
1. Import `Gesture` and `GestureDetector` from `react-native-gesture-handler`.
2. To recognize the tap on the sticker, import `useAnimatedStyle`, `useSharedValue`, and `withSpring` from `react-native-reanimated` to animate the style of the `<Animated.Image>`.
3. Inside the `EmojiSticker` component, create a reference called `scaleImage` using the `useSharedValue()` hook. It will take the value of `imageSize` as its initial value.
!!!IG2!!!
Creating a shared value using the `useSharedValue()` hook has many advantages. It helps to mutate data and runs animations based on the current value. We can access and modify the shared value using the `.value` property. We'll create a `doubleTap` object to scale the initial value and use `Gesture.Tap()` to animate the transition while scaling the sticker image. To determine the number of taps required, we'll add `numberOfTaps()`.
Create the following object in the `EmojiSticker` component:
!!!IG3!!!
To animate the transition, let's use a spring-based animation. This will make it feel alive because it's based on the real-world physics of a spring. We will use the `withSpring()` function provided by `react-native-reanimated`.
On the sticker image, we'll use the `useAnimatedStyle()` hook to create a style object. This will help us to update styles using shared values when the animation happens. We'll also scale the size of the image by manipulating the `width` and `height` properties. The initial values of these properties are set to `imageSize`.
Create an `imageStyle` variable and add it to the `EmojiSticker` component:
!!!IG4!!!
Next, wrap the `<Animated.Image>` component with the `<GestureDetector>` and modify the `style` prop on the `<Animated.Image>` to pass the `imageStyle`.
!!!IG11!!!
!!!IG5!!!
In the above snippet, the `gesture` prop takes the value of the `doubleTap` to trigger a gesture when a user double-taps the sticker image.
Let's take a look at our app on Android, iOS and the web:
> For a complete reference of the tap gesture API, see the [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture) documentation.
Step 4: 
## Add a pan gesture
To recognize a dragging gesture on the sticker and to track its movement, we'll use a pan gesture. In the **components/EmojiSticker.tsx**:
1. Create two new shared values: `translateX` and `translateY`.
2. Replace the `<View>` with the `<Animated.View>` component.
!!!IG12!!!
!!!IG6!!!
Let's learn what the above code does:
- The translation values defined will move the sticker around the screen. Since the sticker moves along both axes, we need to track the X and Y values.
- In the `useSharedValue()` hooks, we have set both translation variables to have an initial position of `0`. This is the sticker's initial position and a starting point. This value sets the sticker's initial position when the gesture starts.
In the previous step, we triggered the `onStart()` callback for the tap gesture chained to the `Gesture.Tap()` method. For the pan gesture, specify an `onChange()` callback, which runs when the gesture is active and moving.
1. Create a `drag` object to handle the pan gesture. The `onChange()` callback accepts `event` as a parameter. `changeX` and `changeY` properties hold the change in position since the last event. and update the values stored in `translateX` and `translateY`.
2. Define the `containerStyle` object using the `useAnimatedStyle()` hook. It will return an array of transforms. For the `<Animated.View>` component, we need to set the `transform` property to the `translateX` and `translateY` values. This will change the sticker's position when the gesture is active.
!!!IG7!!!
Next, inside the JSX code:
1. Update the `<EmojiSticker>` component so that the `<GestureDetector>` component becomes the top-level component.
2. Add the `containerStyle` on the `<Animated.View>` component to apply the transform styles.
!!!IG13!!!
!!!IG8!!!
`
Let's take a look at our app on Android, iOS and the web:
## Summary
<ProgressTracker
  currentChapterIndex={5}
  name="GET_STARTED"
  summary="We've successfully implemented pan and tap gestures."
  nextChapterDescription="In the next chapter, we'll learn how to take a screenshot of the image and the sticker, and save it on the device's library."
  nextChapterTitle="Take a screenshot"
  nextChapterLink="/tutorial/screenshot"
/>


## 截图

在本教程中，了解如何使用第三方库和 Expo Media Library 捕获屏幕截图。

在本章中，我们将学习如何使用第三方库截取屏幕截图并将其保存在设备的媒体库中。我们将使用 [`react-native-view-shot`](https://github.com/gre/react-native-view-shot) 截取屏幕截图，并使用 [`expo-media-library`](/versions/latest/sdk/media-library/) 将图片保存在设备的媒体库中。
¥In this chapter, we'll learn how to take a screenshot using a third-party library and save it on the device's media library. We'll use [`react-native-view-shot`](https://github.com/gre/react-native-view-shot) to take a screenshot and [`expo-media-library`](/versions/latest/sdk/media-library/) to save an image on device's media library.
>  **info** 到目前为止，我们已经使用了第三方库，例如 `react-native-gesture-handler`、`react-native-reanimated`。我们可以根据用例在 [React Native 目录](https://reactnative.directory/) 上找到数百个其他第三方库。
>
> ¥So far, we have used third-party libraries, such as `react-native-gesture-handler`, `react-native-reanimated`. We can find hundreds of other third-party libraries on [React Native Directory](https://reactnative.directory/) depending on a use case.
Video Tutorial: [Watch: Taking screenshots in your universal Expo app](https://www.youtube.com/watch?v=Jft3_Yfr-p4)
***
Step 1: 
## Install libraries
To install `react-native-view-shot` and `expo-media-library`, run the following commands:
```sh
$ npx expo install react-native-view-shot expo-media-library
```
Step 2: 
## Prompt for permissions
An app that requires sensitive information, such as accessing a device's media library, has to prompt permission to allow or deny access. Using `usePermissions()` hook from `expo-media-library`, we can use the permission `status` and `requestPermission()` method to ask for access.
When the app loads for the first time and the permission status is neither granted nor denied, the value of the `status` is `null`. When asked for permission, a user can either grant the permission or deny it. We can add a condition to check if it is `null`, and if it is, trigger the `requestPermission()` method. After getting the access, the value of the `status` changes to `granted`.
Add the following code snippet inside the **app/(tabs)/index.tsx**:
!!!IG3!!!
!!!IG0!!!
Step 3: 
## Create a ref to save the current view
We'll use `react-native-view-shot` to allow the user to take a screenshot within the app. This library captures the screenshot of a `<View>` as an image using the `captureRef()` method. It returns the URI of the captured screenshot image file.
1. Import `captureRef` from `react-native-view-shot` and `useRef` from React.
2. Create an `imageRef` reference variable to store the reference of the screenshot image captured.
3. Wrap the `<ImageViewer>` and `<EmojiSticker>` components inside a `<View>` and then pass the reference variable to it.
!!!IG4!!!
!!!IG1!!!
In the above snippet, the `collapsable` prop is set to `false`. This allows the `<View>` component to screenshot only of the background image and emoji sticker.
Step 4: 
## Capture a screenshot and save it
We can capture a screenshot of the view by calling the `captureRef()` method from `react-native-view-shot` inside the `onSaveImageAsync()` function. It accepts an optional argument where we can pass the `width` and `height` of the screenshot capturing area. We can read more about available options in [the library's documentation](https://github.com/gre/react-native-view-shot#capturerefview-options-lower-level-imperative-api).
The `captureRef()` method also returns a promise that fulfills with the screenshot's URI. We will pass this URI as a parameter to [`MediaLibrary.saveToLibraryAsync()`](/versions/latest/sdk/media-library/#medialibrarysavetolibraryasynclocaluri) and save the screenshot to the device's media library.
Inside **app/(tabs)/index.tsx**, update the `onSaveImageAsync()` function with the following code:
!!!IG5!!!
!!!IG2!!!
Now, choose a photo and add a sticker in the app. Then tap the "Save" button. We should see the following result on Android and iOS:
## Summary
<ProgressTracker
  currentChapterIndex={6}
  name="GET_STARTED"
  summary={
    <>
        We've successfully used  and  to capture a
        screenshot and save it on the device's library.
    </>
}
nextChapterDescription="In the next chapter, let's learn how to handle the differences between mobile and web
platforms to implement the same functionality on web."
nextChapterTitle="Handle platform differences"
nextChapterLink="/tutorial/platform-differences"
/>


## 处理平台差异

在本教程中，了解在创建通用应用时如何处理原生和 Web 之间的平台差异。

Android、iOS 和 Web 具有不同的功能。在我们的例子中，Android 和 iOS 都可以使用 `react-native-view-shot` 库捕获屏幕截图。但是，Web 浏览器不能。
¥Android, iOS, and the web have different capabilities. In our case, both Android and iOS can capture a screenshot with the `react-native-view-shot` library. However, web browsers cannot.
在本章中，我们将学习如何处理 Web 浏览器的屏幕截图，以便我们的应用在所有平台上具有相同的功能。
¥In this chapter, we'll learn how to handle capturing screenshots for web browsers so our app has the same functionality on all platforms.
Video Tutorial: [Watch: Handling platform differences in your universal Expo app](https://www.youtube.com/watch?v=mEKQvF4irBM)
***
Step 1: 
## Install and import dom-to-image
To capture a screenshot on the web and save it as an image, we'll use a third-party library called [`dom-to-image`](https://github.com/tsayen/dom-to-image#readme). It takes a screenshot of any DOM node and turns it into a vector (SVG) or raster (PNG or JPEG) image.
Stop the development server and run the following command to install the library:
```sh
$ npm install dom-to-image
```
After installing it, make sure to restart the development server and press <kbd>w</kbd> in the terminal.
Step 2: 
## Add platform-specific code
Using `Platform` module from React Native, we can implement platform-specific behavior. Inside **app/(tabs)/index.tsx**:
1. Import the `Platform` module from `react-native`.
2. Import the `domtoimage` library from `dom-to-image`.
3. Update the `onSaveImageAsync()` function to check whether the current platform is `'web'` with the `Platform.OS` property. If it is `'web'`, we'll use the `domtoimage.toJpeg()` method to convert and capture the current `<View>` as a JPEG image. Otherwise, we'll keep using the same logic added for native platforms.
!!!IG2!!!
!!!IG0!!!
Note: Fix  TypeScript module error
---
We need to add a type definition after importing the `domtoimage` library since we're using TypeScript. We can do this by creating a file **types.d.ts** in the root of our project directory and adding the declaration statement:
!!!IG1!!!
---
On running the app in a web browser, we can now save a screenshot:
## Summary
<ProgressTracker
  currentChapterIndex={7}
  name="GET_STARTED"
  summary="The app does everything we set out for it to do, so it's time to shift our focus toward the purely aesthetic.."
  nextChapterDescription="In the next chapter, we will customize the app's status bar, splash screen, and app icon."
  nextChapterTitle="Configure status bar, splash screen and app icon"
  nextChapterLink="/tutorial/configuration"
/>


## 配置状态栏、启动屏幕和应用图标

在本教程中，了解如何配置状态栏、应用图标和启动画面的基础知识。

在本章中，我们将在将我们的应用部署到应用商店之前解决一些应用细节，例如为状态栏设置主题、自定义应用图标和启动画面。
¥In this chapter, we'll address some app details before deploying our app to an app store, such as theming the status bar, customizing the app icon, and splash screen.
Video Tutorial: [Watch: Adding the finishing touches to your universal Expo app](https://www.youtube.com/watch?v=OgGCYdElcZo)
***
Step 1: 
## Configure the status bar
[`expo-status-bar`](/versions/latest/sdk/status-bar/) library comes pre-installed in every project created using `create-expo-app`. This library provides a `StatusBar` component to configure the app's status bar style.
Inside **app/\_layout.tsx**:
1. Import `StatusBar` from `expo-status-bar`.
2. Group the `StatusBar` and existing `Stack` components with [React's Fragment component](https://react.nodejs.cn/reference/react/Fragment).
!!!IG2!!!
!!!IG0!!!
Let's take a look at our app now on Android, and iOS:
Step 2: 
## App icon
Inside the project, there's an **icon.png** file inside the **assets/images** directory. This is our app icon. It's a 1024px by 1024px image and looks as shown below:
Like the splash screen image, the `"icon"` property in the **app.json** file configures the app icon's path. By default, a new Expo project defines the correct path to `"./assets/images/icon.png"`. We don't have to change anything.
> Eventually, when you'll build your app for the app stores, [Expo Application Services (EAS)](/eas/) will take this image and create optimized icon for every device.
You can see the icon in various places in Expo Go. Here is an example of the app icon displayed in the developer menu of Expo Go:
Step 3: 
## Splash screen
A splash screen is visible before the app's content is loaded. It uses a smaller image, such as an app's icon, which is centered. It hides once the app's content is ready to be displayed.
The [`expo-splash-screen`](/versions/latest/sdk/splash-screen/) plugin already comes pre-installed in every project created using `create-expo-app`. This library provides a config plugin to configure the splash screen.
In **app.json**, the `expo-splash-screen` plugin is already configured to use the app's icon as the splash screen image (provided in the [downloadable assets](/tutorial/create-your-first-app/#download-assets)) with the following snippet so we don't have to change anything:
!!!IG1!!!
However, **to test the splash screen, we cannot use Expo Go or a [development build](/develop/development-builds/introduction/)**. To test it, we need to create a preview or a production build of our app. We recommend going through the following resources to learn more about the splash screen configuration and how to test it:
- [Create a splash screen icon](/develop/user-interface/splash-screen-and-app-icon/#splash-screen) guide to learn how splash screen icon is configured.
- To learn how to create a preview build, see [Internal distribution](/tutorial/eas/internal-distribution-builds/) guide in EAS Tutorial, or to create production builds see guides for [Android](/tutorial/eas/android-production-build/) and [iOS](/tutorial/eas/ios-production-build/).
## Summary
<ProgressTracker
  currentChapterIndex={8}
  name="GET_STARTED"
  summary="Well done! We built an app that runs on Android, iOS, and the web from the same codebase."
  nextChapterDescription="The next section of the tutorial will guide you toward resources to learn more about concepts we've covered here and others we have mentioned briefly."
  nextChapterTitle="Learning resources"
  nextChapterLink="/tutorial/follow-up"
/>


## 学习资源

浏览精选的资源列表以了解 Expo 和 React Native。

现在示例应用已经完成，让我们进一步了解我们用于构建它的技术。
¥Now that the example app is done, let's learn more about the technologies we used to build it.
<a id="build-your-project-into-an-app"></a>
## 将你的项目构建为应用
¥Build your project into an app
要在你的机器上开始创建新应用，你可以依次使用 `npx create-expo-app@latest` 和 [设置你的开发环境](/get-started/set-up-your-environment/)。
¥To start creating a new app on your machine you can use `npx create-expo-app@latest` and [set up your development environment](/get-started/set-up-your-environment/) sequentially.
<a id="recommended-resources"></a>
### 推荐结构
¥Recommended resources
创建新项目后，你可以了解有关帮助你完成应用开发之旅的不同工具和概念的更多信息：
¥Once you've created your new project, you can learn more about different tools and concepts that will help you on your app development journey:
* [开发工具](/develop/tools/)：Expo 工具的参考，可帮助你完成应用构建过程的各个方面。
  ¥[Development tools](/develop/tools/): A reference of Expo tools that will help you during various aspects of your app-building journey.
* [开发构建](/develop/development-builds/introduction/)：使用开发构建允许你完全控制应用的构建过程，并在设备或模拟器上测试你的应用。
  ¥[Development builds](/develop/development-builds/introduction/): Using a development build allows you to gain full control over your app's build process, and to test your app on a device or simulator.
* [开发概述](/workflow/overview/)：这是一个高级概述，详细介绍了使用 Expo 开发应用的关键概念以及核心开发循环的流程。
  ¥[Development overview](/workflow/overview/): This is a high-level overview that provides details on key concepts for developing an app with Expo and the flow of core development loop.
* [Expo 路由](/router/introduction/)：我们介绍了 Expo Router 的基础知识并实现了一个标签导航器。查看其文档以了解有关该库的更多信息。
  ¥[Expo Router](/router/introduction/): We went through basics of Expo Router and implemented a tab navigator. See its documentation to learn more about the library.
* [应用图标](/develop/user-interface/splash-screen-and-app-icon/#app-icon) 和 [启动画面](/develop/user-interface/splash-screen-and-app-icon/#splash-screen)：你可以了解有关自定义应用图标和启动画面指南的更多信息。此外，查看 [应用配置参考](/workflow/configuration) 以查找你可以在 app.json 文件中配置的属性。
  ¥[App icon](/develop/user-interface/splash-screen-and-app-icon/#app-icon) and [splash screen](/develop/user-interface/splash-screen-and-app-icon/#splash-screen): You can learn more about customizing your app icon and splash screen guides. Also, look through the [app config reference](/workflow/configuration) for properties you can configure in the **app.json** file.
* [应用分发](/deploy/build-project/) 和 [submission](/deploy/submit-to-app-stores/) 到应用商店：阅读这些资源以了解有关如何在准备好发布后将应用发布并提交到应用商店的更多信息。
  ¥[App distribution](/deploy/build-project/) and [submission](/deploy/submit-to-app-stores/) to app stores: Read these resources to learn more about how to release and submit your app to app stores once it's ready to ship.
* [调试](/debugging/runtime-issues/)：有时事情会出错，当它们出错时，你可以使用调试工具来查找和修复错误。
  ¥[Debugging](/debugging/runtime-issues/): Sometimes things go wrong, and when they do, you can use debugging tools to find and fix errors.
<a id="learning"></a>
## 学习
¥Learning
<a id="react"></a>
### React
我们使用了 React 组件和 API。深入了解 React 对于使用 Expo 构建应用至关重要。我们建议阅读 React 文档的 [快速入门部分](https://react.nodejs.cn/learn) 和 [钩子部分](https://react.nodejs.cn/reference/react/hooks)。
¥We used React components and APIs. Having a solid understanding of React is essential to using Expo to build your app. We recommend reading the React documentation's [Quick Start section](https://react.nodejs.cn/learn) and the [Hooks section](https://react.nodejs.cn/reference/react/hooks).
<a id="react-native"></a>
### React Native
在开发教程应用时，我们广泛使用了 React Native。你可以从 [React Native 基础知识指南](https://rn.nodejs.cn/docs/getting-started) 开始了解更多。另外，请查看以下文档：
¥While developing the tutorial app, we used React Native extensively. You can start from the [React Native basics guide](https://rn.nodejs.cn/docs/getting-started) to learn more. Also, check out the following docs:
* [查看 API 参考](https://rn.nodejs.cn/docs/view)
  ¥[View API reference](https://rn.nodejs.cn/docs/view)
* [文本 API 参考](https://rn.nodejs.cn/docs/text)
  ¥[Text API reference](https://rn.nodejs.cn/docs/text)
* [平台特定代码](https://rn.nodejs.cn/docs/platform-specific-code)
  ¥[Platform specific code](https://rn.nodejs.cn/docs/platform-specific-code)
* [在列表中渲染数据](https://rn.nodejs.cn/docs/using-a-listview)
  ¥[Presenting data in a list](https://rn.nodejs.cn/docs/using-a-listview)
我们使用 Flexbox 来布局我们的组件。查看以下建议以了解更多信息：
¥We used Flexbox to layout our components. Check out the following recommendations to learn more about it:
* [高度和宽度](https://rn.nodejs.cn/docs/height-and-width)
  ¥[Height and Width](https://rn.nodejs.cn/docs/height-and-width)
* [使用 Flexbox 进行布局](https://rn.nodejs.cn/docs/flexbox)
  ¥[Layout with Flexbox](https://rn.nodejs.cn/docs/flexbox)
<a id="gestures-and-animations"></a>
### 手势和动画
¥Gestures and animations
要了解有关实现不同类型的手势和动画的更多信息，我们推荐以下文档：
¥To learn more about implementing different types of gestures and animations, we recommend the following documentation:
* [React Native 手势处理程序](https://docs.swmansion.com/react-native-gesture-handler/docs/)
  ¥[React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/)
* [React Native 复活](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started)
  ¥[React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started)
<a id="join-the-community"></a>
## 加入社区
¥Join the community
加入我们的 <A href="https://chat.expo.dev/" shouldLeakReferrer>Discord</A> 社区，与其他 Expo 用户聊天或提出问题。
¥Join our community on <A href="https://chat.expo.dev/" shouldLeakReferrer>Discord</A> to chat with other Expo users or to ask questions.


# EAS 教程

## EAS 教程：介绍

介绍使用 Expo 应用服务 (EAS) 构建 Android 和 iOS 应用的教程，其中涵盖构建、更新和提交工作流程。

<a id="about-this-tutorial"></a>
## 关于本教程
¥About this tutorial
本教程将帮助你熟练掌握 [Expo 应用服务（EAS）](https://expo.dev/eas) 核心服务：[构建](/build/introduction/)、[提交](/submit/introduction/) 和 [更新](/eas-update/introduction/)。完成本教程后，你将了解如何为个人和团队项目设置专业的移动持续集成 (CI)/持续开发 (CD) 管道。
¥This tutorial will give you proficiency with [Expo Application Services (EAS)](https://expo.dev/eas) core services: [Build](/build/introduction/), [Submit](/submit/introduction/), and [Update](/eas-update/introduction/). When you complete the tutorial, you will know how to set up a professional mobile Continuous Integration (CI)/Continuous Development (CD) pipeline for your individual and team projects.
本教程涵盖以下主题：
¥This tutorial covers the following topics:
* 使用 EAS Build 创建并安装开发版本，然后在设备、模拟器或模拟器上运行它。
  ¥Use EAS Build to create and install a development build, then run it on a device, emulator, or simulator.
* 体验使用开发构建而不是 Expo Go 的好处。
  ¥Experience the benefits of using a development build instead of Expo Go.
* 实现与团队或外部利益相关者共享开发构建的工作流程。
  ¥Implement workflows for sharing development builds with a team or external stakeholders.
* 自动增加应用构建版本。
  ¥Automatically increment app build versions.
* 在一台设备上同时安装不同的应用变体，例如开发版和预览版。
  ¥Simultaneously install different app variants, like development and preview, on one device.
* 利用 EAS 更新在开发阶段快速创建和部署更新。
  ¥Utilize EAS Update to create and deploy updates swiftly during the development phase.
* 通过与 GitHub 存储库集成来自动化构建过程。
  ¥Automate build processes by integrating with a GitHub repository.
这些主题将为我们提供有效使用 EAS 以及在需要时处理更高级主题所需的基础。
¥These topics will give us the foundation needed to use EAS effectively and to approach more advanced topics when needed.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
本教程是实践性的，预计在大约两个小时内完成。你将需要一个现有的 Expo 项目来跟进并在你的计算机上进行本地设置。选项包括：
¥This tutorial is hands-on and designed to be completed in about two hours. You will need an existing Expo project to follow along and set it up locally on your machine. Options include:
* 继续我们之前教程中的 Sticker Smash 应用。如果是新的，请从 [GitHub](https://github.com/expo/examples/tree/master/stickersmash) 下载。
  ¥Continuing with the Sticker Smash app from our previous tutorial. If new, download it from [GitHub](https://github.com/expo/examples/tree/master/stickersmash).
* 与 [`npx create-expo-app`](/get-started/create-a-project/) 开始一个新项目。
  ¥Starting a new project with [`npx create-expo-app`](/get-started/create-a-project/).
* 使用一个裸露的 React Native 项目。确保安装了 `expo` 软件包，你可以执行 [automatically](/bare/installing-expo-modules/) 或 [manually](/bare/installing-expo-modules/#manual-installation) 操作。
  ¥Using a bare React Native project. Ensure the `expo` package is installed, which you can do [automatically](/bare/installing-expo-modules/) or [manually](/bare/installing-expo-modules/#manual-installation).
<a id="tools"></a>
## 工具
¥Tools
[Expo 轨道](https://expo.dev/orbit) 在 macOS 和 Windows 上一键管理和启动构建。
¥[Expo Orbit](https://expo.dev/orbit) to manage and launch builds with one click on macOS and Windows.
如果你想同时在计算机上本地安装并运行构建，可以使用 Android 模拟器或 iOS 模拟器。要设置它们，请参阅以下内容：
¥If you want to install and run the build locally on your machine simultaneously, you can use Android Emulator or iOS Simulator. To set them up, see the following:
* [安卓模拟器](/workflow/android-studio-emulator/)
  ¥[Android Emulator](/workflow/android-studio-emulator/)
* [iOS 模拟器](/workflow/ios-simulator/)（仅适用于 macOS）
  ¥[iOS Simulator](/workflow/ios-simulator/) (available only on macOS)
<a id="next-step"></a>
## 下一步
¥Next step
在当地建立了 Expo 项目后，我们已经为这一旅程做好了准备。在下一章中，我们将学习如何使用 EAS Build 创建你的第一个构建。
¥We're ready for this journey after setting up an Expo project locally. In the next chapter, let's learn how to create your first build with EAS Build.


## 在云中配置开发构建

了解如何使用 EAS Build 配置项目的开发构建。

在本章中，我们将使用 EAS 为示例应用设置和配置开发构建。
¥In this chapter, we'll set up and configure a development build with EAS for our example app.
Video Tutorial: [Watch: How to configure a development build](https://www.youtube.com/watch?v=uQCE9zl3dXU)
***
<a id="understanding-development-builds"></a>
## 了解开发构建
¥Understanding development builds
让我们首先了解什么是开发构建以及为什么我们需要它们。
¥Let's start by learning about what are development builds and why we need them.
[开发构建](/develop/development-builds/introduction/) 是我们项目的调试版本。它针对创建应用时的快速迭代进行了优化。它包含 [`expo-dev-client`](/versions/latest/sdk/dev-client/) 库，提供强大且完整的开发环境。此设置允许我们根据需要集成任何原生库或更改 [原生目录](/workflow/overview/#android-and-ios-native-projects) 内的代码。
¥A [development build](/develop/development-builds/introduction/) is a debug version of our project. It is optimized for quick iterations when creating an app. It contains the [`expo-dev-client`](/versions/latest/sdk/dev-client/) library, which offers a robust and complete development environment. This setup allows us to integrate any native library or change code inside the [native directories](/workflow/overview/#android-and-ios-native-projects) as required.
<a id="key-highlights"></a>
### 主要亮点
¥Key highlights
> 注意：如果你熟悉 [Expo](/get-started/expo-go/)，可以将开发版本视为 Expo Go 的可定制版本，该版本对于项目的要求是独一无二的。
>
> ¥**Note:** If you are familiar with [Expo Go](/get-started/expo-go/), think of a development build as a customizable version of Expo Go that is unique to the requirements of a project.
| 特性         | 开发构建                                                                            | Expo                               |
| ---------- | ------------------------------------------------------------------------------- | ---------------------------------- |
| **开发阶段**   | 为移动应用开发提供类似 Web 的迭代速度。                                                          | 允许使用客户端应用快速迭代和测试 Expo SDK 项目。      |
| **合作**     | 通过共享原生运行时促进团队测试。                                                                | 通过设备上的二维码轻松共享项目。                   |
| **第三方库支持** | 完全支持任何 [第三方库](/workflow/using-libraries/#third-party-libraries)，包括那些需要自定义原生代码的。 | 仅限于 Expo SDK 内的库，不适合自定义原生依赖。       |
| **定制化**    | 使用 [配置插件](/config-plugins/introduction/) 进行广泛的定制并直接访问原生代码。                      | 有限的定制，重点关注 Expo SDK 功能，无需直接修改原生代码。 |
| **有可能的使用** | 非常适合针对商店部署的成熟应用开发，提供完整的开发环境和工具。                                                 | 非常适合学习、原型设计和实验。不建议用于生产应用。          |
Step 1: 
## Install expo-dev-client library
To initialize our project for a development build, let's [`cd`](https://web.nodejs.cn/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line#basic_built-in_terminal_commands) inside our project directory and run the following command to install the library:
```sh
$ npx expo install expo-dev-client
```
### Start the development server
Run the `npx expo start` to start the [development server](/get-started/start-developing/#start-a-development-server):
```sh
$ npx expo start
```
This command starts the metro bundler. In the terminal window, we see the QR code followed by the `Metro waiting on...` and a manifest URL:
Let's notice the changes installing the `expo-dev-client` library:
- The manifest URL contains `expo-development-client` along with the app scheme
- The development server now operates for a development build (instead of Expo Go).
Since we do not have a development build installed on one of our devices or an emulator/simulator, we can't run our project yet.
Step 2: 
## Initialize a development build
### Install EAS CLI
We need to install the EAS Command Line Interface (CLI) tool as a global dependency on our local machine. Run the following command:
```sh
$ npm install -g eas-cli
```
### Log in or sign up for an Expo account
> If you have an Expo account and are signed in using Expo CLI, skip this step. If you don't have an Expo account, [sign up here](https://expo.dev/signup) and proceed with the login command described below.
To log in, run the following command:
```sh
$ eas login
```
This command asks for our Expo account email or username and password to complete the login.
### Initialize and link the project to EAS
For any new project, the first step is to initialize and link it to the EAS servers. Run the following command:
```sh
$ eas init
```
On running, this command:
- Requests verification of the account owner by entering our Expo account credentials and asks if we want to create a new EAS project:
```sh
✔ Which account should own this project? > your-username
✔ Would you like to create a project for @your-username/sticker-smash? … yes
✔ Created @your-username/sticker-smash
✔ Project successfully linked (ID: XXXX-XX-XX-XXXX) (modified app.json)
```
- Creates EAS project and provides a link to that project which we can open in the EAS dashboard:
- Generates a unique `projectId` and links this EAS project to the example app on our development machine.
- Modifies **app.json** to include [`extra.eas.projectId`](/versions/latest/sdk/constants/#easconfig) and updates its value with the unique ID created.
Note: What is  in app.json?
---
When `eas init` runs, it associates a unique identifier for our project in **app.json** under `extra.eas.projectId`. The value of this property is used to identify our project on EAS servers.
!!!IG0!!!
---
Step 3: 
## Configure project for EAS Build
To set up our project for EAS Build, run the following command:
```sh
$ eas build:configure
```
On running, this command:
- Prompts to select a platform: **Android**, **iOS**, or **All**. Since we are creating Android and iOS apps, let's select **All**.
- Creates **eas.json** in the root of our project's directory with the following configuration:
!!!IG1!!!
This is the default configuration for **eas.json** in a new project. It does two things:
- Defines the current EAS CLI version.
- Adds three [build profiles](/build/eas-json/#build-profiles): `development`, `preview`, and `production`.
Note: Explore development profile further
---
**eas.json** is a collection of different build profiles. Each profile is tailored with distinct configurations to produce specific build types. These profiles can also include platform-specific settings for Android or iOS.
Currently, our focus is on the `development` profile, which includes the following configuration:
- [`developmentClient`](/eas/json/#developmentclient): Enabled (`true`) for creating a debug build. It loads the app using the `expo-dev-client` library, which provides development tools and generates a build artifact for device or emulator/simulator installation and allows using the app for local development as it supports updating the JavaScript on the fly.
- [`distribution`](/eas/json/#distribution): Configured as `internal` to indicate that we want to share the build internally (instead of uploading it on app stores).
> **Note**: Builds offer extensive customization options, including platform-specific settings and the ability to extend configurations across different build profiles. Learn more about [customizing build profiles](/build/eas-json/#build-profiles).
---
## Summary
<ProgressTracker
  currentChapterIndex={0}
  name="EAS_TUTORIAL"
  summary="
We successfully used the EAS CLI to initialize, and configure our project, link it to EAS servers, and prepare a development build."
  nextChapterDescription="In the next chapter, let's create a development build for Android, install it on a device and an emulator, and get it running with the development server."
  nextChapterTitle="Create and run a cloud build for Android"
  nextChapterLink="/tutorial/eas/android-development-build/"
/>


## 创建并运行 Android 云构建

了解如何使用 EAS Build 配置 Android 设备和模拟器的开发版本。

在本章中，我们将使用 EAS Build 创建一个可以在 Android 上运行的开发版本。
¥In this chapter, we'll create a development build that can run on Android with EAS Build.
在 Android 设备或模拟器上创建和运行构建的过程是相同的，只是开发构建的安装有所不同。
¥The process for creating and running a build on Android devices or emulators is identical, with differences only in the installation of the development build.
Video Tutorial: [Watch: How to create and run a cloud build for Android](https://www.youtube.com/watch?v=D612BUtvvl8)
***
<a id="create-a-build-for-the-development-profile"></a>
## 为开发配置文件创建构建
¥Create a build for the development profile
对于 Android，开发版本必须位于 .apk 中。虽然默认的 Android 格式是 .aab，非常适合 Google Play 商店分发，但它无法安装在设备或模拟器上。
¥For Android, the development build must be in the **.apk**. While the default Android format is **.aab**, which is ideal for Google Play Store distribution, it cannot be installed on devices or emulators.
要创建 .apk：
¥To create a **.apk**:
* 在 eas.json 中，确保 `build.development` 配置文件下的 `developmentClient` 设置为 `true`。
  ¥In **eas.json**, make sure that `developmentClient` is set to `true` under `build.development` profile.
* 然后，运行 `eas build` 命令，其中 `android` 作为平台，`development` 作为构建配置文件：
  ¥Then, run the `eas build` command with `android` as the platform and `development` as the build profile:
```sh
$ eas build --platform android --profile development
```
>  **info** 提示：下次运行 `eas build` 命令时，还可以使用 `-p` 来指定平台。它是 `--platform` 的缩写。
>
> ¥**Tip**: Next time you run `eas build` command, you can also use `-p` to specify the platform. It is short for `--platform`.
该命令提示我们以下问题：
¥This command prompts us with the following questions:
* 你希望你的 Android 应用 ID 是什么？按 <kbd>return</kbd> 选择为此提示提供的默认值。这将在 app.json 中添加 [`android.package`](/versions/latest/config/app/#package)。
  ¥**What would you like your Android application id to be?** Press <kbd>return</kbd> to select the default value provided for this prompt. This will add [`android.package`](/versions/latest/config/app/#package) in **app.json**.
* 生成新的 Android 密钥库？按 <kbd>Y</kbd>。
  ¥**Generate a new Android Keystore**? Press <kbd>Y</kbd>.
回复后，构建将排队，我们可以通过 EAS CLI 在 EAS 仪表板中提供的链接跟踪其进度：
¥After responding, the build will queue up, and we can track its progress via a provided link by the EAS CLI in the EAS dashboard:
Note: What information does a build details page contain?
---
The build details page displays the build type, profile, Expo SDK version, app version, version code, last commit hash, and the identity of the developer or account owner who initiated the build.
In the above image, the current status of the **Build artifact** shows that the build is in progress. Upon completion, this section will offer an option to download the build. The **Logs** outlines every step taken during the Android build process on EAS Build. For the sake of brevity, we won't explore each step in detail here. To learn more, see [Android build process](/build-reference/android-builds/).
---
Note: What is an Android application ID?
---
Also known as the package name of our Android app, it stores the value in DNS reverse notation format (`com.owner.appname`). Each component of this notation should start with a lowercase letter.
For example, our example app has `com.owner.stickersmash` where `com.owner` is the domain and `stickersmash` is our app name.
---
## Android device
Step 1: 
### Install development build
Once the build finishes, the **Build artifact** section gets updated, indicating that the build is complete:
This section provides the methods available for running the development build on an Android device: Expo Orbit and Install button.
[Expo Orbit](https://expo.dev/orbit) allows for seamless installation of the development build on an Android device. To use this method:
- Connect our Android device to our local machine using USB.
- Open the Orbit menu bar app.
- Select the **Device** in the Orbit app.
- On the EAS dashboard, under **Build artifact**, click the **Open with Orbit**.
After the build is installed, the Orbit app launches the development build on the device.
Note: Alternate: Use the Install button and QR code
---
The **Install** button in the **Build artifact** generates a QR code for installation:
- Click **Install** to display a popup with the QR code.
- Scan the QR code with our Android device's camera to open the build link in the default web browser.
- Tap the **Install** button on the webpage to download the **.apk** file.
- Once downloaded, open the **.apk** to start the installation process.
- If an **Unsafe app blocked message** appears, select **Install anyway**. This warning can safely be ignored as the source of the **.apk** (which we generated) is trusted.
---
Step 2: 
### Run development build
Start the development server by running `npx expo start` from the project directory. Once the server is running, press <kbd>a</kbd> in the terminal window to open the project:
```sh
$ npx expo start
```
## Android Emulator
Step 1: 
### Install the development build
In the terminal, once the build finishes, EAS CLI prompts us by asking whether we want to run the build on an Android Emulator. Press <kbd>Y</kbd>.
Note: Alternate: Use Expo Orbit
---
Alternatively, [Expo Orbit](/build/orbit/) can be used for installation. From **Build artifact** on the EAS dashboard, click **Open with Expo Orbit** to install the development build on the Android Emulator.
---
Step 2: 
### Run the development build
Start the development server by running `npx expo start` from the project directory. Once the server is running, press <kbd>a</kbd> in the terminal window to open the project:
```sh
$ npx expo start
```
## Summary
<ProgressTracker
  currentChapterIndex={1}
  name="EAS_TUTORIAL"
  summary={
    <>
      We successfully used EAS Build to create and run development builds on Android devices and
      emulators, and learned about <strong>.apk</strong> and <strong>.aab</strong> file formats.
    </>
  }
  nextChapterDescription="In the next chapter, learn how to configure a development build for iOS Simulators using EAS Build and get it running."
  nextChapterTitle="Create and run a cloud build for iOS Simulator"
  nextChapterLink="/tutorial/eas/ios-development-build-for-simulators/"
/>


## 为 iOS 模拟器创建并运行云构建

了解如何使用 EAS Build 配置 iOS 模拟器的开发构建。

在本章中，我们将创建一个可以使用 EAS Build 在 iOS 模拟器上运行的开发版本。
¥In this chapter, we'll create a development build that can run on an iOS Simulator with EAS Build.
iOS 模拟器的开发版本以 .app 格式生成，这与 iOS 设备不同。
¥Development builds for iOS Simulators are generated in the **.app** format which is different from iOS devices.
Video Tutorial: [Watch: Creating a development build for iOS Simulator](https://www.youtube.com/watch?v=SgL97PFZctg)
***
<a id="create-a-simulator-build-profile-in-easjson"></a>
## 在 eas.json 中创建模拟器构建配置文件
¥Create a simulator build profile in eas.json
在 eas.json 中，添加一个名为 `ios-simulator` 的新构建配置文件，其属性为 [`ios.simulator`](/eas/json/#simulator) 属性。设置其值 `true`：
¥In **eas.json**, add a new build profile called `ios-simulator` with the property [`ios.simulator`](/eas/json/#simulator) property. Set its value `true`:
```json eas.json
{
  "build": {
    "development": {
    },
    "ios-simulator": {
      "ios": {
        "simulator": true
      }
    }
  }
}
```
对于开发版本，必须在配置文件中定义 `developmentClient` 和 `distribution` 属性。为了避免冗余，我们可以扩展 `development` 配置文件属性：
¥For a development build, it's necessary to have the `developmentClient` and `distribution` properties defined in the profile. To avoid redundancy, we can extend the `development` profile properties:
```json eas.json
{
  "ios-simulator": {
    "extends": "development",
    "ios": {
      "simulator": true
    }
  }
}
```
<a id="development-build-for-ios-simulator"></a>
## iOS 模拟器的开发构建
¥Development build for iOS Simulator
Step 1: 
### Create
Run the `eas build` command with `ios` as a platform and `ios-simulator` as the build profile:
```sh
$ eas build --platform ios --profile ios-simulator
```
This command prompts us with the following questions when we create the build for the first time:
- **What would you like your iOS bundle identifier to be?** Press <kbd>return</kbd> to select the default value provided for this prompt. This will add [`ios.bundleIdentifier`](/versions/latest/config/app/#package) in **app.json**.
- **iOS app only uses standard/exempt encryption?** Press <kbd>Y</kbd> to select the default value provided for this prompt. Since our app doesn't use encryption, it sets `ITSAppUsesNonExemptEncryption` in the **Info.plist** file to `NO` and manages the compliance check for the same when you are releasing your app to TestFlight/Apple App Store. When you are releasing your own app, and it uses encryption, you can select `N` to skip this prompt next time.
After responding to the prompts, our EAS Build is queued, and the EAS CLI provides a link to view build details and track progress on the EAS dashboard:
Note: What does a build details page contain?
---
The build details page displays the build type, profile, Expo SDK version, app version, build number, last commit hash, and the identity of the developer or account owner who initiated the build.
In the above image, the current status of the **Build artifact** shows that the build is in progress. Upon completion, this section will offer an option to download the build. The **Logs** outlines every step taken during the iOS build process on EAS Build. For the sake of brevity, we won't explore each step in detail here. To learn more, see [iOS build process](/build-reference/ios-builds/).
---
Note: What is iOS bundle identifier?
---
The `ios.bundleIdentifier` is a unique name of our app. If we publish our app right now, the Apple App Store will use this property and its value to identify our app on the store.
This notation is defined as `host.owner.app-name`. For example, our example app has `com.owner.stickersmash` where `com.owner` is the domain and `stickersmash` is our app name.
---
Step 2: 
### Install
In the terminal, once the build finishes, EAS CLI prompts us by asking whether we want to run the build on an iOS Simulator. Press <kbd>Y</kbd>.
Note: Alternate: Use Expo Orbit
---
You can use [Expo Orbit](https://expo.dev/orbit) to install the development build. From **Build artifact** on the EAS dashboard, click **Open with Expo Orbit** to install the development build on the iOS Simulator.
---
Step 3: 
### Run
Start the development server by running the `npx expo start` command from the project directory:
```sh
$ npx expo start
```
Press <kbd>i</kbd> in the terminal window to open the project on the iOS Simulator.
## Summary
<ProgressTracker
  currentChapterIndex={2}
  name="EAS_TUTORIAL"
  summary="We successfully used EAS Build to create and run development builds on iOS Simulators."
  nextChapterDescription="In the next chapter, let's create a development build for iOS, install it on a device, and get it running."
  nextChapterTitle="Create and run a cloud build for iOS device"
  nextChapterLink="/tutorial/eas/ios-development-build-for-devices/"
/>


## 为 iOS 设备创建并运行云构建

了解如何使用 EAS Build 配置 iOS 设备的开发版本。

在本章中，我们将使用 EAS Build 创建一个可以在 iOS 设备上运行的开发版本。
¥In this chapter, we'll create a development build that can run on an iOS device with EAS Build.
iOS 设备的开发版本以 .ipa 格式生成，这是 iOS 应用安装的标准。
¥Development builds for iOS devices are generated in the **.ipa** format, which is standard for iOS app installations.
Video Tutorial: [Watch: Creating a development build for iOS physical device](https://www.youtube.com/watch?v=HbfWU7_o4cU)
***
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
在我们开始之前，请确保你拥有：
¥Before we begin, ensure you have:
* 苹果开发者账户：这是访问 [必要的凭证](/app-signing/app-credentials/#ios) 来签署我们的应用所必需的，因为每个构建都需要进行签名以验证应用是否来自可信来源。EAS Build 有助于管理这些凭证。
  ¥**Apple Developer Account:** This is required to access [necessary credentials](/app-signing/app-credentials/#ios) for signing our app, as each build needs to be signed to verify that the app comes from a trusted source. EAS Build helps manage these credentials.
* 在 iOS 16 及更高版本上激活开发者模式：在你的设备上安装开发版本需要启用开发者模式。如果这是你第一次或者当前已禁用，请参阅 [激活开发者模式](/guides/ios-developer-mode/) 的这些说明。
  ¥**Developer Mode activated on iOS 16 and higher:** Installing development builds on your device requires Developer Mode to be enabled. If this is your first time or if it's currently disabled, see these instructions to [activate Developer Mode](/guides/ios-developer-mode/).
<a id="provisioning-profile"></a>
## 配置文件
¥Provisioning profile
要在 iOS 设备上启动开发，我们必须：
¥To initiate development on an iOS device, we have to:
* 通过创建新的 [配置文件](/app-signing/app-credentials/#provisioning-profiles) 来注册设备。
  ¥Register the device by creating a new [provisioning profile](/app-signing/app-credentials/#provisioning-profiles).
* 下载此配置文件并将其安装到设备上。
  ¥Download and install this profile onto the device.
Step 1: 
### Register an iOS device
With EAS CLI, run the command to register a new Apple device:
```sh
$ eas device:create
```
This command prompts us with the following questions:
- **You're inside the project directory. Would you like to use the** **your-account-name** **account?** Press <kbd>Y</kbd>.
- **Apple ID.** For this step, enter your Apple ID. It will then log in to our Apple Developer account. Follow the steps in the terminal window.
- **How would you like to register your devices?** Select **Website** that generates a registration URL that can be opened on the iOS device.
> **info** **Tip**: If you or your team have multiple devices, you can share the provisioning profile link with those devices for downloading and installing the profile.
Step 2: 
### Download and install profile
On a device's web browser, open the link provided in the previous step and tap the **Download Profile button**.
Open the **Settings** app, which prompts us to register our device.
Tap **Install** to register the iOS device.
After the provisioning profile is installed, our device redirects us back to the web browser, displaying a success message indicating the completion of the process.
## Development build for iOS device
Step 1: 
### Create
To create a development build on an iOS device, make sure that under the `build.development` profile:
- The `developmentClient` is set to `true` in **eas.json**, which is done by the default configuration.
- Then, run the `eas build` command with `ios` as the platform and `development` as the build profile:
```sh
$ eas build --platform ios --profile development
```
> **info** **Tip**: Next time you run `eas build` command, you can also use `-p` to specify the platform. It is short for `--platform`.
This command prompts us with the following questions when we create the build for the first time:
- **What would you like your iOS bundle identifier to be?** Press <kbd>return</kbd> to select the default value provided for this prompt. This will add [`ios.bundleIdentifier`](/versions/latest/config/app/#package) in **app.json** if it isn't already defined.
- **Do you want to log in to your Apple account?**. Since we are creating a development build for the first time, it will ask us to **Generate a new Apple Distribution Certificate**. Press <kbd>Y</kbd> both times.
- **Select a device for ad hoc build**. This is the key part, which is why we had to register a provisioning profile before. We can select one or all of our registered devices here and then press return to install that build on those devices later.
> **info** **Only if you have skipped [iOS Simulator chapter](/tutorial/eas/ios-development-build-for-simulators/):** You'll be prompted **iOS app only uses standard/exempt encryption?** Press <kbd>Y</kbd> to select the default value provided for this prompt. Since our app doesn't use encryption, it sets `ITSAppUsesNonExemptEncryption` in the **Info.plist** file to `NO` and manages the compliance check for the same when you are releasing your app to TestFlight/Apple App Store. When you are releasing your own app, and it uses encryption, you can select `N` to skip this prompt next time.
After responding, the build will queue up, and we can track its progress via a provided link by the EAS CLI in the EAS dashboard:
Note: What does a build details page contain?
---
The build details page displays the build type, profile, Expo SDK version, app version, build number, last commit hash, and the identity of the developer or account owner who initiated the build.
In the above image, the current status of the **Build artifact** shows that the build is in progress. Upon completion, this section will offer an option to download the build. The **Logs** outlines every step taken during the iOS build process on EAS Build. For the sake of brevity, we won't explore each step in detail here. To learn more, see [iOS build process](/build-reference/ios-builds/).
---
Note: What is iOS bundle identifier?
---
The `ios.bundleIdentifier` is a unique name of our app. If we publish our app right now, the Apple App Store will use this property and its value to identify our app on the store.
This notation is defined as `host.owner.app-name`. For example, our example app has `com.owner.stickersmash` where `com.owner` is the domain and `stickersmash` is our app name.
---
Step 2: 
### Install
Once the build finishes, the Build artifact section gets updated, indicating that the build is complete:
This section provides the methods available for running the development build on an iOS device: Expo Orbit and Install button.
[Expo Orbit](https://expo.dev/orbit) allows for seamless installation of the development build on an iOS device. To use this method:
- Connect our iOS device to our developer machine using USB.
- Open the Orbit menu bar app.
- Select the **Device** in the Orbit app.
- On the EAS dashboard, under **Build artifact**, click the **Open with Orbit**.
After the build is installed, the Orbit app launches the development build on the device.
Note: Alternate: Use the Install button and QR code
---
The **Install** button in the **Build artifact** section generates a QR code for easy installation:
- Click **Install** to display a popup with the QR code.
- Scan the QR code with our iOS device's camera to open and tap the link to download the development build on the device.
---
Step 3: 
### Run
Start the development server by running the `npx expo start` command from the project directory:
```sh
$ npx expo start
```
- On the device, tap the app icon to open the development build.
- Use the account syncing feature by ensuring we're logged into both the EAS CLI and development build. As we're already logged into the EAS CLI, the next step is to log in through the UI of your development build.
- Tap **Fetch development servers** and select the server running from the list under Development servers.
## Summary
<ProgressTracker
  currentChapterIndex={3}
  name="EAS_TUTORIAL"
  summary="We successfully used EAS Build to create and run development builds on iOS devices."
  nextChapterDescription="In the next chapter, learn how to configure our app config to install multiple app variants on a single device."
  nextChapterTitle="Configure multiple app variants"
  nextChapterLink="/tutorial/eas/multiple-app-variants/"
/>


## 配置多个应用变体

了解如何配置动态应用配置以在单个设备上安装多个应用变体。

在本章中，我们将配置项目以在单个设备上同时运行多种构建类型（开发、预览、生产）。此设置将使我们能够测试应用开发的各个阶段，而无需卸载和重新安装不同的版本。
¥In this chapter, we'll configure our project to run multiple build types (development, preview, production) on a single device simultaneously. This setup will allow us to test various stages of our app development without the need to uninstall and reinstall different versions.
Video Tutorial: [Watch: How to configure multiple app variants](https://www.youtube.com/watch?v=UtJJCAfrjIg)
***
每个变体都需要唯一的 Android 应用 ID 和 iOS 打包包标识符，才能在一台设备上同时安装。以下是在 app.json 文件中设置 ID 的方式：
¥Each variant requires a unique Android Application ID and iOS Bundle Identifier to enable simultaneous installations on one device. Here's how the IDs are set up in our **app.json** file:
```json app.json
{
  "ios": {
    "bundleIdentifier": "com.yourname.stickersmash"
  },
  "android": {
    "package": "com.yourname.stickersmash"
  }
}
```
Step 1: 
## Add app.config.js for dynamic configuration
**app.json** contains app-related configuration in a JSON file. It's static and isn't ideal if we want to use [dynamic values for certain properties](/workflow/configuration/#dynamic-configuration). We're going to add different Android Application IDs and iOS Bundle Identifiers for all build profiles based on [environment variables](/workflow/configuration/#switching-configuration-based-on-the-environment).
- In the root of your project, create a new file called **app.config.js**.
- In **app.config.js**, export a default function that takes `config` as its argument. We'll then destructure the `config` to copy all existing properties from **app.json**.
!!!IG1!!!
Step 2: 
## Update dynamic values based on environment
To identify the build type, let's add two environment variables called `IS_DEV` and`IS_PREVIEW` for `development` and `preview` build profiles in **app.config.js**:
!!!IG2!!!
Then, add two functions that dynamically change the app name, Android Application ID and iOS Bundle Identifier:
!!!IG3!!!
We'll use `getAppName()` to assign dynamic `name` values for the app and `getUniqueIdentifier()` to differentiate `android.package` and `ios.bundleIdentifier` for development and preview builds:
!!!IG7!!!
!!!IG4!!!
Step 3: 
## Configure eas.json
In **eas.json**, add the `APP_VARIANT` environment variable:
!!!IG8!!!
!!!IG5!!!
Running `eas build --profile development` will now set `APP_VARIANT` to `development`.
> **Note**: Since we changed the Android Application ID and iOS Bundle Identifier, the EAS CLI will prompt us to generate a new Keystore for Android and a new provisioning profile for iOS. To learn more about what these steps include, see the previous chapter for more information.
Since our `ios-simulator` build profile extends `development`, this configuration is automatically applied for iOS Simulators.
Step 4: 
## Run development server
> After builds are complete, follow the same procedure from previous chapters to install them on a device or emulator/simulator.
Since we're identifying our development build with the `APP_VARIANT` environment variable, we need to pass it to the command when starting the development server. To do this, add a `dev` script in the [`"scripts"`](https://npm.nodejs.cn/cli/v10/using-npm/scripts) field of our project's **package.json**:
!!!IG6!!!
Run the `npm run dev` command to start the development server:
```sh
$ npm run dev
```
This script will evaluate **app.config.js** locally and load the environment variable for the `development` profile.
Now, our development build will run on both Android and iOS, displaying the modified app name from **app.config.js**. For example, the below development build is running on an iOS Simulator. See that the app name is **StickerSmash (Dev)**:
You can now continue using **app.json** for static values and use **app.config.js** for dynamic values.
## Summary
<ProgressTracker
  currentChapterIndex={4}
  name="EAS_TUTORIAL"
  summary={
    <>
      We successfully created <strong>app.config.js</strong> just for our dynamic configuration
      while leaving static configuration in **app.json** unchanged, added environment variables in{' '}
      <strong>eas.json</strong> to configure specific build profile, and learned how to start the
      development server with a custom <strong>package.json</strong> script.
    </>
  }
  nextChapterDescription="In the next chapter, learn about what are internal distribution builds, why we need them, and how to create them."
  nextChapterTitle="Create and share internal distribution build"
  nextChapterLink="/tutorial/eas/internal-distribution-builds/"
/>


## 创建并共享内部发行版本

了解内部分发构建、我们为什么需要它们以及如何创建它们。

在本章中，我们将学习如何设置 [内部分布构建](/build/internal-distribution/#internal-distribution)。
¥In this chapter, we'll learn how to set up [internal distribution builds](/build/internal-distribution/#internal-distribution).
Video Tutorial: [Watch: How to create and share an internal distribution build](https://www.youtube.com/watch?v=1fQuGLHxWks)
***
<a id="internal-distribution-build"></a>
## 内部分布构建
¥Internal distribution build
内部分发版本非常适合与团队成员共享更新，允许技术和非技术利益相关者直接提供反馈。与开发版本不同，这些版本不需要运行开发服务器，从而简化了测试过程。
¥Internal distribution builds are ideal for sharing updates with team members, allowing both technical and non-technical stakeholders to provide feedback directly. Unlike development builds, these do not require running a development server, simplifying the testing process.
<a id="ways-to-distribute-an-app-internally"></a>
### 内部分发应用的方法
¥Ways to distribute an app internally
Google 和 Apple 都提供了内部共享应用的内置机制：
¥Both Google and Apple provide built-in mechanisms for sharing apps internally:
* 安卓：使用 Google Play 测试版
  ¥**Android**: Using Google Play beta
* iOS：使用测试飞行
  ¥**iOS**: Using TestFlight
然而，这两种传统方法都有其局限性。例如，TestFlight 限制一次只能进行一个活动构建。
¥However, both of these traditional methods have their limitations. For example, TestFlight limits to one active build at a time.
<a id="eas-build-for-faster-distribution"></a>
### EAS Build 加快分发速度
¥EAS Build for faster distribution
EAS Build 加快了这一过程。它为我们的构建创建可共享的链接，并提供使用它们的说明。它有一个默认配置，旨在促进内部分发，为传统方法提供更有效的替代方案。
¥EAS Build speeds up the process. It creates shareable links for our builds and provides instructions on using them. It has a default configuration designed to facilitate internal distribution, offering a more efficient alternative to traditional methods.
<a id="create-an-internal-distribution-build"></a>
## 创建内部分发版本
¥Create an internal distribution build
要使用 EAS Build 创建和分发构建，我们需要执行以下步骤：
¥To create and distribute a build with EAS Build, we need to follow these steps:
Step 1: 
### Configure preview build profile
From our initial setup in **eas.json**, we already have a default configuration that includes a `preview` build profile designed for internal distribution:
!!!IG0!!!
This is all we need to create our first internal distribution build. The `preview` build profile from the above snippet has a `distribution` property whose value is set to `internal`. This value allows us to share our build URLs with anyone so they can install it on their device and do not require a development server to run the app.
As discussed in the previous chapters, for non-app store builds, Android requires **.apk** and iOS needs **.ipa** formats. This applies to internal distribution builds as well. The `distribution` when set to `internal`, automatically creates the app binary in these file formats for devices.
Step 2: 
### Create
Creating an internal distribution build requires [app signing credentials](/app-signing/app-credentials/).
Android app signing is non-restrictive and allows installing any compatible **.apk** file. When a development build was created, a new Android Keystore was generated for it. Hence, there is no need to generate a new keystore for preview builds.
On the other hand, Apple has stricter rules for app distribution on iOS devices. We need an ad hoc provisioning profile that explicitly lists the devices allowed to run the app. Some organizations whose apps meet specific requirements may be able to use the [Apple Developer Enterprise Program](https://developer.apple.com/programs/enterprise/) to distribute apps internally to a larger audience.
!!!IG1!!!
!!!IG2!!!
- Use the `preview` profile to initiate an Android build:
```sh
$ eas build --platform android --profile preview
```
- This command triggers the EAS Build, and on the EAS dashboard, we can see the build's progress:
!!!IG3!!!
!!!IG4!!!
Apps signed with an ad hoc provisioning profile can be installed by an iOS device whose UDID is registered with the provisioning profile.
- To register more devices, use `eas device:create`. This command registers an iOS device and gives us a URL or QR code to share for device registration:
```sh
$ eas device:create
```
- This command registers an iOS device for app installation, generating a shareable URL (or QR code) for device registration.
  > **info** **Tip**: This command enables device registration at any time. However, only builds created post-registration will work on the newly added device.
- To create the preview build, we need to use the `preview` profile with the `eas build` command:
```sh
$ eas build --platform ios --profile preview
```
- This command triggers the EAS Build, and on the EAS dashboard, we can see the build's progress:
Note: Alternative method to register devices using 
---
[`eas build:resign`](/app-signing/app-credentials/#re-signing-new-credentials) command can be used to re-sign an existing iOS **.ipa** with a new ad hoc provisioning profile, eliminating the need for a full rebuild.
---
Note: Are you setting up enterprise provisioning?
---
Apple Enterprise Program membership costs $299 USD per year and [not all organizations will be eligible](https://developer.apple.com/programs/enterprise/), so you will likely be using ad hoc provisioning, which works with any normal paid Apple Developer account.
If you have an [Apple Developer Enterprise Program membership](https://developer.apple.com/programs/enterprise/) users can install your app to their device without pre-registering their UDID. They just need to install the profile to their device and they can then access existing builds. You will need to sign in using your Apple Developer Enterprise account during the `eas build` process to set up the correct provisioning.
If you distribute your app both through enterprise provisioning and the App Store, you will need to have a distinct bundle identifier for each context. We recommend either:
- In projects generated with Expo CLI, use [**app.config.js** to dynamically switch identifiers](/tutorial/eas/multiple-app-variants/).
- In [existing React Native projects](/bare/overview/), create a separate `scheme` for each bundle identifier and specify the scheme name in separate build profiles.
---
Note: Are you using manual local credentials?
---
If so, make sure to point your **credentials.json** to an ad hoc or enterprise provisioning profile that you generate through the Apple Developer Portal (either update an existing **credentials.json** used for another type of distribution or replace it with a new one that points to the appropriate provisioning profile). Beware that EAS CLI does only a limited validation of your local credentials, and you will have to handle device UDID registration manually. Read more about [using local credentials](/app-signing/local-credentials).
---
!!!IG5!!!
!!!IG6!!!
Step 3: 
### Install
Once the build finishes, the Build artifact section gets updated, indicating that the build is complete. This section provides the methods available for running the development build on an iOS device: Expo Orbit and Install button.
- Open the build's detail page. If you are sharing the build with someone else, you can send them the link to the build. They'll be able to open the build's detail page or build artifact details which include Expo Orbit.
- Connect the Android or iOS device to our machine using USB.
- Open the Orbit menu bar app.
- Select the **Device** in the Orbit app.
- Under **Build artifact**, click the **Open with Orbit**.
Note: Alternate: Use Install and QR code
---
- Open the build's detail page. If you are sharing the build with someone else, you can send them the link to the build page. They'll be able to open it and see build artifact details which includes Expo Orbit.
- Click **Install** under the Build artifact section to display the **Install on a test device** popup.
- Copy the link from **Send a link to a device** section and send it to the test device.
---
Step 4: 
### Run
Tap the app icon on your device to start the preview build. There is no need for a development server.
Since we have already set up multiple app variants, we can see both the development and preview variants installed separately on our devices. For example:
- On Android:
- On iOS:
## Summary
<ProgressTracker
  currentChapterIndex={5}
  name="EAS_TUTORIAL"
  summary="We successfully created internal distribution builds for Android and iOS, used ad hoc provisioning for iOS, and installed multiple app variants on the same device."
  nextChapterDescription="In the next chapter, learn about developer-facing and user-facing app versions and how to manage them automatically."
  nextChapterTitle="Manage different app versions"
  nextChapterLink="/tutorial/eas/manage-app-versions/"
/>


## 管理不同的应用版本

了解面向开发者和面向用户的应用版本，以及 EAS Build 如何自动管理面向开发者的版本。

在本章中，我们将了解 EAS Build 如何自动管理面向开发者的 Android 和 iOS 应用版本。在我们在接下来的两章中深入生产构建之前，了解它将会很有用。
¥In this chapter, we'll learn how EAS Build automatically manages the developer-facing app version for Android and iOS. Learning about it will be useful before we dive into production build in the next two chapters.
Video Tutorial: [Watch: Automating app version code](https://www.youtube.com/watch?v=C8x4N9UmzS8)
***
<a id="understanding-developer-facing-and-user-facing-app-versions"></a>
## 了解面向开发者和面向用户的应用版本
¥Understanding developer-facing and user-facing app versions
应用版本由两个值组成：
¥An app version is composed of two values:
* 面向开发者的价值：Android 为 [`versionCode`](/versions/latest/config/app/#versioncode)，iOS 为 [`buildNumber`](/versions/latest/config/app/#buildnumber)。
  ¥Developer-facing value: Represented by [`versionCode`](/versions/latest/config/app/#versioncode) for Android and [`buildNumber`](/versions/latest/config/app/#buildnumber) for iOS.
* 面向用户的价值：由 [`version`](/versions/latest/config/app/#version) app.config.js 代表。
  ¥User-facing value: Represented by [`version`](/versions/latest/config/app/#version) **app.config.js**.
Google Play 商店和 Apple App Store 都依赖面向开发者的价值观来识别每个独特的版本。例如，如果我们上传的应用版本为 `1.0.0 (1)`（这是面向用户和面向开发者的值的组合），则我们无法向应用商店提交具有相同应用版本的另一个版本。提交具有重复应用版本号的版本会导致提交失败。
¥Both Google Play Store and Apple App Store rely on developer-facing values to identify each unique build. For example, if we upload an app with the app version `1.0.0 (1)` (which is a combination of user-facing and developer-facing values), we cannot submit another build to the app stores with the same app version. Submitting builds with duplicate app version numbers results in a failed submission.
下面通过 app.config.js 中的 `android.versionCode` 和 `ios.buildNumber` 显示了手动管理面向开发者的值的示例演示。我们不必手动添加或管理这些值，因为 EAS Build 会为我们自动执行此操作。
¥An example demonstration of manually managing developer-facing values is shown below by `android.versionCode` and `ios.buildNumber` in **app.config.js**. **We don't have to add or manage these values manually since EAS Build automates this for us**.
```js app.config.js
{
  ios: {
    buildNumber: 1
  },
  android: {
    versionCode: 1
  }
}
```
> 注意：[面向用户的版本号](/build-reference/app-versions/#user-facing-version) 不由 EAS 处理。相反，我们在提交生产应用以供审核之前在应用商店开发者门户中进行定义。
>
> ¥**Note**: The [user-facing version number](/build-reference/app-versions/#user-facing-version) is not handled by EAS. Instead, we define that in the app store developer portals before submitting our production app for review.
<a id="automatic-app-version-management-with-eas-build"></a>
## 使用 EAS Build 自动管理应用版本
¥Automatic app version management with EAS Build
默认情况下，EAS Build 协助自动化面向开发者的值。它利用 [远程版本源](/build-reference/app-versions/#remote-version-source) 在发布新的生产版本时自动增加面向开发者的值。
¥By default, EAS Build assists in automating developer-facing values. It utilizes the [remote version source](/build-reference/app-versions/#remote-version-source) to automatically increment developer-facing values whenever a new production release is made.
当我们使用 `eas init` 命令初始化项目时，EAS CLI 会自动在 eas.json 中添加以下属性：
¥When we initialized the project with `eas init` command, the EAS CLI automatically added the following properties in **eas.json**:
* `cli.appVersionSource` 设置为 `remote`
  ¥`cli.appVersionSource` which is set to `remote`
* [`build.production.autoIncrement`](/eas/json/#autoincrement-1) 设置为 `true`
  ¥[`build.production.autoIncrement`](/eas/json/#autoincrement-1) which is set to `true`
你可以在项目的 eas.json 中查看它们：
¥You can view them in your project's **eas.json**:
```json eas.json
{
  "cli": {
    "appVersionSource": "remote"
  },
  "build": {
    "production": {
      "autoIncrement": true
    }
  }
}
```
当我们在接下来的两章中创建新的生产版本时，Android 的 `versionCode` 和 iOS 的 `buildNumber` 将自动递增。
¥When we create a new production build in the next two chapters, the `versionCode` for Android and `buildNumber` for iOS will increment automatically.
Note: Syncing developer-facing app versions for already published apps to EAS
---
If your app is already published in the app stores, the developer-facing app versions are already set. When migrating this app to use EAS Build, follow the steps below to sync those app versions:
- In the terminal window, run the `eas build:version:set` command:
```sh
$ eas build:version:set
```
- Select the platform (Android or iOS) when prompted.
- When prompted **Do you want to set app version source to remote now?**, select **yes**. This will set the `cli.appVersionSource` to `remote` in **eas.json**.
- When prompted **What version would you like to initialize it with?**, enter the last version number that you have set in the app stores.
After these steps, the app versions will be synced to EAS Build remotely. You can set `build.production.autoIncrement` to `true` in **eas.json**. When you create a new production build, the `versionCode` and `buildNumber` will be automatically incremented from now on.
---
## Summary
<ProgressTracker
  currentChapterIndex={6}
  name="EAS_TUTORIAL"
  summary={
    <>
      We successfully explored app versioning differences, addressed the importance of unique app
      versions to prevent store rejections, and enabled automated version updates in{' '}
      <strong>eas.json</strong> for production builds.
    </>
  }
  nextChapterDescription="In the next chapter, learn about the process of creating a production build for Android."
  nextChapterTitle="Create a production build for Android"
  nextChapterLink="/tutorial/eas/android-production-build/"
/>


## 为 Android 创建生产版本

了解为 Android 创建生产版本和自动化发布过程的过程。

在本章中，我们将创建示例应用的生产版本并将其提交到 Google Play 商店。我们还将探索如何自动创建和发布新的应用版本。
¥In this chapter, we'll create our example app's production version and submit it to the Google Play Store. We'll also explore how to automate the creation and release of new app versions.
Video Tutorial: [Watch: Creating and releasing a production build for Android](https://www.youtube.com/watch?v=nxlt8uwqhpE)
***
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
要在 Google Play 商店上发布和分发应用，我们需要：
¥To publish and distribute an app on the Google Play Store, we need:
* Google Play 开发者账户：必须有付费开发者账户。有关设置的详细信息，请访问 [Google Play 注册页面](https://play.google.com/apps/publish/signup/)。
  ¥**Google Play Developer Account:** Must have a paid developer account. For details on setting one up, visit the [Google Play sign-up page](https://play.google.com/apps/publish/signup/).
* Google 服务账户密钥：我们需要 Google 服务账户电子邮件和 JSON 密钥来自动执行应用提交过程。请按照 [创建 Google 服务账户密钥或从现有账户下载](https://expo.fyi/creating-google-service-account) 指南中的详细说明进行操作，然后返回到本指南。这是可选的，但对于 [自动化发布过程](#automated-release) 是必需的。
  ¥**Google Service Account key:** We'll need a Google Service Account email and JSON key to automate the app submission process. **Follow the detailed instructions in our guide on [creating a Google Service Account key or downloading it from an existing account ](https://expo.fyi/creating-google-service-account), then return to this guide.** This is optional but required for [automating the release process](#automated-release).
* 生产构建简介：确保你的 eas.json 中存在 `production` 构建配置文件，该配置文件是默认添加的。
  ¥**Production build profile:** Ensure that a `production` build profile is present in your **eas.json**, which is added by default.
<a id="production-build-for-android"></a>
## Android 的生产版本
¥Production build for Android
[生产 Android 构建](/build/eas-json/#production-builds) 具有 .aab 格式，该格式针对在 Google Play 商店上的分发进行了优化。与 .apk 构建不同，.aab 文件只能通过 Google Play 商店分发和安装。
¥A [production Android build](/build/eas-json/#production-builds) has a **.aab** format which is optimized for distribution on the Google Play Store. Unlike **.apk** builds, **.aab** files can only be distributed and installed through the Google Play Store.
Step 1: 
## Create a production build
To create an Android production build using the default `production` profile, open your terminal and execute the following command. Since `production` is set as the default profile in the EAS configuration, there is no need to specify it explicitly with the `--profile` flag.
```sh
$ eas build --platform android
```
The above command will queue the build. Notice in the EAS dashboard that the **Version Code** is auto-incremented.
Step 2: 
## Create an app on the Google Play Console
To upload the app to the Google Play Store for the first time, we need to:
- Go to the Google Play dashboard.
- On the **Home** page, click **Create app** to make a new app.
- Fill out our app details and click the **Create app** button.
Step 3: 
## Release an internal testing version
After the app is created on Google Play Console, it redirects us to the app's Dashboard screen. We need to prepare an internal test version of our app.
- Click **Start testing now** on the **Dashboard**.
- Create an email list of users under **Internal Testing** > **Testers for the internal testing release**.
- Google Play Console prompts us to create a **Release**.
- To create a new release, go to **Releases** and click **Create new release**.
- To store the signing key, go to **App integrity** > **App bundles** and click **Choose signing key** > **Use Google-generated key**.
Step 4: 
## Upload the app binary
After EAS has created a production build:
- Open the EAS dashboard and click on **Download** to get the **.aab** file.
- Return to the Google Play Console and go to **App bundles**. Click on **Upload** to add the **.aab**.
- Provide the release details for our app and click on **Next**.
- On the following screen, click on **Save and publish**.
Step 5: 
## Share the internal release version
Under **Track Summary**, we see that the latest release shows a temporary app name. This is because our app is not reviewed yet.
Under **Releases**, we see that the app is available to internal testers. To share the app with a team of testers:
- Open the Internal testing dashboard, then click on **View release details**.
- Click on **copy link** under **How testers join your test**.
- On the device, open the test email and follow the steps to download the app.
- The testing email holder needs to accept the invite, and once accepted, the app can be installed on the device.
> **info** **Tip**: To publish an app on the Play Store, in the Google Dashboard, finish the steps under **Set up your app**. These steps are required before releasing the app on the Play Store for the first time. You'll have to provide details like a link to a privacy policy, a target audience, data safety and so on.
> **Complete app store listing**: To prepare the app for store listing, see [Create app store assets](/guides/store-assets/) on how to create screenshots and previews.
Note: Promoting a testing release
---
To promote our internal test release version to **alpha**, in Google Play Store Console:
- Go to internal testing and click **Promote release**.
- Open the dropdown menu and click **Closes testing** > **Closed testing - Alpha**.
---
Step 6: 
## Add Google Service Account permissions key
> **info** **Tip**: Before following the steps in this section, see the instructions on [creating a Google Service Account key or downloading it from an existing account ](https://expo.fyi/creating-google-service-account) guide.
From now on, we can use [EAS Submit](/submit/introduction/) to automate releases and avoid the manual process. To do that, we need to add the service account key to our project's **eas.json**.
After following the Google Service Account guide steps, we can use the downloaded JSON key:
- Open our project and copy the JSON file from the Google Service Account to the project's root directory.
- To secure sensitive data, ensure this file is excluded from version control by listing it in our **.gitignore**.
Step 7: 
## Internal release
Let's add the path to the Google Service Account file path in **eas.json**.
- Under `submit.production` profile, add `android.serviceAccountKeyPath` and the relative file path as its value:
!!!IG2!!!
!!!IG0!!!
In the above snippet, we're also adding [`track`](/eas/json/#track) property and setting its value to `internal`. This will enable the `eas submit` command to upload our production build and release it for internal testing on the Google Play Store.
- Now run the `eas submit` command to release a new internal testing version:
```sh
$ eas submit --platform android
```
- This command will automatically create a new internal release version in Google Play Console:
Step 8: 
## Production release
To release the app for production:
- Change the value for `track` to `production` in **eas.json**:
!!!IG1!!!
- We can also use the same EAS Build we did for the internal testing release. Run the `eas submit` command to release to the Play Store:
```sh
$ eas submit --platform android
```
- To create a track and submit our app to the Google Play Store's review process, we need to **Release** > **Production** and under **Releases**, select the build we want to send for review.
Step 9: 
## Automated release
For subsequent releases in future, we can streamline the process by combining build creation and Play Store submission into a single step by using the [`--auto-submit`](/build/automate-submissions/) flag with `eas build`:
```sh
$ eas build --platform android --auto-submit
```
## Summary
<ProgressTracker
  currentChapterIndex={7}
  name="EAS_TUTORIAL"
  summary={
    <>
      We successfully created a production-ready Android build, discussed manual and automated
      uploading to Google Play Store using , and automated the release
      process with the .
    </>
  }
  nextChapterDescription="
In the next chapter, learn about the process of creating a production build for iOS."
  nextChapterTitle="Create a production build for iOS"
  nextChapterLink="/tutorial/eas/ios-production-build/"
/>


## 为 iOS 创建生产版本

了解为 iOS 创建生产版本和自动化发布过程的过程。

在本章中，我们将创建示例应用的生产版本并提交它以使用 TestFlight 进行测试。之后，我们将提交它们进行 App Store 审核，以将其上架 App Store。
¥In this chapter, we'll create our example app's production version and submit it for testing using TestFlight. After that, we'll submit them for App Store review to get it on the App Store.
Video Tutorial: [Watch: Creating and releasing a production build for iOS](https://www.youtube.com/watch?v=VZL_e0cEwo8)
***
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
要在 Apple Play Store 上发布和分发应用，我们需要：
¥To publish and distribute an app on the Apple Play Store, we need:
* 苹果开发者账户：要创建一个，请参阅 [苹果开发者门户](https://developer.apple.com/account/)。
  ¥**Apple Developer account:** To create one, see [Apple Developer Portal](https://developer.apple.com/account/).
* 生产构建简介：确保你的 eas.json 中存在 `production` 构建配置文件，该配置文件是默认添加的。
  ¥**Production build profile:** Ensure that a `production` build profile is present in your **eas.json**, which is added by default.
<a id="production-build-for-ios"></a>
## iOS 的生产版本
¥Production build for iOS
[生产 iOS 构建](/build/eas-json/#production-builds) 针对 Apple 的 App Store Connect 进行了优化，允许通过 App Store 将构建版本分发给 TestFlight 测试人员和公共终端用户。此构建类型无法在模拟器或设备上旁加载，只能通过 App Store Connect 进行分发。
¥A [production iOS build](/build/eas-json/#production-builds) is optimized for Apple's App Store Connect, which allows distributing builds to testers with TestFlight and public end users through the App Store. This build type cannot be side-loaded on a simulator or device and can only be distributed through App Store Connect.
Step 1: 
## Create a distribution provisioning profile
Run the `eas credentials` command in the terminal and then answer the following prompts by EAS CLI:
- **Select platform** iOS.
- **Which build profile do you want to configure?** Select production.
- **Do you want to log in to your Apple account?** Press <kbd>Y</kbd>. This will log in to our Apple Developer account.
- **What do you want to do?** Select **Build credentials** and choose **All: Set up all the required credentials to build your project**.
- Now, it will prompt whether we want to re-use the previous Distribution Certificate. Press <kbd>Y</kbd>.
- **Generate a new Apple Provisioning Profile?** Press <kbd>Y</kbd>. This will be the provisioning profile for the production app.
- Once the profiles are created, press any <kbd>ctrl</kbd> + <kbd>c</kbd> to exit the EAS CLI.
Step 2: 
## Create a production build
To create an iOS production build using the default `production` profile, open your terminal and execute the following command. Since `production` is set as the default profile in the EAS configuration, there is no need to specify it explicitly with the `--profile` flag.
```sh
$ eas build --platform ios
```
The command will queue the build. Notice on the EAS dashboard that the **Build Number** is auto-incremented.
Step 3: 
## Submit the app binary to the App Store
To submit the app binary created from our latest EAS Build, run the [`eas submit`](/submit/introduction/) command:
```sh
$ eas submit --platform ios
```
After running this command, we need to:
- **Select a build from EAS.** Let's select the latest build ID.
- **Follow the prompt to log in to our Apple account.** When it asks for **Reuse this App Store Connect API Key?** Press <kbd>Y</kbd>.
This will trigger the submission process.
Step 4: 
## Release an internal testing version
After the submission process is complete, we'll need to log in to the Apple Developer account from the web browser.
- Click **[Apps](https://appstoreconnect.apple.com/apps),** and see the app icon.
- Click the app name, and from the navigation tab menu, click **TestFlight**. If the build was just submitted, it may take a few minutes for Apple to process the build before it is available to distribute with TestFlight.
> **info** **Only if you have skipped [iOS development build for devices chapter](/tutorial/eas/ios-development-build-for-devices/):** You'll be prompted **iOS app only uses standard/exempt encryption?** Press <kbd>Y</kbd> to select the default value provided for this prompt. Since our app doesn't use encryption, it sets `ITSAppUsesNonExemptEncryption` in the **Info.plist** file to `NO` and manages the compliance check for the same when you are releasing your app to TestFlight/Apple App Store. When you are releasing your own app, and it uses encryption, you can select `N` to skip this prompt next time.
- In App Store Connect, under **Internal Testing**, and create a test group. This will allow us to invite test users.
- Once the group is created, an email will be sent to all the test users.
- In the email, click **View in TestFlight,** accept the invite, and then tap **Install**.
After that, the app will download on our device so that we can test it.
> **Note**: Similar to internal testing, we can also create a group for inviting external testers using TestFlight. Where internal testing has a limit of 100 users, TestFlight allows sharing a test release version externally with up to 10,000 testers and provides a publicly shareable link. For brevity, we are not going to cover those steps in this tutorial.
Step 5: 
## Submit the app to the Apple App Store
To prepare our app for App Store submission, go to the **App Store** tab:
- Provide metadata details, provide screenshots as per Apple's guidelines and also fill details under **General**.
- Then, manually select the build.
> **Complete App Store listing**: To prepare the app for store listing, see [Create app store assets](/guides/store-assets/) on how to create screenshots and previews.
- Once our app is ready, click on **Submit to App Review**. After that, Apple will review our app, and if approved, the app will be available on the App Store.
Step 6: 
## Automated submissions
For future releases, we can streamline the process by combining build creation and App Store submission into a single step by using the [`--auto-submit`](/build/automate-submissions/) flag with `eas build`:
```sh
$ eas build --platform ios --auto-submit
```
> **Note:** This command will automatically upload your build to TestFlight for internal testing, but it will not automatically submit your app for App Store review. You'll still need to manually promote the build from TestFlight to the App Store when you're ready for public release. For more information, see [Default submission behavior for app stores](/build/automate-submissions/#default-submission-behavior-for-app-stores).
## Summary
<ProgressTracker
  currentChapterIndex={8}
  name="EAS_TUTORIAL"
  summary={
    <>
      We successfully created a production-ready iOS build, discussed distribution using TestFlight
      and Apple App Store using , and automated the release process with the{' '}
      .
    </>
  }
  nextChapterDescription="In the next chapter, learn how to use the EAS Update to send OTA updates and share previews with our team."
  nextChapterTitle="Share previews with your team"
  nextChapterLink="/tutorial/eas/team-development/"
/>


## 与你的团队分享预览

了解如何使用 EAS Update 发送 OTA 更新并与团队共享预览。

更新通常会修复小错误并在应用商店版本之间推送小更改。它们允许更新示例应用的非原生部分，例如 JavaScript 代码、样式和图片。
¥Updates generally fix small bugs and push small changes in between app store releases. They allow updating the non-native parts of our example app, such as JavaScript code, styling, and images.
在本章中，我们将使用 [EAS 更新](/eas-update/introduction/) 与我们的团队共享更改。这将有助于 [我们和我们的团队快速分享预览](/review/overview/) 的改变。
¥In this chapter, we'll use [EAS Update](/eas-update/introduction/) to share changes with our team. This will help [us and our team quickly share previews](/review/overview/) of the change.
Video Tutorial: [Watch: How to share previews with your team](https://www.youtube.com/watch?v=vPKh-tNm-yI)
***
Step 1: 
## Install expo-updates library
To initialize our project and send an update, we need to use the [`expo-updates`](/versions/latest/sdk/updates/) library. Run the following command to install it:
```sh
$ npx expo install expo-updates
```
Step 2: 
## Configure EAS Update
To initialize our project with EAS Update, we need to follow these steps:
- Since we are using dynamic **app.config.js** for our app's configuration, adding [`updates`](/versions/latest/config/app/#updates) and [`runtimeVersion`](/eas-update/runtime-versions/#setting-runtimeversion) properties are required to make our project compatible with EAS Update. Run the following command to obtain these properties and their values from EAS and manually copy them to **app.config.js**:
```sh
$ eas update:configure
```
Note: What about non-dynamic (app.json) projects?
---
If a project doesn't use dynamic app config (uses **app.json** instead of **app.config.js**), the above command will configure our app to be compatible with EAS Update and add the right properties to **app.json** and **eas.json**.
---
- Re-run `eas update:configure` to continue with the setup process. A [`channel`](/eas/json/#channel) should be added to every build profile in **eas.json**:
!!!IG2!!!
!!!IG0!!!
> **info** Notice that the `eas update:configure` command adds the `channel` to every build profile in **eas.json**. However, our `ios-simulator` profile extends the `development` profile and having a separate `channel` doesn't make sense. We can safely remove `ios-simulator.channel` from the above configuration.
Note: What is a channel?
---
[Channels](/eas-update/how-it-works/#conceptual-overview) are used to group builds together. If we have an Android and iOS build, both on the app store, we can give them both a channel of production. Later, we can tell EAS Update to target the production channel, so our update will affect all builds with a production channel.
---
Step 3: 
## Create a development build
We need to create a new development build since our last build doesn't contain the `expo-updates` library. Run the following command:
```sh
$ eas build --platform android --profile development
```
> We are using a development build for Android devices to demonstrate updates. However, we can use `--platform all` or `--platform ios` to create a build for both platforms or just for iOS.
After the new version of the development build is created, make sure to install it on a device.
Step 4: 
## Modify the JavaScript code of the app
Let's modify our example app's JavaScript code. If you are not using [Sticker Smash app](/tutorial/eas/introduction/#prerequisites), you can modify any piece of your code to see the changes in the app.
We'll modify the text of the first button in our example app that says **Choose a photo** to **Select a photo**.
!!!IG1!!!
Step 5: 
## Publish an update
Instead of creating a new build to share this change with our team for testing, let's publish an update:
```sh
$ eas update --channel development --message "Change first button label"
```
In the command above, we used the `development` channel. Every update is associated with a [channel name]](/eas-update/how-it-works/#publishing-an-update). It is similar to every commit that we make with git, which is associated with a git branch.
So, by using the channel `development` in our build profile and then publishing an, we're asking EAS to deliver this update to builds with the `development` channel. When we make an EAS Update channel it automatically gets mapped to a branch with the same name.
After the update is published, the CLI will prompt us with information about it.
Click on the **Website link** to see the Update on the EAS dashboard under **Updates**:
Step 6: 
## Preview the update live in a development build
To preview the live update in a development build:
- Log in to your Expo account within the development build.
- Open the **Extensions** tab.
- Look for **Branch: development** listed under **EAS Update**.
- Tap on **Open** to access the update.
Step 7: 
## Sharing changes with preview or production builds
Updates for non-development builds (preview or production) are automatically downloaded to the device when the app starts up and makes a request for any new updates.
Any team member running the preview or production build will receive the update with the changes we push to those specific branches.
For example, for a `preview` build, we can run:
```sh
$ eas update --channel preview --message "Change first button label"
```
Here is an example where we've published an update for the `preview` build. To test the update, force close and reopen the app twice to download and view the changes:
## Summary
<ProgressTracker
  currentChapterIndex={9}
  name="EAS_TUTORIAL"
  summary="We successfully configured  EAS Update to manage and publish over-the-air updates across platforms, and explored methods to fetch updates to review."
  nextChapterDescription="In the next chapter, learn about the process of triggering builds from a GitHub repository."
  nextChapterTitle="Trigger builds from a GitHub repository"
  nextChapterLink="/tutorial/eas/using-github/"
/>


## 从 GitHub 存储库触发构建

了解从 GitHub 存储库触发构建的过程。

[Expo GitHub 应用](/build/building-from-github/) 使用 EAS 自动触发我们的 GitHub 项目的构建。我们可以根据我们的开发团队的偏好触发任何构建配置文件的构建。它还允许触发直接提交到存储库或拉取请求的 `git` 推送的构建。
¥[Expo GitHub App](/build/building-from-github/) automatically triggers builds from our GitHub projects with EAS. We can trigger builds for any build profile based on our development team's preferences. It also allows triggering builds for `git` push committed directly to a repository or a pull request.
在本章中，我们将配置此功能。我们已经为示例应用提供了一个 GitHub 存储库来演示这一点。
¥In this chapter, we'll configure this functionality. We already have a GitHub repository for our example app to demonstrate this.
Video Tutorial: [Watch: How to trigger builds from a GitHub repository](https://www.youtube.com/watch?v=fBLFEFC0ip0)
***
Step 1: 
## Configure Expo GitHub app
To use this functionality, we need to connect our GitHub account:
- In the EAS dashboard, go to [expo.dev/settings](https://expo.dev/settings#connections), and under **Connections** > **GitHub**, click **Connect**. This opens the **Connect GitHub** accounts page.
- Click the **Get started** button which opens a popup to authorize the Expo GitHub app. Click **Install and Authorize**.
- Once the app is installed on our GitHub account, we need to link it to our Expo account. In the next popup, click **Link installation**.
- Once the account is linked, it will show under **GitHub**.
Step 2: 
## Connect the GitHub repository
To enable triggering builds from a GitHub repository, we need to connect it to our project in the EAS dashboard:
- In EAS dashboard, go to **Projects** > Select your project > **Project settings** > **GitHub**.
- Under **Connect a GitHub repository**, we'll see a list of our GitHub repos. We need to connect the right one. In the example, we're searching for our repo **sticker-smash.**
- Click **Connect** for the project repository.
Step 3: 
## Use default repository settings
The Expo GitHub app needs to know where to find the source code of our project. By default, it selects the root directory using `/`. In our example project, the source code is also available in the root repository. We can leave this to default in the EAS dashboard.
Step 4: 
## Trigger a build using a GitHub PR label
The Expo GitHub app provides us [multiple options](/build/building-from-github/#trigger-a-build-from-github) to trigger a build, such as:
- Manually from the Builds page for a specific platform
- Automatically when new code is pushed to the repository
- Automatically using GitHub PR labels
To automatically trigger a build using a GitHub PR label, we're going to utilize the third option from the list above:
- We need to specify the build image that we will be using. Open **eas.json**, and under the `development` profile, add [`android.image`](/eas/json/#image) and [`ios.image`](/eas/json/#image-1) properties and set their value to [`latest`](/build-reference/infrastructure/#configuring-build-environment).
!!!IG0!!!
- Next, let's create a new branch called `dev`, and make a change in our app's JavaScript code. Then, commit the change, push the branch, and create a PR from that branch.
- In the PR link, under **Labels**, create a label called `eas-build-all:development`.
- Click **Create pull request** button to create the PR. The Expo GitHub app will start the process of creating a development build.
- In the EAS dashboard, on the **Builds** page, we can verify that the builds for both Android and iOS are triggered.
- If we check the details of an individual build, we can see under **Created by** that the build is created by the GitHub app.
## Summary
<ProgressTracker
  currentChapterIndex={10}
  name="EAS_TUTORIAL"
  summary="We successfully linked our GitHub account with Expo, connected our repository to our EAS project, and learned about automated development build creation using GitHub PR labels."
  nextChapterDescription="Learn about the next steps to use EAS."
  nextChapterTitle="Next steps in your journey with EAS"
  nextChapterLink="/tutorial/eas/next-steps/"
/>


## 下一步

了解 EAS 之旅的后续步骤。

恭喜！你已完成 EAS 教程并了解主要功能。现在，你已经有了一个可以工作的 [EAS 项目](https://expo.dev/eas)。
¥Congratulations! You've completed the EAS tutorial and learned about the main features. Now, you have a working [EAS project](https://expo.dev/eas).
<a id="eas"></a>
## EAS
但这仅仅是开始。以下是继续你的 EAS 之旅的一些后续步骤：
¥But this is just the beginning. Here are some next steps to continue your journey with EAS:
  }
  href="/eas-insights/introduction/"
/>
<a id="easjson-reference"></a>
## eas.json 参考
¥eas.json reference
<a id="custom-builds"></a>
## 定制构建
¥Custom builds
<a id="relevant-guides"></a>
## 相关指南
¥Relevant guides
我们希望你喜欢本课程。如果你有任何问题或反馈，请随时通过 [Discord](https://chat.expo.dev/) 与我们联系，或在 [X](https://x.com/expo) 上分享你的经验。
¥We hope you enjoyed this course. If you have any questions or feedback, don't hesitate to reach out to us on [Discord](https://chat.expo.dev/), or share your experience on [X](https://x.com/expo).


# 更多

## 其他资源

## 指南：概述

本节包含有关使用 Expo 和 Expo 应用服务 (EAS) 进行开发的信息：
¥This section contains information about the development with Expo and Expo Application Services (EAS):
### <span className="inline-flex items-center gap-2"><CodeSquare01Icon />开发流程</span
了解 [使用 Expo 构建应用](/workflow/overview/) 的流程，有助于理解核心开发循环的心智模型。本节还深入介绍你在开发过程中可能需要的其他配置和工作流程，以帮助你开发、部署和维护应用。它包含有关 [应用配置](/workflow/configuration/)、[permissions](/guides/permissions/)、[通用链接](/linking/into-your-app/)、[自定义原生代码](/workflow/continuous-native-generation/)、[web](/workflow/web/) 等的深入信息。
¥Learn about the process of [building an app with Expo](/workflow/overview/) to help understand the mental model of the core development loop. This section also dives into additional configurations and workflows you may require during the development process to help you develop, deploy, and maintain your app. It contains in-depth information about [app config](/workflow/configuration/), [permissions](/guides/permissions/), [universal links](/linking/into-your-app/), [custom native code](/workflow/continuous-native-generation/), [web](/workflow/web/), and more.
### <span className="inline-flex items-center gap-2"><RouterLogo />Expo 路由</span
了解如何使用 [Expo 路由](/router/basics/layout/#root-layout) 库中的不同导航功能。它还涵盖了该库提供的全面的 [钩子 API](/router/reference/hooks/) 以及导航的其他方面，例如 [验证](/router/reference/authentication/)、[重定向](/router/reference/redirects/)、[测试](/router/reference/testing/) 等。
¥Learn about using different navigation functionalities from the [Expo Router](/router/basics/layout/#root-layout) library. It also covers a comprehensive [Hooks API](/router/reference/hooks/) that the library provides and other aspects of navigation such as [Authentication](/router/reference/authentication/), [Redirects](/router/reference/redirects/), [Testing](/router/reference/testing/), and more.
### <span className="inline-flex items-center gap-2"><CpuChip01Icon />Expo 模块 API</span
了解如何使用 [Expo 模块 API](/modules/overview/) 在你的应用中添加和使用原生模块。
¥Learn how to add and use Native modules in your app using [Expo Modules API](/modules/overview/).
<a id="other-content"></a>
### 其他内容
¥Other content
除了上面列出的基本功能外，还有许多其他功能可供探索，例如 [推送通知](/push-notifications/overview/)。我们还在分类和第三方集成部分提供了一系列指南。
¥Apart from the essentials listed above, there are plenty of other features to explore such as [Push notifications](/push-notifications/overview/). We also have a collection of guides in the **Assorted** and third-party **Integrations** sections.


# 开发流程

## 使用 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.
<a id="key-concepts"></a>
## 关键概念
¥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.
<Collapsible summary={`What is an "Expo app"?`}>
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.
We say "Expo app" because _React Native app that uses Expo tools_ is incredibly inconvenient to frequently type and speak out loud.
<Collapsible summary={<>Is the development process different for an "Expo app" and a "React Native app that does <span><i>not</i></span> use Expo tools"?</>}>
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.
---
---
<Collapsible summary={`What is the difference between "Expo" and "Expo Application Services (EAS)"?`}>
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 Application Services (EAS) is a suite of hosted services that you can use with Expo and React Native projects to:
- Build, submit, and update your app
- Set up automation around all of these processes
- Collaborate with your team
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](https://expo.dev/pricing#get-started) that will work for many student and hobby projects.
You don't have to use GitHub to use git, but it certainly helps for many cases. The same goes for EAS and Expo.
Note: Do I have to use EAS if I use Expo open source tools?
---
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.
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](/versions/latest/sdk/updates/) (rather than using EAS Update), or [running builds locally](/guides/local-app-development/) or on [your own CI](build/building-on-ci/) (rather than using our EAS Build worker fleet).
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 &mdash; which ties back into monitoring with [EAS Insights](/eas-insights/introduction/).
---
Note: Can I use EAS if I'm not using any Expo open source tools?
---
Yes! We think EAS is a great fit for any React Native project.
---
---
Note: Expo Go: an optional tool for learning, experimenting, and prototyping
---
There's no faster way to spin up a React Native project and run it on your device or emulator than [Expo Go](https://expo.dev/go), especially when combined with [Snack](https://snack.expo.dev/).
However, **Expo Go and Snack are not intended for building production apps**. They are great when you're getting started on a project or for prototypes. **If you plan on deploying your app to the store, then [development builds](#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.
---
Note: Development builds
---
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](#android-and-ios-native-projects) using [app config](/workflow/configuration/) or by creating a [config plugin](/config-plugins/introduction/). You can create a development build [locally](/guides/local-app-development/#local-builds-with-expo-dev-client) or use [EAS Build](/develop/development-builds/create-a-build/) to create a build in the cloud.
---
Note: Android and iOS native projects
---
React Native apps for mobile platforms are made of two interconnected parts:
Note: 1. The 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.
---
Note: 2. The native projects
---
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.
---
Like any mobile app, the application that is distributed to users is created by compiling ("building") the Android Studio or Xcode project.
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`](/workflow/prebuild/), which will initialize the native projects and then apply the project Expo app config (**app.json/app.config.js**) to them.
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](#cloud-based-and-local-development-workflows).
<Collapsible summary={`Why aren't the native projects created by default when you initialize a project with create-expo-app?`}>
The default behavior encourages the use of [Continuous Native Generation](/workflow/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:
```sh
$ 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
```
---
---
Note: Continuous Native Generation (CNG)
---
Continuous Native Generation (CNG) is a process for building an Expo app where your [native projects](#android-and-ios-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**.
You can add the [native project](#android-and-ios-native-projects) directories (**android** and **ios**) to your **.gitignore** and/or delete the project 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.
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](https://github.com/bndkt/react-native-app-clip), [share extensions](https://github.com/timedtext/expo-config-plugin-ios-share-extension), and [push notifications](https://github.com/OneSignal/onesignal-expo-plugin). This is all made possible with [config plugins](/config-plugins/introduction/). Learn more about [CNG](/workflow/continuous-native-generation/).
Note: What if I want to edit the native project configuration in Android Studio or Xcode rather than generating the projects with prebuild?
---
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.
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 &mdash; running prebuild after making native changes directly will overwrite all of those modifications.
Note that you can use [config plugins](/config-plugins/introduction/) 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.
---
Note: How do I know when I need to run prebuild again?
---
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](/workflow/using-libraries/#determining-third-party-library-compatibility) for more information on how to determine if a new dependency requires native code changes.
---
---
Note: Cloud-based and local development workflows
---
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.
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](/build/introduction/).
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.
Learn more about [cloud-based workflows with EAS Build](/build/introduction/) and [local development](/guides/local-app-development/).
---
## Initialize and run a project
The easiest way to [create a new project is with `create-expo-app`](/get-started/create-a-project/). 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.
In most cases, you will create and use a development build of your project. You will install the [`expo-dev-client`](/develop/development-builds/introduction/#what-is-expo-dev-client) library. Development builds can be created with EAS Build or locally on your machine:
## The core development loop
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.
- #### Write and run JavaScript code
  This involves creating components, writing business logic, or installing libraries from npm that don't require native
  code changes. The changes you make here are reflected in your app without needing any interaction
  with the native side of your app.
- #### Update app configuration
  This involves modifying your app's
  configuration using the app config file (**app.json** or **app.config.js**). It includes updating
  your app's name, icon, splash screen, and other properties. These changes don't all affect the
  native project directly. However, if you make changes that affect the native projects, you can use
  the [app config](/workflow/configuration/) to modify the native project configuration or create or
  use a [config plugin](/config-plugins/introduction/). See [app config
  reference](/versions/latest/config/app/) for a complete list of properties available in the app
  config file.
- #### Write native code or modify native project configuration
  This includes writing native code directly or modifying native code configuration. You either need
  access to the native code project directories to make these changes, or you can write native code
  with a [local Expo Module](/modules/get-started/#adding-a-new-module-to-an-existing-application).
- #### Install a library that requires native code modifications
  This includes that a library requires making changes to the native code project configuration. Either
  the library provides a config plugin or steps to take to update the app config. Like the previous
  activity, this also requires you to create a development build.
When creating a [development build](#development-builds), you have two options. You can create a cloud-based build using [EAS Build](/build/setup/) or do it locally. If you choose to do it locally, you can use [CNG](#continuous-native-generation-cng) and then [`npx expo prebuild --clean`](#how-do-i-know-when-i-need), or you can create a development build using [`npx expo run android|ios` or Android Studio and Xcode](/guides/local-app-development/#local-app-compilation).
>
注意：在本地创建开发版本时，`npx expo run` 命令将在构建应用之前生成原生目录。如果你在第一次构建后修改项目的配置或原生代码，则必须重新构建项目。再次运行 `npx expo prebuild` 会将更改分层到现有文件的顶部。构建后也可能会产生不同的结果。为了避免这种情况，请将原生目录添加到项目的 .gitignore 并使用 `npx expo prebuild --clean` 命令。
¥**Note**: When creating a development build locally, the `npx expo run` commands will generate native directories before building your app. If you modify your project's configuration or native code after the first build, you will have to rebuild your project. Running `npx expo prebuild` again layers the changes on the top of existing files. It may also produce different results after the build. To avoid this, add native directories to the project's **.gitignore** and use `npx expo prebuild --clean` command.
在应用的开发循环中，还可以在同一设备上对应用进行 [安装不同的变体（开发、预览或生产）](/build-reference/variants/) 操作。
¥During your app's development loop can also [install different variants (development, preview or production)](/build-reference/variants/) of your app on the same device.
开发循环的另一个关键部分是调试。有关调试应用的更多信息，请参阅 [调试运行时问题](/debugging/runtime-issues/) 并了解可用的不同 [调试工具](/debugging/tools/)。
¥Another key part of the development loop is debugging. See [Debugging runtime issues](/debugging/runtime-issues/) for more information about debugging your app and learn about different [debugging tools](/debugging/tools/) available.
<a id="share-app-with-testers"></a>
## 与测试器共享应用
¥Share app with testers
开发应用的下一步是与你的团队、Beta 测试人员共享你的应用，或在多个测试设备上运行它。传统方法是将应用的二进制文件上传到 Google Play Beta (Android) 或 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，我们建议你完成 [内部分发](/build/internal-distribution/) 以了解有关共享你的应用以进行测试的更多信息。
¥If you are using EAS Build, we recommend going through [Internal distribution](/build/internal-distribution/) to learn more about sharing your app for testing.
如果你在本地编译应用，则可以创建 [本地生产版本](/guides/local-app-production/)。
¥If you compile your app locally, you can create [production builds locally](/guides/local-app-production/).
<a id="release-app-to-stores"></a>
## 向商店发布应用
¥Release app to stores
要在应用商店上发布你的应用，你可以使用 [EAS 提交](/submit/introduction/)。有关使用 EAS 提交的更多信息，请参阅 [提交到 Google Play 商店](/submit/android/) 和 [提交至苹果应用商店](/submit/ios/)。
¥To release your app on the app stores, you can use [EAS Submit](/submit/introduction/). For more information on using EAS Submit, see [Submit to Google Play Store](/submit/android/) and [Submit to Apple App Store](/submit/ios/).
要在本地创建生产版本，请参阅相同的 [guide](/guides/local-app-production/)，然后按照应用商店指南提交你的应用。
¥To create a production build locally, see the [guide](/guides/local-app-production/) on the same and then go through the app stores guide to submit your app.
<a id="monitor-app-in-production"></a>
## 监控生产中的应用
¥Monitor app in production
监控生产应用的两种方法是崩溃报告和分析。崩溃报告可帮助你了解用户在使用应用时遇到的异常或错误。你可以使用 [Sentry](/guides/using-sentry/) 或 [BugSnag](https://docs.bugsnag.com/platforms/react-native/expo/) 来启用崩溃报告。
¥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](/guides/using-sentry/) or [BugSnag](https://docs.bugsnag.com/platforms/react-native/expo/) to enable crash reports.
通过分析，你可以跟踪用户如何与你的应用交互。请参阅 [分析概述](/guides/using-analytics/) 了解有关 Expo 和 React Native 生态系统中可用服务的更多信息。
¥Analytics allows you to track how users interact with your app. See [analytics overview](/guides/using-analytics/) to learn more about the services available in the Expo and React Native ecosystem.
<a id="update-the-app"></a>
## 更新应用
¥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 更新](/eas-update/introduction/)，它为 React Native 应用中的即时更新提供一流的支持。它从全球 CDN 边缘提供更新，并为支持它们的客户端使用 HTTP/3 等现代网络协议。使用 EAS Build 的也是 [为开发商量身定制](/eas-update/develop-faster/)。你还可以将它用于你创建的 [locally](/eas-update/standalone-service/) 版本。
¥You can use [EAS Update](/eas-update/introduction/) 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](/eas-update/develop-faster/) who use EAS Build. You can also use it for builds you have created [locally](/eas-update/standalone-service/).


## 使用应用配置进行配置

了解 app.json/app.config.js/app.config.ts 文件是什么以及如何动态自定义和使用它们。

<PossibleRedirectNotification newUrl="/versions/latest/config/app/" />
应用配置（app.json、app.config.js、app.config.ts）用于配置 [Expo 预建](/workflow/prebuild) 生成、项目如何在 [Expo](/get-started/expo-go/) 中加载以及 OTA 更新清单。
¥The app config (**app.json**, **app.config.js**, **app.config.ts**) is used for configuring [Expo Prebuild](/workflow/prebuild) generation, how a project loads in [Expo Go](/get-started/expo-go/), and the OTA update manifest.
它必须位于项目的根目录中，package.json 旁边。这是一个最小的例子：
¥It must be located at the root of your project, next to the **package.json**. Here is a minimal example:
```json app.json
{
  "name": "My app",
  "slug": "my-app"
}
```
如果你的 Expo 配置有一个顶层 `expo: {}` 对象，那么它将代替根对象，并且所有其他键将被忽略。
¥If your Expo config has a top-level `expo: {}` object, then this will be used in place of the root object and all other keys will be ignored.
<a id="properties"></a>
## 属性
¥Properties
应用配置配置许多内容，例如应用名称、图标、启动屏幕、深度链接方案、用于某些服务的 API 密钥等。有关可用属性的完整列表，请参阅 [app.json/app.config.js/app.config.ts 参考](/versions/latest/config/app/)。
¥The app config configures many things such as app name, icon, splash screen, deep linking scheme, API keys to use for some services and so on. For a complete list of available properties, see [app.json/app.config.js/app.config.ts reference](/versions/latest/config/app/).
>  **info** 你使用 Visual Studio 代码吗？如果是这样，我们建议你安装 [Expo 工具](https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools) 扩展以自动补齐 app.json 文件中的属性。
>
> ¥Do you use Visual Studio Code? If so, we recommend that you install the [Expo Tools](https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools) extension to get auto-completion of properties in **app.json** files.
<a id="reading-configuration-values-in-your-app"></a>
## 读取应用中的配置值
¥Reading configuration values in your app
应用配置中的大多数配置都可以在运行时通过 JavaScript 代码使用 [`Constants.expoConfig`](/versions/latest/sdk/constants/#nativeconstants--properties) 进行访问。你不应在应用配置中包含任何敏感信息（过滤掉的字段有一些例外，如下所述）。
¥Most configuration in the app config is accessible at runtime from your JavaScript code, using [`Constants.expoConfig`](/versions/latest/sdk/constants/#nativeconstants--properties). You **should not** include any sensitive information in the app config (with a few exceptions for fields that are filtered out, as outlined below).
你可以通过运行 `npx expo config --type public` 来验证哪些配置将嵌入到你的构建/更新中并在运行时可用。
¥You can verify which configuration will be embedded in your builds/updates and available at runtime by running `npx expo config --type public`.
Note: Which fields are filtered out of the public app config?
---
The following fields are filtered out of the public app config (and not accessible through the `Constants.expoConfig` object):
- [`hooks`](/versions/latest/config/app/#hooks)
- [`ios.config`](/versions/latest/config/app/#config)
- [`android.config`](/versions/latest/config/app/#config-1)
- [`updates.codeSigningCertificate`](/versions/latest/config/app/#codesigningcertificate)
- [`updates.codeSigningMetadata`](/versions/latest/config/app/#codesigningmetadata)
---
> **warning** You should also avoid importing **app.json** or **app.config.js** directly in your JavaScript code, because this will import the entire file rather than a processed version of it. Instead, use [`Constants.expoConfig`](/versions/latest/sdk/constants/#nativeconstants--properties) to access the configuration.
## Extending configuration
Library authors can extend the app config by using [Expo Config plugins](/config-plugins/introduction/).
> **info** Config plugins are mostly used to configure the [`npx expo prebuild`](/workflow/prebuild) command.
## Dynamic configuration
For more customization, you can use the JavaScript (**app.config.js**) or [TypeScript](#using-typescript-for-configuration-appconfigts-instead-of-appconfigjs) (**app.config.ts**). These configs have the following properties:
- Comments, variables, and single quotes.
- ESM import syntax (the `import` keyword) is not supported, except when using [TypeScript with `tsx`](/guides/typescript/#appconfigjs). JS files that are compatible with your current version of Node.js can be imported with `require()`.
- TypeScript support with nullish coalescing and optional chaining.
- Updated whenever Metro bundler reloads.
- Provide environment information to your app.
- Does not support Promises.
For example, you can export an object to define your custom config:
```js app.config.js
const myValue = 'My App';
module.exports = {
  name: myValue,
  version: process.env.MY_CUSTOM_PROJECT_VERSION || '1.0.0',
  // All values in extra will be passed to your app.
  extra: {
    fact: 'kittens are cool',
  },
};
```
The `"extra"` key allows passing arbitrary configuration data to your app. The value of this key is accessed using [`expo-constants`](/versions/latest/sdk/constants/):
```js App.js
import Constants from 'expo-constants';
Constants.expoConfig.extra.fact === 'kittens are cool';
```
You can access and modify incoming config values by exporting a function that returns an object. This is useful if your project also has an **app.json**. By default, Expo CLI will read the **app.json** first and send the normalized results to the **app.config.js**.
For example, your **app.json** could look like this:
```json app.json
{
  "name": "My App"
}
```
And in your **app.config.js**, you are provided with that configuration in the arguments to the exported function:
```js app.config.js
module.exports = ({ config }) => {
  console.log(config.name); // prints 'My App'
  return {
    ...config,
  };
};
```
### Switching configuration based on the environment
It's common to have some different configuration in development, staging, and production environments, or to swap out configuration entirely to white label an app. To accomplish this, you can use **app.config.js** along with environment variables.
```js app.config.js
module.exports = () => {
  if (process.env.MY_ENVIRONMENT === 'production') {
    return {
      /* your production config */
    };
  } else {
    return {
      /* your development config */
    };
  }
};
```
To use this configuration with Expo CLI commands, set the environment variable either for specific commands or in your shell profile. To set environment variables for specific commands, prefix the command with the variables and values as shown in the example:
```sh
$ MY_ENVIRONMENT=production eas update
```
This is not anything unique to Expo CLI. On Windows you can approximate the above command with:
```sh
$ npx cross-env MY_ENVIRONMENT=production eas update
```
或者，你可以使用任何其他你熟悉的环境变量机制。
¥Or you can use any other mechanism that you are comfortable with for environment variables.
<a id="using-typescript-for-configuration-appconfigts-instead-of-appconfigjs"></a>
### 使用 TypeScript 进行配置：使用 app.config.ts 而不是 app.config.js
¥Using TypeScript for configuration: app.config.ts instead of app.config.js
你可以在 TypeScript 中将自动补齐和文档块与 Expo 配置一起使用。创建一个包含以下内容的 app.config.ts 文件：
¥You can use autocomplete and doc-blocks with an Expo config in TypeScript. Create an **app.config.ts** with the following contents:
```ts app.config.ts
import { ExpoConfig, ConfigContext } from 'expo/config';
export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  slug: 'my-app',
  name: 'My App',
});
```
要将其他 TypeScript 文件导入 app.config.ts 或自定义语言特性，我们建议使用 [`tsx`](/guides/typescript/#appconfigjs)。`tsx` 还支持在 app.config.ts 导入的任何文件中使用 `import` 语法。这意味着你可以使用 TypeScript 编写具有完整语言特性的本地 [配置插件](/config-plugins/introduction/)。
¥To import other TypeScript files into **app.config.ts** or customize the language features, we recommend using [`tsx`](/guides/typescript/#appconfigjs). `tsx` also enables using `import` syntax in any file imported by **app.config.ts**. This means you can write local [config plugins](/config-plugins/introduction/) in TypeScript with full language features.
<a id="configuration-resolution-rules"></a>
### 配置解析规则
¥Configuration resolution rules
有两种不同类型的配置：静态（app.config.json、app.json）和动态（app.config.js、app.config.ts）。静态配置可以使用 CLI 工具自动更新，而动态配置必须由开发者手动更新。
¥There are two different types of configs: static (**app.config.json**, **app.json**), and dynamic (**app.config.js**, **app.config.ts**). Static configs can be automatically updated with CLI tools, whereas dynamic configs must be manually updated by the developer.
1. 如果 app.config.json 存在，则会读取静态配置（回退到 app.json）。如果不存在静态配置，则默认值将从 package.json 和你的依赖中推断出来。
   ¥The static config is read if **app.config.json** exists (falls back to **app.json**). If no static config exists, then default values are inferred from the **package.json** and your dependencies.
2. 如果 app.config.ts 或 app.config.js 存在，则会读取动态配置。如果两者都存在，则使用 TypeScript 配置。
   ¥The dynamic config is read if either **app.config.ts** or **app.config.js** exist. If both exist, then the TypeScript config is used.
3. 如果动态配置返回一个函数，则静态配置将与 `({ config }) => ({})` 一起传递给该函数。此函数可以修改静态配置的值。可以将其视为静态配置的中间件。
   ¥If the dynamic config returns a function, then the static config is passed to the function with `({ config }) => ({})`. This function can then mutate the static config values. Think of this like middleware for the static config.
4. 动态配置的返回值将用作最终配置。它不能包含任何 Promise。
   ¥The return value from the dynamic config is used as the final config. It cannot have any promises.
5. Expo 生态系统中的任何工具使用配置之前，配置中的所有函数都会被评估和序列化。托管时，配置必须是 JSON 清单。
   ¥All functions in the config are evaluated and serialized before any tool in the Expo ecosystem uses it. The config must be a JSON manifest when it is hosted.
6. 如果最终配置对象包含顶层 `expo: {}` 对象，则该对象将代替根对象，并且所有其他键都将被忽略。
   ¥If the final config object has a top-level `expo: {}` object, then this will be used in place of the root object and all other keys will be ignored.
运行 `npx expo config` 将显示解析后将在 Expo CLI 中使用的最终配置。
¥Running `npx expo config` will display the final configuration that will be used in Expo CLI after resolution has occurred.


## 持续的原生生成 (CNG)

了解如何使用持续原生生成 (CNG) 和预构建来管理你的原生项目。

单个原生项目本身的维护、扩展和更新都很复杂。在跨平台应用中，你有多个原生项目，你必须维护这些项目并保持最新的操作系统版本，以避免在任何第三方依赖中落后太多。
¥A single native project on its own is complicated to maintain, scale, and update. In a cross-platform app, you have multiple native projects that you must maintain and keep up to date with the latest operating system releases to avoid falling too far behind in any third-party dependencies.
随着你的原生项目的增长，来自第三方依赖的复杂性也会增加，从而使升级变得复杂并减缓开发者的开发速度。这不鼓励添加高级原生功能，并导致应用功能减弱。在跨平台应用中，这种复杂性在每个平台上都会成倍增加。
¥As your native project grows, the complexity from third-party dependencies increases, complicating upgrades and slowing down developer momentum. This discourages adding advanced native functionality and leads to less powerful apps. In cross-platform apps, this complexity is multiplied across each platform.
为了解决这个问题，我们引入了持续原生生成的概念。不是一次性创建原生项目并在代码库的整个生命周期内维护对这些原生项目的自定义，而是仅在需要时（例如调试或构建时）生成短暂的原生项目。这些项目是从标准模板加上配置或定义如何自定义模板的自定义代码生成的。结果是一个原生项目，可以编译成原生应用，并根据开发者的需要进行任何自定义。但是，开发者只负责维护其自定义的定义，而不是所有原生项目代码。
¥To address this, we've introduced the concept of **Continuous Native Generation**. Instead of creating native projects a single time and maintaining customizations to those native projects for the lifetime of the codebase, short-lived native projects are generated only when needed, such as when debugging or building. These projects are generated from a standard template plus configuration or custom code that defines how the template should be customized. The result is a native project that can be compiled into a native app with any customizations desired by the developer. However, the developer is responsible for only maintaining the definition of their customizations, rather than all of the native project code.
<a id="cng-in-react-native-apps"></a>
## React Native 应用中的 CNG
¥CNG in React Native apps
React Native 应用可以使用 [预建](#usage) 使用 CNG 来自动升级、安装或卸载库、应用白标自定义、跨多个应用共享配置、减少 [孤立代码](#how-does-prebuild-help-with-orphaned-code) 等等。
¥React Native apps can use **CNG** by using [Prebuild](#usage) to automate upgrades, install or uninstall libraries, apply white label customizations, share configuration across multiple apps, reduce [orphaned code](#how-does-prebuild-help-with-orphaned-code), and more.
Expo 作为一个框架，通过结合以下工具来启用 CNG：
¥**Expo as a framework** enables CNG by combining the following tools:
1. [应用配置](/workflow/configuration/) 文件。
   ¥The [app config](/workflow/configuration/) file.
2. 传递给 `npx expo prebuild` 命令的参数。
   ¥Arguments passed to the `npx expo prebuild` command.
3. 项目中安装的 `expo` 版本以及相应的 [预构建模板](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum)。
   ¥Version of `expo` that's installed in the project and corresponding [prebuild template](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum).
4. [自动链接](/more/glossary-of-terms#autolinking)，用于链接 package.json 中找到的 [原生模块](/more/glossary-of-terms/#native-module)。
   ¥[Autolinking](/more/glossary-of-terms#autolinking), for linking [native modules](/more/glossary-of-terms/#native-module) found in the **package.json**.
5. 原生订阅者，用于减少入口点文件中的原生代码副作用，例如 MainApplication 或 AppDelegate。
   ¥Native subscribers, for reducing native code side-effects in entry point files, such as **MainApplication** or **AppDelegate**.
6. 用于代码签名附加目标和权利的 EAS 凭证。
   ¥EAS Credentials for code signing additional targets and entitlements.
最终结果是一个工作流程，开发者可以使用应用配置表达任何原生应用并通过运行 `npx expo prebuild` 连续生成该项目。
¥The end result is a workflow where a developer can express any native application with the app config and generate that project continuously — by running `npx expo prebuild`.
<a id="usage"></a>
## 用法
¥Usage
可以通过运行以下命令来使用预构建：
¥Prebuild can be used by running:
```sh
$ npx expo prebuild
```
这将创建用于运行 React 代码的 android 和 ios 目录。如果你手动修改生成的目录，那么你下次运行 `npx expo prebuild --clean` 时可能会丢失所做的更改。相反，使用 [配置插件](/config-plugins/introduction/) ，它们是在预构建期间对原生项目执行修改的函数。
¥This creates the **android** and **ios** directories for running your React code. If you modify the generated directories manually then you risk losing your changes the next time you run `npx expo prebuild --clean`. Instead, use [config plugins](/config-plugins/introduction/) , which are functions that perform modifications on native projects during prebuild.
我们强烈建议你出于 [常见问题](#prebuild) 部分中列出的原因使用 Prebuild，但系统是 [完全可选](#optionality)，你可以随时停止使用它。
¥We highly recommend using Prebuild for the reasons listed in the [common questions](#prebuild) section, but the system is [fully optional](#optionality), and you can stop using it at any time.
<a id="usage-with-eas-build"></a>
### 与 EAS 构建一起使用
¥Usage with EAS Build
如果你的项目不包含 android 和 ios 目录，EAS Build 将在编译前运行 Prebuild 生成这些原生目录。这是使用 `npx create-expo-app` 创建的任何项目的默认行为。
¥If your project does not contain **android** and **ios** directories, EAS Build will run Prebuild to generate these native directories before compilation. This is the default behavior for any project created using `npx create-expo-app`.
对于具有 android 和 ios 目录的项目，EAS Build 将不会运行 Prebuild，以避免覆盖你对原生目录所做的任何更改。
¥For a project that has **android** and **ios** directories, EAS Build will not run Prebuild to avoid overwriting any changes you've made to the native directories.
如果你通过 [本地编译](/guides/local-app-development/#local-app-compilation)（运行 `npx expo prebuild`、或 `npx expo run:android` 或 `npx expo run:ios`）对应用进行故障排除，你仍然可以使用 Prebuild 和 EAS Build 在构建过程中生成新的原生目录。在这种情况下，将 android 和 ios 目录添加到 .gitignore 或 [**.easignore**](/build-reference/easignore/) 文件中：
¥If you troubleshoot your app by [compiling it locally](/guides/local-app-development/#local-app-compilation) (running `npx expo prebuild`, or `npx expo run:android` or `npx expo run:ios`), you can still use Prebuild with EAS Build to generate fresh native directories during the build process. In this scenario, add the **android** and **ios** directories to **.gitignore** or [**.easignore**](/build-reference/easignore/) files:
```diff .gitignore
+ /android
+ /ios
```
<a id="usage-with-expo-cli-run-commands"></a>
### 与 Expo CLI 运行命令一起使用
¥Usage with Expo CLI run commands
你可以通过运行以下命令在本地执行原生构建：
¥You can perform a native build locally by running:
```sh
$ npx expo run:android
$ npx expo run:ios
```
如果原生目录不存在，`npx expo prebuild` 将针对特定平台运行一次。在随后使用这些 `run` 命令时，请手动运行 `npx expo prebuild --clean` 以确保原生代码与你的本地配置最新同步。
¥If native directories are absent, `npx expo prebuild` will run once for the specific platform. On subsequent uses of these `run` commands, manually run `npx expo prebuild --clean` to ensure the native code is freshly synchronized with your local configuration.
<a id="platform-support"></a>
## 平台支持
¥Platform support
Prebuild 目前支持 Android 和 iOS。不需要 Web 支持，因为没有为 Web 和它在 Web 浏览器中运行的 Web 应用生成的原生项目。使用 `--platform` 选项为各个平台运行预构建：
¥Prebuild currently supports Android and iOS. Web support is not required because there is no native project to generate for the web and the web app it runs in a web browser. Use the `--platform` option to run prebuild for individual platforms:
```sh
$ npx expo prebuild --platform ios
```
<a id="dependencies"></a>
## 依赖
¥Dependencies
Prebuild 首先从与每个 Expo SDK 版本相对应的模板初始化新的原生项目。这也与特定的 React 和 React Native 版本一致。如果项目的 React 和 React Native 版本与 [模板的 package.json](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum) 的 `dependencies` 字段中指定的预期版本不同，则在运行 `npx expo prebuild` 时你将看到警告。
¥Prebuild begins by initializing new native projects from a template corresponding to each Expo SDK version. This also aligns with specific React and React Native versions. You will see a warning when running `npx expo prebuild` when your project's React and React Native versions differ from the expected versions from specified in the `dependencies` field of the [template's **package.json**](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum) if they differ.
你可以使用 `--skip-dependency-update` 选项跳过更改 npm 包版本：
¥You can skip changing npm package versions with the `--skip-dependency-update` option:
```sh
$ npx expo prebuild --skip-dependency-update react-native
react
```
<a id="package-managers"></a>
## 包管理器
¥Package managers
当 [dependencies](#dependencies) 发生更改时，Prebuild 将使用项目当前使用的包管理器重新安装库（这是从锁定文件中推断出来的）。你可以通过提供以下之一来强制使用特定的包管理器：`--npm`、`--yarn`、`--pnpm`。
¥When the [dependencies](#dependencies) are changed, Prebuild will reinstall libraries using the package manager that is currently used in the project (this is inferred from the lockfile). You can force a specific package manager by providing one of: `--npm`, `--yarn`, `--pnpm`.
通过传递 `--no-install` 命令可以跳过所有安装，这对于快速测试生成很有用。
¥All installations can be skipped by passing the `--no-install` command, which is useful for testing generation quickly.
<a id="clean"></a>
## 清理
¥Clean
`--clean` 选项在生成之前删除任何现有的原生目录。在没有 `--clean` 选项的情况下重新运行 `npx expo prebuild` 将在现有文件之上分层更改，这样速度更快，但在某些情况下可能不会产生相同的结果。
¥The `--clean` option deletes any existing native directories before generating. Re-running `npx expo prebuild` without the `--clean` option will layer changes on top of the existing files, which is faster, but may not produce the same results in some cases.
例如，一些配置插件不是幂等的。当项目利用多个 "危险修饰语" 将正则表达式更改添加到应用代码时，可能会导致意外行为。这就是为什么使用 `--clean` 选项是使用预构建命令的最安全方式，并且通常在大多数情况下都推荐这样做。
¥For example, some config plugins aren't idempotent. When a project utilizes multiple "dangerous modifiers" to add regex changes to an app's code, it can lead to unexpected behavior. This is why using the `--clean` option is the safest way to use the prebuild command and is generally recommended in most cases.
<a id="using---clean-option"></a>
#### 使用 `--clean` 选项
¥Using `--clean` option
使用 `--clean` 选项时，如果你对 git 代码存储库有任何未提交的更改，你将收到警告，因为此选项将删除并重新创建所有原生项目文件。该提示是可选的，在 CI 中遇到时会跳过。你可以通过启用环境变量 `EXPO_NO_GIT_STATUS=1` 来禁用此检查。
¥When using the `--clean` option, you'll be warned if you have any uncommitted changes to your git code repository, as this option will delete and recreate all of your native project files. This prompt is optional and will be skipped when encountered in CI. You can disable this check by enabling the environment variable `EXPO_NO_GIT_STATUS=1`.
在某些情况下，开发者可能希望经常在工作流程之间进行交换。例如，你可能希望在 Android Studio 和 Xcode 中原生构建自定义功能，然后将该功能移至本地配置插件中。
¥There are cases where developers may want to swap between workflows often. For example, you may want to build custom functionality natively in Android Studio and Xcode, and then move that functionality into local config plugins.
<a id="templates"></a>
## 模板
¥Templates
你可以自定义 [配置插件](/config-plugins/introduction) 生成原生目录的方式。许多配置插件已经存在，可以进行大量修改，社区库也经常提供自己的插件。你可以 [查看一些流行插件的列表](https://github.com/expo/config-plugins) 了解更多信息。
¥You can customize how the native directories are generated by [config plugins](/config-plugins/introduction). Many config plugins already exist for lots of modifications, and community libraries often ship their own as well. You can [see a list of some popular plugins](https://github.com/expo/config-plugins) for more information.
Prebuild 从模板文件开始，然后使用配置插件进行修改。模板文件基于 Expo SDK 版本，来自 npm 包 [`expo-template-bare-minimum`](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum)。你可以通过将 `--template /path/to/template.tgz` 传递给 `npx expo prebuild` 命令来更改使用的模板。通常不建议这样做，因为 `@expo/prebuild-config` 中的基本修饰符对模板文件做出了一些未记录的假设，因此维护自定义模板可能很棘手。
¥Prebuild starts from template files, which are then modified with config plugins. The template files are based on the Expo SDK version and come from the npm package [`expo-template-bare-minimum`](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum). You can change the template used by passing `--template /path/to/template.tgz` to the `npx expo prebuild` command. This is not generally recommended because the base modifiers in `@expo/prebuild-config` make some undocumented assumptions about the template files, so it may be tricky to maintain your custom template.
> 注意：在所有包都是从私有注册表下载并且 npm 公共注册表访问被阻止的网络环境中，必须将本地可用的模板传递给预构建命令。[了解有关使用默认模板的本地版本的详细信息](https://expo.fyi/prebuild-without-npm-access)。
>
> ¥**Note:** In network environments where all packages are downloaded from a private registry and npm public registry access is blocked, a locally-available template must be passed to the prebuild command. [Learn more about using a local version of the default template](https://expo.fyi/prebuild-without-npm-access).
<a id="side-effects"></a>
## 副作用
¥Side effects
除了生成 android 和 ios 目录之外，`npx expo prebuild` 还执行一些副作用。消除这些副作用的工作正在进行中 - 理想情况下，运行 `npx expo prebuild` 将生成 Android 和 iOS 项目，并且项目的其余部分保持不变。
¥`npx expo prebuild` performs several side effects outside of generating the **android** and **ios** directories. Work is in progress to eliminate these side effects — ideally, running `npx expo prebuild` would generate the Android and iOS projects and leave the rest of the project untouched.
除了生成原生目录外，prebuild 还进行了以下修改：
¥In addition to generating the native directories, prebuild also makes the following modifications:
* 修改 package.json 中的 `scripts` 字段，将 `expo start --android` 和 `expo start --ios` 替换为 `expo run:android` 和 `expo run:ios`
  ¥Modifies the `scripts` field in the **package.json** to replace `expo start --android` and `expo start --ios` with `expo run:android` and `expo run:ios`
* 修改 package.json 中的 `dependencies` 字段
  ¥Modifies the `dependencies` field in the **package.json**
对 `scripts` 字段的方便更改是改变开发者在预构建之前/之后处理应用的方式的唯一副作用。所有其他更改都可以保留并提交给 git，以最大限度地减少运行预构建时的差异。
¥The convenience change to the `scripts` field is the only side effect that alters how a developer works on their app before/after prebuild. All other changes can be left in place and committed to git to minimize the diff when running prebuild.
<a id="optionality"></a>
## 可选
¥Optionality
Prebuild 是可选的，可与所有 Expo 工具和服务无缝协作。对于现有的 React Native 项目，其中原生项目是手动管理的，请勿使用 `npx expo prebuild`，因为这可能会覆盖任何手动自定义。开发者可以在采用其他 Expo 工具和工作流程的同时继续制作 ([直接更改其原生项目](/more/glossary-of-terms/#bare-workflow))。稍后，他们可以将手动自定义移动到应用配置和/或配置插件，然后采用 CNG。
¥Prebuild is optional and works seamlessly with all Expo tools and services. For existing React Native projects, where the native projects are managed manually, do not use `npx expo prebuild`, as that may overwrite any manual customizations. Developers can continue to make ([direct changes to their native projects](/more/glossary-of-terms/#bare-workflow)) while adopting other Expo tools and workflows. Later on, they can move their manual customizations to app config and/or config plugins, and then adopt CNG.
Expo 提供的所有内容，包括 [EAS](/eas/)、Expo CLI 和 Expo SDK 中的库，都是为完全支持裸 React Native 项目而构建的，因为这是使用 `npx expo prebuild` 支持项目的最低要求。唯一的例外是 [Expo](https://expo.dev/go) 应用，它只能在包含 Expo Go 运行时中不存在的原生代码的 JavaScript 回退时加载任意 React Native 项目。
¥Everything offered by Expo including [EAS](/eas/), Expo CLI, and the libraries in the Expo SDK are built to **fully support** bare React Native projects as this is a minimum requirement for supporting projects using `npx expo prebuild`. The only exception is the [Expo Go](https://expo.dev/go) app, which can load arbitrary React Native projects only if they include JavaScript fallbacks for native code absent in the Expo Go runtime.
<a id="common-questions"></a>
## 常见问题
¥Common questions
<a id="cng"></a>
### CNG
Note: How does CNG help with project upgrades?
---
React Native developers who don't use **Continuous Native Generation** have reported that upgrading their apps to the latest version of React Native is the number one weakness of the library as per [React Native Survey (2022)](https://results.2022.stateofreactnative.com/opinions/#opinions_pain_points).
When using CNG, the upgrade process simply involves upgrading the npm dependencies, app config, and re-running `npx expo prebuild --clean`.
---
Note: How a React Native library author can adopt CNG?
---
React Native library authors can adopt CNG in several ways. It depends on the complexity of their libraries. Here are a few scenarios:
- **No native code or configuration side-effects**: Libraries without native code or configuration side-effects, such as `react-native-blurhash`, can seamlessly integrate with `npx expo prebuild`. They can rely on Node Module Resolution without requiring any additional configuration.
- **Native code with no additional setup after install**: Libraries with native code can often be installed and linked automatically with [Expo Autolinking](/more/glossary-of-terms#autolinking), which runs before the native app is built.
- **Additional configuration side-effects and setup**: Libraries that require additional configuration side-effects can adopt CNG by creating [Expo config plugins](/config-plugins/introduction/) for their libraries. This approach enables library authors to automate adding values such as permission messages to the **Info.plist**, or injecting targets in the Xcode project.
- **Libraries Dependent on Native Runtime Hooks**: Libraries that depend on specific native runtime hooks, such as intercepting the initial launch URL via the `AppDelegate`, `MainActivity`, `MainApplication`, and so on, can utilize [**Lifecycle listeners**](/modules/android-lifecycle-listeners/) in the Expo Modules API. These lifecycle listeners allow these runtime hooks to be applied via Expo Autolinking instead of by modifying these standard native project files, eliminating the need for a config plugin.
Many complex libraries and services already support CNG via Expo Prebuild such as, [MapBox](https://github.com/rnmapbox/maps), [OneSignal](https://github.com/OneSignal/onesignal-expo-plugin), [Stripe](https://github.com/stripe/stripe-react-native), and [React Native Firebase](https://rnfirebase.io/#expo).
Adopting CNG by library authors is not a preqrequisite for using `npx expo prebuild`. If a library author has not adopted CNG, developers can still use `npx expo prebuild` by creating local [Config Plugins](https://github.com/expo/config-plugins/) to modify the native generation pipeline. This flexibility makes CNG accessible and beneficial to all developers within the React Native community.
---
Note: Is CNG limited to React Native projects?
---
No, CNG is a versatile pattern that can be applied to any native project. While Expo Prebuild is a tool that implements CNG specifically for React Native projects, the concept itself is not limited to this framework.
---
Note: How does community use CNG?
---
Here are a few community examples of difficult native features converted into simple configuration files, which have allowed developers to build more powerful apps without compromising on iteration speed:
- [iOS Safari Extensions](https://github.com/andrew-levy/react-native-safari-extension): Here, the process of creating a Safari Extension for iOS, which is a notoriously difficult feature to implement, is reduced to a few of lines of JSON.
- [iMessage Sticker App](https://github.com/expo/config-plugins/tree/main/packages/ios-stickers): This Expo config plugin can generate an entire iMessage Sticker App from a JSON object.
- [Cross-platform end-to-end testing](https://github.com/expo/config-plugins/tree/main/packages/detox): Configure native apps to support E2E testing with Detox in a single-line.
- [The entire Firebase suite](https://rnfirebase.io/): Here you can see the entire native Firebase suite going from a multi-step native configuration process across multiple IDEs, down to basic JSON configuration.
- [Cross-platform home screen widgets](https://github.com/gaishimo/eas-widget-example): This Expo config plugin can generate a home screen widget for Android and iOS.
- [Notification extension and code signing](https://github.com/OneSignal/onesignal-expo-plugin): This Expo config plugin generates a notification extension target on iOS and it augments the EAS credentials service to keep zero-config code signing working.
- [Apple App Clips](https://github.com/bndkt/react-native-app-clip): This Expo config plugin takes the process of generating an Apple App Clip from a multi-step process, ranging across multiple targets, and reduces it to a single line `["react-native-app-clip", { "name": "My App Clip" }]`.
At any point, these features can be easily added and removed, without any side effects. CNG allows developers to experiment with complex features and iterate on them quickly without worrying about the long-term maintenance costs or potential orphaned code in their project.
---
Note: Can CNG be used for operating systems other than Android and iOS?
---
Absolutely! CNG is an abstract concept that can be applied to any operating system. Although Expo Prebuild officially implements CNG for Android and iOS, it also provides abstract platform support for developers to create implementations for additional platforms.
---
Note: Is using Expo a requirement for CNG?
---
Not at all. CNG is an open pattern that can be adopted by any community. We've defined the pattern abstractly to help other communities understand how they can adopt CNG for their own projects.
---
Note: How does CNG compare to web development patterns such as Static Site Generation (SSG)?
---
CNG shares similarities with SSG in that it generates a project from a set of inputs. However, CNG differs from SSG in its output. It generates native runtime code instead of static website code. This means the native project is generated on-demand, and the generated source code and configuration are discarded once the native project is compiled into a native app.
---
Note: Is it possible to use CNG with an existing brownfield project?
---
CNG is designed to manage the entire state of a native project continuously. As a result, it's not intended for use with existing brownfield projects. However, you can use CNG to generate a new native project, which can then be integrated into an existing brownfield project.
---
### Prebuild
Expo Prebuild streamlines CNG processing. Here are some issues in the React Native development cycle that are addressed by Prebuild:
Note: How can Prebuild help with sensible project upgrades?
---
Building native code requires familiarity with the platform's tooling, creating a steep learning curve. This challenge intensifies in cross-platform development due to multiple platforms. Cross-platform tooling doesn't help if you must implement many features in platform-specific native code.
When bootstrapping a native app, there's initial code and configuration that you may not understand. Yet you are not responsible for maintaining it. Eventually, you'll need to understand this code to upgrade your app safely. This challenge often leads developers to upgrade incorrectly or start a new app, copying existing source code.
**With Prebuild**, upgrading is much closer to upgrading a pure JavaScript application. Bump the versions in your **package.json**, regenerate the native project, and you should be ready to continue development.
---
Note: How does Prebuild simplify cross-platform configuration?
---
Cross-platform configurations such as the app icon, name, splash screen, and so on must be implemented manually in native code. These implementations are often quite different for each platform.
**With Prebuild** cross-platform configurations are handled at the config plugin level, and the developer only needs to set a single value like `"icon": "./icon.png"` to have all icon generation taken care of.
---
Note: How can I manage dependency side-effects with Prebuild?
---
Many complex native packages require additional setup beyond installing and [autolinking](/more/glossary-of-terms#autolinking). For example, a camera library requires permission settings to be added **AndroidManifest.xml** for Android and **Info.plist** for iOS. This additional setup can be considered a configuration side effect of a package. Pasting the required side effect code into your project's native files can lead to difficult native compilation errors, and it's also code that you now own and maintain.
**With Prebuild** library authors, who know how to configure their library better than anyone, can create a testable and versioned script called a [config plugin](/config-plugins/introduction/), to automate adding the required configuration side effects for their library. This means library side effects can be more expressive, powerful, and stable. For native code side effects, we also provide [Android Lifecycle Listeners](/modules/android-lifecycle-listeners) and [AppDelegate Subscribers](/modules/appdelegate-subscribers) which come standard in the default [prebuild template](#templates).
---
Note: How does Prebuild help with orphaned code?
---
When you uninstall a package, you have to be certain you removed all of the side effects required to make that package work. If you miss anything, it leads to orphaned code that you cannot trace back to any particular package, this code builds up and makes your project harder to understand and maintain.
**With Prebuild** the only side effect is the [config plugin](/config-plugins/introduction/) in a project's Expo config (**app.json**), which will throw an error when the corresponding node module has been uninstalled, meaning a lot less orphaned configuration.
---
Note: When Prebuild might not be the right fit for a project
---
Here are some reasons Expo Prebuild might **not** be the right fit for a particular project:
#### Platform compatibility
Prebuild can only be used for native platforms that are supported by the Expo SDK. This means Android and iOS for the time being. Except for web, which doesn't require `npx expo prebuild` since it uses the browser instead of a custom native runtime.
#### Making changes directly is quicker than modularizing and automating
All native changes must be added with native modules (using React Native's built-in Native Module APIs or the Expo Modules API) and config plugins. This means if you want to quickly add a native file to your project to experiment, then you may be better off running prebuild and adding the file manually, then working your way back into the system with a [monorepo](/guides/monorepos). We plan to speed this process up by adding functionality to [Expo Autolinking](/more/glossary-of-terms#expo-autolinking) that finds native project files outside of the native directories and links them before building.
If you want to modify the configuration, such as the **gradle.properties** file, you'll have to write a plugin ([example](https://github.com/expo/expo/blob/1c994bb042ad47fbf6878e3b5793d4545f2d1208/apps/native-component-list/app.config.js#L21-L28)). This can be easily automated with helper plugin libraries, however, it is a bit slower if you need to do it often.
#### Config plugin support in the community
Not all packages support _Expo Prebuild_ yet. If you find a library that requires extra setup after installation and doesn't yet have a config plugin, we recommend opening a pull request or an issue so that the maintainer is aware of the feature request.
Many packages, such as [`react-native-blurhash`](https://github.com/mrousavy/react-native-blurhash), don't require any additional native configuration beyond what is handled by [autolinking](/more/glossary-of-terms#autolinking) and so no config plugin is required.
Other packages, such as [`react-native-ble-plx`](https://github.com/Polidea/react-native-ble-plx), do require additional setup and therefore require a config plugin to be used with `npx expo prebuild` (in this case there's an external plugin called [`@config-plugins/react-native-ble-plx`](https://github.com/expo/config-plugins/tree/main/packages/react-native-ble-plx)).
Alternatively, we also have a repo for [out-of-tree config plugins](https://github.com/expo/config-plugins) which provides plugins for popular packages that haven't adopted the system yet. Think of this like [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) for TypeScript. We prefer packages ship their own config plugin, but if they haven't adopted the system yet, the community can use the packages listed in the repo.
---


## 使用 Expo SDK、React Native 和第三方库

了解如何在你的项目中使用 Expo SDK、React Native 库和其他第三方 npm 包。

每个应用都不可避免地会使用第三方库，因此了解如何确定库是否与你的项目兼容非常重要。
¥Every app is inevitably going to use a third-party library, so it's important to understand how to determine whether a library is compatible with your project.
<a id="react-native-core-libraries"></a>
## React Native 核心库
¥React Native core libraries
React Native 提供了一组大多数开发者在其应用中需要的内置原语。其中包括 `<ActivityIndicator>`、`<TextInput>`、`<Text>`、`<ScrollView>` 和 `<View>` 等组件。这些列在 React Native 文档的 [核心组件和 API](https://rn.nodejs.cn/docs/components-and-apis) 处。你还可以查看 [与你的 Expo SDK 版本对应的 React Native 版本](/versions/latest)。
¥React Native provides a set of built-in primitives that most developers will need in their apps. These include components such as `<ActivityIndicator>`, `<TextInput>`, `<Text>`, `<ScrollView>`, and `<View>`. These are listed at [Core Components and APIs](https://rn.nodejs.cn/docs/components-and-apis) in React Native documentation. You can also view the [React Native version that corresponds to your Expo SDK version](/versions/latest).
要在项目中使用 React Native 组件或 API，请从代码中的 `react-native` 包导入它：
¥To use a React Native component or API in your project, import it from the `react-native` package in your code:
<SnackInline>
  ```tsx
import { Text, View } from 'react-native';
export default function App() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Hello, world!</Text>
    </View>
  );
}
```
<a id="expo-sdk-libraries"></a>
## Expo SDK 库
¥Expo SDK libraries
Expo SDK 接续了 React Native 核心库的结尾。它提供对许多设备和系统功能的访问，例如音频、条形码扫描、相机、日历、联系人、视频等。它还添加了其他强大的库，如更新、地图、OAuth 身份验证工具等。有关更多信息，请参阅我们如何决定 [Expo SDK 包含哪些内容](https://expo.fyi/whats-in-the-sdk)。
¥The Expo SDK picks up where the React Native core libraries end. It provides access to a lot of device and system functionality such as audio, barcode scanning, camera, calendar, contacts, video, and so on. It also adds other powerful libraries like updates, maps, OAuth authentication tools, and more. For more information, see how we decide [what goes into the Expo SDK](https://expo.fyi/whats-in-the-sdk).
要使用 Expo SDK 中的库，请在 [API 参考](/versions/latest/) 中找到你要查找的库或使用文档搜索。
¥To use a library from the Expo SDK, find the one you are looking for in the [API reference](/versions/latest/) or use the documentation search.
<ConfigReactNative>
  如果你使用 `npx @react-native-community/cli@latest init` 初始化了你的应用，但尚未在其中安装 `expo` 包，请参阅 [安装 Expo 模块指南](/bare/installing-expo-modules) 了解更多信息。
  ¥If you initialized your app using `npx @react-native-community/cli@latest init` and you don't have the `expo` package installed in it yet, see the [installing Expo modules guide](/bare/installing-expo-modules) for more information.
</ConfigReactNative>
你将在每个 API 参考的顶部看到平台兼容性标签。它告诉你该库与哪些平台和环境兼容。例如，[`expo-device`](/versions/latest/sdk/device/) 库的平台标签如下所示：
¥You will see the platform compatibility tags at the top of each API reference. It tells you which platforms and environments the library is compatible with. For example, the platform tags for the [`expo-device`](/versions/latest/sdk/device/) library look like the following:
在平台兼容性表之后，有一个库的描述和一个包含安装库说明的部分。例如：
¥After the platform compatibility table, there is a library's description and a section with instructions on installing the library. For example:
<InstallSection packageName="expo-device" hideBareInstructions />
`npx expo install` 命令选择与你的项目兼容的库版本，然后使用你的 JavaScript 包管理器（例如 npm）进行安装。
¥The `npx expo install` command picks a library version compatible with your project and then uses your JavaScript package manager (such as npm) to install it.
接下来，典型的 API 参考包括：
¥Next, a typical API reference includes:
* 如果库需要配置插件，请配置插件使用信息。
  ¥Config plugin usage information if the library requires a config plugin.
* 一个代码示例，展示如何使用库。
  ¥A code example that shows how to use the library.
* API 部分列出了如何导入库，后面是库提供的钩子、属性、类型、方法和类的列表。
  ¥API section that lists how to import the library, followed by a list of hooks, props, types, methods, and classes that the library provides.
> 注意：如果你使用 TypeScript，你可以在兼容 TypeScript 的代码编辑器（例如 VS Code）中看到 API 部分中包含的信息，并自动补齐。
>
> ¥**Note**: If you use TypeScript, you can see the information included in the API section in your TypeScript-compatible code editor (such as VS Code) with auto-completion.
<a id="third-party-libraries"></a>
## 第三方库
¥Third-party libraries
<a id="finding-a-third-party-library"></a>
### 寻找第三方库
¥Finding a third-party library
[React Native 目录](https://reactnative.directory) 是专门为 React Native 构建的可搜索库数据库。如果你正在寻找的库不是由 React Native 或 Expo SDK 提供的，那么这是在尝试为你的应用查找库时首先查看的最佳位置。
¥[React Native Directory](https://reactnative.directory) is a searchable database of libraries built specifically for React Native. If the library that you are looking for is not provided by React Native or the Expo SDK then this is the best place to look first when trying to find a library for your app.
在 React Native Directory 之后，[npm 注册表](https://www.npmjs.com/) 是下一个最好的地方。npm 注册表是 JavaScript 库的权威来源，但它列出的库可能并不全部与 React Native 兼容。React Native 是众多 JavaScript 编程环境之一，包括 Node.js、Web 浏览器、Electron 等，而 npm 包含适用于所有这些环境的库。当你创建 [开发构建](/workflow/overview/#development-builds) 时，任何与 React Native 兼容的库都与 Expo 项目兼容。但是，它可能与 [Expo](https://expo.dev/go) 应用不兼容。
¥After the React Native Directory, the [npm registry](https://www.npmjs.com/) is the next best place. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments. Any library that is compatible with React Native is compatible with the Expo project when you create a [development build](/workflow/overview/#development-builds). However, it may not be compatible with the [Expo Go](https://expo.dev/go) app.
<a id="determining-third-party-library-compatibility"></a>
### 确定第三方库兼容性
¥Determining third-party library compatibility
使用 Expo [开发构建](/workflow/overview/#development-builds) 构建生产质量的应用。它包括你的项目运行所需的所有原生代码。这是在将应用发布到 App Store 或 Google Play 之前测试应用的好方法。你还可以包含需要原生项目（android 和 ios 目录）配置的库。
¥Use Expo [development builds](/workflow/overview/#development-builds) for building production-quality apps. It includes all of the native code that your project needs to run. This is a great way to test your app before you publish it to the App Store or Google Play. You can also include libraries that require native projects (**android** and **ios** directories) configuration.
Expo Go 应用是开发构建的可选垫脚石。你可以在开发应用时使用它来快速测试应用，但它不包含支持每个库所需的所有原生代码。你可以通过访问 React Native Directory 网站并验证它是否具有 "✔️ Expo" 标签来查找与 Expo Go 兼容的库。你还可以启用 [按 Expo Go 过滤](https://reactnative.directory/?expoGo=true)。
¥The Expo Go app is an optional stepping stone towards development builds. You can use it to quickly test your app while you are developing it, but it does not include all of the native code required to support every library. You can check **React Native Directory** to find a library compatible with Expo Go by visiting the website and verifying that it has a "✔️ Expo Go" tag. You can also enable the [filter by Expo Go](https://reactnative.directory/?expoGo=true).
要确定新的依赖是否更改原生项目目录，你可以检查以下内容：
¥To determine if a new dependency changes native project directories, you can check the following:
* 该库是否包含 android 或 ios 目录？
  ¥Does the library includes **android** or **ios** directories?
* 库的自述文件是否提到链接？
  ¥Does the library's README mention linking?
* 该库是否要求你更改 android/app/src/main/AndroidManifest.xml 或 ios/Podfile 或 ios/Info.plist 来更改项目配置？
  ¥Does the library requires you to change **android/app/src/main/AndroidManifest.xml** or **ios/Podfile** or **ios/Info.plist** to change the project configuration?
* 库有 [配置插件](/config-plugins/introduction/) 吗？
  ¥Does the library have a [config plugin](/config-plugins/introduction/)?
如果你对这些问题中的任何一个的回答是肯定的，那么你应该 [创建开发版本](/develop/development-builds/introduction/) 在你的项目中使用该库。
¥**If you answered yes to any of these questions,** then you should [create a development build](/develop/development-builds/introduction/) to use the library in your project.
未列入目录？你可以在 GitHub 上找到该项目。执行此操作的一个简单方法是使用 `npx npm-home --github <package-name>`。例如，要打开 `react-native-localize` 的 GitHub 页面，请运行：
¥**Not listed on the directory?** You can find the project on GitHub. A simple way to do this is with `npx npm-home --github <package-name>`. For example, to open the GitHub page for `react-native-localize`, run:
```sh
$ npx npm-home --github react-native-localize
```
> 如果你需要一些确定库兼容性的帮助，请 [在 React Native Directory 存储库上创建问题](https://github.com/react-native-community/directory/issues/new/choose) 并告诉我们。这不仅可以帮助你，还可以帮助其他开发者在将来获得简单的答案！
>
> ¥If you want some help determining library compatibility, [create an issue on the React Native Directory repository](https://github.com/react-native-community/directory/issues/new/choose) and let us know. This will not just help you, it will also help other developers have an easy answer in the future!
<a id="installing-a-third-party-library"></a>
### 安装第三方库
¥Installing a third-party library
> 我们建议始终直接使用 `npx expo install` 而不是 `npm install` 或 `yarn add`，因为它允许 [Expo CLI](/more/expo-cli/) 在可能的情况下选择库的兼容版本，并警告你已知的不兼容性。
>
> ¥We recommend always using `npx expo install` instead of `npm install` or `yarn add` directly because it allows [Expo CLI](/more/expo-cli/) to pick a compatible version of a library when possible and also warn you about known incompatibilities.
一旦确定该库是否与 React Native 兼容，请使用 [Expo CLI](/more/expo-cli/) 安装该包：
¥Once you have determined if the library is compatible with React Native, use [Expo CLI](/more/expo-cli/) to install the package:
```sh
$ npx expo install @react-navigation/native
```
请务必遵循项目网站或自述文件以获取任何其他配置和使用说明。你可以使用以下命令快速访问自述文件：
¥Be sure to follow the project website or README for any additional configuration and usage instructions. You can get to the README quickly using this command:
```sh
$ npx npm-home @react-navigation/native
```
如果模块需要额外的原生配置，你可以使用 [配置插件](/config-plugins/introduction/)。有些软件包需要配置插件，但他们还没有，你可以参考 [树外配置插件](https://github.com/expo/config-plugins/).1 的列表。
¥If the module needs additional native configuration, you can do so using [config plugins](/config-plugins/introduction/). Some packages require a config plugin but they don't have one yet, you can refer to the list of [out-of-tree config plugins](https://github.com/expo/config-plugins/).
<ConfigReactNative>
  如果你的项目不支持 [Expo 预建](/workflow/prebuild)，那么你将无法使用 [配置插件](/config-plugins/introduction/)。你可以 [采用 Expo Prebuild](/guides/adopting-prebuild) 或按照相应模块网站或自述文件中的任何其他设置指南手动设置和配置每个库。
  ¥If your project does not support [Expo Prebuild](/workflow/prebuild) then you won't be able to use [config plugins](/config-plugins/introduction/). You can either [adopt Expo Prebuild](/guides/adopting-prebuild) or set up and configure each library manually by following any additional setup guides from the respective module's website or README.
</ConfigReactNative>
如果 [Expo](https://expo.dev/go) 不支持该模块，你可以创建一个 [开发构建](/develop/development-builds/introduction/)：
¥If the module is not supported in [Expo Go](https://expo.dev/go), you can create a [development build](/develop/development-builds/introduction/):
<a id="excluding-a-third-party-library-from-version-checks"></a>
### 从版本检查中排除第三方库
¥Excluding a third-party library from version checks
如果你安装了特定版本的第三方库，并希望将其排除在 `npx expo install`、`npx expo-doctor` 或 `npx expo start` 执行的版本检查之外，请使用 package.json 文件中的 [`expo.install.exclude`](/versions/latest/config/package-json/#exclude) 属性。
¥If you have a specific version of a third-party library installed and want it to be excluded from version checks performed by `npx expo install`, `npx expo-doctor`, or `npx expo start`, use the [`expo.install.exclude`](/versions/latest/config/package-json/#exclude) property in the **package.json** file.


## 隐私清单

了解如何为你的移动应用配置 iOS 隐私清单。

如果你使用的是使用 "限制原因" API 的原生 iOS 库，则需要配置 iOS 隐私清单来声明为什么要包含原生代码来调用这些 API。
¥If you're using a native iOS library that uses a "restricted reason" APIs, you'll need to configure an iOS privacy manifest to declare why you're including native code to call those APIs.
更多详细信息和 "必需原因" API 列表可在 [Apple 开发者文档](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files) 中找到。
¥More details and a list of "required reason" APIs can be found in the [Apple Developer Documentation](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files).
>  **info** 本指南中包含的信息和步骤仍在开发中，可能会因为此目的构建的新工具或 Apple 的新要求而发生变化。
>
> ¥The information and steps included in this guide are still in development and may change due to new tools built for this purpose or new requirements from Apple.
<a id="what-is-a-privacy-manifest"></a>
## 什么是隐私清单？
¥What is a Privacy manifest?
隐私清单是一个名为 PrivacyInfo.xcprivacy 的文件，包含在你的 iOS 原生项目中。此文件用于声明应用包含调用 Apple 认为敏感的某些 API 的原生代码的原因。
¥A privacy manifest is a file named **PrivacyInfo.xcprivacy** that is included in your iOS native project. This file is used to declare why the app includes native code that calls into certain APIs that Apple considers sensitive.
这些 API 当前包括访问 UserDefaults、文件时间戳、系统启动时间、磁盘空间和活动键盘。Apple 认为这是一个开放列表，将来可以扩展。
¥These APIs currently include accessing UserDefaults, file timestamp, system boot time, disk space, and active keyboard. Apple considers it an open list that can be expanded in the future.
<a id="configuration-in-app-config"></a>
## 应用配置中的配置
¥Configuration in app config
你可以通过使用应用配置中 `expo.ios` 下的 `privacyManifests` 字段来包含 iOS 隐私清单。
¥You can include an iOS privacy manifest by using the `privacyManifests` field under `expo.ios` in your app config.
```json app.json
{
  "expo": {
    "name": "My App",
    "slug": "my-app",
    "ios": {
      "privacyManifests": {
        "NSPrivacyAccessedAPITypes": [
          {
            "NSPrivacyAccessedAPIType": "NSPrivacyAccessedAPICategoryUserDefaults",
            "NSPrivacyAccessedAPITypeReasons": ["CA92.1"]
          }
        ]
      }
    }
  }
}
```
确保你已使用 `npx expo install --fix` 将 Expo SDK 库更新为适用于你的 SDK 版本的最新版本。
¥Make sure you have updated your Expo SDK libraries to the latest versions for your SDK version using `npx expo install --fix`.
<ConfigReactNative>
  你可以通过使用 Xcode 创建 PrivacyInfo.xcprivacy 文件并将其添加到你的 iOS 应用目标，在裸 Expo 应用中包含 iOS 隐私清单。按照 [Apple 的隐私清单文件](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files) 指南创建 PrivacyInfo.xcprivacy 文件。
  ¥You can include an iOS privacy manifest in a bare Expo app by creating a **PrivacyInfo.xcprivacy** file using Xcode and adding it to your iOS app target.
  Follow [Apple's Privacy manifest files](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files) guide to create a **PrivacyInfo.xcprivacy** file.
</ConfigReactNative>
你可以通过查看 [Apple 开发者文档](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api) 来识别 `NSPrivacyAccessedAPITypes` 和 `NSPrivacyAccessedAPITypeReasons` 值。
¥You can identify the `NSPrivacyAccessedAPITypes` and `NSPrivacyAccessedAPITypeReasons` values by looking at the [Apple Developer documentation](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api).
<a id="including-required-reasons-for-expo-sdk-packages-and-other-third-party-libraries"></a>
### 包括 Expo SDK 包和其他第三方库所需的原因
¥Including required reasons for Expo SDK packages and other third-party libraries
截至目前，Apple 无法正确解析静态 CocoaPods 依赖（例如 Expo SDK 包和其他生态系统库）包含的所有 PrivacyInfo 文件。你可能需要在应用的 PrivacyInfo.xcprivacy 文件或 app.json 中的配置中包含这些依赖使用的 API 所需的原因。
¥As of now, Apple does not correctly parse all the **PrivacyInfo** files included by static CocoaPods dependencies (such as Expo SDK packages and other ecosystem libraries). You may need to include the required reasons for the APIs used by those dependencies in your app's **PrivacyInfo.xcprivacy** file or the configuration in the **app.json**.
所有使用 "必需原因" API 文件的 Expo SDK 包都在包目录中包含一个 PrivacyInfo 文件。这是 `expo-application` 库中包含的 [示例文件](https://github.com/expo/expo/blob/main/packages/expo-application/ios/PrivacyInfo.xcprivacy)。
¥All Expo SDK packages that use "required reason" APIs file have a **PrivacyInfo** file included in the package directory. Here's [an example file](https://github.com/expo/expo/blob/main/packages/expo-application/ios/PrivacyInfo.xcprivacy) included with the `expo-application` library.
通常，你可以通过检查你打算使用的库是否在 node_modules/package_name/ios 目录中具有 PrivacyInfo.xcprivacy 文件来确定其他第三方库使用的 API 所需的原因。如果确实如此，你可以检查该文件中的 `NSPrivacyAccessedAPITypes` 和 `NSPrivacyAccessedAPITypeReasons` 值，并将这些值复制到你的配置中。
¥You can usually identify the required reasons for the APIs used by other third-party libraries by checking if the library you intend to use has a **PrivacyInfo.xcprivacy** file in the **node_modules/package_name/ios** directory. If it does, you can check the `NSPrivacyAccessedAPITypes` and `NSPrivacyAccessedAPITypeReasons` values in that file and copy those values to your configuration.
作为替代方案，Apple 会在开发者提交缺少隐私清单文件或特定原因的版本后通知他们。你可以等到收到来自 Apple 的通知电子邮件，然后将电子邮件中列出的所需原因包含在应用的 PrivacyInfo.xcprivacy 文件中（如果你不使用 [CNG](/workflow/continuous-native-generation/)）或 app.json 文件中的配置中。
¥As an alternative, Apple notifies developers after they submit a build with missing privacy manifest files or specific reasons. You can wait until you receive a notification email from Apple and then include the required reasons listed in the email in your app's **PrivacyInfo.xcprivacy** file (if you don't use [CNG](/workflow/continuous-native-generation/)) or the configuration in your **app.json** file.
<a id="testing-the-privacy-manifest"></a>
## 测试隐私清单
¥Testing the Privacy manifest
你可以通过构建应用并提交来测试隐私清单，无论是通过 App Store 审核流程还是 TestFlight 的外部审核。如果你的应用缺少所用 API 的任何必要原因，Apple 会在提交后的几分钟内向你发送电子邮件。
¥You can test the privacy manifest by building your app and submitting it, either through App Store review process or to TestFlight's external review. Apple will email you within a few minutes of submitting if your app is missing any required reasons for the APIs used.


## 权限

了解如何在应用配置文件中配置和添加权限。

当开发需要访问用户设备上的潜在敏感信息（例如位置或联系人）的原生应用时，应用必须首先请求用户的许可。例如，要访问用户的媒体库，应用需要运行 [`MediaLibrary.requestPermissionsAsync()`](/versions/latest/sdk/media-library#medialibraryrequestpermissionsasync)。
¥When developing a native app that requires access to potentially sensitive information on a user's device, such as their location or contacts, the app must request the user's permission first. For example, to access the user's media library, the app will need to run [`MediaLibrary.requestPermissionsAsync()`](/versions/latest/sdk/media-library#medialibraryrequestpermissionsasync).
独立和 [开发构建](/develop/development-builds/introduction/) 中的权限需要原生构建时配置，然后才能使用运行时 JavaScript 代码请求。在 [Expo](https://expo.dev/go) 应用中测试项目时不需要这样做。
¥Permissions in standalone and [development builds](/develop/development-builds/introduction/) require native build-time configuration before they can be requested using runtime JavaScript code. This is not required when testing projects in the [Expo Go](https://expo.dev/go) app.
> 如果你没有正确配置或解释原生权限，可能会导致你的应用被拒绝或从商店下架。
>
> ¥If you don't configure or explain the native permissions properly **it may result in your app getting rejected or pulled from the stores**.
<a id="android"></a>
## 安卓
¥Android
使用 [应用配置](/workflow/configuration/) 中的 [`android.permissions`](/versions/latest/config/app/#permissions) 和 [`android.blockedPermissions`](/versions/latest/config/app/#blockedpermissions) 键配置权限。
¥Permissions are configured with the [`android.permissions`](/versions/latest/config/app/#permissions) and [`android.blockedPermissions`](/versions/latest/config/app/#blockedpermissions) keys in your [app config](/workflow/configuration/).
大多数权限由你在应用中使用的库自动添加，无论是使用 [配置插件](/config-plugins/plugins-and-mods/#create-a-plugin) 还是使用包级 AndroidManifest.xml。你只需要使用 `android.permissions` 添加默认情况下未包含在库中的其他权限。
¥Most permissions are added automatically by libraries that you use in your app either with [config plugins](/config-plugins/plugins-and-mods/#create-a-plugin) or with a package-level **AndroidManifest.xml**. You only need to use `android.permissions` to add additional permissions that are not included by default in a library.
```json app.json
{
  "android": {
    "permissions": ["android.permission.SCHEDULE_EXACT_ALARM"]
  }
}
```
删除包级 AndroidManifest.xml 文件添加的权限的唯一方法是使用 [`android.blockedPermissions`](/versions/latest/config/app/#blockedpermissions) 属性阻止它们。为此，请指定完整的权限名称。例如，如果你想删除 `expo-av` 添加的录音权限：
¥The only way to remove permissions that are added by package-level **AndroidManifest.xml** files is to block them with the [`android.blockedPermissions`](/versions/latest/config/app/#blockedpermissions) property. To do this, specify the **full permission name**. For example, if you want to remove the audio recording permissions added by `expo-av`:
```json app.json
{
  "android": {
    "blockedPermissions": ["android.permission.RECORD_AUDIO"]
  }
}
```
* 请参阅 [`android.permissions`](/versions/latest/config/app/#permissions) 了解默认 [预构建模板](/workflow/prebuild#templates) 中包含哪些权限。
  ¥See [`android.permissions`](/versions/latest/config/app/#permissions) to learn about which permissions are included in the default [prebuild template](/workflow/prebuild#templates).
* 没有正当理由而使用危险或签名权限的应用可能会被 Google 拒绝。确保在提交应用时遵循 [Android 权限最佳实践](https://developer.android.com/training/permissions/usage-notes)。
  ¥Apps using *dangerous* or *signature* permissions without valid reasons **may be rejected by Google**. Ensure you follow the [Android permissions best practices](https://developer.android.com/training/permissions/usage-notes) when submitting your app.
* [所有可用的 Android `Manifest.permissions`](https://developer.android.com/reference/android/Manifest.permission)。
  ¥[All available Android `Manifest.permissions`](https://developer.android.com/reference/android/Manifest.permission).
<ConfigReactNative>
  修改 AndroidManifest.xml 以排除特定权限：将 `tools:node="remove"` 属性添加到 `<use-permission>` 标签以确保将其删除，即使它包含在库的 AndroidManifest.xml 中。
  ¥Modify **AndroidManifest.xml** to exclude specific permissions: add the `tools:node="remove"` attribute to a `<use-permission>` tag to ensure it is removed, even if it's included in a library's **AndroidManifest.xml**.
  ```xml
<manifest xmlns:tools="http://schemas.android.com/tools">
  <uses-permission tools:node="remove" android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>
```
  > 你必须先在 `<manifest>` 上定义 `xmlns:tools` 属性，然后才能在权限上使用 `tools:node` 属性。
  >
  > ¥You have to define the `xmlns:tools` attribute on `<manifest>` before you can use the `tools:node` attribute on permissions.
</ConfigReactNative>
<a id="ios"></a>
## iOS 系统
¥iOS
你的 iOS 应用可以向用户请求系统权限。例如，要使用设备的相机或访问照片，Apple 需要说明你的应用如何使用这些数据。大多数软件包都会自动提供 [配置插件](/config-plugins/introduction/) 给定权限的样板原因。这些默认消息很可能需要根据你的特定用例进行定制，以便你的应用被 App Store 接受。
¥Your iOS app can ask for system permissions from the user. For example, to use the device's camera or access photos, Apple requires an explanation for how your app makes use of that data. Most packages will automatically provide a boilerplate reason for a given permission with [config plugins](/config-plugins/introduction/). These default messages will most likely need to be tailored to your specific use case for your app to be accepted by the App Store.
要设置权限消息，请使用 [应用配置](/workflow/configuration/) 中的 [`ios.infoPlist`](/versions/latest/config/app/#infoplist) 键，例如：
¥To set permission messages, use the [`ios.infoPlist`](/versions/latest/config/app/#infoplist) key in your [app config](/workflow/configuration/), for example:
```json app.json
{
  "ios": {
    "infoPlist": {
      "NSCameraUsageDescription": "This app uses the camera to scan barcodes on event tickets."
    }
  }
}
```
其中许多属性还可以使用与添加它们的库关联的 [配置插件](/config-plugins/introduction/) 属性直接进行配置。例如，使用 [`expo-media-library`](/versions/latest/sdk/media-library)，你可以像这样配置照片权限消息：
¥Many of these properties are also directly configurable using the [config plugin](/config-plugins/introduction/) properties associated with the library that adds them. For example, with [`expo-media-library`](/versions/latest/sdk/media-library) you can configure photo permission messages like this:
```json app.json
{
  "plugins": [
    [
      "expo-media-library",
      {
        "photosPermission": "Allow $(PRODUCT_NAME) to access your photos.",
        "savePhotosPermission": "Allow $(PRODUCT_NAME) to save photos."
      }
    ]
  ]
}
```
* Info.plist 的更改无法通过无线方式更新，只有在你提交新的原生二进制文件时才会部署它们。例如，使用 [`eas build`](/build/introduction)。
  ¥Changes to the **Info.plist** cannot be updated over-the-air, they will only be deployed when you submit a new native binary. For example, with [`eas build`](/build/introduction).
* 苹果官方 [权限消息建议](https://developer.apple.com/design/human-interface-guidelines/privacy#Requesting-permission)。
  ¥Apple's official [permission message recommendations](https://developer.apple.com/design/human-interface-guidelines/privacy#Requesting-permission).
* [所有可用的 Info.plist 属性](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)。
  ¥[All available **Info.plist** properties](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html).
<ConfigReactNative>
  直接在 Info.plist 文件中添加和修改权限消息值。我们建议直接在 Xcode 中执行此操作以进行自动补全。
  ¥Add and modify the permission message values in **Info.plist** file directly. We recommend doing this directly in Xcode for autocompletion.
</ConfigReactNative>
<a id="web"></a>
## Web
在网络上，像 `Camera` 和 `Location` 这样的权限只能从 [安全上下文](https://web.nodejs.cn/en-US/docs/Web/Security/Secure_Contexts#When_is_a_context_considered_secure) 请求。例如，使用 `https://` 或 `http://localhost`。此限制类似于 Android 的清单权限和 iOS 的 Info.plist 使用消息，并且强制执行以提高隐私性。
¥On the web, permissions like the `Camera` and `Location` can only be requested from a [secure context](https://web.nodejs.cn/en-US/docs/Web/Security/Secure_Contexts#When_is_a_context_considered_secure). For example, using `https://` or `http://localhost`. This limitation is similar to Android's manifest permissions and iOS's **Info.plist** usage messages and is enforced to increase privacy.
<a id="resetting-permissions"></a>
## 重置权限
¥Resetting permissions
通常，你希望能够测试用户拒绝权限时会发生什么，以确保你的应用正常反应。Android 和 iOS 上的操作系统级别限制禁止应用多次请求相同的权限（你可以想象，如果用户在拒绝权限后反复提示权限，这会是多么烦人）。要测试涉及开发权限的不同流程，你可能需要卸载并重新安装原生应用。
¥Often you want to be able to test what happens when a user rejects permissions, to ensure your app reacts gracefully. An operating-system level restriction on both Android and iOS prohibits an app from asking for the same permission more than once (you can imagine how this could be annoying for the user to be repeatedly prompted for permissions after rejecting them). To test different flows involving permissions in development, you may need to uninstall and reinstall the native app.
在 [Expo](https://expo.dev/go) 中测试时，你可以通过运行 `npx expo start` 并在 [Expo CLI](/more/expo-cli/) 终端 UI 中按 <kbd>i</kbd> 或 <kbd>a</kbd> 来删除应用并重新安装。
¥When testing in [Expo Go](https://expo.dev/go), you can delete the app and reinstall it by running `npx expo start` and pressing <kbd>i</kbd> or <kbd>a</kbd> in the [Expo CLI](/more/expo-cli/) Terminal UI.


## Expo 中的环境变量

了解如何在 Expo 项目中使用环境变量。

环境变量是在源代码外部配置的键值对，允许你的应用根据环境的不同而表现不同。例如，你可以在构建应用的测试版本时启用或禁用某些功能，或者在构建生产时切换到不同的 API 端点。
¥Environment variables are key-value pairs configured outside your source code that allow your app to behave differently depending on the environment. For example, you can enable or disable certain features when building a test version of your app, or switch to a different API endpoint when building for production.
每当你使用 Expo CLI 时，例如在本地开发模式下运行 `npx expo start` 启动应用时，Expo CLI 都会自动从 .env 文件加载带有 `EXPO_PUBLIC_` 前缀的环境变量，以便在 JavaScript 代码中使用。
¥The Expo CLI will automatically load environment variables with an `EXPO_PUBLIC_` prefix from **.env** files for use within your JavaScript code whenever you use the Expo CLI, such as when running `npx expo start` to start your app in local development mode.
<a id="reading-environment-variables-from-env-files"></a>
## 从 .env 文件读取环境变量
¥Reading environment variables from .env files
在项目目录的根目录中创建一个 .env 文件，并以 `EXPO_PUBLIC_[NAME]=VALUE` 的形式在新行中添加特定于环境的变量：
¥Create a **.env** file in the root of your project directory and add environment-specific variables on new lines in the form of `EXPO_PUBLIC_[NAME]=VALUE`:
```bash .env
EXPO_PUBLIC_API_URL=https://staging.example.com
EXPO_PUBLIC_API_KEY=abc123
```
现在你可以直接在源代码中使用环境变量：
¥Now you can use environment variables directly in your source code:
```tsx
import { Button } from 'react-native';
function Post() {
  const apiUrl = process.env.EXPO_PUBLIC_API_URL;
  async function onPress() {
    await fetch(apiUrl, { ... })
  }
  return <Button onPress={onPress} title="Post" />;
}
```
当你运行 `npx expo start` 时，应用包中的 `process.env.EXPO_PUBLIC_API_URL` 将被替换为 `https://staging.example.com`。你可以在编辑代码时更新变量，而无需重新启动 Expo CLI 或清除缓存。你将需要执行完全重新加载（例如，摇动手势，然后在 Expo Go 或你的开发版本中重新加载）才能查看更新的值。
¥When you run `npx expo start`, `process.env.EXPO_PUBLIC_API_URL` will be replaced with `https://staging.example.com` in your app bundle. Variables can be updated as you edit your code without restarting the Expo CLI or clearing the cache. You will need to perform a full reload (for example, shake gesture and then Reload in Expo Go or your development build) to see the updated value.
>  **warning** 不要在 `EXPO_PUBLIC_` 变量中存储敏感信息，例如私钥。这些变量将以纯文本形式在编译的应用中可见。
>
> ¥Do not store sensitive info, such as private keys, in `EXPO_PUBLIC_` variables. These variables will be visible in plain-text in your compiled application.
<a id="how-variables-are-loaded"></a>
### 变量如何加载
¥How variables are loaded
Expo CLI 根据 [标准 .env 文件解析](https://github.com/bkeepers/dotenv/blob/c6e583a/README.md#what-other-env-files-can-i-use) 加载 .env 文件，然后将代码中对 `process.env.EXPO_PUBLIC_[VARNAME]` 的所有引用替换为 .env 文件中设置的相应值。出于安全目的，node_modules 内的代码不会受到影响。
¥Expo CLI loads **.env** files according to the [standard .env file resolution](https://github.com/bkeepers/dotenv/blob/c6e583a/README.md#what-other-env-files-can-i-use) and then replaces all references in your code to `process.env.EXPO_PUBLIC_[VARNAME]` with the corresponding value set in the **.env** files. Code inside **node_modules** is not affected for security purposes.
<a id="how-to-read-from-environment-variables"></a>
### 如何读取环境变量
¥How to read from environment variables
*  每个环境变量都必须使用 JavaScript 的点表示法静态引用为 `process.env` 的属性，才能内联。例如，表达式 `process.env.EXPO_PUBLIC_KEY` 有效并且将被内联。
  ¥<YesIcon small /> **Every environment variable must be statically referenced as a property of
  `process.env` using JavaScript's dot notation for it to be inlined.** For example, the expression
  `process.env.EXPO_PUBLIC_KEY` is valid and will be inlined.
*  不支持表达式的替代版本。例如，`process.env['EXPO_PUBLIC_KEY']` 或 `const {EXPO_PUBLIC_X} = process.env` 无效，不会被内联。
  ¥<NoIcon small /> **Alternative versions of the expression are not supported**. For example,
  `process.env['EXPO_PUBLIC_KEY']` or `const {EXPO_PUBLIC_X} = process.env` is invalid and will not
  be inlined.
<a id="using-multiple-env-files-to-define-separate-environments"></a>
### 使用多个 .env 文件定义单独的环境
¥Using multiple .env files to define separate environments
你可以定义任何 [标准 .env 文件](https://github.com/bkeepers/dotenv/blob/c6e583a/README.md#what-other-env-files-can-i-use) 文件，因此可以使用单独的 .env 和 .env.local 文件，它们将根据标准优先级加载。
¥You can define any of the [standard .env files](https://github.com/bkeepers/dotenv/blob/c6e583a/README.md#what-other-env-files-can-i-use), so it is possible to have separate **.env** and **.env.local**, files and they will load according to the standard priority.
你可以选择提交默认的 .env 文件或其他标准配置，但通常应该将 .env.local 文件添加到你的 .gitignore 文件中，因为它们用于指定特定于你本地计算机的环境配置（例如，如果你需要它来向本地服务器发出请求，则需要你的网络 IP 地址）。
¥You may choose to commit the default **.env** file or other standard configurations, but generally **.env.local** files should be added to your **.gitignore**, because they are used to specify environment configuration specific to your local machine (such as, for example, your network IP address if you need it to make a request against a local server).
```bash .gitignore
.env*.local
```
<a id="environment-variables-and-node_env"></a>
#### 环境变量和 `NODE_ENV`
¥Environment variables and `NODE_ENV`
我们建议不要使用 `NODE_ENV` 在 .env 文件（例如 .env.test 和 .env.production）之间切换。虽然技术上可行（`NODE_ENV=test npx expo start` 将加载 .env.test），但它的行为可能与你预期的不同。例如，`npx expo export` 始终强制 `NODE_ENV` 执行 `production`，因此 `NODE_ENV=test npx expo export` 实际上不会在 `NODE_ENV` 设置为 `test` 的情况下运行该命令。
¥We recommend against using `NODE_ENV` to switch between **.env** files (such as **.env.test** and **.env.production**). While it is technically possible (`NODE_ENV=test npx expo start` will load **.env.test**) — it may not behave as you would expect. For example, `npx expo export` always forces `NODE_ENV` to `production`, so `NODE_ENV=test npx expo export` will not actually run the command with the `NODE_ENV` set to `test`.
其他基于 Expo CLI 命令构建的工具也会表现出相同的行为 - 例如，`eas update` 调用 `npx expo export`，因此，`NODE_ENV=test eas update` 同样不会在 `NODE_ENV` 设置为 `test` 的情况下运行（它将设置为 `production`）。许多工具以不同的方式使用 `NODE_ENV` 环境变量（例如，如果你运行 `NODE_ENV=production npm install`，则不会安装 `devDependencies`），我们发现对于 React Native 项目，最好不要为此用例进一步重载它。
¥Other tools that build on top of Expo CLI commands will exhibit the same behavior — for example, `eas update` calls into `npx expo export` and, as a result, `NODE_ENV=test eas update` will similarly not run with the `NODE_ENV` set to `test` (it will be `production`). The `NODE_ENV` environment variable is used by many tools in different ways (for example, if you run `NODE_ENV=production npm install` then your `devDependencies` will not be installed) and we have found that for React Native projects, it's best not to overload it further for this use case.
如果你使用 EAS，请考虑改用 `eas env:pull`。这会将你的 .env.local 与你选择的环境进行交换，而不是依赖于 `NODE_ENV`。你可以在不使用 EAS 的情况下，通过编写脚本，用你希望使用的环境的相应内容覆盖 .env.local 或 .env 文件来实现类似的行为。
¥If you use EAS, consider using `eas env:pull` instead. This will swap your **.env.local** with an environment of your choice, rather than depending on `NODE_ENV`. You can accomplish a similar behavior without EAS by writing a script to overwrite **.env.local** or **.env** with the appropriate contents for the environment you wish to work with.
<a id="disabling-environment-variables"></a>
### 禁用环境变量
¥Disabling environment variables
Expo CLI 中的环境变量有两部分，并且都可以禁用：
¥Environment variables in Expo CLI have two parts and both can be disabled:
1. Expo CLI 自动将 .env 文件加载到全局进程中。要禁用此行为，请在运行任何 Expo CLI 命令之前将环境变量 `EXPO_NO_DOTENV` 设置为 `1`：`EXPO_NO_DOTENV=1`。
   ¥Expo CLI automatically loads the **.env** files into the global process. To disable this behavior, set the environment variable `EXPO_NO_DOTENV` to `1` before running any Expo CLI command: `EXPO_NO_DOTENV=1`.
2. Expo 的 Metro 配置包括客户端 JavaScript 包中环境变量的内联序列化。要禁用此行为，你可以使用 `EXPO_NO_CLIENT_ENV_VARS=1`。
   ¥Expo's Metro config includes the inline serialization of environment variables in the client JavaScript bundle. To disable this behavior, you can use `EXPO_NO_CLIENT_ENV_VARS=1`.
如果你遇到环境变量问题，可以尝试禁用其中一项或两项功能。
¥If you're experiencing issues with environment variables, you can try disabling one or both of these features.
<a id="environment-variables-in-expo-application-services"></a>
## Expo 应用服务中的环境变量
¥Environment variables in Expo Application Services
<a id="eas-build"></a>
### EAS 构建
¥EAS Build
[EAS 构建](/build/introduction/) 使用 Metro Bundler 构建嵌入在应用二进制文件中的 JavaScript 包，因此它将使用随构建作业上传的 .env 文件将 `EXPO_PUBLIC_` 变量内联到你的代码中。EAS Build 还允许你在 eas.json 的构建配置文件中以及通过 EAS Secrets 定义环境变量。查看 [环境变量和构建秘密](/build-reference/variables/) 上的 EAS 构建文档以获取更多信息。
¥[EAS Build](/build/introduction/) uses Metro Bundler to build the JavaScript bundle embedded within your app binary, so it will use **.env** files uploaded with your build job to inline `EXPO_PUBLIC_` variables into your code. EAS Build also lets you define environment variables within build profiles in **eas.json** and via EAS Secrets. Check out the EAS Build documentation on [environment variables and build secrets](/build-reference/variables/) for more information.
<a id="eas-update"></a>
### EAS 更新
¥EAS Update
[EAS 更新](/eas-update/introduction) 在本地环境或 CI 中使用 Metro Bundler 来构建应用包，因此它将使用可用的 .env 文件将 `EXPO_PUBLIC_` 变量内联到你的代码中。查看 [环境变量](/eas-update/environment-variables/) 上的 EAS 更新文档以了解更多信息。
¥[EAS Update](/eas-update/introduction) uses Metro Bundler in your local environment or CI to build your app bundle, so it will use available **.env** files to inline `EXPO_PUBLIC_` variables into your code. Check out the EAS Update documentation on [environment variables](/eas-update/environment-variables/) for more information.
<a id="migrating-to-expo-environment-variables"></a>
## 迁移到 Expo 环境变量
¥Migrating to Expo environment variables
<a id="from-react-native-config"></a>
### 来自 react-native-config
¥From react-native-config
更新你的 .env 文件，以在 JavaScript 代码中使用的任何变量添加 `EXPO_PUBLIC_` 前缀：
¥Update your **.env** files to prefix any variables used within your JavaScript code with `EXPO_PUBLIC_`:
```diff .env
- API_URL=https://myapi.com
+ EXPO_PUBLIC_API_URL=https://myapi.com
```
> 如果你有任何非标准 .env 文件（例如 .env.staging），你将需要将它们迁移到 [标准 .env 文件](https://github.com/bkeepers/dotenv/blob/c6e583a/README.md#what-other-env-files-can-i-use).1.1 或 .env.staging 之一。
>
> ¥If you have any non-standard **.env** files (for example, **.env.staging**), you will need to migrate those to one of the [standard .env files](https://github.com/bkeepers/dotenv/blob/c6e583a/README.md#what-other-env-files-can-i-use).
然后更新你的代码以使用 `process.env.EXPO_PUBLIC_[VARNAME]`：
¥Then update your code to use `process.env.EXPO_PUBLIC_[VARNAME]`:
```diff
- import Config from 'react-native-config';
- const apiUrl = Config.API_URL;
+ const apiUrl = process.env.EXPO_PUBLIC_API_URL;
```
<a id="from-babel-plugin-transform-inline-environment-variables"></a>
### 来自 babel-plugin-transform-inline-environment-variables
¥From babel-plugin-transform-inline-environment-variables
使用 Babel 插件来转换代码中的环境变量引用与 Expo 环境变量的工作方式类似。在 .env 文件中设置变量并更新变量名称以使用 `EXPO_PUBLIC_` 前缀：
¥Using a Babel plugin to transform your environment variable references in your code is similar to how Expo environment variables work. Set your variables inside a **.env** file and update your variable names to use the `EXPO_PUBLIC_` prefix:
```diff
- const apiUrl = process.env.API_URL;
+ const apiUrl = process.env.EXPO_PUBLIC_API_URL;
```
然后你可以从你的 [Babel 配置](/versions/latest/config/babel/) 中删除插件：
¥Then you can remove the plugin from your [Babel config](/versions/latest/config/babel/):
```diff babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
--    plugins: ['transform-inline-environment-variables'],
  };
};
```
更新 Babel 配置文件后，请务必使用 `npx expo start --clear` 清除缓存。
¥After updating your Babel config file, be sure to clear your cache with `npx expo start --clear`.
<a id="from-direnv"></a>
### 来自 direnv
¥From direnv
将 JavaScript 中使用的任何环境变量从其 .envrc 文件移动到 .env 文件，并在其前面加上 `EXPO_PUBLIC_` 前缀。
¥Move any environment variables used in your JavaScript from their **.envrc** file to a **.env** file and prefix it with `EXPO_PUBLIC_`.
以前使用 `direnv` 时，你需要使用从 [`process.env`](https://nodejs.cn/dist/latest/docs/api/process.html#process_process_env) 读取的 [动态应用配置](/versions/latest/config/app/#app-config) 在 `extra` 字段上设置环境变量，以便可以通过 [`expo-constants`](/versions/latest/sdk/constants) 在 JavaScript 代码中使用它们。将这些引用直接移到你的代码中，添加 `EXPO_PUBLIC_` 前缀：
¥Previously with `direnv`, you would need to use a [dynamic app config](/versions/latest/config/app/#app-config) that reads from [`process.env`](https://nodejs.cn/dist/latest/docs/api/process.html#process_process_env) to set environment variables on the `extra` field so they can be used in your JavaScript code via [`expo-constants`](/versions/latest/sdk/constants). Move those references directly into your code, adding the `EXPO_PUBLIC_` prefix:
```diff
- import Constants from 'expo-constants';
- const apiUrl = Constants.expoConfig.extra.apiUrl;
+ const apiUrl = process.env.EXPO_PUBLIC_API_URL;
```
> [`direnv`](https://direnv.net/) 根据当前目录自动加载和卸载 shell 中的环境变量，这意味着它可以直接影响在其中运行的任何进程的环境，而不仅仅是 Expo CLI。你可能希望继续将 `direnv` 用于 JavaScript 代码中未使用的其他环境变量。
>
> ¥[`direnv`](https://direnv.net/) automatically loads and unloads environment variables in your shell depending on your current directory, meaning it can affect the environment for any process running in that directly, not just the Expo CLI. You will likely want to continue using `direnv` for other environment variables that are not used in your JavaScript code.
<a id="security-considerations"></a>
## 安全考虑
¥Security considerations
切勿将敏感密钥存储在前缀为 `EXPO_PUBLIC_` 的环境变量中。当终端用户运行你的应用时，他们可以访问你的应用中的所有代码和嵌入的环境变量。了解有关 [存储敏感信息](https://rn.nodejs.cn/docs/security#storing-sensitive-info) 的更多信息。
¥Never store sensitive secrets in environment variables that are prefixed with `EXPO_PUBLIC_`. When an end-user runs your app, they have access to all of the code and embedded environment variables in your app. Read more about [storing sensitive info](https://rn.nodejs.cn/docs/security#storing-sensitive-info).


# 链接

## 链接、深层链接、Android 应用链接和 iOS 通用链接概述

关于在你的 Expo 应用中实现链接和深层链接的可用资源的概述。

<a id="linking"></a>
## 链接
¥Linking
链接允许你的应用与传入和传出 URL 进行交互。在此过程中，用户不仅会被引导打开你的应用，而且还会被带到应用内的特定屏幕（路由）。
¥Linking allows your app to interact with incoming and outgoing URLs. In this process, the user not only gets directed to open your app, but they are taken to a specific screen (route) within the app.
Video Tutorial: [Watch: Setting up linking with Expo](https://www.youtube.com/watch?v=kNbEEYlFIPs)
<a id="linking-strategies"></a>
### 链接策略
¥Linking strategies
你在 Expo 应用中处理不同的链接策略：
¥There are different linking strategies you handle in your Expo app:
* 使用你的 Web 域链接链接到你的应用（[通用链接](#universal-linking) 使用 `https` 或 `http` 方案）
  ¥Linking to your app using your web domain links ([universal linking](#universal-linking) using the `https` or `http` scheme)
* 使用自定义方案（深层链接）从其他应用或网站链接到你的应用
  ¥Linking to your app from other apps or websites using a custom scheme (deep links)
* 从你的应用链接到其他应用（传出链接）
  ¥Linking to other apps from your app (outgoing links)
>  **info** 提示：Expo Go 中对传入链接的支持有限。我们建议使用 [开发构建](/develop/development-builds/introduction/) 来测试你的应用的链接策略。
>
> ¥**Tip:** Support for incoming links in Expo Go is limited. We recommend using [Development builds](/develop/development-builds/introduction/) to test your app's linking strategies.
<a id="universal-linking"></a>
## 更新底部选项卡导航器外观
¥Universal linking
如果安装了应用，Android 和 iOS 都实现了自己的系统来将 Web URL 路由到应用。在 Android 上，此系统称为 App Links，在 iOS 上称为 Universal Links。这两个系统的先决条件是你有一个 Web 域，你可以在其中托管一个文件来验证你对域的控制。
¥Both Android and iOS implement their own systems for routing web URL's to an app if the app is installed. On Android, this system is called App Links, and on iOS it is called Universal Links. The pre-requisite for both systems is that you have a web domain where you can host a file which verifies you control the domain.
<a id="android-app-links"></a>
### 安卓应用链接
¥Android App Links
Android App Links 与 [支持的 SDK 版本](#linking-to-your-app-from-other-apps-or-websites) 不同，因为它们使用常规 HTTP 和 HTTPS 方案并且是 Android 设备独有的。
¥Android App Links are different from [standard deep links](#linking-to-your-app-from-other-apps-or-websites) as they use regular HTTP and HTTPS schemes and are exclusive to Android devices.
此链接类型允许你的应用在用户单击链接时始终打开，而不是从设备上显示的对话框中选择浏览器或其他处理程序。如果用户未安装你的应用，则链接会将他们带到你应用的关联网站。
¥This link type allows your app to always open when a user clicks the link instead of choosing between the browser or another handler from a dialog displayed on the device. If the user doesn't have your app installed, the link takes them to your app's associated website.
<a id="ios-universal-links"></a>
### iOS 通用链接
¥iOS Universal Links
iOS 通用链接与 [支持的 SDK 版本](#linking-to-your-app-from-other-apps-or-websites) 不同，因为它们使用常规 HTTP 和 HTTPS 方案，并且是 iOS 设备独有的。
¥iOS Universal Links are different from [standard deep links](#linking-to-your-app-from-other-apps-or-websites) as they use regular HTTP and HTTPS schemes and are exclusive to iOS devices.
此链接类型允许你的应用在用户单击指向你的网络域的 HTTP(S) 链接时打开。如果用户未安装你的应用，则链接会将他们带到你应用的关联网站。你可以通过显示横幅让用户使用 [苹果智能横幅](/linking/ios-universal-links/#apple-smart-banner) 打开你的应用来进一步配置网站。
¥This link type allows your app to open when a user clicks an HTTP(S) link pointing to your web domain. If the user doesn't have your app installed, the link takes them to your app's associated website. You can further configure the website by displaying a banner for the user to open your app using [Apple Smart Banner](/linking/ios-universal-links/#apple-smart-banner).
<a id="linking-to-your-app-from-other-apps-or-websites"></a>
## 从其他应用链接到你的应用或网站
¥Linking to your app from other apps or websites
[深层链接](https://en.wikipedia.org/wiki/Deep_linking) 是指向应用或网站内特定基于 URL 的内容的链接。
¥[Deep Links](https://en.wikipedia.org/wiki/Deep_linking) are links to a specific URL-based content inside an app or a website.
例如，通过点击产品广告，你的应用将在用户的设备上打开，他们可以查看该产品的详细信息。用户单击的此产品链接可能看起来像（或者由设置 `window.location.href` 的 JavaScript 调用）：
¥For example, by clicking a product advertisement, your app will open on the user's device and they can view that product's details. This product's link that the user clicked may look like (or alternatively be invoked by JavaScript with setting `window.location.href`):
```html
<a href="myapp://web-app.com/product">View Product</a>
```
此链接由三部分构成：
¥This link is constructed by three parts:
* 方案：标识应打开 URL 的应用的 URL 方案（例如：`myapp://`）。对于非标准深层链接，它也可以是 `https` 或 `http`。我们建议使用 [通用链接](#universal-linking) 进行基于 http(s) 的深层链接。
  ¥**Scheme**: The URL scheme that identifies the app that should open the URL (example: `myapp://`). It can also be `https` or `http` for non-standard deep links. We recommend [universal linking](#universal-linking) for http(s)-based deep links.
* 主机：应打开 URL 的应用的域名（例如：`web-app.com`）。
  ¥**Host**: The domain name of the app that should open the URL (example: `web-app.com`).
* 路径：应打开的屏幕的路径（例如：`/product`）。如果未指定路径，用户将进入应用的主屏幕。
  ¥**Path**: The path to the screen that should be opened (example: `/product`). If the path isn't specified, the user is taken to the home screen of the app.
<a id="use-expo-router-to-handle-deep-linking"></a>
### 使用配置插件进行原生项目配置
¥Use Expo Router to handle deep linking
要实现上述任何链接策略，我们建议使用 [Expo 路由](/router/introduction/)，因为深度链接会自动为你应用的所有屏幕启用。
¥To implement any of the above Linking strategies, **we recommend using** [Expo Router](/router/introduction/) since deep linking is automatically enabled for all of your app's screens.
**好处：**
¥**Benefits:**
* Expo Router 中的 `Link` 组件可用于 [处理到其他应用的 URL 方案](/linking/into-other-apps/#expo-router)
  ¥`Link` component from Expo Router can be used to [handle URL schemes to other apps](/linking/into-other-apps/#expo-router)
* Android App Links 和 iOS Universal Links 需要在 JavaScript 中为应用中的链接配置运行时路由。使用 Expo Router，你不必单独配置运行时路由，因为所有路由的深层链接都会自动启用。
  ¥Android App Links and iOS Universal Links require configuring runtime routing in JavaScript for the link in your app. Using Expo Router, you don't have to configure runtime routing separately since deep links for all routes are automatically enabled.
* 对于第三方深层链接，你可以覆盖默认链接行为以处理传入链接并发送导航事件。参见 [自定义链接](/router/advanced/native-intent)。
  ¥For third-party deep links, you can override the default linking behavior to handle incoming links and send navigation events. See [Customizing links](/router/advanced/native-intent).
<a id="linking-to-other-apps-from-your-app"></a>
## 从你的应用链接到其他应用
¥Linking to other apps from your app
使用基于目标应用的 URL 方案的 URL 可以从你的应用链接到其他应用。此 URL 方案允许你引用该原生应用中的资源。
¥Linking to other apps from your app is achieved using a URL based on the target app's URL scheme. This **URL scheme** allows you to reference resources within that native app.
你的应用可以使用 [通用 URL 方案](/linking/into-other-apps/#common-url-schemes) 作为默认应用，包括 `https` 和 `http`（通常由 Chrome、Safari 等 Web 浏览器使用），并使用 JavaScript 调用启动相应原生应用的 URL。
¥Your app can use a [common URL scheme](/linking/into-other-apps/#common-url-schemes) for default apps, including `https` and `http` (commonly used by web browsers like Chrome, Safari, and so on), and use JavaScript to invoke the URL that launches the corresponding native app.


## 链接到其他应用

了解如何根据另一个应用的 URL 方案处理和打开应用中的 URL。

通过使用目标应用的 URL，可以处理从你的应用链接到其他应用。你可以使用两种方法从你的应用打开此类 URL：
¥Handling linking into other apps from your app is achieved by using the target app's URL. There are two methods you can use to open such URLs from your app:
* 使用 [`expo-linking`](/versions/latest/sdk/linking) API
  ¥Using the [`expo-linking`](/versions/latest/sdk/linking) API
* 使用 Expo Router 的 [`Link` 组件](/develop/file-based-routing/#how-does-link-work)
  ¥Using Expo Router's [`Link` component](/develop/file-based-routing/#how-does-link-work)
<a id="using-expo-linking-api"></a>
## 使用旧版 FileSystem API
¥Using expo-linking API
[`expo-linking`](/versions/latest/sdk/linking) API 提供了对原生链接 API（例如 Web 上的 `window.history`）的通用抽象，并为你的应用提供了与其他已安装应用交互的实用程序。
¥The [`expo-linking`](/versions/latest/sdk/linking) API provides a universal abstraction over native linking APIs (such as `window.history` on the web) and offers utilities for your app to interact with other installed apps.
以下示例使用 [`Linking.openURL`](/versions/latest/sdk/linking/#linkingopenurlurl) 在操作系统的默认浏览器中打开 [通用 URL 方案](#common-url-schemes)：
¥The example below opens at the [common URL scheme](#common-url-schemes) in the default browser of the operating system using [`Linking.openURL`](/versions/latest/sdk/linking/#linkingopenurlurl):
```tsx index.tsx|collapseHeight=240
import { Button, View, StyleSheet } from 'react-native';
import * as Linking from 'expo-linking';
export default function Home() {
  return (
    <View style={styles.container}>
      <Button title="Open a URL" onPress={() => Linking.openURL('https://expo.dev/')} />
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
<a id="using-expo-routers-link-component"></a>
## 在 Expo Router 应用中使用 React Server Components
¥Using Expo Router's `Link` component
如果你的项目使用 [Expo 路由](/router/introduction/)，请使用 `Link` 组件打开 URL。它在原生平台上封装一个 `<Text>` 组件，在 Web 上封装一个 `<a>` 元素。它还使用 `expo-linking` API 来处理 URL 方案。
¥If your project uses [Expo Router](/router/introduction/), use the `Link` component to open a URL. It wraps a `<Text>` component on native platforms and an `<a>` element on the web. It also uses the `expo-linking` API to handle URL schemes.
以下示例在操作系统的默认浏览器中打开 [通用 URL 方案](#common-url-schemes) (HTTPS)：
¥The example below opens a [common URL scheme](#common-url-schemes) (HTTPS) in the default browser of the operating system:
```tsx index.tsx|collapseHeight=240
import { Button, View, StyleSheet } from 'react-native';
import { Link } from 'expo-router';
export default function Home() {
  return (
    <View style={styles.container}>
      <Link href="https://expo.dev">Open a URL</Link>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
<a id="common-url-schemes"></a>
## 常见 URL 方案
¥Common URL schemes
有内置的 URL 方案，可在所有平台上提供对核心功能的访问。以下是常用方案列表：
¥There are built-in URL schemes that provide access to core functionality on all platforms. Here is a list of commonly-used schemes:
| 方案               | 描述         | 示例                        |
| ---------------- | ---------- | ------------------------- |
| `https` / `http` | 打开网络浏览器应用。 | `https://expo.dev`        |
| `mailto`         | 打开邮件应用。    | `mailto:support@expo.dev` |
| `tel`            | 打开调用应用。    | `tel:+123456789`          |
| `sms`            | 打开短信应用。    | `sms:+123456789`          |
Note: Specify Android intents to handle common URL schemes
---
For Android 11 (API level 30) and above, you must specify the intents your app will handle in the **AndroidManifest.xml** file. You can accomplish this by [creating a config plugin](/config-plugins/plugins-and-mods/#create-a-plugin).
The following config plugin example enables linking to email and phone apps by defining the intents:
```ts my-plugin.ts|collapseHeight=300
import { withAndroidManifest, ConfigPlugin } from 'expo/config-plugins';
const withAndroidQueries: ConfigPlugin = config => {
  return withAndroidManifest(config, config => {
    config.modResults.manifest.queries = [
      {
        intent: [
          {
            action: [{ $: { 'android:name': 'android.intent.action.SENDTO' } }],
            data: [{ $: { 'android:scheme': 'mailto' } }],
          },
          {
            action: [{ $: { 'android:name': 'android.intent.action.DIAL' } }],
          },
        ],
      },
    ];
    return config;
  });
};
module.exports = withAndroidQueries;
```
After creating the config plugin, [导入自定义配置插件](/config-plugins/plugins-and-mods/#import-a-plugin) under the `plugins` property:
```json app.json
{
  "expo": {
    "plugins": [
      "./my-plugin.ts"
    ]
  }
}
```
> **info** **Tip**: On Android, you can use `expo-intent-launcher` to open a **specific settings screen** on the device. See [`expo-intent-launcher` API reference](/versions/latest/sdk/intent-launcher/#enums) to view the list of available intents.
---
## Custom URL schemes
> If you know the custom scheme for the app you want to open, you can link to it using any of the methods: [Using `expo-linking` API](#using-expo-linking-api) or [Using `Link` from Expo Router](#using-expo-routers-link-component).
Some services provide documentation on how to use their app's custom URL schemes. For example, [Uber's deep linking documentation](https://developer.uber.com/docs/riders/ride-requests/tutorials/deep-links/introduction#standard-deep-links) describes how to link directly to a specific pickup location and destination:
```shell
uber://?client_id=<CLIENT_ID>&action=setPickup&pickup[latitude]=37.775818&pickup[longitude]=-122.418028&pickup[nickname]=UberHQ&pickup[formatted_address]=1455%20Market%20St%2C%20San%20Francisco%2C%20CA%2094103&dropoff[latitude]=37.802374&dropoff[longitude]=-122.405818&dropoff[nickname]=Coit%20Tower&dropoff[formatted_address]=1%20Telegraph%20Hill%20Blvd%2C%20San%20Francisco%2C%20CA%2094133&product_id=a1111c8c-c720-46c3-8534-2fcdd730040d&link_text=View%20team%20roster&partner_deeplink=partner%3A%2F%2Fteam%2F9383
```
In the example above, if the user does not have the Uber app installed on their device, your app can direct them to the Google Play Store or Apple App Store to install it. We recommend using the [`react-native-app-link`](https://github.com/FiberJW/react-native-app-link) library to handle these scenarios.
Note: Specify custom schemes for iOS
---
On iOS, using [`Linking.canOpenURL`](/versions/latest/sdk/linking/#linkingcanopenurlurl) to query other apps's linking schemes requires additional configuration in **InfoPlist**. You can use the [`ios.infoPlist`](/versions/latest/config/app/#infoplist) property in your app config to specify a list of schemes your app is allowed to query. For example:
```json app.json
{
  "expo": {
    "ios": {
      "infoPlist": {
        "LSApplicationQueriesSchemes": ["uber"]
      }
    }
  }
}
```
If your don't specify this list, `Linking.canOpenURL` may return `false` even if the device has the target app installed.
> **info** **Tip**: To test the configuration described above from an iOS device, [use a development build](/develop/development-builds/introduction/). It cannot be tested with Expo Go.
---
## Create URLs
You can use [`Linking.createURL`](/versions/latest/sdk/linking/#linkingcreateurlurl) to create a URL that can be used to open or redirect back to your app. This method resolves to the following:
- **Production and development builds**: `myapp://`, where `myapp` is the [custom scheme](/linking/into-your-app/#add-a-scheme-in-app-config) defined in the app config
- **Development in Expo Go**: `exp://127.0.0.1:8081`
Using `Linking.createURL` helps you avoid hardcoding URLs. You can modify the returned URL by passing optional parameters to this method.
To pass data to your app, you can append it as a path or query string to the URL. `Linking.createURL` will construct a working URL automatically. For example:
```tsx Example
const redirectUrl = Linking.createURL('path/into/app', {
  queryParams: { hello: 'world' },
});
```
This will resolve into the following, depending on the environment:
- **Production and development builds**: `myapp://path/into/app?hello=world`
- **Development in Expo Go**: `exp://127.0.0.1:8081/--/path/into/app?hello=world`
Note: Using Expo Go for testing?
---
For apps that require a stable URL (for example, auth provider redirects), use a development build with a custom scheme instead of using Expo Go. For more details on how to create and test a custom scheme, see [Linking into your app](/linking/into-your-app/).
---
## In-app browsers
The `expo-linking` API allows you to open a URL using the operating system's default web browser app. You can use the [`expo-web-browser`](/versions/latest/sdk/webbrowser) library to open URLs in an in-app browser. For example, an in-app browser is useful for secure [authentication](/guides/authentication).
Note: Example of opening a URL in an in-app browser
---
The example below simulates the behavior of opening a URL in an in-app browser using `expo-web-browser` and the default or preferred web browser using `expo-linking`:
#### WebBrowser compared to Linking
```tsx
import { Button, View, StyleSheet } from 'react-native';
import * as Linking from 'expo-linking';
import * as WebBrowser from 'expo-web-browser';
export default function Home() {
  return (
    <View style={styles.container}>
      <Button
        title="Open URL with the system browser"
        onPress={() => Linking.openURL('https://expo.dev')}
        style={styles.button}
      />
      <Button
        title="Open URL with an in-app browser"
        onPress={() => WebBrowser.openBrowserAsync('https://expo.dev')}
        style={styles.button}
      />
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  button: {
    marginVertical: 10,
  },
});
```
---
<a id="additional-link-functionality-on-web"></a>
## 网页端的附加链接功能
¥Additional link functionality on web
为了在网页端提供附加链接功能，例如右键单击复制或悬停预览，你可以使用 [`expo-router`](/router/introduction/) 库中的 `Link` 组件。
¥To provide additional link functionality on the web, such as right-click to copy or hover to preview, you can use a `Link` component from the [`expo-router`](/router/introduction/) library.
```tsx index.tsx
import { Link } from 'expo-router';
export default function Home() {
  return <Link href="https://expo.dev">Go to Expo</Link>;
}
```
或者，你可以使用 [`@expo/html-elements`](https://www.npmjs.com/package/@expo/html-elements) 库来使用通用的 `<A>` 元素：
¥Alternatively, you can use the [`@expo/html-elements`](https://www.npmjs.com/package/@expo/html-elements) library to use a universal `<A>` element:
```tsx index.tsx
import { A } from '@expo/html-elements';
export default function Home() {
  return <A href="https://expo.dev">Go to Expo</A>;
}
```
`<A>` 组件在网页端渲染 `<a>`，并在原生平台上渲染使用 `expo-linking` API 的交互式 `<Text>`。
¥The `<A>` component renders an `<a>` on the web and an interactive `<Text>`that uses the `expo-linking` API on native platforms.


## 链接到你的应用

了解如何通过创建深层链接来处理 React Native 和 Expo 应用中的传入 URL。

本指南提供了通过添加自定义方案在项目中配置标准深层链接的步骤。
¥This guide provides steps to configure standard **deep links** in your project by adding a custom scheme.
>  **info** 对于大多数应用，你可能希望设置 [Android App/iOS 通用链接](/linking/overview/#universal-linking) 而不是本指南中描述的深层链接，或者同时设置两者。
>
> ¥For most apps, you probably want to set up [Android App/iOS Universal Links](/linking/overview/#universal-linking) instead of the deep links described in this guide or set up both.
<a id="add-a-custom-scheme-in-app-config"></a>
## 在应用配置中添加自定义方案
¥Add a custom scheme in app config
要提供指向你的应用的链接，请在 [应用配置](/workflow/configuration/) 中的 [`scheme`](/versions/latest/config/app/#scheme) 属性中添加自定义字符串：
¥To provide a link to your app, add a custom string to the [`scheme`](/versions/latest/config/app/#scheme) property in the [app config](/workflow/configuration/):
```json app.json
{
  "expo": {
    "scheme": "myapp"
  }
}
```
在向你的应用添加自定义方案后，你需要 [创建新的开发版本](/develop/development-builds/create-a-build/)。一旦应用安装在设备上，你就可以使用 `myapp://` 在应用内打开链接。
¥After adding a custom scheme to your app, you need to [create a new development build](/develop/development-builds/create-a-build/). Once the app is installed on a device, you can open links within your app using `myapp://`.
如果未定义自定义方案，应用将在开发和生产版本中使用 `android.package` 和 `ios.bundleIdentifier` 作为默认方案。这是因为 [Expo 预建](/workflow/prebuild/) 会自动将这些属性添加为 Android 和 iOS 的自定义方案。
¥If the **custom scheme is not defined**, the app will use `android.package` and `ios.bundleIdentifier` as the default schemes in both development and production builds. This is because [Expo Prebuild](/workflow/prebuild/) automatically adds these properties as custom schemes for Android and iOS.
<a id="test-the-deep-link"></a>
## 测试更新
¥Test the deep link
你可以使用 [`npx uri-scheme`](https://github.com/expo/expo/tree/main/packages/uri-scheme#readme) 测试打开应用的链接，[`npx uri-scheme`](https://github.com/expo/expo/tree/main/packages/uri-scheme#readme) 是一个用于交互和测试 URI 方案的命令行实用程序。
¥You can test a link that opens your app using [`npx uri-scheme`](https://github.com/expo/expo/tree/main/packages/uri-scheme#readme), which is a command-line utility for interacting and testing URI schemes.
例如，如果你的应用有一个 `/details` 屏幕，你希望在用户点击链接时打开该屏幕（通过另一个应用或 Web 浏览器），你可以通过运行以下命令来测试此行为：
¥For example, if your app has a `/details` screen that you want to open when a user taps on a link (either through another app or a web browser), you can test this behavior by running the following command:
```sh
$ npx uri-scheme open com.example.app://somepath/details --android
$ npx uri-scheme open myapp://somepath/details --ios
```
运行上述命令：
¥Running the above command:
* 打开你应用的 `/details` 屏幕
  ¥Opens your app's `/details` screen
* `android` 或 `ios` 选项指定应在 Android 或 iOS 上打开链接
  ¥The `android` or `ios` options specify that the link should be opened on Android or iOS
* 或者，你可以尝试通过在设备的 Web 浏览器中单击 `<a href="scheme://">Click me</a>` 之类的链接来打开链接。请注意，在地址栏中输入链接可能无法按预期工作，你可以使用 [通用链接](/linking/overview/#universal-linking) 来实现该功能。
  ¥Alternatively, you can try opening the link by clicking a link like `<a href="scheme://">Click me</a>` in the device's web browser. Note that entering the link in the address bar may not work as expected, and you can use [universal linking](/linking/overview/#universal-linking) to implement that ability.
Note: Test a link using Expo Go
---
By default, [Expo Go](https://expo.dev/go) uses the `exp://` scheme. If you link to `exp://` without specifying a URL address afterward, it will open the app to the home screen. In development, your app's complete URL looks like `exp://127.0.0.1:8081`.
To open the `/details` screen while testing on Expo Go, you can use `npx uri-scheme`:
```sh
$ npx uri-scheme open exp://127.0.0.1:8081/--/somepath/into/app?hello=world --ios
```
In Expo Go, `/--/` is added to the URL when a path is specified. This indicates to Expo Go that the substring after it corresponds to the deep link path and is not part of the path to the app itself.
By default, `exp://` is replaced with `http://` when opening a URL in Expo Go. You can also use `exps://` to open `https://` URLs. However, `exps://` does not currently support loading sites with insecure TLS certificates.
---
## Handle URLs
>
如果你使用的是 [Expo 路由](/linking/overview/#use-expo-router-to-handle-deep-linking)，则可以忽略本节。
¥**info** If you are using [Expo Router](/linking/overview/#use-expo-router-to-handle-deep-linking), you can ignore this section.
你可以使用 [`expo-linking`](/versions/latest/sdk/linking/) 中的 [`Linking.useURL()`](/versions/latest/sdk/linking/#useurl) 钩子观察启动应用的链接。
¥You can observe links that launch your app using the [`Linking.useURL()`](/versions/latest/sdk/linking/#useurl) hook from [`expo-linking`](/versions/latest/sdk/linking/).
```tsx index.tsx
import * as Linking from 'expo-linking';
export default function Home() {
  const url = Linking.useURL();
  return <Text>URL: {url}</Text>;
}
```
`Linking.useURL()` 钩子通过遵循以下命令式方法在后台工作：
¥The `Linking.useURL()` hook works behind the scenes by following these imperative methods:
* 启动应用的链接最初使用 [`Linking.getInitialURL()`](/versions/latest/sdk/linking/#linkinggetinitialurl) 返回
  ¥The link that launched the app is initially returned using [`Linking.getInitialURL()`](/versions/latest/sdk/linking/#linkinggetinitialurl)
* 在应用已打开时触发的任何新链接都可以通过 [`Linking.addEventListener('url', callback)`](/versions/latest/sdk/linking/#linkingaddeventlistenertype-handler) 观察到
  ¥Any new links triggered while the app is already open are observed with [`Linking.addEventListener('url', callback)`](/versions/latest/sdk/linking/#linkingaddeventlistenertype-handler)
<a id="parse-urls"></a>
## 解析 URL
¥Parse URLs
你可以使用 [`Linking.parse()`](/versions/latest/sdk/linking/#linkingparseurl) 方法从 URL 解析路径、主机名和查询参数。此方法提取深度链接信息并考虑非标准实现。
¥You can use the [`Linking.parse()`](/versions/latest/sdk/linking/#linkingparseurl) method to parse the **path**, **hostname**, and **query parameters** from a URL. This method extracts deep linking information and considers nonstandard implementations.
```tsx index.tsx|collapseHeight=440
import * as Linking from 'expo-linking';
export default function Home() {
  const url = Linking.useURL();
  if (url) {
    const { hostname, path, queryParams } = Linking.parse(url);
    console.log(
      `Linked to app with hostname: ${hostname}, path: ${path} and data: ${JSON.stringify(
        queryParams
      )}`
    );
  }
  return (
  )
}
```
<a id="limitations"></a>
## 局限性
¥Limitations
如果用户未安装你的应用，则指向你应用的深层链接将不起作用。[分支](https://www.branch.io/deep-linking/) 等归因服务提供有条件链接到你的应用或网页的解决方案。
¥If a user does not have your app installed, deep links to your app will not work. Attribution services like [Branch](https://www.branch.io/deep-linking/) offer solutions for conditionally linking to your app or web page.
Android App/iOS 通用链接是你可以用来处理此类情况的另一种解决方案。这种类型的链接允许你的应用在用户点击指向你的网络域的 HTTP(S) 链接时打开。如果用户没有安装你的应用，链接会将他们带到你的网站。详细信息请参见 [通用链接](/linking/overview/#universal-linking)。
¥Android App/iOS Universal Links is another solution you can use to handle such cases. This type of linking allows your app to open when a user clicks follows an HTTP(S) link pointing to your web domain. If the user doesn't have your app installed, the link takes them to your website. For more details, see [universal linking](/linking/overview/#universal-linking).


## 安卓应用链接

了解如何配置 Android 应用链接以从标准 Web URL 打开你的 Expo 应用。

要为你的应用配置 Android 应用链接，你需要：
¥To configure Android App Links for your app, you need to:
* 在项目的应用配置中添加 `intentFilters` 并将 `autoVerify` 设置为 true
  ¥Add `intentFilters` and set `autoVerify` to true in your project's app config
* 设置双向关联以验证你的网站和原生应用
  ¥Set up two-way association to verify your website and native app
<VideoBoxLink videoId="kNbEEYlFIPs" time={399} title="Watch: Set up Android App Links with Expo Router" />
<a id="add-intentfilters-to-the-app-config"></a>
## 将 `intentFilters` 添加到应用配置
¥Add `intentFilters` to the app config
通过添加 `android.intentFilters` 属性并将 `autoVerify` 属性设置为 `true` 来配置你的应用配置。指定 `autoVerify` 是 Android App Links 正常工作所必需的。
¥Configure your app config by adding the `android.intentFilters` property and setting the `autoVerify` attribute to `true`. Specifying `autoVerify` is required for Android App Links to work correctly.
以下示例显示了一个基本配置，使你的应用可以出现在标准 Android 对话框中，作为处理指向 `webapp.io` 域的任何链接的选项。它还使用常规 `https` 方案，因为 [安卓应用链接](/linking/overview/#android-app-links) 与 [支持的 SDK 版本](/linking/into-other-apps/) 不同。
¥The following example shows a basic configuration that enables your app to appear in the standard Android dialog as an option for handling any links to the `webapp.io` domain. It also uses the regular `https` scheme since [Android App Links](/linking/overview/#android-app-links) are different from [standard deep links](/linking/into-other-apps/).
```json app.json|collapseHeight=454
{
  "expo": {
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            {
              "scheme": "https",
              "host": "*.webapp.io",
              "pathPrefix": "/records"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}
```
<a id="set-up-two-way-association"></a>
## 在应用/扩展之间共享数据库（iOS）
¥Set up two-way association
要设置网站和 Android 应用之间的双向关联，你需要以下内容：
¥To setup **two-way association** between the website and Android app, you will need the following:
* 网站验证：这需要在 /.well-known 目录中创建一个 assetlinks.json 文件并将其托管在目标网站上。此文件用于验证从给定链接打开的应用是否是正确的应用。
  ¥**Website verification:** This requires creating a **assetlinks.json** file inside the **/.well-known** directory and hosting it on the target website. This file is used to verify that the app opened from a given link is the correct app.
* 原生应用验证：这需要某种形式的引用目标网站域 (URL) 的代码签名。
  ¥**Native app verification:** This requires some form of code signing that references the target website domain (URL).
<a id="create-assetlinksjson-file"></a>
### 创建 assetlinks.json 文件
¥Create assetlinks.json file
Step 1: 
Create an **assetlinks.json** file for the website verification (also known as [digital asset links](https://developers.google.com/digital-asset-links/v1/getting-started) file) at **/.well-known/assetlinks.json**. This file is used to verify that the app opened for a given link.
If you're using Expo Router to build your website (or any other modern React framework such as Remix, Next.js, and so on), create **assetlinks.json** at **public/.well-known/assetlinks.json**. For legacy Expo webpack projects, create the file at **web/.well-known/assetlinks.json**.
Step 2: 
Get the value of `package_name` from your app config, under `android.package`.
Step 3: 
Get the value of `sha256_cert_fingerprints` from your app's signing certificate. If you're using [EAS Build](/build/setup/) to build your Android app, after creating a build:
- Run `eas credentials -p android` command, and select the build profile to get its fingerprint value.
- Copy the fingerprint value listed under `SHA256 Fingerprint`.
Note: Alternate method to obtain the SHA256 certificate fingerprint from Google Play Console
---
If you're not using EAS to manage code signing, you can find the **sha256_cert_fingerprints** by building and submitting your app manually to the [Google Play Console](https://play.google.com/console/):
- Inside the Google Play Console's dashboard, go to **Release > Setup > App Signing**.
- Find the correct **Digital Asset Links JSON** snippet for your app.
- Copy the value looks like `14:6D:E9:83...` and paste it into your **public/.well-known/assetlinks.json** file under `sha256_cert_fingerprints`.
---
Step 4: 
Add `package_name` and `sha256_cert_fingerprints` to the **assetlinks.json** file:
```json public/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example",
      "sha256_cert_fingerprints": [
        // Supports multiple fingerprints for different apps and keys
        "14:6D:E9:83:51:7F:66:01:84:93:4F:2F:5E:E0:8F:3A:D6:F4:CA:41:1A:CF:45:BF:8D:10:76:76:CD"
      ]
    }
  }
]
```
> **info** You can add multiple fingerprints to the `sha256_cert_fingerprints` array to support different variants of your app. For more information, see [Android's documentation on how to declare website associations](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc).
### Host assetlinks.json file
Host the **assetlinks.json** file using a web server with your domain. This file must be served with the content-type `application/json` and accessible over an HTTPS connection. Verify that your browser can access this file by typing the complete URL in the address bar.
### Native app verification
Install the app on an Android device to trigger the [Android app verification](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc) process.
Once you have your app opened, see [Handle links into your app](/linking/into-your-app/#handle-urls) for more information on how to handle inbound links and show the user the content they requested.
## Debugging
The Expo CLI enables you to test Android App Links without deploying a website. Utilizing the [`--tunnel`](/more/expo-cli/#tunneling) functionality, you can forward your dev server to a publicly available HTTPS URL.
Step 1: 
Set the environment variable `EXPO_TUNNEL_SUBDOMAIN=my-custom-domain` where `my-custom-domain` is a unique string that you use during development. This ensures that your tunnel URL is consistent across dev server restarts.
Step 2: 
Add `intentFilters` to your app config as [described above](#add-intentfilters-to-the-app-config). Replace the `host` value with a Ngrok URL: `my-custom-domain.ngrok.io`.
Step 3: 
Start your dev server with the `--tunnel` flag:
```sh
$ npx expo start --tunnel
```
Step 4: 
Compile the development build on your device:
```sh
$ npx expo run:android
```
Step 5: 
Use the following `adb` command to start the intent activity and open the link on your app or type the custom domain link in your device's web browser.
```sh
$ adb shell am start -a android.intent.action.VIEW  -c android.intent.category.BROWSABLE -d "https://my-custom-domain.ngrok.io/" <your-package-name>
```
<a id="troubleshooting"></a>
## 故障排除
¥Troubleshooting
以下是一些在实现 Android 应用链接时帮助你排除故障的常见提示：
¥Here are some common tips to help you troubleshoot when implementing Android App Links:
* 确保你的网站通过 HTTPS 提供服务，并且内容类型为 `application/json`
  ¥Ensure your website is served over HTTPS and with the content-type `application/json`
* [验证 Android 应用链接](https://developer.android.com/training/app-links/verify-android-applinks)
  ¥[Verify Android app links](https://developer.android.com/training/app-links/verify-android-applinks)
* Android 验证可能需要 20 秒或更长时间才能生效，因此请务必等到验证完成。
  ¥Android verification may take 20 seconds or longer to take effect, so be sure to wait until it is completed.
* 如果你更新了 Web 文件，请重建原生应用以在供应商端（Google）触发服务器更新
  ¥If you update your web files, rebuild the native app to trigger a server update on the vendor side (Google)


## iOS 通用链接

了解如何配置 iOS 通用链接以从标准 Web URL 打开你的 Expo 应用。

要为你的应用配置 iOS 通用链接，你需要设置双向关联以验证你的网站和原生应用。
¥To configure iOS Universal Links for your app, you need to set up the **two-way association** to verify your website and native app.
<VideoBoxLink videoId="kNbEEYlFIPs" time={68} title="Watch: Set up iOS Universal Links with Expo Router" />
<a id="set-up-two-way-association"></a>
## 在应用/扩展之间共享数据库（iOS）
¥Set up two-way association
要设置网站和 iOS 应用之间的双向关联，你需要执行以下步骤：
¥To setup **two-way association** between the website and app for iOS, you need to perform the following steps:
* 网站验证：这需要在 /.well-known 目录中创建一个 apple-app-site-association (AASA) 文件并将其托管在目标网站上。此文件用于验证从给定链接打开的应用是否是正确的应用。
  ¥**Website verification:** This requires creating a **apple-app-site-association (AASA)** file inside the **/.well-known** directory and hosting it on the target website. This file is used to verify that the app opened from a given link is the correct app.
* 原生应用验证：这需要某种形式的引用目标网站域 (URL) 的代码签名。
  ¥**Native app verification:** This requires some form of code signing that references the target website domain (URL).
<a id="create-aasa-file"></a>
### 创建 AASA 文件
¥Create AASA file
在 /.well-known 目录内为网站验证创建 apple-app-site-association 文件。此文件指定你的 Apple 开发者团队 ID、打包包标识符以及重定向到原生应用的支持路径列表。
¥Create an **apple-app-site-association** file for the website verification inside the **/.well-known** directory. This file specifies your Apple Developer Team ID, bundle identifier, and a list of supported paths to redirect to the native app.
>  **info** 你可以在项目中运行实验性的 CLI 命令 `npx setup-safari`，以自动将包标识符注册到你的 Apple 账户，为 ID 分配权利，并在商店中创建 iTunes 应用条目。将打印本地设置，你可以跳过以下大部分内容。这是在 iOS 上开始使用通用链接的最简单方法。
>
> ¥You can run the **experimental** CLI command `npx setup-safari` inside your project to automatically register a bundle identifier to your Apple account, assign entitlements to the ID, and create an iTunes app entry in the store. The local setup will be printed and you can skip most the following. This is the easiest way to get started with universal links on iOS.
如果你使用 Expo Router 构建你的网站（或任何其他现代 React 框架，如 Remix、Next.js 等），请在 public/.well-known/apple-app-site-association 创建 AASA 文件。对于旧版 Expo webpack 项目，请在 web/.well-known/apple-app-site-association 创建文件。
¥If you're using Expo Router to build your website (or any other modern React framework such as Remix, Next.js, and so on), create the AASA file at **public/.well-known/apple-app-site-association**. For legacy Expo webpack projects, create the file at **web/.well-known/apple-app-site-association**.
```json public/.well-known/apple-app-site-association
{
  // This section enables Universal Links
  "applinks": {
    "apps": [],
    "details": [
      {
        // Syntax: "<APPLE_TEAM_ID>.<BUNDLE_ID>"
        "appID": "QQ57RJ5UTD.com.example.myapp",
        // All paths that should support redirecting.
        "paths": ["/records/*"]
      }
    ]
  },
  // This section enables Apple Handoff
  "activitycontinuation": {
    "apps": ["<APPLE_TEAM_ID>.<BUNDLE_ID>"]
  },
  // This section enable Shared Web Credentials
  "webcredentials": {
    "apps": ["<APPLE_TEAM_ID>.<BUNDLE_ID>"]
  }
}
```
在上面的例子中：
¥In the above example:
* 任何指向 `https://www.myapp.io/records/*` 的链接（记录 ID 使用通配符匹配）都应由 iOS 设备上具有匹配包标识符的应用直接打开。它是 [苹果团队 ID](https://expo.fyi/apple-team) 和包标识符的组合。
  ¥Any links to `https://www.myapp.io/records/*` (with wildcard matching for the record ID) should be opened directly by the app with a matching bundle identifier on an iOS device. It is a combination of the [Apple Team ID](https://expo.fyi/apple-team) and the bundle identifier.
* `*` 通配符与域或路径分隔符（句点和斜杠）不匹配。
  ¥The `*` wildcard does **not** match domain or path separators (periods and slashes).
* `activitycontinuation` 和 `webcredentials` 对象是可选的，但建议使用。
  ¥The `activitycontinuation` and `webcredentials` objects are optional, but recommended.
> 有关 AASA 格式的更多详细信息，请参阅 [苹果的文档](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html)。Branch 提供了 [AASA 验证器](https://branch.io/resources/aasa-validator/)，它可以帮助你确认你的 AASA 已正确部署并且具有有效的格式。
>
> ¥See [Apple's documentation](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html) for further details on the format of the AASA. Branch provides an [AASA validator](https://branch.io/resources/aasa-validator/) which can help you confirm that your AASA is correctly deployed and has a valid format.
<a id="supporting-details-format"></a>
### Suspense
截至 iOS 13 的 [`details` 格式是支持](https://developer.apple.com/documentation/xcode/supporting-associated-domains)。它允许你指定：
¥The [`details` format is supported](https://developer.apple.com/documentation/xcode/supporting-associated-domains) as of iOS 13. It allows you to specify:
* `appIDs` 代替 `appID`:使将多个应用与相同配置关联起来更容易
  ¥`appIDs` instead of `appID`: Makes it easier to associate multiple apps with the same configuration
* `components` 数组：允许你指定片段、排除特定路径和添加注释
  ¥An array of `components`: Allows you to specify fragments, exclude specific paths, and add comments
Note: An example AASA JSON from Apple's documentation
---
```json public/.well-known/apple-app-site-association
{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app", "ABCDE12345.com.example.app2"],
        "components": [
          {
            "#": "no_universal_links",
            "exclude": true,
            "comment": "Matches any URL whose fragment equals no_universal_links and instructs the system not to open it as a universal link"
          },
          {
            "/": "/buy/*",
            "comment": "Matches any URL whose path starts with /buy/"
          },
          {
            "/": "/help/website/*",
            "exclude": true,
            "comment": "Matches any URL whose path starts with /help/website/ and instructs the system not to open it as a universal link"
          },
          {
            "/": "/help/*",
            "?": {
              "articleNumber": "????"
            },
            "comment": "Matches any URL whose path starts with /help/ and which has a query item with name 'articleNumber' and a value of exactly 4 characters"
          }
        ]
      }
    ]
  }
}
```
---
To support all iOS versions, you can provide both the above formats in your `details` key, but we recommend placing the configuration for more recent iOS versions first.
### Host AASA file
Host the **apple-app-site-association** file using a web server with your domain. This file must be served over an HTTPS connection. Verify that your browser can access this file.
After you have setup the AASA file, deploy your website to a server that supports HTTPS (most modern web hosts).
### Native app configuration
After deploying your **apple-app-site-association** (AASA) file, configure your app to use your associated domain by adding [`ios.associatedDomains`](/versions/latest/config/app/#associateddomains) to your [app config](/workflow/configuration/). Make sure to follow [Apple's specified format](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_associated-domains) and **not** include the protocol (`https`) in your URL. This is a common mistake that will result in the universal links not working.
For example, if an associated website is `https://expo.dev/`, the `applinks` is:
```json app.json
{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:expo.dev"]
    }
  }
}
```
Build your iOS app with [EAS Build](/build/setup/) which ensures that the entitlement is registered with Apple automatically.
Note: Manual native configuration
---
If you're not using EAS or [Continuous Native Generation](/workflow/continuous-native-generation) (`npx expo prebuild`), you have to [manually configure](/build-reference/ios-capabilities#manual-setup) the **Associated Domains** capability for your bundle identifier.
If you enable through the [Apple Developer Console](/build-reference/ios-capabilities#apple-developer-console), then make sure to add the following entitlements in your **ios/[app]/[app].entitlements** file:
```xml
<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:expo.dev</string>
</array>
```
---
### Native app verification
Install the app on your iOS device to trigger the verification process. A link to your website on your mobile device should open your app. If it doesn't, re-check the previous steps to ensure that your AASA is valid, the path specified in the AASA, and you have correctly configured your App ID in the [Apple Developer Console](https://developer.apple.com/account/resources/identifiers/list).
Once you have your app opened, see [Handle links into your app](/linking/into-your-app/#handle-urls) for more information on how to handle inbound links and show the user the content they requested.
> iOS downloads your AASA when your app is first installed or when updates are installed from the App Store. The operating system does not refresh frequently after that. If you want to change the paths in your AASA for a production app, you will need to issue a full update via the App Store so that all of your users' apps re-fetch your AASA and recognize the new paths.
## Apple Smart Banner
If a user doesn't have your app installed, they'll be directed to the website. You can use the [Apple Smart Banner](https://developer.apple.com/documentation/webkit/promoting_apps_with_smart_app_banners) to show a banner at the top of the page that prompts the user to install the app. The banner will only show up if the user is on a mobile device and doesn't have the app installed.
To enable the banner, add the following meta tag to the `<head>` of your website, replacing `<ITUNES_ID>` with your app's iTunes ID:
```html
<meta name="apple-itunes-app" content="app-id=<ITUNES_ID>" />
```
If you're having trouble setting up the banner, run the following command to automatically generate the meta tag for your project:
```sh
$ npx setup-safari
```
### Add the meta tag to your statically rendered website
If you're building a [statically rendered website with Expo Router](/router/reference/static-rendering), then add the HTML tag to the `<head>` component in your [**app/+html.js** file](/router/reference/static-rendering#root-html).
```tsx app/+html.tsx
import { type PropsWithChildren } from 'react';
export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="apple-itunes-app" content="app-id=<ITUNES_ID>" />
        {/* Other head elements... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
```
## Debugging
Expo CLI enables you to test iOS Universal Links without deploying a website. Utilizing the [`--tunnel`](/more/expo-cli/#tunneling) functionality, you can forward your dev server to a publicly available HTTPS URL.
Step 1: 
Set the environment variable `EXPO_TUNNEL_SUBDOMAIN=my-custom-domain` where `my-custom-domain` is a unique string that you use during development. This ensures that your tunnel URL is consistent across dev server restarts.
Step 2: 
Add `associatedDomains` to your app config as [described above](#native-app-configuration). Replace the domain value with a Ngrok URL: `my-custom-domain.ngrok.io`.
Step 3: 
Start your dev server with the `--tunnel` flag:
```sh
$ npx expo start --tunnel
```
Step 4: 
Compile the development build on your device:
```sh
$ npx expo run:ios
```
你现在可以在设备的 Web 浏览器中键入自定义域链接来打开你的应用。
¥You can now type your custom domain link in your device's web browser to open your app.
<a id="troubleshooting"></a>
## 故障排除
¥Troubleshooting
以下是一些在实现 iOS 通用链接时帮助你排除故障的常见提示：
¥Here are some common tips to help you troubleshoot when implementing iOS Universal Links:
* 阅读 Apple 关于 [调试通用链接](https://developer.apple.com/documentation/technotes/tn3155-debugging-universal-links) 的官方文档
  ¥Read Apple's official documentation on [debugging universal links](https://developer.apple.com/documentation/technotes/tn3155-debugging-universal-links)
* 使用 [验证器工具](https://branch.io/resources/aasa-validator/).conf 确保你的 Apple 应用站点关联文件有效。
  ¥Ensure your apple app site association file is valid by using a [validator tool](https://branch.io/resources/aasa-validator/).
* 未压缩的 `apple-app-site-association` 文件不能是 [大于 128kb](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html)。
  ¥The uncompressed `apple-app-site-association` file cannot be [larger than 128kb](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html).
* 确保你的网站通过 HTTPS 提供服务。
  ¥Ensure your website is served over HTTPS.
* 如果你更新 Web 文件，请重建原生应用以触发供应商端（Apple）的服务器更新。
  ¥If you update your web files, rebuild the native app to trigger a server update on the vendor side (Apple).


# 编写原生代码

## 添加自定义原生代码

了解如何将自定义原生代码添加到你的 Expo 项目中。

你可以使用以下一种或两种方法添加自定义原生代码：
¥You can add custom native code by using one or both of the following approaches:
* [使用 Expo Modules API](#using-libraries-that-include-native-code)
  ¥[Using libraries that include native code](#using-libraries-that-include-native-code)
* [编写原生代码](#writing-native-code)
  ¥[Writing native code](#writing-native-code)
<a id="using-libraries-that-include-native-code"></a>
## 使用 Expo Modules API
¥Using libraries that include native code
Expo 和 React Native 开发者通常将大部分时间花在编写 JavaScript 代码和使用通过 [`expo-camera`](/versions/latest/sdk/camera/)、[`react-native-safe-area-context`](/versions/latest/sdk/safe-area-context/) 和 `react-native` 等库本身提供的原生 API 和组件上。这些库允许开发者通过 JavaScript 代码访问和使用设备功能。它们还可以提供对以原生代码实现的第三方服务 SDK 的访问（例如 [`@sentry/react-native`](/guides/using-sentry/)，它提供与 Android 和 iOS 的 Sentry 原生 SDK 的绑定）。
¥Expo and React Native developers typically spend the vast majority of their time writing JavaScript code and using native APIs and components that are made available through libraries like [`expo-camera`](/versions/latest/sdk/camera/), [`react-native-safe-area-context`](/versions/latest/sdk/safe-area-context/), and `react-native` itself. These libraries allow developers to access and use device features from their JavaScript code. They may also provide access to a third-party service SDK that is implemented in native code (such as [`@sentry/react-native`](/guides/using-sentry/), which provides bindings to the Sentry native SDK for Android and iOS).
Note: Using Expo Go?
---
If you are using the sandbox app, [Expo Go](http://expo.dev/go), [you can only access native libraries that are included in the Expo SDK](/versions/latest/sdk/third-party-overview/), or libraries that do not include any custom native code ([learn more](/workflow/using-libraries/#third-party-libraries)). [Creating a development build](/develop/development-builds/introduction/) allows you to change the native code or configuration as you would in any other native app.
---
### Installing libraries with custom native code in development builds
When using [development builds](/develop/development-builds/introduction/), using libraries with custom native code is straightforward:
- Install the library with npm, for example: `npx expo install react-native-localize`
- If the library includes a [config plugin](/config-plugins/introduction/), you can specify your preferred configuration in your app config.
- Create a new development build (either [locally](/guides/local-app-development/) or with [EAS](/develop/development-builds/create-a-build/)).
You can now use the library in your application code.
Note: Key concepts and development workflow
---
[The development overview](/workflow/overview/) provides details on key concepts for developing an app with Expo and the flow of the core development loop.
---
## Writing native code
Use the [Expo Modules API](/modules/overview/) to write Swift and Kotlin code and add new capabilities to your app with native modules and views. While there are other tools that you can use to build native modules, we believe that using the Expo Modules API makes building and maintaining nearly all kinds of React Native modules about as easy as it can be. We think that the Expo Modules API is the best choice for most developers building native modules for their apps.
Note: When should I consider writing native code?
---
It's common to encounter situations where a library doesn't quite do what you need. For example, the library might not provide access to a specific platform feature, or a third-party service might not provide bindings for React Native.
---
Note: Are you considering writing a module primarily in C++?
---
If you intend to write a native module primarily in C++, you may want to explore the [Turbo Modules API](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/turbo-modules.md) provided by React Native.
---
### Using the Expo Modules API
!!!IG0!!!
!!!IG1!!!
!!!IG2!!!
### Creating a local module
If you intend to use your native module in a single app (you can always change your mind later), we recommend [using a "local" Expo module](/modules/get-started/#creating-the-local-expo-module) to write custom native code. Local Expo Modules function similarly to [Expo Modules](/modules/overview) used by library developers and within the Expo SDK, like `expo-camera`, but they are not published on npm. Instead, you create them directly inside your project.
Creating a local module scaffolds a Swift and Kotlin module inside the `modules` directory in your project, and these modules are automatically linked to your app.
```sh
$ npx create-expo-module@latest --local
$ npx expo run
```
### Sharing a module with multiple apps
If you intend to use your native module with multiple apps, then use `npx create-expo-module@latest,` leave out the `--local` flag, and [create a standalone module](/modules/use-standalone-expo-module-in-your-project/). You can publish your package to npm, or you can put it in a packages directory in your [monorepo](/guides/monorepos/) (if you have one) to use it in [a similar way to local modules](/modules/use-standalone-expo-module-in-your-project/).
## Considerations when using Continuous Native Generation (CNG)
The following suggestions are most important when using [CNG](/workflow/continuous-native-generation/), but are good guidelines even if you don't use it.
Note: Build locally for the best debugging experience and fast feedback
---
By default, Expo projects created with `create-expo-app` use CNG and do not contain **android** or **ios** native directories until you've run the `npx expo prebuild` command in your project. When using CNG, developers typically do not commit the **android** and **ios** directories to source control and do not generate them locally, since EAS Build will do it automatically during the build process. That said, it is common to generate native directories and build locally with `npx expo run` when writing custom native code, to have a fast feedback loop and full access to native debugging tools in Android Studio / Xcode.
---
Note: Use config plugins for native project configuration
---
If your native code requires that you make changes to your project configuration, such as modifying the project's **AndroidManifest.xml** or **Info.plist**, [you should apply these changes through a config plugin](/modules/config-plugin-and-native-module-tutorial/) rather than by modifying the files directly in the **android** and **ios** directories. Remember that changes made directly to native project directories will be lost the next time you run prebuild when you use CNG.
---
Note: Use event subscribers to hook into app lifecycle events
---
If you need to hook into Android lifecycle events or `AppDelegate` methods, use the APIs provided by Expo Modules for [Android](/modules/android-lifecycle-listeners/) and [iOS](/modules/appdelegate-subscribers/) to accomplish this rather than modifying the source files in your native project directories directly or using a config plugin to add the code, which does not compose well with other plugins.
---


## 采用预构建

了解如何在使用 React Native CLI 引导的项目中采用 Expo Prebuild。

使用 [Expo 预建][prebuild] 至 [不断生成你的原生项目](/workflow/continuous-native-generation) 有 [许多优点](/workflow/prebuild#pitch) 个。本指南将向你展示如何在使用 `npx @react-native-community/cli@latest init` 引导的项目中采用 Expo Prebuild。转换项目所需的时间取决于你对 Android 和 iOS 原生项目所做的自定义原生更改量。对于一个全新的项目，这可能需要一两分钟，而对于一个大型项目，时间会长得多。
¥There are [many advantages](/workflow/prebuild#pitch) of using [Expo Prebuild][prebuild] to [continuously generate your native projects](/workflow/continuous-native-generation). This guide will show you how to adopt Expo Prebuild in a project that was bootstrapped with `npx @react-native-community/cli@latest init`. The amount of time it will take to convert your project depends on the amount of custom native changes that you have made to your Android and iOS native projects. This may take a minute or two on a brand new project, and on a large project, it will be much longer.
采用预构建将通过本地链接 `expo-modules-core` 自动添加对使用 [Expo 原生模块 API][expo-modules-core] 开发模块的支持。你还可以在项目中使用 [Expo CLI][cli] 中的任何命令。
¥Adopting prebuild will automatically add support for developing modules with the [Expo native module API][expo-modules-core] by linking `expo-modules-core` natively. You can also use any command from [Expo CLI][cli] in your project.
>  **warning** [并非所有版本的 `react-native` 都得到明确支持](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version)。确保使用具有相应 Expo SDK 版本的 `react-native` 版本。
>
> ¥[Not all versions of `react-native` are explicitly supported](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version). Make sure to use a version of `react-native` that has a corresponding Expo SDK version.
<a id="install-the-expo-package"></a>
## 安装 `expo` 包
¥Install the `expo` package
`expo` 包包含 [`npx expo prebuild`](/more/expo-cli/#prebuild) 命令并指示要使用哪个 [预构建模板](/workflow/prebuild#templates)：
¥The `expo` package contains the [`npx expo prebuild`](/more/expo-cli/#prebuild) command and indicates which [prebuild template](/workflow/prebuild#templates) to use:
```sh
$ npm install expo
```
确保你安装的 `expo` 版本适用于当前安装的 [`react-native` 版本](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version)。
¥Ensure you install the version of `expo` that works for your currently installed [version of `react-native`](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version).
<a id="update-the-entry-file"></a>
## 更新入口文件
¥Update the entry file
修改入口文件以使用 [`registerRootComponent`](/versions/latest/sdk/expo/#registerrootcomponentcomponent) 而不是 `AppRegistry.registerComponent`：
¥Modify the entry file to use [`registerRootComponent`](/versions/latest/sdk/expo/#registerrootcomponentcomponent) instead of `AppRegistry.registerComponent`:
```diff
+ import {registerRootComponent} from 'expo';
- import {AppRegistry} from 'react-native';
import App from './App';
- import {name as appName} from './app.json';
- AppRegistry.registerComponent(appName, () => App);
+ registerRootComponent(App);
```
> 了解有关 [`registerRootComponent`](/versions/latest/sdk/expo/#registerrootcomponentcomponent) 的更多信息。
>
> ¥Learn more about [`registerRootComponent`](/versions/latest/sdk/expo/#registerrootcomponentcomponent).
<a id="prebuild"></a>
## 预建
¥Prebuild
>  **warning** 确保你已提交更改，以防万一你想恢复，该命令也会警告你这一点！
>
> ¥Make sure you have committed your changes in case you want to revert, the command will warn you about this too!
如果你要迁移现有项目，那么你可能需要首先参考 [**迁移原生自定义**](#migrate-native-customizations)。
¥If you're migrating an existing project, then you may want to refer to [**migrating native customizations**](#migrate-native-customizations) first.
运行以下命令根据应用配置（app.json/app.config.js）配置重新生成 android 和 ios 目录：
¥Run the following command to regenerate the **android** and **ios** directories based on the app config (**app.json/app.config.js**) configuration:
```sh
$ npx expo prebuild --clean
```
你可以通过在本地构建项目来测试一切是否正常：
¥You can test that everything worked by building the projects locally:
```sh
$ npx expo run:android
$ npx expo run:ios
```
> 了解有关 [编译原生应用](/more/expo-cli/#compiling) 的更多信息。
>
> ¥Learn more about [compiling native apps](/more/expo-cli/#compiling).
<a id="extra-changes"></a>
## 额外的改变
¥Extra changes
以下更改是可选的，但建议进行。
¥The following changes are optional but recommended.
**.gitignore**
你可以将 .expo 添加到 .gitignore 以防止提交 Expo CLI 生成的值。这些 [值对于你的项目来说是独一无二的](/more/expo-cli/#expo-directory) 在你的本地计算机上。
¥You can add **.expo** to your **.gitignore** to prevent generated values from Expo CLI from being committed. These [values are unique to your project](/more/expo-cli/#expo-directory) on your local computer.
如果你想确保在预构建之间不会提交 android 和 ios，你还可以将 android 和 ios 添加到 .gitignore。
¥You can also add **android** and **ios** to the **.gitignore** if you want to ensure they are not committed between prebuilds.
**app.json**
删除顶层 `expo` 对象之外的所有字段，因为这些字段不会在 `npx expo prebuild` 中使用。
¥Remove all fields that are outside the top-level `expo` object as these will not be used in `npx expo prebuild`.
```diff
{
-  "name": "myapp",
-  "displayName": "myapp"
+  "expo": {
+    "name": "myapp"
+  }
}
```
**metro.config.js**
参见 [定制 Metro](/guides/customizing-metro/)。
¥See [Customizing Metro](/guides/customizing-metro/).
**package.json**
你可能想要更改脚本以使用 [Expo CLI](/more/expo-cli/#compiling) 运行命令：
¥You may want to change the scripts to use the [Expo CLI](/more/expo-cli/#compiling) run commands:
```diff
  "scripts": {
    "start": "expo start",
-    "android": "react-native run-android",
-    "ios": "react-native run-ios",
+    "android": "expo run:android",
+    "ios": "expo run:ios",
  },
```
这些命令具有更好的日志记录、自动代码签名、更好的模拟器处理，并且它们确保你运行 `npx expo start` 来提供文件。
¥These commands have better logging, auto code signing, better simulator handling, and they ensure you run `npx expo start` to serve files.
<a id="migrate-native-customizations"></a>
## 迁移原生自定义
¥Migrate native customizations
如果你的项目有任何原生修改（对 android 或 ios 目录的更改，例如应用图标配置或启动屏幕），那么你需要配置应用配置 (app.json) 以反映这些原生更改。
¥If your project has any native modifications (changes to the **android** or **ios** directories, such as app icon configuration or splash screen) then you'll need to configure your app config (**app.json**) to reflect those native changes.
* 检查你的更改是否与内置 [应用配置字段](/versions/latest/config/app/) 重叠。例如，如果你有一个应用图标，请务必在 app.json 中将其定义为 `expo.icon`，然后重新运行 `npx expo prebuild`。
  ¥Check to see if your changes overlap with the built-in [app config fields](/versions/latest/config/app/). For example, if you have an app icon, be sure to define it as `expo.icon` in the **app.json** then re-run `npx expo prebuild`.
* 查看你正在使用的任何软件包是否需要 [Expo 配置插件][config-plugins]。如果项目中的包需要在 android 或 ios 目录中进行其他更改，那么你可能需要一个配置插件。通过使用 package.json 依赖中的所有包运行 `npx expo install` 可以自动添加一些插件。如果某个软件包需要插件但不提供插件，那么你可以尝试检查 [`expo/config-plugins`](https://github.com/expo/config-plugins) 上的社区插件，看看是否已经存在插件。
  ¥Look up if any of the packages you are using require an [Expo config plugin][config-plugins]. If a package in your project requires additional changes inside the **android** or **ios** directories, then you will probably need a Config Plugin. Some plugins can be automatically added by running `npx expo install` with all of the packages in your **package.json** dependencies. If a package requires a plugin but doesn't supply one, then you can try checking the community plugins at [`expo/config-plugins`](https://github.com/expo/config-plugins) to see if one already exists.
* 你可以使用 [VS Code Expo 扩展][vs-code-expo] 内省你的更改并调试预构建是否生成你期望的原生代码。只需按 <kbd>Cmd ⌘</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd>，输入“Expo:预览修改器”，然后选择你想要内省的原生文件。
  ¥You can use the [VS Code Expo extension][vs-code-expo] to introspect your changes and debug if prebuild is generating the native code you expect. Just press <kbd>Cmd ⌘</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd>, type "Expo: Preview Modifier", and select the native file you wish to introspect.
* 此外，你可以开发本地配置插件来满足你的需求。[了解更多](/config-plugins/development-and-debugging/#develop-a-plugin)。
  ¥Additionally, you can develop local config plugins to fit your needs. [Learn more](/config-plugins/development-and-debugging/#develop-a-plugin).
<a id="add-more-features"></a>
## 添加更多功能
¥Add more features
预构建是自动化的冰山一角，以下是你接下来可以采用的一些功能：
¥Prebuild is the tip of the automation iceberg, here are some features you can adopt next:
* [EAS 构建](/build/setup)：代码签名和云构建。
  ¥[EAS Build](/build/setup): Code signing and cloud building.
* [EAS 更新](/build/updates)：立即发送无线更新。
  ¥[EAS Update](/build/updates): Send over-the-air updates instantly.
* [用于 Web 的 Expo](/workflow/web)：在浏览器中运行你的应用。
  ¥[Expo for web](/workflow/web): Run your app in the browser.
* [Expo 开发客户端][dev-client]：围绕你的原生运行时创建你自己的个人 "Expo" 类型应用。
  ¥[Expo Dev Client][dev-client]: Create your own personal "Expo Go" type app around your native runtime.
* [Expo 原生模块 API][expo-modules-core]：使用 Swift 和 Kotlin 编写模块。使用 `npx expo prebuild` 时会自动支持此功能。
  ¥[Expo native module API][expo-modules-core]: Write modules with Swift and Kotlin. This is automatically supported when using `npx expo prebuild`.
[vs-code-expo]: https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools
[expo-modules-core]: /modules/module-api/
[dev-client]: /develop/development-builds/introduction/
[config-plugins]: /config-plugins/introduction/
[prebuild]: /workflow/prebuild
[cli]: /more/expo-cli/


# 本地编译

## 本地应用开发

了解如何在本地编译和构建你的 Expo 应用。

要使用你的计算机在本地将项目构建为应用，你必须在测试调试版本或创建生产版本以将其提交到应用商店之前手动生成原生代码。你可以通过两种方式在本地构建应用。本指南简要介绍了创建此工作流程所需的方法和其他指南的参考。
¥To build your project into an app locally using your machine, you have to manually generate native code before testing the debug build or creating a production build for it to submit to the app store. There are two ways you can build your app locally. This guide provides a brief introduction to both methods and references to other guides that are necessary to create this workflow.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
你需要安装并设置 Android Studio 和 Xcode 以在本地机器上编译和运行 Android 和 iOS 项目。请参阅以下内容，了解如何设置这些工具：
¥You need to install and set up Android Studio and Xcode to compile and run Android and iOS projects on your local machine. See the following on how to set up these tools:
* [安卓工作室](/get-started/set-up-your-environment/?platform=android\&device=physical\&mode=development-build\&buildEnv=local#set-up-an-android-device-with-a-development-build)
  ¥[Android Studio](/get-started/set-up-your-environment/?platform=android\&device=physical\&mode=development-build\&buildEnv=local#set-up-an-android-device-with-a-development-build)
* [Xcode](/get-started/set-up-your-environment/?platform=ios\&device=physical\&mode=development-build\&buildEnv=local#set-up-an-ios-device-with-a-development-build)
<a id="local-app-compilation"></a>
## 本地应用编译
¥Local app compilation
要在本地构建项目，你可以使用 Expo CLI 中的编译命令来生成 android 和 ios 目录：
¥To build your project locally you can use compile commands from Expo CLI which generates the **android** and **ios** directories:
```sh
$ npx expo run:android
$ npx expo run:ios
```
上述命令使用本地安装的 Android SDK 或 Xcode 将你的项目编译为应用的调试版本。
¥The above commands compile your project, using your locally installed Android SDK or Xcode, into a debug build of your app.
* 这些编译命令最初运行 `npx expo prebuild` 以在构建之前生成原生目录（android 和 ios）（如果它们尚不存在）。如果它们已经存在，这将被跳过。
  ¥These compilation commands initially run `npx expo prebuild` to generate native directories (**android** and **ios**) before building, if they do not exist yet. If they already exist, this will be skipped.
* 你还可以添加 `--device` 标志来选择运行应用的设备 - 你可以选择物理连接的设备或模拟器/模拟器。
  ¥You can also add the `--device` flag to select a device to run the app on — you can select a physically connected device or emulator/simulator.
* 你可以传入 `--variant release` (Android) 或 `--configuration Release` (iOS) 来构建 [应用的生产版本](/deploy/build-project/#production-builds-locally)。请注意，这些版本未签名，你无法将它们提交到应用商店。要签署你的生产版本，请参阅 [本地应用生产](/guides/local-app-production/)。
  ¥You can pass in `--variant release` (Android) or `--configuration Release` (iOS) to build a [production build of your app](/deploy/build-project/#production-builds-locally). Note that these builds are not signed and you cannot submit them to app stores. To sign your production build, see [Local app production](/guides/local-app-production/).
要在第一次构建后修改项目的配置或原生代码，你必须重新构建项目。再次运行 `npx expo prebuild` 会将更改分层到现有文件之上。构建后也可能会产生不同的结果。
¥To modify your project's configuration or native code after the first build, you will have to rebuild your project. Running `npx expo prebuild` again layers the changes on top of existing files. It may also produce different results after the build.
为了避免这种情况，请将原生目录添加到项目的 .gitignore 并使用 `npx expo prebuild --clean` 命令。这确保了项目始终受到管理，并且 [`--clean` 旗](/workflow/prebuild/#clean) 将在重新生成现有目录之前删除它们。你可以使用 [应用配置](/workflow/configuration/) 或创建 [配置插件](/config-plugins/introduction/) 来修改原生目录内的项目配置或代码。
¥To avoid this, add native directories to the project's **.gitignore** and use `npx expo prebuild --clean` command. This ensures that the project is always managed, and the [`--clean` flag](/workflow/prebuild/#clean) will delete existing directories before regenerating them. You can use [app config](/workflow/configuration/) or create a [config plugin](/config-plugins/introduction/) to modify your project's configuration or code inside the native directories.
要了解有关编译和预构建如何工作的更多信息，请参阅以下指南：
¥To learn more about how compilation and prebuild works, see the following guides:
<a id="local-builds-with-expo-dev-client"></a>
## 使用 `expo-dev-client` 进行本地构建
¥Local builds with `expo-dev-client`
如果你将 [`expo-dev-client`](/develop/development-builds/introduction/#what-is-expo-dev-client) 安装到项目中，那么项目的调试版本将包括 `expo-dev-client` UI 和工具，我们将这些版本称为开发版本。
¥If you install [`expo-dev-client`](/develop/development-builds/introduction/#what-is-expo-dev-client) to your project, then a debug build of your project will include the `expo-dev-client` UI and tooling, and we call these development builds.
```sh
$ npx expo install expo-dev-client
```
要创建开发版本，你可以使用 [本地应用编译](#local-app-compilation) 命令 (`npx expo run:[android|ios]`)，这将创建调试版本并启动开发服务器。
¥To create a development build, you can use [local app compilation](#local-app-compilation) commands (`npx expo run:[android|ios]`) which will create a debug build and start the development server.
<a id="local-builds-using-android-product-flavors"></a>
## 使用 Android 产品风格进行本地构建
¥Local builds using Android product flavors
>  **warning** 此功能仅适用于 SDK 52 及以上版本。
>
> ¥This feature is only available for SDK 52 and above.
如果你有一个自定义 Android 项目，其中包含使用不同应用 ID 的多个产品风格，则可以配置 `npx expo run:android` 以使用正确的风格和构建类型。Expo 支持 `--variant` 和 `--app-id`，以自定义构建和启动行为。
¥If you have a custom Android project with multiple product flavors using different application IDs, you can configure `npx expo run:android` to use the correct flavor and build type. Expo supports both `--variant` and `--app-id` to customize the build and launch behavior.
`--variant` 标志可以将 Android 构建类型从调试切换到发布。当采用 camelCase 格式时，此标志还可以配置产品风格和构建类型。例如，如果你同时拥有 [免费和付费产品风格](https://developer.android.com/build/build-variants#change-app-id)，则可以使用以下方式构建应用的开发版本：
¥The `--variant` flag can switch the Android build type from **debug** to **release**. This flag can also configure a product flavor and build type, when formatted in camelCase. For example, if you have both [**free** and **paid** product flavors](https://developer.android.com/build/build-variants#change-app-id), you can build a development version of your app with:
```sh
$ npx expo run:android --variant freeDebug
$ npx expo run:android --variant paidDebug
```
`--app-id` 标志可用于在使用自定义应用 ID 构建后启动应用。例如，如果你的产品版本免费使用 `applicationIdSuffix ".free"` 或 `applicationId "dev.expo.myapp.free"`，你可以运行构建并启动应用：
¥The `--app-id` flag can be used to launch the app after building using a customized application id. For example, if your product flavor **free** is using `applicationIdSuffix ".free"` or `applicationId "dev.expo.myapp.free"` you can run build and launch the app with:
```sh
$ npx expo run:android --variant freeDebug --app-id dev.expo.myapp.free
```
>  **info** 也可以自定义 Android 构建类型，但这会破坏 Expo 的假设，即构建类型发布用于生产。你可能会使用不同的构建类型（而不是发布类型）在应用中构建未优化的代码。
>
> ¥Customizing the Android build type is also possible, but that would break Expo's assumption that the build type **release** is used for production. You might build unoptimized code in your app using a different build type instead of **release**.
<a id="local-builds-with-eas"></a>
## 使用 EAS 进行本地构建
¥Local builds with EAS


## 在本地创建生产版本

了解如何在本地为你的 Expo 应用创建生产版本。

要在本地创建应用的生产版本（也称为发布版本），你需要在计算机上执行单独的步骤并使用创建任何原生应用所需的工具。本指南提供了 Android 和 iOS 的必要步骤。
¥To create your app's production build (also known as release build) locally, you need to follow separate steps on your computer and use the tools required to create any native app. This guide provides the necessary steps for Android and iOS.
<a id="android"></a>
## 安卓
¥Android
在本地为 Android 创建生产版本需要使用 [上传密钥](https://developer.android.com/studio/publish/app-signing#certificates-keystores) 对其进行签名并生成 Android 应用包 (.aab)。请按照以下步骤操作：
¥Creating a production build locally for Android requires signing it with an [upload key](https://developer.android.com/studio/publish/app-signing#certificates-keystores) and generating an Android Application Bundle (**.aab**). Follow the steps below:
<a id="prerequisites"></a>
### 先决条件
¥Prerequisites
* [OpenJDK 发行版](/get-started/set-up-your-environment/?mode=development-build\&buildEnv=local#install-watchman-and-jdk) 安装以访问 `keytool` 命令
  ¥[OpenJDK distribution](/get-started/set-up-your-environment/?mode=development-build\&buildEnv=local#install-watchman-and-jdk) installed to access the `keytool` command
* android 目录已生成。如果你使用的是 [CNG](/workflow/continuous-native-generation/)，则运行 `npx expo prebuild` 来生成它。
  ¥**android** directory generated. If you are using [CNG](/workflow/continuous-native-generation/), then run `npx expo prebuild` to generate it.
Step 1: 
### Create an upload key
Note: Already created a build with EAS Build? Download your credentials and skip to the next step.
---
If you've already created a build with EAS Build, follow the steps below to download the credentials, which contains the upload key and its password, key alias, and key password:
1. In your terminal, run `eas credentials -p android` and select the build profile.
2. Select **credentials.json** > **Download credentials from EAS to credentials.json**.
3. Move the downloaded **keystore.jks** file to the **android/app** directory.
4. Copy the values for the upload keystore password, key alias, and key password from the **credentials.json** as you will need them in the next step.
---
Inside your Expo project directory, run the following `keytool` command to create an upload key:
```sh
$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000
```
After running this command, you will be prompted to enter a password for the keystore. This password will protect the upload key. Remember the password you enter here, as you'll need it in the next step.
This command also generates the keystore file named **my-upload-key.keystore** in your project directory. Move it to the **android/app** directory.
> **warning** If you commit the **android** directory to a version control system like Git, don't commit this keystore file. It contains your upload key and should be kept private.
Step 2: 
### Update gradle variables
Open **android/gradle.properties** file and add the following gradle variables at the end of the file. Replace the `*****` with the correct keystore and key password that you provided in the previous step.
These variables contain information about your upload key:
!!!IG0!!!
> **warning** If you commit the **android** directory to a version control system like Git, don't commit the above information. Instead, create a **~/.gradle/gradle.properties** file on your computer and add the above variables to this file.
Step 3: 
### Add signing config to build.gradle
Open **android/app/build.gradle** file and add the following configuration:
<DiffBlock source="/static/diffs/android-release-build.diff" />
Step 4: 
### Generate release Android Application Bundle (aab)
Navigate inside the **android** directory and create a production build in **.aab** format by running Gradle's `bundleRelease` command:
```sh
$ cd android
$ ./gradlew app:bundleRelease
```
This command will generate app-release.aab inside the **android/app/build/outputs/bundle/release** directory.
Step 5: 
### Manual app submission to Google Play Console
Google Play Store requires manual app submission when submitting the **.aab** file for the first time.
!!!IG1!!!
## iOS
To create an iOS production build locally for Apple App Store, you need to use Xcode which handles the signing and submission process via App Store Connect.
### Prerequisites
- Paid Apple Developer membership
- [Xcode installed](/get-started/set-up-your-environment/?platform=ios&device=physical&mode=development-build&buildEnv=local#set-up-xcode-and-watchman) on your computer
- **ios** directory generated. If you are using [CNG](/workflow/continuous-native-generation/), then run `npx expo prebuild` to generate it.
Step 1: 
### Open iOS workspace in Xcode
Inside your Expo project directory, run the following command to open `your-project.xcworkspace` in Xcode:
```sh
$ xed ios
```
After opening the iOS project in Xcode:
1. From the sidebar on the left, select your app's workspace.
2. Go to **Signing & Capabilities** and select **All** or **Release**.
3. Under **Signing** > **Team**, ensure your Apple Developer team is selected. Xcode will generate an automatically managed Provisioning Profile and Signing Certificate.
Step 2: 
### Configure a release scheme
To configure your app's release scheme:
1. From the menu bar, open **Product** > **Scheme** > **Edit Scheme**.
2. Select **Run** from the sidebar, then set the **Build configuration** to **Release** using the dropdown.
Step 3: 
### Build app for release
To build your app for release, From the menu bar, open **Product** > **Build**. This step will build your app binary for release.
Step 4: 
### App submission using App Store Connect
Once the build is complete, you can distribute your app to TestFlight or submit it to the App Store using App Store Connect:
1. From the menu bar, open **Product** > **Archive**.
2. Under **Archives**, click **Distribute App** from the right sidebar.
3. Click **App Store Connect** and follow the prompts shown in the window. This step will create an app store record and upload your app to the App Store.
4. Now you can go to your App Store Connect account, select your app under Apps, and submit it for testing using TestFlight or prepare it for final release by following the steps in the App Store Connect dashboard.


## 使用构建缓存提供程序

通过缓存和重用来自服务提供者的构建版本来加速本地开发。

构建缓存是一项实验性功能，它基于 [fingerprint](/versions/latest/sdk/fingerprint/) 项目，通过远程缓存构建来加速 `npx expo run:[android|ios]`。运行 `npx expo run:[android|ios]` 时，它会检查是否存在具有匹配指纹的版本，然后下载并启动它，而不是重新编译它。否则，项目将照常编译，然后将生成的二进制文件上传到远程缓存以供将来运行。
¥Build caching is an experimental feature that speeds up `npx expo run:[android|ios]` by caching builds remotely, based on the project [fingerprint](/versions/latest/sdk/fingerprint/).
When you run `npx expo run:[android|ios]`, it checks if a build with a matching fingerprint exists, then downloads and launches it rather than compiling it again. Otherwise, the project is compiled as usual and then the resulting binary is uploaded to the remote cache for future runs.
<a id="using-eas-as-a-build-provider"></a>
## 使用 EAS 作为构建提供程序
¥Using EAS as a build provider
要使用 EAS Build 提供程序插件，首先需要安装 `eas-build-cache-provider` 包作为开发者依赖：
¥To use the EAS Build provider plugin, start by installing the `eas-build-cache-provider` package as a developer dependency:
```sh
$ npx expo install eas-build-cache-provider
```
然后，更新你的 app.json 文件，使其在 `experiments` 下包含 `buildCacheProvider` 属性及其提供程序：
¥Then, update your **app.json** to include the `buildCacheProvider` property and its provider under `experiments`:
```json app.json
{
  "expo": {
    ...
    "experiments": {
      "buildCacheProvider": "eas"
    }
  }
}
```
你可以通过导出实现以下方法的插件来构建自己的缓存提供程序：
¥You can roll your own cache provider by exporting a plugin that implements the following methods:
```ts
type BuildCacheProviderPlugin<T = any> = {
  /**
   * Try to fetch an existing build. Return its URL or null if missing.
   */
  resolveBuildCache(props: ResolveBuildCacheProps, options: T): Promise<string | null>;
  /**
   * Upload a new build binary. Return its URL or null on failure.
   */
  uploadBuildCache(props: UploadBuildCacheProps, options: T): Promise<string | null>;
  /**
   * (Optional) Customize the fingerprint hash algorithm.
   */
  calculateFingerprintHash?: (
    props: CalculateFingerprintHashProps,
    options: T
  ) => Promise<string | null>;
};
type ResolveBuildCacheProps = {
  projectRoot: string;
  platform: 'android' | 'ios';
  runOptions: RunOptions;
  fingerprintHash: string;
};
type UploadBuildCacheProps = {
  projectRoot: string;
  buildPath: string;
  runOptions: RunOptions;
  fingerprintHash: string;
  platform: 'android' | 'ios';
};
type CalculateFingerprintHashProps = {
  projectRoot: string;
  platform: 'android' | 'ios';
  runOptions: RunOptions;
};
```
在 [构建缓存提供程序示例](https://github.com/expo/examples/tree/master/with-github-remote-build-cache-provider) 中可以找到使用 GitHub Releases 缓存构建的参考实现。
¥A reference implementation using GitHub Releases to cache builds can be found in the [Build Cache Provider Example](https://github.com/expo/examples/tree/master/with-github-remote-build-cache-provider).
<a id="creating-a-custom-build-provider"></a>
## 创建自定义构建提供程序
¥Creating a custom build provider
首先创建一个提供程序目录，用于用 TypeScript 编写提供程序插件，并在项目根目录中添加一个 provider.plugin.js 文件，该文件将成为插件的入口点。
¥Start by creating a **provider** directory for writing the provider plugin in TypeScript and add a **provider.plugin.js** file in the project root, which will be the plugin's entry point.
Step 1: 
### Create a `provider/tsconfig.json` file
```json provider/tsconfig.json
{
  "extends": "expo-module-scripts/tsconfig.plugin",
  "compilerOptions": {
    "outDir": "build",
    "rootDir": "src"
  },
  "include": ["./src"],
  "exclude": ["**/__mocks__/*", "**/__tests__/*"]
}
```
Step 2: 
### Create a `provider/src/index.ts` file for your plugin
```ts provider/src/index.ts
import { BuildCacheProviderPlugin } from '@expo/config';
const plugin: BuildCacheProviderPlugin {
  resolveBuildCache: () => {
    console.log('Searching for remote builds...')
    return null;
  },
  uploadBuildCache: () => {
    console.log('Uploading build to remote...')
    return null;
  },,
};
export default plugin;
```
Step 3: 
### Create an `provider.plugin.js` file in the root directory
```js provider.plugin.js
// This file configures the entry file for your plugin.
module.exports = require('./provider/build');
```
Step 4: 
### Build your provider plugin
At the root of your project, run `npm run build provider` to start the TypeScript compiler in watch mode.
Step 5: 
### Configure your example project to use your plugin by adding the following line to the `example/app.json` file:
```json example/app.json
{
  "expo": {
    ...
    "experiments": {
      "buildCacheProvider": {
        "plugin": "./provider.plugin.js"
      }
    }
  }
}
```
Step 6: 
### Test your provider
When you run the `npx expo run` command inside your **example** directory, you should see your plugin's console statements in the logs.
```sh
$ cd example
$ npx expo run:ios
```
That's it! You now have a remote build cache provider to speed up your builds.
<a id="passing-custom-options"></a>
### 传递自定义选项
¥Passing custom options
要将自定义选项注入到插件中，你可以使用 `options` 字段，它将作为自定义函数的第二个参数转发。为此，请修改 example/app.json 中的 `buildCacheProvider` 字段，如下所示：
¥To inject custom options to your plugin you can use the `options` field and it will be forwarded as the second parameter of your custom functions. To do so modify the `buildCacheProvider` field in **example/app.json** as shown below:
```json example/app.json
{
  "expo": {
    ...
    "experiments": {
      "buildCacheProvider": {
        "plugin": "./provider.plugin.js",
        "options": {
          "myCustomKey": "XXX-XXX-XXX"
        }
      }
    }
  }
}
```


## Android 预置 Expo 模块

了解预构建的 Expo 模块如何将 Android 构建时间在你的设备上缩短高达 25%。

构建 React Native 应用时，较长的构建时间会减慢你的开发工作流程并降低生产力。每次更改代码时，你可能需要等待构建过程完成，这可能会造成严重的延迟。
¥When building React Native apps, longer build times can slow down your development workflow and reduce productivity. Each time you make changes to your code, you might need to wait for the build process to complete, which can add up to significant delays.
从 SDK 53 开始，Expo 引入了针对 Android 的预构建 Expo 模块来解决这一痛点。现在，你的项目可以使用这些模块的预编译版本，而不必在每次构建时从头开始编译 Expo 模块源代码。最终，这将缩短构建时间。
¥**Starting from SDK 53**, Expo introduces prebuilt Expo Modules for Android to address this pain point. Instead of compiling Expo Modules source code from scratch during each build, your project can now use pre-compiled versions of these modules. Ultimately, this results in faster build times.
<a id="benefits"></a>
## 优势
¥Benefits
* 更快的本地开发：本地机器上的 Android 构建时间最多可缩短 25%
  ¥**Faster local development**: Up to 25% reduction in Android build times on local machines
* 提升开发者体验：减少开发迭代期间的等待时间
  ¥**Improved developer experience**: Less waiting time during development iterations
* 自动优化：适用于 SDK 53 及以上版本的新项目，开箱即用。
  ¥**Automatic optimization**: Works out of the box with new projects for SDK 53 and above
<a id="how-prebuilt-expo-modules-for-android-work"></a>
## Android 预构建的 Expo 模块如何工作
¥How prebuilt Expo Modules for Android work
在项目的 Android 构建过程中，请在构建输出中查找软件包名称旁边的 `[📦]` 表情符号前缀。这表明这些软件包使用的是预构建版本，而不是从源代码编译的。
¥During your project's Android build process, look for the `[📦]` emoji prefix next to package names in the build output. This indicates that those packages are using prebuilt versions rather than being compiled from source.
例如，在使用 SDK 53 的默认模板创建项目并运行 `npx expo run:android` 命令后，你会注意到预编译包旁边的 `[📦 package-name` 前缀：
¥For example, after creating a project with SDK 53's default template, and running the `npx expo run:android` command, you will notice the `[📦 package-name` prefix next to packages that are precompiled:
<a id="configuration"></a>
## 配置
¥Configuration
对于 SDK 53 及以上版本，使用可用 [Expo 模板](/more/create-expo/#--template) 创建的项目无需任何配置步骤。
¥**For SDK 53 and above, no configuration steps are required for projects** that are created with one of the available [Expo templates](/more/create-expo/#--template).
<a id="opting-out-of-prebuilt-expo-modules"></a>
### 退出预置 Expo 模块
¥Opting out of prebuilt Expo Modules
你可以选择退出预构建模块。当你自己修改模块源代码时，可能需要这样做。在这种情况下，你可以通过将 `buildFromSource` 添加到 package.json 文件来配置 Expo Autolinking 配置：
¥You can opt out of prebuilt modules. This might be required when you are modifying the module source code yourself. In this scenario, you can configure the Expo Autolinking configuration by adding `buildFromSource` to the **package.json** file:
```json package.json
{
  "name": "your-app-name",
  "expo": {
    "autolinking": {
      "android": {
        "buildFromSource": [
          ".*"
        ]
      }
    }
  }
}
```
<a id="selectively-opt-out"></a>
### 选择性退出
¥Selectively opt out
你还可以通过指定单独的软件包名称（而不是通配符 `".*"`）来选择退出特定模块，同时保留其他预构建模块：
¥You can also opt out of specific modules while keeping others prebuilt by specifying individual package names instead of the wildcard `".*"`:
```json package.json
{
  "name": "your-app-name",
  "expo": {
    "autolinking": {
      "android": {
        "buildFromSource": [
          "expo-camera",
          "expo-web-browser",
          "expo-linking",
        ]
      }
    }
  }
}
```
<a id="considerations"></a>
## 注意事项
¥Considerations
* 现有项目升级到 SDK 53 及以上版本后可受益于此功能。
  ¥Existing projects can benefit from this feature when upgrading to SDK 53 and above
* 性能提升可能因硬件配置而异
  ¥Performance improvements may vary based on your hardware configuration
* EAS 构建的当前改进较为温和，但为未来的缓存机制奠定了基础。
  ¥Current improvements on EAS Builds are more modest but provide groundwork for future caching mechanisms


# Web

## 与 Expo 一起开发网站

了解如何开发网络应用，以便构建通用应用。

Expo 为使用 React 构建全栈网站提供一流的支持。Expo 网站可以是 [静态渲染](/router/reference/static-rendering) 的 SEO 和性能，也可以是客户端渲染的，以便在浏览器中获得更像应用的体验。
¥Expo has first-class support for building full-stack websites with React. Expo websites can be [statically rendered](/router/reference/static-rendering) for SEO and performance, or client-rendered for a more app-like experience in the browser.
For Universal: 
使用 [React Native 网页版](https://github.com/necolas/react-native-web) 中的 `<Text>` 组件在任何平台上渲染文本。
¥Render text on any platform with the `<Text>` component from [React Native for web](https://github.com/necolas/react-native-web).
```jsx app/index.js
    import { Text } from 'react-native';
    export default function Page() {
      return <Text>Home page</Text>;
    }
    ```
React Native for Web (RNW) 是一组组件库，例如 `<View>` 和 `<Text>`，它们封装了 `react-dom` 原语，例如 `<div>`、`<p>` 和 `<img>`。在进行 Web 开发时，RNW 是可选的，因为你可以直接使用 React DOM，但我们在跨平台构建时经常推荐它，因为它可以最大限度地提高代码重用性。
¥React Native for web (RNW) is a set of component libraries such as `<View>`, and `<Text>`, that wrap `react-dom` primitives such as `<div>`, `<p>`, and `<img>`. RNW is optional when developing for web since you can use React DOM directly, but we often recommended it when building across platforms as it maximizes code reuse.
> React Native for web 用于为整个 [X](https://x.com/) 网站提供支持。
>
> ¥React Native for web is used to power the entire [X](https://x.com/) website.
For Web-only: 
或者，你可以编写仅用于 Web 的 React DOM 组件，例如 `<div>`、`<p>` 等，但是这些组件不会在原生平台上渲染。
¥Alternatively, you can write web-only React DOM components such as `<div>`, `<p>`, and so on, however, these components won't render on native platforms.
```jsx app/index.js
    export default function Page() {
      return <p>Home page</p>;
    }
    ```
Expo 完全支持构建仅限 Web 的组件，但是，你可能希望组织代码以更好地支持同时构建 Web 和原生平台。在 [特定于平台的模块](/router/advanced/platform-specific-modules) 中了解更多信息。
¥Building web-only components is fully supported by Expo, however, you may want to organize your code to better support building for both web and native platforms simultaneously. Learn more in [platform-specific modules](/router/advanced/platform-specific-modules).
Expo SDK 中的所有库都是为了支持浏览器和服务器渲染环境（如果适用）而构建的。库还针对其目标的各个平台进行了优化。
¥All of the libraries in the Expo SDK are built to support both browser and server rendering environments (when applicable). Libraries are also optimized for the individual platforms they target.
快速刷新、调试、环境变量和 [bundling](/guides/customizing-metro) 等开发功能也完全通用，从而实现统一的开发者体验。当你为生产而构建时，Expo CLI 会使用 [平台晃动](/guides/tree-shaking#platform-shaking) 等技术自动优化各个平台的代码。
¥Development features like Fast Refresh, debugging, environment variables, and [bundling](/guides/customizing-metro) are also fully universal, enabling a unified developer experience. Expo CLI **automatically optimizes code** for individual platforms when you build for production, using techniques like [platform shaking](/guides/tree-shaking#platform-shaking).
<a id="getting-started"></a>
## 入门
¥Getting started
<a id="install-web-dependencies"></a>
### 安装网络依赖
¥Install web dependencies
```sh
$ npx expo install react-dom react-native-web @expo/metro-runtime
```
Note: Not using the  package in your app yet?
---
If you haven't added Expo to your React Native app yet, you can either [install Expo modules](/bare/installing-expo-modules/) (recommended) or just install the `expo` package and configure the app entry file. This will allow you to target web, but it will not include support for the Expo SDK.
1. Install [Expo CLI](/more/expo-cli/) in your project:
```sh
$ npm install expo
```
2. Modify the entry file to use [`registerRootComponent`](/versions/latest/sdk/expo/#registerrootcomponentcomponent) instead of `AppRegistry.registerComponent`:
```diff
+ import {registerRootComponent} from 'expo';
import App from './App';
- import {AppRegistry} from 'react-native';
- import {name as appName} from './app.json';
- AppRegistry.registerComponent(appName, () => App);
+ registerRootComponent(App);
```
---
### Start the dev server
You can now start the dev server and develop in the browser with:
```sh
$ npx expo start --web
```
The app can be exported as a production website with:
```sh
$ npx expo export --platform web
```
<a id="next"></a>
## 下一章
¥Next


## 发布网站

了解如何部署 Expo 网站进行生产。

Expo Web 应用可以在本地提供服务以测试生产行为，并部署到托管服务。我们建议部署到 [EAS 托管](/eas/hosting) 以获得最佳功能支持。你还可以自行托管或使用第三方服务。
¥An Expo web app can be served locally for testing the production behavior, and deployed to a hosting service. We recommend deploying to [EAS Hosting](/eas/hosting) for the best feature support. You can also self-host or use a third-party service.
> 对于 SDK 49 及以下版本，你可能需要 [发布 `webpack` 构建的指南](/archive/publishing-websites-webpack/)。
>
> ¥For SDK 49 and below, you may need the [guide for publishing `webpack` builds](/archive/publishing-websites-webpack/).
<a id="output-targets"></a>
## 产出目标
¥Output targets
可以在 [应用配置](/workflow/configuration/) 中配置 [`web.output`](/versions/latest/config/app/#output) 目标来设置 Web 应用的导出方法：
¥The [`web.output`](/versions/latest/config/app/#output) target can be configured in the [app config](/workflow/configuration/) to set the export method for the web app:
```json app.json
{
  "expo": {
    "web": {
      "output": "server",
      "bundler": "metro"
    }
  }
}
```
Expo Router 支持 Web 应用的三个输出目标。
¥Expo Router supports three output targets for web apps.
| 输出           | Expo 路由 | API 路由 | 描述                                                                              |
| ------------ | ------- | ------ | ------------------------------------------------------------------------------- |
| `single`（默认） |         |        | 在输出目录中输出带有单个 index.html 的单页应用 (SPA)，并且没有静态可索引的 HTML。                            |
| `server`     |         |        | 创建客户端和服务器目录。客户端文件作为单独的 HTML 文件输出。API 路由作为单独的 JavaScript 文件，用于托管自定义 Node.js 服务器。 |
| `static`     |         |        | 为应用目录中的每个路由输出单独的 HTML 文件。                                                       |
<a id="create-a-build"></a>
## 创建构建
¥Create a build
创建项目的构建是发布 Web 应用的第一步。无论你是要在本地提供服务还是部署到托管服务，你都需要导出项目的所有 JavaScript 和资源。这称为静态打包包。可以通过运行以下命令导出它：
¥Creating a build of the project is the first step to publishing a web app. Whether you want to serve it locally or deploy to a hosting service, you'll need to export all JavaScript and assets of a project. This is known as a static bundle. It can be exported by running the following command:
运行通用导出命令来编译 Web 项目：
¥Run the universal export command to compile the project for web:
```sh
$ npx expo export -p web
```
生成的项目文件位于 dist 目录中。public 目录中的所有文件也会复制到 dist 目录中。
¥The resulting project files are located in the **dist** directory. Any files inside the **public** directory are also copied to the **dist** directory.
<a id="serve-locally"></a>
## 本地服务
¥Serve locally
使用 `npx expo serve` 在本地快速测试你的网站在生产环境中的托管方式。运行以下命令来提供静态打包包：
¥Use `npx expo serve` to quickly test locally how your website will be hosted in production. Run the following command to serve the static bundle:
```sh
$ npx expo serve
```
打开 [`http://localhost:8081`](http://localhost:8081) 查看你的项目的运行情况。这仅适用于 HTTP，因此权限、相机、位置和许多其他安全功能可能无法按预期工作。
¥Open [`http://localhost:8081`](http://localhost:8081) to see your project in action. This is **HTTP only**, so permissions, camera, location, and many other secure features may not work as expected.
<a id="hosting-with-eas"></a>
## 使用 EAS 托管
¥Hosting with EAS
当你准备好投入生产时，你可以立即使用 EAS CLI 部署你的网站。
¥When you're ready to go to production, you can instantly deploy your website with EAS CLI.
<a id="hosting-on-third-party-services"></a>
## 托管在第三方服务上
¥Hosting on third-party services
<a id="netlify"></a>
### Netlify
[Netlify](https://www.netlify.com/) 是一个几乎没有任何意见的用于部署 Web 应用的平台。这与 Expo Web 应用具有最高的兼容性，因为它对框架做了很少的假设。
¥[Netlify](https://www.netlify.com/) is a mostly-unopinionated platform for deploying web apps. This has the highest compatibility with Expo web apps as it makes few assumptions about the framework.
<a id="manual-deployment-with-the-netlify-cdn"></a>
#### 使用 Netlify CDN 手动部署
¥Manual deployment with the Netlify CDN
Step 1: 
Install the Netlify CLI by running the following command:
```sh
$ npm install -g netlify-cli
```
Step 2: 
Configure redirects for single-page applications.
> If your app uses [static rendering](/router/reference/static-rendering), then you can skip this step.
`expo.web.output: 'single'` generates a single-page application. It means there's only one **dist/index.html** file to which all requests must be redirected. This can be done in Netlify by creating a **./public/\_redirects** file and redirecting all requests to **/index.html**.
!!!IG1!!!
If you modify this file, you must rebuild your project with `npx expo export -p web` to have it safely copied into the **dist** directory.
Step 3: 
Deploy the web build directory by running the following command:
```sh
$ netlify deploy --dir dist
```
You'll see a URL that you can use to view your project online.
#### Continuous delivery
Netlify can also build and deploy when you push to git or open a new pull request:
- [Start a new Netlify project](https://app.netlify.com/signup).
- Pick your Git hosting service and select your repository.
- Click **Build your site**.
### Vercel
[Vercel](https://vercel.com/) has a single-command deployment flow.
Step 1: 
Install the [Vercel CLI](https://vercel.com/docs/cli).
```sh
$ npm install -g vercel@latest
```
Step 2: 
  Configure redirects for single-page applications.
Create a **vercel.json** file at the root of your app and add the following configuration:
!!!IG2!!!
If your app uses [static rendering](/router/reference/static-rendering), then you may want to add additional [dynamic route configuration](/router/reference/static-rendering#dynamic-routes).
Step 3: 
  Deploy the website.
{' '}
```sh
$ vercel
```
You'll now see a URL that you can use to view your project online. Paste that URL into your browser when the build is complete, and you'll see your deployed app.
### AWS Amplify Console
The [AWS Amplify Console](https://console.amplify.aws) provides a Git-based workflow for continuously deploying and hosting full-stack serverless web apps. Amplify deploys your PWA from a repository instead of from your computer. In this guide, we'll use a GitHub repository. Before starting, [create a new repo on GitHub](https://github.com/new).
Step 1: 
Add the [**amplify-explicit.yml**](https://github.com/expo/amplify-demo/blob/master/amplify-explicit.yml) file to the root of your repository. Ensure you have removed the generated **dist** directory from the **.gitignore** file and committed those changes.
Step 2: 
Push your local Expo project to a GitHub repository. If you haven't pushed to GitHub yet, follow [GitHub's guide to add an existing project to GitHub](https://docs.github.com/en/get-started/importing-your-projects-to-github/importing-source-code-to-github/adding-locally-hosted-code-to-github).
Step 3: 
Login to the [Amplify Console](https://console.aws.amazon.com/amplify/home) and select an existing app or create a new app. Grant Amplify permission to read from your GitHub account or the organization that owns your repo.
Step 4: 
Add your repo, select the branch, and select **Connecting a monorepo?** to enter the path to your app's **dist** directory and choose **Next**.
The Amplify Console will detect the **amplify.yml** file in your project. Select **Allow AWS Amplify to automatically deploy all files hosted in your project root directory** and choose **Next**.
Step 5: 
Review your settings and choose **Save and deploy**. Your app will now be deployed to a `https://branchname.xxxxxx.amplifyapp.com` URL. You can now visit your web app, deploy another branch, or add a unified backend environment across your Expo mobile and web apps.
Follow the steps in the **Learn how to get the most out of Amplify Hosting** drop-down to **Add a custom domain with a free SSL certificate** and more information.
### Firebase hosting
[Firebase Hosting](https://console.firebase.google.com/) is production-grade web content hosting for web projects.
Step 1: 
Create a firebase project with the [Firebase Console](https://console.firebase.google.com) and install the Firebase CLI by following these [instructions](https://firebase.google.com/docs/hosting).
Step 2: 
Using the CLI, login to your Firebase account by running the command:
```sh
$ firebase login
```
Step 3: 
Then, initialize your firebase project to host by running the command:
```sh
$ firebase init
```
The settings will depend on how you built your Expo website:
1. When asked about the public path, make sure to specify the **dist** directory.
2. When prompted **Configure as a single-page app (rewrite all urls to /index.html)**, only select **Yes** if you used `web.output: "single"` (default). Otherwise, select **No**.
Step 4: 
In the existing `scripts` property of **package.json**, add `predeploy` and `deploy` properties. Each has the following values:
!!!IG19!!!
!!!IG3!!!
Step 5: 
To deploy, run the following command:
```sh
$ npm run deploy-hosting
```
Open the URL from the console output to check your deployment, for example: `https://project-name.firebaseapp.com`.
In case you want to change the header for hosting add the following config for `hosting` section in **firebase.json**:
!!!IG20!!!
!!!IG4!!!
### GitHub Pages
[GitHub Pages](https://pages.github.com/) allows you to publish a website directly from a GitHub repository.
> **warning** GitHub Pages deployment uses experimental `baseUrl` functionality that may not work as intended.
Step 1: 
Start by initializing a new git repository in your project and configuring it to push to a GitHub repository. If you are already syncing your changes with a GitHub repository, skip this step.
Create a repository on the GitHub website. Then, run the following commands in your project's root directory:
```sh
$ git init
$ git remote add origin https://github.com/username/expo-gh-pages.git
```
The above commands initialize a new Git repository and configure it to push your source code to the specified GitHub repository.
Step 2: 
Install the `gh-pages` package as a development dependency in your project:
!!!IG7!!!
!!!IG8!!!
```sh
$ npm install --save-dev gh-pages
```
!!!IG9!!!
!!!IG10!!!
```sh
$ yarn add -D gh-pages
```
!!!IG11!!!
!!!IG12!!!
Step 3: 
To deploy the project, configure it to a subdomain with the [`baseUrl`](/versions/latest/config/app/#baseurl) property in [app config](/workflow/configuration/). Set its value to the string `/repo-name`.
For example, if the GitHub repository is `expo-gh-pages`, the following will be the value of the [experimental `baseUrl` property](/more/expo-cli/#hosting-with-sub-paths):
!!!IG21!!!
!!!IG5!!!
Step 4: 
Modify the `scripts` in the **package.json** file by adding `predeploy` and `deploy` scripts. Each has its own value:
!!!IG22!!!
!!!IG6!!!
Since Expo uses underscores in generated files, you need to disable Jekyll with the `--nojekyll` flag.
Step 5: 
To generate a production build of the web app and deploy it to GitHub Pages, run the following command:
!!!IG13!!!
!!!IG14!!!
```sh
$ npm run deploy
```
!!!IG15!!!
!!!IG16!!!
```sh
$ yarn deploy
```
!!!IG17!!!
!!!IG18!!!
This publishes a build of the web app to the `gh-pages` branch of your GitHub repository. This branch only contains build artifacts from the **dist** directory, plus the **.nojekyll** file generated by `gh-pages`. It does not include development source code.
Step 6: 
Now that the web app is published to the `gh-pages` branch, configure GitHub Pages to serve the app from that branch.
- Navigate to the **Settings** tab of the GitHub repository.
- Scroll down to **Pages** section.
- Ensure the **Source** is set to **Deploy from a branch**.
- Under **Branch** section, select **gh-pages** and the **root** directory.
- Click **Save**.
Step 7: 
Once the web app is published and the GitHub Pages configuration is set, a GitHub Action will deploy your website. You can monitor its progress by navigating to your repository's **Actions** tab. Upon completion, your web app will be available at the URL `http://username-on-github.github.io/repo-name`.
For subsequent deployments and updates, run the `deploy` command and the GitHub Action will start automatically to update your web app.


## 在 Expo 原生应用中使用 React DOM

了解如何使用 '使用 dom' 指令在 Expo 原生应用中渲染 React DOM 组件。

>  **info** 在 SDK 52 及以上版本中可用。
>
> ¥Available in **SDK 52 and above**.
Expo 通过 `'use dom'` 指令提供了一种新颖的方法，可直接在原生应用中使用现代 Web 代码。这通过按组件移动，实现了整个网站到通用应用的增量迁移。
¥Expo offers a novel approach to work with modern web code directly in a native app via the `'use dom'` directive. This enables incremental migration for an entire website to a universal app by moving on a per-component basis.
虽然 Expo 原生运行时通常不支持 `<div>` 或 `<img>` 等元素，但在某些情况下你可能需要快速合并 Web 组件。在这种情况下，DOM 组件提供了一个有用的解决方案。
¥While the Expo native runtime generally does not support elements like `<div>` or `<img>`, there may be instances where you need to quickly incorporate web components. In such cases, DOM components provide a useful solution.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
Note: Your project must use Expo CLI and extend the Expo Metro Config
---
If you already run your project with `npx expo [command]` (for example, if you created it with `npx create-expo-app`), then you're all set, and you can skip this step.
If you don't have the `expo` package in your project yet, then install it by running the command below and [opt in to using Expo CLI and Metro Config](/bare/installing-expo-modules/#configure-expo-cli-for-bundling-on-android-and-ios):
```sh
$ npx install-expo-modules@latest
```
If the command fails, refer to the [Installing Expo modules](/bare/installing-expo-modules/#manual-installation) guide.
---
Note: Expo Metro Runtime, React DOM, and React Native Web
---
If you are using Expo Router and Expo Web, you can skip this step. Otherwise, install the following packages:
```sh
$ npx expo install @expo/metro-runtime react-dom react-native-web
```
---
## Usage
Install `react-native-webview` in your project:
```sh
$ npx expo install react-native-webview
```
To render a React component to the DOM, add the `'use dom'` directive to the top of the web component file:
!!!IG0!!!
Inside the native component file, import the web component to use it:
!!!IG1!!!
## Features
- Shared bundler config across web, native, and DOM components.
- React, TypeScript, CSS, and all other Metro features are enabled in DOM components.
- Logging in the terminal and Safari/Chrome debugging.
- Fast Refresh and HMR.
- Embedded exports for offline support.
- Assets are unified across web and native.
- DOM component bundles can be introspected in [Expo Atlas](/guides/analyzing-bundles/#analyzing-bundle-size-with-atlas) for debugging.
- Access to all web functionality without needing a native rebuild.
- Runtime error overlay in development.
- Supports Expo Go.
## WebView props
To pass props to the underlying native **WebView**, use the `dom` prop on the component. This prop is built into every DOM component and accepts an object with any [`WebView` props](https://github.com/react-native-webview/react-native-webview/blob/master/docs/Reference.md) that you would like to change.
!!!IG2!!!
On your DOM component, add the `dom` prop so it is recognized in TypeScript:
!!!IG3!!!
## Marshalled props
You can send data to the DOM component through serializable props (`number`, `string`, `boolean`, `null`, `undefined`, `Array`, `Object`). For example, inside a native component file, you can pass a prop to the DOM component:
!!!IG4!!!
Inside the web component file, you can receive the prop as shown in the example below:
!!!IG5!!!
Props are sent over an asynchronous bridge so they are not updated synchronously. They are passed as props to the React root component, which means they re-render the entire React tree.
## Native actions
You can send type-safe native functions to DOM components by passing asynchronous functions as top-level props to the DOM component:
!!!IG6!!!
!!!IG7!!!
> You cannot pass functions as nested props to DOM components. They must be top-level props.
Native actions are always asynchronous and accept only serializable arguments (meaning no functions) because the data is sent over a bridge to the DOM component's JavaScript engine.
Native actions can return serializable data to the DOM component, which is useful for getting data back from the native side.
!!!IG8!!!
Think of these functions like React Server Functions, but instead of residing on the server, they live locally in the native app and communicate with the DOM component. This approach provides a powerful way to add truly native functionality to your DOM components.
## Passing refs
> **important** This is experimental and may change in the future.
You can use the `useDOMImperativeHandle` hook inside a DOM component to accept ref calls from the native side. This hook is similar to React's [`useImperativeHandle`](https://react.nodejs.cn/reference/react/useImperativeHandle) hook, but it does not need a ref object to be passed to it.
!!!IG9!!!
!!!IG21!!!
!!!IG22!!!
Expo SDK 53 and above use React 19. This means that the `ref` prop is passed to the component as a prop, and you can use it directly in the component.
!!!IG10!!!
!!!IG23!!!
!!!IG24!!!
In Expo SDK 52 and below (React 18), use the legacy `forwardRef` function to access the `ref` handle.
!!!IG11!!!
!!!IG25!!!
!!!IG26!!!
React is meant to have a unilateral data flow, so the concept of using callbacks to go back up the tree is not idiomatic. Expect the behavior to be flakey and possibly phased out in the future with newer versions of React. The preferred way to send data back up the tree is to use native actions, which update the state and then pass it back to the DOM component.
## Feature detection
Since DOM components are used to run websites, you might need extra qualifiers to better support certain libraries. You can detect if a component is running in a DOM component with the following code:
!!!IG12!!!
## Public assets
> **important** **Warning:** This is experimental and may change in the future. Public assets are not supported in EAS Update. Use `require()` to load local assets instead.
The contents of the root **public** directory are copied to the native app's binary to support the use of public assets in DOM components. Since these public assets will be served from the local filesystem, use the `process.env.EXPO_BASE_URL` prefix to reference the correct path. For example:
!!!IG13!!!
## Debugging
By default, all `console.log` methods are extended in WebViews to forward logs to the terminal. This makes it fast and easy to see what's happening in your DOM components.
Expo also enables WebView inspection and debugging when bundling in development mode. You can open **Safari** > **Develop** > **Simulator** > **MyComponent.tsx** to see the WebView's console and inspect elements.
## Manual WebViews
You can create a manual WebView using the `WebView` component from `react-native-webview`. This can be useful for rendering websites from a remote server.
!!!IG14!!!
## Routing
Expo Router APIs such as `<Link />`, and `useRouter` can be used in DOM components to navigate between routes.
!!!IG15!!!
APIs that synchronously return routing info such as `useLocalSearchParams()`, `useGlobalSearchParams()`, `usePathname()`, `useSegments()`, `useRootNavigation()`, and `useRootNavigationState()` are not automatically supported. Instead, read these values outside of DOM components and supply them as props.
!!!IG16!!!
The `router.canGoBack()` and `router.canDismiss()` functions are also unsupported and require manual marshalling, this ensures no extraneous render cycles are triggered.
Avoid using standard web `<a />` anchor elements for navigation as these will change the DOM component origin in a way that users may not be able to navigate back from. Prefer launching `WebBrowser`s if you want to present external websites.
Since DOM components cannot render native children, layout routes (`_layout`) can never be DOM components. You can render DOM components from layout routes to create headers, backgrounds, and more, but the layout route itself should always be native.
## Measuring DOM components
You may want to measure the size of a DOM component and report it back to the native side (for example, native scrolling). This can be done using a `matchContents` prop or a manual native action:
### Automatically with `matchContents` prop
You can use the `dom={{ matchContents: true }}` prop to measure the size of the DOM component automatically and resize the native view. This is particularly useful for certain layouts where the DOM component must have an intrinsic size in order to be displayed, such as when the component is centered within a parent view:
!!!IG17!!!
### Manually by specifying a size
You can also manually provide a size by passing it to the `WebView` `style` prop via the `dom` prop:
!!!IG18!!!
### Observing changes in size
If you would like to report changes in the size of the DOM component back to the native side, you can add a native action to your DOM component that is called whenever the size is changed:
!!!IG19!!!
Then update your native code to set the size in state whenever the DOM component reports a change in size:
!!!IG20!!!
## Architecture
Built-in DOM support only renders websites as single-page applications (no SSR or SSG). This is because search engine optimization and indexing are unnecessary for embedded JS code.
When a module is marked with `'use dom'`, it is replaced with a proxy reference imported at runtime. This feature is primarily achieved through a series of bundler and CLI techniques.
If desired, you can still use a WebView with the standard approach by passing raw HTML to a `WebView` component.
DOM components rendered within websites or other DOM components will behave as regular components, and the `dom` prop will be ignored. This is because web content is passed directly through and not wrapped in an `iframe`.
Overall, this system shares many similarities with Expo's React Server Components implementation.
## Considerations
We recommend building truly native apps using universal primitives such as `View`, `Image`, and `Text`. DOM components only support standard JavaScript, which is slower to parse and start up than optimized Hermes bytecode.
Data can be sent between DOM components and native components only through an asynchronous JSON transport system. Avoid relying on data across JS engines and deep linking to nested URLs in DOM components, as they do not currently support full reconciliation with Expo Router.
While DOM components are not exclusive to Expo Router, they are developed and tested against Expo Router apps to provide the best experience when used with Expo Router.
If you have a global state for sharing data, it will not be accessible across JS engines.
While native modules in the Expo SDK can be optimized to support DOM components, this optimization has not been implemented yet. Use native actions and props to share native functionality with DOM components.
DOM components and websites in general are less optimal than native views but there are some reasonable uses for them. For example, the web is conceptually the best way to render rich-text and markdown. The web also has very good WebGL support, with the caveat that devices in low-power mode will often throttle web frame rates to preserve battery.
Many large apps also use some web content for auxiliary routes such as blog posts, rich-text (for example, long-form posts on X), settings pages, help pages, and other less frequently visited parts of the app.
## Server Components
DOM components currently only render as single-page applications and don't support static rendering or React Server Components (RSC). When the project uses React Server Components, `'use dom'` will work the same as `'use client'` regardless of the platform. RSC Payloads can be passed as properties to DOM components. However, they cannot be hydrated correctly on native platforms as they'll be rendered for a native runtime.
## Limitations
- Unlike server components, you cannot pass `children` to DOM components.
- DOM components are standalone and do not automatically share data between different instances.
- You cannot add native views to DOM components. While you can attempt to float native views over DOM components, this approach results in a suboptimal user experience.
- Function props cannot return values synchronously. They must be asynchronous.
- DOM components can currently only be embedded and do not support OTA updates. This functionality may be added in the future as part of React Server Components.
Ultimately, universal architecture is the most exciting kind. Expo CLI's extensive universal tooling is the only reason we can even offer a feature as intricate and valuable as this one.
While DOM components help with migration and moving quickly, we recommend using truly native views whenever possible.
## Common questions
### How to obtain a Secure Context in DOM components?
Some Web APIs require a [Secure Context](https://web.nodejs.cn/en-US/docs/Web/Security/Secure_Contexts) function correctly. For example, the [Clipboard API](https://web.nodejs.cn/en-US/docs/Web/API/Clipboard_API) is only available in secure contexts. A secure context means that remote resources must be served over HTTPS. [Learn more about features restricted to secure contexts](https://web.nodejs.cn/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts).
To ensure your DOM components run within a secure context, follow these guidelines:
- **Release builds**: DOM components served using the `file://` scheme are provided a secure context by default.
- **Debug builds**: When using development servers (which default to the `http:// `protocol), you can use [tunneling](/more/expo-cli/#tunneling) to serve DOM components over HTTPS.
Note: Example commands to tunnel DOM components over HTTPS
---
```sh
$ npx expo install expo-dev-client
$ npx expo run:android
$ npx expo start --tunnel -d -a
$ npx expo run:ios
$ npx expo start --tunnel -d -i
```
---


## 渐进式网络应用

了解如何向 Expo 网站添加渐进式 Web 应用支持。

渐进式网络应用（简称 PWA）是一个可以安装在用户设备上并离线使用的网站。我们建议尽可能构建原生应用，因为它们具有最好的离线支持，但 PWA 对于桌面用户来说是一个不错的选择。
¥A progressive web app (or PWA for short) is a website that can be installed on the user's device and used offline. We recommend building native apps whenever possible as they have the best offline support, but PWAs are a great option for desktop users.
<a id="favicons"></a>
## 网站图标
¥Favicons
Expo CLI 根据 app.json 中的 `web.favicon` 字段自动生成 favicon.ico 文件。
¥Expo CLI automatically generates the **favicon.ico** file based on the `web.favicon` field in the **app.json**.
```json
{
  "web": {
    "favicon": "./assets/favicon.png"
  }
}
```
或者，你可以在 public 目录中创建 favicon.ico 文件来手动指定图标。
¥Alternatively, you can create a **favicon.ico** file in the **public** directory to manually specify the icon.
<a id="manifest-file"></a>
## 清单文件
¥Manifest file
PWA 可以是 [使用清单文件配置](https://web.nodejs.cn/en-US/docs/Web/Manifest)，描述应用的名称、图标和其他元数据。
¥PWAs can be [configured with a manifest file](https://web.nodejs.cn/en-US/docs/Web/Manifest) that describes the app's name, icon, and other metadata.
Step 1: 
Create a PWA manifest in **public/manifest.json**:
```json
{
  "short_name": "Expo App",
  "name": "Expo Router Sample",
  "icons": [
    {
      "src": "favicon.ico",
      "sizes": "64x64 32x32 24x24 16x16",
      "type": "image/x-icon"
    },
    {
      "src": "logo192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "logo512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "start_url": ".",
  "display": "standalone",
  "theme_color": "#000000",
  "background_color": "#ffffff"
}
```
Step 2: 
The files **logo192.png** and **logo512.png** are the icons that will be used when the app is installed on the user's device. These should be added to the **public** directory too.
Step 3: 
Now link the manifest in your HTML file. The method here depends on the output mode of your website (indicated in `web.output` in the **app.json**––defaults to `single`).
For single: 
If you're using a single-page app, you can link the manifest in your HTML file by first creating a template HTML in **public/index.html**:
```sh
$ npx expo customize public/index.html
```
Then add the manifest to the `<head>` tag:
```html
<link rel="manifest" href="/manifest.json" />
```
For static & server: 
If you're using static or server rendering, the HTML entry can be dynamically created in **app/+html.tsx**. Here we'll link the manifest by adding a `<link>` tag to the `<head>` component:
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import type { PropsWithChildren } from 'react';
// This file is web-only and used to configure the root HTML for every
// web page during static rendering.
// The contents of this function only run in Node.js environments and
// do not have access to the DOM or browser APIs.
export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
        {/* Link the PWA manifest file. */}
        <link rel="manifest" href="/manifest.json" />
        {/*
          Disable body scrolling on web. This makes ScrollView components work closer to how they do on native.
          However, body scrolling is often nice to have for mobile web. If you want to enable it, remove this line.
        */}
        <ScrollViewStyleReset />
        {/* Add any additional <head> elements that you want globally available on web... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
```
## Service workers
Service workers are primarily used to add offline support to websites. Google's Workbox is the best way to add service workers to a website. Follow the guide for [using Workbox CLI](https://developer.chrome.com/docs/workbox/modules/workbox-cli/), and wherever it refers to a "build script" use `npx expo export -p web` instead.
> **warning** Be careful adding service workers as they are known to cause unexpected behavior on web. If you accidentally ship a service worker that aggressively caches your website, users cannot request updates easily. For the best offline mobile experience, create a native app with Expo. Unlike websites with service workers, native apps can be updated through the app store to clear the cached experience. This would be similar to resetting the user's native browser (which they may have to do if the service worker is aggressive enough). See [why service workers are suboptimal](https://github.com/facebook/create-react-app/issues/2398) for more information.
For example, here's a possible flow for setting up Workbox:
Step 1: 
Create a new project with the following command:
```sh
$ npm create expo -t tabs my-app
$ cd my-app
```
Step 2: 
Now register the service worker in the HTML file. The method here depends on the output mode of your website (indicated in `web.output` in the **app.json**––defaults to `single`).
For single: 
Next add a service worker registration script to the root **index.html**.
First create a template HTML in **public/index.html** if one does not already exist:
```sh
$ npx expo customize public/index.html
```
Then create the service worker registration script in the `<head>` tag:
```html
<script>
  if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
      navigator.serviceWorker
        .register('/sw.js')
        .then(registration => {
          console.log('Service Worker registered with scope:', registration.scope);
        })
        .catch(error => {
          console.error('Service Worker registration failed:', error);
        });
    });
  }
</script>
```
For static & server: 
Next, create a root HTML file for the app and add the service worker registration script:
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import type { PropsWithChildren } from 'react';
// This file is web-only and used to configure the root HTML for every
// web page during static rendering.
// The contents of this function only run in Node.js environments and
// do not have access to the DOM or browser APIs.
export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
        {/* Bootstrap the service worker. */}
        <script dangerouslySetInnerHTML={{ __html: sw }} />
        {/*
          Disable body scrolling on web. This makes ScrollView components work closer to how they do on native.
          However, body scrolling is often nice to have for mobile web. If you want to enable it, remove this line.
        */}
        <ScrollViewStyleReset />
        {/* Add any additional <head> elements that you want globally available on web... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
const sw = `
if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
        navigator.serviceWorker.register('/sw.js').then(registration => {
            console.log('Service Worker registered with scope:', registration.scope);
        }).catch(error => {
            console.error('Service Worker registration failed:', error);
        });
    });
}
`;
```
Step 3: 
Now build the website before running the wizard:
```sh
$ npx expo export -p web
```
Step 4: 
Run the wizard command, select `dist` as the root of the app, and the defaults for everything else:
```sh
$ npx workbox-cli wizard
? What is the root of your web app (that is which directory do you deploy)? dist/
? Which file types would you like to precache? js
html
ttf
ico
json
? Where would you like your service worker file to be saved? dist/sw.js
? Where would you like to save these configuration options? workbox-config.js
? Does your web app manifest include search parameter(s) in the 'start_url
other than 'utm_' or 'fbclid' (like '?source=pwa')? No
```
Step 5: 
Finally, run `npx workbox-cli generateSW workbox-config.js` to generate the service worker config.
Going forward, you can add a build script in **package.json** to run both scripts in the correct order:
```json package.json
{
  "scripts": {
    "build:web": "expo export -p web && npx workbox-cli generateSW workbox-config.js"
  }
}
```
Step 6: 
If you host your website and visit with Chrome, you can inspect the service worker by going to **Application > Service Workers** in the Chrome DevTools.


## Tailwind CSS

了解如何在你的 Expo 项目中配置和使用 Tailwind CSS。

>  **info** 标准 Tailwind CSS 仅支持 Web 平台。对于通用支持，请使用 [NativeWind](https://www.nativewind.dev/) 等库，它允许使用 Tailwind CSS 创建样式化的 React Native 组件。
>
> ¥Standard Tailwind CSS supports only web platform. For universal support, use a library such as [NativeWind](https://www.nativewind.dev/), which allows creating styled React Native components with Tailwind CSS.
[Tailwind CSS](https://tailwind.nodejs.cn/) 是一个实用优先的 CSS 框架，可以与 Metro 一起用于 Web 项目。本指南介绍如何配置 Expo 项目以使用该框架。
¥[Tailwind CSS](https://tailwind.nodejs.cn/) is a utility-first CSS framework and can be used with Metro for web projects. This guide explains how to configure your Expo project to use the framework.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
将修改以下文件以设置 Tailwind CSS 配置：
¥The following files will be modified to set the Tailwind CSS configuration:
确保你的项目正在使用 Metro for web。你可以通过检查 app.json 文件中设置为 `metro` 的 `web.bundler` 字段来验证这一点。
¥Ensure that your project is using Metro for web. You can verify this by checking the `web.bundler` field which is set to `metro` in the **app.json** file.
```json app.json
{
  "expo": {
    "web": {
      "bundler": "metro"
    }
  }
}
```
<a id="configuration"></a>
## 配置
¥Configuration
根据 [Tailwind PostCSS 文档](https://tailwind.nodejs.cn/docs/installation/using-postcss) 在你的 Expo 项目中配置 Tailwind CSS。
¥Configure Tailwind CSS in your Expo project according to the [Tailwind PostCSS documentation](https://tailwind.nodejs.cn/docs/installation/using-postcss).
For v3: 
Step 1: 
Install `tailwindcss` and its required peer dependencies. Then, the run initialization command to create **tailwind.config.js** and **post.config.js** files in the root of your project.
```sh
$ npx expo install tailwindcss@3 postcss autoprefixer --dev
$ npx tailwindcss init -p
```
Step 2: 
Add paths to all of your template files inside **tailwind.config.js**.
```js tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // Ensure this points to your source code
    './app/**/*.{js,tsx,ts,jsx}',
    // If you use a `src` directory, add: './src/**/*.{js,tsx,ts,jsx}'
    // Do the same with `components`, `hooks`, `styles`, or any other top-level directories
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```
> If you are using Expo Router, consider using a root **src** directory to simplify this step. Learn more about [top-level src directory](/router/reference/src-directory/).
Step 3: 
Create a **global.css** file in the root of your project and directives for each of Tailwind's layers:
```css global.css
/* This file adds the requisite utility classes for Tailwind to work. */
@tailwind base;
@tailwind components;
@tailwind utilities;
```
Step 4: 
Import the **global.css** file in your **app/\_layout.tsx** (if using Expo Router) or **index.js** file:
```tsx
import '../global.css';
```
```tsx
// Import the global.css file in the index.js file:
import './global.css';
```
> **info** If you are using [DOM components](/guides/dom-components), add this file import to each module using the `"use dom"` directive since they don't share globals.
Step 5: 
You now start your project and use Tailwind CSS classes in your components.
```sh
$ npx expo start
```
For v4: 
Step 1: 
Install `tailwindcss` and its required peer dependencies:
```sh
$ npx expo install tailwindcss @tailwindcss/postcss postcss --dev
```
Step 2: 
Add Tailwind to your PostCSS configuration
```js postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
```
Step 3: 
Create a global CSS file that imports Tailwind CSS.
You can choose any name for this file. Using **global.css** is common practice.
```css global.css
@import 'tailwindcss';
```
Step 4: 
Import your CSS file in your **app/\_layout.tsx** (if using Expo Router) or **index.js** file:
```tsx
// If using Expo Router, import your CSS file in the app/_layout.tsx file
import '../global.css';
```
```tsx
// Otherwise import your CSS file in the index.js file:
import './global.css';
```
> **info** If you are using [DOM components](/guides/dom-components), add this file import to each module using the `"use dom"` directive since they don't share globals.
Step 5: 
You now start your project and use Tailwind CSS classes in your components.
```sh
$ npx expo start
```
<a id="usage"></a>
## 用法
¥Usage
你可以按原样将 Tailwind 与 React DOM 元素一起使用：
¥You can use Tailwind with React DOM elements as-is:
```tsx app/index.tsx
export default function Index() {
  return (
    <div className="bg-slate-100 rounded-xl">
      <p className="text-lg font-medium">Welcome to Tailwind</p>
    </div>
  );
}
```
你可以使用 `{ $$css: true }` 语法将 Tailwind 与 React Native Web 元素一起使用：
¥You can use the `{ $$css: true }` syntax to use Tailwind with React Native web elements:
```tsx app/index.tsx
import { View, Text } from 'react-native';
export default function Index() {
  return (
    <View style={{ $$css: true, _: 'bg-slate-100 rounded-xl' }}>
      <Text style={{ $$css: true, _: 'text-lg font-medium' }}>Welcome to Tailwind</Text>
    </View>
  );
}
```
<a id="tailwind-for-android-and-ios"></a>
## 适用于 Android 和 iOS 的 Tailwind
¥Tailwind for Android and iOS
Tailwind 不支持 Android 和 iOS 平台。你可以使用兼容性库（如 [NativeWind](https://www.nativewind.dev/)）获得通用支持。
¥Tailwind does not support Android and iOS platforms. You can use a compatibility library such as [NativeWind](https://www.nativewind.dev/) for universal support.
<a id="alternative-for-android-and-ios"></a>
## Android 和 iOS 的替代方案
¥Alternative for Android and iOS
或者，你可以使用 [DOM 组件](/guides/dom-components) 在原生上的 `WebView` 中渲染你的 Tailwind Web 代码。
¥Alternatively, you can use [DOM components](/guides/dom-components) to render your Tailwind web code in a `WebView` on native.
```tsx app/index.tsx
'use dom';
// Remember to import the global.css file in each DOM component.
import '../global.css';
export default function Page() {
  return (
    <div className="bg-slate-100 rounded-xl">
      <p className="text-lg font-medium">Welcome to Tailwind</p>
    </div>
  );
}
```
<a id="troubleshooting"></a>
## 故障排除
¥Troubleshooting
如果你的 Metro.config.js 中有自定义 `config.cacheStores`，则需要扩展 `FileStore` 的 Expo 超类：
¥If you have a custom `config.cacheStores` in your **metro.config.js**, you need to extend the Expo superclass of `FileStore`:
```js metro.config.js
// Import the Expo superclass which has support for PostCSS.
const { FileStore } = require('@expo/metro-config/file-store');
config.cacheStores = [
  new FileStore({
    root: '/path/to/custom/cache',
  }),
];
module.exports = config;
```
确保你的 Metro.config.js 中没有禁用 CSS：
¥Ensure you don't have CSS disabled in your **metro.config.js**:
```js metro.config.js
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname, {
  // Do not disable CSS support when using Tailwind.
  isCSSEnabled: true,
});
```


# 打包

## Metro 打包器

了解可定制的不同 Metro 打包器配置。

Expo CLI 在 [`npx expo start`](/more/expo-cli/#develop) 和 [`npx expo export`](/more/expo-cli/#exporting) 期间使用 [Metro](https://metrobundler.dev/) 来打包你的 JavaScript 代码和资源。Metro 是针对 React Native 构建和优化的，用于 Facebook 和 Instagram 等大型应用。
¥Expo CLI uses [Metro](https://metrobundler.dev/) during [`npx expo start`](/more/expo-cli/#develop) and [`npx expo export`](/more/expo-cli/#exporting) to bundle your JavaScript code and assets. Metro is built and optimized for React Native and used for large-scale applications such as Facebook and Instagram.
<a id="customizing"></a>
## 定制
¥Customizing
你可以通过在项目根目录下创建 Metro.config.js 文件来自定义 Metro 打包程序。该文件应导出扩展 [`expo/metro-config`](https://github.com/expo/expo/tree/main/packages/@expo/metro-config) 的 [Metro 配置](https://metrobundler.dev/docs/configuration/)。导入 `expo/metro-config` 而不是 `@expo/metro-config`，以保证版本一致性。
¥You can customize the Metro bundler by creating a **metro.config.js** file at the root of your project. This file should export a [Metro configuration](https://metrobundler.dev/docs/configuration/) that extends [`expo/metro-config`](https://github.com/expo/expo/tree/main/packages/@expo/metro-config). Import `expo/metro-config` instead of `@expo/metro-config` to ensure version consistency.
运行以下命令生成模板文件：
¥Run the following command to generate the template file:
```sh
$ npx expo customize metro.config.js
```
Metro.config.js 文件如下所示：
¥The **metro.config.js** file looks as below:
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
module.exports = config;
```
请参阅 [Metro.config.js 文档](https://metrobundler.dev/docs/configuration/) 了解更多信息。
¥See [**metro.config.js** documentation](https://metrobundler.dev/docs/configuration/) for more information.
<a id="assets"></a>
## 资源
¥Assets
Metro 将文件解析为源代码或资源。源代码是 JavaScript、TypeScript、JSON 和应用使用的其他文件。[资源](/develop/user-interface/assets/) 是不应由 Metro 转换的图片、字体和其他文件。为了适应大规模代码库，Metro 要求在启动打包器之前显式定义源代码和资源的所有扩展。这是通过将 `resolver.sourceExts` 和 `resolver.assetExts` 选项添加到 Metro 配置来完成的。默认情况下，包含以下扩展：
¥Metro resolves files as either source code or assets. Source code is JavaScript, TypeScript, JSON, and other files used by your application. [Assets](/develop/user-interface/assets/) are images, fonts, and other files that should not be transformed by Metro. To accommodate large-scale codebases, Metro requires all extensions for both source code and assets to be explicitly defined before starting the bundler. This is done by adding the `resolver.sourceExts` and `resolver.assetExts` options to the Metro configuration. By default, the following extensions are included:
* [`resolver.assetExts`](https://github.com/facebook/metro/blob/7028b7f51074f9ceef22258a8643d0f90de2388b/packages/metro-config/src/defaults/defaults.js#L15)
* [`resolver.sourceExts`](https://github.com/facebook/metro/blob/7028b7f51074f9ceef22258a8643d0f90de2388b/packages/metro-config/src/defaults/defaults.js#L53)
<a id="adding-more-file-extensions-to-assetexts"></a>
### 向 `assetExts` 添加更多文件扩展名
¥Adding more file extensions to `assetExts`
最常见的定制是包含 Metro 的额外资源扩展。
¥The most common customization is to include extra asset extensions to Metro.
在 Metro.config.js 文件中，将文件扩展名（不带前导 `.`）添加到 `resolver.assetExts` 数组：
¥In the **metro.config.js** file, add the file extension (without a leading `.`) to `resolver.assetExts` array:
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.resolver.assetExts.push(
  // Adds support for `.db` files for SQLite databases
  'db'
);
module.exports = config;
```
<a id="aliases"></a>
## 别名
¥Aliases
有时你希望将导入重定向到另一个模块或文件。这称为别名。由于 Metro 同时为多个平台打包的方式，我们建议使用自定义解析器来处理别名。
¥Sometimes you want an import to be redirected to another module or file. This is called an alias. Due to the way Metro bundles for multiple platforms simultaneously, we recommend using a custom resolver to handle aliases.
在下面的示例中，我们将为 `old-module` 到 `new-module` 添加一个别名：
¥In the following example, we'll add an alias for `old-module` to `new-module`:
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);
const ALIASES = {
  'old-module': 'new-module',
};
config.resolver.resolveRequest = (context, moduleName, platform) => {
  // Ensure you call the default resolver.
  return context.resolveRequest(
    context,
    // Use an alias if one exists.
    ALIASES[moduleName] ?? moduleName,
    platform
  );
};
module.exports = config;
```
如果你只想在某个平台上应用别名，你可以检查 `platform` 参数：
¥If you want to only apply the alias on a certain platform, you can check the `platform` argument:
```js metro.config.js
config.resolver.resolveRequest = (context, moduleName, platform) => {
  if (platform === 'web') {
    // The alias will only be used when bundling for the web.
    return context.resolveRequest(context, ALIASES[moduleName] ?? moduleName, platform);
  }
  // Ensure you call the default resolver.
  return context.resolveRequest(context, moduleName, platform);
};
```
你将在下次重新启动开发服务器时看到更改。解析永远不会被缓存，不需要 `--clear` 标志来更新。如果你使用像 `babel-plugin-module-resolver` 这样的基于转换的系统，则需要清除缓存才能看到应用的更改。
¥You will see the changes the next time you restart the dev server. Resolutions are never cached and do not need the `--clear` flag to update. If you use a transform-based system like `babel-plugin-module-resolver`, you will need to clear the cache to see changes applied.
<a id="bundle-splitting"></a>
## 打包分裂
¥Bundle splitting
Expo CLI 会根据异步导入自动拆分 bundle（仅限 Web 应用）。
¥Expo CLI automatically splits bundles based on async imports (web-only).
此技术可与 Expo Router 一起使用，根据应用目录中的路由文件自动拆分包。它将仅加载当前路由所需的代码，并推迟加载其他 JavaScript，直到用户导航到不同的页面。请参阅 [异步路由](/router/reference/async-routes) 了解更多信息。
¥This technique can be used with Expo Router to automatically split the bundle based on route files in the **app** directory. It will only load the code required for the current route, and defer loading additional JavaScript until the user navigates to different pages. See [Async Routes](/router/reference/async-routes) for more information.
<a id="tree-shaking"></a>
## 摇树
¥Tree shaking
<a id="minification"></a>
## 缩小化
¥Minification
<a id="web-support"></a>
## Web 支持
¥Web support
Expo CLI 支持使用 Metro 打包网站。这与用于原生应用的打包器相同，并且它被设计为跨平台通用。它是推荐用于 Web 项目的打包工具。
¥Expo CLI has support for bundling websites using Metro. This is the same bundler used for native apps, and it is designed to be universal across platforms. It is the recommended bundler for web projects.
<a id="expo-webpack-versus-expo-metro"></a>
### Expo webpack 与 Expo Metro
¥Expo webpack versus Expo Metro
如果你之前使用已弃用的 `@expo/webpack-adapter` 编写网站，请参阅 [迁移指南](/router/migrate/from-expo-webpack) 和 [对比图](/router/migrate/from-expo-webpack#expo-cli)。
¥If you previously wrote your website using the deprecated `@expo/webpack-adapter`, see the [migration guide](/router/migrate/from-expo-webpack) and [comparison chart](/router/migrate/from-expo-webpack#expo-cli).
<a id="adding-web-support-to-metro"></a>
### 为 Metro 添加 Web 支持
¥Adding Web support to Metro
使用 `expo.web.bundler` 字段修改你的 [应用配置](/workflow/configuration) 以启用该功能：
¥Modify your [app config](/workflow/configuration) to enable the feature using the `expo.web.bundler` field:
```json app.json
{
  "expo": {
    "web": {
      "bundler": "metro"
    }
  }
}
```
<a id="development"></a>
#### 开发
¥Development
要启动开发服务器，请运行以下命令：
¥To start the development server run the following command:
```sh
$ npx expo start --web
```
或者，在 Expo CLI 终端 UI 中按 <kbd>W</kbd>。
¥Alternatively, press <kbd>W</kbd> in the Expo CLI terminal UI.
<a id="static-files"></a>
#### 静态文件
¥Static files
Expo 的 Metro 实现支持通过将静态文件放置在根 public/ 目录中来托管来自开发服务器的静态文件。它与许多其他 Web 框架类似。
¥Expo's Metro implementation supports hosting static files from the dev server by putting them in the root **public/** directory. It is similar to many other web frameworks.
使用 `npx expo export` 导出时，public 目录的内容被复制到 dist/目录中。这意味着你的应用可以获取相对于主机 URL 的这些资源。最常见的示例是 public/favicon.ico，网站使用它来渲染选项卡图标。
¥When exporting with `npx expo export`, the contents of the **public** directory are copied into the **dist/** directory. It means your app can expect to fetch these assets relative to the host URL. The most common example of this is the **public/favicon.ico** which is used by websites to render the tab icon.
你可以通过在项目中创建 public/index.html 文件来覆盖 Metro web 中的默认 index.html。
¥You can overwrite the default **index.html** in Metro web by creating a **public/index.html** file in your project.
将来，这将通过 EAS 更新托管在跨平台上普遍使用。目前，该功能仅限于 Web，基于用于原生应用的静态主机，例如，旧版 Expo 服务更新不支持此功能。
¥In the future, this will work universally across platforms with EAS Update hosting. Currently, the feature is web-only based on the static host used for the native app, for example, the legacy Expo service updates do not support this feature.
<a id="typescript"></a>
## TypeScript
Expo 的 Metro 配置支持项目的 tsconfig.json（或 jsconfig.json）文件中的 `compilerOptions.paths` 和 `compilerOptions.baseUrl` 字段。这可以在项目中启用绝对导入和别名。有关详细信息，请参阅 [TypeScript](/guides/typescript) 指南。
¥Expo's Metro config supports the `compilerOptions.paths` and `compilerOptions.baseUrl` fields in the project's **tsconfig.json** (or **jsconfig.json**) file. This enables absolute imports and aliases in the project. See [TypeScript](/guides/typescript) guide for more information.
此功能需要在裸项目中进行额外设置。请参阅 [Metro 设置指南](/versions/latest/config/metro#bare-workflow-setup) 了解更多信息。
¥This feature requires additional setup in bare projects. See the [Metro setup guide](/versions/latest/config/metro#bare-workflow-setup) for more information.
<a id="css"></a>
## CSS


## 分析 JavaScript 包

了解如何改进 Expo 应用和网站的生产 JavaScript 包大小。

不同平台的打包包性能有所不同。例如，Web 浏览器不支持预编译字节码，因此 JavaScript 包大小对于提高启动时间和性能非常重要。打包包越小，下载和解析的速度就越快。
¥Bundle performance varies for different platforms. For example, web browsers don't support precompiled bytecode, so the JavaScript bundle size is important for improving startup time and performance. The smaller the bundle, the faster it can be downloaded and parsed.
<a id="analyzing-bundle-size-with-atlas"></a>
## 使用 Atlas 分析包大小
¥Analyzing bundle size with Atlas
> 仅适用于 SDK 51 及以上版本。
>
> ¥Available only for **SDK 51 and above**.
项目中使用的库会影响生产 JavaScript 包的大小。从 Expo SDK 51 开始，你可以使用 [Expo Atlas](https://github.com/expo/expo-atlas#readme) 可视化生产包并确定哪些库对包大小有贡献。
¥The libraries used in a project influence the size of the production JavaScript bundle. Starting from **Expo SDK 51**, you can use [Expo Atlas](https://github.com/expo/expo-atlas#readme) to visualize the production bundle and identify which libraries contribute to the bundle size.
<a id="using-atlas-with-npx-expo-start"></a>
### 将 Atlas 与 `npx expo start` 结合使用
¥Using Atlas with `npx expo start`
你可以将 Expo Atlas 与本地开发服务器一起使用。此方法允许 Atlas 在你更改项目中的任何代码时进行更新。
¥You can use Expo Atlas with the local development server. This method allows Atlas to update whenever you change any code in your project.
在 Android、iOS 和/或 Web 上使用本地开发服务器运行你的应用后，你可以使用 <kbd>shift</kbd> + <kbd>m</kbd> 通过 [开发工具插件菜单](/debugging/devtools-plugins/#using-a-dev-tools-plugin) 打开 Atlas。
¥Once your app is running using the local development server on Android, iOS, and/or web, you can open Atlas through the [dev tools plugin menu](/debugging/devtools-plugins/#using-a-dev-tools-plugin) using <kbd>shift</kbd> + <kbd>m</kbd>.
```sh
$ EXPO_ATLAS=true npx expo start
```
<a id="changing-development-mode-to-production"></a>
#### 将开发模式更改为生产模式
¥Changing development mode to production
默认情况下，Expo 在 [开发模式](/workflow/development-mode/#development-mode) 中启动本地开发服务器。开发模式禁用了 [使用 React Native 测试库进行查询](/workflow/development-mode/#production-mode) 中启用的一些优化。你还可以在生产模式下启动本地开发服务器，以更准确地表示生产包大小：
¥By default, Expo starts the local development server in [development mode](/workflow/development-mode/#development-mode). Development mode disables some optimizations that are enabled in [production mode](/workflow/development-mode/#production-mode). You can also start the local development server in production mode to get a more accurate representation of the production bundle size:
```sh
$ EXPO_ATLAS=true npx expo start --no-dev
```
<a id="using-atlas-with-npx-expo-export"></a>
### 将 Atlas 与 `npx expo export` 结合使用
¥Using Atlas with `npx expo export`
你还可以在为你的应用或 EAS 更新生成生产包时使用 Expo Atlas。Atlas 在导出期间会生成一个 .expo/atlas.jsonl 文件，你可以在不访问项目的情况下共享和打开该文件。
¥You can also use Expo Atlas when generating a production bundle for your app or EAS Update. Atlas generates a **.expo/atlas.jsonl** file during export, which you can share and open without having access to the project.
```sh
$ EXPO_ATLAS=true npx expo export
$ npx expo-atlas .expo/atlas.jsonl
```
你还可以使用 `--platform` 选项指定要分析的平台。Atlas 将仅收集导出平台的数据。
¥You can also specify the platforms you want to analyze using the `--platform` option. Atlas will gather the data for the exported platforms only.
<a id="analyzing-transformed-modules"></a>
### 分析转换后的模块
¥Analyzing transformed modules
在 Atlas 中，你可以按住 <kbd>⌘ Cmd</kbd> 并单击图形节点以查看转换后的模块详细信息。此功能可帮助你了解 Babel 如何转换模块、它导入了哪些模块以及哪些模块导入了它。这可用于在依赖图中跟踪模块的来源。
¥Inside Atlas, you can hold <kbd>⌘ Cmd</kbd> and click on a graph node to see the transformed module details. This feature helps you understand how a module is transformed by Babel, which modules it imports, and which modules imported it. This can be used to trace the origin of a module across the dependency graph.
<a id="analyzing-bundle-size-with-source-map-explorer"></a>
## 使用 source-map-explorer 分析包大小
¥Analyzing bundle size with source-map-explorer
> 适用于 SDK 50 及以下版本的替代方法。
>
> ¥Alternative method for **SDK 50 and below**.
如果你使用的是 SDK 50 或更低版本，则可以使用 [`source-map-explorer`](https://www.npmjs.com/package/source-map-explorer) 库来可视化和分析生产 JavaScript 包。
¥If you are using SDK 50 or below, you can use the [`source-map-explorer`](https://www.npmjs.com/package/source-map-explorer) library to visualize and analyze the production JavaScript bundle.
Step 1: 
To use source map explorer, run the following command to install it:
```sh
$ npm i --save-dev source-map-explorer
```
Step 2: 
Add a script to **package.json** to run it. You might have to adjust the input path depending on the platform or SDK you are using. For brevity, the following example assumes the project is Expo SDK 50 and does not use Expo Router `server` output.
!!!IG0!!!
If you are using the SDK 50 `server` output for web, then use the following to map web bundles:
```sh
$ npx source-map-explorer 'dist/client/_expo/static/js/web/*.js' 'dist/client/_expo/static/js/web/*.js.map'
```
Web bundles are output to the **dist/client** subdirectory to prevent exposing server code to the client.
Step 3: 
Export your production JavaScript bundle and include the `--source-maps` flag so that the source map explorer can read the source maps. For native apps using Hermes, you can use the `--no-bytecode` option to disable bytecode generation.
```sh
$ npx expo export --source-maps --platform web
$ npx expo export --source-maps --platform ios --no-bytecode
```
This command shows the JavaScript bundle and source map paths in the output. In the next step, you will pass these paths to the source map explorer.
> Avoid publishing source maps to production as they can cause both security issues and performance issues (a browser will download the large maps).
Step 4: 
Run the script to analyze your bundle:
```sh
$ npm run analyze:web
```
On running this command, you might see the following error:
!!!IG1!!!
This is probably due to a [known issue](https://github.com/danvk/source-map-explorer/issues/247) in `source-map-explorer` in Node.js 18 and above. To resolve this, set the environment variable `NODE_OPTIONS=--no-experimental-fetch` before running the analyze script.
You might encounter a warning such as `Unable to map 809/13787 bytes (5.87%)`. This occurs because source maps often exclude bundler runtime definitions (for example, `__d(() => {}, [])`). This value is consistent and not a reason for concern.
## Lighthouse
Lighthouse is a great way to see how fast, accessible, and performant your website is. You can test your project with the **Audit** tab in Chrome, or with the [Lighthouse CLI](https://github.com/GoogleChrome/lighthouse#using-the-node-cli).
After creating a production build with `npx expo export -p web` and serving it (using either `npx serve dist`, or production deployment, or custom server), run Lighthouse with the URL your site is hosted at.
```sh
$ npm install -g lighthouse
$ npx lighthouse <url> --view
```


## 树摇动和代码删除

了解 Expo CLI 如何优化生产 JavaScript 包。

Tree Shaking（也称为死代码删除）是一种从生产包中删除未使用代码的技术。Expo CLI 采用不同的技术（包括 [minification](/guides/minify)），通过删除未使用的代码来缩短启动时间。
¥Tree shaking (also referred to as *dead code removal*) is a technique to remove unused code from the production bundle. Expo CLI employs different techniques, including [minification](/guides/minify), to improve startup time by removing unused code.
<a id="platform-shaking"></a>
## 平台晃动
¥Platform shaking
Expo CLI 采用称为平台抖动的过程进行应用打包，为每个平台（Android、iOS、Web）创建单独的打包包。它确保代码仅在一个平台上使用，并从其他平台上删除。
¥Expo CLI employs a process known as **platform shaking** for app bundling, where it creates separate bundles for each platform (Android, iOS, web). It ensures that the code is only used on one platform and is removed from other platforms.
任何基于 `react-native` 中的 `Platform` 模块有条件使用的代码都将从其他平台中删除。但是，此排除特别适用于每个文件中直接从 React-Native 导入 `Platform.select` 和 `Platform.OS` 的实例。如果通过不同的模块重新导出它们，则它们在不同平台的打包过程中不会被删除。
¥Any code that is used conditionally based on the `Platform` module from `react-native` is removed from the other platforms. However, this exclusion specifically applies to instances where `Platform.select` and `Platform.OS` are directly imported from react-native in each file. If these are re-exported through a different module, they will not be removed during the bundling process for different platforms.
例如，考虑以下转换输入：
¥For example, consider the following transformation input:
```js Input
import { Platform } from 'react-native';
if (Platform.OS === 'ios') {
  console.log('Hello on iOS');
}
```
生产包将根据平台删除条件：
¥The production bundle will remove the conditional based on the platform:
```js Output (Android)
```
```js Output (iOS)
console.log('Hello on iOS');
```
此优化仅适用于生产，并且在每个文件的基础上运行。如果你从不同的模块重新导出 `Platform.OS`，它不会从生产包中删除。
¥This optimization is production only and runs on a per-file basis. If you re-export `Platform.OS` from a different module, it will not be removed from the production bundle.
从 SDK 51 开始，`process.env.EXPO_OS` 可用于检测打包 JavaScript 的平台（无法在运行时更改）。由于 Metro 在依赖解析后缩小代码的方式，该值不支持平台抖动导入。
¥Starting in SDK 51, `process.env.EXPO_OS` can be used to detect the platform that the JavaScript was bundled for (cannot change at runtime). This value does not support platform shaking imports due to how Metro minifies code after dependency resolution.
<a id="remove-development-only-code"></a>
## 删除仅供开发的代码
¥Remove development-only code
在你的项目中，可能有一些旨在帮助开发过程的代码。它应该被排除在生产包之外。要处理这些场景，请使用 `process.env.NODE_ENV ` 环境变量或非标准 `__DEV__` 全局布尔值。
¥In your project, there might be code designed to help with the development process. It should be excluded from the production bundle. To handle these scenarios, use the `process.env.NODE_ENV `environment variable or the non-standard `__DEV__` global boolean.
Step 1: 
For example, the following code snippet will be removed from the production bundle:
```js Input
if (process.env.NODE_ENV === 'development') {
  console.log('Hello in development');
}
if (__DEV__) {
  console.log('Another development-only conditional...');
}
```
Step 2: 
After _constants folding_ takes place, the conditions can be evaluated statically:
```js Post constants folding
if ('production' === 'development') {
  console.log('Hello in development');
}
if (false) {
  console.log('Another development-only conditional...');
}
```
Step 3: 
The unreachable conditions are removed during [minification](/guides/minify):
```js Output (production)
```
To improve speed, Expo CLI only performs code elimination in production builds. Conditionals from the above code snippet are kept in development builds.
## Custom code removal
`EXPO_PUBLIC_` environment variables are inlined before the minification process. This means they can be used to remove code from the production bundle. For example:
Step 1: 
```js .env
EXPO_PUBLIC_DISABLE_FEATURE=true;
```
```js Input
if (!process.env.EXPO_PUBLIC_DISABLE_FEATURE) {
  console.log('Hello from the feature!');
}
```
Step 2: 
The above input code snippet is transformed to the following after `babel-preset-expo`:
```js Post babel-preset-expo
if (!'true') {
  console.log('Hello from the feature!');
}
```
Step 3: 
The above code snippet is then minified, which removes the unused conditional:
```js Post minifier
// Empty file
```
- This system does not apply to server code as environment variables are not inlined in server bundles.
- Library authors should not use `EXPO_PUBLIC_` environment variables as they only run in application code for security reasons.
## Removing server code
> SDK 51 and greater
It's common to use `typeof window === 'undefined'` to conditionally enable or disable code for server and client environments.
`babel-preset-expo` will transform `typeof window === 'undefined'` to `true` when bundling for server environments. By default, this check remains unchanged when bundling for web client environments. This transform runs in both development and production but only removes conditional requires in production.
You can configure `babel-preset-expo` to enable this transform by passing `{ minifyTypeofWindow: true }`.
By default, this transform remains disabled even for web environments since web workers won't have a `window` global.
Step 1: 
```js Input
if (typeof window === 'undefined') {
  console.log('Hello on the server!');
}
```
Step 2: 
The input code from the previous step is transformed to the following code snippet after `babel-preset-expo` when bundling for server environments (API routes, server rendering):
```js Post babel-preset-expo (bundling for server)
if (true) {
  console.log('Hello on the server!');
}
```
Bundling client code for web or native apps will not replace `typeof window` unless `minifyTypeOfWindow: true` is set:
```js Post babel-preset-expo
if (typeof window === 'undefined') {
  console.log('Hello on the server!');
}
```
Step 3: 
For server environments, the above code snippet is then minified which removes the unused conditional:
```js Post minifier (server)
console.log('Hello on the server!');
```
```js Post minifier (client)
if (typeof window === 'undefined') {
  console.log('Hello on the server!');
}
// Empty file
```
## React Native web imports
`babel-preset-expo` provides a built-in optimization for the `react-native-web` barrel file. If you import `react-native` directly using ESM, then the barrel file will be removed from the production bundle.
For ESM: 
If you import `react-native` using the static `import` syntax, the barrel file will be removed.
```js Input
import { View, Image } from 'react-native';
```
```js Output (web)
import View from 'react-native-web/dist/exports/View';
import Image from 'react-native-web/dist/exports/Image';
```
For CJS: 
If you import `react-native` using `require()`, the barrel file will be left as-is in the production bundle.
```js Input
const { View, Image } = require('react-native');
```
```js Output (web)
const { View, Image } = require('react-native-web');
```
## Remove unused imports and exports
> Experimentally available in SDK 52 and above.
You can experimentally enable support for automatically removing unused imports and exports across modules. This is useful for speeding up native OTA downloads and optimizing web performance where JavaScript must be parsed and executed using a standard JavaScript engine.
Consider the following example code:
```js index.js
import { ArrowUp } from './icons';
export default function Home() {
  return <ArrowUp />;
}
```
```js icons.js
export function ArrowUp() {
  /* ... */
}
export function ArrowDown() {
  /* ... */
}
export function ArrowRight() {
  /* ... */
}
export function ArrowLeft() {
  /* ... */
}
```
Since only `ArrowUp` is used in `index.js`, the production bundle will remove all other components from `icons.js`.
```js icons.js (Output)
export function ArrowUp() {
  /* ... */
}
```
This system scales up to automatically optimize all `import` and `export` syntax in your app, across all platforms. While this results in smaller bundles, processing JS still requires time and computer memory so avoid importing millions of modules.
- Tree-shaking only runs in production bundles and can only run on modules that use `import` and `export` syntax. Files that use `module.exports` and `require` will not be tree-shaken.
- Avoid adding Babel plugins such as `@babel/plugin-transform-modules-commonjs` which convert `import`/`export` syntax to CJS. This will break tree-shaking across your project.
- Modules that are marked as side-effects will not be removed from the graph.
- `export * from "..."` will be expanded and optimized unless the export uses `module.exports` or `exports`.
- All modules in the Expo SDK are shipped as ESM and can be exhaustively tree-shaken.
## Enabling tree shaking
> Experimentally available in SDK 52 and above.
Step 1: 
Ensure `experimentalImportSupport` and ensure your app builds and runs as expected.
> **info** **Note**: Enabled by default in SDK 54 and above.
Note: How to enable import support in older SDK versions?
---
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.getTransformOptions = async () => ({
  transform: {
    experimentalImportSupport: true,
  },
});
module.exports = config;
```
Experimental import support uses a custom version of the `@babel/plugin-transform-modules-commonjs` plugin. This drastically reduces the number of resolutions and simplifies your output bundle. This feature can be used with `inlineRequires` to further optimize your bundle experimentally.
---
Step 2: 
Toggle on the environment variable `EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1` to keep modules around until the entire graph is created. Ensure your app builds and runs as expected in production with this feature enabled before continuing.
```sh .env
EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1
```
This will only be used in production mode.
Step 3: 
Toggle on the environment variable `EXPO_UNSTABLE_TREE_SHAKING=1` to enable the feature.
```sh .env
EXPO_UNSTABLE_TREE_SHAKING=1
```
This will only be used in production mode.
Step 4: 
Bundle your app in production mode to see the effects of tree shaking.
```sh
$ npx expo export
```
This feature is very experimental because it changes the fundamental structure of how Metro bundles code. By default, Metro bundles everything on-demand and lazily to ensure the fastest possible development times. In contrast, tree shaking requires some transformation to be delayed until after the entire bundle has been created. This means less code can be cached, which is generally fine because tree shaking is a production-only feature and production bundles often don't use transform caches.
## Barrel files
> Experimentally available in SDK 52 and above.
With Expo tree shaking, star exports will automatically be expanded and shaken based on usage. For example, consider the following code snippet:
```js Input
export * from './icons';
```
The optimization pass will crawl `./icons` and add the exports to the current module. If the exports are unused, they will be removed from the production bundle.
```js Expanded
export { ArrowRight, ArrowLeft } from './icons';
```
This will be shaken according to standard tree shaking rules. If you only import `ArrowRight`, then `ArrowLeft` will be removed from the production bundle.
If the star export pulls in ambiguous exports such as `module.exports.ArrowUp` or `exports.ArrowDown`, then the optimization pass will not expand the star export and no exports will be removed from the barrel file. You can use [Expo Atlas](/guides/analyzing-bundles/#analyzing-bundle-size-with-atlas) to inspect the expanded exports.
You can use this strategy with libraries like `lucide-react` to remove all icons that are not used in your app.
## Recursive optimizations
>
实验性地在 SDK 52 及以上版本中可用。
¥Experimentally available in SDK 52 and above.
Expo 通过详尽地递归图表来查找未使用的导入，从而优化模块。考虑以下代码片段：
¥Expo optimizes a module by recursing through the graph exhaustively to find unused imports. Consider the following code snippet:
```js Input
export function foo() {
  // Because bar is used here, it cannot be removed.
  bar();
}
export function bar() {}
```
在这种情况下，`bar` 用于 `foo`，因此无法删除。但是，如果应用中的任何地方都没有使用 `foo`，那么 `foo` 将被删除，并且将再次扫描模块以查看是否可以删除 `bar`。由于性能原因，此过程在退出之前针对给定模块递归 5 次。
¥In this case, `bar` is used in `foo`, so it cannot be removed. However, if `foo` is not used anywhere in the app, then `foo` will be removed and the module will be scanned again to see if `bar` can be removed. This process recurses 5 times for a given module before bailing out due to performance reasons.
<a id="side-effects"></a>
## 副作用
¥Side-effects
Expo CLI 根据 [Webpack 系统](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free) 尊重模块副作用。副作用通常用于定义全局变量（`console.log`）或修改原型（避免这样做）。
¥Expo CLI respects module side-effects according to the [Webpack system](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free). Side-effects are generally used for defining global variables (`console.log`) or modifying prototypes (avoid doing this).
你可以在 package.json 中标记你的模块是否有副作用：
¥You can mark if your module has side-effects in the **package.json**:
```json package.json
{
  "name": "library",
  "sideEffects": ["./src/*.js"]
}
```
副作用将阻止删除未使用的模块并禁用模块内联以确保 JS 代码按预期顺序运行。如果副作用为空或仅包含注释和指令（`"use strict"`、`"use client"` 等），则会被删除。
¥Side-effects will prevent the removal of unused modules and disable module inlining to ensure JS code runs in the expected order. Side-effects will be removed if they're empty or contain only comments and directives (`"use strict"`, `"use client"`, and so on).
启用 Expo 树摇动后，你可以安全地在 metro.config.js 中为生产包启用 `inlineRequires`。这将在评估模块时延迟加载模块，从而缩短启动时间。避免在没有 Expo tree shake 的情况下使用此功能，因为它会以可能改变副作用执行顺序的方式移动模块。
¥When Expo tree shaking is enabled, you can safely enable `inlineRequires` in your **metro.config.js** for production bundles. This will lazily load modules when they're evaluated, leading to faster startup time. Avoid using this feature without Expo tree shaking as it will move modules around in ways that can change the execution order of side-effects.
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.getTransformOptions = async () => ({
  transform: {
    experimentalImportSupport: true,
    inlineRequires: true,
  },
});
module.exports = config;
```
<a id="optimizing-for-tree-shaking"></a>
## 针对摇树进行优化
¥Optimizing for tree shaking
在 Expo tree shake 之前，React Native 库会通过将导入封装在条件块中来删除导入，例如：
¥Before Expo tree shaking, React Native libraries would remove imports by wrapping them in conditional blocks such as:
```js
if (process.env.NODE_ENV === 'development') {
  require('./dev-only').doSomething();
}
```
这是有问题的，因为你没有准确的 TypeScript 支持，并且由于你无法静态分析代码，因此会使图表变得模糊。启用 Expo tree shake 后，你可以重构此代码以使用 ESM 导入：
¥This is problematic because you don't have accurate TypeScript support and it makes the graph ambiguous since you cannot statically analyze the code. With Expo tree shaking enabled, you can restructure this code to use ESM imports:
```js Input
import { doSomething } from './dev-only';
if (process.env.NODE_ENV === 'development') {
  doSomething();
}
```
在这两种情况下，整个模块在生产打包包中都是空的。
¥In both cases, the entire module will be empty in production bundles.


## 缩小 JavaScript

了解如何使用 Metro 打包程序在 Expo CLI 中自定义 JavaScript 缩小流程。

缩小是优化构建步骤。它从源代码中删除不必要的字符，例如折叠空格、删除注释并缩短静态操作。此过程减少了最终大小并缩短了加载时间。
¥Minification is an optimization build step. It removes unnecessary characters such as collapses whitespace, removes comments, and shortens static operations, from the source code. This process reduces the final size and improves load times.
<a id="minification-in-expo-cli"></a>
## Expo CLI 中的缩小
¥Minification in Expo CLI
在 Expo CLI 中，在生产导出期间（当运行 `npx expo export`、`npx expo export:embed`、`eas build` 等命令时）对 JavaScript 文件执行缩小。
¥In Expo CLI, minification is performed on JavaScript files during the production export (when `npx expo export`, `npx expo export:embed`, `eas build`, and so on, commands run).
例如，考虑项目中的以下代码片段：
¥For example, consider following code snippet in a project:
```js Input
// This comment will be stripped
console.log('a' + ' ' + 'long' + ' string' + ' to ' + 'collapse');
```
这将被 Expo CLI 缩小：
¥This will be minified by the Expo CLI:
```js Output
console.log('a long string to collapse');
```
> 提示：可以使用 `/** @preserve */` 指令保留注释。
>
> ¥**Tip**: Comments can be preserved by using the `/** @preserve */` directive.
Expo CLI 的默认缩小对于大多数项目来说已经足够了。但是，你可以自定义缩小器以优化速度或删除日志等附加功能。
¥The default minification of Expo CLI is sufficient for most projects. However, you can customize the minifier to optimize for speed or remove additional features like logs.
<a id="remove-console-logs"></a>
## 删除控制台日志
¥Remove console logs
你可以从生产版本中删除控制台日志。在 Terser minifier 配置中使用 `drop_console` 选项。
¥You can remove console logs from your production build. Use the `drop_console` option in the Terser minifier config.
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.minifierConfig = {
  compress: {
    // The option below removes all console logs statements in production.
    drop_console: true,
  },
};
module.exports = config;
```
如果你想保留某些日志，你还可以传递要删除的控制台类型数组。例如：`drop_console: ['log', 'info']` 将删除 `console.log` 和 `console.info`，但保留 `console.warn` 和 `console.error`。
¥You can also pass an array of console types to drop if you want to preserve certain logs. For example: `drop_console: ['log', 'info']` will remove `console.log` and `console.info` but preserve `console.warn` and `console.error`.
<a id="customizing-the-minifier"></a>
## 自定义缩小器
¥Customizing the minifier
不同的压缩器在速度和压缩之间进行权衡。你可以通过修改项目中的 metro.config.js 文件来自定义 Expo CLI 使用的压缩器。
¥Different minifiers have tradeoffs between speed and compression. You can customize the minifier used by Expo CLI by modifying the **metro.config.js** file in your project.
<a id="terser"></a>
### Terser
> [`terser`](https://github.com/terser/terser) 是默认的压缩器（[Metro@0.73.0 变更日志](https://github.com/facebook/metro/releases/tag/v0.73.0)）。
>
> ¥[`terser`](https://github.com/terser/terser) is the default minifier ([Metro@0.73.0 changelog](https://github.com/facebook/metro/releases/tag/v0.73.0)).
Step 1: 
To install Terser in a project, run the command:
```sh
$ yarn add --dev metro-minify-terser
```
Step 2: 
Set Terser as a minifier with `transformer.minifierPath`, and pass in [`terser` options](https://github.com/terser/terser#compress-options) to `transformer.minifierConfig`.
!!!IG3!!!
### Unsafe Terser options
For additional compression that may not work in all JavaScript engines, enable the [`unsafe` `compress` options](https://terser.nodejs.cn/docs/miscellaneous/#the-unsafe-compress-option):
!!!IG4!!!
### esbuild
[`esbuild`](https://esbuild.github.io/) is used to minify exponentially faster than `uglify-es` and `terser`. For more information, see [`metro-minify-esbuild`](https://github.com/EvanBacon/metro-minify-esbuild#usage) usage.
### Uglify
For projects SDK 48 and above, you can use [`uglify-es`](https://github.com/mishoo/UglifyJS) by following the steps below:
Step 1: 
To install Uglify in a project, run the command:
```sh
$ yarn add --dev metro-minify-uglify
```
> Make sure the version of `metro-minify-uglify` matches the version of `metro` in your project.
Step 2: 
Set Uglify as a minifier with `transformer.minifierPath`, and pass in [options](https://github.com/mishoo/UglifyJS#compress-options) to `transformer.minifierConfig`.
!!!IG5!!!


## 为什么是 Metro？

了解为什么 Metro 是 React Native 中通用打包的未来以及它如何使开发者受益。

[Metro](https://metrobundler.dev/) 是 Expo 和 React Native 的官方打包器。它是 Expo 框架中的核心构建工具。打包器包含数千种意见和权衡。本文档概述了围绕 Metro 开发 Expo 的主要原因以及它如何使开发者受益。
¥[Metro](https://metrobundler.dev/) is the official bundler for Expo and React Native. It's a central build tool in the Expo framework. Bundlers comprise thousands of opinions and trade-offs. This document outlines the key reasons why Expo is developed around Metro and how it benefits developers.
<a id="official-meta-bundler"></a>
## 官方 Meta 打包器
¥Official Meta bundler
Metro 由 Meta 维护，Meta 是 React、React Native、Yoga 和 Hermes 的维护者。它用于开发一些世界上最大的应用，涵盖应用商店中的所有类别。
¥Metro is maintained by Meta, the maintainers of React, React Native, Yoga, and Hermes. It's used for developing some of the world's largest apps, ranging across all categories in the app stores.
Meta 工程师积极开发 Metro，明确要求将所有应用（超过 40 万个源文件）打包在一起，同时保持快速可靠。
¥Meta engineers actively develop Metro with the express requirement of bundling all their apps, across 400k+ source files, while remaining fast and reliable.
通过一流的 Metro 支持，我们确保 Expo 开发者在 Meta 的工具中具有连续性并可以即时访问新兴功能。这包括：
¥By having first-class Metro support, we ensure Expo developers have continuity across Meta's tools and get instant access to emerging features. This includes:
* React Fast Refresh 是 2019 年作为 Metro 功能推出的 [首次引入](https://rn.nodejs.cn/blog/2019/09/18/version-0.61)。React Web 社区于次年通过 Webpack 采用了它。
  ¥React Fast Refresh was [first introduced](https://rn.nodejs.cn/blog/2019/09/18/version-0.61) as a Metro feature in 2019. The React web community adopted it the following year via Webpack.
* 将 JavaScript 转换为 Hermes 字节码以实现即时原生启动。
  ¥Transforming JavaScript to Hermes bytecode for instant native startup.
* React Native DevTools（包括对 [网络和 JS 调试](/debugging/tools/#debugging-with-react-native-devtools) 的一流支持）仅与 Metro 和 Hermes 一起使用。
  ¥React Native DevTools, including first-class support for [network and JS debugging](/debugging/tools/#debugging-with-react-native-devtools), is exclusively available with Metro and Hermes.
* React Compiler 最初是作为 Metro 兼容的 Babel 插件推出的。
  ¥React Compiler was initially rolled out as a Metro-compatible Babel plugin.
计划加入 Metro 的新功能和即将推出的功能包括：
¥New and upcoming features that are planned to come to Metro include:
* 使用 Static Hermes 将 Flow 代码编译为原生机器代码。在 Tzvetan Mikov 的 [Static Hermes](https://www.youtube.com/watch?v=GUM64b-gAGg) 演讲中了解更多信息。
  ¥Compiling Flow code to native machine code with Static Hermes. Learn more in the [Static Hermes](https://www.youtube.com/watch?v=GUM64b-gAGg) talk by Tzvetan Mikov.
* 使用适用于所有平台的通用 React Server Components 进行数据提取、流式传输、React Suspense、服务器渲染和构建时静态渲染。在 React Conf 2024 的 [通用 React 服务器组件](https://www.youtube.com/watch?v=djhEgxQf3Kw) 演讲中了解更多信息。
  ¥Data fetching, streaming, React Suspense, server rendering, and build-time static rendering with universal React Server Components for all platforms. Learn more in the [Universal React Server Components](https://www.youtube.com/watch?v=djhEgxQf3Kw) talk at React Conf 2024.
Expo 团队与 Meta 合作开发 Metro for Expo Router，添加了 [基于文件的路由](/develop/file-based-routing/)、[网络支持](/guides/customizing-metro/#web-support)、[打包包拆分](/guides/customizing-metro/#bundle-splitting)、[使用部分](/guides/tree-shaking/)、[CSS](/versions/latest/config/metro/#css)、[DOM 组件](/guides/dom-components/)、服务器组件和 [API 路由](/router/reference/api-routes/) 等功能。
¥The Expo team collaborates with Meta to develop Metro for Expo Router, adding features like [file-based routing](/develop/file-based-routing/), [web support](/guides/customizing-metro/#web-support), [bundle splitting](/guides/customizing-metro/#bundle-splitting), [tree shaking](/guides/tree-shaking/), [CSS](/versions/latest/config/metro/#css), [DOM components](/guides/dom-components/), server components, and [API routes](/router/reference/api-routes/).
<a id="battle-tested-at-scale"></a>
## 大规模实战测试
¥Battle-tested at scale
世界上几乎每个 React Native 应用都使用 Metro，使其成为针对大型项目优化的久经考验的解决方案。这使其适合各种规模的开发者，从业余爱好者到大型公司。Metro 专为处理大型 Meta 应用而设计，这就是它具有使用 Watchman 和 [共享远程缓存](https://metrobundler.dev/docs/caching) 进行原生文件监视等功能的原因。
¥Nearly every React Native app in the world uses Metro, making it a battle-tested solution optimized for large-scale projects. This makes it suitable for developers of all sizes, from hobbyists to large companies. Metro is designed specifically to handle large-scale Meta apps, which is why it has features such as native file watching with Watchman and [shared remote caches](https://metrobundler.dev/docs/caching).
<a id="on-demand-processing"></a>
## 按需处理
¥On-demand processing
在开发过程中，Metro 不会执行任何特定于平台的工作，直到收到请求。这允许开发者在大型项目上工作，而无需为他们支持的平台数量支付性能成本。结合积极缓存和 [异步路由](/router/reference/async-routes/)，开发者可以逐步打包他们正在积极开发的应用部分。
¥In development, Metro doesn't perform any platform-specific work until requested. This allows developers to work on large projects without paying a performance cost for the number of platforms they support. In conjunction with aggressive caching and [async routes](/router/reference/async-routes/), developers can incrementally bundle only the parts of the app that they're actively working on.
<a id="multi-dimensional"></a>
## 多维
¥Multi-dimensional
与创建多个实例来打包服务器和客户端代码的传统打包器不同，Metro 可最大限度地跨平台和环境（服务器、客户端、DOM 组件）重用资源。这种架构非常适合多平台和服务器开发。
¥Unlike traditional bundlers, which create multiple instances to bundle server and client code, Metro maximizes resource reuse across platforms and environments (server, client, DOM components). This architecture is ideal for multiplatform and server development.
<a id="reusable-transform-memoization"></a>
## 回滚到上一个更新版本
¥Reusable transform memoization
Metro 是增量式的，可以创建可跨机器使用的缓存转换工件。这使大型团队能够重用远程构建器的工作，这是 Meta 用于所有大型项目的一种技术。
¥Metro is incremental and can create cached transform artifacts that can be used across machines. This enables large teams to reuse work from remote builders, a technique used at Meta for all large projects.
<a id="optimized-for-custom-runtimes"></a>
## 针对自定义运行时进行了优化
¥Optimized for custom runtimes
虽然其他打包器是围绕 Web 浏览器的静态规范设计的，但 Metro 针对 React Native 的灵活性进行了优化。这将启用诸如生成 Hermes 字节码编译所需的特定受支持语言功能集等功能，从而加快生产中的应用启动速度。这还将扩展到 Static Hermes，它将静态类型信息编译为原生应用的机器代码。
¥While other bundlers are designed around the static specification of web browsers, Metro is optimized for the flexibility of React Native. This enables features like generating the specific set of supported language features required for Hermes bytecode compilation which enables faster app startup in production. This will also extend to Static Hermes, which will compile static type information into machine code for native apps.
<a id="cross-technology-support"></a>
## 跨技术支持
¥Cross-technology support
Expo 利用 Metro 的技术创建了像 [DOM 组件](/guides/dom-components/) 这样的新功能。这允许原生应用中的 React 组件根据需要动态打包为整个网站，所有默认值与父应用相同。
¥Expo leverages Metro's technology to create novel functionality like [DOM components](/guides/dom-components/). This allows a React component in a native app to be dynamically bundled as an entire website with all the same defaults as the parent app, on-demand.
<a id="native-asset-exports"></a>
## 原生资源导出
¥Native asset exports
与最终结果是完全托管的应用的传统打包器不同，Metro 的配置选项支持导出打包包以作为独立应用二进制文件中的原生工件嵌入。这利用了特定于操作系统的优化，例如 Apple 平台上的 `xcassets`。
¥Unlike traditional bundlers, where the end result is a fully hosted app, Metro's configuration options support exporting bundles to embed as native artifacts in standalone app binaries. This leverages OS-specific optimizations such as `xcassets` on Apple platforms.
<a id="concurrent-processing"></a>
## 并发处理
¥Concurrent processing
Metro 中的所有 AST 转换都是在所有可用线程上同时执行的，从而最大限度地利用硬件。
¥All AST transformation in Metro is performed concurrently across all available threads, maximizing the use of hardware.
<a id="comparison-with-other-approaches"></a>
## 与其他方法的比较
¥Comparison with other approaches
虽然 Metro 是为通用应用开发而设计的，但它经常与其他仅限网络的打包器进行比较。以下是一些主要区别：
¥While Metro is designed for universal app development, it's often compared to other web-only bundlers. Here are some key differences:
<a id="browser-esm-versus-bundling"></a>
### 浏览器 ESM 与打包
¥Browser ESM versus bundling
虽然像 Vite 这样的打包器利用了浏览器中内置的 ESM 支持，但由于数千个级联网络请求，这种方法可能会导致中型到大型规模的实际开发时间变慢。Metro 在本地开发中执行打包，使开发结果更接近生产结果，更适合 React Native 更大的模块数量。
¥While bundlers like Vite leverage built-in ESM support in the browser, this approach can lead to slower practical development times at medium to large scales due to thousands of cascading network requests. Metro performs bundling in local development, which aligns the development results much closer to the production results and is better suited for React Native's larger module count.
<a id="javascript-versus-native-languages"></a>
### JavaScript 与原生语言
¥JavaScript versus native languages
出于性能原因，一些打包器选择用 Rust 编写其核心，但这也带来了一些权衡，例如更具挑战性的贡献、补丁和开发。Metro 根据操作使用多种技术：
¥Several bundlers are opting to write their core in Rust for performance reasons, but this comes with some trade-offs, such as more challenging contributions, patches, and development. Metro uses a mix of technologies based on the operation:
* 核心打包器和实用程序是用 JS/Flow 编写的。
  ¥The core bundler and utilities are written in JS/Flow.
* 文件监视通过 Watchman 用 C++ 编写，并带有 JS 回退。然后，Watchman 可用于你计算机上的项目。
  ¥File watching is written in C++ via Watchman, with a JS fallback. Watchman is then used across projects on your computer.
* AST 使用 Hermes 解析器 (WebAssembly) 解析为 Babel 兼容格式。
  ¥AST is parsed with Hermes parser (WebAssembly) to a Babel-compatible format.
* AST 转换由 Babel 完成。这最大限度地提高了开发者的自定义能力。
  ¥AST transformation is done with Babel. This maximizes developer customization.
* Minification 在原生平台上使用 Hermes，在 Web 上使用 Terser（带有可选的 ESBuild 支持）。
  ¥Minification uses Hermes on native platforms and Terser (with optional ESBuild support) for web.
* CSS 解析和压缩由 [LightningCSS](https://lightningcss.dev/)（Rust）执行。
  ¥CSS parsing and minification is performed with [LightningCSS](https://lightningcss.dev/) (Rust).
这种方法与 Meta 和社区工具保持一致，同时允许开发者更轻松地进行调试、分析和修补。
¥This approach aligns with Meta and community tools while allowing easier debugging, profiling, and patching for developers.


# 参考

## 使用大仓

了解如何使用 Yarn v1 工作区在 monorepo 中设置 Expo 项目。

Monorepos（或 "整体存储库"）是包含多个应用或包的单个存储库。它可以帮助加快大型项目的开发速度，使代码共享变得更容易，并充当单一事实来源。本指南将使用 Expo 项目设置一个简单的 monorepo。目前，我们为 [Yarn 1（经典）](https://yarn.nodejs.cn/lang/en/) 工作区提供一流的支持。如果你想使用其他工具，请确保你知道如何配置它。
¥Monorepos, or *"monolithic repositories"*, are single repositories containing multiple apps or packages. It can help speed up development for larger projects, make it easier to share code, and act as a single source of truth. This guide will set up a simple monorepo with an Expo project. We currently have first-class support for [Yarn 1 (Classic)](https://yarn.nodejs.cn/lang/en/) workspaces. If you want to use another tool, make sure you know how to configure it.
>  **warning** Monorepos 并不适合所有人。它需要对所使用的工具有深入的了解，增加了更多的复杂性，并且通常需要特定的工具配置。只需一个存储库就可以走得很远。
>
> ¥Monorepos are not for everyone. It requires in-depth knowledge of the used tooling, adds more complexity, and often requires specific tooling configuration. You can get far with just a single repository.
<a id="automatic-configuration"></a>
## 自动配置
¥Automatic configuration
从 SDK 48 开始，Expo 会自动检测 monorepos 并在使用 [bun](https://bun.sh/docs/install/workspaces)、[npm](https://npm.nodejs.cn/cli/using-npm/workspaces) 或 [yarn](https://yarn.nodejs.cn/features/workspaces) 时配置添加到 monorepo 的新应用项目。从 SDK 52 开始，Expo 在使用 [pnpm](https://pnpm.nodejs.cn/workspaces) 时也会执行此自动配置。检测基于项目中的工作区配置。
¥Starting from **SDK 48**, Expo automatically detects monorepos and configures new app projects added to a monorepo when using [bun](https://bun.sh/docs/install/workspaces), [npm](https://npm.nodejs.cn/cli/using-npm/workspaces), or [yarn](https://yarn.nodejs.cn/features/workspaces). From **SDK 52**, Expo also performs this automatic configuration when using [pnpm](https://pnpm.nodejs.cn/workspaces). The detection is based on the workspaces configuration in your project.
>  **info** Expo 的自动 monorepo 设置将 monorepo 中的所有工作区作为 `watchFolders` 添加到 Metro。这可能会减慢 Metro 较大的 monorepos 的速度。你还可以通过更改 metro.config.js 中的 `watchFolders` 来手动配置 Metro 应监视的目录，请参阅 [修改 Metro 配置](#modify-the-metro-config)。
>
> ¥Expo's automatic monorepo setup adds all workspaces in your monorepo as `watchFolders` to Metro. This might slow Metro down for larger monorepos. You can also manually configure which directories Metro should watch by changing the `watchFolders` in your **metro.config.js**, see [Modify the Metro config](#modify-the-metro-config).
<a id="manual-configuration"></a>
## 手动配置
¥Manual configuration
在此示例中，我们将使用 Yarn 工作区（不带 [nohoist](https://yarn.nodejs.cn/blog/2018/02/15/nohoist/) 选项）设置 monorepo。我们将采用一些熟悉的名称，但你可以完全自定义它们。完成本指南后，我们的基本结构应如下所示：
¥In this example, we will set up a monorepo using Yarn workspaces without the [nohoist](https://yarn.nodejs.cn/blog/2018/02/15/nohoist/) option. We will assume some familiar names, but you can fully customize them. After this guide, our basic structure should look like this:
* apps - 包含多个项目，包括 React Native 应用。
  ¥**apps** - Contains multiple projects, including React Native apps.
* packages - 包含我们的应用使用的不同包。
  ¥**packages** - Contains different packages used by our apps.
* package.json - 根包文件，包含 Yarn 工作区配置。
  ¥**package.json** - Root package file, containing Yarn workspaces config.
<a id="root-package-file"></a>
### 根包文件
¥Root package file
所有 Yarn monorepos 都应该有一个 "root" package.json 文件。它是我们 monorepo 的主要配置，可能包含为存储库中的所有项目安装的包。你可以运行 `yarn init`，或手动创建 package.json。它应该看起来像这样：
¥All Yarn monorepos should have a "root" **package.json** file. It is the main configuration for our monorepo and may contain packages installed for all projects in the repository. You can run `yarn init`, or create the **package.json** manually. It should look something like this:
```json package.json
{
  "name": "monorepo",
  "version": "1.0.0"
}
```
<a id="set-up-yarn-workspaces"></a>
### 设置 Yarn 工作区
¥Set up yarn workspaces
Yarn 和其他工具有一个称为 "workspaces" 的概念。我们存储库中的每个包和应用都有自己的工作区。在使用它们之前，我们必须指示 Yarn 在哪里找到这些工作区。我们可以通过在 package.json 中使用 [通配符模式](https://yarn.nodejs.cn/lang/en/docs/workspaces/#toc-tips-tricks) 设置 `workspaces` 属性来做到这一点：
¥Yarn and other tooling have a concept called *"workspaces"*. Every package and app in our repository has its own workspace. Before we can use them, we have to instruct Yarn where to find these workspaces. We can do that by setting the `workspaces` property using [glob patterns](https://yarn.nodejs.cn/lang/en/docs/workspaces/#toc-tips-tricks), in the **package.json**:
```json package.json
{
  "private": true,
  "name": "monorepo",
  "version": "1.0.0",
  "workspaces": ["apps/*", "packages/*"]
}
```
>  **warning** Yarn 工作区要求根 package.json 是私有的。如果你不设置此项，`yarn install` 将出错并显示一条提及此信息的消息。
>
> ¥Yarn workspaces require the root **package.json** to be private. If you don't set this, `yarn install` will error with a message mentioning this.
<a id="create-our-first-app"></a>
### 创建我们的第一个应用
¥Create our first app
现在我们已经设置了基本的 monorepo 结构，让我们添加我们的第一个应用。
¥Now that we have the basic monorepo structure set up, let's add our first app.
在创建应用之前，我们必须创建应用目录。此目录包含属于此 monorepo 的所有单独的应用或网站。在这个 apps 目录中，我们可以创建一个包含 React Native 应用的子目录。
¥Before we create our app, we have to create the **apps** directory. This directory contains all separate apps or websites that belong to this monorepo. Inside this **apps** directory, we can create a sub-directory that contains the React Native app.
```sh
$ yarn create expo apps/cool-app
```
> 如果你有现有应用，你可以将所有这些文件复制到应用内的目录中。
>
> ¥If you have an existing app, you can copy all those files into a directory inside **apps**.
复制或创建第一个应用后，运行 `yarn` 以检查常见警告。
¥After copying or creating the first app, run `yarn` to check for common warnings.
<a id="modify-the-metro-config"></a>
#### 修改 Metro 配置
¥Modify the Metro config
Expo 的 Metro 配置为 Bun、npm、pnpm 和 Yarn 提供 monorepo 支持。如果你使用 [`expo/metro-config`](/guides/customizing-metro/) 中的配置，则在使用 monorepos 时无需手动配置 Metro。如果是这种情况，你可以跳过此步骤。
¥Expo's Metro config has monorepo support for Bun, npm, pnpm and Yarn. You don't have to manually configure Metro when using monorepos if you use the config from [`expo/metro-config`](/guides/customizing-metro/). If that's the case, you can skip this step.
要手动使用 Metro 配置 monorepo，有两个主要更改：
¥To configure a monorepo with Metro manually, there are two main changes:
1. 确保 Metro 正在监视 monorepo 中的所有相关代码，而不仅仅是 apps/cool-app。
   ¥Make sure Metro is watching all relevant code within the monorepo, not just **apps/cool-app**.
2. 告诉 Metro 在哪里可以解析包。它们可能安装在 apps/cool-app/node_modules 或 node_modules 中。
   ¥Tell Metro where it can resolve packages. They might be installed in **apps/cool-app/node_modules** or **node_modules**.
我们可以通过 [创建 Metro.config.js](/guides/customizing-metro/#customizing) 来配置它，内容如下：
¥We can configure this by [creating a **metro.config.js**](/guides/customizing-metro/#customizing) with the following content:
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const path = require('path');
// Find the project and workspace directories
const projectRoot = __dirname;
// This can be replaced with `find-yarn-workspace-root`
const monorepoRoot = path.resolve(projectRoot, '../..');
const config = getDefaultConfig(projectRoot);
// 1. Watch all files within the monorepo
config.watchFolders = [monorepoRoot];
// 2. Let Metro know where to resolve packages and in what order
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(monorepoRoot, 'node_modules'),
];
module.exports = config;
```
> 了解有关 [定制 Metro](/guides/customizing-metro) 的更多信息。
>
> ¥Learn more about [customizing Metro](/guides/customizing-metro).
Note: 1. Why do we need to watch all files with the monorepo?
---
Metro has three separate stages in its bundling process, [documented here](https://metrobundler.dev/docs/concepts). During the first phase, **Resolution**, Metro resolves your app's required files and dependencies. Metro does that with the `watchFolders` option, which is set to the project directory by default. This default setting works great for apps that don't use a monorepo structure.
When using monorepos, your app dependencies splits up into different directories. Each of these directories must be within the scope of the [`watchFolders`](https://metrobundler.dev/docs/configuration/#watchfolders). If a changed file is outside of that scope, Metro won't be able to find it. Setting this path to the root of your monorepo will force Metro to watch all files within the repository and possibly cause a slow initial startup time.
As your monorepo increases in size, watching all files within the monorepo becomes slower. You can speed things up by only watching the packages your app uses. Typically, these are the ones that are installed with an asterisk (\*) in your **package.json**. For example:
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const path = require('path');
const projectRoot = __dirname;
const monorepoRoot = path.resolve(projectRoot, '../..');
const config = getDefaultConfig(projectRoot);
// Only list the packages within your monorepo that your app uses. No need to add anything else.
// If your monorepo tooling can give you the list of monorepo workspaces linked
// in your app workspace, you can automate this list instead of hardcoding them.
const monorepoPackages = {
  '@acme/api': path.resolve(monorepoRoot, 'packages/api'),
  '@acme/components': path.resolve(monorepoRoot, 'packages/components'),
};
// 1. Watch the local app directory, and only the shared packages (limiting the scope and speeding it up)
// Note how we change this from `monorepoRoot` to `projectRoot`. This is part of the optimization!
config.watchFolders = [projectRoot, ...Object.values(monorepoPackages)];
// Add the monorepo workspaces as `extraNodeModules` to Metro.
// If your monorepo tooling creates workspace symlinks in the `node_modules` directory,
// you can either add symlink support to Metro or set the `extraNodeModules` to avoid the symlinks.
// See: https://metrobundler.dev/docs/configuration/#extranodemodules
config.resolver.extraNodeModules = monorepoPackages;
// 2. Let Metro know where to resolve packages and in what order
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(monorepoRoot, 'node_modules'),
];
module.exports = config;
```
---
Note: 2. Why do we need to tell Metro how to resolve packages?
---
This option is important to resolve libraries in the correct **node_modules** directories. Monorepo tooling, like Yarn, usually creates two different **node_modules** directories which are used for a single workspace.
1. **apps/mobile/node_modules** - The "project" directory
2. **node_modules** - The "root" directory
Yarn uses the root directory to install packages used in multiple workspaces. If a workspace uses a different package version, it installs that different version in the project directory.
We have to tell Metro to look in these two directories. The order is important here because the project directory **node_modules** can contain specific versions we use for our app. When the package does not exist in the project directory, it should try the shared root directory.
---
#### Change default entrypoint
In monorepos, we can't hardcode paths to packages anymore since we can't be sure if they are installed in the root **node_modules** or the workspace **node_modules** directory. If you are using a managed project, we have to change our default entry point that looks like `node_modules/expo/AppEntry.js`.
> This new entry point already exists for existing React Native (bare) projects. You only need to add this if you have a project generated with `npx create-expo-app`.
If you are using [Expo Router](/router/introduction/), do not change the entrypoint. By default [`EXPO_USE_METRO_WORKSPACE_ROOT`](/more/expo-cli/#environment-variables) is activated, which enables the auto server root detection for Metro. You can skip this step.
Otherwise, open your app's **package.json**, change the `main` property to `index.js`, and create this new **index.js** file in the app directory with the content below.
```js index.js
import { registerRootComponent } from 'expo';
import App from './App';
// registerRootComponent calls AppRegistry.registerComponent('main', () => App);
// It also ensures that whether you load the app in Expo Go or in a native build,
// the environment is set up appropriately
registerRootComponent(App);
```
### Create a package
Monorepos can help us group code in a single repository. That includes apps but also separate packages. They also don't need to be published. The [Expo repository](https://github.com/expo/expo) uses this as well. All the Expo SDK packages live inside the [**packages**](https://github.com/expo/expo/tree/main/packages) directory in our repo. It helps us test the code inside one of our [**apps**](https://github.com/expo/expo/tree/main/apps/native-component-list) directory before we publish them.
Let's go back to the root and create the **packages** directory. This directory can contain all the separate packages that you want to make. Once you are inside this directory, we need to add a new sub-directory. The sub-directory is a separate package that we can use inside our app. In the example below, we named it **cool-package**.
```sh
$ mkdir -p packages/cool-package
$ cd packages/cool-package
$ yarn init
```
We won't go into too much detail in creating a package. If you are not familiar with this, consider using a simple app without monorepos. But, to make the example complete, let's add an **index.js** file with the following content:
```js index.js
export const greeting = 'Hello!';
```
### Using the package
Like standard packages, we need to add our **cool-package** as a dependency to our **cool-app**. The main difference between a standard package, and one from the monorepo, is you'll always want to use the _"current state of the package"_ instead of a version. Let's add **cool-package** to our app by adding `"cool-package": "*"` to our app **package.json** file:
```json package.json
{
  "name": "cool-app",
  "version": "1.0.0",
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web"
  },
  "dependencies": {
    "cool-package": "*",
    "expo": "~53.0.0",
    "expo-status-bar": "~2.2.3",
    "react": "19.0.0",
    "react-dom": "19.0.0",
    "react-native": "0.79.4",
    "react-native-web": "~0.20.0"
  },
  "devDependencies": {
    "@babel/core": "^7.27.7"
  }
}
```
> After adding the package as a dependency, run `yarn install` to install or link the dependency to your app.
Now you should be able to use the package inside your app! To test this, let's edit the **App.js** in our app and render the `greeting` text from our **cool-package**.
```jsx App.js
import { greeting } from 'cool-package';
import { StatusBar } from 'expo-status-bar';
import React from 'react';
import { Text, View } from 'react-native';
export default function App() {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>{greeting}</Text>
      <StatusBar style="auto" />
    </View>
  );
}
```
## Common issues
As mentioned earlier, using monorepos is not for everyone. You take on increased complexity and need to solve issues you most likely will run into. Here are a couple of common issues you might encounter.
### Multiple React Native versions within the monorepo
Expo SDK has improved support for more complete **node_modules** patterns, such as isolated modules. Unfortunately, React Native can still cause issues when installing multiple versions inside a single monorepo. Because of that, it's recommended to only use a single version of React Native.
You can check if your monorepo has multiple React Native versions and why they are installed through the package manager you use.
```sh
but you can use `yarn why`
$ bun install --yarn && yarn why react-native
aliased to `npm why`
$ npm why react-native
$ pnpm why --recursive react-native
$ yarn why react-native
```
### Can I use another monorepo tool instead of Yarn workspaces?
There are a lot of monorepo tools available, and each of these tools has its benefits. It's hard for us to keep up with the latest tools and methods, and because of that, we can't officially support new monorepo tools. That being said, if the tool follows these three rules, it should work fine.
Note: 1. All dependencies must be installed in a node_modules directory
---
React Native dependencies contain many other files besides JavaScript, like Gradle files such as **react-native/react.gradle**. These native files are referenced from different sources other than Node.js, and because of that, it makes it fundamentally incompatible with concepts like Plug'n'Play modules.
---
Note: 2. Dependencies used in multiple workspaces can be installed in the root node_modules directory
---
Whenever multiple workspaces use the same version of a single dependency, they can be installed in a root **node_modules** directory. Monorepo tools usually do this to remove duplicate tasks, like installing the same dependency twice in different places. This rule isn't necessary but does set us up for next rule.
---
Note: 3. Different versions of dependencies must be installed in the app node_modules directory
---
In the [Modify the Metro config](#modify-the-metro-config) step, we instructed Metro to do a couple of this, specifically:
- #2 - Resolve dependencies in the order of the local **apps/&lt;name&gt;/node_modules** and root **node_modules** directories.
- #3 - Disable resolving dependencies using the hierarchical lookup strategy.
If a workspace uses a different library version than the one installed in the root **node_modules**, that different library version must be installed in the workspace **apps/&lt;name&gt;/node_modules** directory.
When Metro resolves a library, for example, `react`, from the workspace, it should find that different version in **apps/&lt;name&gt;/node_modules** and not look inside the root **node_modules** directory.
When importing a dependency from the root **node_modules** directory that also imports `react`, `react` should still resolve to the different version installed in **apps/&lt;name&gt;/node_modules**. That's what the disabled hierarchical lookup option does for Metro. Without this, some libraries might import the wrong `react` version and cause "multiple React versions found" errors.
---
[pnpm](https://pnpm.nodejs.cn/) 等工具的默认设置不遵循这些规则。你可以通过添加带有 `node-linker=hoisted` ([请参阅文档](https://pnpm.nodejs.cn/npmrc#node-linker)) 的 .npmrc 文件来更改它。该配置选项将更改行为以匹配这些规则。
¥The default settings of tools like [pnpm](https://pnpm.nodejs.cn/) do not follow these rules. You can change that by adding a **.npmrc** file with `node-linker=hoisted` ([see docs](https://pnpm.nodejs.cn/npmrc#node-linker)). That config option will change the behavior to match these rules.
<a id="script--does-not-exist"></a>
### 脚本 '...' 不存在
¥Script '...' does not exist
React Native 使用包来传送 JavaScript 和原生文件。这些原生文件也需要链接，例如 android/app/build.Gradle 中的 [**react-native/react.Gradle**](https://github.com/facebook/react-native/blob/v0.70.6/react.gradle) 文件。通常，该路径被硬编码为：
¥React Native uses packages to ship both JavaScript and native files. These native files also need to be linked, like the [**react-native/react.Gradle**](https://github.com/facebook/react-native/blob/v0.70.6/react.gradle) file from **android/app/build.Gradle**. Usually, this path is hardcoded to something like:
安卓 ([source](https://github.com/facebook/react-native/blob/e918362be3cb03ae9dee3b8d50a240c599f6723f/template/android/app/build.gradle#L84))
¥**Android** ([source](https://github.com/facebook/react-native/blob/e918362be3cb03ae9dee3b8d50a240c599f6723f/template/android/app/build.gradle#L84))
```groovy
apply from: "../../node_modules/react-native/react.gradle"
```
iOS ([source](https://github.com/facebook/react-native/blob/e918362be3cb03ae9dee3b8d50a240c599f6723f/template/ios/Podfile#L1))
```ruby
require_relative '../node_modules/react-native/scripts/react_native_pods'
```
不幸的是，由于 [hoisting](https://yarn.nodejs.cn/blog/2018/02/15/nohoist/)，这条路径在 monorepos 中可能会有所不同。它也不使用 [节点模块解析](https://nodejs.cn/api/modules.html#all-together)。你可以通过使用 Node 查找包的位置而不是对其进行硬编码来避免此问题：
¥Unfortunately, this path can be different in monorepos because of [hoisting](https://yarn.nodejs.cn/blog/2018/02/15/nohoist/). It also doesn't use the [Node module resolution](https://nodejs.cn/api/modules.html#all-together). You can avoid this issue by using Node to find the location of the package instead of hardcoding this:
安卓 ([source](https://github.com/expo/expo/blob/6877c1f5cdca62b395b0d5f49d87f2f3dbb50bec/templates/expo-template-bare-minimum/android/app/build.gradle#L87))
¥**Android** ([source](https://github.com/expo/expo/blob/6877c1f5cdca62b395b0d5f49d87f2f3dbb50bec/templates/expo-template-bare-minimum/android/app/build.gradle#L87))
```groovy
apply from: new File(["node", "--print", "require.resolve('react-native/package.json')"].execute(null, rootDir).text.trim(), "../react.gradle")
```
iOS ([source](https://github.com/expo/expo/blob/61cbd9a5092af319b44c319f7d51e4093210e81b/templates/expo-template-bare-minimum/ios/Podfile#L2))
```ruby
require File.join(File.dirname(`node --print "require.resolve('react-native/package.json')"`), "scripts/react_native_pods")
```
在上面的代码片段中，你可以看到我们使用 Node 自己的 [`require.resolve()`](https://nodejs.cn/api/modules.html#requireresolverequest-options) 方法来查找包位置。我们明确引用 `package.json` 是因为我们想要找到包的根位置，而不是入口点的位置。有了这个根位置，我们就可以解析出包内预期的相对路径。[在此处了解有关这些参考资料的更多信息](https://github.com/expo/expo/blob/4633ab2364e30ea87ca2da968f3adaf5cdde9d8b/packages/expo-modules-core/README.mdx#importing-native-dependencies---autolinking)。
¥In the snippets above, you can see that we use Node's own [`require.resolve()`](https://nodejs.cn/api/modules.html#requireresolverequest-options) method to find the package location. We explicitly refer to `package.json` because we want to find the root location of the package, not the location of the entry point. And with that root location, we can resolve to the expected relative path within the package. [Learn more about these references here](https://github.com/expo/expo/blob/4633ab2364e30ea87ca2da968f3adaf5cdde9d8b/packages/expo-modules-core/README.mdx#importing-native-dependencies---autolinking).
所有 Expo SDK 模块和模板都有这些动态引用并与 monorepos 一起使用。但是，偶尔，你可能会遇到仍然使用硬编码路径的包。你可以使用 [`patch-package`](https://github.com/ds300/patch-package#readme) 手动编辑它或向软件包维护人员提及这一点。
¥All Expo SDK modules and templates have these dynamic references and work with monorepos. However, occasionally, you might run into packages that still use the hardcoded path. You can manually edit it with [`patch-package`](https://github.com/ds300/patch-package#readme) or mention this to the package maintainers.


## 查看日志

了解如何在使用 Expo CLI 时查看日志、Android Studio 和 Xcode 中的原生日志以及系统日志。

在 React Native 应用中记录信息的工作方式与在 Web 浏览器中类似。你可以使用 `console.log`、`console.warn` 和 `console.error`。然而，有时，你可能想要深入了解有关应用中发生的情况的更多有用信息。为此，你可以使用原生日志和系统日志。
¥Logging information in a React Native app works similarly to in a web browser. You can use `console.log`, `console.warn` and `console.error`. However, at times, you might want to dive deep to get more useful information about what's happening in your app. For that, you can use **native logs** and **system logs**.
<a id="console-logs"></a>
## 控制台日志
¥Console logs
当你运行 `npx expo start` 并连接设备时，控制台日志将显示在终端进程中。这些日志通过 Web 套接字从运行时发送到 Expo CLI，这意味着结果的保真度低于将开发工具直接连接到引擎的结果。
¥When you run `npx expo start` and connect a device, console logs will show up in the terminal process. These logs are sent from the runtime to Expo CLI over web sockets, meaning the results are lower fidelity than connecting dev tools directly to the engine.
你可以通过使用 [Hermes](/guides/using-hermes) 和 [连接检查器](/guides/using-hermes#javascript-inspector-for-hermes) 创建开发版本来查看高保真日志并使用 `console.table` 等高级日志记录功能。
¥You can view **high fidelity** logs and use advanced logging functions like `console.table` by creating a development build with [Hermes](/guides/using-hermes), and [connecting the inspector](/guides/using-hermes#javascript-inspector-for-hermes).
<a id="native-logs"></a>
## 原生日志
¥Native logs
你可以通过本地编译原生应用在 Android Studio 和 Xcode 中查看原生运行时日志。欲了解更多信息，请参阅 [原生调试](/debugging/runtime-issues/#native-debugging)。
¥You can view native runtime logs in Android Studio and Xcode by compiling the native app locally. For more information, see [native debugging](/debugging/runtime-issues/#native-debugging).
<a id="system-logs"></a>
## 系统日志
¥System logs
虽然通常没有必要，但如果你想查看设备上发生的所有情况的日志，例如，甚至来自其他应用和操作系统的日志，你可以使用以下命令：
¥While it's usually not necessary, if you want to see logs for everything happening on your device, for example, even the logs from other apps and the OS, you can use the following commands:
```sh
$ npx react-native log-android
$ npx react-native log-ios
```


## 开发生产模式

了解如何在开发模式或生产模式下运行项目。

你的项目将始终在开发或生产模式下运行。默认情况下，使用 `npx expo start` 在本地运行项目会在开发模式下运行，而已发布的项目（使用 `eas update`）或任何独立应用都会在生产模式下运行。
¥Your project will always run in either **development** or **production** mode. By default, running your project locally with `npx expo start` runs it in development mode, whereas a published project (with `eas update`), or any standalone app, will run in production mode.
开发模式包括有用的警告，并让你可以访问使开发和调试更容易的工具。生产模式 [缩小你的代码](/guides/customizing-metro/#minification) 及更好地代表你的应用在终端用户设备上的性能。让我们更详细地了解每种模式，并了解如何在它们之间进行切换。
¥**Development mode** includes useful warnings and gives you access to tools that make development and debugging easier. **Production mode** [minifies your code](/guides/customizing-metro/#minification) and better represents the performance your app will have on end users' devices. Let's look at each of these modes in more detail and learn how you can switch between them.
<a id="development-mode"></a>
## 开发模式
¥Development mode
React Native 包含一些非常有用的开发工具：Chrome 中的远程 JavaScript 调试、实时重载、热重载以及类似于你在 Chrome 中使用的深受喜爱的检查器的元素检查器。如果你想了解如何使用这些工具，请参阅 [调试](/debugging/runtime-issues/)。
¥React Native includes some very useful tools for development: remote JavaScript debugging in Chrome, live reload, hot reloading, and an element inspector similar to the beloved inspector you use in Chrome. If you want to see how to use those tools, see [Debugging](/debugging/runtime-issues/).
开发模式还会在你的应用运行时执行验证以向你发出警告。例如，如果你正在使用已弃用的属性，或者你忘记将必需属性传递到组件中。下面的视频展示了元素检查器和性能监视器在 Android 模拟器和 iOS 模拟器上的运行情况：
¥Development mode also performs validations while your app is running to give you warnings. For example, if you're using a deprecated property or if you forgot to pass a required property into a component. The video below shows the Element Inspector and Performance Monitor in action on both Android Emulator and iOS Simulator:
>  **warning** 这是有代价的。你的应用在开发模式下运行速度较慢。 你可以使用 Expo CLI 打开和关闭它，请参阅 [生产模式](#production-mode)。当你切换它时，关闭并重新打开你的应用以使更改生效。每当你测试应用的性能时，请确保禁用开发模式。
>
> ¥**This comes at a cost. Your app runs slower in development mode.**  You can switch it on and off with the Expo CLI, see [Production mode](#production-mode). When you switch it, close and re-open your app for the change to take effect. **Any time you are testing your app's performance, make sure to disable development mode**.
<a id="view-the-developer-menu"></a>
### 查看开发者菜单
¥View the developer menu
通过该菜单可以访问许多功能，使开发和调试变得更加容易。有关如何在 Android 和 iOS 上打开它的更多信息，请参阅 [开发者菜单](/debugging/tools/#developer-menu)。
¥The menu gives access to a host of features that make development and debugging much easier. For more information on how to open it on Android and iOS, see [Developer menu](/debugging/tools/#developer-menu).
<a id="production-mode"></a>
## 生产模式
¥Production mode
生产模式对于两件事最有用：
¥Production mode is most useful for two things:
* 测试应用的性能，因为开发会大大减慢应用的速度。
  ¥Testing your app's performance, as Development slows your app down considerably.
* 捕获仅在生产中出现的错误。
  ¥Catching bugs that only show up in production.
模拟项目在终端用户设备上运行方式的最简单方法是使用以下命令：
¥The easiest way to simulate how your project will run on end users' devices is with the command:
```sh
$ npx expo start --no-dev --minify
```
它在生产模式下运行应用的 JavaScript（它告诉 Metro 打包程序将 `__DEV__` 环境变量设置为 `false` 等）。`--minify` 标志缩小了你的应用。该标志还消除了不必要的数据，例如注释、格式和未使用的代码。如果你的独立应用出现错误或崩溃，使用此命令运行项目可以节省大量时间来查找根本原因。
¥It runs the JavaScript of your app in production mode (which tells the Metro bundler to set the `__DEV__` environment variable to `false`, among a few other things). The `--minify` flag minifies your app. This flag also eliminates unnecessary data such as comments, formatting, and unused code. If you are getting an error or crash in your standalone app, running your project with this command can save you a lot of time in finding the root cause.
要完全编译你的应用以进行生产，请参阅 [编译 Android](/more/expo-cli/#compiling-android) 和 [编译 iOS](/more/expo-cli/#compiling-ios)。
¥To completely compile your app for production see [Compiling Android](/more/expo-cli/#compiling-android) and [Compiling iOS](/more/expo-cli/#compiling-ios).


## 常见开发错误

开发者使用 Expo 时遇到的常见开发错误列表。

本页概述了开发者使用 Expo 时经常遇到的错误列表。对于每个错误，第一个项目符号提供了错误发生原因的解释，第二个项目符号包含调试建议。如果你认为这里有错误，我们欢迎并鼓励你 [创建 PR](https://github.com/expo/expo/pulls)！
¥This page outlines a list of errors that are commonly encountered by developers using Expo. For each error, the first bullet provides an explanation for why the error occurs and the second bullet contains debugging suggestions. If there is an error you think belongs here, we welcome and encourage you to [create a PR](https://github.com/expo/expo/pulls)!
<a id="metro-bundler-econnrefused-12700119001"></a>
### Metro 打包程序 ECONNREFUSED 127.0.0.1:19001
¥Metro bundler ECONNREFUSED 127.0.0.1:19001
* 错误导致无法连接到本地开发服务器。
  ¥An error is preventing the connection to your local development server.
* 运行 `rm -rf .expo` 以清除本地状态。检查影响你当前连接的网络的防火墙或 [proxies](/troubleshooting/proxies/)。
  ¥Run `rm -rf .expo` to clear your local state. Check for firewalls or [proxies](/troubleshooting/proxies/) affecting the network you are currently connected to.
<a id="module-appregistry-is-not-a-registered-callable-module-calling-runapplication"></a>
### Module AppRegistry 不是已注册的可调用模块（调用 runApplication）
¥Module AppRegistry is not a registered callable module (calling runApplication)
* 代码中的错误导致 JavaScript 包无法在启动时执行。
  ¥An error in your code is preventing the JavaScript bundle from being executed on startup.
* 尝试运行 `npx expo start --no-dev --minify` 在本地重现生产 JS 包。如果可能，请连接你的设备并通过 Android Studio 或 Xcode 访问设备日志。设备日志包含更详细的堆栈跟踪和信息。检查 Babel 配置是否有任何更改或错误。在极少数情况下，此问题可能是由于 Metro JavaScript 压缩器与应用中的某些代码 ([更多信息](https://forums.expo.dev/t/change-minifierconfig-for-minify-uglify/36460/2)) 不兼容造成的。
  ¥Try running `npx expo start --no-dev --minify` to reproduce the production JS bundle locally. If possible, connect your device and access the device logs via Android Studio or Xcode. Device logs contain much more detailed stacktraces and information. Check to see if you have any changes or errors in your Babel configuration. In some rare cases, this issue could be caused by incompatibility between the Metro JavaScript minifier and certain code in your app ([more information](https://forums.expo.dev/t/change-minifierconfig-for-minify-uglify/36460/2)).
<a id="npm-err-no-git-binary-found-in-path"></a>
### npm 错误！在 $PATH 中找不到 git 二进制文件
¥npm ERR! No git binary found in $PATH
* 要么你没有安装 git，要么你的 `$PATH`.conf 中没有正确配置 git。
  ¥Either you do not have git installed or it is not properly configured in your `$PATH`.
* [安装 git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)（如果你还没有）。否则，请根据你的操作系统检查如何在 `$PATH` 中设置它。
  ¥[Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) if you have not already. Otherwise, check how to set it in your `$PATH` based on your OS.
<a id="xxxx-is-not-a-valid-sdk-version"></a>
### XX.X.X 不是有效的 SDK 版本
¥XX.X.X is not a valid SDK version
* 你正在运行的 SDK 版本已被弃用，不再受支持。
  ¥The SDK version you are running has been deprecated and is no longer supported.
* [升级你的项目](/workflow/upgrading-expo-sdk-walkthrough) 到支持的 SDK 版本。如果你使用的是受支持的版本并看到此消息，则需要更新你的 Expo Go 应用。
  ¥[Upgrade your project](/workflow/upgrading-expo-sdk-walkthrough) to a supported SDK version. If you are using a supported version and see this message, you'll need to update your Expo Go app.
<a id="react-native-version-mismatch"></a>
### React Native 版本不匹配
¥React Native version mismatch
* 在你的终端中运行的开发服务器打包了与你的设备或模拟器中的应用不同版本的 React Native。
  ¥The development server running in your terminal is bundling a different version of React Native than the app in your device or simulator.
* [调整你的 react-native 版本](/troubleshooting/react-native-version-mismatch) 通过检查 app.json 和 package.json 中的版本
  ¥[Align your versions of react-native](/troubleshooting/react-native-version-mismatch) by checking the versions in your **app.json** and **package.json**
<a id="application-has-not-been-registered"></a>
### 应用尚未注册
¥Application has not been registered
* 你的应用的原生部分和 JS 部分中注册的 AppKey 不匹配。
  ¥There is a mismatch between the AppKey registered in the native and JS portion of your app.
* [对齐你的 AppKey](/troubleshooting/application-has-not-been-registered/) 与你项目的原生部分。
  ¥[Align your AppKey](/troubleshooting/application-has-not-been-registered/) with the native side of your project.
<a id="application-not-behaving-as-expected"></a>
### 应用未按预期运行
¥Application not behaving as expected
* 缓存可能会阻止你查看应用的当前状态。
  ¥It is possible caches may be preventing you from seeing the current state of your application.
* 清除 [类 Unix](/troubleshooting/clear-cache-macos-linux/) 或 [视窗](/troubleshooting/clear-cache-windows/) 系统中与你的项目关联的所有缓存。
  ¥Clear all caches associated with your project in [Unix-like](/troubleshooting/clear-cache-macos-linux/) or [Windows](/troubleshooting/clear-cache-windows/) systems.


## Android Studio 模拟器

了解如何设置 Android 模拟器以在虚拟 Android 设备上测试你的应用。

如果你没有可用于测试的 Android 设备，我们建议使用 Android Studio 附带的默认模拟器。如果你在设置时遇到任何问题，请按照本指南中的步骤操作。
¥If you don't have an Android device available to test with, we recommend using the default emulator that comes with Android Studio. If you run into any problems setting it up, follow the steps in this guide.
<AndroidStudioEnvironmentInstructions />
<AndroidStudioInstructions />
<AndroidEmulatorInstructions />
<a id="troubleshooting"></a>
## 故障排除
¥Troubleshooting
<a id="multiple-adb-versions"></a>
### 多个 `adb` 版本
¥Multiple `adb` versions
系统上有多个 `adb` 版本可能会导致以下错误：
¥Having multiple `adb` versions on your system can result in the following error:
```sh
$ adb server version (xx) doesn't match this client (xx); killing...
```
这是因为你系统上的 `adb` 版本与 Android SDK 平台工具上的 `adb` 版本不同。
¥This is because the `adb` version on your system is different from the `adb` version on the Android SDK platform-tools.
Step 1: 
Open the terminal and check the `adb` version on the system:
```sh
$ adb version
```
Step 2: 
And from the Android SDK platform-tool directory:
```sh
$ cd ~/Library/Android/sdk/platform-tools
$ ./adb version
```
Step 3: 
Copy `adb` from Android SDK directory to `usr/bin` directory:
```sh
$ sudo cp ~/Library/Android/sdk/platform-tools/adb /usr/bin
```


## iOS 模拟器

了解如何在 Mac 上安装 iOS 模拟器并使用它来开发应用。

直接在计算机上开发应用比不断与 iPhone 或 iPad 交互更方便，尤其是当网络条件较慢或由于 LAN 限制而需要 [隧道连接](/more/expo-cli/#tunneling) 时。
¥Developing your app directly on a computer can be more convenient than constantly interacting with an iPhone or iPad, especially when network conditions are slow or when a [tunnel connection](/more/expo-cli/#tunneling) is required due to LAN limitations.
本指南介绍了如何在 Mac 上安装 iOS 模拟器以进行应用开发。请注意，iOS 模拟器只能安装在 macOS 上。如果你要从 Windows 或 Linux 计算机开发 iOS 应用，则需要物理 iOS 设备。
¥This guide explains how to install the iOS Simulator on your Mac for app development. Note that the iOS Simulator can only be installed on macOS. If you are developing an iOS app from a Windows or a Linux machine, you will need a physical iOS device.
<a id="setup-xcode-and-watchman"></a>
## 设置 Xcode 和 Watchman
¥Setup Xcode and Watchman
<XcodeInstructions />
Step 4: 
### Try it out
Run your app with `npx expo start` and press <kbd>i</kbd> from the command line.
You may get a warning about needing to accept the Xcode license. Run the command that it suggests. Open your app again to see if it was successful. If not, check the [troubleshooting](#troubleshooting) tips below.
You can also press <kbd>shift</kbd> + <kbd>i</kbd> in the Expo CLI to interactively select a simulator to open.
## Expo Orbit
You can use the Expo Orbit app which allows launching builds and simulator management with one click from the menu bar on macOS.
## Limitations
Although the iOS Simulator is great for rapid development, it does come with a few limitations. We'll list out a few of the main differences that affect Expo APIs below. However, see [Apple's documentation](https://help.apple.com/simulator/mac/current/#/devb0244142d) for more details.
The following hardware is unavailable in the Simulator:
- Audio Input
- Barometer
- Camera
- Motion Support (accelerometer and gyroscope)
The Simulator also suspends background apps and processes on iOS 11 and later.
## Troubleshooting
### The CLI seems to be stuck when opening a Simulator
Sometimes the iOS Simulator doesn't respond to the open command. If it seems stuck on this prompt, you can open the iOS Simulator manually (`open -a Simulator`) and then in the macOS toolbar, choose **File** &gt; **Open Simulator**, and select an iOS version and device that you'd like to open.
You can use this menu to open any version of the simulator. You can also open multiple simulators at the same time, however, Expo CLI will always target the most recently opened simulator.
### Simulator opened but the Expo Go app isn't opening inside of it
The first time you install the app in the simulator, iOS will ask if you'd like to open the Expo Go app. You may need to interact with the simulator (click around, drag something) for this prompt to show up, then press **OK**.
### How do I force an update to the latest version?
Create a project with the desired SDK version and open it in a simulator to install a particular version of Expo Go.
```sh
$ npx create-expo-app --template blank@53
$ npx expo start --ios
```
### Expo CLI is printing an error message about `xcrun`, what do I do?
For miscellaneous errors, try the following:
- Manually uninstall Expo Go on your simulator and reinstall by pressing <kbd>shift</kbd> + <kbd>i</kbd> in the Expo CLI Terminal UI and selecting the desired simulator.
- If that doesn't help, focus the simulator window and in the Mac toolbar choose **Device** &gt; **Erase All Content and Settings...**
这将从空白图片重新初始化你的模拟器。这有时对于计算机内存不足且模拟器无法存储某些内部文件、使设备处于损坏状态的情况很有用。
¥This will reinitialize your simulator from a blank image. This is sometimes useful for cases where your computer is low on memory and the simulator fails to store some internal files, leaving the device in a corrupt state.


## React Native 的新架构

了解 React Native 的 "新架构" 以及如何以及为何迁移到它。

>  **info** 为了在新架构下获得最佳体验，我们建议使用最新的 Expo 版本。
>
> ¥We recommend using the latest Expo version for the best experience with the New Architecture.
新架构是我们用来描述 React Native 内部结构的完整重构的一个名称。它还用于解决 Meta 和其他公司多年来在生产中使用时发现的原始 React Native 架构的局限性。
¥The New Architecture is a name that we use to describe a complete refactoring of the internals of React Native. It is also used to solve limitations of the original React Native architecture discovered over years of usage in production at Meta and other companies.
在本指南中，我们今天将讨论如何在 Expo 项目中使用新架构。
¥In this guide, we'll talk about how to use the New Architecture in Expo projects today.
Note: Why migrate to the New Architecture?
---
**The New Architecture is the future of React Native** &mdash; yet, for many apps, there may not be many immediate benefits to migrating today. You may want to think of migrating to the New Architecture as an investment in the future of your app, rather than as a way to immediately improve your app.
That said, **new React and React Native features are coming to the New Architecture only**. For example, the New Architecture includes [full support for Suspense](https://rn.nodejs.cn/blog/2024/10/23/the-new-architecture-is-here#full-support-for-suspense) and [new styling capabilities](https://rn.nodejs.cn/blog/2025/01/21/version-0.77#new-css-features-for-better-layouts-sizing-and-blending) are not implemented in the legacy architecture. Libraries such as [@shopify/flash-list](https://github.com/Shopify/flash-list) and [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated) will be shipping new major versions that take full advantage of new features to deliver better performance than was possible before, and will drop support for the legacy architecture.
**The legacy architecture will not be around forever** &mdash; it's possible that the legacy architecture will be removed from React Native in a late 2025 release. When it is removed, you will not be able to upgrade React Native or the Expo SDK without migrating to the New Architecture.
---
## Expo tools and the New Architecture
As of SDK 53, all `expo-*` packages in the [Expo SDK](/versions/latest/) support the New Architecture (including [bridgeless](https://github.com/reactwg/react-native-new-architecture/discussions/154)). [Learn more about known issues](#known-issues-in-expo-sdk-libraries).
Additionally, all modules written using the [Expo Modules API](/modules/overview/) support the New Architecture by default! So if you have built your own native modules using this API, no additional work is needed to use them with the New Architecture.
**As of April 2025, approximately 75% of SDK 52+ projects built with [EAS Build](/build/introduction/) use the New Architecture**.
## Third-party libraries and the New Architecture
The compatibility status of many of the most popular libraries is tracked on [React Native Directory](https://reactnative.directory/) ([learn more about known issues in third-party libraries](#known-issues-in-third-party-libraries)). We've built tooling into Expo Doctor to integrate with React Native Directory to help you validate your dependencies, so you can quickly learn which libraries are unmaintained and which incompatible or untested with the New Architecture.
### Validate your dependencies with React Native Directory
Run `npx expo-doctor` to check your dependencies against the data in React Native Directory.
```sh
$ npx expo-doctor@latest
```
You can configure the React Native Directory check in your **package.json** file. For example, if you would like to exclude a package from validation:
!!!IG0!!!
Note: See all available options
---
- **enabled**: If `true`, the check will warn if any packages are missing from React Native Directory. Set this to `false` to disable this behavior. On SDK 52 and above, this is set to `true` by default, otherwise it is `false` by default. You can also override this setting with the `EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK` environment variable (0 is `false`, 1 is `true`).
- **exclude**: List any packages you want to exclude from the check. Supports exact package names and regex patterns. For example, `["exact-package", "/or-a-regex-.*/"]`.
- **listUnknownPackages**: By default, the check will warn if any packages are missing from React Native Directory. Set this to false to disable this behavior.
---
## Initialize a new project with the New Architecture
**As of SDK 52**, all new projects will be initialized with the New Architecture enabled by default.
```sh
$ npx create-expo-app@latest
```
## Enable the New Architecture in an existing project
!!!IG3!!!
!!!IG4!!!
    **The New Architecture is enabled by default in SDK 53 and above**. If you have explicitly disabled it, remove that configuration to enable it.
!!!IG5!!!
!!!IG6!!!
    We recommend upgrading to SDK 53 to ensure that your app can take advantage of all of the latest New Architecture related fixes and improvements with libraries and React Native itself. If you want to try it on SDK 52 first, follow the instructions below.
    Step 1: 
    To enable it on both Android and iOS, use the `newArchEnabled` at the root of the `expo` object in your app config. You can selectively enable it for a single platform by setting, for example, `"android": { "newArchEnabled": true }`.
!!!IG1!!!
    Step 2: 
      Create a new build:
!!!IG7!!!
!!!IG8!!!
          ```sh
if you like
$ npx expo prebuild --clean && npx expo run:android
$ eas build -p android
```
!!!IG9!!!
!!!IG10!!!
          ```sh
if you like
$ npx expo prebuild --clean && npx expo run:ios
$ eas build -p ios
```
!!!IG11!!!
!!!IG12!!!
      If the build succeeds, you will now be running your app with the New Architecture! Depending on the native modules you use, your app may work properly immediately.
      Now you can tap around your app and test it out. For most non-trivial apps, you're likely to encounter some issues, such as missing native views that haven't been implemented for the New Architecture yet. Many of the issues you encounter are actionable and can be resolved with some configuration or code changes. We recommend reading [Troubleshooting](#troubleshooting) sections below for more information.
!!!IG13!!!
!!!IG14!!!
    We recommend upgrading to at least SDK 52, preferably SDK 53. It's possible to enable the New Architecture in SDK 51, but you are likely to encounter a variety of issues that have been resolved in more recent releases. To enable it, you need to [install the `expo-build-properties` plugin](/versions/latest/sdk/build-properties/#installation) and set `newArchEnabled` on target platforms.
!!!IG15!!!
!!!IG16!!!
Note: Are you enabling the New Architecture in a bare React Native app?
---
If you are using Expo SDK 53 or higher, it will be enabled by default. The following instructions apply to older projects.
- **Android**: Set `newArchEnabled=true` in the **gradle.properties** file.
- **iOS**: If your project has a **Podfile.properties.json** file (which is created by `npx create-expo-app` or `npx expo prebuild`), you can enable the New Architecture by setting the `newArchEnabled` property to `"true"` in the **Podfile.properties.json** file. Otherwise, refer to the ["Enable the New Architecture for Apps"](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/enable-apps.md) section of the React Native New Architecture working group.
---
## Disable the New Architecture in an existing project
> **info**: Expo Go only supports the New Architecture.
If you want to opt out of using the New Architecture, set the `newArchEnabled` property to `false` in app config and create a [development build](/develop/development-builds/introduction/).
!!!IG2!!!
Note: Are you disabling the New Architecture in a bare React Native app?
---
- **Android**: Set `newArchEnabled=false` in the **gradle.properties** file.
- **iOS**: If your project has a **Podfile.properties.json** file (which is created by `npx create-expo-app` or `npx expo prebuild`), you can disable the New Architecture by setting the `newArchEnabled` property to `"false"` in the **Podfile.properties.json** file. Otherwise, refer to the ["Enable the New Architecture for Apps"](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/enable-apps.md) section of the React Native New Architecture working group.
---
## Troubleshooting
Meta and Expo are working towards making the New Architecture the default for all new apps and ensuring it is as easy as possible to migrate existing apps. However, the New Architecture isn't just a name &mdash; many of the internals of React Native has been re-architected and rebuilt from the ground up. As a result, you may encounter issues when enabling the New Architecture in your app. The following is some advice for troubleshooting these issues.
Note: Can I still try the New Architecture even if some of the libraries I use aren't supported?
---
You may be able to try the New Architecture in your app even if some of the libraries you use aren't supported, but it will require temporarily removing those libraries. Create a new branch in your repository and remove any of the libraries that aren't compatible until your app is running. This will give you a good idea of what libraries still need work before you can fully migrate to the New Architecture. We recommend creating issues or pull requests on those libraries' repositories to help them become compatible with the New Architecture. Alternatively, you could switch to other libraries that are compatible with the New Architecture. Refer to [React Native Directory](https://reactnative.directory/) to find compatible libraries.
---
Note: Known issues in React Native
---
Refer to the [issues labeled with "Type: New Architecture" on the React Native GitHub repository](https://github.com/facebook/react-native/issues?q=is%3Aopen+is%3Aissue+label%3A%22Type%3A+New+Architecture%22).
---
Note: Known issues in Expo libraries
---
There are no known issues specific to the New Architecture in Expo libraries.
---
Note: Known issues in third-party libraries
---
Since React Native 0.74, there are various Interop Layers enabled by default. This allows many libraries built for the old architecture to work on the New Architecture without any changes. However, the interop is not perfect and some libraries will need to be updated. The libraries that are most likely to require updates are those that ship or depend on third-party native code. [Learn more about library support in the New Architecture](https://github.com/reactwg/react-native-new-architecture/discussions/167).
Refer to [React Native Directory](https://reactnative.directory/) a more complete list of libraries and their compatibility with the New Architecture. The following libraries were found to be popular among Expo apps and are known to be incompatible:
The following are known issues with libraries that are popular among Expo apps.
- **react-native-maps**: Version 1.20.x, which is the default for SDK 53, supports the New Architecture with the interop layer and works well for most features. A New Architecture-first version is available in version 1.21.0, which is still stabilizing. We encourage your to test it in your app, report issues that you find, and [follow along with the discussion on GitHub](https://github.com/react-native-maps/react-native-maps/discussions/5355). We are also investigating another approach that may provider a smoother migration path, by leaning on the [interop layer](https://github.com/reactwg/react-native-new-architecture/discussions/175) rather than rewriting the module. It's worth mentioning that if your app can force a minimum version of iOS 17, or does not need to support maps on iOS, then you can consider using [`expo-maps`](/versions/latest/sdk/maps/) instead.
- **@stripe/react-native**: The New Architecture is supported starting with version 0.45.0, which is the default for SDK 53.
- **@react-native-community/masked-view**: Use `@react-native-masked-view/masked-view` instead.
- **@react-native-community/clipboard**: Use `@react-native-clipboard/clipboard` instead.
- **rn-fetch-blob**: Use `react-native-blob-util` instead.
- **react-native-fs**: Use `expo-file-system` or [a fork of react-native-fs](https://github.com/birdofpreyru/react-native-fs) instead.
- **react-native-geolocation-service**: Use `expo-location` instead.
- **react-native-datepicker**: Use `react-native-date-picker` or `@react-native-community/datetimepicker` instead.
---
Note: My build failed after enabling the New Architecture
---
This isn't entirely surprising! Not all libraries are compatible yet, and in some cases compatibility was only recently added and so you will want to ensure you update your libraries to their latest versions. Read the logs to determine which library is incompatible. Also, run `npx expo-doctor@latest` to check your dependencies against the data in React Native Directory.
When you are using the latest version of a library and it is not compatible, report any issues you encounter to the respective GitHub repository. Create a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) and report the issue to the library author. If you believe the issue originates in React Native itself, rather than a library, report it to the React Native team (again, with a minimal reproducible example).
---


## React 编译器

了解如何在 Expo 应用中启用和使用 React Compiler。

>  **important** React Compiler 是实验性的。目前，它处于暂停状态，我们将很快提供有关其使用的更多更新。
>
> ¥React Compiler is experimental. Currently, it is on hold and we'll soon provide more updates on its usage.
新的 [React 编译器](https://react.nodejs.cn/learn/react-compiler) 会自动记忆组件和钩子以实现细粒度的反应性。这可以显著提高你的应用的性能。React Compiler 目前处于实验阶段，默认情况下未启用。你可以按照以下说明在你的应用中启用它。
¥The new [React Compiler](https://react.nodejs.cn/learn/react-compiler) automatically memoizes components and hooks to enable fine-grained reactivity. This can lead to significant performance improvements in your app. The React Compiler is currently experimental and is not enabled by default. You can enable it in your app by following the instructions below.
<a id="enabling-react-compiler"></a>
## 启用 React 编译器
¥Enabling React Compiler
Step 1: 
[Check how compatible](https://react.nodejs.cn/learn/react-compiler#checking-compatibility) your project is with the React Compiler.
```sh
$ npx react-compiler-healthcheck@latest
```
This will generally verify if your app is following the [**rules of React**](https://react.nodejs.cn/reference/rules).
Step 2: 
Install `babel-plugin-react-compiler` and the React compiler runtime in your project:
    Babel is automatically configured in Expo SDK 54 and above.
    ```sh
$ npx expo install babel-plugin-react-compiler@beta
```
    ```sh
$ npx expo install babel-plugin-react-compiler@beta react-compiler-runtime@beta
```
Step 3: 
Toggle on the React Compiler experiment in your app config file:
```json app.json
{
  "expo": {
    "experiments": {
      "reactCompiler": true
    }
  }
}
```
### Enabling the linter
> In the future, all of the following steps below will be automated by Expo CLI.
Additionally, you should use the ESLint plugin to continuously enforce the rules of React in your project.
Step 1: 
Run [`npx expo lint`](/guides/using-eslint/#eslint) to ensure ESLint is setup in your app, then install the ESLint plugin for React Compiler:
```sh
$ npx expo install eslint-plugin-react-compiler
```
Step 2: 
Update your [ESLint configuration](/guides/using-eslint/) to include the plugin:
```js .eslintrc.js
// https://expo.nodejs.cn/guides/using-eslint/
const { defineConfig } = require('eslint/config');
const expoConfig = require('eslint-config-expo/flat');
module.exports = defineConfig([
  expoConfig,
  {
    ignores: ['dist/*'],
    plugins: ['react-compiler'],
    rules: {
      'react-compiler/react-compiler': 'error',
    },
  },
]);
```
## Incremental adoption
You can incrementally adopt the React Compiler in your app using a few strategies:
Step 1: 
Configure the Babel plugin to only run on specific files or components. To do this:
1. If your project doesn't have [**babel.config.js**](/versions/latest/config/babel/), create one by running `npx expo customize babel.config.js`.
2. Add the following configuration to **babel.config.js**:
```js babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      [
        'babel-preset-expo',
        {
          'react-compiler': {
            sources: filename => {
              // Match file names to include in the React Compiler.
              return filename.includes('src/path/to/dir');
            },
          },
        },
      ],
    ],
  };
};
```
Whenever you change your **babel.config.js** file, you need to restart the Metro bundler to apply the changes:
```sh
$ npx expo start --clear
```
Step 2: 
Use the `"use no memo"` directive to opt out of the React Compiler for specific components or files.
```jsx
function MyComponent() {
  'use no memo';
  return <Text>Will not be optimized</Text>;
}
```
## Usage
>
为了更好地了解 React Compiler 的工作原理，请查看 [React Playground](https://playground.react.dev/)。
¥To better understand how React Compiler works, check out the [React Playground](https://playground.react.dev/).
改进主要是自动的。你可以删除 `useCallback`、`useMemo` 和 `React.memo` 的实例以支持自动记忆。类组件不会进行优化。而是迁移到功能组件。
¥Improvements are primarily automatic. You can remove instances of `useCallback`, `useMemo`, and `React.memo` in favor of the automatic memoization. Class components will not be optimized. Instead, migrate to function components.
Expo 的 React Compiler 实现将仅在应用代码（无节点模块）上运行，并且仅在为客户端打包时运行（在服务器渲染中禁用）。
¥Expo's implementation of the React Compiler will only run on application code (no node modules), and only when bundling for the client (disabled in server rendering).
<a id="configuration"></a>
## 配置
¥Configuration
你可以通过使用 Babel 配置中的 `react-compiler` 对象将其他设置传递给 React Compiler Babel 插件：
¥You can pass additional settings to the React Compiler Babel plugin by using the `react-compiler` object in the Babel configuration:
```js babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      [
        'babel-preset-expo',
        {
          'react-compiler': {
            // Passed directly to the React Compiler Babel plugin.
            compilationMode: 'strict',
            panicThreshold: 'all_errors',
          },
          web: {
            'react-compiler': {
              // Web-only settings...
            },
          },
        },
      ],
    ],
  };
};
```


# 现有的 React Native 应用

## 将 Expo 与现有 React Native 应用结合使用的概述

了解如何将 Expo 工具和服务与现有的 React Native 应用结合使用。

如果你有一个不使用任何 Expo 工具的 React Native 应用，你可能想知道 Expo 可以为你提供什么，为什么你可能想要使用 Expo 工具和服务，以及如何开始。
¥If you have a React Native app that doesn't use any Expo tools, you might be wondering what Expo can provide for you, why you might want to use Expo tools and services, and how to get started.
Expo 提供的所有工具和服务在任何 React Native 应用中都能很好地运行。
¥**All tools and services provided by Expo work great in any React Native app**.
你可以使用 [EAS](/eas) 快速设置专业的 CI/CD 工作流程，以构建、审核、部署和更新你的应用。[Expo CLI](/more/expo-cli/) 为使用 React Native 提供最佳命令行体验。[Expo SDK](/versions/latest/) 是 React Native 的扩展标准库。它为开发者提供了高质量、维护良好的原生库，这些库使用一致的 API 约定，使它们更易于学习和使用。
¥You can use [EAS](/eas) to get quickly set up with a professional CI/CD workflow for building, reviewing, deploying, and updating your apps. [Expo CLI](/more/expo-cli/) provides the best command-line experience for working with React Native. The [Expo SDK](/versions/latest/) is an extended standard library for React Native. It gives developers high-quality, well-maintained native libraries that use consistent API conventions to make them easier to learn and use.
如果你曾经为 React Native 编写过原生模块，你会惊讶地发现，使用 [Expo 模块 API](/modules/overview/) 提供的惯用 Swift 和 Kotlin DSL 构建和维护模块要容易得多。
¥If you've ever written a native module for React Native, you'll be surprised how much easier it is to build and maintain modules with the idiomatic Swift and Kotlin DSL provided by the [Expo Modules API](/modules/overview/).
还有更多值得探索的内容，以下链接将帮助你探索可用的选项。
¥There's so much more to explore, and the links below will help you to explore the options available to you.
<a id="incremental-adoption-steps"></a>
## 增量采用步骤
¥Incremental adoption steps
以下是建议的四个增量采用阶段。这些阶段通常从快速更改以改善开发者体验，到更重要的工作流程和代码库优化。
¥Below are four suggested phases of incremental adoption. These phases generally progress from quick changes to improve developer experience, to more significant workflow and codebase optimizations.
其他阶段只需要第一阶段（先决条件）。按照其说明操作后，你可以跳到与你采用 Expo 的目标最相关的工具和服务。
¥Only the first phase — prerequisites — is required by other phases. After following its instructions, you can skip to the tools and services that are most relevant to your goals in adopting Expo.
<a id="prerequisites"></a>
### 先决条件
¥Prerequisites
这些第一步是以后采用 Expo 工具和服务所必需的：
¥These first steps are required to later adopt Expo tools and services:
  }
  href="/bare/installing-expo-modules"
/>
  }
  href="/bare/using-expo-cli/"
/>
<a id="quick-wins"></a>
### React Native 的 Modal 组件
¥Quick wins
以下内容有助于改善开发体验并需要配置：
¥The following helps improving development experience and requires configuration:
  }
  Icon={BookOpen02Icon}
  href="/bare/install-dev-builds-in-bare/"
/>
<a id="new-workflows"></a>
### 新工作流程
¥New workflows
安装应用 `expo` 包后，你可以使用单个命令将应用提交到应用商店或更新配置 `expo-updates` 库来管理应用代码的远程更新：
¥Once your app has `expo` package installed, you can submit your app to app stores with a single command or update configure `expo-updates` library to manage remote updates to you app's code:
  }
  href="/bare/installing-updates/"
/>
<a id="new-mindsets"></a>
### 新思维模式
¥New mindsets
以下内容有助于提高项目的长期可维护性、原生代码维护和更轻松的升级：
¥The following helps with your project's long term maintainability, native code maintenance, and easier upgrades:
<a id="common-questions"></a>
## 常见问题
¥Common questions
Note: How long will it take to adopt Expo in my existing React Native project?
---
Adopting Expo doesn't have to be done in one step. You can start with the _quick wins_ and then move on to more complex parts. You can also pick and choose which features you want to adopt based on what is most helpful for your project.
---
Note: What will I gain from using Expo in my React Native app?
---
Adopting Expo tools in your existing React Native app can help you develop faster with the [Expo SDK](/versions/latest/), streamline native code maintenance and upgrades with [CNG](/workflow/continuous-native-generation/), deploy faster with [EAS Update](/eas-update/introduction/), and more.
---
Note: Who uses Expo?
---
Expo is used by top companies worldwide that serve millions of end users. For more information, see our [Expo showcase](https://expo.dev/customers).
---
Note: What impact will adopting Expo have on my app's size?
---
The `expo` package has a small footprint since it only includes a minimal set of modules required in every app with autolinking infrastructure and other Expo SDK libraries that are built-in. For more information on how to determine the actual size of your app, see [Understanding app size](/distribution/app-size/).
---
Note: Why did React Native recommend using Expo?
---
Most React Native developers solve common problems when building an app, such as implementing navigation, accessing Native APIs, upgrading to new versions, and more. This requires using a specific set of tools and libraries to build and maintain your app &mdash; which means you are creating your own framework.
Expo solves these problems by providing a set of primitives and helping you (the developer) to focus on building your app. It also offers tools to iterate faster in development. For more information, see [Why React Native recommends using a framework](https://rn.nodejs.cn/blog/2024/06/25/use-a-framework-to-build-react-native-apps).
---
Note: Do I have to get rid of my native projects to use Expo?
---
By default, Expo projects created with `create-expo-app` use [Continuous Native Generation (CNG)](/workflow/continuous-native-generation/) and do not contain **android** and **ios** native directories. If you incrementally adopt Expo in your existing React Native app, you don't have to remove these directories. You can use `npx expo run:[android|ios]` as an alternative to commands offered by `@react-native-community/cli` to compile your app locally and keep the configuration of your native projects.
---
Note: I use CodePush. Can I continue using it with Expo?
---
CodePush will be retired in March 2025 and is incompatible with React Native's New Architecture, so, in the long run, we recommend switching to EAS Update to manage remote updates to your app's code. However, you can start using Expo tools in your CodePush enabled app today, including the Expo SDK, Expo CLI, EAS Build, and more.
---
Note: Do I have to build with EAS?
---
[Expo Application Services (EAS)](/eas/) are deeply integrated cloud services for Expo and React Native apps that provide tools to build, test, and deploy your app.
Although we recommend using EAS for a smooth collaboration with your teammates and fast distribution, you can compile your app locally, on your CI, or any other way you prefer.
---
Note: Can I install third-party native libraries in my code?
---
Yes, you can install and use third-party libraries that require native projects (**android** and **ios**) configuration or provides a [config plugin](/config-plugins/introduction/) with [development builds](/workflow/overview/#development-builds). See [Using Third-Party libraries](/workflow/using-libraries/#third-party-libraries) for more information.
---
Note: I use React Navigation. Do I have to use Expo Router?
---
You can continue using any navigation library in your project. However, we recommend using Expo Router for all the benefits [described here](/router/introduction).
---


## 在现有的 React Native 项目中安装 Expo 模块

了解如何准备现有的 React Native 项目以安装和使用任何 Expo 模块。

要在你的应用中使用 Expo 模块，你需要安装并配置 `expo` 包。
¥To use Expo modules in your app, you will need to install and configure the `expo` package.
`expo` 封装占地面积小；它只包含几乎每个应用所需的最小包集以及其他 Expo SDK 包构建所需要的模块和自动链接基础设施。在项目中安装并配置 `expo` 包后，你可以使用 `npx expo install` 从 SDK 添加任何其他 Expo 模块。
¥The `expo` package has a small footprint; it includes only a minimal set of packages that are needed in nearly every app and the module and autolinking infrastructure that other Expo SDK packages are built with. Once the `expo` package is installed and configured in your project, you can use `npx expo install` to add any other Expo module from the SDK.
根据你的 [初始化项目](/bare/overview/) 方式，你可以通过两种方式安装 Expo 模块：[automatically](#automatic-installation) 或 [manually](#manual-installation)。
¥Depending on how you [initialized the project](/bare/overview/), there are two ways you can install the Expo modules: [automatically](#automatic-installation) or [manually](#manual-installation).
<a id="automatic-installation"></a>
## 自动安装
¥Automatic installation
要安装和使用 Expo 模块，最简单的启动和运行方法是使用 `install-expo-modules` 命令。
¥To install and use Expo modules, the easiest way to get up and running is with the `install-expo-modules` command.
<InstallSection
  packageName="expo"
  cmd={[
    '# Install and configure the expo package automatically',
    '$ npx install-expo-modules@latest',
  ]}
  hideBareInstructions
/>
*  命令成功后，你将能够在应用中添加任何 Expo 模块！请前往 [用法](#usage) 了解更多信息。
  ¥<YesIcon small /> **When the command succeeds**, you will be able to add any Expo module in your
  app! Proceed to [Usage](#usage) for more information.
*  如果命令失败，请按照手动安装说明进行操作。以编程方式更新代码可能很棘手，如果你的项目与默认的 React Native 项目有很大偏差，那么你需要执行手动安装并将此处的说明调整为你的代码库。
  ¥<NoIcon small /> **If the command fails**, follow the manual installation instructions. Updating
  code programmatically can be tricky, and if your project deviates significantly from a default
  React Native project, then you need to perform manual installation and adapt the instructions here
  to your codebase.
<a id="manual-installation"></a>
## 手动安装
¥Manual installation
以下说明适用于在 React Native 0.79 中安装最新版本的 Expo 模块。对于以前的版本，请查看 [原生升级助手](/bare/upgrade) 以了解如何自定义这些文件。
¥The following instructions apply to installing the latest version of Expo modules in React Native 0.79. For previous versions, check the [native upgrade helper](/bare/upgrade) to see how these files are customized.
<InstallSection packageName="expo" cmd={['$ npm install expo']} hideBareInstructions />
安装完成后，应用以下差异中的更改来配置项目中的 Expo 模块。这预计需要大约五分钟，你可能需要根据项目的定制程度稍作调整。
¥Once installation is complete, apply the changes from the following diffs to configure Expo modules in your project. This is expected to take about five minutes, and you may need to adapt it slightly depending on how customized your project is.
<a id="configuration-for-android"></a>
### 安卓配置
¥Configuration for Android
<DiffBlock source="/static/diffs/expo-android.diff" />
<a id="configuration-for-ios"></a>
### iOS 配置
¥Configuration for iOS
<DiffBlock source="/static/diffs/expo-ios.diff" />
你也可以选择向 AppDelegate.swift 文件添加其他委托方法。有些库可能需要它们，因此除非你有充分的理由将它们排除在外，否则建议添加它们。[查看 AppDelegate.swift 中的委托方法](https://github.com/expo/expo/blob/sdk-53/templates/expo-template-bare-minimum/ios/HelloWorld/AppDelegate.swift#L24-L42)。
¥Optionally, you can also add additional delegate methods to your **AppDelegate.swift**. Some libraries may require them, so unless you have a good reason to leave them out, it is recommended to add them. [See delegate methods in AppDelegate.swift](https://github.com/expo/expo/blob/sdk-53/templates/expo-template-bare-minimum/ios/HelloWorld/AppDelegate.swift#L24-L42).
保存所有更改并将 Xcode 中的 iOS 部署目标更新为 `iOS 15.1`：
¥Save all of your changes and update your iOS Deployment Target in Xcode to `iOS 15.1`:
* 在 Xcode 中打开 your-project-name.xcworkspace，在左侧边栏中选择你的项目。
  ¥Open **your-project-name.xcworkspace** in Xcode, select your project in the left sidebar.
* 选择目标 > 你的项目名称 > 构建设置 > iOS 部署目标并将其设置为 `iOS 15.1`。
  ¥Select **Targets** > **your-project-name** > **Build Settings** > **iOS Deployment Target** and set it to `iOS 15.1`.
最后一步是再次安装项目的 CocoaPods，以引入由我们添加到 Podfile 中的 `use_expo_modules!` 指令检测到的 Expo 模块：
¥The last step is to install the project's CocoaPods again to pull in Expo modules that are detected by `use_expo_modules!` directive that we added to the **Podfile**:
<InstallSection
  packageName="expo"
  cmd={[
    '# Install pods',
    '$ npx pod-install',
    '',
    '# Alternatively, the run command will install them for you',
    '$ npx expo run:ios',
  ]}
  hideBareInstructions
/>
<a id="configure-expo-cli-for-bundling-on-android-and-ios"></a>
### 配置 Expo CLI 以在 Android 和 iOS 上进行打包
¥Configure Expo CLI for bundling on Android and iOS
我们建议使用 Expo CLI 和相关工具配置来打包你的应用 JavaScript 代码和资源。这增加了对使用 package.json 中的 `"main"` 字段来使用 [Expo 路由](/router/introduction/) 库的支持。不使用 Expo CLI 进行打包可能会导致意外行为。[了解有关 Expo CLI 的更多信息](/bare/using-expo-cli/)。
¥We recommend using Expo CLI and related tooling configurations to bundle your app JavaScript code and assets. This adds support for using the `"main"` field in **package.json** to use [Expo Router](/router/introduction/) library. Not using Expo CLI for bundling may result in unexpected behavior. [Learn more about Expo CLI](/bare/using-expo-cli/).
Note: Use babel-preset-expo in your babel.config.js
---
  <DiffBlock source="/static/diffs/babel-config.diff" />
---
Note: Extend expo/metro-config in your metro.config.js
---
  <DiffBlock source="/static/diffs/metro-config.diff" />
---
Note: Configure Android project to bundle with Expo CLI
---
  <DiffBlock source="/static/diffs/expo-cli-android.diff" />
---
Note: Configure iOS project to bundle with Expo CLI
---
Replace the shell script under **Build Phases** > **Bundle React Native code and images** in Xcode with the following:
```sh /bin/sh
if [[ -f "$PODS_ROOT/../.xcode.env" ]]; then
  source "$PODS_ROOT/../.xcode.env"
fi
if [[ -f "$PODS_ROOT/../.xcode.env.local" ]]; then
  source "$PODS_ROOT/../.xcode.env.local"
fi
# The project root by default is one level up from the ios directory
export PROJECT_ROOT="$PROJECT_DIR"/..
if [[ "$CONFIGURATION" = *Debug* ]]; then
  export SKIP_BUNDLING=1
fi
if [[ -z "$ENTRY_FILE" ]]; then
  # Set the entry JS file using the bundler's entry resolution.
  export ENTRY_FILE="$("$NODE_BINARY" -e "require('expo/scripts/resolveAppEntry')" "$PROJECT_ROOT" ios relative | tail -n 1)"
fi
if [[ -z "$CLI_PATH" ]]; then
  # Use Expo CLI
  export CLI_PATH="$("$NODE_BINARY" --print "require.resolve('@expo/cli')")"
fi
if [[ -z "$BUNDLE_COMMAND" ]]; then
  # Default Expo CLI command for bundling
  export BUNDLE_COMMAND="export:embed"
fi
`"$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'"`
```
And add support the `"main"` field in **package.json** by making the following change to **AppDelegate.swift**:
```diff AppDelegate.swift
   override func bundleURL() -> URL? {
 #if DEBUG
-    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: ".expo/.virtual-metro-entry")
 #else
     Bundle.main.url(forResource: "main", withExtension: "jsbundle")
 #endif
```
---
<a id="usage"></a>
## 用法
¥Usage
<a id="verifying-installation"></a>
### 验证安装
¥Verifying installation
你可以通过记录 [`expo-constants`](/versions/latest/sdk/constants) 中的值来验证安装是否成功。
¥You can verify that the installation was successful by logging a value from [`expo-constants`](/versions/latest/sdk/constants).
* 运行 `npx expo install expo-constants`
  ¥Run `npx expo install expo-constants`
* 然后，运行 `npx expo run` 并修改你的应用 JavaScript 代码以添加以下内容：
  ¥Then, run `npx expo run` and modify your app JavaScript code to add the following:
```js
import Constants from 'expo-constants';
console.log(Constants.systemFonts);
```
<a id="using-expo-sdk-packages"></a>
### 使用 Expo SDK 包
¥Using Expo SDK packages
在项目中安装并配置 `expo` 包后，你可以使用 `npx expo install` 从 SDK 添加任何其他 Expo 模块。请参阅 [使用库](/workflow/using-libraries) 了解更多信息。
¥Once the `expo` package is installed and configured in your project, you can use `npx expo install` to add any other Expo module from the SDK. See [Using Libraries](/workflow/using-libraries) for more information.
<a id="expo-modules-included-in-the-expo-package"></a>
### `expo` 包中包含 Expo 模块
¥Expo modules included in the `expo` package
以下 Expo 模块作为 `expo` 包的依赖引入：
¥The following Expo modules are brought in as dependencies of the `expo` package:
* [`expo-application`](/versions/latest/sdk/application) - 在开发中的远程日志记录中生成安装 ID。该模块是可选的，如果你不使用 `expo-dev-client`，则可以安全地删除该模块。
  ¥[`expo-application`](/versions/latest/sdk/application) - Generates the installation id in remote logging in development. This module is optional and can be safely removed if you do not use `expo-dev-client`.
* [`expo-asset`](/versions/latest/sdk/asset) - 围绕 `expo-file-system` 构建的纯 JavaScript 包，为所有 Expo 模块的资源提供通用基础。
  ¥[`expo-asset`](/versions/latest/sdk/asset) - A JavaScript-only package that builds around `expo-file-system` and provides a common foundation for assets across all Expo modules.
* [`expo-constants`](/versions/latest/sdk/constants) - 提供对清单的访问。
  ¥[`expo-constants`](/versions/latest/sdk/constants) - Provides access to the manifest.
* [`expo-file-system`](/versions/latest/sdk/filesystem) - 与设备文件系统交互。被 `expo-asset` 和许多其他 Expo 模块使用。通常由开发者在应用代码中直接使用。
  ¥[`expo-file-system`](/versions/latest/sdk/filesystem) - Interact with the device file system. Used by `expo-asset` and many other Expo modules. Commonly used directly by developers in application code.
* [`expo-font`](/versions/latest/sdk/font) - 在运行时加载字体。然而，该模块是可选的，可以安全地删除；如果你使用 `expo-dev-client` 进行开发并且 `@expo/vector-icons` 需要它，则建议使用。
  ¥[`expo-font`](/versions/latest/sdk/font) - Load fonts at runtime. This module is optional and can be safely removed, however; it is recommended if you use `expo-dev-client` for development and it is required by `@expo/vector-icons`.
* [`expo-keep-awake`](/versions/latest/sdk/keep-awake) - 防止你的设备在开发应用时进入睡眠状态。该模块是可选的，可以安全地删除。
  ¥[`expo-keep-awake`](/versions/latest/sdk/keep-awake) - Prevents your device from going to sleep while developing your app. This module is optional and can be safely removed.
要排除任何这些模块，请参阅以下有关 [从自动链接中排除模块](#excluding-specific-modules-from-autolinking) 的指南。
¥To exclude any of these modules, refer to the following guide on [excluding modules from autolinking](#excluding-specific-modules-from-autolinking).
<a id="excluding-specific-modules-from-autolinking"></a>
### 从自动链接中排除特定模块
¥Excluding specific modules from autolinking
如果你需要从你未使用但由其他依赖安装的 Expo 模块中排除原生代码，则可以使用 package.json 中的 [`expo.autolinking.exclude`](/modules/autolinking/#exclude) 属性：
¥If you need to exclude native code from Expo modules you are not using, but were installed by other dependencies, you can use the [`expo.autolinking.exclude`](/modules/autolinking/#exclude) property in **package.json**:
```json package.json
{
  "name": "...",
  "dependencies": {},
  "expo": {
    "autolinking": {
      "exclude": ["expo-keep-awake"]
    }
  }
}
```


## 从 React Native CLI 迁移到 Expo CLI

了解如何将任何 React Native 项目从 React Native CLI (@react-native-community/cli) 迁移到 Expo CLI。

要从 React Native CLI (`npx @react-native-community/cli@latest init`) 迁移到 Expo CLI，你需要安装 `expo` 包，其中包括 Expo Modules API 和 Expo CLI。本指南介绍了安装步骤、使用 Expo CLI 的优点以及迁移到 Expo CLI 后如何编译和运行项目。
¥To migrate from React Native CLI (`npx @react-native-community/cli@latest init`) to Expo CLI, you'll need to install the `expo` package, which includes the Expo Modules API and Expo CLI. This guide covers the installation step, the benefits of using Expo CLI, and how to compile and run your project after migrating to Expo CLI.
强烈建议在使用其他 Expo 工具时使用 Expo CLI。许多工具都需要它，例如 EAS Update、Expo Router 和 expo-dev-client，如果没有它，其他功能可能无法正常工作。
¥It is strongly recommended to use Expo CLI when using other Expo tools. It is required for many tools, such as EAS Update, Expo Router, and expo-dev-client, and other features may not work as well without it.
<a id="install-the-expo-package"></a>
## 安装 `expo` 包
¥Install the `expo` package
在大多数情况下，你只需在项目目录中执行以下命令即可安装包：
¥In most cases, executing the following command in a project directory to install the package is all you need to do:
```sh
$ npx install-expo-modules@latest
```
详细安装指南请参见 [安装 Expo 模块](/bare/installing-expo-modules)。
¥For a detailed installation guide, see [Install Expo modules](/bare/installing-expo-modules).
<a id="why-expo-cli-instead-of-react-native-cli"></a>
## 为什么选择 Expo CLI 而不是 React Native CLI
¥Why Expo CLI instead of React Native CLI
与 `@react-native-community/cli` 中的类似命令相比，Expo CLI 命令具有多项优势，其中包括：
¥Expo CLI commands provide several benefits over the similar commands in `@react-native-community/cli`, which includes:
* 通过 <kbd>j</kbd> 按键即时访问 Hermes 调试器。
  ¥Instant access to Hermes debugger with <kbd>j</kbd> keystroke.
* 调试器随 [React Native DevTools](/debugging/tools/#debugging-with-react-native-devtools) 一起提供。
  ¥The debugger ships with [React Native DevTools](/debugging/tools/#debugging-with-react-native-devtools).
* [持续的原生生成 (CNG)](/workflow/continuous-native-generation/) 支持 [`expo prebuild`](/workflow/prebuild/)，用于升级、白色标签、轻松的第三方包设置以及更好的代码库可维护性（通过减少表面积）。
  ¥[Continuous Native Generation (CNG)](/workflow/continuous-native-generation/) support with [`expo prebuild`](/workflow/prebuild/) for upgrades, white-labeling, easy third-party package setup, and better maintainability of the codebase (by reducing the surface area).
* 支持 [`expo-router`](/router/introduction/) 的基于文件的路由。
  ¥Support for file-based routing with [`expo-router`](/router/introduction/).
  * [异步打包](/router/reference/async-routes) 正在开发中。
    ¥[Async bundling](/router/reference/async-routes) in development.
* 内置 [环境变量支持](/guides/environment-variables) 和 .env 文件集成。
  ¥Built-in [environment variable support](/guides/environment-variables) and **.env** file integration.
* 直接在终端中查看原生日志以及 JavaScript 日志。
  ¥View native logs directly in the terminal alongside JavaScript logs.
* 使用专为 React Native 应用构建的 Expo CLI 的 `xcpretty` 风格工具改进了原生构建日志格式。例如，在编译 Pod 时，你可以看到哪个 Node 模块包含了它。
  ¥Improved native build log formatting using Expo CLI's `xcpretty`-style tool built specifically for React Native apps. For example, when compiling a Pod, you can see which Node module included it.
* [一流的 TypeScript 支持](/guides/typescript)。
  ¥[First-class TypeScript support](/guides/typescript).
* 支持 tsconfig.json 别名为 `paths` 和 `baseUrl` [内置于 Metro](/guides/typescript/#path-aliases-optional)。
  ¥Support for **tsconfig.json** aliases with `paths` and `baseUrl` [built-in to Metro](/guides/typescript/#path-aliases-optional).
* [Web 支持](/guides/customizing-metro/#adding-web-support-to-metro) 与 Metro。针对 React Native Web 的完全类型化。
  ¥[Web support](/guides/customizing-metro/#adding-web-support-to-metro) with Metro. Fully typed for React Native Web.
* 现代 [CSS 支持](/versions/latest/config/metro#css) 带有 Tailwind、PostCSS、CSS 模块、SASS 等。
  ¥Modern [CSS support](/versions/latest/config/metro#css) with Tailwind, PostCSS, CSS Modules, SASS, and more.
* 使用 Expo Router 和 Metro web 生成静态站点。
  ¥Static site generation with Expo Router and Metro web.
* 开箱即用 [支持单一仓库](/guides/monorepos)。
  ¥Out of the box [support for monorepos](/guides/monorepos).
* 支持 [`expo-dev-client`](/develop/development-builds/introduction)、[Expo 更新协议](/technical-specs/expo-updates-1) 和 [EAS 更新](/eas-update/introduction) 等 Expo 工具。
  ¥Support for Expo tooling such as [`expo-dev-client`](/develop/development-builds/introduction), the [Expo Updates protocol](/technical-specs/expo-updates-1) and [EAS Update](/eas-update/introduction).
* 使用 `npx expo run:ios` 时自动执行 `pod install`。
  ¥Automated `pod install` execution when using `npx expo run:ios`.
* `npx expo install` 为众所周知的包选择兼容的依赖版本。
  ¥`npx expo install` selects compatible dependency versions for well-known packages.
* 运行 `npx expo run:[android|ios]` 和 `npx expo start` 时自动端口检测。如果另一个应用正在默认端口上运行，则会使用不同的端口。
  ¥Automatic port detection when running `npx expo run:[android|ios]` and `npx expo start`. If another app is running on the default port, a different port is used.
* Android 或 iOS 设备在交互式提示中使用 <kbd>Shift</kbd> + <kbd>a</kbd> 或 <kbd>Shift</kbd> + <kbd>i</kbd> 启动选择快捷方式。
  ¥Android or iOS device launch selection shortcuts using <kbd>Shift</kbd> + <kbd>a</kbd> or <kbd>Shift</kbd> + <kbd>i</kbd> from the interactive prompt.
* 内置支持通过 [恩格罗克隧道](/develop/development-builds/development-workflows/#tunnel-urls) 为你的应用提供服务。
  ¥Built-in support for serving your app over an [ngrok tunnel](/develop/development-builds/development-workflows/#tunnel-urls).
* 使用任何入口 JavaScript 文件在任何端口上进行开发。
  ¥Develop on any port with any entry JavaScript file.
对于大多数面向 Android、iOS 和/或 Web 的 React Native 项目，我们建议使用 Expo CLI。它尚未内置对最流行的树外平台（例如 Windows 和 macOS）的支持。如果针对这些平台进行构建，你可以对支持的平台使用 Expo CLI，对其他平台使用 `@react-native-community/cli`。
¥We recommend Expo CLI for most React Native projects that target Android, iOS, and/or web. It does not yet have built-in support for the most popular out-of-tree platforms, such as
Windows and macOS. If building for these platforms, you can utilize Expo CLI for the supported platforms and `@react-native-community/cli` for the others.
<a id="compile-and-run-your-app"></a>
## 编译并运行你的应用
¥Compile and run your app
安装 `expo` 软件包后，你可以使用以下命令替代 `npx react-native run-android` 和 `npx react-native run-ios`：
¥After installing the `expo` package, you can use the following commands which are alternatives to `npx react-native run-android` and `npx react-native run-ios`:
```sh
$ npx expo run:android
$ npx expo run:ios
```
构建项目时，你可以使用 `--device` 标志选择设备或模拟器。这也适用于连接到你的计算机的任何 iOS 设备。
¥When building your project, you can choose a device or simulator by using the `--device` flag. This also applies to any iOS device that is connected to your computer.
<a id="start-the-bundler-independently"></a>
## 独立启动打包器
¥Start the bundler independently
`npx expo run:[android|ios]` 自动启动打包器/开发服务器。如果你想使用 `npx expo start` 命令独立启动打包程序，请将 `--no-bundler` 传递给 `npx expo run:[android|ios]` 命令。
¥`npx expo run:[android|ios]` automatically starts the bundler/development server. If you want to independently start the bundler with `npx expo start` command, pass the `--no-bundler` to the `npx expo run:[android|ios]` command.
<a id="common-questions"></a>
## 常见问题
¥Common questions
Note: Can I use Expo CLI without installing the Expo Modules API?
---
Expo Modules API is also installed when you install the `expo` package with `npx install-expo-modules`. If you want to try out Expo CLI for now without installing Expo Modules API, install the `expo` package with `npm install` and then configure the **react-native.config.js** to exclude the package from autolinking:
```js react-native.config.js
module.exports = {
  dependencies: {
    expo: {
      platforms: {
        android: null,
        ios: null,
        macos: null,
      },
    },
  },
};
```
> **Note:** Without Expo API Modules installed, certain features such as `expo-dev-client` or `expo-router` are unavailable.
---
Note: Can I use prebuild for out-of-tree platforms, such as macOS or Windows?
---
Yes! Refer to the [Customized Prebuild Example repository](https://github.com/byCedric/custom-prebuild-example) for more information.
---
<a id="next-steps"></a>
## 下一步
¥Next steps
现在，在你的项目中安装和配置 `expo` 软件包后，你可以开始使用 Expo CLI 和 SDK 中的所有功能。以下是一些建议的后续深入研究步骤：
¥Now, with the `expo` package installed and configured in your project, you can start using all features from Expo CLI and SDK. Here are some recommended next steps to dive deep:


## 在现有 React Native 项目中安装 expo-updates

了解如何在现有的 React Native 项目中安装和配置 expo-updates。

`expo-updates` 是一个库，可让你的应用管理对应用代码的远程更新。它与配置的远程更新服务通信以获取有关可用更新的信息。本指南介绍如何设置一个裸 React Native 项目以用于 [EAS 更新](/eas-update/introduction)，[EAS 更新](/eas-update/introduction) 是一种托管远程更新服务，其中包括用于简化 `expo-updates` 库安装和配置的工具。
¥`expo-updates` is a library that enables your app to manage remote updates to your application code. It communicates with the configured remote update service to get information about available updates. This guide explains how to set up a bare React Native project for use with [EAS Update](/eas-update/introduction), a hosted remote update service that includes tools to simplify installation and configuration of the `expo-updates` library.
Note: Do you use Continuous Native Generation (CNG) in your project?
---
You may be reading the wrong guide. To use `expo-updates` in a project that uses [CNG](/workflow/continuous-native-generation/), see [EAS Update "Get started"](/eas-update/getting-started/).
---
## Prerequisites
**The `expo` package must be installed and configured.** If you created your project with `npx @react-native-community/cli@latest init` and do not have any other Expo libraries installed, you will need to [install Expo modules](/bare/installing-expo-modules) before proceeding.
## Installation
To get started, install `expo-updates`:
```sh
$ npx expo install expo-updates
```
Then, install pods for iOS:
```sh
$ npx pod-install
```
## Configuring expo-updates library
Apply the changes from the diffs from the following sections to configure `expo-updates` in your project.
### JavaScript and JSON
Run `eas update:configure` to set the `updates` URL and `projectId` in **app.json**.
```sh
$ eas update:configure
```
Modify the `expo` section of **app.json**. If you created your project using `npx @react-native-community/cli@latest init`, you will need to add the following changes including the [`updates` URL](/versions/latest/config/app/#url).
> The example `updates` URL and `projectId` shown below are used with EAS Update. The EAS CLI sets this URL correctly for the EAS Update service when running `eas update:configure`.
<DiffBlock source="/static/diffs/expo-updates-app-json.diff" />
If you want to set up a [custom `expo-updates` server](https://github.com/expo/custom-expo-updates-server) instead, add your URL to `updates.url` in **app.json**.
```diff app.json
 {
   "name": "MyApp",
   "displayName": "MyApp",
   "expo": {
     "name": "MyApp",
      ...
     "updates": {
-      "url": "https://u.expo.dev/[your-project-id]"
+      "url": "http://localhost:3000/api/manifest"
     }
   }
 }
```
### Android
Modify **android/app/build.gradle** to check for the JS engine configuration (JSC or Hermes) in Expo files:
<DiffBlock source="/static/diffs/expo-updates-android-build-gradle.diff" />
Modify **android/app/src/main/AndroidManifest.xml** to add the `expo-updates` configuration XML so that it matches the contents of **app.json**:
<DiffBlock source="/static/diffs/expo-updates-android-manifest.diff" />
If using the updates server URL (a custom non-HTTPS update server running on the same machine), you will need to modify **android/app/src/main/AndroidManifest.xml** to add the update server URL and enable `usesCleartextTraffic`:
```diff android/app/src/main/AndroidManifest.xml
 <application
  android:name=".MainApplication"
  android:label="@string/app_name"
  android:icon="@mipmap/ic_launcher"
  android:roundIcon="@mipmap/ic_launcher_round"
  android:allowBackup="false"
  android:theme="@style/AppTheme"
+ android:usesCleartextTraffic="true"
 >
- <meta-data android:name="expo.modules.updates.EXPO_UPDATE_URL" android:value="https://u.expo.dev/[your-project-id]"/>
+ <meta-data android:name="expo.modules.updates.EXPO_UPDATE_URL" android:value="http://localhost:3000/api/manifest"/>
 </application>
```
Add the Expo runtime version string key to **android/app/src/main/res/values/strings.xml**:
<DiffBlock source="/static/diffs/expo-updates-strings-xml.diff" />
### iOS
Add the file **Podfile.properties.json** to the **ios** directory:
```json ios/Podfile.properties.json
{
  "expo.jsEngine": "hermes"
}
```
Modify **ios/Podfile** to check for the JS engine configuration (JSC or Hermes) in Expo files:
<DiffBlock source="/static/diffs/expo-updates-ios-podfile.diff" />
使用 Xcode，将 Expo.plist 文件添加到 ios/your-project/Supporting，内容如下，以匹配 app.json 的内容：
¥Using Xcode, add **Expo.plist** file to **ios/your-project/Supporting** with the following content to match the contents of **app.json**:
```xml Expo.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>EXUpdatesCheckOnLaunch</key>
    <string>ALWAYS</string>
    <key>EXUpdatesEnabled</key>
    <true/>
    <key>EXUpdatesLaunchWaitMs</key>
    <integer>0</integer>
    <key>EXUpdatesRuntimeVersion</key>
    <string>1.0.0</string>
    <key>EXUpdatesURL</key>
    <string>http://localhost:3000/api/manifest</string>
  </dict>
</plist>
```
<a id="next-steps"></a>
## 下一步
¥Next steps
* 要开始将 EAS Update 与 EAS Build 结合使用，请参阅 EAS Update [开始使用](/eas-update/getting-started/)。
  ¥To start using EAS Update with EAS Build, see the EAS Update [Get started](/eas-update/getting-started/).
* 有关如何使用该库的更多信息，请参阅 [`expo-updates` API 参考](/versions/latest/sdk/updates/)。
  ¥See [`expo-updates` API reference](/versions/latest/sdk/updates/) for more information on how to use the library.
* 了解如何使用 [直接使用本地版本进行 EAS 更新](/eas-update/standalone-service/)。
  ¥See how to use [EAS Update with a local build directly](/eas-update/standalone-service/).
* 也可以将 `expo-updates` 与实现 [Expo 更新协议](/technical-specs/expo-updates-1/) 的自定义服务器一起使用。参见 [`custom-expo-updates-server` 自述文件](https://github.com/expo/custom-expo-updates-server#readme)。
  ¥It is also possible to use `expo-updates` with a custom server that implements the [Expo Updates protocol](/technical-specs/expo-updates-1/). See [`custom-expo-updates-server` README](https://github.com/expo/custom-expo-updates-server#readme).


## 在现有 React Native 项目中安装 expo-dev-client

了解如何在现有的 React Native 项目中安装和配置 expo-dev-client。

以下指南介绍了如何在现有 React Native 项目中安装和配置 `expo-dev-client`。
¥The following guide explains how to install and configure `expo-dev-client` in an existing React Native project.
Note: Do you need to create a new project?
---
If you're starting with a new project, create it using the `with-dev-client` template:
```sh
$ npx create-expo-app -e with-dev-client
```
---
Note: Do you use Continuous Native Generation (CNG) in your project?
---
To use `expo-dev-client` in a project that uses [CNG](/workflow/continuous-native-generation/), see [Create a development build](/develop/development-builds/create-a-build/).
---
## Prerequisites
**The `expo` package must be installed and configured.** If you created your project with `npx @react-native-community/cli@latest init` and do not have any other Expo libraries installed, you will need to [install Expo modules](/bare/installing-expo-modules) before proceeding.
Step 1: 
## Install expo-dev-client
Add the `expo-dev-client` library to your **package.json**:
```sh
$ npx expo install expo-dev-client
```
If your project has an **ios** directory on disk, run the following command to fully install the native code for `expo-dev-client`:
```sh
$ npx pod-install
```
If your project doesn't have an **ios** directory, you can skip this step.
Step 2: 
## Configure deep links
Expo CLI uses a deep link to launch your project, and it's also useful if you use plan to [use `expo-dev-client` for launching preview updates](/eas-update/getting-started/) if you have added a custom deep link scheme to your project.
If you haven't configured a `scheme` for your app yet to support deep linking, then use `uri-scheme` library to do this for you.
```sh
$ npx uri-scheme list
$ npx uri-scheme add your-scheme
```
For more information, see the [`uri-scheme` library](https://www.npmjs.com/package/uri-scheme).
Step 3: 
## Add additional optional configuration
For certain types of errors, you can obtain more helpful error messages when using `expo-dev-client`. To turn this on, import `expo-dev-client` in the project's **index** file. Make sure that the import statement is executed early, before your application's JS code is imported (place the import above `import App from './App'`).
!!!IG0!!!
For more information, see [Error handling](/develop/development-builds/use-development-builds/#add-error-handling).
Step 4: 
## Build and install the app
Create a debug build of your app using the tools of your choice. For example, you can do this [locally with Expo CLI](/guides/local-app-development/) or [in the cloud with EAS Build](/develop/development-builds/create-a-build/).


## 原生项目升级助手

查看你需要对原生项目进行的所有更改的逐个文件差异，以将其升级到下一个 Expo SDK 版本。

如果你管理你的原生项目（以前称为裸工作流），到 [升级到最新的 Expo SDK](/workflow/upgrading-expo-sdk-walkthrough/)，你必须对你的原生项目进行更改。查找哪些原生文件发生更改以及要更新哪个文件中的内容可能是一个复杂的过程。
¥If you manage your native projects (previously known as bare workflow), to [upgrade to the latest Expo SDK](/workflow/upgrading-expo-sdk-walkthrough/), you have to make changes to your native projects. It can be a complex process to find which native file changes and what to update in which file.
以下指南提供了比较项目当前 SDK 版本和要升级的目标 SDK 版本之间的原生项目文件的差异。你可以使用它们根据你的项目使用的 `expo` 软件包版本对你的项目进行更改。此页面上的工具与 [React Native 升级助手](https://react-native-community.github.io/upgrade-helper/) 类似。然而，它们面向使用 Expo 模块和相关工具的项目。
¥The following guide provides diffs to compare native project files between your project's current SDK version and the target SDK version you want to upgrade. You can use them to make changes to your project depending on the `expo` package version your project uses. The tools on this page are similar to [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/). However, they are oriented around projects that use Expo modules and related tooling.
> 有兴趣完全避免升级原生代码吗？请参阅 [持续的原生生成 (CNG)](/workflow/continuous-native-generation/) 了解 Expo Prebuild 如何在构建之前生成你的原生项目。
>
> ¥Interested in avoiding upgrading native code altogether? See [Continuous Native Generation (CNG)](/workflow/continuous-native-generation/) to learn how Expo Prebuild can generate your native projects before a build.
<a id="upgrade-native-project-files"></a>
## 升级原生项目文件
¥Upgrade native project files
一旦你拥有 [升级你的 Expo SDK 版本和相关依赖](/workflow//upgrading-expo-sdk-walkthrough/#how-to-upgrade-to-the-latest-sdk-version)，请使用下面的 diff 工具来了解你需要对原生项目进行的更改，并将其更新为当前的 Expo SDK 版本。
¥Once you have [upgraded your Expo SDK version and related dependencies](/workflow//upgrading-expo-sdk-walkthrough/#how-to-upgrade-to-the-latest-sdk-version), use the diff tool below to learn about changes you need to make to your native project and bring them up to date with the current Expo SDK version.
选择你的 SDK 版本和 SDK 版本以查看生成的差异。然后，通过复制和粘贴或手动更改项目文件，将这些更改应用到你的原生项目。
¥Choose your **from SDK version** and **to SDK version** to see the generated diff. Then, apply those changes to your native projects by copying and pasting or manually making changes to the project files.
<TemplateBareMinimumDiffViewer />


# 现有的原生应用

## 将 Expo 工具集成到现有的原生应用中

概述如何将 Expo 工具集成到现有原生应用 ("brownfield" 应用) 中。

使用其他技术构建的现有原生应用，其主要入口点不是 React Native 视图，通常称为 "brownfield" 应用。例如，如果你的应用是使用 UIKit 和 Swift 构建的，并且你想在单个屏幕上使用 React Native，那么这将被视为 "现有的原生应用" 和 "brownfield"。
¥An existing native app that was built using another technology, whose main entry point is *not* a React Native view, is commonly referred to as a "brownfield" app. For example, if your app was built using UIKit and Swift, and you want to use React Native for a single screen then that is considered an "existing native app" and "brownfield".
相比之下，"greenfield" 应用从一开始就使用 Expo 或 React Native 创建，或者 React Native 是入口点，所有其他 UI 都从这里分支。
¥In contrast, "greenfield" apps are created using Expo or React Native from the start or where React Native is the entry point and where all other UI branches off from.
根据这些定义，如果你有适用于 Android 或 iOS 的 "现有的原生应用"，并且想要学习如何在项目中使用 Expo 和 React Native（可能在单个屏幕上，甚至单个功能上），那么本指南适合你。
¥By these definitions, if you have an "existing native app" for Android or iOS and you want to learn how to use Expo and React Native in your project (perhaps on a single screen or even a single feature), then this guide is for you.
<a id="compatibility-with-existing-native-apps"></a>
## 与现有原生应用的兼容性
¥Compatibility with existing native apps
>  **info** 将 Expo 模块集成到现有原生项目的支持仍处于试验阶段。如果你遇到问题，[在 GitHub 上创建问题](https://github.com/expo/expo/issues)。在现有原生应用环境中使用时，以下工具和服务的某些功能并非全部可用。
>
> ¥Support for integrating Expo modules into existing native projects is still experimental. If you encounter issues, [create an issue on GitHub](https://github.com/expo/expo/issues). Not all features of the tools and services below will be available when used in the context of an existing native app.
Expo 主要为绿地应用而构建，但我们越来越多地投资于棕地场景。并非所有 Expo 工具和服务都与现有的原生项目兼容。此外，棕地集成的全面文档可能尚未提供，你可能需要根据你的情况调整其他相关文档。
¥Expo is primarily built with greenfield apps in mind, but we are increasingly investing in brownfield scenarios. Not all Expo tools and services are compatible with existing native projects yet. Additionally, comprehensive documentation for brownfield integrations may not yet available, and you may need to adapt other related documentation to your context.
| 工具/服务                                                                  | 支持 brownfield？ |
| ---------------------------------------------------------------------- | -------------- |
| [Expo SDK](/versions/latest/) - React Native 的扩展标准库                    | 是              |
| [Expo 模块 API](/modules/overview/) - 使用惯用的 Swift/Kotlin API 构建原生扩展      | 是              |
| [Expo 路由](/router/introduction/) - 基于文件的路由和导航                          | 否              |
| [Expo CLI](/more/expo-cli/) - 从终端运行和开发应用的工具                            | 否              |
| [Expo 开发客户端](/versions/latest/sdk/dev-client/) - 将应用内开发者工具添加到 Debug 版本 | 否              |
| [EAS 构建](/build/introduction/) - 专为 Expo/React Native 构建的 CI/CD 服务     | 是              |
| [EAS 提交](/submit/introduction/) - 将你的应用上传到商店的托管服务                      | 是              |
| [EAS 更新](/eas-update/introduction/) - 即时更新你的应用 JavaScript 和资源          | 是              |
<a id="next-steps"></a>
## 下一步
¥Next steps


## 在现有的原生项目中安装 Expo 模块

了解如何准备你现有的原生项目以安装和使用 Expo 模块和模块 API。

>  **info** 如果你的项目是一个全新的 React Native 应用 — 从一开始就主要使用 React Native 构建，那么请参阅 [在现有的 React Native 项目中安装 Expo 模块](/bare/installing-expo-modules/) 而不是本指南。
>
> ¥If your project is a **greenfield React Native app** — primarily built with React Native from the start, then see [Install Expo modules in an existing React Native project](/bare/installing-expo-modules/) instead of this guide.
本指南提供了准备现有原生项目以安装和使用 Expo 模块和模块 API 的步骤。
¥This guide provides the steps to prepare your existing native project to install and use Expo modules and the module API.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
>  **important** 以下说明可能不适用于所有项目。将 Expo 模块集成到现有项目的支持仍处于试验阶段。如果你遇到问题，[在 GitHub 上创建问题](https://github.com/expo/expo/issues)。
>
> ¥The following instructions may not work for all projects. Support for integrating Expo modules into existing projects is still experimental. If you encounter issues, [create an issue on GitHub](https://github.com/expo/expo/issues).
你应该有一个安装并配置了 React Native 的棕地原生项目来渲染根视图。如果你还没有这个，请按照 React Native 文档中的 [与现有应用集成](https://rn.nodejs.cn/docs/integration-with-existing-apps) 指南进行操作，然后在完成步骤后返回此处。
¥You should have a brownfield native project with React Native installed and configured to render a root view. If you don't have this yet, follow the [Integration with Existing Apps](https://rn.nodejs.cn/docs/integration-with-existing-apps) guide from the React Native documentation and then come back here once you have followed the steps.
<a id="install-the-expo-package"></a>
## 安装 `expo` 包
¥Install the `expo` package
将 `expo` 包添加到你的项目中。确保你使用的是 [与你项目中的 React Native 版本兼容的 `expo` 包](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version) 版本。
¥Add the `expo` package to your project. Ensure you are using a version of [the `expo` package that is compatible with the React Native version in your project](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version).
```sh
$ npm install expo
```
<a id="configuring-native-apps"></a>
## 配置原生应用
¥Configuring native apps
<a id="android-app"></a>
### Android 应用
¥Android app
Step 1: 
Add the following to the **gradle.properties** file in the **android** directory:
```diff
diff --git a/android/gradle.properties b/android/gradle.properties
index 20e2a01..e98ad88 100644
--- a/android/gradle.properties
+++ b/android/gradle.properties
@@ -20,4 +20,8 @@ kotlin.code.style=official
+newArchEnabled=true
+
+hermesEnabled=true
```
Step 2: 
Add the following to the **setting.gradle** file in the **android** directory:
```diff
diff --git a/android/settings.gradle b/android/settings.gradle
index a26c7c6..dd8802a 100644
--- a/android/settings.gradle
+++ b/android/settings.gradle
@@ -1,5 +1,11 @@
+apply from: new File(["node", "--print", "require.resolve('expo/package.json')"].execute(null, rootDir).text.trim(), "../scripts/autolinking.gradle");
+useExpoModules()
+
 include ':app'
 includeBuild("../node_modules/@react-native/gradle-plugin")
```
Step 3: 
Inside the **android** directory, run the following command:
```sh
$ ./gradlew clean
```
Once the above command completes, run:
```sh
$./gradlew assembleDebug
```
Step 4: 
**(Optional)** Complete the following steps if you would like to use [lifecycle listeners](/modules/android-lifecycle-listeners/) in your app. If you do not set up lifecycle listeners, then additional setup will be required for each module that uses them.
Step 4.1: 
If you already have a class that extends the `Application` class you can move to step 3. If you do not have it, we need to create one. Add a file called **MainApplication.kt** file to your **android/app/src/main/java/com/&lt;your-app-package&gt;** directory with the following content:
```diff
diff --git a/android/app/src/main/java/com/<my-app-package>/MainApplication.kt b/android/app/src/main/java/com/<my-app-package>/MainApplication.kt
new file mode 100644
index 0000000..2c8525a
--- /dev/null
+++ b/android/app/src/main/java/com/<my-app-package>/MainApplication.kt
@@ -0,0 +1,19 @@
+package <my.app.package>
+
+import android.app.Application
+import android.content.res.Configuration
+import com.facebook.soloader.SoLoader
+import expo.modules.ApplicationLifecycleDispatcher
+
+class MainApplication() : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        ApplicationLifecycleDispatcher.onApplicationCreate(this)
+    }
+
+    override fun onConfigurationChanged(newConfig: Configuration) {
+        super.onConfigurationChanged(newConfig)
+        ApplicationLifecycleDispatcher.onConfigurationChanged(this, newConfig)
+    }
+}
```
Step 4.2: 
Register the class in the **AndroidManifest.xml** file.
```diff
diff --git a/android/app/src/main/AndroidManifest.xml b/android/app/src/main/AndroidManifest.xml
index a71b5e7..d6d406e 100644
--- a/android/app/src/main/AndroidManifest.xml
+++ b/android/app/src/main/AndroidManifest.xml
@@ -7,6 +7,7 @@
     <application
         android:allowBackup="true"
+         android:name=".MainApplication"
         android:fullBackupContent="@xml/backup_rules"
```
Step 4.3: 
If you have your own class extending `Application`, you can add the following. It includes calls to `ApplicationLifecycleDispatcher` for handling events at the application startup and during device configuration changes.
```diff
diff --git a/android/app/src/main/java/com/<my-app-package>/MainApplication.kt b/android/app/src/main/java/com/<my-app-package>/MainApplication.kt
new file mode 100644
index 0000000..2c8525a
--- /dev/null
+++ b/android/app/src/main/java/com/<my-app-package>/MainApplication.kt
@@ -0,0 +1,19 @@
class MainApplication() : Application() {
    override fun onCreate() {
        super.onCreate()
+       ApplicationLifecycleDispatcher.onApplicationCreate(this)
    }
+
+   override fun onConfigurationChanged(newConfig: Configuration) {
+       super.onConfigurationChanged(newConfig)
+       ApplicationLifecycleDispatcher.onConfigurationChanged(this, newConfig)
+   }
}
```
Override `onConfigurationChanged` if you have not done so already.
### iOS app
Step 1: 
Add the following to your `Podfile` in the **ios** directory:
```diff
diff --git a/ios/Podfile b/ios/Podfile
index f991b7b..17c24b0 100644
--- a/ios/Podfile
+++ b/ios/Podfile
@@ -1 +1,4 @@
+# Expo requires
+require File.join(File.dirname(\`node --print "require.resolve('expo/package.json')"\`), "scripts/autolinking")
+
 # Resolve react_native_pods.rb with node to allow for hoisting
@@ -17,3 +20,16 @@ end
 target '<YourAppTarget>' do
-  config = use_native_modules!()
+  # Need to be added inside the target block
+  use_expo_modules!
+
+  config_command = [
+    'node',
+    '--no-warnings',
+    '--eval',
+    'require(require.resolve("expo-modules-autolinking", { paths: [require.resolve("expo/package.json")] }))(process.argv.slice(1))',
+    'react-native-config',
+    '--json',
+    '--platform',
+    'ios'
+  ]
+  config = use_native_modules!(config_command)
```
Step 2: 
Open your **ios** directory in Xcode. From the project navigator, select your project and then select your app target under `TARGETS`. In `Build Settings`, using the search bar, search for `ENABLE_USER_SCRIPT_SANDBOXING`. If it is not already, set its value to `No`.
Step 3: 
Run `pod install` in the **ios** directory.
```sh
$ cd ios && pod install
```
You will need to do this every time you add a dependency that uses native code.
Step 4: 
**(Optional)** Complete the following if you would like to use [`AppDelegate` subscribers](/modules/appdelegate-subscribers/). If you do not set up `AppDelegate` subscribers, then additional setup will be required for each module that uses them.
```diff
diff --git a/ios/<MyAppProject>/AppDelegate.swift b/ios/<MyAppProject>/AppDelegate.swift
index ff83531..bd8651d 100644
--- a/ios/<MyAppProject>/AppDelegate.swift
+++ b/ios/<MyAppProject>/AppDelegate.swift
@@ -1,31 +1,29 @@
 import UIKit
+import ExpoModulesCore
@main
-class AppDelegate: UIResponder, UIApplicationDelegate {
+class AppDelegate: ExpoAppDelegate {
- func application(\_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+override func application(\_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
- return true
+super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
```


# Expo 路由

## Expo 路由简介

Expo Router 是一个开源路由库，适用于使用 Expo 构建的 Universal React Native 应用。

Expo Router 是一个用于 React Native 和 Web 应用的基于文件的路由。它允许你管理应用中屏幕之间的导航，允许用户在多个平台（Android、iOS 和 Web）上使用相同的组件，在应用 UI 的不同部分之间无缝移动。
¥Expo Router is a file-based router for React Native and web applications. It allows you to manage navigation between screens in your app, allowing users to move seamlessly between different parts of your app's UI, using the same components on multiple platforms (Android, iOS, and web).
它将最好的文件系统路由概念从网络引入到通用应用中 - 允许你的路由在每个平台上工作。将文件添加到应用目录后，该文件会自动成为导航中的路由。
¥It brings the best file-system routing concepts from the web to a universal application — allowing your routing to work across every platform. When a file is added to the **app** directory, the file automatically becomes a route in your navigation.
<a id="features"></a>
## 特性
¥Features
* 本国的：Expo Router 导航建立在我们强大的 [React 导航套件](https://react-navigation.nodejs.cn/) 之上，默认情况下是真正的原生和平台优化。
  ¥**Native**: Built on top of our powerful [React Navigation suite](https://react-navigation.nodejs.cn/), Expo Router navigation is truly native and platform-optimized by default.
* 可分享：应用中的每个屏幕都可以自动深度链接。使应用中的任何路由都可以通过链接共享。
  ¥**Shareable**: Every screen in your app is automatically deep linkable. Making any route in your app shareable with links.
* 离线优先：应用会被缓存并首先离线运行，并在你发布新版本时自动更新。无需网络连接或服务器即可处理所有传入的原生 URL。
  ¥**Offline-first**: Apps are cached and run offline-first, with automatic updates when you publish a new version. Handles all incoming native URLs without a network connection or server.
* 优化：通过生产中的惰性评估和开发中的延迟打包，自动优化路由。
  ¥**Optimized**: Routes are automatically optimized with lazy-evaluation in production, and deferred bundling in development.
* 迭代：跨 Android、iOS 和 Web 的通用快速刷新，以及打包器中的工件记忆，可让你大规模快速前进。
  ¥**Iteration**: Universal Fast Refresh across Android, iOS, and web, along with artifact memoization in the bundler to keep you moving fast at scale.
* 普遍的：Android、iOS 和 Web 共享统一的导航结构，能够在路由级别下拉至特定于平台的 API。
  ¥**Universal**: Android, iOS, and web share a unified navigation structure, with the ability to drop-down to platform-specific APIs at the route level.
* 可发现：Expo Router 支持在 Web 上构建时静态渲染以及与原生的通用链接。这意味着你的应用内容可以被搜索引擎索引。
  ¥**Discoverable**: Expo Router enables build-time static rendering on web, and universal linking to native. Meaning your app content can be indexed by search engines.
<a id="using-a-different-navigation-library"></a>
### 使用不同的导航库
¥Using a different navigation library
你可以在 Expo 项目中使用任何其他导航库，例如 [React 导航](https://react-navigation.nodejs.cn/docs/getting-started#installation)。但是，如果你正在构建新应用，我们建议使用 Expo Router 来实现上述所有功能。对于其他导航库，你可能必须为其中一些功能实现自己的策略，例如可共享链接或在同一项目中处理 Web 和原生导航。
¥You can use any other navigation library, like [React Navigation](https://react-navigation.nodejs.cn/docs/getting-started#installation), in your Expo project. However, if you are building a new app, **we recommend using Expo Router for all the features described above**. With other navigation libraries, you might have to implement your own strategies for some of these features, such as shareable links or handling web and native navigation in the same project.
如果你希望使用 [Wix 的 React Native Navigation](https://github.com/wix/react-native-navigation)，它在 Expo Go 中不可用，并且尚不兼容 `expo-dev-client`。我们建议使用 React Navigation 中的 [`createNativeStackNavigator`](https://react-navigation.nodejs.cn/docs/native-stack-navigator) 来使用 Android 和 iOS 原生导航 API。
¥If you are looking to use [React Native Navigation by Wix](https://github.com/wix/react-native-navigation), it is not available in Expo Go and is not yet compatible with `expo-dev-client`. We recommend using [`createNativeStackNavigator`](https://react-navigation.nodejs.cn/docs/native-stack-navigator) from React Navigation to use Android and iOS native navigation APIs.
<a id="common-questions"></a>
## 常见问题
¥Common questions
Note: Expo Router versus Expo versus React Native CLI
---
Historically, React Native has been non prescriptive about how apps should be built which is similar to using React without a modern web framework. Expo Router is an opinionated framework for React Native, similar to how Remix and Next.js are opinionated frameworks for web-only React.
Expo Router is designed to bring the best architectural patterns to everyone, to ensure React Native is leveraged to its fullest. For example, Expo Router's [Async Routes](/router/reference/async-routes) feature enables lazy bundling for everyone. Previously, lazy bundling was only used at Meta to build the Facebook app.
---
Note: Can I use Expo Router in my existing React Native app?
---
Yes, Expo Router is the framework for universal React Native apps. Due to the deep connection between the router and the bundler, Expo Router is only available in Expo CLI projects with Metro. Luckily, you can [use Expo CLI in any React Native project](/bare/using-expo-cli/) too!
---
Note: What are the benefits of file-based routing?
---
- The file system is a well-known and well-understood concept. The simpler mental model makes it easier to educate new team members and scale your application.
- The fastest way to onboard new users is by having them open a universal link that opens the app or website to the correct screen depending on if they have the app installed or not. This technique is so advanced that it's usually only available to large companies that can afford to make and maintain the parity between platforms. But with Expo's file-based routing, you can have this feature out of the box!
- Refactoring is easier to do because you can move files around without having to update any imports or routing components.
- Expo Router has the ability to statically type routes automatically. This ensures you can only link to valid routes and that you can't link to a route that doesn't exist. Typed Routes also improve refactoring as you'll get type errors if links are broken.
- Async Routes (bundle splitting) improve development speed, especially in larger projects. They also make upgrades easier as errors are isolated to a single route, meaning you can incrementally update or refactor your app page-by-page rather than all at once (traditional React Native).
- Deep links always work, for every page. This makes it possible to share links to any content in the app, which is great for promoting your app, collecting bug reports, E2E testing, automating screenshots, and so on.
- Expo Head uses automatic links to enable deep-native integration. Features like Quick Notes, Handoff, Siri context, and universal links only require configuration setup, no code changes. This enables perfect vertical integration with the entire ecosystem of smart devices that a user has, leading to the types of user experiences that are only possible with universal apps (web ⇄ native).
- Expo Router has the ability to statically render each page automatically on the web, enabling real SEO and full discoverability of your app's content. This is only possible because of the file-based convention.
- **Expo CLI** can infer a lot of information about your application when it follows a known convention. For example, we could implement automatic bundle splitting per route, or automatically generate a sitemap for your website. This is impossible when your app only has a single entry point.
- Re-engagement features like notifications and home screen widgets are easier to integrate as you can simply intercept the launch and deep link, with query parameters, anywhere in the app.
- Like on the web, analytics and error reporting can easily be configured to automatically include the route name, which is useful for debugging and understanding user behavior.
---
Note: Why should I use Expo Router over React Navigation?
---
Expo Router and React Navigation are both libraries from the Expo team. We built Expo Router on top of React Navigation to enable the benefits of file-based routing. Expo Router is a superset of React Navigation, meaning you can use any React Navigation components and APIs with Expo Router.
If file-based routing isn't right for your project, you can drop down to React Navigation and set up routes, types, and links manually.
---
Note: How do I server-render my Expo Router website?
---
Basic static rendering (SSG) is supported in Expo Router. Server-side rendering currently requires custom infrastructure to set up.
---
<a id="next-steps"></a>
## 下一步
¥Next steps


## 安装 Expo 路由

了解如何通过使用 Expo Router 创建新项目或将库添加到现有项目来快速入门。

请按照以下步骤使用 Expo Router 库创建新项目或将其添加到现有项目中。
¥Find the steps below to create a new project with Expo Router library or add it to your existing project.
<a id="quick-start"></a>
## 快速开始
¥Quick start
Step 1: 
We recommend creating a new Expo app using `create-expo-app` to create a project with Expo Router library already installed and configured:
```sh
$ npx create-expo-app@latest
```
Step 2: 
Now, you can start your project by running:
```sh
$ npx expo start
```
- To view your app on a mobile device, we recommend starting with [Expo Go](/get-started/set-up-your-environment/#how-would-you-like-to-develop). As your application grows in complexity and you need more control, you can create a [development build](/develop/development-builds/introduction/).
- Open the project in a web browser by pressing <kbd>w</kbd> in the Terminal UI. Press <kbd>a</kbd> for Android (Android Studio is required), or <kbd>i</kbd> for iOS (macOS with Xcode is required).
## Manual installation
Follow the steps below if you have a project that was previously created with Expo but does not have Expo Router library installed.
### Prerequisites
Make sure your computer is [set up for running an Expo app](/get-started/create-a-project/).
Step 1: 
### Install dependencies
You'll need to install the following dependencies:
```sh
$ npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar
```
The above command will install versions of these libraries that are compatible with the Expo SDK version your project is using.
Step 2: 
### Setup entry point
For the property `main`, use the `expo-router/entry` as its value in the **package.json**. The initial client file is [**app/\_layout.tsx**](/router/basics/layout/#root-layout).
!!!IG0!!!
Note: Custom entry point to initialize and load side-effects
---
You can create a custom entry point in your Expo Router project to initialize and load side-effects before your app loads the root layout (**app/\_layout.tsx**). Below are some of the common cases for a custom entry point:
- Initializing global services like analytics, error reporting, and so on.
- Setting up polyfills
- Ignoring specific logs using `LogBox` from `react-native`
1. Create a new file in the root of your project, such as **index.js**. After creating this file, the project structure should look like this:
!!!IG6!!!
2. Import or add your custom configuration to the file. Then, import `expo-router/entry` to register the app entry. Remember to always import it last to ensure all configurations are properly set up before the app renders.
!!!IG1!!!
3. Update the `main` property in **package.json** to point to the new entry file.
!!!IG2!!!
---
Step 3: 
### Modify project configuration
Add a deep linking `scheme` in your [app config](/workflow/configuration/):
!!!IG3!!!
If you are developing your app for web, install the following dependencies:
```sh
$ npx expo install react-native-web react-dom
```
Then, enable [Metro web](/guides/customizing-metro/#adding-web-support-to-metro) support by adding the following to your [app config](/workflow/configuration/):
!!!IG4!!!
Step 4: 
### Modify babel.config.js
Ensure you use `babel-preset-expo` as the `preset`, in the **babel.config.js** file or delete the file:
!!!IG5!!!
Step 5: 
### Clear bundler cache
After updating the Babel config file, run the following command to clear the bundler cache:
```sh
$ npx expo start --clear
```
Step 6: 
### Update resolutions
If you're upgrading from an older version of Expo Router, ensure you remove all outdated Yarn resolutions or npm overrides in your **package.json**. Specifically, remove `metro`, `metro-resolver`, `react-refresh` resolutions from your **package.json**.


# 路由入门

## Expo Router 中基于文件路由的核心概念

了解 Expo Router 的基本规则以及它与其他代码的关系。

在深入研究如何使用 Expo Router 构建应用的导航树之前，让我们首先了解构成 Expo Router 中基于文件路由基础的核心概念，以及 Expo Router 项目在结构上与其他 React Native 项目有何不同。
¥Before diving into how to construct your app's navigation tree with Expo Router, let's first understand the core concepts that make up the foundation of file-based routing in Expo Router, and how an Expo Router project might differ in structure from other React Native projects.
<a id="the-rules-of-expo-router"></a>
## Expo Router 规则
¥The rules of Expo Router
<a id="all-screenspages-are-files-inside-of-app-directory"></a>
### 1. 所有屏幕/页面都是应用目录中的文件
¥ All screens/pages are files inside of app directory
应用中的所有导航路由均由应用目录中的文件和子目录定义。app 目录下的每个文件都有一个默认导出，用于定义应用中的不同页面（特殊的 _layout 文件除外）。
¥All navigation routes in your app are defined by the files and sub-directories inside the **app** directory. Every file inside the **app** directory has a default export that defines a distinct page in your app (except for the special **_layout** files).
因此，应用内的目录将相关屏幕组合在一起定义为堆栈、选项卡或其他排列方式。
¥Accordingly, directories inside **app** define groups of related screens together as stacks, tabs, or in other arrangements.
<a id="all-pages-have-a-url"></a>
### 2. 所有页面都有一个 URL
¥ All pages have a URL
所有页面的 URL 路径都与应用目录中文件的位置匹配，可用于在网页地址栏中导航到该页面，或在原生移动应用中用作特定于应用的深层链接。这就是 Expo Router 支持 "通用深度链接" 的含义。无论使用哪个平台，都可以通过 URL 导航到应用中的所有页面。
¥All pages have a URL path that matches the file's location in the **app** directory, which can be used to navigate to that page in the address bar on the web, or as an app-specific deep link in a native mobile app. This is what is meant by Expo Router supporting "universal deep-linking". All pages in your app can be navigated to with a URL, regardless of the platform.
<a id="first-indextsx-is-the-initial-route"></a>
### 3. 第一个 index.tsx 是初始路由
¥ First index.tsx is the initial route
使用 Expo Router，你无需在代码中定义初始路由或首屏。相反，当你打开应用时，Expo Router 会查找第一个与 `/` URL 匹配的 index.tsx 文件。这可以是 app/index.tsx 文件，但并非必须如此。如果用户默认从导航树的更深层位置启动，你可以使用 [路由组](/router/basics/notation/#parentheses)（名称用括号括起来的目录），这将不计入 URL 的一部分。如果你希望第一个屏幕是一组标签页，你可以将所有标签页放在 app/(tabs) 目录中，并将默认标签页定义为 index.tsx。通过这种安排，`/` URL 会将用户直接带到 app/(tabs)/index.tsx 文件。
¥With Expo Router, you do not define an initial route or first screen in code. Rather, when you open your app, Expo Router will look for the first **index.tsx** file matching the `/` URL. This could be an **app/index.tsx** file, but it doesn't have to be. If the user should start by default in a deeper part of your navigation tree, you can use a [route group](/router/basics/notation/#parentheses) (a directory where the name is surrounded in parenthesis), and that will not count as part of the URL. If you want your first screen to be a group of tabs, you might put all of the tab pages inside the **app/(tabs)** directory and define the default tab as **index.tsx**. With this arrangement, the `/` URL will take the user directly to **app/(tabs)/index.tsx** file.
<a id="root-_layouttsx-replaces-appjsxtsx"></a>
### 4. 根 \_layout.tsx 替换 App.jsx/tsx
¥ Root \_layout.tsx replaces App.jsx/tsx
每个项目都应该在 app 目录中直接包含一个 _layout.tsx 文件。此文件会在应用中的任何其他路由之前渲染，你可以在此处放置之前可能已在 App.jsx 文件中定义的初始化代码，例如加载字体或与启动画面交互。
¥Every project should have a **_layout.tsx** file directly inside the **app** directory. This file is rendered before any other route in your app and is where you would put the initialization code that may have previously gone inside an **App.jsx** file, such as loading fonts or interacting with the splash screen.
<a id="non-navigation-components-live-outside-of-app-directory"></a>
### 5. 非导航组件位于应用目录之外
¥ Non-navigation components live outside of app directory
在 Expo Router 中，app 目录专门用于定义应用的路由。应用的其他部分，例如组件、钩子、实用程序等，应放置在其他顶层目录中。如果你将非路由内容放在应用目录中，Expo Router 将尝试将其视为路由。
¥In Expo Router, the **app** directory is exclusively for defining your app's routes. Other parts of your app, like components, hooks, utilities, and so on, should be placed in other top-level directories. If you put a non-route inside of the **app** directory, Expo Router will attempt to treat it like a route.
或者，你可以创建一个 [顶层 src 目录](/router/reference/src-directory/) 文件，并将路由放在 src/app 目录中，将非路由组件放在 src/components、src/utils 等文件夹中。这是 Expo Router 唯一能识别的其他目录结构。
¥Alternatively, you can create a [top-level **src** directory](/router/reference/src-directory/) and put your routes inside the **src/app** directory, with non-route components going in folders like **src/components**, **src/utils**, and so on. This is the only other directory structure that Expo Router will recognize.
<a id="its-still-react-navigation-under-the-hood"></a>
### 6. 底层仍然是 React Navigation
¥ It's still React Navigation under the hood
虽然这听起来与 React Navigation 有很大不同，但 Expo Router 实际上是建立在 React Navigation 之上的。你可以将 Expo Router 视为 Expo CLI 的优化，它将你的文件结构转换为你之前在代码中定义的 React Navigation 组件。
¥While this may sound quite a bit different from React Navigation, Expo Router is actually built on top of React Navigation. You can think of Expo Router as an Expo CLI optimization that translates your file structure into React Navigation components that you previously defined in your own code.
这也意味着你可以经常参考 React Navigation 文档来了解如何设置或配置导航，因为默认的堆栈导航器和标签导航器使用完全相同的选项。
¥This also means that you can often refer to React Navigation documentation for how to style or configure navigation, as the default stack and tab navigators use the exact same options.
<a id="the-rules-of-expo-router-applied"></a>
## Expo Router 规则的应用
¥The rules of Expo Router applied
让我们运用 Expo Router 的基本规则来快速识别以下项目文件结构的关键元素：
¥Let's apply these foundational rules of Expo Router to quickly identify key elements of the following project file structure:
* app/index.tsx 是初始路由，当你打开应用或导航到 Web 应用的根 URL 时，它将首先显示。
  ¥**app/index.tsx** is the initial route, and will appear first when you open the app or navigate to your web app's root URL.
* app/home.tsx 是一个包含路由 `/home` 的页面，因此你可以在浏览器中使用类似 `yourapp.com/home` 的 URL 导航到该页面，在原生应用中使用 `myapp://home` 的 URL 导航到该页面。
  ¥**app/home.tsx** is a page with the route `/home`, so you can navigate to it with a URL like `yourapp.com/home` in the browser, or `myapp://home` in a native app.
* app/_layout.tsx 是根布局。你之前在 App.jsx 中编写的任何初始化代码都应在此处放置。
  ¥**app/_layout.tsx** is the root layout. Any initialization code you may have previously put in **App.jsx** should go here.
* app/profile/friends.tsx 是一个包含路由 `/profile/friends` 的页面。
  ¥**app/profile/friends.tsx** is a page with the route `/profile/friends`.
* TextField.tsx 和 Toolbar.tsx 不在应用目录中，因此它们不会被视为页面。它们没有 URL，也不能成为导航操作的目标。但是，它们可以用作应用目录内页面中的组件。
  ¥**TextField.tsx** and **Toolbar.tsx** are not in the **app** directory, so they will not be considered pages. They will not have a URL, and they cannot be the target of a navigation action. However, they can be used as components in the pages inside of the **app** directory.


## Expo Router 符号

了解如何使用特殊文件名和符号在项目文件结构中清晰地定义应用的导航树。

当你查看典型的 Expo Router 项目中的应用目录时，你会看到比一些简单的文件和目录名称更多内容。括号和方括号是什么意思？让我们了解基于文件的路由符号的重要性，以及它如何帮助你定义复杂的导航模式。
¥When you look inside the **app** directory in a typical Expo Router project, you'll see a lot more than some simple file and directory names. What do the parentheses and brackets mean? Let's learn the significance of file-based routing notation and how it allows you to define complex navigation patterns.
<a id="types-of-route-notation"></a>
## 路由符号类型
¥Types of route notation
<a id="simple-namesno-notation"></a>
### 简单名称/无符号
¥Simple names/no notation
没有任何符号的常规文件和目录名称表示静态路由。它们的 URL 与文件树中显示的完全匹配。因此，feed 目录中名为 favorites.tsx 的文件将具有 `/feed/favorites` 的 URL。
¥Regular file and directory names without any notation signify *static routes*. Their URL matches exactly as they appear in your file tree. So, a file named **favorites.tsx** inside the **feed** directory will have a URL of `/feed/favorites`.
<a id="square-brackets"></a>
### 方括号
¥Square brackets
如果你在文件或目录名称中看到方括号，则表示你正在查看动态路由。路由名称包含一个可在渲染页面时使用的参数。该参数可以是目录名，也可以是文件名。例如，名为 [userName].tsx 的文件将匹配 `/evanbacon`、`/expo` 或其他用户名。然后，你可以使用页面内的 `useLocalSearchParams` 钩子访问该参数，并使用它来加载特定用户的数据。
¥If you see square brackets in a file or directory name, you are looking at a *dynamic route*. The name of the route includes a parameter that can be used when rendering the page. The parameter could be either in a directory name or a file name. For example, a file named **[userName].tsx** will match `/evanbacon`, `/expo`, or another username. Then, you can access that parameter with the `useLocalSearchParams` hook inside the page, using that to load the data for that specific user.
<a id="parentheses"></a>
### 括号
¥Parentheses
名称用括号括起来的目录表示路由组。这些目录可用于在不影响 URL 的情况下将路由分组。例如，名为 app/(tabs)/settings.tsx 的文件的 URL 会包含 `/settings`，即使它并不直接位于应用目录中。
¥A directory with its name surrounded in parentheses indicates a *route group*. These directories are useful for grouping routes together without affecting the URL. For example, a file named **app/(tabs)/settings.tsx** will have `/settings` for its URL, even though it is not directly in the **app** directory.
路由组对于简单的组织目的很有用，但通常在定义路由之间的复杂关系时更为重要。
¥Route groups can be useful for simple organization purposes, but often become more important for defining complex relationships between routes.
<a id="indextsx-files"></a>
### index.tsx 文件
¥index.tsx files
与 Web 一样，index.tsx 文件指示目录的默认路由。例如，名为 profile/index.tsx 的文件将匹配 `/profile`。名为 (tabs)/index.tsx 的文件将与 `/` 匹配，从而有效地成为整个应用的默认路由。
¥Just like on the web, an **index.tsx** file indicates the default route for a directory. For example, a file named **profile/index.tsx** will match `/profile`. A file named **(tabs)/index.tsx** will match `/`, effectively becoming the default route for your entire app.
<a id="_layouttsx-files"></a>
### \_layout.tsx 文件
¥\_layout.tsx files
_layout.tsx 文件是特殊文件，它们本身不是页面，但定义了目录内路由组之间的关系。如果路由目录以堆栈或选项卡的形式排列，则布局路由是你可以使用堆栈导航器或选项卡导航器组件定义这种关系的地方。
¥**_layout.tsx** files are special files that are not pages themselves but define how groups of routes inside a directory relate to each other. If a directory of routes is arranged as a stack or tabs, the layout route is where you would define that relationship by using a stack navigator or tab navigator component.
布局路由在其目录中的实际页面路由之前渲染。这意味着直接位于应用目录中的 _layout.tsx 会在应用中的任何其他内容之前渲染，并且你将在其中放置可能先前位于 App.jsx 文件中的初始化代码。
¥Layout routes are rendered before the actual page routes inside their directory. This means that the **_layout.tsx** directly inside the **app** directory is rendered before anything else in the app, and is where you would put the initialization code that may have previously gone inside an **App.jsx** file.
<a id="plus-sign"></a>
### 加号
¥Plus sign
以 `+` 开头的路由对 Expo Router 具有特殊意义，并用于特定用途。[`+not-found`](/router/error-handling/#unmatched-routes) 就是一个例子，它会捕获任何与应用中的路由不匹配的请求。[`+html`](/router/reference/static-rendering/#root-html) 用于自定义你的应用在 Web 上使用的 HTML 样板。[`+native-intent`](/router/advanced/native-intent/) 用于处理应用中与特定路由不匹配的深层链接，例如由第三方服务生成的链接。
¥Routes starting with a `+` have special significance to Expo Router, and are used for specific purposes. One example is [`+not-found`](/router/error-handling/#unmatched-routes), which catches any requests that don't match a route in your app. [`+html`](/router/reference/static-rendering/#root-html) is used to customize the HTML boilerplate used by your app on web. [`+native-intent`](/router/advanced/native-intent/) is used to handle deep links into your app that don't match a specific route, such as links generated by third party services.
<a id="route-notation-applied"></a>
## 路由应用的符号
¥Route notation applied
考虑以下项目文件结构，以识别所代表的不同类型的路由：
¥Consider the following project file structure to identify the different types of routes represented:
* app/about.tsx 是一个与 `/about` 匹配的静态路由。
  ¥**app/about.tsx** is a static route that matches `/about`.
* app/users/[userId].tsx 是一个与 `/users/123`、`/users/456` 等匹配的动态路由。
  ¥**app/users/[userId].tsx** is a dynamic route that matches `/users/123`, `/users/456`, and so on.
* app/(tabs) 是一个路由组。它不会计入 URL，因此 `/feed` 将匹配 app/(tabs)/feed.tsx。
  ¥**app/(tabs)** is a route group. It will not factor into the URL, so `/feed` will match **app/(tabs)/feed.tsx**.
* app/(tabs)/index.tsx 是 (tabs) 目录的默认路由，因此它将是最初获得焦点的标签页，并匹配 `/` URL。
  ¥**app/(tabs)/index.tsx** is the default route for the **(tabs)** directory, so it will be the initially-focused tab, and will match the `/` URL.
* app/(tabs)/_layout.tsx 是一个布局文件，定义了 app/(tabs)/ 目录下的三个页面之间的关系。如果你在此文件中使用选项卡导航器组件，则这些屏幕将以选项卡形式排列。
  ¥**app/(tabs)/_layout.tsx** is a layout file defining how the three pages inside **app/(tabs)/** relate to each other. If you use a tab navigator component inside of this file, then those screens will be arranged as tabs.
* app/_layout.tsx 是根布局文件，在应用中的任何其他路由之前渲染。
  ¥**app/_layout.tsx** is the root layout file, and is rendered before any other route in the app.
* +not-found.tsx 是一个特殊路由，如果用户导航到应用中不存在的路由，则会显示该路由。
  ¥**+not-found.tsx** is a special route that will be displayed if the user navigates to a route that doesn't exist in your app.


## Expo Router 中的导航布局

了解如何使用目录和布局文件构建页面之间的不同关系。

<VideoBoxLink videoId="Yh6Qlg2CYwQ" title="Introduction to Expo Router Layout Files" description="What are layout files, how to navigate between screens, and block access using redirects." className="mb-6" />
app 目录下的每个目录（包括 app 本身）都可以在该目录中以 _layout.tsx 文件的形式定义布局。此文件定义了该目录中所有页面的排列方式。你可以在此处定义堆栈导航器、标签导航器、抽屉导航器或任何其他要用于该目录中页面的布局。布局文件导出一个默认组件，该组件会在你在该目录中导航到的任何页面之前渲染。
¥Each directory within the **app** directory (including **app** itself) can define a layout in the form of a **_layout.tsx** file inside that directory. This file defines how all the pages within that directory are arranged. This is where you would define a stack navigator, tab navigator, drawer navigator, or any other layout that you want to use for the pages in that directory. The layout file exports a default component that is rendered before whatever page you are navigating to within that directory.
让我们看一些常见的布局场景。
¥Let's look at a few common layout scenarios.
<a id="root-layout"></a>
## 根布局
¥Root layout
几乎每个应用都会在应用目录中直接包含一个 _layout.tsx 文件。这是根布局，代表导航的入口点。除了描述应用的顶层导航器之外，你还可以在此文件中放置初始化代码，这些代码可能之前已包含在 App.jsx 文件中，例如加载字体、与启动画面交互或添加上下文提供程序。
¥Virtually every app will have a **_layout.tsx** file directly inside the **app** directory. This is the root layout and represents the entry point for your navigation. In addition to describing the top-level navigator for your app, this file is where you would put initialization code that may have previously gone inside an **App.jsx** file, such as loading fonts, interacting with the splash screen, or adding context providers.
以下是根布局示例：
¥Here's an example root layout:
```tsx app/_layout.tsx
import { useFonts } from 'expo-font';
import { Stack } from 'expo-router';
import * as SplashScreen from 'expo-splash-screen';
import { useEffect } from 'react';
SplashScreen.preventAutoHideAsync();
export default function RootLayout() {
  const [loaded] = useFonts({
    SpaceMono: require('../assets/fonts/SpaceMono-Regular.ttf'),
  });
  useEffect(() => {
    if (loaded) {
      SplashScreen.hide();
    }
  }, [loaded]);
  if (!loaded) {
    return null;
  }
  return <Stack />;
}
```
以上示例最初显示启动画面，然后在字体加载完成后渲染堆栈导航器，这将使你的应用继续执行初始路由。
¥The above example shows the splash screen initially and then renders a stack navigator once the fonts are loaded, which will cause your app to proceed to the initial route.
<a id="stacks"></a>
## 堆栈
¥Stacks
你可以在根布局中实现堆栈导航器（如上所示），也可以在目录内的任何其他布局文件中实现。假设你有一个文件结构，其目录内有一个堆栈：
¥You can implement a stack navigator in your root layout, as shown above, or in any other layout file inside a directory. Let's suppose you have a file structure with a stack inside of a directory:
如果你希望 app/products 目录中的所有内容以堆叠关系排列，请在 _layout.tsx 文件中返回一个 `Stack` 组件：
¥If you want everything inside of the **app/products** directory to be arranged in a stack relationship, inside the **_layout.tsx** file, return a `Stack` component:
```tsx app/products/_layout.tsx
import { Stack } from 'expo-router';
export default function StackLayout() {
  return <Stack />;
}
```
当你导航到 `/products` 时，它将首先转到默认路由，即 products/index.tsx。如果你导航到 `/products/123`，则该页面将被推送到堆栈。默认情况下，堆栈将在标题中渲染一个后退按钮，该按钮会将当前页面从堆栈中弹出，并让用户返回到上一页。即使页面不可见，只要它仍然被推送到堆栈中，它就会被渲染。
¥When you navigate to `/products`, it will first go to the default route, which is **products/index.tsx**. If you navigate to `/products/123`, then that page will be pushed onto the stack. By default, the stack will render a back button in the header that will pop the current page off the stack, returning the user to the previous page. Even when a page isn't visible, if it is still pushed onto the stack, it is still being rendered.
`Stack` 组件实现了 [React Navigation 原生技术栈](https://react-navigation.nodejs.cn/docs/native-stack-navigator/)，可以使用相同的屏幕选项。但是，你不必在导航器中具体定义页面。目录中的文件将自动被视为堆栈中的合格路由。但是，如果你想定义屏幕选项，你可以在 `Stack` 组件内添加一个 `Stack.Screen` 组件。`name` 属性应与路由名称匹配，但你无需提供 `component` 属性；Expo Router 将自动映射：
¥The `Stack` component implements [React Navigation's native stack](https://react-navigation.nodejs.cn/docs/native-stack-navigator/) and can use the same screen options. However, you do not have to define the pages specifically inside the navigator. The files inside the directory will be automatically treated as eligible routes in the stack. However, if you want to define screen options, you can add a `Stack.Screen` component inside the `Stack` component. The `name` prop should match the route name, but you do not need to supply a `component` prop; Expo Router will map this automatically:
```tsx app/products/_layout.tsx
import { Stack } from 'expo-router';
export default function StackLayout() {
  return (
    <Stack>
      <Stack.Screen name="[productId]" options={{ headerShown: false }} />
    </Stack>
  );
}
```
虽然可以嵌套导航器，但请确保仅在真正需要时才这样做。在上面的示例中，如果你想将 products/accessories/index.tsx 推送到堆栈，则无需在 Accessories 目录中再添加一个带有 `Stack` 导航器的 _layout.tsx 文件。这将在第一个堆栈内定义另一个堆栈。可以添加仅影响 URL 的目录，否则，请使用与父目录相同的导航器。
¥While it is possible to nest navigators, be sure to only do so when it is truly needed. In the above example, if you want to push **products/accessories/index.tsx** onto the stack, it's not necessary to have an additional **_layout.tsx** in the **accessories** directory with a `Stack` navigator. That would define another stack inside the first one. It is fine to add directories that only affect the URL, otherwise, use the same navigator as the parent directory.
<a id="tabs"></a>
## 选项卡
¥Tabs
与堆栈非常相似，你可以在布局文件中实现一个标签页导航器，并且该目录中的所有路由都将被视为标签页。考虑以下文件结构：
¥Much like a stack, you can implement a tab navigator in your layout file, and all the routes directly inside that directory will be treated as tabs. Consider the following file structure:
在 _layout.tsx 文件中，返回一个 `Tabs` 组件：
¥In the **_layout.tsx** file, return a `Tabs` component:
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
import MaterialIcons from '@expo/vector-icons/MaterialIcons';
export default function TabLayout() {
  return (
    <Tabs>
      <Tabs.Screen
        name="index"
        options={{
          title: 'Home',
          tabBarIcon: ({ color }) => <MaterialIcons size={28} name="house.fill" color={color} />,
        }}
      />
      <!-- Add more tabs here -->
    </Tabs>
  );
}
```
这将导致 index.tsx、feed.tsx 和 profile.tsx 文件一起出现在同一个底部选项卡导航器中。此 `Tabs` 组件使用 [React Navigation 原生底部标签页](https://react-navigation.nodejs.cn/docs/bottom-tab-navigator/) 并支持相同的选项。
¥This will cause the **index.tsx**, **feed.tsx**, and **profile.tsx** files to appear together in the same bottom tabs navigator. This `Tabs` component uses [React Navigation's native bottom tabs](https://react-navigation.nodejs.cn/docs/bottom-tab-navigator/) and supports the same options.
对于 `Tabs`，你可能需要在导航器中定义标签页，因为这会影响标签页的显示顺序、标题以及标签页内的图标。索引路由将是默认选定的选项卡。
¥In the case of `Tabs`, you will likely want to define the tabs in the navigator, as this influences the order in which tabs appear, the title, and the icon inside the tab. The index route will be the default selected tab.
<a id="slot"></a>
## 插槽
¥Slot
在某些情况下，你可能需要一个没有导航器的布局。这对于在当前路由周围添加页眉或页脚，或在目录内的任何路由上显示模态框非常有用。在这种情况下，你可以使用 `Slot` 组件，它作为当前子路由的占位符。
¥In some cases, you may want a layout without a navigator. This is helpful for adding a header or footer around the current route, or for displaying a modal over any route inside a directory. In this case, you can use the `Slot` component, which serves as a placeholder for the current child route.
考虑以下文件结构：
¥Consider the following file structure:
例如，你可能希望用页眉和页脚封装社交目录内的任何路由，但你希望在页面之间导航时直接替换当前页面，而不是将新页面推送到堆栈上，然后可以通过 "back" 导航操作将其弹出。在 _layout.tsx 文件中，返回一个由页眉和页脚包围的 `Slot` 组件：
¥For example, you may want to wrap any route inside the **social** directory with a header and footer, but you want navigating between the pages to simply replace the current page rather than pushing new pages onto a stack, which can then later be popped off with a "back" navigation action. In the **_layout.tsx** file, return a `Slot` component surrounded by your header and footer:
```tsx app/social/_layout.tsx
import { Slot } from 'expo-router';
export default function Layout() {
  return (
    <>
      <Header />
      <Slot />
      <Footer />
    </>
  );
}
```
<a id="other-layouts"></a>
## 其他布局
¥Other layouts
这些只是一些常见布局的示例，旨在帮助你了解其工作原理。布局功能还有很多其他用途：
¥These are just a few examples of common layouts to give you an idea of how it works. There's much more you can do with layout:
* 实现 [抽屉式导航器](/router/advanced/drawer)
  ¥Implement a [Drawer navigator](/router/advanced/drawer)
* 将默认选项卡替换为 [完全自定义标签页](/router/advanced/custom-tabs)
  ¥Replace the default tabs with [fully customized tabs](/router/advanced/custom-tabs)
* 使用 [modal](/router/advanced/modals) 显示透明页面，使父导航器在下方仍然可见。
  ¥Use a [modal](/router/advanced/modals) to display a page with transparency, such that the parent navigator is still visible underneath
* [适配任何与 React Navigation 兼容的导航器](/versions/latest/sdk/router/#withlayoutcontextnav-processor)，包括顶部标签页、底部工作表等
  ¥[Adapt any navigator that is compatible with React Navigation](/versions/latest/sdk/router/#withlayoutcontextnav-processor), including top tabs, bottom sheets, and more


## 在 Expo Router 中页面间导航

了解在 Expo Router 中链接和导航到页面的不同方式。

在你的应用中创建几个页面并设置好布局后，就可以开始在它们之间导航了。Expo Router 中的导航与 React Navigation 非常相似，但所有页面默认都有一个 URL，因此我们可以创建链接并使用这些 URL，以熟悉的 Web 模式在应用中移动。
¥Once you have a few pages in your app and their layouts setup, it's time to start navigating between them. Navigation in Expo Router works a lot like React Navigation, but with all pages having a URL by default, we can create links and use these URLs to move about our app using familiar web patterns.
<a id="native-navigation-basics-with-userouter"></a>
## `useRouter` 原生导航基础知识
¥Native navigation basics with `useRouter`
与 React Navigation 类似，你可以从 `onPress` 处理程序调用函数来导航到另一个页面。在 Expo Router 中，你可以使用 `useRouter` 钩子访问导航功能：
¥Like in React Navigation, you can call a function from an `onPress` handler to navigate to another page. In Expo Router, you can use the `useRouter` hook to access navigation functions:
```tsx
import { useRouter } from 'expo-router';
import { Button } from 'react-native';
export default function Home() {
  const router = useRouter();
  return <Button title="Go to About" onPress={() => router.navigate('/about')} />;
}
```
Expo Router 应用默认使用堆栈导航，导航到新路由会将屏幕推送到堆栈中，退出该路由会将其弹出堆栈。通常情况下，你应该使用 `router.navigate` 函数。这会将新页面推送到堆栈中，或展开到堆栈中的现有路由。但是，你也可以调用 `router.push` 显式将新页面推送到堆栈，调用 `router.back` 返回上一页，或调用 `router.replace` 替换堆栈中的当前页面。
¥Expo Router apps default to stack navigation, where navigating to a new route pushes a screen onto a stack, and backing out of that route pops it off the stack. Usually, you would want to use the `router.navigate` function. This will either push a new page onto the stack or unwind to an existing route on the stack. However, you can also call `router.push` to explicitly push a new page onto the stack, `router.back` to go back to the previous page, or `router.replace` to replace the current page on the stack.
使用 Expo Router，你可以通过 URL 或相对于应用目录的位置来引用页面。查看以下文件结构以及如何导航到每个页面：
¥With Expo Router, you refer to pages by their URL, or their position relative to the **app** directory. Check out the following file structure and how you would navigate to each page:
<a id="links-and-buttons"></a>
## 链接和按钮
¥Links and buttons
在 Expo Router 中链接到页面的典型方式是使用类似 Web 应用的链接。Expo Router 有一个 `Link` 组件用于在页面之间导航，其中 `href` 与你在 `router.navigate` 中使用的路由相同：
¥The typical way to link to a page in Expo Router is to use links like web apps. Expo Router has a `Link` component for navigating between pages, where the `href` is the same route you would use in `router.navigate`:
```tsx app/index.tsx
import { View } from 'react-native';
import { Link } from 'expo-router';
export default function Page() {
  return (
    <View>
      <Link href="/about">About</Link>
    </View>
  );
}
```
默认情况下，链接只能封装 `Text` 组件。你可以在带有 `asChild` 属性的链接中使用 `Pressable` 或其他支持 `onPress` 和 `onClick` 属性的组件：
¥By default, Links can only wrap `Text` components. You can use `Pressable` or other components that support `onPress` and `onClick` props inside a link with the `asChild` prop:
```tsx
import { Pressable, Text } from 'react-native';
import { Link } from 'expo-router';
export default function Page() {
  return (
    <Link href="/other" asChild>
      <Pressable>
        <Text>Home</Text>
      </Pressable>
    </Link>
  );
}
```
<a id="relative-routes"></a>
## 相对路由
¥Relative routes
你不必总是使用路由的绝对路径。使用以 `./`（表示当前目录）或 `../`（表示父目录）开头的路径将相对于当前路由进行导航。
¥You don't always have to use the absolute path to a route. Using paths that start with `./` (for the current directory) or `../` (for the parent directory) will navigate relative to the current route.
相对 URL 是带有 `./` 的 URL 前缀，例如 `./article` 或 `./article/`。相对 URL 是相对于当前渲染的屏幕解析的。
¥A relative URL is a URL prefix with `./`, such as `./article`, or `./article/`. Relative URLs are resolved relative to the current rendered screen.
```tsx
<Link href="./article">Go to article</Link>
```
```ts
router.navigate('./article');
```
<a id="dynamic-routes-and-url-parameters"></a>
## 动态路由和 URL 参数
¥Dynamic routes and URL parameters
<VideoBoxLink videoId="izZv6a99Roo" time={350} title="Using dynamic routes with Expo Router" description="Learn how to make a segment of a route dynamic." className="mb-6" />
动态路由可以通过其完整 URL 或传递 `params` 对象来链接。
¥Dynamic routes can be linked to with their full URL, or by passing a `params` object.
考虑以下文件结构：
¥Consider the following file structure:
以下每个链接都将导航到同一页面：
¥Each of these links will navigate to the same page:
```tsx app/index.tsx
import { Link, router } from 'expo-router';
import { View, Pressable, Text } from 'react-native';
export default function Page() {
  return (
    <View>
      <Link
        href="/user/bacon">
        View user (id inline)
      </Link>
      <Link
        href={{
          pathname: '/user/[id]',
          params: { id: 'bacon' }
        }}
      >
        View user (id in params in href)
      </Link>
      <Pressable
        onPress={() =>
          router.navigate({
            pathname: '/user/[id]',
            params: { id: 'bacon' }
          })
        }
      >
        <Text>View user (imperative)</Text>
      </Pressable>
    </View>
  );
}
```
<a id="passing-query-parameters"></a>
### 传递查询参数
¥Passing query parameters
你可以在链接 URL 本身中指定查询参数，也可以将其作为 `params` 对象中的附加参数指定。任何与动态路由变量名称不匹配的参数都等同于查询参数。
¥You can specify query parameters in the link URL itself, or as additional parameters in the `params` object. Any parameters that don't match the name of the dynamic route variable are equivalent to query parameters.
```tsx
<Link href="/users?limit=20">View users</Link>
<Link
  href={{
    pathname: '/users',
    params: { limit: 20 }
  }}>
  View users
</Link>
```
<a id="using-dynamic-route-variables-and-query-parameters-in-the-destination-page"></a>
### 在目标页面中使用动态路由变量和查询参数
¥Using dynamic route variables and query parameters in the destination page
接收页面可以通过 `useLocalSearchParams` 钩子访问链接 URL 中的所有变量。此钩子返回一个包含所有 URL 参数的对象，包括作为 `params` 传递的参数。
¥All variables in the link URL are accessible to the receiving page via the `useLocalSearchParams` hook. This hook returns an object with all the URL parameters, including those passed as `params`.
例如，如果你有如下链接：
¥For example, if you have a link like this:
```tsx
<Link href="/users?limit=20">View users</Link>
```
然后，你可以像这样在另一端读取参数：
¥Then you can read the parameters on the other end like this:
```tsx
import { useLocalSearchParams } from 'expo-router';
import { View, Text } from 'react-native';
export default function Users() {
  const { id, limit } = useLocalSearchParams();
  return (
    <View>
      <Text>User ID: {id}</Text>
      <Text>Limit: {limit}</Text>
    </View>
  );
}
```
<a id="updating-query-parameters-without-navigating"></a>
### 无需导航即可更新查询参数
¥Updating query parameters without navigating
查询参数无需跳转到新页面即可更新。这可以通过使用与当前页面相同的 URL，但使用更新的查询参数或命令式的 `Link` 来实现。
¥Query parameters can be updated without navigating to a new page. This can be done with a `Link` that uses the same URL as the current page, but with updated query parameters, or imperatively.
```tsx
<Link href="/users?limit=50">View more users</Link>
<Pressable onPress={() => router.setParams({ limit: 50 })}>
  <Text>View more users</Text>
</Pressable>
```
<a id="redirects"></a>
## 重定向
¥Redirects
你可以使用 `Redirect` 组件立即从页面或布局重定向到另一个路由。其功能类似于 `replace` 命令式导航功能。重定向将导航到新路由，而不渲染当前页面。
¥You can immediately redirect to another route from a page or layout with the `Redirect` component. This functions like the `replace` imperative navigation function. A redirect will navigate to the new route without rendering the current page.
```tsx
import { Redirect } from 'expo-router';
export default function Page() {
  return <Redirect href="/about" />;
}
```
<a id="prefetching"></a>
## 预加载
¥Prefetching
`<Link />` 组件上的 `prefetch` 属性允许在渲染组件时预取目标屏幕。这样可以通过提前准备屏幕来实现更快的导航。
¥The `prefetch` prop on a `<Link />` component enables prefetching of the target screen when the component is rendered. This allows for faster navigation by preparing the screen in advance.
```tsx
import { Link } from 'expo-router';
export default function Page() {
  return <Link href="/about" prefetch />;
}
```
设置 `prefetch` 后，Expo Router 将尝试在屏幕外渲染目标屏幕。具体行为取决于所使用的导航器类型：
¥When `prefetch` is set, Expo Router will attempt to render the target screen off-screen. The exact behavior depends on the type of navigator used:
* Expo 路由导航器：将目标屏幕渲染到屏幕外以启用预加载。
  ¥**Expo Router Navigators**: Render the target screen off-screen to enable preloading.
* 自定义导航器：可以以不同的方式实现预取，或者完全不支持预取。
  ¥**Custom Navigators**: May implement prefetching differently or not support it at all.
当屏幕在堆栈导航器中预加载时，它会受到一些限制：
¥When a screen is preloaded in a stack navigator, it will have a few limitations:
* 它无法使用命令式 `router` API。
  ¥It cannot use the imperative `router` API.
* 它无法使用 `useNavigation().setOptions()` 更新选项
  ¥It cannot update options with `useNavigation().setOptions()`
* 它无法监听导航器中的事件（例如 focus、tabPress 等）。
  ¥It cannot listen to events from the navigator (for example focus, tabPress, and so on).
导航到屏幕后，导航对象将会更新。因此，如果你在 useEffect 钩子中有一个事件监听器，并且依赖于导航，那么当屏幕导航到以下位置时，它将添加任何监听器：
¥The navigation object will be updated once you navigate to the screen. So if you have an event listener in a useEffect hook, and have a dependency on navigation, it will add any listeners when the screen is navigated to:
```tsx
const navigation = useNavigation();
useEffect(() => {
  const unsubscribe = navigation.addListener('tabPress', () => {
    // do something
  });
  return () => {
    unsubscribe();
  };
}, [navigation]);
```
类似地，对于调度操作或更新选项，你可以在执行此操作之前检查屏幕是否已聚焦：
¥Similarly, for dispatching actions or updating options, you can check if the screen is focused before doing so:
```tsx
const navigation = useNavigation();
if (navigation.isFocused()) {
  navigation.setOptions({ title: 'Updated title' });
}
```
更多信息，请参阅 [React Navigation 预加载文档](https://react-navigation.nodejs.cn/docs/navigation-object/#preload)
¥For more information, refer to the [React Navigation preload docs](https://react-navigation.nodejs.cn/docs/navigation-object/#preload)
<a id="deep-links"></a>
## 深层链接
¥Deep links
深层链接是指通过 URL 在应用中打开特定页面。Expo Router 默认支持深度链接，因此你可以使用应用外部的 URL 链接到应用中的任何页面，就像在应用内部使用 `Link` 一样。这对于在应用中分享特定页面的链接特别有用。
¥Deep linking is when a URL opens a specific page in your app. Expo Router supports deep linking by default, so you can link to any page in your app with a URL from outside of your app, as you would inside your app with `Link`. This is especially useful for sharing links to specific pages in your app.
在网页端，深度链接非常简单，只需在网页浏览器中导航到特定的 URL 即可。在移动设备上，你可以在 [应用配置](/workflow/configuration/) 文件中定义一个 `scheme`，它将成为你应用中深层链接的前缀。
¥On web, deep linking is as simple as navigating to that specific URL in your web browser. On mobile, you define a `scheme` in your [app config](/workflow/configuration/) file, and this becomes the prefix for deep links into your app.
假设你的 `scheme` 是 `myapp`，以下是如何从网页或其他应用链接到你应用中页面的示例：
¥Assuming your `scheme` is `myapp`, here are some examples of how you would link to a page in your app from a web page or another app:
使用应用链接和通用链接，你还可以使用 `https` URL 链接到你的应用。欲了解更多信息，请参阅 [更新底部选项卡导航器外观](/linking/overview/#universal-linking)。
¥With app links and universal links, you can also link to your app with an `https` URL. For more information, see [Universal linking](/linking/overview/#universal-linking).
<a id="initial-routes"></a>
## 初始路由
¥Initial routes
在应用中打开指向某个页面的深层链接时，你可能希望返回导航能够像用户从主页导航到该页面一样工作。为此，你可以指定 `initialRouteName` 配置，该配置定义了应在深度链接页面之前加载的页面布局。
¥When opening a deep link to a page in your app, you will likely want back navigation to work as if the user navigated to the page from your home page. To do this, you can specify an `initialRouteName` configuration, which defines the page in a layout that should be loaded before the deep linked page.
考虑以下文件结构：
¥Consider the following file structure:
`stack` 是一个堆栈导航器，`/stack/index` 始终是堆栈中的第一个路由。
¥`stack` is a stack navigator, and `/stack/index` is always the first route in the stack.
为了确保即使用户深度链接到 `/stack/second`，`/stack/index` 也始终优先加载，你可以在 app/stack/_layout.tsx 中设置 `initialRouteName`：
¥To ensure that `/stack/index` is always loaded first, even if the user deep links to `/stack/second`, you can set the `initialRouteName` in **app/stack/_layout.tsx**:
```tsx
export const unstable_settings = {
  // Ensure any route can link back to `/`
  initialRouteName: 'index',
};
```
默认情况下，`initialRouteName` 仅在深度链接时考虑，在应用内导航时不考虑。但是，你可以在 `Link` 上使用 `withAnchor` 属性，在直接导航到应用内的另一个堆栈时强制加载初始路由。
¥By default, the `initialRouteName` is only considered when deep linking and not during navigation within your app. However, you can use the `withAnchor` prop on `Link` to force the initial route to be loaded when navigating directly into another stack inside your app.
因此，如果 app/index.tsx 包含指向 `/stack/second` 的链接，请添加 `withAnchor` 属性以确保首先加载 `/stack/index`，这将导致用户在按下 `/stack/second` 的返回按钮时返回到 `/stack/index`：
¥So, if **app/index.tsx** contained a link to `/stack/second`, add the `withAnchor` prop to ensure that `/stack/index` is loaded first, which will cause the user to go back to `/stack/index` when they press the back button from `/stack/second`:
```tsx
<Link href="/stack/second" withAnchor>
  Go to second
</Link>
```
>  **info** 如果在测试深层链接时缺少后退按钮，通常可以通过设置 `initialRouteName` 来解决。
>
> ¥If you are missing a back button when testing deep links, this can often be fixed by setting an `initialRouteName`.


## Expo Router 中常见的导航模式

将 Expo Router 基础知识应用于你可以在应用中使用的实际导航模式。

现在你已经了解了 Expo Router 中文件和目录的命名和排列方式，让我们运用这些知识，看看你可能在应用中使用的一些实际导航模式。
¥Now that you know the basics of how files and directories are named and arranged in Expo Router, let's apply that knowledge, looking at some real-life navigation patterns you might use in your app.
<a id="stacks-inside-tabs-nested-navigators"></a>
## 选项卡内的堆栈：嵌套导航器
¥Stacks inside tabs: nested navigators
如果你的应用通常以一组选项卡为起点，但一个或多个选项卡可能关联多个屏幕，则通常可以在选项卡内嵌套堆栈导航器。这种模式通常会生成直观的 URL，并且能够很好地扩展到桌面 Web 应用，因为桌面 Web 应用的主选项卡通常始终可见。
¥If the typical starting point for your app is a set of tabs, but one or more tabs may have more than one screen associated with it, nesting a stack navigator inside of a tab is often the way to go. This pattern often results in intuitive URLs and scales well to desktop web apps, where the primary tabs are often always visible.
考虑以下导航树：
¥Consider the following navigation tree:
在 app/(tabs)/_layout.tsx 文件中，返回一个 `Tabs` 组件：
¥In the **app/(tabs)/_layout.tsx** file, return a `Tabs` component:
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs screenOptions={{ headerShown: false }}>
      <Tabs.Screen name="index" options={{ title: 'Home' }} />
      <Tabs.Screen name="feed" options={{ title: 'Feed' }} />
      <Tabs.Screen name="settings" options={{ title: 'Settings' }} />
    </Tabs>
  );
}
```
在 app/(tabs)/feed/_layout.tsx 文件中，返回一个 `Stack` 组件：
¥In the **app/(tabs)/feed/_layout.tsx** file, return a `Stack` component:
```tsx app/(tabs)/feed/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  initialRouteName: 'index',
};
export default function FeedLayout() {
  return <Stack />;
}
```
现在，在 app/(tabs)/feed 目录中，你可以拥有指向不同帖子的 `Link` 组件（例如 `/feed/123`）。这些链接会将 `feed/[postId]` 路由推送到堆栈，使标签导航器可见。
¥Now, within the **app/(tabs)/feed** directory, you can have `Link` components that point to different posts (for example, `/feed/123`). Those links will push the `feed/[postId]` route onto the stack, leaving the tab navigator visible.
你还可以使用相同的 URL 从任何其他选项卡导航到 feed 选项卡中的帖子。将 `withAnchor` 与 `initialRouteName` 结合使用，可确保 `feed/index` 路由始终是堆栈中的第一个屏幕：
¥You can also navigate from any other tab to a post in the feed tab with the same URL. Use `withAnchor` in conjunction with `initialRouteName` to ensure that the `feed/index` route is always the first screen in the stack:
```tsx app/(tabs)/feed/index.tsx
<Link href="/feed/123" withAnchor>
  Go to post
</Link>
```
你还可以将选项卡嵌套在外部堆栈导航器中。这通常更适合在标签页上显示模态框。
¥You can also nest tabs inside of an outer stack navigator. That is often more useful for displaying modals over the tabs.
<a id="one-screen-two-tabs-sharing-routes"></a>
## 一屏两屏标签页：共享路由
¥One screen, two tabs: sharing routes
路由组可用于在两个不同的选项卡之间共享单个屏幕。假设导航树包含一个“Feed”选项卡和一个“Search”选项卡，它们共享用于查看用户个人资料的页面：
¥Route groups can be used to share a single screen between two different tabs. Consider a navigation tree that has a Feed tab and a Search tab, and they both share pages for viewing a user profile:
每个标签页都放在一个组中，因此你可以定义第三个目录，在两个组之间共享路由 (app/(tabs)/(feed,search)/)。即使有额外的层，app/(tabs)/(feed)/index.tsx 仍然是最近的索引，因此它将是默认路由。
¥Each of the tabs is put in a group so you can define a third directory that shares routes between two groups (**app/(tabs)/(feed,search)/**). Even with the extra layer, **app/(tabs)/(feed)/index.tsx** is still the nearest index, so it will be the default route.
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs>
      <Tabs.Screen name="(feed)" options={{ title: 'Feed' }} />
      <Tabs.Screen name="(search)" options={{ title: 'Search' }} />
    </Tabs>
  );
}
```
`(feed)` 和 `(search)` 路由组都包含堆栈，因此它们也可以共享单个布局：
¥Both the `(feed)` and `(search)` route groups contain stacks, so they can also share a single layout:
```tsx app/(tabs)/(feed,search)/_layout.tsx
import { Stack } from 'expo-router';
export default function SharedLayout() {
  return <Stack />;
}
```
共享组也可以仅包含共享页面，每个不同的组都有自己的布局文件。
¥It's also possible for shared groups to only contain the shared pages, with each distinct group having its own layout file.
现在，两个标签页都可以导航到 `/users/evanbacon` 并显示相同的用户资料页面。
¥Now, both tabs can navigate to `/users/evanbacon` and see the same user profile page.
当你已将焦点放在某个选项卡上并导航到某个用户时，你将停留在当前选项卡的组中。但是，当从应用外部直接深度链接到用户个人资料页面时，Expo Router 必须从两个组中选择一个，因此它将按字母顺序选择第一个组。因此，深度链接到 `/users/evanbacon` 将在“Feed”选项卡中显示用户配置文件。
¥When you're already focused on a tab and navigating to a user, you will stay in that current tab's group. But when deep-linking directly to a user profile page from outside the app, Expo Router has to pick one of the two groups, so it will pick the first group alphabetically. Therefore, deep-linking to `/users/evanbacon` will show the user profile in the Feed tab.
<a id="authenticated-users-only-protected-routes"></a>
## 仅限已验证用户：受保护的路由
¥Authenticated users only: protected routes
对于需要身份验证的移动应用，你可能会有一组只能由经过身份验证的用户访问的路由。
¥For mobile apps requiring authentication, you will likely have a set of routes that should only be accessible to authenticated users.
例如，考虑以下导航树，其中有一个底部选项卡布局、一个登录页面、一个创建账户页面和一个仅对经过身份验证的用户可见的模态窗口：
¥For example, consider the following navigation tree in which you have a bottom tabs layout, a sign-in page, a create account page, and a modal that should only be visible to authenticated users:
      </span>,
    ],
    [
      'app/(tabs)/settings.tsx',
      <span>
        Protected <Lock01Icon className="mb-1 inline" />
      </span>,
    ],
    ['app/sign-in.tsx'],
    ['app/create-account.tsx'],
    [
      'app/modal.tsx',
      <span>
        Protected <Lock01Icon className="mb-1 inline" />
      </span>,
    ],
  ]}
/>
当你的应用首次启动时，路由将尝试打开根索引 app/(tabs)/index.tsx。如果你将此屏幕与 `guard={false}` 一起封装在 `Stack.Protected` 中，则该屏幕将无法访问，而是会打开下一个可用屏幕。在本例中，`sign-in` 窗口将被打开，因为它是下一个可用路径。
¥When your app is first launched, the router will try to open the root index, **app/(tabs)/index.tsx**. If you wrap this screen in a `Stack.Protected` with the `guard={false}`, the screen will become inaccessible and the next available screen will be opened instead. In this example, the `sign-in` screen will be opened, since it is the next available route.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
import { useAuthState } from '@/utils/authState';
export default function RootLayout() {
  const { isLoggedIn } = useAuthState();
  return (
    <Stack>
      <Stack.Protected guard={isLoggedIn}>
        <Stack.Screen name="(tabs)" />
        <Stack.Screen name="modal" />
      </Stack.Protected>
      <Stack.Protected guard={!isLoggedIn}>
        <Stack.Screen name="sign-in" />
        <Stack.Screen name="create-account" />
      </Stack.Protected>
    </Stack>
  );
}
```
这样，你可以从存储中获取身份验证状态并显示相应的屏幕。如果授权状态发生变化，布局将重新渲染，因此如果 `isLoggedIn` 从 `false` 更改为 `true`，应用将自动导航到 `(tabs)` 组的根目录。
¥This way, you can fetch your auth state from a store and show the appropriate screens. If the auth state changes, the layout will re-render, so if `isLoggedIn` changes from `false` to `true`, the app will automatically navigate to the root of the `(tabs)` group.
受保护路由的另一个好处是，即使你直接深度链接到页面，它们也会被检查。例如，如果未经身份验证的用户深度链接到上面的模态窗口，他们将被重定向到登录页面。
¥Another benefit of protected routes is that they are checked even if you deep link into a page directly. For example, if an unauthenticated user deep links into the modal screen above, they will be redirected to the sign-in page.
受保护的路由也可用于有条件地显示底部标签页。在本例中，`vip` 选项卡仅向经过身份验证的 VIP 会员显示：
¥Protected routes can also be used to conditionally show bottom tabs. In this example, the `vip` tab will only be shown to authenticated users who are VIP members:
```tsx app/(tabs)/_layout.tsx
import { Stack } from 'expo-router';
import { useAuthState } from '@/utils/authState';
export default function TabsLayout() {
  const { isVip } = useAuthState();
  return (
    <Tabs>
      <Tabs.Screen name="index" />
      <Tabs.Protected guard={isVip}>
        <Tabs.Screen name="vip" />
      </Tabs.Protected>
      <Tabs.Screen name="settings" />
    </Tabs>
  );
}
```
<a id="sometimes-the-best-route-isnt-a-route-at-all"></a>
## 有时最佳路由根本不是路由
¥Sometimes the best route isn't a route at all
将导航状态划分为不同的路由是为了更好地服务你和你的应用。有时，最适合该任务的模式根本不涉及导航到其他路由。由于布局文件只是 React 组件，因此你可以使用它们来显示导航器周围、旁边或替代导航器的各种 UI。
¥Separating your navigation states into distinct routes is meant to serve you and your app. Sometimes the best pattern for the job will not involve navigating to another route at all. Since layout files are just React components, you can use them to display all sorts of UI around, besides, or instead of a navigator.
回想一下身份验证，如果用户无法在未登录的情况下访问某些页面，则受保护的路由设置非常有效。但是，当未经身份验证的用户以只读模式浏览应用时该怎么办？在这种情况下，你可能希望在应用上方显示登录模式，而不是将用户重定向到登录页面：
¥Thinking back to authentication, the protected route setup works great if the user should simply not be able to visit certain pages without logging in. But what about when unauthenticated users can browse an app in read-only mode? In that case, you might want to show a login modal over the app, rather than redirecting the user to a login page:
```tsx app/(logged-in)/_layout.tsx
import { SafeAreaView, Modal } from 'react-native';
import { Stack } from 'expo-router';
export default function Layout() {
  const isAuthenticated = /* check for valid auth token / session */
  return (
    <SafeAreaView>
      <Stack />
      <Modal visible={!isAuthenticated}>{/* login UX */}</Modal>
    </SafeAreaView>
  );
}
```


# 导航模式

## 堆

了解如何使用 Expo Router 中的 Stack 导航器。

<VideoBoxLink videoId="izZv6a99Roo" title="Using a Stack Navigator with Expo Router" description="Navigate between screens, pass params between screens, create dynamic routes, and configure the screen titles and animations." className="mb-6" />
堆栈导航器是在应用中的路由之间导航的基本方式。在 Android 上，堆叠路由会在当前屏幕顶部动画。在 iOS 上，堆叠路由从右侧动画显示。Expo Router 提供了一个 `Stack` 导航组件，可创建导航堆栈并允许你在应用中添加新路由。
¥A stack navigator is the foundational way of navigating between routes in an app. On Android, a stacked route animates on top of the current screen. On iOS, a stacked route animates from the right. Expo Router provides a `Stack` navigation component that creates a navigation stack and allows you to add new routes in your app.
本指南提供有关如何在项目中创建 `Stack` 导航器以及自定义单个路由的选项和标题的信息。
¥This guide provides information on how you can create a `Stack` navigator in your project and customize an individual route's options and header.
<a id="get-started"></a>
## 开始使用
¥Get started
你可以使用基于文件的路由来创建堆栈导航器。这是一个示例文件结构：
¥You can use file-based routing to create a stack navigator. Here's an example file structure:
此文件结构生成一个布局，其中 `index` 路由是堆栈中的第一个路由，而 `details` 路由在导航时被推到 `index` 路由的顶部。
¥This file structure produces a layout where the `index` route is the first route in the stack, and the `details` route is pushed on top of the `index` route when navigated.
你可以使用 app/_layout.tsx 文件通过以下两个路由定义应用的 `Stack` 导航器：
¥You can use the **app/_layout.tsx** file to define your app's `Stack` navigator with these two routes:
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function Layout() {
  return <Stack />;
}
```
<a id="screen-options-and-header-configuration"></a>
## 屏幕选项和标题配置
¥Screen options and header configuration
<a id="statically-configure-route-options"></a>
### 静态配置路由选项
¥Statically configure route options
你可以在布局组件路由中使用 `<Stack.Screen name={routeName} />` 组件来静态配置路由的选项。这对 [tabs](/router/advanced/tabs/) 或 [drawers](/router/advanced/drawer/) 也很有用，因为它们需要提前定义图标。
¥You can use the `<Stack.Screen name={routeName} />` component in the layout component route to statically configure a route's options. This is also useful for [tabs](/router/advanced/tabs/) or [drawers](/router/advanced/drawer/) as they need an icon defined ahead of time.
```tsx app/_layout.tsx|collapseHeight=440
import { Stack } from 'expo-router';
export default function Layout() {
  return (
    <Stack
      screenOptions={{
        headerStyle: {
          backgroundColor: '#f4511e',
        },
        headerTintColor: '#fff',
        headerTitleStyle: {
          fontWeight: 'bold',
        },
      }}>
      {/* Optionally configure static options outside the route.*/}
      <Stack.Screen name="home" options={{}} />
    </Stack>
  );
}
```
作为 `<Stack.Screen>` 组件的替代方案，你可以使用 [`navigation.setOptions()`](https://react-navigation.nodejs.cn/docs/navigation-object/#setoptions) 从路由的组件文件中配置路由的选项。
¥As an alternative to the `<Stack.Screen>` component, you can use [`navigation.setOptions()`](https://react-navigation.nodejs.cn/docs/navigation-object/#setoptions) to configure a route's options from within the route's component file.
```tsx app/index.tsx
import { Stack, useNavigation } from 'expo-router';
import { Text, View } from 'react-native';
import { useEffect } from 'react';
export default function Home() {
  const navigation = useNavigation();
  useEffect(() => {
    navigation.setOptions({ headerShown: false });
  }, [navigation]);
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>Home Screen</Text>
    </View>
  );
}
```
<a id="configure-header-bar"></a>
### 配置标题栏
¥Configure header bar
你可以使用 `screenOptions` 属性配置 `Stack` 导航器中所有路由的标题栏。这对于在所有路由上设置通用标题样式很有用。
¥You can configure the header bar for all routes in a `Stack` navigator by using the `screenOptions` prop. This is useful for setting a common header style across all routes.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function Layout() {
  return (
    <Stack
      screenOptions={{
        headerStyle: {
          backgroundColor: '#f4511e',
        },
        headerTintColor: '#fff',
        headerTitleStyle: {
          fontWeight: 'bold',
        },
      }}
    />
  );
}
```
要为单个路由动态配置标题栏，请在路由文件中使用该导航器的 `<Stack.Screen>` 组件。这对于更改 UI 的交互很有用。
¥To configure the header bar dynamically for an individual route, use that navigator's `<Stack.Screen>` component in the routes's file. This is useful for interactions that change the UI.
```tsx app/index.tsx
import { Link, Stack } from 'expo-router';
import { Image, Text, View, StyleSheet } from 'react-native';
function LogoTitle() {
  return (
    <Image style={styles.image} source={{ uri: 'https://rn.nodejs.cn/img/tiny_logo.png' }} />
  );
}
export default function Home() {
  return (
    <View style={styles.container}>
      <Stack.Screen
        options={{
          title: 'My home',
          headerStyle: { backgroundColor: '#f4511e' },
          headerTintColor: '#fff',
          headerTitleStyle: {
            fontWeight: 'bold',
          },
          headerTitle: props => <LogoTitle {...props} />,
        }}
      />
      <Text>Home Screen</Text>
      <Link href={{ pathname: 'details', params: { name: 'Bacon' }}}>Go to Details</Link>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  image: {
    width: 50,
    height: 50,
  },
});
```
<a id="available-header-options"></a>
### 可用的标头选项
¥Available header options
`Stack` 导航器支持全面的标题配置选项。以下是所有可用的标头相关选项：
¥The `Stack` navigator supports comprehensive header configuration options. Below are all the header-related options available:
<ReactNavigationOptions category="header" />
<a id="set-screen-options-dynamically"></a>
### 动态设置屏幕选项
¥Set screen options dynamically
要动态配置路由选项，你始终可以使用该路由文件中的 `<Stack.Screen>` 组件。
¥To configure a route's option dynamically, you can always use the `<Stack.Screen>` component in that route's file.
作为替代方案，你也可以使用 [命令式 API 的 `router.setParams()`](/versions/latest/sdk/router/#router) 函数动态配置路由。
¥As an alternative, you can also use the [imperative API's `router.setParams()`](/versions/latest/sdk/router/#router) function to configure the route dynamically.
```tsx app/details.tsx
import { Stack, useLocalSearchParams, useRouter } from 'expo-router';
import { View, Text, StyleSheet } from 'react-native';
export default function Details() {
  const router = useRouter();
  const params = useLocalSearchParams();
  return (
    <View style={styles.container}>
      <Stack.Screen
        options={{
          title: params.name,
        }}
      />
      <Text
        onPress={() => {
          router.setParams({ name: 'Updated' });
        }}>
        Update the title
      </Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
<a id="header-buttons"></a>
### 标题按钮
¥Header buttons
你可以使用 `headerLeft` 和 `headerRight` 选项向标题添加按钮。这些选项接受在标题中渲染的 React 组件。
¥You can add buttons to the header by using the `headerLeft` and `headerRight` options. These options accept a React component that renders in the header.
```tsx app/index.tsx
import { Stack } from 'expo-router';
import { Button, Text, Image, StyleSheet } from 'react-native';
import { useState } from 'react';
function LogoTitle() {
  return (
    <Image style={styles.image} source={{ uri: 'https://rn.nodejs.cn/img/tiny_logo.png' }} />
  );
}
export default function Home() {
  const [count, setCount] = useState(0);
  return (
    <>
      <Stack.Screen
        options={{
          headerTitle: props => <LogoTitle {...props} />,
          headerRight: () => <Button onPress={() => setCount(c => c + 1)} title="Update count" />,
        }}
      />
      <Text>Count: {count}</Text>
    </>
  );
}
const styles = StyleSheet.create({
  image: {
    width: 50,
    height: 50,
  },
});
```
<a id="other-screen-options"></a>
### 其他屏幕选项
¥Other screen options
有关所有可用其他屏幕选项（包括动画、手势和其他配置）的完整列表：
¥For a complete list of all available other screen options including animations, gestures, and other configurations:
<ReactNavigationOptions excludeCategories={['header']} />
<a id="custom-push-behavior"></a>
## 自定义推送行为
¥Custom push behavior
默认情况下，`Stack` 导航器在推送堆栈中已有的路由时会删除重复的屏幕。例如，如果你两次按下同一个屏幕，第二次按下将被忽略。你可以通过向 `<Stack.Screen>` 提供自定义 `getId()` 函数来更改此推送行为。
¥By default, the `Stack` navigator removes duplicate screens when pushing a route that is already in the stack. For example, if you push the same screen twice, the second push will be ignored. You can change this push behavior by providing a custom `getId()` function to the `<Stack.Screen>`.
例如，以下布局结构中的 `index` 路由显示应用中不同用户配置文件的列表。让我们将 `[details]` 路由设为 [动态路由](/router/basics/notation/#square-brackets)，以便应用用户可以导航查看配置文件的详细信息。
¥For example, the `index` route in the following layout structure shows a list of different user profiles in the app. Let's make the `[details]` route a [dynamic route](/router/basics/notation/#square-brackets) so that the app user can navigate to see a profile's details.
每次应用用户导航到不同的配置文件时，`Stack` 导航器都会推送一个新屏幕，但会失败。如果你提供每次都返回新 ID 的 `getId()` 函数，则每次应用用户导航到个人资料时，`Stack` 都会推送一个新屏幕。
¥The `Stack` navigator will push a new screen every time the app user navigates to a different profile but will fail. If you provide a `getId()` function that returns a new ID every time, the `Stack` will push a new screen every time the app user navigates to a profile.
你可以在布局组件路由中使用 `<Stack.Screen name="[profile]" getId={}>` 组件来修改推送行为：
¥You can use the `<Stack.Screen name="[profile]" getId={}>` component in the layout component route to modify the push behavior:
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen
        name="[profile]"
        getId={
          ({ params }) => String(Date.now())
        }
      />
    </Stack>
  );
}
```
<a id="removing-stack-screens"></a>
## 删除堆栈屏幕
¥Removing stack screens
你可以使用不同的操作来关闭和删除堆栈中的一个或多个路由。
¥There are different actions you can use to dismiss and remove one or many routes from a stack.
<a id="dismiss-action"></a>
### `dismiss` 行动
¥`dismiss` action
关闭最近堆栈中的最后一个屏幕。如果当前屏幕是堆栈中的唯一路由，它将关闭整个堆栈。
¥Dismisses the last screen in the closest stack. If the current screen is the only route in the stack, it will dismiss the entire stack.
你可以选择传递一个正数来关闭指定数量的屏幕。
¥You can optionally pass a positive number to dismiss up to that specified number of screens.
Dismiss 与 `back` 不同，因为它针对最近的堆栈而不是当前导航器。如果你有嵌套导航器，调用 `dismiss` 将带你返回多个屏幕。
¥Dismiss is different from `back` as it targets the closest stack and not the current navigator. If you have nested navigators, calling `dismiss` will take you back multiple screens.
```tsx app/settings.tsx
import { Button, View } from 'react-native';
import { useRouter } from 'expo-router';
export default function Settings() {
  const router = useRouter();
  const handleDismiss = (count: number) => {
    router.dismiss(count)
  };
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button title="Go to first screen" onPress={() => handleDismiss(3)} />
    </View>
  );
}
```
<a id="dismissto-action"></a>
### `dismissTo` 行动
¥`dismissTo` action
> `dismissTo` 已添加到 Expo Router `4.0.8` 中。它的操作类似于 Expo Router v3 中的 `navigation` 函数。
>
> ¥`dismissTo` was added in Expo Router `4.0.8`. It operates similarly to the `navigation` function in Expo Router v3.
在达到指定的 `Href` 之前，关闭当前 `<Stack />` 中的屏幕。如果历史记录中没有 `Href`，则将改为执行 `push` 操作。
¥Dismisses screens in the current `<Stack />` until the specified `Href` is reached. If the `Href` is absent in the history, a `push` action will be performed instead.
例如，考虑 `/one`、`/two`、`/three` 路由的历史记录，其中 `/three` 是当前路由。操作 `router.dismissTo('/one')` 将导致历史记录回溯两次，而 `router.dismissTo('/four')` 将 `push` 历史记录转发到 `/four` 路由。
¥For example, consider the history of `/one`, `/two`, `/three` routes, where `/three` is the current route. The action `router.dismissTo('/one')` will cause the history to go back twice, while `router.dismissTo('/four')` will `push` the history forward to the `/four` route.
```tsx app/settings.tsx
import { Button, View, Text } from 'react-native';
import { useRouter } from 'expo-router';
export default function Settings() {
  const router = useRouter();
  const handleDismissAll = () => {
    router.dismissTo('/')
  };
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button title="Go to first screen" onPress={handleDismissAll} />
    </View>
  );
}
```
<a id="dismissall-action"></a>
### `dismissAll` 行动
¥`dismissAll` action
要返回最近堆栈中的第一个屏幕。这与 [`popToTop`](https://react-navigation.nodejs.cn/docs/stack-actions/#poptotop) 堆栈操作类似。
¥To return to the first screen in the closest stack. This is similar to [`popToTop`](https://react-navigation.nodejs.cn/docs/stack-actions/#poptotop) stack action.
例如，`home` 路由是第一个屏幕，`settings` 是最后一个。要从 `settings` 转到 `home` 路由，你必须返回 `details`。但是，使用 `dismissAll` 操作，你可以从 `settings` 转到 `home` 并关闭中间的任何屏幕。
¥For example, the `home` route is the first screen, and the `settings` is the last. To go from `settings` to `home` route you'll have to go back to `details`. However, using the `dismissAll` action, you can go from `settings` to `home` and dismiss any screen in between.
```tsx app/settings.tsx
import { Button, View, Text } from 'react-native';
import { useRouter } from 'expo-router';
export default function Settings() {
  const router = useRouter();
  const handleDismissAll = () => {
    router.dismissAll()
  };
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button title="Go to first screen" onPress={handleDismissAll} />
    </View>
  );
}
```
<a id="candismiss-action"></a>
### `canDismiss` 行动
¥`canDismiss` action
要检查是否可以关闭当前屏幕。如果路由位于堆栈中，并且堆栈历史记录中有多个屏幕，则返回 `true`。
¥To check if it is possible to dismiss the current screen. Returns `true` if the router is within a stack with more than one screen in the stack's history.
```tsx app/settings.tsx|collapseHeight=410
import { Button, View } from 'react-native';
import { useRouter } from 'expo-router';
export default function Settings() {
  const router = useRouter();
  const handleDismiss = (count: number) => {
    if (router.canDismiss()) {
      router.dismiss(count)
    }
  };
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button title="Maybe dismiss" onPress={() => handleDismiss()} />
    </View>
  );
}
```
<a id="relation-with-native-stack-navigator"></a>
## 与 Native Stack Navigator 的关系
¥Relation with Native Stack Navigator
Expo Router 中的 `Stack` 导航器封装了 React Navigation 中的 [原生堆栈导航器](https://react-navigation.nodejs.cn/docs/native-stack-navigator)。Native Stack Navigator 中可用的选项在 Expo Router 中的 `Stack` 导航器中均可用。
¥The `Stack` navigator in Expo Router wraps the [Native Stack Navigator](https://react-navigation.nodejs.cn/docs/native-stack-navigator) from React Navigation. Options available in the Native Stack Navigator are all available in the `Stack` navigator in Expo Router.
<a id="javascript-stack-with-react-navigationstack"></a>
### 使用 @react-navigation/stack 的 JavaScript 堆栈
¥JavaScript stack with @react-navigation/stack
你还可以使用 JavaScript 驱动的 `@react-navigation/stack` 库通过将此库与 `withLayoutContext` 封装在一起来创建自定义布局组件。
¥You can also use the JavaScript-powered `@react-navigation/stack` library to create a custom layout component by wrapping this library with the `withLayoutContext`.
在以下示例中，`JsStack` 组件是使用 `@react-navigation/stack` 库定义的：
¥In the following example, `JsStack` component is defined using `@react-navigation/stack` library:
```tsx layouts/js-stack.tsx
import { ParamListBase, StackNavigationState } from '@react-navigation/native';
import {
  createStackNavigator,
  StackNavigationEventMap,
  StackNavigationOptions,
} from '@react-navigation/stack';
import { withLayoutContext } from 'expo-router';
const { Navigator } = createStackNavigator();
export const JsStack = withLayoutContext<
  StackNavigationOptions,
  typeof Navigator,
  StackNavigationState<ParamListBase>,
  StackNavigationEventMap
>(Navigator);
```
定义 `JsStack` 组件后，你可以在应用中使用它：
¥After defining the `JsStack` component, you can use it in your app:
```tsx app/_layout.tsx
import { JsStack } from '../layouts/js-stack';
export default function Layout() {
  return (
    <JsStack
      screenOptions={
        {
        }
      }
    />
  );
}
```
有关可用选项的更多信息，请参阅 [`@react-navigation/stack` 文档](https://react-navigation.nodejs.cn/docs/stack-navigator)。
¥For more information on available options, see [`@react-navigation/stack` documentation](https://react-navigation.nodejs.cn/docs/stack-navigator).


## 选项卡

了解如何在 Expo Router 中使用选项卡布局。

<VideoBoxLink videoId="BElPB4Ai3j0" title="Using a Tab Navigator with Expo Router" description="Configure the tab icons, nest navigators, and manage navigation history." className="mb-6" />
选项卡是在应用的不同部分之间导航的常用方式。Expo Router 提供选项卡布局，帮助你在应用底部创建选项卡栏。最快的入门方法是使用模板。请参阅 [快速开始安装](/router/installation/#quick-start) 以开始使用。
¥Tabs are a common way to navigate between different sections of an app. Expo Router provides a tabs layout to help you create a tab bar at the bottom of your app. The fastest way to get started is to use a template. See the [quick start installation](/router/installation/#quick-start) to get started.
继续阅读以向现有项目添加选项卡或自定义应用的选项卡。
¥Continue reading to add tabs to an existing project or to customize your app's tabs.
<a id="get-started"></a>
## 开始使用
¥Get started
你可以使用基于文件的路由来创建选项卡布局。这是一个示例文件结构：
¥You can use file-based routing to create a tabs layout. Here's an example file structure:
此文件结构在屏幕底部生成带有标签栏的布局。选项卡栏将有两个选项卡：主页和设置：
¥This file structure produces a layout with a tab bar at the bottom of the screen. The tab bar will have two tabs: **Home** and **Settings**:
你可以使用 app/_layout.tsx 文件定义应用的根布局：
¥You can use the **app/_layout.tsx** file to define your app's root layout:
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
    </Stack>
  );
}
```
(tabs) 目录是一个特殊的目录名称，它告诉 Expo Router 使用 `Tabs` 布局。
¥The **(tabs)** directory is a special directory name that tells Expo Router to use the `Tabs` layout.
从文件结构来看，（tabs）目录有三个文件。第一个是 (tabs)/_layout.tsx。该文件是选项卡栏和每个选项卡的主要布局文件。在其中，你可以控制选项卡栏和每个选项卡按钮的外观和行为。
¥From the file structure, the **(tabs)** directory has three files. The first is **(tabs)/_layout.tsx**. This file is the main layout file for the tab bar and each tab. Inside it, you can control how the tab bar and each tab button look and behave.
```tsx app/(tabs)/_layout.tsx
import FontAwesome from '@expo/vector-icons/FontAwesome';
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs screenOptions={{ tabBarActiveTintColor: 'blue' }}>
      <Tabs.Screen
        name="index"
        options={{
          title: 'Home',
          tabBarIcon: ({ color }) => <FontAwesome size={28} name="home" color={color} />,
        }}
      />
      <Tabs.Screen
        name="settings"
        options={{
          title: 'Settings',
          tabBarIcon: ({ color }) => <FontAwesome size={28} name="cog" color={color} />,
        }}
      />
    </Tabs>
  );
}
```
最后，你拥有构成选项卡内容的两个选项卡文件：app/(tabs)/index.tsx 和 app/(tabs)/settings.tsx。
¥Finally, you have the two tab files that make up the content of the tabs: **app/(tabs)/index.tsx** and **app/(tabs)/settings.tsx**.
```tsx app/(tabs)/index.tsx & app/(tabs)/settings.tsx
import { View, Text, StyleSheet } from 'react-native';
export default function Tab() {
  return (
    <View style={styles.container}>
      <Text>Tab [Home|Settings]</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
名为 index.tsx 的选项卡文件是应用加载时的默认选项卡。第二个选项卡文件 settings.tsx 显示了如何向选项卡栏添加更多选项卡。
¥The tab file named **index.tsx** is the default tab when the app loads. The second tab file **settings.tsx** shows how you can add more tabs to the tab bar.
<a id="screen-options"></a>
## 屏幕选项
¥Screen options
选项卡布局封装了 React Navigation 中的 [底部选项卡导航器](https://react-navigation.nodejs.cn/docs/bottom-tab-navigator)。你可以使用 [组织账户 成员设置](https://react-navigation.nodejs.cn/docs/bottom-tab-navigator/#options) 自定义选项卡栏或每个选项卡。
¥The tabs layout wraps the [Bottom Tabs Navigator](https://react-navigation.nodejs.cn/docs/bottom-tab-navigator) from React Navigation. You can use the [options presented in the React Navigation documentation](https://react-navigation.nodejs.cn/docs/bottom-tab-navigator/#options) to customize the tab bar or each tab.
<a id="advanced"></a>
## 高级
¥Advanced
<a id="hiding-a-tab"></a>
### 隐藏选项卡
¥Hiding a tab
有时你希望路由存在但不显示在标签栏中。你可以传递 `href: null` 来禁用按钮：
¥Sometimes you want a route to exist but not show up in the tab bar. You can pass `href: null` to disable the button:
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs>
      <Tabs.Screen
        name="index"
        options={{
          href: null,
        }}
      />
    </Tabs>
  );
}
```
<a id="dynamic-routes"></a>
### 动态路由
¥Dynamic routes
你可以在标签栏中使用动态路由。例如，你有一个显示用户个人资料的 `[user]` 选项卡。你可以使用 `href` 选项链接到特定用户的个人资料。
¥You can use a dynamic route in a tab bar. For example, you have a `[user]` tab that shows a user's profile. You can use the `href` option to link to a specific user's profile.
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs>
      <Tabs.Screen
        // Name of the dynamic route.
        name="[user]"
        options={{
          // Ensure the tab always links to the same href.
          href: '/evanbacon',
          // OR you can use the href object.
          href: {
            pathname: '/[user]',
            params: {
              user: 'evanbacon',
            },
          },
        }}
      />
    </Tabs>
  );
}
```
> 注意：在选项卡布局中添加动态路由时，请确保定义的动态路由是唯一的。你不能为同一个动态路由设置两个屏幕。例如，你不能有两个 `[user]` 选项卡。如果你需要多个动态路由，请创建自定义导航器。
>
> ¥**Note**: When adding a dynamic route in your tab layout, ensure that the dynamic route defined is unique. You cannot have two screens for the same dynamic route. For example, you cannot have two `[user]` tabs. If you need to have multiple dynamic routes, create a custom navigator.


## 抽屉

了解如何在 Expo Router 中使用抽屉布局。

要使用 [抽屉导航器](https://react-navigation.nodejs.cn/docs/drawer-based-navigation)，你需要安装一些额外的依赖。
¥To use [drawer navigator](https://react-navigation.nodejs.cn/docs/drawer-based-navigation) you'll need to install some extra dependencies.
<a id="installation"></a>
## 安装
¥Installation
```sh
$ npx expo install @react-navigation/drawer react-native-gesture-handler react-native-reanimated
```
无需额外配置。当你安装库时，[重新启动 Babel 插件](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#reanimated-babel-plugin) 会自动在 `babel-preset-expo` 中配置。
¥No additional configuration is required. [Reanimated Babel plugin](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#reanimated-babel-plugin) is automatically configured in `babel-preset-expo` when you install the library.
<a id="usage"></a>
## 用法
¥Usage
现在你可以使用 `Drawer` 布局来创建抽屉式导航器。你需要将 `<Drawer />` 封装在 `<GestureHandlerRootView>` 中才能启用手势。你的组件树中只需要一个 `<GestureHandlerRootView>`。任何嵌套路由都不需要单独封装。
¥Now you can use the `Drawer` layout to create a drawer navigator. You'll need to wrap the `<Drawer />` in a `<GestureHandlerRootView>` to enable gestures. You only need one `<GestureHandlerRootView>` in your component tree. Any nested routes are not required to be wrapped individually.
```tsx app/_layout.tsx
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { Drawer } from 'expo-router/drawer';
export default function Layout() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <Drawer />
    </GestureHandlerRootView>
  );
}
```
要编辑抽屉式导航菜单标签、标题和屏幕选项，需要特定屏幕，如下所示：
¥To edit the drawer navigation menu labels, titles and screen options specific screens are required as follows:
```tsx app/_layout.tsx
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { Drawer } from 'expo-router/drawer';
export default function Layout() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <Drawer>
        <Drawer.Screen
          name="index" // This is the name of the page and must match the url from root
          options={{
            drawerLabel: 'Home',
            title: 'overview',
          }}
        />
        <Drawer.Screen
          name="user/[id]" // This is the name of the page and must match the url from root
          options={{
            drawerLabel: 'User',
            title: 'overview',
          }}
        />
      </Drawer>
    </GestureHandlerRootView>
  );
}
```
> 注意：在网络上使用 `react-native-gesture-handler` 时要小心。它可以显着增加 JavaScript 包的大小。了解有关使用 [特定于平台的模块](/router/advanced/platform-specific-modules/) 的更多信息。
>
> ¥**Note:** Be careful when using `react-native-gesture-handler` on the web. It can increase the JavaScript bundle size significantly. Learn more about using [platform-specific modules](/router/advanced/platform-specific-modules/).


## Expo 路由中的身份验证

如何使用 Expo Router 实现身份验证和保护路由。

>  **info** **注意：**本指南需要 SDK 53。有关本指南的先前版本，请参阅 [身份验证（重定向）](/router/advanced/authentication-rewrites/)。
>
> ¥**Note:**This guide requires SDK 53. For the previous version of this guide see [Authentication (redirects)](/router/advanced/authentication-rewrites/).
借助 Expo Router，所有路由均已定义且可访问。你可以使用运行时逻辑将用户重定向到特定屏幕，具体取决于用户是否经过身份验证。有两种不同的技术可用于对路由内的用户进行身份验证。本指南提供了一个示例，演示标准原生应用的功能。
¥With Expo Router, all routes are always defined and accessible. You can use runtime logic to redirect users away from specific screens depending on whether they are authenticated. There are two different techniques for authenticating users within routes. This guide provides an example that demonstrates the functionality of standard native apps.
<a id="using-protected-routes"></a>
## 使用受保护的路由
¥Using Protected Routes
[受保护的路由](/router/advanced/protected/) 允许你阻止用户使用客户端导航访问某些路由。如果用户尝试导航到受保护的屏幕，或者如果屏幕在活动状态下受到保护，他们将被重定向到锚点路由（通常是索引屏幕）或堆栈中第一个可用的屏幕。考虑以下项目结构，其中具有始终可访问的 `/sign-in` 路由和需要身份验证的 `(app)` 组：
¥[Protected routes](/router/advanced/protected/) allow you to prevent users from accessing certain routes using client-side navigation. If a user tries to navigate to a protected screen, or if a screen becomes protected while it is active, they will be redirected to the anchor route (usually the index screen) or the first available screen in the stack. Consider the following project structure that has a `/sign-in` route that is always accessible and a `(app)` group that requires authentication:
      </span>,
    ],
    [
      'app/(app)/_layout.tsx',
      <span>
        Requires authorization <Lock01Icon className="mb-1 inline" />
      </span>,
    ],
    ['app/(app)/index.tsx', <span>Should be protected by the (app)/_layout</span>],
  ]}
/>
Step 1: 
To follow the above example, set up a [React Context provider](https://react.nodejs.cn/reference/react/createContext) that can expose an authentication session to the entire app. You can implement your custom authentication session provider or use the one from the **Example authentication context** below.
Note: Example authentication context
---
This provider uses a mock implementation. You can replace it with your own [authentication provider](/guides/authentication/).
```tsx ctx.tsx
import { use, createContext, type PropsWithChildren } from 'react';
import { useStorageState } from './useStorageState';
const AuthContext = createContext<{
  signIn: () => void;
  signOut: () => void;
  session?: string | null;
  isLoading: boolean;
}>({
  signIn: () => null,
  signOut: () => null,
  session: null,
  isLoading: false,
});
// This hook can be used to access the user info.
export function useSession() {
  const value = use(AuthContext);
  if (!value) {
    throw new Error('useSession must be wrapped in a <SessionProvider />');
  }
  return value;
}
export function SessionProvider({ children }: PropsWithChildren) {
  const [[isLoading, session], setSession] = useStorageState('session');
  return (
    <AuthContext
      value={{
        signIn: () => {
          // Perform sign-in logic here
          setSession('xxx');
        },
        signOut: () => {
          setSession(null);
        },
        session,
        isLoading,
      }}>
      {children}
    </AuthContext>
  );
}
```
The following code snippet is a basic hook that persists tokens securely on native with [`expo-secure-store`](/versions/latest/sdk/securestore) and in local storage on web.
```tsx useStorageState.ts
import  { useEffect, useCallback, useReducer } from 'react';
import * as SecureStore from 'expo-secure-store';
import { Platform } from 'react-native';
type UseStateHook<T> = [[boolean, T | null], (value: T | null) => void];
function useAsyncState<T>(
  initialValue: [boolean, T | null] = [true, null],
): UseStateHook<T> {
  return useReducer(
    (state: [boolean, T | null], action: T | null = null): [boolean, T | null] => [false, action],
    initialValue
  ) as UseStateHook<T>;
}
export async function setStorageItemAsync(key: string, value: string | null) {
  if (Platform.OS === 'web') {
    try {
      if (value === null) {
        localStorage.removeItem(key);
      } else {
        localStorage.setItem(key, value);
      }
    } catch (e) {
      console.error('Local storage is unavailable:', e);
    }
  } else {
    if (value == null) {
      await SecureStore.deleteItemAsync(key);
    } else {
      await SecureStore.setItemAsync(key, value);
    }
  }
}
export function useStorageState(key: string): UseStateHook<string> {
  // Public
  const [state, setState] = useAsyncState<string>();
  // Get
  useEffect(() => {
    if (Platform.OS === 'web') {
      try {
        if (typeof localStorage !== 'undefined') {
          setState(localStorage.getItem(key));
        }
      } catch (e) {
        console.error('Local storage is unavailable:', e);
      }
    } else {
      SecureStore.getItemAsync(key).then(value => {
        setState(value);
      });
    }
  }, [key]);
  // Set
  const setValue = useCallback(
    (value: string | null) => {
      setState(value);
      setStorageItemAsync(key, value);
    },
    [key]
  );
  return [state, setValue];
}
```
---
Step 2: 
Create a **SplashScreenController** to manage the splash screen. Because loading the authentication is asynchronous we can keep the splash screen visible until the authentication has loaded.
```tsx splash.tsx
import { SplashScreen } from 'expo-router';
import { useSession } from './ctx';
export function SplashScreenController() {
  const { isLoading } = useSession();
  if (!isLoading) {
    SplashScreen.hideAsync();
  }
  return null;
}
```
Step 3: 
Use the **SessionProvider** in the root layout to provide the authentication context to the entire app. Ensure the **SplashScreenController** is inside the **SessionProvider**
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
import { SessionProvider } from '../ctx';
import { SplashScreenController } from '../splash';
export default function Root() {
  // Set up the auth context and render our layout inside of it.
  return (
    <SessionProvider>
      <SplashScreenController />
      <RootNavigator />
    </SessionProvider>
  );
}
// Separate this into a new component so it can access the SessionProvider context later
function RootNavigator() {
  return <Stack />;
}
```
Step 4: 
Create the `/sign-in` screen. It can toggle the authentication using `signIn()`. Since this screen is outside the `(app)` group, the group's layout and authentication check do not run when rendering this screen. This lets logged-out users see this screen.
```tsx app/sign-in.tsx|collapseHeight=480
import { router } from 'expo-router';
import { Text, View } from 'react-native';
import { useSession } from '../ctx';
export default function SignIn() {
  const { signIn } = useSession();
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text
        onPress={() => {
          signIn();
          // Navigate after signing in. You may want to tweak this to ensure sign-in is
          // successful before navigating.
          router.replace('/');
        }}>
        Sign In
      </Text>
    </View>
  );
}
```
Step 5: 
Now we can modify the `<RootNavigator />` to protect routes based on our SessionProvider.
```tsx app/_layout.tsx|collapseHeight=400
/* Keep the code the same above, just edit the RootNavigator */
function RootNavigator() {
  const { session } = useSession();
  return (
    <Stack>
      <Stack.Protected guard={session}>
        <Stack.Screen name="(app)" />
      </Stack.Protected>
      <Stack.Protected guard={!session}>
        <Stack.Screen name="sign-in" />
      </Stack.Protected>
    </Stack>
  );
}
```
Step 6: 
Implement an authenticated screen that lets users sign out.
```tsx app/(app)/index.tsx|collapseHeight=480
import { Text, View } from 'react-native';
import { useSession } from '../../ctx';
export default function Index() {
  const { signOut } = useSession();
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text
        onPress={() => {
          // The `app/(app)/_layout.tsx` will redirect to the sign-in screen.
          signOut();
        }}>
        Sign Out
      </Text>
    </View>
  );
}
```
You now have an app that will present the splash screen until the initial authentication state has loaded and will redirects to the sign-in screen if the user is not authenticated. If a user visits a deep link to any routes with the authentication check, they'll be redirected to the sign-in screen.
## Modals and per-route authentication
Another common pattern is to render a sign-in modal over the top of the app. This enables you to dismiss and partially preserve deep links when the authentication is complete. However, this pattern requires routes to be rendered in the background as these routes require handling data loading without authentication.
      </span>,
    ],
  ]}
/>
```tsx app/(app)/_layout.tsx|collapseHeight=480
import { Stack } from 'expo-router';
export const unstable_settings = {
  initialRouteName: '(root)',
};
export default function AppLayout() {
  return (
    <Stack>
      <Stack.Screen name="(root)" />
      <Stack.Screen
        name="sign-in"
        options={{
          presentation: 'modal',
        }}
      />
    </Stack>
  );
}
```
## More information
For more information, read the [Protected routes documentation](/router/advanced/protected/) to learn more patterns
<VideoBoxLink
  videoId="XCTaMu0qnFY"
  title="How to use Protected Routes in Expo Router V5 for smooth auth"
  description="Learn how to use Protected Routes in Expo Router V5 to create an authentication flow"
  className="mb-6"
/>
<a id="middleware"></a>
## 中间件
¥Middleware
传统上，网站可能会利用某种形式的服务器端重定向来保护路由。Web 上的 Expo Router 目前仅支持构建时静态生成，不支持自定义中间件或服务。将来可以添加此功能，以提供更优化的网络体验。同时，可以通过客户端重定向和加载状态来实现身份验证。
¥Traditionally, websites may leverage some form of server-side redirection to protect routes. Expo Router on the web currently only supports build-time static generation and has no support for custom middleware or serving. This can be added in the future to provide a more optimal web experience. In the meantime, authentication can be implemented by using client-side redirects and a loading state.


## 在 Expo Router 中使用重定向进行身份验证

如何使用 Expo Router 实现身份验证和保护路由。

> SDK 53 引入了 [受保护的路由](/router/advanced/protected/)，一种更强大的身份验证处理方法。如果使用 SDK 53 以上版本，请遵循本指南。
>
> ¥SDK 53 introduced [Protected routes](/router/advanced/protected/), a more powerful method of handling authentication. Please follow this guide if using SDK >53.
<VideoBoxLink videoId="yNaOaR2kIa0" title="Building an Auth Flow with Expo Router" description="Learn how to implement an auth flow in your Expo Router project." className="mb-6" />
借助 Expo Router，所有路由均已定义且可访问。你可以使用运行时逻辑将用户重定向到特定屏幕，具体取决于用户是否经过身份验证。有两种不同的技术可用于对路由内的用户进行身份验证。本指南提供了一个示例，演示标准原生应用的功能。
¥With Expo Router, all routes are always defined and accessible. You can use runtime logic to redirect users away from specific screens depending on whether they are authenticated. There are two different techniques for authenticating users within routes. This guide provides an example that demonstrates the functionality of standard native apps.
<a id="using-react-context-and-route-groups"></a>
## 使用 React 上下文和路由组
¥Using React Context and Route Groups
将特定路由限制为未经身份验证的用户是很常见的。这可以通过使用 React Context 和 Route Groups 以有组织的方式实现。考虑以下项目结构，其中具有始终可访问的 `/sign-in` 路由和需要身份验证的 `(app)` 组：
¥It's common to restrict specific routes to users who are not authenticated. This is achievable in an organized way by using React Context and Route Groups. Consider the following project structure that has a `/sign-in` route that is always accessible and a `(app)` group that requires authentication:
      </span>,
    ],
    ['app/(app)/_layout.tsx', <span>Protects child routes</span>],
    [
      'app/(app)/index.tsx',
      <span>
        Requires authorization <Lock01Icon className="mb-1 inline" />
      </span>,
    ],
  ]}
/>
Step 1: 
To follow the above example, set up a [React Context provider](https://react.nodejs.cn/reference/react/createContext) that can expose an authentication session to the entire app. You can implement your custom authentication session provider or use the one from the **Example authentication context** below.
Note: Example authentication context
---
This provider uses a mock implementation. You can replace it with your own [authentication provider](/guides/authentication/).
```tsx ctx.tsx
import { use, createContext, type PropsWithChildren } from 'react';
import { useStorageState } from './useStorageState';
const AuthContext = createContext<{
  signIn: () => void;
  signOut: () => void;
  session?: string | null;
  isLoading: boolean;
}>({
  signIn: () => null,
  signOut: () => null,
  session: null,
  isLoading: false,
});
// This hook can be used to access the user info.
export function useSession() {
  const value = use(AuthContext);
  if (!value) {
    throw new Error('useSession must be wrapped in a <SessionProvider />');
  }
  return value;
}
export function SessionProvider({ children }: PropsWithChildren) {
  const [[isLoading, session], setSession] = useStorageState('session');
  return (
    <AuthContext
      value={{
        signIn: () => {
          // Perform sign-in logic here
          setSession('xxx');
        },
        signOut: () => {
          setSession(null);
        },
        session,
        isLoading,
      }}>
      {children}
    </AuthContext>
  );
}
```
The following code snippet is a basic hook that persists tokens securely on native with [`expo-secure-store`](/versions/latest/sdk/securestore) and in local storage on web.
```tsx useStorageState.ts
import  { useEffect, useCallback, useReducer } from 'react';
import * as SecureStore from 'expo-secure-store';
import { Platform } from 'react-native';
type UseStateHook<T> = [[boolean, T | null], (value: T | null) => void];
function useAsyncState<T>(
  initialValue: [boolean, T | null] = [true, null],
): UseStateHook<T> {
  return useReducer(
    (state: [boolean, T | null], action: T | null = null): [boolean, T | null] => [false, action],
    initialValue
  ) as UseStateHook<T>;
}
export async function setStorageItemAsync(key: string, value: string | null) {
  if (process.env.EXPO_OS === 'web') {
    if (value === null) {
      localStorage.removeItem(key);
    } else {
      localStorage.setItem(key, value);
    }
  } else {
    if (value == null) {
      await SecureStore.deleteItemAsync(key);
    } else {
      await SecureStore.setItemAsync(key, value);
    }
  }
}
export function useStorageState(key: string): UseStateHook<string> {
  // Public
  const [state, setState] = useAsyncState<string>();
  // Get
  useEffect(() => {
    if (Platform.OS === 'web') {
      try {
        if (typeof localStorage !== 'undefined') {
          setState(localStorage.getItem(key));
        }
      } catch (e) {
        console.error('Local storage is unavailable:', e);
      }
    } else {
      SecureStore.getItemAsync(key).then(value => {
        setState(value);
      });
    }
  }, [key]);
  // Set
  const setValue = useCallback(
    (value: string | null) => {
      setState(value);
      setStorageItemAsync(key, value);
    },
    [key]
  );
  return [state, setValue];
}
```
---
Step 2: 
Use the `SessionProvider` in the root layout to provide the authentication context to the entire app. It's imperative that the `<Slot />` is mounted before any navigation events are triggered. Otherwise, a runtime error will be thrown.
```tsx app/_layout.tsx
import { Slot } from 'expo-router';
import { SessionProvider } from '../ctx';
export default function Root() {
  // Set up the auth context and render our layout inside of it.
  return (
    <SessionProvider>
      <Slot />
    </SessionProvider>
  );
}
```
Step 3: 
Create a nested [layout route](/router/basics/layout/) that checks whether users are authenticated before rendering the child route components. This layout route redirects users to the sign-in screen if they are not authenticated.
```tsx app/(app)/_layout.tsx|collapseHeight=400
import { Text } from 'react-native';
import { Redirect, Stack } from 'expo-router';
import { useSession } from '../../ctx';
export default function AppLayout() {
  const { session, isLoading } = useSession();
  // You can keep the splash screen open, or render a loading screen like we do here.
  if (isLoading) {
    return <Text>Loading...</Text>;
  }
  // Only require authentication within the (app) group's layout as users
  // need to be able to access the (auth) group and sign in again.
  if (!session) {
    // On web, static rendering will stop here as the user is not authenticated
    // in the headless Node process that the pages are rendered in.
    return <Redirect href="/sign-in" />;
  }
  // This layout can be deferred because it's not the root layout.
  return <Stack />;
}
```
Step 4: 
Create the `/sign-in` screen. It can toggle the authentication using `signIn()`. Since this screen is outside the `(app)` group, the group's layout and authentication check do not run when rendering this screen. This lets logged-out users see this screen.
```tsx app/sign-in.tsx|collapseHeight=480
import { router } from 'expo-router';
import { Text, View } from 'react-native';
import { useSession } from '../ctx';
export default function SignIn() {
  const { signIn } = useSession();
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text
        onPress={() => {
          signIn();
          // Navigate after signing in. You may want to tweak this to ensure sign-in is
          // successful before navigating.
          router.replace('/');
        }}>
        Sign In
      </Text>
    </View>
  );
}
```
Step 5: 
Implement an authenticated screen that lets users sign out.
```tsx app/(app)/index.tsx|collapseHeight=480
import { Text, View } from 'react-native';
import { useSession } from '../../ctx';
export default function Index() {
  const { signOut } = useSession();
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text
        onPress={() => {
          // The `app/(app)/_layout.tsx` will redirect to the sign-in screen.
          signOut();
        }}>
        Sign Out
      </Text>
    </View>
  );
}
```
现在，你拥有一个可以在检查初始身份验证状态时渲染加载状态的应用，并在用户未通过身份验证时重定向到登录屏幕。如果用户访问任何经过身份验证检查的路由的深层链接，他们将被重定向到登录屏幕。
¥You now have an app that can present a loading state while it checks the initial authentication state and redirects to the sign-in screen if the user is not authenticated. If a user visits a deep link to any routes with the authentication check, they'll be redirected to the sign-in screen.
<a id="alternative-loading-states"></a>
## 替代加载状态
¥Alternative loading states
使用 Expo Router，在加载初始身份验证状态时必须将某些内容渲染到屏幕上。在上面的示例中，应用布局渲染一条加载消息。或者，你可以将 `index` 路由设为加载状态，并将初始路由移动到 `/home` 之类的路由，这与 X 的工作方式类似。
¥With Expo Router, something must be rendered to the screen while loading the initial auth state. In the example above, the app layout renders a loading message. Alternatively, you can make the `index` route a loading state and move the initial route to something such as `/home`, which is similar to how X works.
<a id="modals-and-per-route-authentication"></a>
## 模态和每条路由的身份验证
¥Modals and per-route authentication
另一种常见模式是在应用顶部渲染登录模式。这使你能够在身份验证完成后关闭并部分保留深层链接。但是，此模式要求在后台渲染路由，因为这些路由需要在没有身份验证的情况下处理数据加载。
¥Another common pattern is to render a sign-in modal over the top of the app. This enables you to dismiss and partially preserve deep links when the authentication is complete. However, this pattern requires routes to be rendered in the background as these routes require handling data loading without authentication.
      </span>,
    ],
  ]}
/>
```tsx app/(app)/_layout.tsx|collapseHeight=480
import { Stack } from 'expo-router';
export const unstable_settings = {
  anchor: '(root)',
};
export default function AppLayout() {
  return (
    <Stack>
      <Stack.Screen name="(root)" />
      <Stack.Screen
        name="sign-in"
        options={{
          presentation: 'modal',
        }}
      />
    </Stack>
  );
}
```
<a id="navigating-without-navigation"></a>
## 无需导航即可导航
¥Navigating without navigation
当应用尝试在 [根布局](/router/basics/layout/#root-layout) 中未安装导航器的情况下执行导航时，你可能会遇到以下错误。
¥You may encounter the following error when the app attempts to perform navigation without a navigator mounted in the [root layout](/router/basics/layout/#root-layout).
```text
Error: Attempted to navigate before mounting the Root Layout component. Ensure the Root Layout component is rendering a Slot, or other navigator on the first render.
```
要解决此问题，请添加一个组并将条件逻辑下移一个级别。
¥To fix this, add a group and move conditional logic down a level.
<a id="before"></a>
### 之前
¥Before
```tsx app/_layout.tsx
export default function RootLayout() {
  React.useEffect(() => {
    // This navigation event will trigger the error above.
    router.push('/about');
  }, []);
  // This conditional statement creates a problem since the root layout's
  // content (the Slot) must be mounted before any navigation events occur.
  if (isLoading) {
    return <Text>Loading...</Text>;
  }
  return <Slot />;
}
```
<a id="after"></a>
### 之后
¥After
```tsx app/_layout.tsx
export default function RootLayout() {
  return <Slot />;
}
```
```tsx app/(app)/_layout.tsx
export default function RootLayout() {
  React.useEffect(() => {
    router.push('/about');
  }, []);
  // It is OK to defer rendering this nested layout's content. We couldn't
  // defer rendering the root layout's content since a navigation event (the
  // redirect) would have been triggered before the root layout's content had
  // been mounted.
  if (isLoading) {
    return <Text>Loading...</Text>;
  }
  return <Slot />;
}
```
<a id="middleware"></a>
## 中间件
¥Middleware
传统上，网站可能会利用某种形式的服务器端重定向来保护路由。Web 上的 Expo Router 目前仅支持构建时静态生成，不支持自定义中间件或服务。将来可以添加此功能，以提供更优化的网络体验。同时，可以通过客户端重定向和加载状态来实现身份验证。
¥Traditionally, websites may leverage some form of server-side redirection to protect routes. Expo Router on the web currently only supports build-time static generation and has no support for custom middleware or serving. This can be added in the future to provide a more optimal web experience. In the meantime, authentication can be implemented by using client-side redirects and a loading state.


## 嵌套导航器

了解如何在 Expo Router 中嵌套导航器。

>  **warning** 导航 UI 元素（链接、选项卡、堆栈）将来可能会从 Expo Router 库中移出。
>
> ¥Navigation UI elements (Link, Tabs, Stack) may move out of the Expo Router library in the future.
<VideoBoxLink videoId="izZv6a99Roo" title="Using a Stack Navigator with Expo Router" description="Navigate between screens, pass params between screens, create dynamic routes, and configure the screen titles and animations." className="mb-6" />
嵌套导航器允许在另一个导航器的屏幕内渲染一个导航器。本指南是 [反应导航：嵌套导航器](https://react-navigation.nodejs.cn/docs/nesting-navigators) 对 Expo Router 的扩展。它提供了使用 Expo Router 时嵌套导航器如何工作的示例。
¥Nesting navigators allow rendering a navigator inside the screen of another navigator. This guide is an extension of [React Navigation: Nesting navigators](https://react-navigation.nodejs.cn/docs/nesting-navigators) to Expo Router. It provides an example of how nesting navigators work when using Expo Router.
<a id="example"></a>
## 示例
¥Example
考虑以下用作示例的文件结构：
¥Consider the following file structure which is used as an example:
在上面的例子中，app/home/feed.tsx 匹配 `/home/feed`，app/home/messages.tsx 匹配 `/home/messages`。
¥In the above example, **app/home/feed.tsx** matches `/home/feed`, and **app/home/messages.tsx** matches `/home/messages`.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default Stack;
```
下面的 app/home/_layout.tsx 和 app/index.tsx 都嵌套在 app/_layout.tsx 布局中，因此它将被渲染为堆栈。
¥Both **app/home/_layout.tsx** and **app/index.tsx** below are nested in the **app/_layout.tsx** layout so that it will be rendered as a stack.
```tsx app/home/_layout.tsx
import { Tabs } from 'expo-router';
export default Tabs;
```
```tsx app/index.tsx
import { Link } from 'expo-router';
export default function Root() {
  return <Link href="/home/messages">Navigate to nested route</Link>;
}
```
下面的 app/home/feed.tsx 和 app/home/messages.tsx 都嵌套在 home/_layout.tsx 布局中，因此它将被渲染为选项卡。
¥Both **app/home/feed.tsx** and **app/home/messages.tsx** below are nested in the **home/_layout.tsx** layout, so it will be rendered as a tab.
```tsx app/home/feed.tsx
import { View, Text } from 'react-native';
export default function Feed() {
  return (
    <View>
      <Text>Feed screen</Text>
    </View>
  );
}
```
```tsx app/home/messages.tsx
import { View, Text } from 'react-native';
export default function Messages() {
  return (
    <View>
      <Text>Messages screen</Text>
    </View>
  );
}
```
<a id="navigate-to-a-screen-in-a-nested-navigator"></a>
## 导航到嵌套导航器中的屏幕
¥Navigate to a screen in a nested navigator
在 React Navigation 中，可以通过在参数中传递屏幕名称来控制导航到特定的嵌套屏幕。这将渲染指定的嵌套屏幕，而不是该嵌套导航器的初始屏幕。
¥In React Navigation, navigating to a specific nested screen can be controlled by passing the screen name in params. This renders the specified nested screen instead of the initial screen for that nested navigator.
例如，你想要从 `root` 导航器内的初始屏幕导航到 `settings`（嵌套导航器）内名为 `media` 的屏幕。在 React Navigation 中，这是按以下示例所示完成的：
¥For example, from the initial screen inside the `root` navigator, you want to navigate to a screen called `media` inside `settings` (a nested navigator). In React Navigation, this is done as shown in the example below:
```jsx React Navigation
navigation.navigate('root', {
  screen: 'settings',
  params: {
    screen: 'media',
  },
});
```
在 Expo Router 中，你可以使用 `router.push()` 来达到相同的结果。无需在参数中显式传递屏幕名称。
¥In Expo Router, you can use `router.push()` to achieve the same result. There is no need to pass the screen name in the params explicitly.
```jsx Expo Router
router.push('/root/settings/media');
```


## 模态

了解如何在 Expo Router 中使用模态。

<VideoBoxLink videoId="gNzuJVRmyDk" title="Using Modals with Expo Router" description="Learn about the different ways to display content over the rest of your app." className="mb-6" />
Modal 是移动应用中常见的用户界面模式。它们用于在现有屏幕顶部显示内容，并用于不同的目的，例如显示确认警报或独立表单。你可以使用以下方法在你的应用中创建模式：
¥Modals are a common user interface pattern in mobile apps. They are used to present content on top of the existing screen and is used for different purposes, such as displaying confirmation alerts or standalone forms. You can create modals in your app using the following methods:
* 使用 React Native 的 [`Modal`](https://rn.nodejs.cn/docs/modal) 组件。
  ¥Use React Native's [`Modal`](https://rn.nodejs.cn/docs/modal) component.
* 使用 Expo Router 的特殊基于文件的语法在应用的导航系统中创建模态屏幕。
  ¥Use Expo Router's special file-based syntax to create a modal screen within the app's navigation system.
每种方法都有其特定的用例。了解何时使用每种方法对于创造积极的用户体验很重要。
¥Each approach has its specific use case. Understanding when to use each method is important for creating a positive user experience.
<a id="react-natives-modal-component"></a>
## React 服务器功能
¥React Native's Modal component
`Modal` 组件是 React Native 核心 API 的一部分。常见用例包括：
¥The `Modal` component is part of React Native's core API. Common use cases include:
* 独立交互，例如不需要成为导航系统一部分的自包含任务。
  ¥Standalone interactions, such as self-contained tasks that don't need to be part of the navigation system.
* 临时警报或确认对话框，非常适合快速交互。
  ¥Temporary alerts or confirmation dialogs that are ideal for quick interactions.
下面是一个自定义 `Modal` 组件的示例，该组件在不同平台上覆盖当前屏幕：
¥Below is an example of a custom `Modal` component that overlays the current screen on different platforms:
对于大多数用例，你可以使用 `Modal` 组件并根据应用的用户界面要求对其进行自定义。有关如何使用 `Modal` 组件及其属性的详细信息，请参阅 [React Native 文档](https://rn.nodejs.cn/docs/modal)。
¥For most use cases, you can use the `Modal` component and customize it according to your app's user interface requirements. For details on how to use the `Modal` component and its props, see the [React Native documentation](https://rn.nodejs.cn/docs/modal).
<a id="modal-screen-using-expo-router"></a>
## 使用 Expo Router 的模态屏幕
¥Modal screen using Expo Router
模式屏幕是在应用目录内创建的文件，用作现有堆栈中的路由。它用于需要成为导航系统一部分的复杂交互，例如多步骤表单，你可以在流程完成后链接到特定屏幕。
¥A modal screen is a file created inside the **app** directory and is used as a route within the existing stack. It is used for complex interactions that need to be part of the navigation system, such as multi-step forms where you can link to a specific screen after the process completes.
下面是一个模态屏幕在不同平台上的工作方式的示例：
¥Below is an example of how a modal screen works on different platforms:
<a id="usage"></a>
### 用法
¥Usage
要实现模态路由，请在应用目录中创建一个名为 modal.tsx 的屏幕。这是一个示例文件结构：
¥To implement a modal route, create a screen called **modal.tsx** inside the **app** directory. Here's an example file structure:
上述文件结构生成一个布局，其中 `index` 是堆栈中的第一个路由。在根布局文件 (app/_layout.tsx) 中，你可以在堆栈中添加 `modal` 路由。要将其作为模态显示，请在路由上将 `presentation` 选项设置为 `modal`。
¥The above file structure produces a layout where the `index` is the first route in the stack. Inside the root layout file (**app/_layout.tsx**), you can add the `modal` route in the stack. To present it as a modal, set the `presentation` option to `modal` on the route.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'modal',
        }}
      />
    </Stack>
  );
}
```
你可以使用 `Link` 组件从 index.tsx 文件导航到模式屏幕。
¥You can use the `Link` component to navigate to the modal screen from the **index.tsx** file.
```tsx app/index.tsx|collapseHeight=350
import { Link } from 'expo-router';
import { StyleSheet, Text, View } from 'react-native';
export default function Home() {
  return (
    <View style={styles.container}>
      <Text>Home screen</Text>
      <Link href="/modal" style={styles.link}>
        Open modal
      </Link>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  link: {
    paddingTop: 20,
    fontSize: 20,
  },
});
```
modal.tsx 渲染了模态的内容。
¥The **modal.tsx** presents the contents of the modal.
```tsx app/modal.tsx|collapseHeight=250
import { StyleSheet, Text, View } from 'react-native';
export default function Modal() {
  return (
    <View style={styles.container}>
      <Text>Modal screen</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
<a id="modal-presentation-and-dismiss-behavior"></a>
### 模态渲染和关闭行为
¥Modal presentation and dismiss behavior
当模式是导航器中的当前屏幕并作为独立屏幕渲染时，它将失去其先前的上下文。其渲染和关闭行为在每个平台上都不同：
¥A modal loses its previous context when it is the current screen in the navigator and is presented as a standalone screen. Its presentation and dismissal behavior are different on each platform:
* 在 Android 上，模式在当前屏幕顶部滑动。要关闭它，请使用后退按钮导航回上一个屏幕。
  ¥On Android, the modal slides on top of the current screen. To dismiss it, use the back button to navigate back to the previous screen.
* 在 iOS 上，模态框从当前屏幕底部滑动。要关闭它，请从顶部向下滑动。
  ¥On iOS, the modal slides from the bottom of the current screen. To dismiss it, swipe it down from the top.
* 在网络上，模式显示为单独的路由，并且必须使用 [`router.canGoBack()`](/router/navigating-pages/#imperative-navigation) 手动提供关闭行为。以下是如何关闭模式的示例：
  ¥On web, the modal is presented as a separate route, and the dismiss behavior has to be provided manually using [`router.canGoBack()`](/router/navigating-pages/#imperative-navigation). Here's an example of how to dismiss the modal:
```tsx app/modal.tsx
import { StyleSheet, Text, View } from 'react-native';
export default function Modal() {
  const isPresented = router.canGoBack();
  return (
    <View style={styles.container}>
      <Text>Modal screen</Text>
      {isPresented && <Link href="../">Dismiss modal</Link>}
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
<a id="change-status-bar-appearance-on-ios"></a>
### 更改 iOS 上的状态栏外观
¥Change status bar appearance on iOS
在 iOS 上，默认情况下，模式具有深色背景，可隐藏状态栏。要更改状态栏外观，你可以使用 `Platform` API 检查当前平台是否为 iOS，然后使用 [`StatusBar`](/versions/latest/sdk/status-bar/) 组件更改 modal.tsx 文件中的外观。
¥By default on iOS, the modal has a dark background which hides the status bar. To change the status bar appearance, you can use the `Platform` API to check if the current platform is iOS and then use the [`StatusBar`](/versions/latest/sdk/status-bar/) component to change the appearance inside the **modal.tsx** file.
```tsx app/modal.tsx|collapseHeight=250
import { StyleSheet, Text, View, Platform } from 'react-native';
import { StatusBar } from 'expo-status-bar';
export default function Modal() {
  return (
    <View style={styles.container}>
      <Text>Modal screen</Text>
      <StatusBar style={Platform.OS === 'ios' ? 'light' : 'auto'} />
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
<a id="web-modals-implementation"></a>
## Web 模式实现
¥Web modals implementation
上面的视频演示了出现在网页主要内容上的模态窗口。背景变暗以将焦点吸引到模式上，其中包含用户信息。这是 Web 模式的典型行为，用户可以与模式交互或关闭它以返回主页。
¥The video above demonstrates a modal window that appears over the main content of the web page. The background dims to draw focus to the modal, which contains information for the user. This is typical behavior for web modals, where users can interact with the modal or close it to return to the main page.
你可以通过使用 [`transparentModal`](https://react-navigation.nodejs.cn/docs/stack-navigator/#transparent-modals) 演示模式、设置覆盖和模式内容的样式以及利用 [`react-native-reanimated`](/versions/latest/sdk/reanimated/#installation) 为模式的演示设置动画来实现上述 Web 模式行为。
¥You can achieve the above web modal behavior by using the [`transparentModal`](https://react-navigation.nodejs.cn/docs/stack-navigator/#transparent-modals) presentation mode, styling the overlay and modal content, and utilizing [`react-native-reanimated`](/versions/latest/sdk/reanimated/#installation) to animate the modal's presentation.
修改项目的根布局 (app/_layout.tsx) 以将 `options` 对象添加到模式路由：
¥Modify your project's root layout (**app/_layout.tsx**) to add an `options` object to the modal route:
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  initialRouteName: 'index',
};
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'transparentModal',
          animation: 'fade',
          headerShown: false,
        }}
      />
    </Stack>
  );
}
```
>  **info** `unstable_settings` 目前仅适用于 `Stack` 导航器。
>
> ¥`unstable_settings` currently works only with `Stack` navigators.
上述示例使用 [`unstable_settings`](/router/advanced/router-settings) 将 `index` 屏幕设置为 [`initialRouteName`](/router/advanced/router-settings/#initialroutename)。这可确保透明模式始终渲染在当前屏幕的顶部，即使用户通过直接链接导航到模式屏幕也是如此。
¥The above example sets the `index` screen as the [`initialRouteName`](/router/advanced/router-settings/#initialroutename) using [`unstable_settings`](/router/advanced/router-settings). This ensures that the transparent modal is always rendered on top of the current screen, even when users navigate to the modal screen via a direct link.
在 modal.tsx 中设置覆盖和模态内容的样式，如下所示：
¥Style the overlay and modal content in **modal.tsx** as shown below:
```tsx app/modal.tsx|collapseHeight=250
import { Link } from 'expo-router';
import { Pressable, StyleSheet, Text } from 'react-native';
import Animated, { FadeIn, SlideInDown } from 'react-native-reanimated';
export default function Modal() {
  return (
    <Animated.View
      entering={FadeIn}
      style={{
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
        backgroundColor: '#00000040',
      }}
    >
      {/* Dismiss modal when pressing outside */}
      <Link href={'/'} asChild>
        <Pressable style={StyleSheet.absoluteFill} />
      </Link>
      <Animated.View
        entering={SlideInDown}
        style={{
          width: '90%',
          height: '80%',
          alignItems: 'center',
          justifyContent: 'center',
          backgroundColor: 'white',
        }}
      >
        <Text style={{ fontWeight: 'bold', marginBottom: 10 }}>Modal Screen</Text>
        <Link href="/">
          <Text>← Go back</Text>
        </Link>
      </Animated.View>
    </Animated.View>
  );
}
```
请随意自定义模态动画和样式以满足你的喜好。
¥Feel free to customize the modal animations and styles to your liking.
<a id="additional-information"></a>
## 附加信息
¥Additional information
<a id="presentation-options"></a>
### 演示选项
¥Presentation options
在 Android 和 iOS 上使用 `presentation` 选项有不同的选项来渲染模态屏幕。
¥There are different options to present a modal screen using the `presentation` option on Android and iOS.
| 选项                          | 描述                                                                                                                                                                                                             |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `card`                      | 新屏幕将被推送到堆栈上。Android 上的默认动画将根据操作系统版本和主题而有所不同。在 iOS 上，它会从侧面滑动。                                                                                                                                                   |
| `modal`                     | 新屏幕将以模态方式渲染，允许在屏幕内渲染嵌套堆栈。                                                                                                                                                                                      |
| `transparentModal`          | 新屏幕将以模态方式渲染，前一个屏幕保持可见。如果屏幕具有半透明背景，则下面的内容仍然可见。                                                                                                                                                                  |
| `containedModal`            | 在 Android 上，回退到 `modal`。在 iOS 上，使用 [`UIModalPresentationCurrentContext`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationcurrentcontext) 模态框样式。                    |
| `containedTransparentModal` | 在 Android 上，回退到 `transparentModal`。在 iOS 上，使用 [`UIModalPresentationOverCurrentContext`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationovercurrentcontext) 模态框样式。 |
| `fullScreenModal`           | 在 Android 上，回退到 `modal`。在 iOS 上，使用 [`UIModalPresentationFullScreen`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationfullscreen) 模态框样式。                            |
| `formSheet`                 | 在 Android 上，回退到 `modal`。在 iOS 上，使用 [`UIModalPresentationFormSheet`](https://developer.apple.com/documentation/uikit/uimodalpresentationstyle/uimodalpresentationformsheet) 模态框样式。                              |


## 共享路由

了解如何使用 Expo Router 定义共享路由或使用数组以不同布局多次使用同一路由。

要将相同的 URL 与不同的布局相匹配，请使用 [**groups**](/router/basics/notation/#parentheses) 和重叠的子路由。这种模式在原生应用中非常常见。例如，在 X 应用中，可以在每个选项卡（例如主页、搜索和个人资料）中查看个人资料。然而，访问该路由只需要一个 URL。
¥To match the same URL with different layouts, use [**groups**](/router/basics/notation/#parentheses) with overlapping child routes. This pattern is very common in native apps. For example, in the X app, a profile can be viewed in every tab (such as home, search, and profile). However, there is only one URL that is required to access this route.
在下面的示例中，app/_layout.tsx 是标签栏，每个路由都有自己的标题。app/(profile)/[user].tsx 路由在每个选项卡之间共享。
¥In the example below, **app/_layout.tsx** is the tab bar and each route has its own header. The **app/(profile)/[user].tsx** route is shared between each tab.
> 重新加载页面时，将渲染第一个字母匹配项。
>
> ¥When reloading the page, the first alphabetical match is rendered.
共享路由可以通过在路由中包含群组名称来直接导航。例如，`/(search)/baconbrix` 导航到 "search" 布局中的 `/baconbrix`。
¥Shared routes can be navigated directly by including the group name in the route. For example, `/(search)/baconbrix` navigates to `/baconbrix` in the "search" layout.
<a id="arrays"></a>
## 数组
¥Arrays
> 数组语法是原生应用开发所独有的高级概念。
>
> ¥Array syntax is an advanced concept that is unique to native app development.
不要使用不同的布局多次定义相同的路由，而是使用数组语法 `(,)` 来复制组的子级。例如，`app/(home,search)/[user].tsx` — 在内存中创建 `app/(home)/[user].tsx` 和 `app/(search)/[user].tsx`。
¥Instead of defining the same route multiple times with different layouts, use the array syntax `(,)` to duplicate the children of a group. For example, `app/(home,search)/[user].tsx` — creates `app/(home)/[user].tsx` and `app/(search)/[user].tsx` in memory.
要区分两条路由，请使用布局的 `segment` 属性：
¥To distinguish between the two routes use a layout's `segment` prop:
```tsx app/(home,search)/_layout.tsx
export default function DynamicLayout({ segment }) {
  if (segment === '(search)') {
    return <SearchStack />;
  }
  return <Stack />;
}
```
要启用数组语法，请在动态布局中使用 `unstable_settings` 对象为每个组指定 [`initialRouteName`](/router/advanced/router-settings/#initialroutename)：
¥To enable the **array syntax**, specify the [`initialRouteName`](/router/advanced/router-settings/#initialroutename) for each group using `unstable_settings` object in the dynamic layout:
```tsx app/(home,search)/_layout.tsx
export const unstable_settings = {
  initialRouteName: 'home',
  search: {
    initialRouteName: 'search',
  },
};
export default function DynamicLayout({ segment }) {
}
```
在上面的示例中，`home` 路由是 `home` 组和应用的默认路由。`search` 路由是 `search` 组的默认路由。
¥In the above example, the `home` route is the default route for the `home` group and the app. The `search` route is the default route for the `search` group.
<a id="key-points"></a>
## 关键点
¥Key points
* 你只能为当前导航器提供组。
  ¥You can only provide groups for the current navigator.
* 使用数组语法时，如果有两个组（例如 `(one)/(two)`），则只有最后一个组的段用于匹配路由。
  ¥When using the array syntax, if there are two groups (for example, `(one)/(two)`), only the last group's segment is used for matching the route.
* 如果至少有两个组 `initialRouteNames`，但未提供默认 `initialRouteName`，则使用第一个组的 `initialRouteName`。
  ¥If there are at least two group `initialRouteNames`, but a default `initialRouteName` is not provided, the first group's `initialRouteName` is used.


## 受保护的路由

了解如何使屏幕无法通过客户端导航访问。

>  **warning** 受保护的路由在 SDK 53 及更高版本中可用。
>
> ¥Protected routes are available in SDK 53 and above.
Video Tutorial: [Watch: Using protected routes](https://www.youtube.com/watch?v=zHZjJDTTHJg)
<a id="overview"></a>
## 概述
¥Overview
受保护的屏幕允许你阻止用户使用客户端导航访问某些路由。如果用户尝试导航到受保护的屏幕，或者如果屏幕在活动状态下受到保护，他们将被重定向到锚点路由（通常是索引屏幕）或堆栈中第一个可用的屏幕。
¥Protected screens allow you to prevent users from accessing certain routes using client-side navigation. If a user tries to navigate to a protected screen, or if a screen becomes protected while it is active, they will be redirected to the anchor route (usually the index screen) or the first available screen in the stack.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
const isLoggedIn = false;
export function AppLayout() {
  return (
    <Stack>
      <Stack.Protected guard={!isLoggedIn}>
        <Stack.Screen name="login" />
      </Stack.Protected>
      <Stack.Protected guard={isLoggedIn}>
        <Stack.Screen name="private" />
      </Stack.Protected>
      {/* Expo Router includes all routes by default. Adding Stack.Protected creates exceptions for these screens. */}
    </Stack>
  );
}
```
在此示例中，由于 `guard` 为 false，因此无法访问 `/private` 路由。当用户尝试访问 `/private` 时，他们会被重定向到锚点路由，即索引屏幕。
¥In this example, the `/private` route is inaccessible because the `guard` is false. When a user attempts to access `/private`, they are redirected to the anchor route, which is the **index** screen.
此外，如果用户在 `/private/page` 上并且 `guard` 条件更改为 false，他们将被自动重定向。
¥Additionally, if the user is on `/private/page` and the `guard` condition changes to **false**, they will be redirected automatically.
当屏幕的保护状态从 true 更改为 false 时，其所有历史记录条目都将从导航历史记录中删除。
¥When a screen's **guard** is changed from **true** to **false**, all it's history entries will be removed from the navigation history.
<a id="multiple-protected-screens"></a>
## 多个受保护屏幕
¥Multiple protected screens
在 Expo Router 中，一个屏幕一次只能存在于一个活动路由组中。
¥In Expo Router, a screen can **only exist in one active route group at a time**.
你应该只在最合适的组或堆栈中声明一次屏幕。如果屏幕的可用性取决于逻辑，请将其封装在条件组中，而不是复制屏幕。
¥You should only declare a screen only once, in the most appropriate group or stack. If a screen's availability depends on logic, wrap it in a conditional group instead of duplicating the screen.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
const isLoggedIn = true;
const isAdmin = true;
export function AppLayout() {
  return (
    <Stack>
      <Stack.Protected guard={true}>
        <Stack.Screen name="profile" />
      </Stack.Protected>
      <Stack.Screen name="profile" /> // ❌ Not allowed: duplicate screen
    </Stack>
  );
}
```
<a id="nesting-protected-screens"></a>
## 嵌套受保护屏幕
¥Nesting protected screens
受保护的屏幕可以嵌套，以定义分层访问控制逻辑。
¥Protected screens can be nested to define hierarchical access control logic.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
const isLoggedIn = true;
const isAdmin = true;
export function AppLayout() {
  return (
    <Stack>
      <Stack.Protected guard={isLoggedIn}>
        <Stack.Protected guard={isAdmin}>
          <Stack.Screen name="private" />
        </Stack.Protected>
        <Stack.Screen name="about" />
      </Stack.Protected>
    </Stack>
  );
}
```
本例中：
¥In this case:
* 仅当用户登录且为管理员时，`/private` 才受保护。
  ¥`/private` is only protected if the user is logged in and is an admin.
* `/about` 对任何登录用户均受保护。
  ¥`/about` is protected to any logged-in user.
<a id="falling-back-to-a-specific-screen"></a>
## 回退到特定屏幕
¥Falling back to a specific screen
你可以将导航器配置为在访问被拒绝时回退到特定屏幕。
¥You can configure the navigator to fall back to a specific screen if access is denied.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
const isLoggedIn = false;
export function AppLayout() {
  return (
    <Stack>
      <Stack.Protected guard={isLoggedIn}>
        <Stack.Screen name="index" />
        <Stack.Screen name="private" />
      </Stack.Protected>
      <Stack.Screen name="login" />
    </Stack>
  );
}
```
此处，由于索引屏幕受保护且 protected 为 false，因此路由会重定向到第一个可用的屏幕 — 登录。
¥Here, because the **index** screen is protected and the **protected** is **false**, the router redirects to the first available screen — **login**.
<a id="tabs-and-drawer"></a>
## 标签页和抽屉
¥Tabs and Drawer
受保护的路由也适用于 [选项卡](/router/advanced/tabs/) 和 [抽屉](/router/advanced/drawer/) 导航器。
¥Protected routes are also available for [Tabs](/router/advanced/tabs/) and [Drawer](/router/advanced/drawer/) navigators.
```tsx app/_layout.tsx
import { Tabs } from 'expo-router';
const isLoggedIn = false;
export default function TabLayout() {
  return (
    <Tabs>
      <Tabs.Screen name="index" options={{ tabBarLabel: 'Home' }} />
      <Tabs.Protected guard={isLoggedIn}>
        <Tabs.Screen name="private" options={{ tabBarLabel: 'Private' }} />
        <Tabs.Screen name="profile" options={{ tabBarLabel: 'Profile' }} />
      </Tabs.Protected>
      <Tabs.Protected guard={!isLoggedIn}>
        <Tabs.Screen name="login" options={{ tabBarLabel: 'Login' }} />
      </Tabs.Protected>
    </Tabs>
  );
}
```
<a id="custom-navigators"></a>
## 自定义导航器
¥Custom navigators
`Protected` 也可通过 `withLayoutContext` 钩子用于 [自定义导航器](/router/migrate/from-react-navigation/#rewrite-custom-navigators)。
¥`Protected` is also available for [custom navigators](/router/migrate/from-react-navigation/#rewrite-custom-navigators) using the `withLayoutContext` hook.
<a id="static-rendering-considerations"></a>
## 静态渲染注意事项
¥Static rendering considerations
受保护的屏幕仅在客户端进行评估。在静态站点生成期间，不会为受保护的路由创建 HTML 文件。但是，如果用户知道这些路由的 URL，他们仍然可以直接请求相应的 HTML 或 JavaScript 文件。受保护的屏幕不能替代服务器端身份验证或访问控制。
¥Protected screens are evaluated on the client side only. During static site generation, no HTML files are created for protected routes. However, if users know the URLs of these routes, they can still request the corresponding HTML or JavaScript files directly. Protected screens are not a replacement for server-side authentication or access control.


# 高级

## 平台专属扩展和模块

了解如何使用平台特定的扩展和 React Native 的平台模块在 Expo Router 中根据平台切换模块。

在构建应用时，你可能希望根据当前平台显示特定内容。平台特定的扩展和 `Platform` 模块可以使体验更贴近特定平台。以下部分介绍了使用 Expo Router 实现此目的的方法。
¥While building your app, you may want to show specific content based on the current platform. Platform-specific extensions and `Platform` module can make the experience more native to a given platform. The following sections describe the ways you can achieve this with Expo Router.
<a id="platform-specific-extensions"></a>
## 平台专属扩展
¥Platform-specific extensions
>  **warning** Expo Router `3.5.x` 中添加了平台特定的扩展。如果你使用的是旧版本的库，请按照 [平台特定模块](#platform-module) 中的说明进行操作。
>
> ¥Platform-specific extensions were added in Expo Router `3.5.x`. If you are using an older version of the library, follow instructions from [Platform-specific modules](#platform-module).
有两种方法可以使用平台特定的扩展：
¥There are two ways to use platform-specific extensions:
<a id="within-app-directory"></a>
### 在应用目录中
¥Within app directory
仅当存在非平台版本时，Metro 打包器的平台特定扩展程序（例如 .android.tsx、.ios.tsx、.native.tsx 或 .web.tsx）才支持在应用目录中使用。这确保了路由在深度链接的跨平台上是通用的。
¥Metro bundler's platform-specific extensions (for example, **.android.tsx**, **.ios.tsx**, **.native.tsx**, or **.web.tsx**) are supported in the **app** directory only if a **non-platform version** also exists. This ensures that routes are universal across platforms for deep linking.
考虑以下项目结构：
¥Consider the following project structure:
在上述文件结构中：
¥In the above file structure:
* _layout.web.tsx 文件在 Web 端用作布局，_layout.tsx 文件在所有其他平台上使用。
  ¥**_layout.web.tsx** file is used as a layout on the web and **_layout.tsx** is used on all other platforms.
* index.tsx 文件用作所有平台的主页。
  ¥**index.tsx** file is used as the home page for all platforms.
* about.web.tsx 文件在 Web 端用作关于页面，about.tsx 文件在所有其他平台上使用。
  ¥**about.web.tsx** file is used as the about page for the web, and the **about.tsx** file is used on all other platforms.
<a id="outside-app-directory"></a>
### 应用目录外部
¥Outside app directory
你可以在应用目录外创建带有扩展名（例如 .android.tsx、.ios.tsx、.native.tsx 或 .web.tsx）的特定于平台的文件，并在应用目录中使用它们。
¥You can create platform-specific files with extensions (for example, **.android.tsx**, **.ios.tsx**, **.native.tsx**, or **.web.tsx**) outside the **app** directory and use them from within the **app** directory.
考虑以下项目结构：
¥Consider the following project structure:
在上述文件结构中，设计要求你为每个平台构建不同的 `about` 屏幕。在这种情况下，你可以使用平台扩展在组件目录中为每个平台创建一个组件。导入时，Metro 将确保基于当前平台使用正确的组件版本。然后，你可以将组件重新导出为应用目录中的屏幕。
¥In the above file structure, the designs require you to build different `about` screens for each platform. In that case, you can create a component for each platform in the **components** directory using platform extensions. When imported, Metro will ensure the correct component version is used based on the current platform. You can then re-export the component as a screen in the **app** directory.
```tsx app/about.tsx
export { default } from '../components/about';
```
<a id="platform-module"></a>
## 平台模块
¥Platform module
你可以使用 React Native 中的 [`Platform`](https://rn.nodejs.cn/docs/platform-specific-code#platform-module) 模块来检测当前平台并根据结果渲染适当的内容。例如，你可以在原生上渲染 `Tabs` 布局，在 Web 上渲染自定义布局。
¥You can use the [`Platform`](https://rn.nodejs.cn/docs/platform-specific-code#platform-module) module from React Native to detect the current platform and render the appropriate content based on the result. For example, you can render a `Tabs` layout on native and a custom layout on the web.
```tsx app/_layout.tsx
import { Platform } from 'react-native';
import { Link, Slot, Tabs } from 'expo-router';
export default function Layout() {
  if (Platform.OS === 'web') {
    // Use a basic custom layout on web.
    return (
      <div style={{ flex: 1 }}>
        <header>
          <Link href="/">Home</Link>
          <Link href="/settings">Settings</Link>
        </header>
        <Slot />
      </div>
    );
  }
  // Use a native bottom tabs layout on native platforms.
  return (
    <Tabs>
      <Tabs.Screen name="index" options={{ title: 'Home' }} />
      <Tabs.Screen name="settings" options={{ title: 'Settings' }} />
    </Tabs>
  );
}
```


## 自定义链接

了解如何在使用 Expo Router 时执行链接重定向并使用 +native-intent 利用第三方深层链接。

Expo Router 使用扩展版本的 Web 标准来浏览应用。但是，原生应用并不总是符合基于服务器的路由。这可能会导致集成任何第三方服务时出现错位。例如，可以使用任意字符串或意图对象而不是 URL 启动应用。在两种常见情况下，你可能需要自定义链接：
¥Expo Router uses an extended version of web standards to navigate through an app. However, native apps do not always conform to server-based routing. This can lead to misalignment when integrating any third-party service. For example, apps can be launched with arbitrary strings or intent objects instead of URLs. There are two common scenarios where you may need to customize a link:
* 应用已关闭：当应用未打开时，传入的深层链接 URL 可能需要重写以确保无缝导航。
  ¥**App Closed**: When the app is not open, incoming deep-link URLs may require rewriting to ensure seamless navigation.
* 应用已打开：当应用已经打开时，可能需要根据特定的业务逻辑或用户交互自定义 URL。此逻辑可以是整个应用的全局逻辑，也可以本地化为一组路由。
  ¥**App Open**: When the app is already open, URL customization may be necessary based on specific business logic or user interactions. This logic can be global for the entire app, or localized to a set of routes.
<a id="setup-linking"></a>
## 设置链接
¥Setup linking
请参阅 [链接到你的应用](/linking/into-your-app/) 指南，了解如何在你的应用中设置和测试链接。
¥See the [Linking into your app](/linking/into-your-app/) guide for instructions on how to set up and test linking in your app.
<a id="rewrite-incoming-native-deep-links"></a>
## 重写传入的原生深层链接
¥Rewrite incoming native deep links
Expo Router 将始终评估 URL，并假设该 URL 针对应用内的特定页面。但是，在实践中，这些 URL 的性质可能会有所不同：
¥Expo Router will always evaluate a URL with the assumption that the URL targets a specific page within the app. However, in practice, these URLs can vary in nature:
* 来自第三方提供商的唯一/引用 URL：这些 URL 通常遵循特定的架构（例如 `<my-scheme>://<provider-hostname>/<uuid>`），并由外部源生成，以将用户导航到应用内的指定内容。
  ¥**Unique/Referred URLs from third-party providers**: These URLs often follow a specific schema, such as `<my-scheme>://<provider-hostname>/<uuid>`, and are generated by external sources to navigate users to designated content within the app.
* 以前版本的过时 URL：应用用户可能会遇到来自旧版本应用的 URL，这可能会导致内容过时或不存在。妥善处理此类情况以确保流畅的用户体验至关重要。
  ¥**Stale URLs from previous versions**: App users might encounter URLs from older versions of the app, which could lead to outdated or non-existent content. It's crucial to handle such scenarios gracefully to ensure a smooth user experience.
在这种情况下，需要重写 URL 以正确定位路由。
¥In such scenarios, the URL needs to be rewritten to correctly target a route.
为了方便起见，请在项目的应用目录的顶层创建一个名为 +native-intent.tsx 的特殊文件。此文件导出一种特殊的 [`redirectSystemPath`](/versions/latest/sdk/router/#nativeintent) 方法，旨在处理 URL/路径处理。调用时，它会收到一个具有两个属性的 `options` 对象：`path` 和 `initial`。
¥To facilitate this, create a special file called **+native-intent.tsx** at the top level of your project's **app** directory. This file exports a special [`redirectSystemPath`](/versions/latest/sdk/router/#nativeintent) method designed to handle URL/path processing. When invoked, it receives an `options` object with two attributes: `path` and `initial`.
以下是应用 `redirectSystemPath` 在 +native-intent.tsx 文件中的使用实践的示例。按照此示例，你可以确保应用的 URL 处理功能的稳定性和可靠性，并降低意外错误和崩溃的风险。
¥Here's an example the applies practices on how `redirectSystemPath` is used inside **+native-intent.tsx** file. Following this example, you can ensure the stability and reliability of your app's URL processing functionality and mitigate the risk of unexpected errors and crashes.
```ts app/+native-intent.tsx
import ThirdPartyService from 'third-party-sdk';
export function redirectSystemPath({ path, initial }) {
  try {
    if (initial) {
      // While the parameter is called `path` there is no guarantee that this is a path or a valid URL
      const url = new URL(path, 'myapp://app.home');
      // Detection of third-party URLs will change based on the provider
      if (url.hostname === '<third-party-provider-hostname>') {
        return ThirdPartyService.processReferringUrl(url).catch(() => {
          // Something went wrong
          return '/unexpected-error';
        });
      }
      return path;
    }
    return path;
  } catch {
    // Do not crash inside this function! Instead you should redirect users
    // to a custom route to handle unexpected errors, where they are able to report the incident
    return '/unexpected-error';
  }
}
```
<a id="rewrite-incoming-web-deep-links"></a>
## 重写传入的 Web 深层链接
¥Rewrite incoming web deep links
处理网络上的深层链接与原生平台不同，因为初始路由过程不同。Expo Router 无法为 Web 提供与 `+native-intent` 直接对应的功能，因为 Web 路由是在执行网站的 JavaScript 之前解析的，并且会根据部署输出和你选择的提供商而有所不同。
¥Handling deep links on the web differs from native platforms, as the initial routing process occurs differently. Expo Router cannot provide a direct counterpart to `+native-intent` for web, as web routing is resolved before the website's JavaScript is executed and will differ based upon deployment output and your chosen provider.
因此，你应该实现最适合你要求的以下模式之一：
¥As a result, you should implement one of the following patterns that best suits your requirements:
* 服务器重定向：由于所有网站（包括静态页面）都托管在服务器上，请考虑利用部署提供商提供的服务器端重定向或中间件选项。这种方法非常适合针对服务器或静态输出的部署。
  ¥**Server Redirect**: Since all websites, including static pages, are hosted on a server, consider leveraging server-side redirection or middleware options provided by your deployment provider. This approach is well-suited for deployments targeting **server** or **static** outputs.
* 客户端重定向：或者，你可以在应用的根 `_layout` 中管理 URL 重定向。这种方法非常适合具有针对客户端渲染的单一输出格式的项目。
  ¥**Client Redirect**: Alternatively, you can manage URL redirects within your app's root `_layout`. This approach is ideal for projects with a single output format targeting client-side rendering.
选择与你的部署策略和技术要求相符的模式，以确保在 Web 平台上无缝处理传入的深层链接。
¥Choose the pattern that aligns with your deployment strategy and technical requirements to ensure seamless handling of incoming deep links on the web platform.
<a id="rewrite-urls"></a>
## 重写 URL
¥Rewrite URLs
当你的应用打开时，你可以使用 `usePathname()` 钩子对 `_layout` 文件中的 URL 更改做出反应。`_layout` 的位置决定了订阅的范围。
¥While your app is open, you can react to URL changes within your `_layout` files using the `usePathname()` hook. The location of the `_layout` dictates the scope of the subscription.
* 全局：将逻辑添加到你的根 `_layout` 文件
  ¥**global**: Add the logic to your root `_layout` file
* 本地化：将 `_layout` 文件添加到现有目录（或创建新的 [组目录](/router/basics/notation/#parentheses)）
  ¥**localized**: Add a `_layout` file to an existing directory (or create a new [group directory](/router/basics/notation/#parentheses))
```tsx app/_layout.tsx
import { Slot, Redirect } from 'expo-router';
export default function RootLayout() {
  const pathname = usePathname();
  if (pathname && !isUserAllowed(pathname)) {
    return <Redirect href="/home" />;
  }
  return <Slot />;
}
```
<a id="using-redirectsystempath"></a>
### 使用 `redirectSystemPath`
¥Using `redirectSystemPath`
在原生应用中，重写 URL 的另一种方法是在 [`redirectSystemPath`](#redirectsystempath) 方法中处理它。对于某些用例来说，这种方法可能更简单，但也存在某些缺点：
¥In native apps, an alternative way to rewrite a URL is to handle it within the [`redirectSystemPath`](#redirectsystempath) method. This approach can be simpler for some use cases but comes with certain drawbacks:
* 仅限原生：此方法不适用于 Web，因为 `+native-intent` 仅适用于原生应用。
  ¥**Native-only**: This method will not work on the web, as `+native-intent` is only available in native apps.
* 缺少上下文：`+native-intent` 在你的应用上下文之外进行处理。这意味着你将无法访问其他逻辑，例如用户身份验证状态或当前路由的状态。
  ¥**Lacks context**: `+native-intent` is processed outside the context of your app. This means you won't have access to additional logic, such as user authentication status or the current route's state.
<a id="sending-navigation-events-to-third-party-services"></a>
## 将导航事件发送给第三方服务
¥Sending navigation events to third-party services
下面是如何将导航事件发送到外部服务（例如分析或日志记录服务）的基本示例。请咨询你的提供商以获取具体说明。
¥Below is a basic example of how to send navigation events to an external service, such as an analytics or logging service. Consult with your provider for specific instructions.
```tsx app/_layout.tsx
import ThirdPartyService from 'third-party-sdk';
import { Slot, usePathname } from 'expo-router';
const thirdParty = new ThirdPartyService();
export default function RootLayout() {
  const pathname = usePathname();
  // Perform the service initiation logic
  useEffect(() => {
    thirdParty.register();
    return () => {
      thirdParty.deregister();
    };
  }, [thirdParty]);
  // Send pathname changes to the third party
  useEffect(() => {
    thirdParty.sendEvent({ pathname });
  }, [pathname]);
  return <Slot />;
}
```
<a id="universal-links-and-multiple-domains"></a>
## 通用链接和多个域
¥Universal Links and multiple domains
Expo Router 不需要对通用链接和多个域进行额外配置。将评估提供给你的应用的所有 URL。要自定义应用的 URL 方案，你应该 [自定义应用配置中的 `scheme` 值](/versions/latest/config/app/#scheme)。
¥Expo Router does not require additional configuration for Universal Links and multiple domains. All URLs provided to your App will be evaluated. To customize the URL scheme(s) for your app, your should [customize the `scheme` value in your app config](/versions/latest/config/app/#scheme).
<a id="forcing-web-links"></a>
## 强制网络链接
¥Forcing web links
如果你希望用户浏览器最初评估 URL，请使用 `http`/`https` 方案将地址写为完全限定 URL (FQDN)。使用完整的 URL 可确保链接被解释为 Web URL 并默认在用户的浏览器中打开。
¥If you want a URL to be initially evaluated by the user's browser, write the address as a Fully Qualified URL (FQDN) with an `http`/`https` scheme. Using a complete URL ensures that the link is interpreted as a web URL and opened in the user's browser by default.
这种方法可有效地将用户引导至外部网站或其他应用的通用链接。
¥This approach is effective for directing users to external websites or Universal Links for other apps.
```ts
<Link href="https://my-website.com/router/introduction" />
```
<a id="legacy_subscribe"></a>
## `legacy_subscribe`
> `legacy_subscribe` 在 SDK 52 中实验性地可用。
>
> ¥`legacy_subscribe` is experimentally available in SDK 52.
如果你使用的第三方提供商不支持 Expo Router，但通过 `Linking.subscribe` 功能支持现有项目的 React Navigation，则可以使用 `legacy_subscribe` 作为备用 API。
¥If you're using a third-party provider that doesn't support Expo Router but does support React Navigation via the `Linking.subscribe` function for existing projects, you can use `legacy_subscribe` as an alternative API.
不建议将此 API 用于新项目或集成。其使用与服务器端路由和 [静态渲染](/router/reference/static-rendering/) 不兼容，并且在离线或低网络连接环境中管理起来可能具有挑战性。
¥Using this API is not recommended for new projects or integrations. Its usage is incompatible with Server Side Routing and [Static Rendering](/router/reference/static-rendering/), and can be challenging to manage while offline or in a low network connectivity environment.


## 路由设置

了解如何在 Expo Router 中使用静态属性配置布局。

>  **warning** 警告：`unstable_settings` 目前不能与 [异步路由](/router/reference/async-routes/) 一起使用（仅限开发）。这就是该功能被指定为不稳定的原因。
>
> ¥**Warning:** `unstable_settings` currently do not work with [async routes](/router/reference/async-routes/) (development-only). This is why the feature is designated *unstable*.
#### initialRouteName
  当深层链接到路由时，你可能希望为用户提供 "back" 按钮。`initialRouteName` 设置堆栈的默认屏幕，并且应匹配有效的文件名（不带扩展名）。
  ¥When deep linking to a route, you may want to provide a user with a "back" button. The `initialRouteName` sets the default screen of the stack and should match a valid filename (without the extension).
  ```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  // Ensure any route can link back to `/`
  initialRouteName: 'index',
};
export default function Layout() {
  return <Stack />;
}
```
  现在直接深层链接到 `/other` 或重新加载页面将继续显示后退箭头。
  ¥Now deep linking directly to `/other` or reloading the page will continue to show the back arrow.
  使用 [数组语法](/router/advanced/shared-routes/#arrays) `(foo,bar)` 时，你可以在 `unstable_settings` 对象中指定组的名称以定位特定段。
  ¥When using [array syntax](/router/advanced/shared-routes/#arrays) `(foo,bar)` you can specify the name of a group in the `unstable_settings` object to target a particular segment.
  ```tsx other.tsx
export const unstable_settings = {
  // Used for `(foo)`
  initialRouteName: 'first',
  // Used for `(bar)`
  bar: {
    initialRouteName: 'second',
  },
};
```
  `initialRouteName` 仅在深度链接到路由时使用。在应用导航期间，你要导航到的路由将是初始路由。你可以使用 `<Link />` 组件上的 `initial` prop 或将选项传递给命令式 API 来禁用此行为。
  ¥The `initialRouteName` is only used when deep-linking to a route. During app navigation, the route you are navigating to will be the initial route. You can disable this behavior using the `initial` prop on the `<Link />` component or by passing the option to the imperative APIs.
  ```js
// If this navigates to a new _layout, don't override the initial route
<Link href="/route" initial={false} />;
router.push('/route', { overrideInitialScreen: false });
```


## 苹果交接

了解如何使用 Expo Router 和 Apple Handoff 在 Apple 设备之间无缝地继续应用导航。

Apple Handoff 是一项功能，使用户能够在另一台设备上继续浏览你的应用或网站。Expo Router 可自动执行此功能的所有运行时路由。但是，必须手动设置一次性配置。
¥Apple Handoff is a feature that enables users to continue browsing your app or website on another device. Expo Router automates all of the runtime routing for this feature. However, the one-time configuration must be set up manually.
在 Expo Router 中，底层 iOS API (`NSUserActivity`) 需要 `webpageUrl`，操作系统建议将其作为切换到应用的当前 URL。`expo-router/head` 组件有一个可选的原生模块，可以自动将 `webpageUrl` 设置为 Expo Router 中当前聚焦的路由。
¥In Expo Router, the underlying iOS API (`NSUserActivity`) requires a `webpageUrl` which the OS recommends as the current URL for switching to your app. The `expo-router/head` component has an optional native module that can automatically set the `webpageUrl` to the currently focused route in Expo Router.
<PlatformsSection ios web />
<a id="setup"></a>
## 设置
¥Setup
以下限制和注意事项很重要：
¥The following restrictions and considerations are important:
* Handoff 仅限 Apple。
  ¥Handoff is Apple-only.
* Handoff 不能在 Expo Go 应用中使用，因为它需要构建时配置。
  ¥Handoff can not be used in the Expo Go app as it requires build-time configuration.
* 切换需要配置 [通用链接](/linking/into-your-app/)（至少在 iOS 上），并包含 `activitycontinuation` 对象。
  ¥Handoff requires [universal links](/linking/into-your-app/) to be configured, at least on iOS, and contain the `activitycontinuation` object.
* 切换要求在你想要支持的每个页面上使用 `expo-router/head` 组件，或者如果你希望所有页面都是连续的，则在根布局中使用 `expo-router/head` 组件。
  ¥Handoff requires the `expo-router/head` component to be used on each page that you want to support, or in the root layout if you want all pages to be continuous.
为了确保 public/.well-known/apple-app-site-association 文件配置正确，它必须包含 `activitycontinuation` 密钥和 `apps` 数组，该数组包含应用的打包包 ID 和格式为 `<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>` 的团队 ID。例如，`QQ57RJ5UTD.app.expo.acme`，其中 `QQ57RJ5UTD` 是团队 ID，`app.expo.acme` 是打包包标识符。
¥To ensure that the **public/.well-known/apple-app-site-association** file is configured correctly, it must include the `activitycontinuation` key with an `apps` array that contains your app's bundle ID and Team ID formatted as `<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>`. For example, `QQ57RJ5UTD.app.expo.acme` where `QQ57RJ5UTD` is the Team ID and `app.expo.acme` is the bundle identifier.
```json public/.well-known/apple-app-site-association
{
  "applinks": {
    "details": [
      {
        "appIDs": ["<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>"],
        "components": [
          {
            "/": "*",
            "comment": "Matches all routes"
          }
        ]
      }
    ]
  },
  "activitycontinuation": {
    "apps": ["<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>"]
  },
  "webcredentials": {
    "apps": ["<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>"]
  }
}
```
> `webcredentials` 对象是可选的，但建议使用。
>
> ¥The `webcredentials` object is optional but recommended.
你可以使用以下命令根据你的 [应用配置](/versions/latest/config/app/) 生成 apple-app-site-association 文件：
¥You can use the following command to generate the **apple-app-site-association** file based on your [app config](/versions/latest/config/app/):
```sh
$ npx setup-safari
```
请参阅 [测试更新](/linking/into-your-app/#test-the-deep-link) 开发中测试切换指南。
¥See [Test the deep link](/linking/into-your-app/#test-the-deep-link) guide to test handoff in development.
<a id="expo-head-setup"></a>
### Expo 头设置
¥Expo Head setup
确保使用 `expo-router` 配置插件在 `app.config.tsx` 文件中设置切换原点。这是当用户切换到你的应用时将用于 `webpageUrl` 的 URL。
¥Ensure you set the Handoff origin in your `app.config.tsx` file using the `expo-router` config plugin. This is the URL that will be used for the `webpageUrl` when the user switches to your app.
```tsx app.config.tsx
// Be sure to change this to be unique to your project.
process.env.EXPO_TUNNEL_SUBDOMAIN = 'bacon-router-sandbox';
const ngrokUrl = `${process.env.EXPO_TUNNEL_SUBDOMAIN}.ngrok.io`;
/** @type {import('expo/config').ExpoConfig} */
module.exports = {
  // ...
  ios: {
    associatedDomains: [
      `applinks:${ngrokUrl}`,
      `activitycontinuation:${ngrokUrl}`,
      `webcredentials:${ngrokUrl}`,
      // Add additional production-URLs here.
      // `applinks:example.com`,
      // `activitycontinuation:example.com`,
      // `webcredentials:example.com`,
    ],
  },
  plugins: [
    [
      'expo-router',
      {
        // Note: The URL must start with "https://" in "headOrigin"
        headOrigin:
          process.env.NODE_ENV === 'development'
            ? `https://${ngrokUrl}`
            : 'https://my-website-example.com',
      },
    ],
  ],
};
```
> 测试切换到原生时，请勿使用仅开发的 `?mode=developer` 后缀。
>
> ¥Do not use the development-only `?mode=developer` suffix when testing handoff to native.
配置应用配置后，使用以下命令重新生成原生项目：
¥After configuring the app config, regenerate your native project with the following command:
```sh
$ npx expo prebuild -p ios
```
在开发过程中，你必须在设备上安装应用之前启动网站。这是因为当你安装该应用时，操作系统将触发 Apple 的服务器对你的网站执行 ping 操作以获取 .well-known/apple-app-site-association 文件。如果网站未运行，操作系统将无法找到该文件，并且切换将无法进行。如果发生这种情况，请使用 `npx expo run:ios -d` 重建原生应用。
¥In development, you must start the website **before installing the app on your device**. This is because when you install the app, the OS will trigger Apple's servers to ping your website for the **.well-known/apple-app-site-association** file. If the website is not running, the OS will not be able to find the file and handoff will not work. If this happens, rebuild the native app with `npx expo run:ios -d`.
<a id="usage"></a>
## 用法
¥Usage
在任何你想要支持切换的路由中，请使用 `expo-router/head` 中的 `Head` 组件：
¥In any route that you want to support handoff, use the `Head` component from `expo-router/head`:
```tsx app/index.tsx
import Head from 'expo-router/head';
import { Text } from 'react-native';
export default function App() {
  return (
    <>
      <Head>
        <meta property="expo:handoff" content="true" />
      </Head>
      <Text>Hello World</Text>
    </>
  );
}
```
<a id="meta-tags"></a>
### 元标签
¥Meta tags
`expo-router/head` 组件支持以下元标记：
¥The `expo-router/head` component supports the following meta tags:
| 元标签                    | 描述                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `expo:handoff`         | 设置为 `true` 以启用当前路由的切换。默认为 `false`。（仅限 iOS）                                                                         |
| `og:title` 和 `<title>` | 设置 `NSUserActivity` 的标题，该标题在切换时不使用。                                                                                |
| `og:description`       | 设置 `NSUserActivity` 的描述，该描述不用于切换。                                                                                  |
| `og:url`               | 设置当用户切换到你的应用时应打开的 URL。默认为应用内的当前 URL，并在 `expo-router` 配置插件中使用 `headOrigin` 属性作为基本 URL。传递相对路径会将 `headOrigin` 附加到路径中。 |
你可能想在平台之间切换值，为此你可以使用 Platform.select：
¥You may want to switch the values between platforms, for that you can use **Platform.select**:
```tsx app/index.tsx
import Head from 'expo-router/head';
export default function App() {
  return (
    <Head>
      <meta
        property="og:url"
      />
    </Head>
  );
}
```
<a id="debugging"></a>
## 调试
¥Debugging
确保你的 Apple 设备具有 [启用切换](https://support.apple.com/en-us/HT209455)。你可以按照以下步骤进行测试，但将你的应用替换为 Safari。
¥Ensure your Apple devices have [Handoff enabled](https://support.apple.com/en-us/HT209455). You can test this by following the steps below but substituting your app with Safari.
1. 打开设备上的原生应用。
   ¥Open your native application on your device.
2. 导航到应用中支持切换的路由，该路由正在从 Expo Router 渲染 `<Head />` 元素。
   ¥Navigate to a route in the app that supports handoff which is rendering the `<Head />` element from Expo Router.
3. 要切换到 Mac，请单击 Dock 中应用的“Handoff”图标。
   ¥To switch to your Mac and click the app's Handoff icon in the Dock.
4. 要切换到 iPhone 或 iPad，请打开应用切换器，然后点击屏幕底部的应用横幅。
   ¥To switch to your iPhone or iPad, open the App Switcher, and tap the app banner at the bottom of the screen.
如果你在 iPhone 的应用切换器中只看到 Safari 图标，则说明切换不起作用。
¥If you only see the Safari icon in your iPhone's App Switcher, then handoff is not working.
<a id="troubleshooting"></a>
## 故障排除
¥Troubleshooting
你可以使用验证器（例如 [AASA 验证器](https://branch.io/resources/aasa-validator/)）测试 Apple App Site Association 文件 (public/.well-known/apple-app-site-association)。
¥You can test the Apple App Site Association file (**public/.well-known/apple-app-site-association**) by using a validator such as, [AASA Validator](https://branch.io/resources/aasa-validator/).
如果你遇到问题，最好的办法是在应用中启用最激进的切换设置。这确保了任何可能的路由都是可链接的。你可以通过确保 public/.well-known/apple-app-site-association 文件匹配所有路由来做到这一点：
¥If you're having issues, the best thing you can do is enable the most aggressive handoff settings in your app. This ensures that any possible route is linkable. You can do this by making sure that **public/.well-known/apple-app-site-association** file matches all routes:
```json public/.well-known/apple-app-site-association
{
  "applinks": {
    "details": [
      {
        "appIDs": ["<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>"],
        "components": [
          {
            "/": "*",
            "comment": "Matches all routes"
          }
        ]
      }
    ]
  }
}
```
在应用中，确保你没有有条件地渲染 `<Head />` 元素（例如，在 `if/else` 块中），它必须在你想要支持切换的每个页面上渲染。我们建议将其添加到 [根布局](/router/basics/layout/#root-layout) 组件中，以确保调试时每个路由都是可链接的。
¥In the application, ensure you are not rendering the `<Head />` element conditionally (for example, in an `if/else` block), it must be rendered on every page that you want to support handoff. We recommend adding it to the [Root Layout](/router/basics/layout/#root-layout) component to ensure every route is linkable while debugging.
在设备上安装应用之前，请确保你可以访问 Ngrok URL（例如，通过浏览器）。如果无法访问该 URL，操作系统将无法找到该文件，并且切换将无法进行。
¥Ensure you can access the Ngrok URL (for example, via the browser), before installing the app on your device. If you can't access the URL, the OS will not be able to find the file and handoff will not work.
当关联域设置时，`npx expo run:ios` 和 Xcode 都会对你的应用进行协同设计，这是切换和通用链接工作所必需的。
¥`npx expo run:ios` and Xcode will both codesign your app when associated domains is set up, this is required for handoff and universal links to work.
Expo Go 应用不支持 Mac 和 iPhone/iPad 之间的切换。你必须在设备上构建并安装你的应用。
¥Handoff between your Mac and iPhone/iPad is not supported in the Expo Go app. You must build and install your app on your device.
如果你在 iPhone 上的应用切换器中看到 Safari 图标，则表示切换不起作用。
¥**If you see the Safari icon in the App Switcher on your iPhone**, then it means handoff is not working.
* 确保在测试切换到原生时没有使用 `?mode=developer` 后缀。
  ¥Ensure you are not using the `?mode=developer` suffix when testing handoff to native.
* 另请确保你没有使用本地开发服务器 URL。例如，`http://localhost:8081`，因为这不能用作有效的应用站点关联链接，请在浏览器中打开正在运行的 Ngrok URL 进行测试。
  ¥Also be sure you're not using the local development server URL. For example, `http://localhost:8081` as this cannot be used as a valid app site association link, open the running Ngrok URL in your browser to test.
* 确保你的 public/.well-known/apple-app-site-association 文件包含 `activitycontinuation` 字段。
  ¥Ensure your **public/.well-known/apple-app-site-association** file contains the `activitycontinuation` field.
* 我们观察到，在 iOS 16.3.1 和 macOS 13.0 (Ventura) 中，以 `app.` 和 `io.` 开头的包标识符有时不会触发原生应用显示在 iOS 任务切换器中。使用 `com.` 作为打包包标识符的第一部分。
  ¥We've observed that in iOS 16.3.1 and macOS 13.0 (Ventura), bundle identifiers starting with `app.` and `io.` will sometimes not trigger the native app to show up in the iOS task switcher. Use `com.` as the first part of your bundle identifier.
你的 public/.well-known/apple-app-site-association 必须通过安全 URL (HTTPS) 提供服务。如果你使用开发隧道，则必须使用 `EXPO_TUNNEL_SUBDOMAIN` 环境变量来配置开发隧道的子域。开发中的测试需要隧道，因为你需要 SSL 才能使用通用链接，Expo CLI 通过运行 `npx expo start --tunnel` 对此提供内置支持。
¥Your **public/.well-known/apple-app-site-association** must be served from a secure URL (HTTPS). If you are using a development tunnel, you must use the `EXPO_TUNNEL_SUBDOMAIN` environment variable to configure the subdomain for your development tunnel. The tunnel is required for testing in development because you need SSL to use universal links, Expo CLI provides built-in support for this by running `npx expo start --tunnel`.
检查你的 ios/project/project.entitlements 文件，位于 `com.apple.developer.associated-domains` 键下。这应该包含与你的网络服务器/网站相同的域。URL 不能包含协议 (`https://`) 或其他路径名、查询参数或片段。
¥Check your **ios/project/project.entitlements** file, under the `com.apple.developer.associated-domains` key. This should contain the same domains as your web server/website. The URL cannot contain a protocol (`https://`) or additional pathname, query parameters, or fragments.
<a id="still-stuck"></a>
### 仍然卡住
¥Still stuck
> 这是一个重要但非常难以设置的功能。Expo Router 自动化了许多移动部件，Expo CLI 自动化了大部分配置和托管。然而，硬件设置仍然可能配置错误。
>
> ¥This is an important but very difficult feature to set up. Expo Router automates many of the moving parts, Expo CLI automates much of the configuration and hosting. However, hardware settings can still be misconfigured.
如果以上方法均失败，你可以尝试按照 [苹果文档](https://developer.apple.com/documentation/foundation/task_management/implementing_handoff_in_your_app).1 中的步骤来调试问题。注意：
¥If all else fails, you can try to debug the issue by following the steps in the [Apple Docs](https://developer.apple.com/documentation/foundation/task_management/implementing_handoff_in_your_app). Note that:
* “将用户活动表示为 `NSUserActivity` 的实例。” 由 Expo Head 原生模块执行。
  ¥"Representing user activities as instances of `NSUserActivity`." is performed by the Expo Head native module.
* "当用户在你的应用中执行操作时更新活动实例。" 是通过安装/渲染内部带有元标记 `<meta property="expo:handoff" content="true" />` 的 `<Head />` 组件来执行的。
  ¥"Updating the activity instances as the user performs actions in your app." is performed by mounting/rendering the `<Head />` component with the meta tag `<meta property="expo:handoff" content="true" />` inside.
* "在其他设备上的应用中接收来自 Handoff 的活动。" 由 Expo Head 原生模块中的 [应用委托订阅者](/modules/appdelegate-subscribers) 执行。当你切换到原生应用时，它用于将你重定向到正确的路由。
  ¥"Receiving activities from Handoff in your app on other devices." is performed by an [App Delegate Subscriber](/modules/appdelegate-subscribers) in the Expo Head native module. It is used to redirect you to the correct route when you handoff to your native app.
<a id="known-issues"></a>
## 已知的问题
¥Known issues
从 Web 到原生的切换不支持客户端路由。这意味着应用切换器中显示的 URL 将是你单击链接或重新加载页面时所在页面的 URL。这是网络平台的限制，Expo Router 无法解决。
¥Handoff from web to native does not support client-side routing. This means the URL presented in the App Switcher will be the URL of the page you were on when you clicked the link, or reloaded the page. It is a limitation of the web platform and not something that can be fixed by Expo Router.


## Custom tab layouts

Learn how to use headless tab components to create custom tab layouts in Expo Router.

> **important** Experimentally available in SDK 52 and above. For the React Navigation styled tabs layout that are commonly used in native apps, see [Tabs](/router/advanced/tabs/).
Expo Router offers a set of components to create custom tab layouts via the submodule [`expo-router/ui`](/versions/latest/sdk/router-ui/). Unlike the React Navigation styled `Tabs`, these components are unstyled and flexible. They are designed to allow you build complex UI patterns from scratch in your project.
## Anatomy of custom Tabs components
There are four components offered by `expo-router/ui` to create custom tab layouts:
| Component    | Description                                                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `Tabs`       | Wrapper component which contains the `<View>` for the tabs.                                                                     |
| `TabList`    | The containing `<View>` for the list of `TabTrigger` components.                                                                |
| `TabTrigger` | A trigger component to switch to the specified tab. It is used to define the route using `href` prop and a `name` for each tab. |
| `TabSlot`    | A slot to render the currently selected tab.                                                                                    |
A bare minimum structure of a custom tab layout would consist of a `TabList` (containing `TabTrigger` components for each tab) and a`TabSlot`, all within the `Tabs` component, as shown here:
```tsx app/(tabs)/_layout.tsx|collapseHeight=440
import { Tabs, TabList, TabTrigger, TabSlot } from 'expo-router/ui';
import { Text } from 'react-native';
// Defining the layout of the custom tab navigator
export default function Layout() {
  return (
    <Tabs>
      <TabSlot />
      <TabList>
        <TabTrigger name="home" href="/">
          <Text>Home</Text>
        </TabTrigger>
        <TabTrigger name="article" href="/article">
          <Text>Article</Text>
        </TabTrigger>
      </TabList>
    </Tabs>
  );
}
```
## Creating routes
The `TabList` contains all the routes available within the tab navigator. It must be an immediate child of `Tabs`. Each route is defined by a `TabTrigger` within the `TabList`. A `TabTrigger` within a `TabList` must include a `name` and a `href` prop.
Typically, the `TabList` defines both the available tab routes and the appearance of the tabs, with the children of each `TabTrigger` defining the appearance of each tab button.
> **Note:** A `name` can be any `string`. This is a user-defined name for the Tab.
### Dynamic routes
Dynamic routes are allowed and can be provided with values via the `href`.
The trigger `<TabTrigger name="dynamic page" href="/hello-world" />` will create a tab for **[slug].tsx** with the params `{ slug: 'hello-world' }`. This setup can be useful for displaying an arbitrary number of tabs in the tab bar, based on end-user data, such as showing a separate tab for each user profile in an app.
### Ambiguous routes
The `href` values provided to `TabTrigger` must always point to a single route. In the above example of a shared route, href `/route` is not allowed, as it could refer to either `/(one)/route` or `/(two)/route`. However, specifying the route group within the href would work (for example,`href="/(one)/route"`).
### Nested routes
A `TabTrigger` can link to a deeply nested route. `<TabTrigger name="route" href="/route" />` will show the **(stack-one)/(stack-two)/route.tsx** route. This tab will be controlled by that route's parent navigator (that is, the navigator within **stack-two_layout.tsx**). This navigation is similar to a deep link.
## Rendering routes
The `TabSlot` component renders the current route. `TabSlot` can be nested inside other components within `Tabs` but cannot be within the `TabList`.
```tsx app/_layout.tsx
<Tabs>
  <TabList>
    <TabTrigger name="home" href="/">
      <Text>Home</Text>
    </TabTrigger>
  </TabList>
  {/* Customize how `<TabSlot />` is rendered. */}
  <View>
    <View>
      <TabSlot />
    </View>
  </View>
</Tabs>
```
## Switching tabs
Tabs can be switched via a `Link` or using the imperative APIs. However, these APIs will always perform a navigation action (they will switch tabs and might change the URL). To switch tabs without performing any navigation, you should use a `TabTrigger`. A `TabTrigger` is an unstyled `<View>` that will switch tabs when pressed, much like how text and components can be wrapped in `Link` to make them pressable navigation elements.
### Resetting navigation
The `reset` prop from `TabTrigger` can be used to control when a tab resets its navigation state. The options are `always`, `onLongPress` and `never`. This is particularly useful for a stack navigator nested inside a tab. For example, `<TabTrigger name="home" reset="always" />` will return the user to the index route inside a tab's nested stack navigator.
## TabTrigger
The `TabTrigger` is used to switch tabs, but also has a dual role of defining what routes are available as a tab.
### Within TabList
When a `TabTrigger` is used as a child of `TabList`, that defines what routes are available within the tab navigator. These `TabTrigger` need to include both the `name` and `href` props, as they define the URL for that tab and a custom name that can be used to refer to the tab. If the `TabTrigger` components also contain text or other components as children, then those will also render as the tab buttons. However, you can define the `TabTrigger`'s within the `TabList` without any UI, and they can then be invoked by `TabTrigger`'s outside of the `TabList`.
### Outside TabList
An additional `TabTrigger` can be defined outside of a `TabList`, allowing you to perform the same action as the `TabTrigger` that is defined in the `TabList`. In this case, the `TabTrigger` will not have an `href` prop. Rather, it will perform the same action as the primary `TabTrigger` with the same `name` prop. This allows you to create components that can switch tabs and be agnostic to your current navigation state. Note that all `TabTrigger`'s need to at least be descendants of the `Tabs` component, or else they will be considered to be outside the tab navigator and unable to invoke it.
## Customizing appearance
All components are rendered unstyled as a `<View>`, except `TabTrigger` which renders as a `<Pressable>`. This allows you to provide a custom `style` prop to customize their appearance. Styling `TabList` is similar to customizing the tab bar in React Navigation, while styling `TabTrigger` affects the appearance of tab buttons.
If you need to change the structure of a component, you can override its underlying component by using the `asChild` props. The component then acts as a slot, and will forward its props to its immediate child.
```tsx Custom TabList
<Tabs>
  <TabSlot />
  <TabList asChild>
    {/* Render a custom TabList */}
    <CustomTabList>
      <TabTrigger name="home" href="/">
        <Text>Home</Text>
      </TabTrigger>
    </CustomTabList>
  </TabList>
</Tabs>
```
```tsx Custom Button
<Tabs>
  <TabSlot />
  <TabList asChild>
    <TabTrigger name="home" href="/" asChild>
      {/* Render a custom button */}
      <CustomButton>
        <Text>Home</Text>
      </CustomButton>
    </TabTrigger>
  </TabList>
</Tabs>
```
### Multiple tab bars
The `TabList` is both the configuration and default appearance of the `Tabs`, but it is not the only way to render a tab bar. By hiding the `TabList`, you can construct custom tab bars using `TabTrigger`.
```tsx Multiple tab bars example
<Tabs>
  <TabSlot />
  {/* A custom tab bar */}
  <View>
    <View>
      <TabTrigger name="home">
        <Text>Home</Text>
      </TabTrigger>
      <TabTrigger name="article">
        <Text>article</Text>
      </TabTrigger>
    </View>
  </View>
  <TabList style={{ display: 'none' }}>
    <TabTrigger name="home" href="/">
      <Text>Home</Text>
    </TabTrigger>
    <TabTrigger name="article" href="/article">
      <Text>article</Text>
    </TabTrigger>
  </TabList>
</Tabs>
```
`TabTrigger` will forward an `isFocused` prop, so you can create a separate tab button component that reacts to focused status.
```tsx TabButton.tsx
import FontAwesome from '@expo/vector-icons/FontAwesome';
import { TabTriggerSlotProps } from 'expo-router/ui';
import { ComponentProps, Ref } from 'react';
import { Text, Pressable, View } from 'react-native';
type Icon = ComponentProps<typeof FontAwesome>['name'];
export type TabButtonProps = TabTriggerSlotProps & {
  icon?: Icon;
  ref: Ref<View>;
};
export function TabButton({ icon, children, isFocused, ...props }: TabButtonProps) {
  return (
    <Pressable
      {...props}
      style={[
        {
          display: 'flex',
          justifyContent: 'space-between',
          alignItems: 'center',
          flexDirection: 'column',
          gap: 5,
          padding: 10,
        },
        isFocused ? { backgroundColor: 'white' } : undefined,
      ]}>
      <FontAwesome name={icon} />
      <Text style={[{ fontSize: 16 }, isFocused ? { color: 'white' } : undefined]}>{children}</Text>
    </Pressable>
  );
}
```
Note: Expo SDK 52 / React 18 and below
---
In Expo SDK 52 and below (React 18), use the legacy `forwardRef` function to access the `ref` handle.
```diff
- import { ComponentProps, Ref } from 'react';
+ import { ComponentProps, Ref, forwardRef } from 'react';
- export function TabButton({ ref }) {
+ export const TabButton = forwardRef((props: TabButtonProps, ref: Ref<View>) => {
```
---
### Hooks
All components also have a hook version giving you control over the render tree. See the [Router UI Reference](/versions/latest/sdk/router-ui/) for a full list of the hooks available.
Using hooks is considered advanced usage of this library. For most use-cases, using the components with `asChild` should give you enough control over the render tree.
If you are developing a custom `<TabTrigger />`, you may also need to develop a custom `<TabList />` as `<TabList />` uses the [`useTabsWithChildren()`](/versions/latest/sdk/router-ui/#usetabswithchildrenoptions) which requires using the exported `<TabTrigger />` component.
### Customizing how tab screens are rendered
The `TabSlot` accepts a `renderFn` property. This function can be used to override how your screen is rendered, allowing you to implement advanced functionality such as animations or persisting/unmounting screens. See the [Router UI Reference](/versions/latest/sdk/router-ui/) for more information.
## Common questions
Note: How do I create multiple tabs for the same route?
---
You should add the route to a shared group and create a separate `TabTrigger` for each group `group`.
---
Note: How do I hide a tab?
---
Not rendering the `TabTrigger` will remove that tab (and its navigation state) from your app.
---
Note: How do I create animated tabs?
---
You can provide a custom renderer to `TabSlot` to customize how it renders a screen. You can use this to detect when screen is focused an animate appropriately.
---
Note: Can I use relative hrefs?
---
A `TabTrigger` with a relative href is relative to the local path name `Tabs` was rendered on. This is different from normal relative hrefs which are relative to the current displayed route. For example, the `<TabTrigger href="./profile" />` will resolve to `/directory/profile`, even when the `/directory/page` route is showing. Expo recommends against using relative hrefs.
---


# 参考

## 错误处理

了解使用 Expo Router 时如何处理应用中不匹配的路由和错误。

本指南指定了使用 Expo Router 时如何处理应用中不匹配的路由和错误。
¥This guide specifies how to handle unmatched routes and errors in your app when using Expo Router.
<a id="unmatched-routes"></a>
## 未匹配的路由
¥Unmatched routes
原生应用没有服务器，因此从技术上讲不存在 404。但是，如果你要实现通用路由，那么处理丢失的路由是有意义的。这是针对每个应用自动补齐的，但你也可以对其进行自定义。
¥Native apps don't have a server so there are technically no 404s. However, if you're implementing a router universally, then it makes sense to handle missing routes. This is done automatically for each app, but you can also customize it.
```tsx app/+not-found.tsx
import { Unmatched } from 'expo-router';
export default Unmatched;
```
这将渲染默认的 `Unmatched`。你可以导出任何想要渲染的组件。我们建议提供 `/` 的链接，以便用户可以导航回主屏幕。
¥This will render the default `Unmatched`. You can export any component you want to render instead. We recommend having a link to `/` so users can navigate back to the home screen.
<a id="route-priority"></a>
### 路由优先级
¥Route priority
在网页端，文件按以下顺序提供：
¥On web, files are served in the following order:
1. 公共目录中的静态文件。
   ¥Static files in the **public** directory.
2. 应用目录中的标准和动态路由。
   ¥Standard and dynamic routes in the app directory.
3. [API 路由](/router/reference/api-routes) 在应用目录中。
   ¥[API routes](/router/reference/api-routes) in the app directory.
4. 未找到的路由将最后返回 404 状态码。
   ¥Not-found routes will be served last with a 404 status code.
<a id="error-handling"></a>
## 错误处理
¥Error handling
Expo Router 支持微调错误处理，以便在未来实现更加有态度的数据加载策略。
¥Expo Router enables fine-tuned error handling to enable a more opinionated data-loading strategy in the future.
你可以从任何路由导出嵌套的 [`ErrorBoundary`](/versions/latest/sdk/router/#errorboundary) 组件，以使用 [反应错误边界](https://react.nodejs.cn/reference/react/Component#catching-rendering-errors-with-an-error-boundary) 拦截和格式化组件级错误：
¥You can export a nested [`ErrorBoundary`](/versions/latest/sdk/router/#errorboundary) component from any route to intercept and format component-level errors using [React Error Boundaries](https://react.nodejs.cn/reference/react/Component#catching-rendering-errors-with-an-error-boundary):
```tsx app/home.tsx
import { View, Text } from 'react-native';
import { type ErrorBoundaryProps } from 'expo-router';
export function ErrorBoundary({ error, retry }: ErrorBoundaryProps) {
  return (
    <View style={{ flex: 1, backgroundColor: "red" }}>
      <Text>{error.message}</Text>
      <Text onPress={retry}>Try Again?</Text>
    </View>
  );
}
export default function Page() { ... }
```
当你导出 `ErrorBoundary` 时，路由将被有效的 React Error Boundary 封装：
¥When you export an `ErrorBoundary` the route will be wrapped with a React Error Boundary effectively:
```tsx Virtual
function Route({ ErrorBoundary, Component }) {
  return (
    <Try catch={ErrorBoundary}>
      <Component />
    </Try>
  );
}
```
当 `ErrorBoundary` 不存在时，错误将被抛出到最近的父级 `ErrorBoundary` 并接受 [`error`](/versions/latest/sdk/router/#error) 和 [`retry`](/versions/latest/sdk/router/#retry) 属性。
¥When `ErrorBoundary` is not present, the error will be thrown to the nearest parent's `ErrorBoundary` and accepts [`error`](/versions/latest/sdk/router/#error) and [`retry`](/versions/latest/sdk/router/#retry) props.
<a id="work-in-progress"></a>
### 尚未完成的
¥Work in progress
React Native LogBox 需要不那么激进地渲染，以便开发时出现错误。目前，它显示 `console.error` 和 `console.warn`。然而，理想情况下它应该只显示未捕获的错误。
¥React Native LogBox needs to be presented less aggressively to develop with errors. Currently, it shows for `console.error` and `console.warn`. However, it should ideally only show for uncaught errors.


## 使用 URL 参数

了解如何访问和修改应用中的路由和搜索参数。

URL 参数包括路由参数和搜索参数。Expo Router 提供了用于访问和修改这些参数的钩子。
¥URL parameters include both **route parameters** and **search parameters**. Expo Router provides hooks for accessing and modifying these parameters.
<a id="difference-between-route-and-search-parameters"></a>
## 路由和搜索参数之间的区别
¥Difference between route and search parameters
路由参数是在 URL 路径中定义的动态段，例如 `/profile/[user]`，其中 `user` 是路由参数。它们用于匹配路由。
¥Route parameters are dynamic segments defined in a URL path, such as `/profile/[user]`, where `user` is a route parameter. They are used to match a route.
搜索参数（也称为查询参数）是可序列化的字段，可以附加到 URL，例如 `/profile?extra=info`，其中 `extra` 是搜索参数。它们通常用于在页面之间传递数据。
¥Search parameters (also known as query params) are serializable fields that can be appended to a URL, such as `/profile?extra=info`, where `extra` is a search parameter. They are commonly used to pass data between pages.
<a id="local-versus-global-url-parameters"></a>
## 本地与全局 URL 参数
¥Local versus global URL parameters
在嵌套应用中，你通常会同时安装多个页面。例如，当推送新路由时，堆栈在内存中具有前一页和当前页。因此，Expo Router 提供了两个不同的钩子来访问 URL 参数：
¥In nested apps, you'll often have **multiple pages mounted** at the same time. For example, a stack has the previous page and current page in memory when a new route is pushed. Because of this, Expo Router provides two different hooks for accessing URL parameters:
* 使用本地搜索参数：返回当前组件的 URL 参数。仅当全局 URL 符合路由时才会更新。
  ¥**useLocalSearchParams**: Returns the URL parameters for the current component. It only updates when the global URL conforms to the route.
* 使用全局搜索参数：无论组件如何，都返回全局 URL。它会在每个 URL 参数更改时更新，并可能导致组件在后台额外更新。
  ¥**useGlobalSearchParams**: Returns the global URL regardless of the component. It updates on every URL param change and might cause components to update extraneously in the background.
钩子 `useGlobalSearchParams` 和 `useLocalSearchParams` 允许你在组件中访问这些参数，使你能够检索和使用两种类型的 URL 参数。
¥The hooks `useGlobalSearchParams` and `useLocalSearchParams` allow you to access these parameters within your components, enabling you to retrieve and utilize both types of URL parameters.
两个钩子的键入和访问方式相同。但是，唯一的区别是更新频率。
¥Both hooks are typed and accessed the same way. However, the only difference is how frequently they update.
下面的示例演示了 `useLocalSearchParams` 和 `useGlobalSearchParams` 之间的区别。它使用以下应用目录结构：
¥The example below demonstrates the difference between `useLocalSearchParams` and `useGlobalSearchParams`. It uses the following **app** directory structure:
Step 1: 
    The Root Layout is a stack navigator:
```tsx app/_layout.tsx
    import { Stack } from 'expo-router';
    export default function Layout() {
      return <Stack />;
    }
    ```
Step 2: 
    The initial route redirects to the dynamic route **app/[user].tsx**, with **user=evanbacon**:
```tsx app/index.tsx
    import { Redirect } from 'expo-router';
    export default function Route() {
      return <Redirect href="/evanbacon" />;
    }
    ```
Step 3: 
    The dynamic route **app/[user]** prints out the global and local URL parameters (route parameters, in this case). It also allows for pushing new instances of the same route with different **route parameters**:
```tsx app/[user].tsx
    import { Text, View } from 'react-native';
    import { useLocalSearchParams, useGlobalSearchParams, Link } from 'expo-router';
    const friends = ['charlie', 'james']
    export default function Route() {
      const glob = useGlobalSearchParams();
      const local = useLocalSearchParams();
      console.log("Local:", local.user, "Global:", glob.user);
      return (
        <View>
          <Text>User: {local.user}</Text>
          {friends.map(friend => (
            <Link key={friend} href={`/${friend}`}>
              Visit {friend}
            </Link>
          ))}
        </View>
      );
    }
    ```
Step 4: 
When the app starts, the following log is printed:
```sh
Local: evanbacon Global: evanbacon
```
Pressing "Visit charlie" pushes a new instance of `/[user]` with **user=charlie**, and logs the following:
```sh
Local: charlie Global: charlie
Local: evanbacon Global: charlie
```
Pressing "Visit james" has a similar effect:
```sh
/james" screen
Local: james Global: james
Local: evanbacon Global: james
Local: charlie Global: james
```
    **Results:**
    - `useGlobalSearchParams` made the background screens re-render when the URL **route parameters** changed. It can cause performance issues if overused.
    - Global re-renders are executed in order of the stack, so the first screen is re-rendered first, then the **user=charlie** screen is re-rendered after.
    - `useLocalSearchParams` remained the same, even when the global URL **route parameters** changed. You can leverage this behavior for data fetching to ensure the previous screen's data is still available when you navigate back.
<a id="statically-typed-url-parameters"></a>
## 静态类型的 URL 参数
¥Statically-typed URL parameters
`useLocalSearchParams` 和 `useGlobalSearchParams` 都可以使用泛型进行静态类型化。以下是 `user` 路由参数的示例：
¥Both the `useLocalSearchParams` and `useGlobalSearchParams` can be statically typed using a generic. The following is an example for the `user` route parameter:
```tsx app/[user].tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';
export default function Route() {
  const { user } = useLocalSearchParams<{ user: string }>();
  return <Text>User: {user}</Text>;
}
// Given the URL: `/evanbacon`
// The following is returned: { user: "evanbacon" }
```
任何搜索参数（例如 `?query=...`）都可以选择输入：
¥Any search parameters (for example, `?query=...`) can be typed optionally:
```tsx app/[user].tsx
const { user, query } = useLocalSearchParams<{ user: string; query?: string }>();
// Given the URL: `/evanbacon?query=hello`
// The following is returned: { user: "evanbacon", query: "hello" }
```
与 REST 语法（`...`）一起使用时，路由参数将以字符串数组形式返回：
¥When used with the rest syntax (`...`), route parameters are returned as a string array:
```tsx app/[...everything].tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';
export default function Route() {
  const { everything } = useLocalSearchParams<{
    everything: string[];
  }>();
  const user = everything[0];
  return <Text>User: {user}</Text>;
}
// Given the URL: `/evanbacon/123`
// The following is returned: { everything: ["evanbacon", "123"] }
```
任何搜索参数将继续以单独的字符串形式返回：
¥Any search parameters will continue to be returned as individual strings:
```tsx app/[...everything].tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';
export default function Route() {
  const { everything } = useLocalSearchParams<{
    everything: string[];
    query?: string;
    query2?: string;
  }>();
  const user = everything[0];
  return <Text>User: {user}</Text>;
}
// Given the URL: `/evanbacon/123?query=hello&query2=world`
// The following is returned: { everything: ["evanbacon", "123"], query: "hello", query2: "world" }
```
<a id="updating-url-parameters"></a>
## 更新 URL 参数
¥Updating URL parameters
可以使用命令式 API 中的 router.setParams 函数更新 URL 参数。更新 URL 参数不会将任何新内容推送到历史记录堆栈。
¥URL parameters can be updated using the **router.setParams** function from the imperative API. Updating a URL parameter will not push anything new to the history stack.
以下示例使用 `<TextInput>` 更新搜索参数 q：
¥The following example uses a `<TextInput>` to update the search parameter **q**:
```tsx app/search.tsx
import { useLocalSearchParams, router } from 'expo-router';
import { useState } from 'react';
import { TextInput, View } from 'react-native';
export default function Page() {
  const params = useLocalSearchParams<{ query?: string }>();
  const [search, setSearch] = useState(params.query);
  return (
    <TextInput
      value={search}
      onChangeText={search => {
        setSearch(search);
        router.setParams({ query: search });
      }}
      placeholderTextColor="#A0A0A0"
      placeholder="Search"
      style={{
        borderRadius: 12,
        backgroundColor: '#fff',
        fontSize: 24,
        color: '#000',
        margin: 12,
        padding: 16,
      }}
    />
  );
}
```
以下是使用 `onPress` 事件更新路由参数用户的示例：
¥Here is an example using an `onPress` event to update the route parameter **user**:
```tsx app/[user].tsx
import { useLocalSearchParams, router } from 'expo-router';
import { Text } from 'react-native';
export default function User() {
  const params = useLocalSearchParams<{ user: string }>();
  return (
    <>
      <Text>User: {params.user}</Text>
      <Text onPress={() => router.setParams({ user: 'evan' })}>Go to Evan</Text>
    </>
  );
}
```
<a id="route-parameters-versus-search-parameters"></a>
## 路由参数与搜索参数
¥Route parameters versus search parameters
路由参数用于匹配路由，而搜索参数用于在路由之间传递数据。考虑以下结构，其中路由参数用于匹配用户路由：
¥Route parameters are used to match a route, while search parameters are used to pass data between routes. Consider the following structure, where a route parameter is used to match the *user* route:
,
    ],
  ]}
/>
当 `app/[user]` 路由匹配时，`user` 参数将传递给组件，并且绝不是 null 值。搜索和路由参数可以一起使用，并且可以通过 `useLocalSearchParams` 和 `useGlobalSearchParams` 钩子访问：
¥When the `app/[user]` route is matched, the `user` parameter is passed to the component and never a nullish value. Both search and route parameters can be used together and are accessible with the `useLocalSearchParams` and `useGlobalSearchParams` hooks:
```tsx app/[user].tsx
import { useLocalSearchParams } from 'expo-router';
export default function User() {
  const {
    // The route parameter
    user,
    // An optional search parameter.
    tab,
  } = useLocalSearchParams<{ user: string; tab?: string }>();
  console.log({ user, tab });
  // Given the URL: `/bacon?tab=projects`, the following is printed:
  // { user: 'bacon', tab: 'projects' }
  // Given the URL: `/expo`, the following is printed:
  // { user: 'expo', tab: undefined }
}
```
每当更改路由参数时，组件都会重新挂载。
¥Whenever a route parameter is changed, the component will re-mount.
```tsx app/[user].tsx
import { Text } from 'react-native';
import { router, useLocalSearchParams, Link } from 'expo-router';
export default function User() {
  // All three of these will change the route parameter `user`, and add a new user page.
  return (
    <>
      <Text onPress={() => router.setParams({ user: 'evan' })}>Go to Evan</Text>
      <Text onPress={() => router.push('/mark')}>Go to Mark</Text>
      <Link href="/charlie">Go to Charlie</Link>
    </>
  );
}
```
{/*
TODO: REMOVE COMMENT WHEN https://github.com/expo/expo/pull/30268 IS PUBLISHED
## Array support
URL parameters that are present multiple times will be grouped together as an array.
```tsx app/hash.tsx
import { router, useLocalSearchParams } from 'expo-router';
export default function Route() {
  // If the current URL is `/route?myParam=1&myParam=2
  const { myParam } = useLocalSearchParams();
  // myParam === ["1", "2"]
}
```
\*/}
<a id="hash-support"></a>
## 哈希支持
¥Hash support
URL [hash](https://web.nodejs.cn/en-US/docs/Web/API/URL/hash) 是 URL 中 `#` 符号后面的字符串。它通常在网站上用于链接到页面的特定部分，但它也可用于存储数据。Expo Router 将哈希值视为使用名称 `#` 的特殊搜索参数。可以使用 [搜索参数](#local-versus-global-search-parameters) 中的相同钩子和 API 来访问和修改它。
¥The URL [hash](https://web.nodejs.cn/en-US/docs/Web/API/URL/hash) is a string that follows the `#` symbol in a URL. It is commonly used on websites to link to a specific section of a page, but it can also be used to store data. Expo Router treats the hash as a special search parameter using the name `#`. It can be accessed and modified using the same hooks and APIs from [search parameters](#local-versus-global-search-parameters).
```tsx app/hash.tsx
import { Text } from 'react-native';
import { router, useLocalSearchParams, Link } from 'expo-router';
export default function User() {
  // Access the hash
  const { '#': hash } = useLocalSearchParams<{ '#': string }>();
  return (
    <>
      <Text onPress={() => router.setParams({ '#': 'my-hash' })}>Set a new hash</Text>
      <Text onPress={() => router.push('/#my-hash')}>Push with a new hash</Text>
      <Link href="/#my-hash">Link with a hash</Link>
    </>
  );
}
```


## 重定向

了解如何在 Expo Router 中重定向 URL。

你可以根据某些应用内条件将请求重定向到不同的 URL。Expo Router 支持多种不同的重定向模式。
¥You can redirect a request to a different URL based on some in-app criteria. Expo Router supports a number of different redirection patterns.
<a id="using-redirect-component"></a>
## 使用 `Redirect` 组件
¥Using `Redirect` component
你可以使用 `Redirect` 组件立即从特定屏幕重定向：
¥You can immediately redirect from a particular screen by using the `Redirect` component:
```tsx
import { View, Text } from 'react-native';
import { Redirect } from 'expo-router';
export default function Page() {
  const { user } = useAuth();
  if (!user) {
    return <Redirect href="/login" />;
  }
  return (
    <View>
      <Text>Welcome Back!</Text>
    </View>
  );
}
```
<a id="using-userouter-hook"></a>
## 使用 `useRouter` 钩子
¥Using `useRouter` hook
你还可以使用 `useRouter` 钩子强制重定向：
¥You can also redirect imperatively with the `useRouter` hook:
```tsx
import { Text } from 'react-native';
import { useRouter, useFocusEffect } from 'expo-router';
function MyScreen() {
  const router = useRouter();
  useFocusEffect(() => {
    // Call the replace method to redirect to a new route without adding to the history.
    // We do this in a useFocusEffect to ensure the redirect happens every time the screen
    // is focused.
    router.replace('/profile/settings');
  });
  return <Text>My Screen</Text>;
}
```


## 静态渲染

了解如何使用 Expo Router 将路由渲染到静态 HTML 和 CSS 文件。

要在网络上启用搜索引擎优化 (SEO)，你必须静态渲染你的应用。本指南将引导你完成静态渲染 Expo Router 应用的过程。
¥To enable Search Engine Optimization (SEO) on the web you must statically render your app. This guide will walk you through the process of statically rendering your Expo Router app.
<a id="setup"></a>
## 设置
¥Setup
Step 1: 
Enable metro bundler and static rendering in the project's [app config](/versions/latest/config/app/):
```json app.json
{
  "expo": {
    "web": {
      "bundler": "metro",
      "output": "static"
    }
  }
}
```
Step 2: 
If you have a **metro.config.js** file in your project, ensure it extends **expo/metro-config** as shown below:
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname, {
  // Additional features...
});
module.exports = config;
```
You can also learn more about [customizing Metro](/guides/customizing-metro/) .
Step 3: 
Ensure Fast Refresh is configured. Expo Router requires at least `react-refresh@0.14.0`. Ensure you **do not** have any overrides or resolutions for `react-refresh` in your **package.json**.
Step 4: 
Start the development server:
```sh
$ npx expo start
```
## Production
To bundle your static website for production, run the universal export command:
```sh
$ npx expo export --platform web
```
This will create a **dist** directory with your statically rendered website. If you have files in a local **public** directory, these will be copied over as well.
You can test the production build locally by running the following command and opening the linked URL in your browser:
```sh
$ npx serve dist
```
This project can be deployed to almost every hosting service. Note that this is not a single-page application, nor does it contain a custom server API. This means dynamic routes (**app/[id].tsx**) will not arbitrarily work. You may need to build a serverless function to handle dynamic routes.
## Dynamic Routes
The `static` output will generate HTML files for each route. This means dynamic routes (**app/[id].tsx**) will not work out of the box. You can generate known routes ahead of time using the `generateStaticParams` function.
```tsx app/blog/[id].tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';
export async function generateStaticParams(): Promise<Record<string, string>[]> {
  const posts = await getPosts();
  // Return an array of params to generate static HTML files for.
  // Each entry in the array will be a new page.
  return posts.map(post => ({ id: post.id }));
}
export default function Page() {
  const { id } = useLocalSearchParams();
  return <Text>Post {id}</Text>;
}
```
This will output a file for each post in the **dist** directory. For example, if the `generateStaticParams` method returned `[{ id: "alpha" }, { id: "beta" }]`, the following files would be generated:
#### generateStaticParams
A server-only function evaluated at build-time in a Node.js environment by Expo CLI. This means it has access to `__dirname`, `process.cwd()`, `process.env`, and more. It also has access to every environment variable that's available in the process. However, the values prefixed with `EXPO_PUBLIC_.generateStaticParams` do not run in a browser environment, so it cannot access browser APIs such as `localStorage` or `document`. It also cannot access native Expo APIs such as `expo-camera` or `expo-location`.
```tsx app/[id].tsx
export async function generateStaticParams(): Promise<Record<string, string>[]> {
  console.log(process.cwd());
  return [];
}
```
`generateStaticParams` cascades from nested parents down to children. The cascading parameters are passed to every dynamic child route that exports **generateStaticParams**.
```tsx app/[id]/_layout.tsx
export async function generateStaticParams(): Promise<Record<string, string>[]> {
  return [{ id: 'one' }, { id: 'two' }];
}
```
Now the dynamic child routes will be invoked twice, once with `{ id: 'one' }` and once with `{ id: 'two' }`. All variations must be accounted for.
```tsx app/[id]/[comment].tsx
export async function generateStaticParams(params: {
  id: 'one' | 'two';
}): Promise<Record<string, string>[]> {
  const comments = await getComments(params.id);
  return comments.map(comment => ({
    ...params,
    comment: comment.id,
  }));
}
```
### Read files using `process.cwd()`
Since Expo Router compiles your code into a separate directory you cannot use `__dirname` to form a path as its value will be different than expected.
Instead, use `process.cwd()`, which gives you the directory where the project is being compiled.
```tsx app/[category].tsx
import fs from 'fs/promises';
import path from 'path';
export async function generateStaticParams(params: {
  id: string;
}): Promise<Record<string, string>[]> {
  const directory = await fs.readdir(path.join(process.cwd(), './posts/', category));
  const posts = directory.filter(fileOrSubDirectory => return path.extname(fileOrSubDirectory) === '.md')
  return {
    id,
    posts,
  };
}
```
## Root HTML
By default, every page is wrapped with some small HTML boilerplate, this is known as the **root HTML**.
You can customize the root HTML file by creating an **app/+html.tsx** file in your project. This file exports a React component that only ever runs in Node.js, which means global CSS cannot be imported inside of it. The component will wrap all routes in the **app** directory. This is useful for adding global `<head>` elements or disabling body scrolling.
> **Note**: Global context providers should go in the [Root Layout](/router/basics/layout/#root-layout) component, not the Root HTML component.
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import { type PropsWithChildren } from 'react';
// This file is web-only and used to configure the root HTML for every
// web page during static rendering.
// The contents of this function only run in Node.js environments and
// do not have access to the DOM or browser APIs.
export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
        {/*
          Disable body scrolling on web. This makes ScrollView components work closer to how they do on native.
          However, body scrolling is often nice to have for mobile web. If you want to enable it, remove this line.
        */}
        <ScrollViewStyleReset />
        {/* Add any additional <head> elements that you want globally available on web... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
```
- The `children` prop comes with the root `<div id="root" />` tag included inside.
- The JavaScript scripts are appended after the static render.
- React Native web styles are statically injected automatically.
- Global CSS should not be imported into this file. Instead, use the [Root Layout](/router/basics/layout/#root-layout) component.
- Browser APIs like `window.location` are unavailable in this component as it only runs in Node.js during static rendering.
### `expo-router/html`
The exports from `expo-router/html` are related to the Root HTML component.
- `ScrollViewStyleReset`: Root style-reset for full-screen [React Native web apps](https://necolas.github.io/react-native-web/docs/setup/#root-element) with a root `<ScrollView />` should use the following styles to ensure native parity.
## Meta tags
You can add meta tags to your pages with the `<Head />` module from `expo-router`:
```tsx app/about.tsx
import Head from 'expo-router/head';
import { Text } from 'react-native';
export default function Page() {
  return (
    <>
      <Head>
        <title>My Blog Website</title>
        <meta name="description" content="This is my blog." />
      </Head>
      <Text>About my blog</Text>
    </>
  );
}
```
The head elements can be updated dynamically using the same API. However, it's useful for SEO to have static head elements rendered ahead of time.
## Static files
Expo CLI supports a root **public** directory that gets copied to the **dist** directory during static rendering. This is useful for adding static files like images, fonts, and other assets.
These files will be copied to the **dist** directory during static rendering:
> **info** **Web only**: Static assets can be accessed in runtime code using relative paths. For example, the **logo.png** can be accessed at `/logo.png`:
```tsx app/index.tsx
import { Image } from 'react-native';
export default function Page() {
  return <Image source={{ uri: '/logo.png' }} />;
}
```
## Fonts
Expo Font has automatic static optimization for font loading in Expo Router. When you load a font with `expo-font`, Expo CLI will automatically extract the font resource and embed it in the page's HTML, enabling preloading, faster hydration, and reduced layout shift.
The following snippet will load Inter into the namespace and statically optimize on web:
```tsx app/home.tsx
import { Text } from 'react-native';
import { useFonts } from 'expo-font';
export default function App() {
  const [isLoaded] = useFonts({
    inter: require('@/assets/inter.ttf'),
  });
  if (!isLoaded) {
    return null;
  }
  return <Text style={{ fontFamily: 'inter' }}>Hello Universe</Text>;
}
```
This generates the following static HTML:
```html dist/home.html
<link rel="preload" href="/assets/inter.ttf" as="font" crossorigin />
<style id="expo-generated-fonts" type="text/css">
  @font-face {
    font-family: inter;
    src: url(/assets/inter.ttf);
    font-display: auto;
  }
</style>
```
- Static font optimization requires the font to be loaded synchronously. If the font isn't statically optimized, it could be because it was loaded inside a `useEffect`, deferred component, or async function.
- Static optimization is only supported with `Font.loadAsync` and `Font.useFonts` from `expo-font`. Wrapper functions are supported as long as the wrappers are synchronous.
## Common questions
### How do I add a custom server?
There is no prescriptive way to add a custom server. You can use any server you want. However, you will need to handle dynamic routes yourself. You can use the `generateStaticParams` function to generate static HTML files for known routes.
In the future, there will be a server API, and a new `web.output` mode which will generate a project that will (amongst other things) support dynamic routes.
## Server-side Rendering
Rendering at request-time (SSR) is not supported in `web.output: 'static'`. This will likely be added in a future version of Expo Router.
### Where can I deploy statically rendered websites?
You can deploy your statically rendered website to any static hosting service. Here are some popular options:
- [EAS Hosting](/eas/hosting/introduction/)
- [Netlify](https://www.netlify.com/)
- [Cloudflare Pages](https://pages.cloudflare.com/)
- [AWS Amplify](https://aws.amazon.com/amplify/)
- [Vercel](https://vercel.com/)
- [GitHub Pages](https://pages.github.com/)
- [Render](https://render.com/)
- [Surge](https://surge.sh/)
>
注意：你不需要将单页应用样式的重定向添加到静态托管服务。静态网站不是单页应用。它是静态 HTML 文件的集合。
¥**Note:** You don't need to add Single-Page Application styled redirects to your static hosting service. The static website is not a single-page application. It is a collection of static HTML files.


## 异步路由

了解如何在 Expo Router 中使用异步打包来加速开发。

>  **important** 异步路由是一项实验性功能。
>
> ¥Async routes is an experimental feature.
<ContentSpotlight file="expo-router/async-routes.mp4" loop={false} />
Expo Router 可以使用 [反应悬念](https://react.nodejs.cn/reference/react/Suspense).5 根据路由文件自动分割你的 JavaScript 包。这可以实现更快的开发，因为只有你导航到的路由才会被打包或加载到内存中。这对于减少应用的初始包大小也很有用。
¥Expo Router can automatically split your JavaScript bundle based on the route files using [React Suspense](https://react.nodejs.cn/reference/react/Suspense). This enables faster development as only the routes you navigate to will be bundled or loaded into memory. This can also be useful for reducing the initial bundle size for your application.
使用 Hermes 引擎的应用不会从包分割中获益那么多，因为字节码已经提前进行了内存映射。但是，它将改进你的无线更新、React 服务器组件和 Web 支持。
¥Apps using the Hermes Engine will not benefit as much from bundle splitting as the bytecode is already memory mapped ahead of time. However, it will improve your over-the-air updates, React Server Components, and web support.
> 在原生平台上打包生产时，所有悬念边界将被禁用，并且不会有加载状态。
>
> ¥When bundling for production **on native platforms**, all suspense boundaries **will be disabled** and there will be no loading states.
<a id="how-it-works"></a>
## 工作原理
¥How it works
所有路由都包含在悬念边界内并异步加载。这意味着你第一次导航到路由时，加载时间会稍长一些。但是，一旦加载，就会被缓存，后续访问将是即时的。
¥All Routes are wrapped inside a suspense boundary and are loaded asynchronously. This means that the first time you navigate to a route, it will take a little longer to load. However, once it is loaded, it will be cached and subsequent visits will be instant.
{/* The [Suspense fallback](https://react.nodejs.cn/reference/react/Suspense#displaying-a-fallback-while-content-is-loading) or loading state **cannot be customized** at this time. We plan to add support in the future via a **route+loading.js** file. */}
加载错误在父路由中通过 [`ErrorBoundary`](/router/error-handling/#errorboundary) 导出进行处理。
¥Loading errors are handled in the parent route, via the [`ErrorBoundary`](/router/error-handling/#errorboundary) export.
异步路由在开发过程中无法进行静态分析，因此所有文件都将被视为路由，即使它们不导出默认组件。组件打包并加载后，任何无效的路由都将使用后备警告屏幕。
¥Async routes cannot be statically analyzed during development, so all files will be treated as routes even if they don't export a default component. After the component is bundled and loaded, any invalid route will use a fallback warning screen.
对于熟悉高级打包技术的人来说，异步路由功能由 [反应悬念](https://react.nodejs.cn/reference/react/Suspense)、[基于路由的打包分割](https://legacy.reactjs.org/docs/code-splitting.html#route-based-code-splitting) 和 [懒惰打包](https://github.com/react-native-community/discussions-and-proposals/blob/main/proposals/0605-lazy-bundling.md)（正在开发中）组成。
¥For those familiar with advanced bundling techniques, the async routes feature is composed of [React Suspense](https://react.nodejs.cn/reference/react/Suspense), [route-based bundle splitting](https://legacy.reactjs.org/docs/code-splitting.html#route-based-code-splitting) and [lazy bundling](https://github.com/react-native-community/discussions-and-proposals/blob/main/proposals/0605-lazy-bundling.md) (in development).
<a id="setup"></a>
## 设置
¥Setup
通过在 [应用配置](/versions/latest/config/app/) 的 Expo Router 配置插件中设置 `asyncRoutes` 选项来启用该功能：
¥Enable the feature by setting the `asyncRoutes` option in the Expo Router config plugin of your [app config](/versions/latest/config/app/):
> 将 `asyncRoutes` 设置为 `true` 以启用生产环境的 bundle splitting。
>
> ¥Set `asyncRoutes` to `true` to enable production bundle splitting.
```json app.json
    {
      "expo": {
        "plugins": [
          [
            "expo-router",
            {
              "origin": "https://acme.com",
              "asyncRoutes": {
                "web": true,
                "default": "development"
              }
            }
          ]
        ]
      }
    }
    ```
你可以使用对象为 `asyncRoutes` 设置特定于平台的设置（`default`、`android`、`ios` 或 `web`）：
¥You can set platform-specific settings (`default`, `android`, `ios` or `web`) for `asyncRoutes` using an object:
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-router",
        {
          "origin": "https://acme.com",
          "asyncRoutes": {
            "web": true,
            "android": false,
            "default": "development"
          }
        }
      ]
    ]
  }
}
```
然后，当你即将启动项目时，可以使用 `--clear` 标志来清除 Metro 缓存。这将确保路由异步加载：
¥Then, when you are about to start your project, you can use the `--clear` flag to clear the Metro cache. This will ensure that the routes are loaded asynchronously:
```sh
$ npx expo start --clear
$ npx expo export --clear
```
<a id="static-rendering"></a>
## 静态渲染
¥Static rendering
生产 Web 应用支持静态渲染，方法是在 Node.js 中同步渲染所有 Suspense 边界，然后根据给定 HTML 文件的所有选定路由将 HTML 中的所有异步块链接在一起。这可确保你不会在服务器导航中遇到加载状态瀑布式的情况。后续导航将递归加载任何丢失的块。
¥Static rendering is supported in production web apps by rendering all Suspense boundaries synchronously in Node.js, then linking all of async chunks together in the HTML based on all the selected routes for a given HTML file. This ensures you don't encounter a waterfall of loading states on server navigations. Subsequent navigations will recursively load any missing chunks.
为了确保一致的首次渲染，通向 URL 的叶路由的所有布局路由都将包含在初始服务器响应中。
¥To ensure a consistent first render, all layout routes leading up to the leaf route for a URL will be included in the initial server response.
使用 `unstable_settings = { initialRouteName: '...' }` 定义的所有初始路由将包含在初始 HTML 文件中，因为它们是第一次渲染所必需的。例如，如果服务器请求是针对模态的，则还将包括模态下渲染的屏幕，以确保模态正确渲染。
¥All initial routes, defined with `unstable_settings = { initialRouteName: '...' }` will be included in the initial HTML file as they are required for the first render. For example, if the server request is for a modal, the screen rendered under the modal will also be included to ensure the modal is rendered correctly.
<a id="caveats"></a>
## 注意事项
¥Caveats
异步路由代表了我们未来计划如何支持 [反应服务器组件](https://react.nodejs.cn/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023#react-server-components) 的早期预览。因此，有一些注意事项需要注意：
¥Async Routes represents an early preview of how we plan to support [React Server Components](https://react.nodejs.cn/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023#react-server-components) in the future. As such, there are some caveats to be aware of:
* 异步路由尚不支持原生生产应用。
  ¥Async Routes do not support native production apps yet.
* 在开发过程中，运行时 JavaScript 是惰性打包的，因此你可能会遇到 HTML 与可用 JavaScript 不匹配的情况。
  ¥In development, the runtime JavaScript is lazily bundled so you may encounter cases where the HTML doesn't match the available JavaScript.
* 目前无法自定义加载状态。
  ¥The loading state cannot be customized at this time.


## API 路由

了解如何使用 Expo Router 创建服务器端点。

Expo Router 使你能够在应用目录中为所有平台编写安全的服务器代码。
¥Expo Router enables you to write secure server code for all platforms, right in your **app** directory.
```ts app/hello+api.ts
export function GET(request: Request) {
  return Response.json({ hello: 'world' });
}
```
服务器功能需要自定义服务器，可以部署到 EAS 或大多数 [其他托管服务提供商](#deployment)。
¥Server features require a custom server, which can be deployed to EAS or most [other hosting providers](#deployment).
Video Tutorial: [Watch: Expo Router API Routes Handle Requests & Stream Data](https://www.youtube.com/watch?v=2_UzR1wdimI)
<a id="what-are-api-routes"></a>
## 什么是 API 路由
¥What are API Routes
API 路由是在路由匹配时在服务器上执行的函数。它们可用于安全地处理敏感数据（例如 API 密钥），或实现自定义服务器逻辑（例如交换访问令牌的授权代码）。API 路由应在符合 [WinterCG](https://wintercg.org/) 的环境中执行。
¥API Routes are functions that are executed on a server when a route is matched. They can be used to handle sensitive data, such as API keys securely, or implement custom server logic, such as exchanging auth codes for access tokens. API Routes should be executed in a [WinterCG](https://wintercg.org/)-compliant environment.
在 Expo 中，API 路由通过在 app 目录中创建带有 `+api.ts` 扩展名的文件来定义。例如，当路由 `/hello` 匹配时，将执行以下 API 路由。
¥In Expo, API Routes are defined by creating files in the **app** directory with the `+api.ts` extension. For example, the following API route is executed when the route `/hello` is matched.
<a id="create-an-api-route"></a>
## 创建 API 路由
¥Create an API route
Step 1: 
Ensure your project is using server output, this will configure the export and production builds to generate a server bundle as well as the client bundle.
```json app.json
{
  "web": {
    "output": "server"
  }
}
```
Step 2: 
An API route is created in the **app** directory. For example, add the following route handler. It is executed when the route `/hello` is matched.
```ts app/hello+api.ts
export function GET(request: Request) {
  return Response.json({ hello: 'world' });
}
```
You can export any of the following functions `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS` from a server route. The function executes when the corresponding HTTP method is matched. Unsupported methods will automatically return `405: Method not allowed`.
Step 3: 
Start the development server with Expo CLI:
```sh
$ npx expo
```
Step 4: 
You can make a network request to the route to access the data. Run the following command to test the route:
```sh
$ curl http://localhost:8081/hello
```
You can also make a request from the client code:
```tsx app/index.tsx
import { Button } from 'react-native';
async function fetchHello() {
  const response = await fetch('/hello');
  const data = await response.json();
  alert('Hello ' + data.hello);
}
export default function App() {
  return <Button onPress={() => fetchHello()} title="Fetch hello" />;
}
```
Relative fetch requests automatically fetch relative to the dev server origin in development, and can be configured in production using the `origin` field in the **app.json**:
```json app.json
{
  "plugins": [
    [
      "expo-router",
      {
        "origin": "https://evanbacon.dev/"
      }
    ]
  ]
}
```
This URL can be automatically configured during EAS Builds by setting the `EXPO_UNSTABLE_DEPLOY_SERVER=1` environment variable. This will trigger a versioned server deployment which sets the origin to a preview deploy URL automatically.
Step 5: 
Deploy the website and server to a [hosting provider](#deployment) to access the routes in production on both native and web.
> **warning** API route filenames cannot have platform-specific extensions. For example, **hello+api.web.ts** will not work.
## Requests
Requests use the global, standard [`Request`](https://fetch.spec.whatwg.org/#request) object.
```ts app/blog/[post]+api.ts
export async function GET(request: Request, { post }: Record<string, string>) {
  // const postId = new URL(request.url).searchParams.get('post')
  // fetch data for 'post'
  return Response.json({ ... });
}
```
### Request body
Use the `request.json()` function to access the request body. It automatically parses the body and returns the result.
```ts app/validate+api.ts
export async function POST(request: Request) {
  const body = await request.json();
  return Response.json({ ... });
}
```
### Request query parameters
Query parameters can be accessed by parsing the request URL:
```ts app/endpoint+api.ts
export async function GET(request: Request) {
  const url = new URL(request.url);
  const post = url.searchParams.get('post');
  // fetch data for 'post'
  return Response.json({ ... });
}
```
## Response
Responses use the global, standard [`Response`](https://fetch.spec.whatwg.org/#response) object.
```ts app/demo+api.ts
export function GET() {
  return Response.json({ hello: 'universe' });
}
```
## Errors
You can respond to server errors by using the `Response` object.
```ts app/blog/[post].ts
export async function GET(request: Request, { post }: Record<string, string>) {
  if (!post) {
    return new Response('No post found', {
      status: 404,
      headers: {
        'Content-Type': 'text/plain',
      },
    });
  }
  // fetch data for `post`
  return Response.json({ ... });
}
```
Making requests with an undefined method will automatically return `405: Method not allowed`. If an error is thrown during the request, it will automatically return `500: Internal server error`.
## Bundling
API Routes are bundled with Expo CLI and [Metro bundler](/guides/customizing-metro). They have access to all of the language features as your client code:
- [TypeScript](/guides/typescript) &mdash; types and [**tsconfig.json** paths](/guides/typescript/#path-aliases-optional).
- [Environment variables](/guides/environment-variables) &mdash; server routes have access to all environment variables, not just the ones prefixed with `EXPO_PUBLIC_`.
- Node.js standard library &mdash; ensure that you are using the correct version of Node.js locally for your server environment.
- **babel.config.js** and **metro.config.js** support &mdash; settings work across both client and server code.
## Security
Route handlers are executed in a sandboxed environment that is isolated from the client code. It means you can safely store sensitive data in the route handlers without exposing it to the client.
- Client code that imports code with a secret is included in the client bundle. It applies to **all files** in the **app directory** even though they are not a route handler file (such as suffixed with **+api.ts**).
- If the secret is in a **&lt;...&gt;+api.ts** file, it is not included in the client bundle. It applies to all files that are imported in the route handler.
- The secret stripping takes place in `expo/metro-config` and requires it to be used in the **metro.config.js**.
## Deployment
When you're ready to deploy to production, run [`npx expo export --platform web`](/more/expo-cli#exporting) to create the server bundle in the **dist** directory. This server can be tested locally with `npx expo serve` (available in Expo SDK 52 and higher), visit the URL in a web browser or create a native build with the `origin` set to the local server URL.
You can deploy the server for production using [EAS Hosting](/eas/hosting/get-started) or another third-party service.
### Native deployment
> **important** This is an experimental feature starting in SDK 52 and above. The process will be more automated and have better support in future versions.
Server features (API routes, and React Server Components) in Expo Router are centered around native implementations of `window.location` and `fetch` which point to the remote server. In development, we automatically point to the dev server running with `npx expo start`, but for production native builds to work you'll need to deploy the server to a secure host and set the `origin` property of the Expo Router Config Plugin.
When configured, features like relative fetch requests `fetch('/my-endpoint')` will automatically point to the server origin.
This deployment process can experimentally be automated to ensure correct versioning during native builds with the `EXPO_UNSTABLE_DEPLOY_SERVER=1` environment variable.
Here's how to configure your native app to automatically deploy and link a versioned production server on build:
Step 1: 
Ensure the `origin` field is **NOT** set in the **app.json** or in the `expo.extra.router.origin` field. Also, ensure you aren't using **app.config.js** as this is not supported with automatically linked deployments yet.
Step 2: 
Setup [EAS Hosting](/eas/hosting/get-started) for the project by deploying once locally first.
```sh
$ npx expo export -p web
$ eas deploy
```
Step 3: 
Set the `EXPO_UNSTABLE_DEPLOY_SERVER` environment variable in your `.env` file. This will be used to enable the experimental server deployment functionality during EAS Build.
```sh .env
EXPO_UNSTABLE_DEPLOY_SERVER=1
```
Step 4: 
You're now ready to use automatic server deployment! Run the build command to start the process.
```sh
$ eas build
```
You can also run this locally with:
```sh
$ npx expo run:android --variant release
$ npx expo run:ios --configuration Release
```
Notes about automatic server deployment for native apps:
- Server failures may occur during the `Bundle JavaScript` phase of EAS Build if something was not setup correctly.
- You can manually deploy the server and set the `origin` URL before building the app if you'd like.
- Automatic deployment can be force skipped with the environment variable `EXPO_NO_DEPLOY=1`.
- Automatic deployment does not support [dynamic app config](/workflow/configuration/#dynamic-configuration) (**app.config.js** and **app.config.ts**) files yet.
- Logs from the deployment will be written to `.expo/logs/deploy.log`.
- Deployment will not run in `EXPO_OFFLINE` mode.
### Testing the native production app locally
It can often be useful to test the production build against a local dev server to ensure everything is working as expected. This can speed up the debugging process substantially.
Step 1: 
Export the production server:
```sh
$ npx expo export
```
Step 2: 
Host the production server locally:
```sh
$ npx expo serve
```
Step 3: 
Set the origin in the **app.json**'s `origin` field. Ensure no generated value is in `expo.extra.router.origin`. This should be `http://localhost:8081` (assuming `npx expo serve` is running on the default port).
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-router",
        {
          "origin": "http://localhost:8081"
        }
      ]
    ]
  }
}
```
Remember to remove this `origin` value when deploying to production.
Step 4: 
Build the app in release mode on to a simulator:
```sh
$ EXPO_NO_DEPLOY=1 npx expo run:ios --configuration Release
```
You should now see requests coming in to the local server. Use a tool like [Proxyman](https://proxyman.com/) to inspect network traffic for the simulator and gain better insight.
You can experimentally change the URL and quickly rebuild for iOS using the `--unstable-rebundle` flag. This will swap out the **app.json** and client assets for new ones, skipping the native rebuild.
For example, you can run `eas deploy` to get a new deployment URL, add it to the **app.json**, then run `npx expo run:ios --unstable-rebundle --configuration Release` to quickly rebuild the app with the new URL.
You will want to make a clean build before sending to the store to ensure no transient issues are present.
## Hosting on third-party services
> **important** This is experimental and subject to breaking changes. We have no continuous tests against this configuration.
Every cloud hosting provider needs a custom adapter to support the Expo server runtime. The following third-party providers have unofficial or experimental support from the Expo team.
Before deploying to these providers, it may be good to be familiar with the basics of [`npx expo export`](/more/expo-cli#exporting) command:
- **dist** is the default export directory for Expo CLI.
- Files in **public** directory are copied to **dist** on export.
- The `@expo/server` package is included with `expo` and delegates requests to the server routes.
- `@expo/server` does **not** inflate environment variables from **.env** files. They are expected to load either by the hosting provider or the user.
- Metro is not included in the server.
### Bun
Step 1: 
Export the website for production:
```sh
$ bunx expo export -p web
```
Step 2: 
Write a server entry file that serves the static files and delegates requests to the server routes:
```ts server.ts
import { createRequestHandler } from '@expo/server/adapter/bun';
const CLIENT_BUILD_DIR = `${process.cwd()}/dist/client`;
const SERVER_BUILD_DIR = `${process.cwd()}/dist/server`;
const handleRequest = createRequestHandler({ build: SERVER_BUILD_DIR });
const port = process.env.PORT || 3000;
Bun.serve({
  port: process.env.PORT || 3000,
  async fetch(req) {
    const url = new URL(req.url);
    console.log('Request URL:', url.pathname);
    const staticPath = url.pathname === '/' ? '/index.html' : url.pathname;
    const file = Bun.file(CLIENT_BUILD_DIR + staticPath);
    if (await file.exists()) return new Response(await file.arrayBuffer());
    return handleRequest(req);
  },
  websocket,
});
console.log(`Bun server running at http://localhost:${port}`);
```
Step 4: 
Start the server with `bun`:
```sh
$ bun run server.ts
```
### Express
Step 1: 
Install the required dependencies:
```sh
$ npm i -D express compression morgan
```
Step 2: 
Export the website for production:
```sh
$ npx expo export -p web
```
Step 3: 
Write a server entry file that serves the static files and delegates requests to the server routes:
```ts server.ts
#!/usr/bin/env node
const path = require('path');
const { createRequestHandler } = require('@expo/server/adapter/express');
const express = require('express');
const compression = require('compression');
const morgan = require('morgan');
const CLIENT_BUILD_DIR = path.join(process.cwd(), 'dist/client');
const SERVER_BUILD_DIR = path.join(process.cwd(), 'dist/server');
const app = express();
app.use(compression());
// http://express.nodejs.cn/en/advanced/best-practice-security.html#at-a-minimum-disable-x-powered-by-header
app.disable('x-powered-by');
process.env.NODE_ENV = 'production';
app.use(
  express.static(CLIENT_BUILD_DIR, {
    maxAge: '1h',
    extensions: ['html'],
  })
);
app.use(morgan('tiny'));
app.all(
  '/{*all}',
  createRequestHandler({
    build: SERVER_BUILD_DIR,
  })
);
const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Express server listening on port ${port}`);
});
```
Step 4: 
Start the server with `node` command:
```sh
$ node server.ts
```
### Netlify
> **important** This is experimental and subject to breaking changes. We have no continuous tests against this configuration.
Step 1: 
Create a server entry file. All requests will be delegated through this middleware. The exact file location is important.
```ts netlify/functions/server.ts
const { createRequestHandler } = require('@expo/server/adapter/netlify');
const handler = createRequestHandler({
  build: require('path').join(__dirname, '../../dist/server'),
});
module.exports = { handler };
```
Step 2: 
Create a Netlify configuration file at the root of your project to redirect all requests to the server function.
```yaml netlify.toml
[build]
  command = "expo export -p web"
  functions = "netlify/functions"
  publish = "dist/client"
[[redirects]]
  from = "/*"
  to = "/.netlify/functions/server"
  status = 404
[functions]
  # Include everything to ensure dynamic routes can be used.
  included_files = ["dist/server/**/*"]
[[headers]]
  for = "/dist/server/_expo/functions/*"
  [headers.values]
    # Set to 60 seconds as an example.
    "Cache-Control" = "public, max-age=60, s-maxage=60"
```
Step 3: 
After you have created the configuration files, you can build the website and functions with Expo CLI:
```sh
$ npx expo export -p web
```
Step 4: 
Deploy to Netlify with the [Netlify CLI](https://docs.netlify.com/cli/get-started/).
```sh
$ npm install netlify-cli -g
$ netlify deploy
```
You can now visit your website at the URL provided by Netlify CLI. Running `netlify deploy --prod` will publish to the production URL.
Step 5: 
If you're using any environment variables or **.env** files, add them to Netlify. You can do this by going to the **Site settings** and adding them to the **Build & deploy** section.
### Vercel
> **important** This is experimental and subject to breaking changes. We have no continuous tests against this configuration.
Step 1: 
Create a server entry file. All requests will be delegated through this middleware. The exact file location is important.
```ts api/index.ts
const { createRequestHandler } = require('@expo/server/adapter/vercel');
module.exports = createRequestHandler({
  build: require('path').join(__dirname, '../dist/server'),
});
```
Step 2: 
Create a Vercel configuration file (**vercel.json**) at the root of your project to redirect all requests to the server function.
For vercel.json v3: 
```json vercel.json
{
  "buildCommand": "expo export -p web",
  "outputDirectory": "dist/client",
  "functions": {
    "api/index.ts": {
      "runtime": "@vercel/node@5.1.8",
      "includeFiles": "dist/server/**"
    }
  },
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/api/index"
    }
  ]
}
```
The newer version of the **vercel.json** does not use `routes` and `builds` configuration options anymore, and serves your public assets from the **dist/client** output directory automatically.
For vercel.json v2: 
```json vercel.json
{
  "version": 2,
  "outputDirectory": "dist",
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/static-build",
      "config": {
        "distDir": "dist/client"
      }
    },
    {
      "src": "api/index.ts",
      "use": "@vercel/node",
      "config": {
        "includeFiles": ["dist/server/**"]
      }
    }
  ],
  "routes": [
    {
      "handle": "filesystem"
    },
    {
      "src": "/(.*)",
      "dest": "/api/index.ts"
    }
  ]
}
```
The **legacy** version of the **vercel.json** needs a `@vercel/static-build` runtime to serve your assets from the **dist/client** output directory.
Step 3: 
> **Note:** This step only applies to users of the **legacy** version of the **vercel.json**. If you're using v3, you can skip this step.
After you have created the configuration files, add a `vercel-build` script to your **package.json** file and set it to `expo export -p web`.
Step 4: 
Deploy to Vercel with the [Vercel CLI](https://vercel.com/docs/cli).
```sh
$ npm install vercel -g
$ vercel build
$ vercel deploy --prebuilt
```
You can now visit your website at the URL provided by the Vercel CLI.
<a id="known-limitations"></a>
## 已知的限制
¥Known limitations
API Routes beta 版本当前不支持多个已知功能。
¥Several known features are not currently supported in the API Routes beta release.
<a id="no-dynamic-imports"></a>
### 无动态导入
¥No dynamic imports
API 路由目前的工作方式是将所有代码（不包括 Node.js 内置代码）打包到一个文件中。这意味着你不能使用任何未与服务器打包的外部依赖。例如，无法使用诸如 `sharp` 之类的包含多个平台二进制文件的库。这将在未来版本中解决。
¥API Routes currently work by bundling all code (minus the Node.js built-ins) into a single file. This means that you cannot use any external dependencies that are not bundled with the server. For example, a library such as `sharp`, which includes multiple platform binaries, cannot be used. This will be addressed in a future version.
<a id="esm-not-supported"></a>
### 不支持 ESM
¥ESM not supported
当前的打包实现选择更加统一而不是灵活。这意味着原生不支持 ESM 的限制将转移到 API 路由中。所有代码都将被转译为 Common JS (`require`/`module.exports`)。但是，无论如何，我们建议你使用 ESM 编写 API 路由。这将在未来版本中解决。
¥The current bundling implementation opts to be more unified than flexible. This means the limitation of native not supporting ESM is carried over to API Routes. All code will be transpiled down to Common JS (`require`/`module.exports`). However, we recommend you write API Routes using ESM regardless. This will be addressed in a future version.


## 网站地图

了解如何使用站点地图通过 Expo Router 调试你的应用。

在原生上，你可以使用 [`uri-scheme`](https://www.npmjs.com/package/uri-scheme) CLI 测试在设备上打开原生链接。
¥On native, you can use the [`uri-scheme`](https://www.npmjs.com/package/uri-scheme) CLI to test opening native links on a device.
例如，如果你想在 iOS 上启动 Expo Go 应用前往 `/form-sheet` 路由，请运行：
¥For example, if you want to launch the Expo Go app on iOS to the `/form-sheet` route, run:
```sh
$ npx uri-scheme open exp://192.168.87.39:19000/--/form-sheet --ios
```
> 将 `192.168.87.39:19000` 替换为运行 `npx expo start` 时显示的 IP 地址。
>
> ¥Replace `192.168.87.39:19000` with the IP address shown when running `npx expo start`.
你还可以直接在 Safari 或 Chrome 等浏览器中搜索链接，以在物理设备上测试深度链接。了解有关 [测试深层链接](https://react-navigation.nodejs.cn/docs/deep-linking) 的更多信息。
¥You can also search for links directly in a browser like Safari or Chrome to test deep linking on physical devices. Learn more about [testing deep links](https://react-navigation.nodejs.cn/docs/deep-linking).
<a id="sitemap"></a>
## 网站地图
¥Sitemap
Expo Router 目前会自动注入 /_sitemap，提供应用中所有路由的列表。这对于调试很有用。
¥Expo Router currently injects a **/_sitemap** automatically that provides a list of all routes in the app. This is useful for debugging.
在 SDK 52 及以上版本中，可以通过在应用配置中将 `sitemap: false` 添加到 `expo-router` 配置插件来删除站点地图：
¥In SDK 52 and above, the sitemap can be removed by adding `sitemap: false` to the `expo-router` config plugin in the app config:
```json app.json
{
  "plugins": [
    [
      "expo-router",
      {
        "sitemap": false
      }
    ]
  ]
}
```
在 SDK 51 及以下版本中，可以通过在 app 目录中创建一个空的 _sitemap 文件来删除站点地图：
¥In SDK 51 and below, the sitemap can be removed by creating an empty **_sitemap** file inside the **app** directory:
```tsx app/_sitemap.tsx
export default function Sitemap() {
  return null;
}
```


## 类型化路由

了解如何在 Expo Router 中使用静态类型的链接和路由。

> 在你的项目中使用 TypeScript 时可用。Expo Router 开箱即用地支持标准 TypeScript。有关如何设置的更多信息，请参阅 [TypeScript](/guides/typescript/) 指南。
>
> ¥Available when using TypeScript in your project. Expo Router supports standard TypeScript out of the box. See the [TypeScript](/guides/typescript/) guide for more information on how to set it up.
Expo Router 支持使用 Expo CLI 自动生成 TypeScript 类型。这使得 `<Link>` 和 [钩子 API](/router/reference/hooks) 能够静态类型化。此功能目前处于测试阶段，默认情况下不启用。
¥Expo Router supports generating TypeScript types automatically with Expo CLI. This enables `<Link>`, and the [hooks API](/router/reference/hooks) to be statically typed. This feature is currently in beta and is not enabled by default.
<a id="get-started"></a>
## 开始使用
¥Get started
<a id="quick-start"></a>
### 快速开始
¥Quick start
如果你使用 [Expo 路由快速入门指南](/router/installation/#quick-start) 创建项目，那么你的项目已配置为使用类型化路由。Expo CLI 将在你第一次运行 `npx expo start` 时生成所需的类型文件。然后，每当你在 .tsx 文件中使用 Expo Router `<Link>` 组件时，你都可以对 `href` 属性使用自动补齐功能。
¥If you created your project using the [Expo Router quick start guide](/router/installation/#quick-start) then your project is already configured to use typed routes. The Expo CLI will generate the required type file the first time you run `npx expo start`. Then, you can use autocomplete for `href` props whenever you use an Expo Router `<Link>` component in a **.tsx** file.
<a id="manual-configuration"></a>
### 手动配置
¥Manual configuration
虽然该功能处于测试阶段，但你可以通过在 app.json 中将 `experiments.typedRoutes` 设置为 `true` 来启用它：
¥While the feature is in beta, you can enable it by setting `experiments.typedRoutes` to `true` in your **app.json**:
```json app.json
{
  "expo": {
    "experiments": {
      "typedRoutes": true
    }
  }
}
```
运行 `npx expo customize tsconfig.json` 以配置 tsconfig.json 以添加所需的 `includes` 字段。
¥Run `npx expo customize tsconfig.json` to configure your **tsconfig.json** to add the required `includes` fields.
然后，通过运行 `npx expo start` 启动开发服务器。你现在可以在 Expo Router `<Link>` 组件的 `href` 属性中使用自动补齐功能。
¥Then, start the development server by running `npx expo start`. You can now use autocomplete in the Expo Router `<Link>` component's `href` prop.
<a id="type-generation"></a>
## 类型生成
¥Type generation
Expo Router 中的类型化路由会在开发服务器启动时自动生成。默认情况下，这些生成的类型配置为不被 Git 跟踪，并将添加到本地 .gitignore 文件中。这可以确保自动生成的文件不会扰乱你的版本控制系统。
¥Typed routes in Expo Router are automatically generated when the development server starts. By default, these generated types are configured to be untracked by Git and will be added to the local **.gitignore** file. This ensures that autogenerated files do not clutter your version control system.
如果你发现自己需要在不启动开发服务器的情况下生成这些类型，例如在持续集成 (CI) 服务器上进行类型检查期间。为此，请在 CI 上运行命令 `npx expo customize tsconfig.json`。
¥If you find yourself in a situation where you need to generate these types without initiating the development server, such as during type checking on a Continuous Integration (CI) server. To do this, run the command `npx expo customize tsconfig.json` on the CI.
<a id="statically-typed-routes"></a>
## 静态类型路由
¥Statically typed routes
使用 `Href<T>` 的组件和函数现在将是静态类型的，并且具有更严格的定义。例如：
¥Components and functions that use `Href<T>` will now be statically typed and have a much stricter definition. For example:
```tsx
✅ <Link href="/about" />
✅ <Link href="/user/1" />
✅ <Link href={`/user/${id}`} />
✅ <Link href={("/user" + id) as Href} />
// TypeScript errors if href is not a valid route
❌ <Link href="/usser/1" />
```
对于动态路由，Href 需要是对象，并且它们的参数类型严格：
¥For dynamic routes, Href's need to be objects and their parameters are strictly typed:
```tsx
✅ <Link href={{ pathname: "/user/[id]", params: { id: 1 }}} />
// TypeScript errors as href is valid, but it should be a HrefObject with params
❌ <Link href="/user/[id]" />
// TypeScript errors as params contain invalid keys
❌ <Link href={{ pathname: "/user/[id]", params: { _id: 1 }}} />
// TypeScript errors as params contain unknown keys
❌ <Link href={{ pathname: "/user/[id]", params: { id: 1, id2: 2 }}} />
```
<a id="relative-paths"></a>
### 相对路径
¥Relative paths
静态类型的路由不支持相对路径。你需要对所有路由使用绝对路径：
¥Statically typed routes do not support relative paths. You'll need to use absolute paths for all routes:
```tsx
✅ <Link href="/about" />
// Relative paths are not supported
❌ <Link href="./about" />
```
你可以利用 `expo-router` 中的 `useSegments()` 钩子来创建复杂的相对路径。考虑以下结构：
¥You can leverage the `useSegments()` hooks from `expo-router` to create complex relative paths. Consider the following structure:
你可以使用 `useSegments()` 钩子来确保推送到同一选项卡以获取当前路由的第一段。
¥You can ensure that you push to the same tab by using the `useSegments()` hook to get the first segment of the current route.
```tsx button.tsx
import { Link, useSegments } from 'expo-router';
export function Button() {
  const [
    // This will be either `(feed)` or `(search)` depending on the current tab.
    first,
  ] = useSegments();
  return <Link href={`/${first}/profile`}>Push profile</Link>;
}
```
现在，你可以利用 app/(feed)/feed.tsx 和 app/(search)/search.tsx 中的 `<Button />` 来推送 `./profile`，同时保留当前选项卡。
¥Now, you can leverage `<Button />` from both **app/(feed)/feed.tsx** and **app/(search)/search.tsx** to push `./profile` while preserving the current tab.
如果你需要特定用途的段，可以将完整路由传递给 `useSegments`。
¥If you require the segments for a specific use, you can pass the full route to `useSegments`
```tsx button.tsx
import { Link, useSegments } from 'expo-router';
export function useMySegments() {
  const segments = useSegments<'app/(search)/profile.tsx'>();
  //    ^? segments = ['app', '(search)', 'profile']
  return segments;
}
```
<a id="imperative-navigation"></a>
## 命令式导航
¥Imperative navigation
你可以使用键入的 `router` 对象进行命令式导航：
¥You can use the typed `router` object to navigate imperatively:
```tsx
import { router } from 'expo-router';
router.push('/about');
```
或者使用键入的 `useRouter()` 钩子：
¥Or with the typed `useRouter()` hook:
```tsx
import { useRouter } from 'expo-router';
function Page() {
  const router = useRouter();
  router.push('/about');
  // ...
}
```
<a id="route-parameters"></a>
## 路由
¥Route parameters
对于强类型路由参数，你可以将完整的 href 传递给 `useLocalSearchParams` 和 `useGlobalSearchParams` 钩子
¥For strongly typed route parameters you can pass a full href to the `useLocalSearchParams` and `useGlobalSearchParams` hooks
```tsx app/search.tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';
export default function Page() {
  const {
    profile, // string
    search, // string[]
  } = useLocalSearchParams<'app/(search)/[profile]/[...search].tsx'>();
  return (
    <>
      <Text>Profile: {profile}</Text>
      <Text>Search: {search.join(',')}</Text>
    </>
  );
}
```
<a id="query-parameters"></a>
## 查询参数
¥Query parameters
大多数查询参数不会在文件系统中表示，因此无法自动键入。你可以通过将泛型传递给 `useLocalSearchParams` 和 `useGlobalSearchParams` 钩子来手动键入查询参数。例如：
¥Most query parameters will not be represented in the file system and therefore cannot be typed automatically. You can type query parameters manually by passing a generic to the `useLocalSearchParams` and `useGlobalSearchParams` hooks. For example:
```tsx app/search.tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';
export default function Page() {
  const { query } = useLocalSearchParams<{ query?: string }>();
  return <Text>Search: {query ?? 'unset'}</Text>;
}
```
如果你需要路由和查询参数的组合，请将路由作为第一个通用参数传递，然后传递查询参数
¥If you need a combination of route and query parameters, pass the route as the first generic and then the query parameters
```tsx app/search.tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';
export default function Page() {
  const { query, profile, search } = useLocalSearchParams<
    '/[profile]/[...search]',
    { query?: string }
  >();
  return <Text>Search: {query ?? 'unset'}</Text>;
}
```
<a id="changes-made-to-the-environment"></a>
## 对环境的改变
¥Changes made to the environment
启用类型化路由后，Expo CLI 将在项目的根目录中生成 git 忽略的 expo-env.d.ts 文件，更新 .gitignore 以忽略新的根 expo-env.d.ts 文件，并修改 tsconfig。 json 以包含新的 expo-env.d.ts 文件。
¥When typed routes is enabled, Expo CLI will generate a git ignored **expo-env.d.ts** file in your project's root directory, update the **.gitignore** to ignore the new root **expo-env.d.ts** file, and modify the **tsconfig.json** to include the new **expo-env.d.ts** file.
tsconfig.json 中的 `includes` 字段已更新以包含 expo-env.d.ts 和隐藏的 .expo 目录。这些条目是必需的，不应从文件中删除。
¥The `includes` field in your **tsconfig.json** gets updated to include **expo-env.d.ts** and a hidden **.expo** directory. These entries are required and should not be removed from the file.
任何时候都不应删除或更改生成的 expo-env.d.ts。它不应该被提交并且应该被版本控制忽略。
¥The generated **expo-env.d.ts** should not be removed or changed at any time. It should not be committed and should be ignored by version control.
<a id="global-types"></a>
### 全局类型
¥Global types
当启用类型化路由时，Expo CLI 会将以下全局类型添加到你的项目中：
¥Expo CLI will add the following global types to your project when typed routes is enabled:
* 套 `process.env.NODE_ENV = "development" | "production" | "test"`
  ¥Sets `process.env.NODE_ENV = "development" | "production" | "test"`
* 允许导入 `.[css|sass|scss]` 文件
  ¥Allows the importing of `.[css|sass|scss]` files
* 将 `*.module.[css|sass|scss]` 的导出设置为 `Record<string, string>`
  ¥Sets the exports of `*.module.[css|sass|scss]` to be `Record<string, string>`
* 添加 Metro 的 `require.context` 类型。这由 `expo/metro-config` 启用并用于静态路由生成。
  ¥Add types for Metro's `require.context`. This is enabled by `expo/metro-config` and used for static route generation.
<a id="react-native-web"></a>
### React Native Web
启用类型化路由后，Expo CLI 还增强了 `react-native` 类型以支持 React Native Web。进行了以下更改：
¥With typed routes enabled, Expo CLI also augments the `react-native` types to support React Native Web. The following changes are made:
* 为 `ViewStyle`、`TextStyle`、`ImageStyle` 添加其他仅 Web 样式
  ¥Add additional web-only styles for `ViewStyle`, `TextStyle`, `ImageStyle`
* 将 `tabIndex`、`aria-level`、`lang` 添加到 `TextProps`
  ¥Add `tabIndex`, `aria-level`, `lang` to `TextProps`
* Pressable 的 `children` 和 `style` 状态回调函数中添加 `hovered`
  ¥Add `hovered` to Pressable's `children` and `style` state callback function
* 添加 `className` 个元素
  ¥Add `className` elements


## 用于分析的屏幕跟踪

了解如何在使用 Expo Router 时启用屏幕跟踪以进行分析。

与 React Navigation 不同，Expo Router 始终可以访问 URL。这意味着屏幕跟踪就像网络一样简单。
¥Unlike React Navigation, Expo Router always has access to a URL. This means screen tracking is as easy as the web.
1. 创建一个高阶组件来观察当前选定的 URL
   ¥Create a higher-order component that observes the currently selected URL
2. 跟踪你的分析提供商中的 URL
   ¥Track the URL in your analytics provider
```tsx app/_layout.tsx
import { useEffect } from 'react';
import { usePathname, useGlobalSearchParams, Slot } from 'expo-router';
export default function Layout() {
  const pathname = usePathname();
  const params = useGlobalSearchParams();
  // Track the location in your analytics provider here.
  useEffect(() => {
    analytics.track({ pathname, params });
  }, [pathname, params]);
  // Export all the children routes in the most basic way.
  return <Slot />;
}
```
现在，当用户更改路由时，分析提供商将收到通知。
¥Now when the user changes routes, the analytics provider will be notified.
<a id="migrating-from-react-navigation"></a>
## 从 React 导航迁移
¥Migrating from React Navigation
React Navigation 的 [屏幕跟踪指南](https://react-navigation.nodejs.cn/docs/screen-tracking/) 无法对 Expo Router 所做的导航状态做出相同的假设。因此，实现需要使用 `onReady` 和 `onStateChange` 回调。如果可能，请避免使用这些方法，因为根 `<NavigationContainer />` 不直接暴露并允许在 Expo Router 中级联。
¥React Navigation's [screen tracking guide](https://react-navigation.nodejs.cn/docs/screen-tracking/) cannot make the same assumptions about the navigation state that Expo Router can. As a result, the implementation requires the use of `onReady` and `onStateChange` callbacks. Avoid using these methods if possible as the root `<NavigationContainer />` is not directly exposed and allows cascading in Expo Router.


## 顶层 src 目录

了解如何在 Expo Router 项目中使用顶层 src 目录。

随着项目的发展，将所有包含应用代码的目录移动到单个 src 目录中会很有帮助。Expo Router 开箱即用地支持此功能。
¥As your project grows, it can be helpful to move all the directories containing application code into a single **src** directory. Expo Router supports this out of the box.
只需将你的应用目录移动到 src/app 并重新启动开发服务器即可。
¥Simply move your **app** directory to **src/app** and restart the development server.
```sh
$ npx expo start
$ npx expo export
```
注意：
¥**Notes**:
* 配置文件（app.config.ts、app.json、package.json、metro.config.js、tsconfig.json）应保留在根目录中。
  ¥The config files (**app.config.ts**, **app.json**, **package.json**, **metro.config.js**, **tsconfig.json**) should remain in the root directory.
* src/app 目录的优先级高于应用根目录。如果两者都有，则仅使用 src/app 目录。
  ¥The **src/app** directory takes higher precedence than the root **app** directory. Only the **src/app** directory will be used if you have both.
* 公共目录应保留在根目录中。
  ¥The **public** directory should remain in the root directory.
* 静态渲染将自动使用 src/app 目录（如果存在）。
  ¥Static rendering will automatically use the **src/app** directory if it exists.
* 你可以考虑更新任何 [类型别名](/guides/typescript#path-aliases) 以指向 src 目录而不是根目录。
  ¥You may consider updating any [type aliases](/guides/typescript#path-aliases) to point to the **src** directory instead of the root directory.
<a id="custom-directory"></a>
## 自定义目录
¥Custom directory
>  **warning** 强烈建议不要更改默认根目录。我们不会接受有关具有自定义根目录的项目的错误报告。
>
> ¥Changing the default root directory is highly discouraged. We will not accept bug reports regarding projects with custom root directories.
你可以使用 Expo 路由配置插件危险地自定义根目录。下面将根目录更改为 src/routes，相对于项目根目录。
¥You can dangerously customize the root directory using the Expo Router Config Plugin. The following will change the root directory to **src/routes**, relative to the project root.
```json app.json
{
  "plugins": [
    [
      "expo-router",
      {
        "root": "./src/routes"
      }
    ]
  ]
}
```
这可能会导致意外的行为。许多工具都假设根目录是 app 或 src/app。只有 Expo CLI 的确切版本中的工具才会尊重配置插件。
¥This may lead to unexpected behavior. Many tools assume the root directory to be either **app** or **src/app**. Only tools in the exact version of Expo CLI will respect the config plugin.


## 测试 Expo Router 的配置

了解如何在使用 Expo Router 时为你的应用创建集成测试。

Expo Router 依赖于你的文件系统，这在为集成测试设置模拟时可能会带来挑战。Expo Router 的子模块 `expo-router/testing-library` 是一组构建在流行的 [`@testing-library/react-native`](https://callstack.github.io/react-native-testing-library/) 之上的测试实用程序，允许你快速创建预先配置用于测试的内存中 Expo Router 应用。
¥Expo Router relies on your file system, which can present challenges when setting up mocks for integration tests. Expo Router's submodule, `expo-router/testing-library`, is a set of testing utilities built on top of the popular [`@testing-library/react-native`](https://callstack.github.io/react-native-testing-library/) and allows you to quickly create in-memory Expo Router apps that are pre-configured for testing.
<a id="configuration"></a>
## 配置
¥Configuration
在继续之前，请确保你已根据项目中的 [使用 Jest 进行单元测试](/develop/unit-testing/) 和 [`@testing-library/react-native`](https://callstack.github.io/react-native-testing-library/docs/start/quick-start) 设置了 `jest-expo`。
¥Before you proceed, ensure you have set up `jest-expo` according to the [Unit testing with Jest](/develop/unit-testing/) and [`@testing-library/react-native`](https://callstack.github.io/react-native-testing-library/docs/start/quick-start) in your project.
> 注意：使用 Expo Router 时，请勿将测试文件放在应用目录中。应用目录中的所有文件都必须是路由或布局文件。而是使用 **tests** 目录或单独的目录。这种方法在 [使用 Jest 进行单元测试](/develop/unit-testing/#structure-your-tests) 中进行了解释。
>
> ¥**Note**: When using Expo Router, do not put your test files inside the **app** directory. All files inside your **app** directory must be either routes or layout files. Instead, use the **__tests__** directory or a separate directory. This approach is explained in [Unit testing with Jest](/develop/unit-testing/#structure-your-tests).
<a id="jest-native-matchers-optional"></a>
### Jest Native 匹配器（可选）
¥Jest Native Matchers (optional)
[`@testing-library/jest-native`](https://testing-library.com/docs/ecosystem-jest-native/) 提供了自定义 Jest 匹配器，可用于扩展 `@testing-library/react-native` 的功能。如果安装，Expo Router 将自动执行 `@testing-library/jest-native` 设置。
¥[`@testing-library/jest-native`](https://testing-library.com/docs/ecosystem-jest-native/) provides custom Jest matchers that can be used to extend the functionality of `@testing-library/react-native`. If installed, Expo Router will automatically perform the `@testing-library/jest-native` setup.
<a id="renderrouter"></a>
## `renderRouter`
`renderRouter` 扩展了 [`render`](https://callstack.github.io/react-native-testing-library/docs/api#render) 的功能，以简化 Expo Router 的测试。它返回与 [`render`](https://callstack.github.io/react-native-testing-library/docs/api#render) 相同的查询对象，并且兼容 [`screen`](https://callstack.github.io/react-native-testing-library/docs/api#screen)，允许你使用标准 [查询接口](https://callstack.github.io/react-native-testing-library/docs/api/queries) 来定位组件。
¥`renderRouter` extends the functionality of [`render`](https://callstack.github.io/react-native-testing-library/docs/api#render) to simplify testing with Expo Router. It returns the same query object as [`render`](https://callstack.github.io/react-native-testing-library/docs/api#render), and is compatible with [`screen`](https://callstack.github.io/react-native-testing-library/docs/api#screen), allowing you to use the standard [query API](https://callstack.github.io/react-native-testing-library/docs/api/queries) to locate components.
`renderRouter` 接受与 `render` 相同的 [options](https://callstack.github.io/react-native-testing-library/docs/api#render-options)，并引入了一个附加选项 `initialUrl`，该选项设置用于模拟深度链接的初始路由。
¥`renderRouter` accepts the same [options](https://callstack.github.io/react-native-testing-library/docs/api#render-options) as `render` and introduces an additional option `initialUrl`, which sets an initial route for simulating deep-linking.
#### Inline file system
  `renderRouter(mock: Record<string, ReactComponent>, options: RenderOptions)`
  `renderRouter` 可以通过将对象作为第一个参数传递给该函数来提供文件系统的内联模拟。该对象的键是模拟文件系统路径。定义这些路径并排除文件扩展名时，请勿使用前导相对 (`./`) 或绝对 (`/`) 表示法。
  ¥`renderRouter` can provide inline-mocking of a file system by passing an object to this function as the first parameter. The keys of the object are the mock filesystem paths. **Do not use leading relative (`./`) or absolute (`/`) notation when defining these paths and exclude file extension.**
  ```tsx app.test.tsx
import { renderRouter, screen } from 'expo-router/testing-library';
it('my-test', async () => {
  const MockComponent = jest.fn(() => <View />);
  renderRouter(
    {
      index: MockComponent,
      'directory/a': MockComponent,
      '(group)/b': MockComponent,
    },
    {
      initialUrl: '/directory/a',
    }
  );
  expect(screen).toHavePathname('/directory/a');
});
```
#### Inline file system with `null` components
  `renderRouter(mock: string[], options: RenderOptions)`
  向 `renderRouter` 提供字符串数组将创建带有 `null` 组件 (`{ default: () => null }`) 的内联模拟文件系统。这对于不需要测试路由输出的测试场景非常有用。
  ¥Providing an array of strings to `renderRouter` will create an inline mock filesystem with `null` components (`{ default: () => null }`). This is useful for testing scenarios where you do not need to test the output of a route.
  ```tsx app.test.tsx
import { renderRouter, screen } from 'expo-router/testing-library';
it('my-test', async () => {
  renderRouter(['index', 'directory/a', '(group)/b'], {
    initialUrl: '/directory/a',
  });
  expect(screen).toHavePathname('/directory/a');
});
```
#### Path to fixture
  `renderRouter(fixturePath: string, options: RenderOptions)`
  `renderRouter` 可以接受目录路径来模拟现有的装置。确保提供的路径相对于当前测试文件。
  ¥`renderRouter` can accept a directory path to mock an existing fixture. Ensure that the provided path is relative to the current test file.
  ```tsx app.test.js
it('my-test', async () => {
  const MockComponent = jest.fn(() => <View />);
  renderRouter('./my-test-fixture');
});
```
#### Path to the fixture with overrides
  `renderRouter({ appDir: string, overrides: Record<string, ReactComponent>}, options: RenderOptions)`
  对于更复杂的测试场景，`renderRouter` 可以同时利用目录路径和内联模拟方法。`appDir` 参数采用表示目录路径名的字符串。overrides 参数是一个内联模拟，可用于覆盖 `appDir` 中的特定路径。这种组合允许对模拟环境进行微调控制。
  ¥For more intricate testing scenarios, `renderRouter` can leverage both directory path and inline-mocking methods simultaneously. The `appDir` parameter takes a string representing a pathname to a directory. The overrides parameter is an inline mock that can be used to override specific paths within the `appDir`. This combination allows for fine-tuned control over the mock environment.
  ```tsx app.test.js
it('my-test', async () => {
  const MockAuthLayout = jest.fn(() => <View />);
  renderRouter({
    appDir: './my-test-fixture',
    overrides: {
      'directory/(auth)/_layout': MockAuthLayout,
    },
  });
});
```
<a id="jest-matchers"></a>
## Jest 匹配器
¥Jest matchers
以下匹配已添加到 `expect`，可用于在 `screen` 上声明值。
¥The following matches have been added to `expect` and can be used to assert values on `screen`.
#### toHavePathname()
  针对给定字符串断言当前路径名。匹配器使用当前 `screen` 上的 [`usePathname`](/router/reference/hooks/#usepathname) 钩子的值。
  ¥Assert the current pathname against a given string. The matcher uses the value of the [`usePathname`](/router/reference/hooks/#usepathname) hook on the current `screen`.
  ```tsx app.test.ts
expect(screen).toHavePathname('/my-router');
```
#### toHavePathnameWithParams()
  针对给定字符串断言当前路径名，包括 URL 参数。这对于断言 URL 在 Web 浏览器中的出现很有用。
  ¥Assert the current pathname, including URL parameters, against a given string. This is useful to assert the appearance of URL in a web browser.
  ```tsx app.test.ts
expect(screen).toHavePathnameWithParams('/my-router?hello=world');
```
#### toHaveSegments()
  针对字符串数组断言当前段。匹配器使用当前 `screen` 上的 [`useSegments`](/router/reference/hooks/#usesegments) 钩子的值。
  ¥Assert the current segments against an array of strings. The matcher uses the value of the [`useSegments`](/router/reference/hooks/#usesegments) hook on the current `screen`.
  ```tsx app.test.ts
expect(screen).toHaveSegments(['[id]']);
```
#### useLocalSearchParams()
  针对对象断言当前本地 URL 参数。匹配器使用当前 `screen` 上的 [`useLocalSearchParams`](/router/reference/hooks/#uselocalsearchparams) 钩子的值。
  ¥Assert the current local URL parameters against an object. The matcher uses the value of the [`useLocalSearchParams`](/router/reference/hooks/#uselocalsearchparams) hook on the current `screen`.
  ```tsx app.test.ts
expect(screen).useLocalSearchParams({ first: 'abc' });
```
#### useGlobalSearchParams()
  断言当前屏幕的路径名与某个值匹配。使用 [`useGlobalSearchParams`](/router/reference/hooks/#useglobalsearchparams) 钩子的值进行比较。
  ¥Assert the current screen's pathname that matches a value. Compares using the value of [`useGlobalSearchParams`](/router/reference/hooks/#useglobalsearchparams) hook.
  针对对象断言当前全局 URL 参数。匹配器使用当前 `screen` 上的 [`useGlobalSearchParams`](/router/reference/hooks/#useglobalsearchparams) 钩子的值。
  ¥Assert the current global URL parameters against an object. The matcher uses the value of the [`useGlobalSearchParams`](/router/reference/hooks/#useglobalsearchparams) hook on the current `screen`.
  ```tsx app.test.ts
expect(screen).useGlobalSearchParams({ first: 'abc' });
```
#### toHaveRouterState()
  一种高级匹配器，用于针对对象断言当前路由状态。
  ¥An advanced matcher that asserts the current router state against an object.
  ```tsx app.test.ts
expect(screen).toHaveRouterState({
  routes: [{ name: 'index', path: '/' }],
});
```


## 故障排除

修复 Expo 路由设置的常见问题。

<a id="missing-files-or-source-maps-in-react-native-devtools"></a>
## React Native DevTools 中缺少文件或源映射
¥Missing files or source maps in React Native DevTools
如果你的 Chrome DevTools 在其忽略列表中有排除项，则可能会发生这种情况。要解决此问题，请使用 [React Native DevTools](https://rn.nodejs.cn/docs/react-native-devtools)：
¥This can happen if your Chrome DevTools has exclusions within its ignore list. To fix the issue, use [React Native DevTools](https://rn.nodejs.cn/docs/react-native-devtools):
1. 通过在终端窗口中运行的开发服务器中按 <kbd>j</kbd> 启动 React Native DevTools
   ¥Start the React Native DevTools by pressing <kbd>j</kbd> from the development server running in the terminal window
2. 单击齿轮图标打开“设置”
   ¥Open **Settings** by clicking the gear icon
3. 在扩展下，单击恢复默认值并重新加载
   ¥Under **Extensions**, click **Restore defaults and reload**
4. 再次打开“设置”，然后转到“忽略列表”选项卡
   ¥Open **Settings** again, and go to **Ignore List** tab
5. 取消选中 `/node_modules/` 的任何排除项
   ¥Uncheck any exclusions for `/node_modules/`
<a id="expo_router_app_root-not-defined"></a>
## `EXPO_ROUTER_APP_ROOT` 未定义
¥`EXPO_ROUTER_APP_ROOT` not defined
如果未定义 `process.env.EXPO_ROUTER_APP_ROOT`，你将看到以下错误：
¥If `process.env.EXPO_ROUTER_APP_ROOT` is not defined you'll see the following error:
```sh
$ Invalid call at line 11: process.env.EXPO_ROUTER_APP_ROOT First argument of require.context should be a string.
```
当项目 babel.config.js 中未使用 Babel 插件 `expo-router/babel` 时，可能会发生这种情况。你可以尝试使用以下方法清除缓存：
¥This can happen when the Babel plugin `expo-router/babel` is not used in the project **babel.config.js**. You can try clearing the cache with:
```sh
$ npx expo start --clear
```
或者，你可以通过在项目的根目录中创建一个包含以下内容的 index.js 文件来规避此问题：
¥Alternatively, you can circumvent this issue by creating an **index.js** file in the root of your project with the following contents:
```jsx index.js
import { registerRootComponent } from 'expo';
import { ExpoRoot } from 'expo-router';
// Must be exported or Fast Refresh won't update the context
export function App() {
  const ctx = require.context('./app');
  return <ExpoRoot context={ctx} />;
}
registerRootComponent(App);
```
然后，在 package.json 中更新应用的主入口点：
¥Then, update your app's main entry point in **package.json**:
```json package.json
{
  "main": "index.js"
}
```
> 不要使用它来更改根目录（应用），因为它不会考虑在任何其他地方的使用。
>
> ¥Do not use this to change the root directory (**app**) as it won't account for usage in any other places.
<a id="requirecontext-not-enabled"></a>
## `require.context` 未启用
¥`require.context` not enabled
当使用未启用上下文模块的自定义版本的 `@expo/metro-config` 时，可能会发生这种情况。Expo Router 要求项目 Metro.config.js 使用 `expo-router/metro` 作为默认配置。删除 metro.config.js，或扩展 `expo/metro-config`。请参阅 [定制 Metro](/guides/customizing-metro/) 了解更多信息。
¥This can happen when using a custom version of `@expo/metro-config` that does not enable context modules. Expo Router requires the project **metro.config.js** to use `expo-router/metro` as the default configuration. Delete the **metro.config.js**, or extend `expo/metro-config`. See [Customizing metro](/guides/customizing-metro/) for more information.
<a id="missing-back-button"></a>
## 缺少后退按钮
¥Missing back button
如果你设置了一个模式或另一个预计有后退按钮的屏幕，那么你需要将 [`unstable_settings`](/router/advanced/router-settings/) 添加到路由的布局中，以确保配置初始路由。初始路由对于移动应用来说有些独特，并且在系统中显得有些笨拙 - 有待改进。
¥If you set up a modal or another screen that is expected to have a back button, then you'll need to add [`unstable_settings`](/router/advanced/router-settings/) to the route's layout to ensure the initial route is configured. Initial routes are somewhat unique to mobile apps and fit awkwardly in the system — improvements pending.
```tsx app/_layout.tsx
export const unstable_settings = {
  initialRouteName: 'index',
};
```


# 迁移

## 从 React 导航迁移

了解如何使用 React Navigation 将项目迁移到 Expo Router。

React Navigation 和 Expo Router 都是用于路由和导航的 Expo 框架。Expo Router 是 React Navigation 的封装器，许多概念是相同的。
¥Both React Navigation and Expo Router are Expo frameworks for routing and navigation. Expo Router is a wrapper around React Navigation and many of the concepts are the same.
<a id="pitch"></a>
## 投入
¥Pitch
除了 React Navigation 的所有优点之外，Expo Router 还支持自动深度链接、[类型安全](/router/reference/typed-routes)、[延迟打包](/router/reference/async-routes)、[Web 上的静态渲染](/router/reference/static-rendering) 等。
¥Along with all the benefits of React Navigation, Expo Router enables automatic deep linking, [type safety](/router/reference/typed-routes), [deferred bundling](/router/reference/async-routes), [static rendering on web](/router/reference/static-rendering), and more.
<a id="anti-pitch"></a>
## 反投入
¥Anti-pitch
如果你的应用使用自定义 `getPathFromState` 或 `getStateFromPath` 组件，它可能不太适合 Expo Router。如果你使用这些函数来支持 [共享路由](/router/advanced/shared-routes)，那么你应该没问题，因为 Expo Router 对此有内置支持。
¥If your app uses a custom `getPathFromState` or `getStateFromPath` component, it may not be a good fit for Expo Router. If you're using these functions to support [shared routes](/router/advanced/shared-routes) then you should be fine as Expo Router has built-in support for this.
<a id="recommendations"></a>
## 建议
¥Recommendations
我们建议在开始迁移之前对你的代码库进行以下修改：
¥We recommend making the following modifications to your codebase before beginning the migration:
* 将 React 导航屏幕组件拆分为单独的文件。例如，如果你有 `<Stack.Screen component={HomeScreen} />`，请确保 `HomeScreen` 组件位于其自己的文件中。
  ¥Split React Navigation screen components into individual files. For example, if you have `<Stack.Screen component={HomeScreen} />`, then ensure the `HomeScreen` component is in its own file.
* 将项目转换为 [TypeScript](/guides/typescript/#migrating-existing-javascript-project)。这将使你更容易发现迁移过程中可能发生的错误。
  ¥Convert the project to [TypeScript](/guides/typescript/#migrating-existing-javascript-project). This will make it easier to spot errors that may occur during the migration.
* 将相对导入转换为 [输入别名](/guides/typescript/#path-aliases-optional)。例如，开始迁移之前的 `../../components/button.tsx` 到 `@/components/button`。这使得在文件系统中移动屏幕变得更容易，而无需更新相对路径。
  ¥Convert relative imports to [typed aliases](/guides/typescript/#path-aliases-optional). For example, `../../components/button.tsx` to `@/components/button` before starting the migration. This makes it easier to move screens around the filesystem without having to update the relative paths.
* 从 `resetRoot` 迁移出去。这用于在运行时对应用进行 "restart" 操作。这通常被认为是不好的做法，你应该重组应用的导航，这样就永远不会发生这种情况。
  ¥Migrate away from `resetRoot`. This is used to "restart" the app while running. This is generally considered bad practice, and you should restructure your app's navigation so this never needs to happen.
* 将初始路由重命名为 `index`。Expo Router 认为启动时打开的路由与 `/` 相匹配，React Navigation 用户通常会使用 "家" 等内容作为初始路由。
  ¥Rename the initial route to `index`. Expo Router considers the route that is opened on launch to match `/`, React Navigation users will generally use something such as "Home" for the initial route.
<a id="refactor-search-parameters"></a>
### 重构搜索参数
¥Refactor search parameters
将屏幕重构为 [使用可序列化的顶层查询参数](https://react-navigation.nodejs.cn/docs/params/#what-should-be-in-params)。我们也在 React Navigation 中推荐这一点。
¥Refactor screens to [use serializable top-level query parameters](https://react-navigation.nodejs.cn/docs/params/#what-should-be-in-params). We recommend this in React Navigation as well.
在 Expo Router 中，搜索参数只能序列化顶层值，例如 `number`、`boolean` 和 `string`。React Navigation 没有相同的限制，因此用户有时可以传递无效参数，例如函数、对象、地图等。
¥In Expo Router, search parameters can only serialize top-level values such as `number`, `boolean`, and `string`. React Navigation doesn't have the same restrictions, so users can sometimes pass invalid parameters like Functions, Objects, Maps, and so on.
如果你的代码有类似下面的内容：
¥If your code has something similar to the below:
```js
import { useNavigation } from '@react-navigation/native';
const navigation = useNavigation();
navigation.push('Followers', {
  onPress: profile => {
    navigation.push('User', { profile });
  },
});
```
考虑进行重组，以便可以从 "followers" 屏幕访问该功能。此时，你可以直接从 "followers" 屏幕访问路由并推送。
¥Consider restructuring so the function can be accessed from the "followers" screen. In this case, you can access the router and push directly from the "followers" screen.
<a id="eagerly-load-ui"></a>
### 提前加载 UI
¥Eagerly load UI
在 React Native 应用中，在加载资源和字体时从根组件到 `return null` 是很常见的。这是不好的做法，并且在 Expo Router 中通常不支持。如果你绝对必须推迟渲染，请确保你不要尝试导航到任何屏幕。
¥It's common in React Native apps to `return null` from the root component while assets and fonts are loading. This is bad practice and generally unsupported in Expo Router. If you absolutely must defer rendering, then ensure you don't attempt to navigate to any screens.
从历史上看，这种模式是存在的，因为如果你使用尚未加载的自定义字体，React Native 会抛出错误。我们在 React Native 0.72 (SDK 49) 中对此上游进行了更改，因此默认行为是在加载自定义字体时交换默认字体。如果你想在字体加载完成之前隐藏各个文本元素，请编写一个封装器 `<Text>`，它在字体加载之前返回 null。
¥Historically this pattern exists because React Native will throw errors if you use custom fonts that haven't loaded yet. We changed this upstream in React Native 0.72 (SDK 49) so the default behavior is to swap the default font when the custom font loads. If you'd like to hide individual text elements until a font has finished loading, write a wrapper `<Text>`, which returns null until the font has loaded.
在网络上，从根返回 `null` 将导致 [静态渲染](/router/reference/static-rendering) 跳过所有子级，从而导致无法搜索内容。这可以通过在 Chrome 中使用 "查看页面源代码" 或禁用 JavaScript 并重新加载页面来测试。
¥On web, returning `null` from the root will cause [static rendering](/router/reference/static-rendering) to skip all of the children, resulting in no searchable content. This can be tested by using "View Page Source" in Chrome, or by disabling JavaScript and reloading the page.
<a id="migration"></a>
## 迁移
¥Migration
<a id="delete-unused-or-managed-code"></a>
### 删除未使用或托管的代码
¥Delete unused or managed code
Expo Router 自动添加 `react-native-safe-area-context` 支持。
¥Expo Router automatically adds `react-native-safe-area-context` support.
```diff
- import { SafeAreaProvider } from 'react-native-safe-area-context';
export default function App() {
  return (
-    <SafeAreaProvider>
      <MyApp />
-    </SafeAreaProvider>
  )
}
```
Expo Router 不添加 `react-native-gesture-handler`（从 v3 开始），因此如果你使用手势处理程序或 `<Drawer />` 布局，则必须自己添加它。避免在 Web 上使用此包，因为它添加了大量经常不使用的 JavaScript。
¥Expo Router **does not** add `react-native-gesture-handler` (as of v3), so you'll have to add this yourself if you are using Gesture Handler or `<Drawer />` layout. Avoid using this package on web since it adds a lot of JavaScript that is often unused.
<a id="copy-screens-to-the-app-directory"></a>
### 将屏幕复制到应用目录
¥Copy screens to the app directory
在存储库的根目录或根 src 目录中创建一个应用目录。
¥Create an **app** directory at the root of your repo, or in a root **src** directory.
通过根据 [Expo Router 规则的应用](/router/basics/core-concepts/#the-rules-of-expo-router-applied) 文件创建文件来布局应用的结构。短横线和小写字母被认为是路由文件名的最佳实践。
¥Layout the structure of your app by creating files according to the [application of Expo Router rules](/router/basics/core-concepts/#the-rules-of-expo-router-applied). Kebab-case and lowercase letters are considered best practice for route filenames.
将导航器替换为目录，例如：
¥Replace navigators with directories, for example:
```jsx React Navigation
function HomeTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen name="Home" component={Home} />
      <Tab.Screen name="Feed" component={Feed} />
    </Tab.Navigator>
  );
}
function App() {
  return (
    // NavigationContainer is managed by Expo Router.
    <NavigationContainer
      linking={
        {
          // ...linking configuration
        }
      }
    >
      <Stack.Navigator>
        <Stack.Screen name="Settings" component={Settings} />
        <Stack.Screen name="Profile" component={Profile} />
        <Stack.Screen
          name="Home"
          component={HomeTabs}
          options={{
            title: 'Home Screen',
          }}
        />
      </Stack.Navigator>
    </NavigationContainer>
  );
}
```
**Expo 路由：**
¥**Expo Router:**
* 将 "main" 路由从 Home 重命名为 index，以确保它与 `/` 路径匹配。
  ¥Rename the "main" route from **Home** to **index** to ensure it matches the `/` path.
* 将名称转换为小写。
  ¥Convert names to lowercase.
* 将所有屏幕移动到应用目录内的适当文件位置。这可能需要一些实验。
  ¥Move all the screens to the appropriate file locations inside the app directory. This may take some experimenting.
```jsx app/_layout.js
import { Stack } from 'expo-router';
export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen
        name="(home)"
        options={
            title: 'Home Screen',
        }
      />
    </Stack>
  );
}
```
选项卡导航器将移动到子目录。
¥The tab navigator will be moved to a subdirectory.
```jsx app/(home)/_layout.js
import { Tabs } from 'expo-router';
export default function HomeLayout() {
  return <Tabs />;
}
```
<a id="use-expo-router-hooks"></a>
### 使用 Expo Router 钩子
¥Use Expo Router hooks
React Navigation v6 及更低版本会将 props `{ navigation, route }` 传递到每个屏幕。这种模式将在 React Navigation 中消失，我们从未将其引入到 Expo Router 中。
¥React Navigation v6 and lower will pass the props `{ navigation, route }` to every screen. This pattern is going away in React Navigation, and we never introduced it to the Expo Router.
相反，将 `navigation` 迁移到 `useRouter` 钩子。
¥Instead, migrate `navigation` to the `useRouter` hook.
```diff
+ import { useRouter } from 'expo-router';
export default function Page({
-  navigation
}) {
-  navigation.push('User', { user: 'bacon' });
+  const router = useRouter();
+  router.push('/users/bacon');
}
```
同样，从 `route` prop 迁移到 [`useLocalSearchParams`](/router/reference/hooks/#uselocalsearchparams) hook。
¥Similarly, migrate from the `route` prop to the [`useLocalSearchParams`](/router/reference/hooks/#uselocalsearchparams) hook.
```diff
+ import { useLocalSearchParams } from 'expo-router';
export default function Page({
-  route
}) {
-  const user = route?.params?.user;
+  const { user } = useLocalSearchParams();
}
```
要访问 [`navigation.navigate`](https://react-navigation.nodejs.cn/docs/navigation-object/#navigate)，请从 [`useNavigation`](/router/reference/hooks/#usenavigation) 钩子导入 `navigation` 属性。
¥To access the [`navigation.navigate`](https://react-navigation.nodejs.cn/docs/navigation-object/#navigate), import the `navigation` prop from [`useNavigation`](/router/reference/hooks/#usenavigation) hook.
```diff
+ import { useNavigation } from 'expo-router';
export default function Page({
+  const navigation = useNavigation();
  return (
    <Button onPress={navigation.navigate('screenName')}>
  )
})
```
<a id="migrate-the-link-component"></a>
### 迁移链接组件
¥Migrate the Link component
React Navigation 和 Expo Router 都提供 Link 组件。然而，Expo 的 Link 组件使用 `href` 而不是 [`to`](https://react-navigation.nodejs.cn/docs/use-link-props/#to)。
¥React Navigation and Expo Router both provide Link components. However, Expo's Link component uses `href` instead of [`to`](https://react-navigation.nodejs.cn/docs/use-link-props/#to).
```jsx
// React Navigation
<Link to="Settings" />
// Expo Router
<Link href="/settings" />
```
React Navigation 用户通常会使用 `useLinkProps` 钩子创建自定义 Link 组件来控制子组件。这在 Expo Router 中不是必需的，而是使用 `asChild` 属性。
¥React Navigation users will often create a custom Link component with the `useLinkProps` hook to control the child component. This isn't necessary in Expo Router, instead, use the `asChild` prop.
<a id="share-screens-across-navigators"></a>
### 跨导航器共享屏幕
¥Share screens across navigators
React Navigation 应用在多个导航器之间重用一组路由是很常见的。这通常与选项卡一起使用，以确保每个选项卡可以推送任何屏幕。
¥It's common for React Navigation apps to reuse a set of routes across multiple navigators. This is generally used with tabs to ensure each tab can push any screen.
在 Expo Router 中，你可以迁移到 [共享路由](/router/advanced/shared-routes) 或创建多个文件并从中重新导出相同的组件。
¥In Expo Router, you can either migrate to [shared routes](/router/advanced/shared-routes) or create multiple files and re-export the same component from them.
当你使用组或共享路由时，你可以使用完全限定的路由名称（例如 `/(home)/settings` 而不是 `/settings`）导航到特定选项卡。
¥When you use groups or shared routes, you can navigate to specific tabs by using the fully qualified route name, for example, `/(home)/settings` instead of `/settings`.
<a id="migrate-screen-tracking-events"></a>
### 迁移屏幕跟踪事件
¥Migrate screen tracking events
你可能根据我们的 [React Navigation 屏幕跟踪指南](https://react-navigation.nodejs.cn/docs/screen-tracking/) 进行了屏幕跟踪设置，根据 [Expo Router 屏幕跟踪指南](/router/reference/screen-tracking) 进行更新。
¥You may have your screen tracking setup according to our [React Navigation screen tracking guide](https://react-navigation.nodejs.cn/docs/screen-tracking/), update it according to the [Expo Router screen tracking guide](/router/reference/screen-tracking).
<a id="use-platform-specific-components-for-screens"></a>
### 使用特定于平台的屏幕组件
¥Use platform-specific components for screens
有关根据平台切换 UI 的信息，请参阅 [特定于平台的模块](/router/advanced/platform-specific-modules) 指南。
¥Refer to the [platform-specific modules](/router/advanced/platform-specific-modules) guide for info on switching UI based on the platform.
<a id="replace-the-navigationcontainer"></a>
### 更换 `NavigationContainer`
¥Replace the `NavigationContainer`
全局 React Navigation [`<NavigationContainer />`](https://react-navigation.nodejs.cn/docs/navigation-container/) 完全在 Expo Router 中管理。Expo Router 提供的系统可以实现与 `NavigationContainer` 相同的功能，而无需直接使用它。
¥The global React Navigation [`<NavigationContainer />`](https://react-navigation.nodejs.cn/docs/navigation-container/) is completely managed in Expo Router. Expo Router provides systems for achieving the same functionality as the `NavigationContainer` without needing to use it directly.
Note: API substitutions
---
### Ref
The `NavigationContainer` ref should not be accessed directly. Use the following methods instead.
#### `resetRoot​`
Navigate to the initial route of the application. For example, if your app starts at `/` (recommended), then you can replace the current route with `/` using this method.
```jsx
import { useRouter } from 'expo-router';
function Example() {
  const router = useRouter();
  return (
    <Text
      onPress={() => {
        // Go to the initial route of the application.
        router.replace('/');
      }}>
      Reset App
    </Text>
  );
}
```
#### `getRootState`
Use `useRootNavigationState()`.
#### `getCurrentRoute`
Unlike React Navigation, Expo Router can reliably represent any route with a string. Use the [`usePathname()`](/router/reference/hooks/#usepathname) or [`useSegments()`](/router/reference/hooks/#usesegments) hooks to identify the current route.
#### `getCurrentOptions`
Use the [`useLocalSearchParams()`](/router/reference/hooks/#uselocalsearchparams) hook to get the current route's query parameters.
#### `addListener`
The following events can be migrated:
#### `state`
Use the [`usePathname()`](/router/reference/hooks/#usepathname) or [`useSegments()`](/router/reference/hooks/#usesegments) hooks to identify the current route. Use in conjunction with `useEffect(() => {}, [...])` to observe changes.
#### `options`
Use the [`useLocalSearchParams()`](/router/reference/hooks/#uselocalsearchparams) hook to get the current route's query parameters. Use in conjunction with `useEffect(() => {}, [...])` to observe changes.
### props
Migrate the following `<NavigationContainer />` props:
#### `initialState`
In Expo Router, you can rehydrate your application state from a route string (for example, `/user/evanbacon`). Use [redirects](/router/reference/redirects/) to handle initial states. See [shared routes](/router/advanced/shared-routes/) for advanced redirects.
Avoid using this pattern in favor of deep linking (for example, a user opens your app to `/profile` rather than from the home screen) as it is most analogous to the web. If an app crashes due to a particular screen, it's best to avoid automatically navigating back to that exact screen when the app starts as it may require reinstalling the app to fix.
#### `onStateChange`
Use the [`usePathname()`](/router/reference/hooks/#usepathname), [`useSegments()`](/router/reference/hooks/#usesegments), and [`useGlobalSearchParams()`](/router/reference/hooks/#useglobalsearchparams) hooks to identify the current route state. Use in conjunction with `useEffect(() => {}, [...])` to observe changes.
- If you're attempting to track screen changes, follow the [Screen Tracking guide](/router/reference/screen-tracking/).
- React Navigation recommends avoiding [`onStateChange`](https://react-navigation.nodejs.cn/docs/navigation-container/#onstatechange).
#### `onReady`
In React Navigation, [`onReady`](https://react-navigation.nodejs.cn/docs/navigation-container/#onready) is most often used to determine when the splash screen should hide or when to track screens using analytics. Expo Router has special handling for both of these use cases. Assume the navigation is always ready for navigation events in the Expo Router.
- See the [Screen Tracking guide](/router/reference/screen-tracking/) for info on migrating analytics from React Navigation.
- See the [Splash Screen feature](/develop/user-interface/splash-screen-and-app-icon/) for info on handling the splash screen.
#### `onUnhandledAction`
Actions are always handled in Expo Router. Use [dynamic routes](/router/basics/notation/#square-brackets) and [404 screens](/router/error-handling/#unmatched-routes) in favor of [`onUnhandledAction`](https://react-navigation.nodejs.cn/docs/navigation-container/#onunhandledaction).
#### `linking`
The [`linking`](https://react-navigation.nodejs.cn/docs/navigation-container/#linking) prop is automatically constructed based on the files to the **app** directory.
#### `fallback`
The [`fallback`](https://react-navigation.nodejs.cn/docs/navigation-container/#fallback) prop is automatically handled by Expo Router. Learn more in the [Splash Screen](/versions/latest/sdk/splash-screen/) reference.
#### `theme`
In React Navigation, you set the theme for the entire app using the [`<NavigationContainer />`](https://react-navigation.nodejs.cn/docs/navigation-container/#theme) component. Expo Router manages the root container for you, so instead you should set the theme using the `ThemeProvider` directly.
```tsx app/_layout.tsx
import { ThemeProvider, DarkTheme, DefaultTheme, useTheme } from '@react-navigation/native';
import { Slot } from 'expo-router';
export default function RootLayout() {
  return (
    <ThemeProvider value={DarkTheme}>
      <Slot />
    </ThemeProvider>
  );
}
```
You can use this technique at any layer of the app to set the theme for a specific layout. The current theme can be accessed with the `useTheme` hook from `@react-navigation/native`.
#### `children`
The `children` prop is automatically populated based on the files in the **app** directory and the currently open URL.
#### `independent`
Expo Router does not support [`independent`](https://react-navigation.nodejs.cn/docs/navigation-container/#independent) containers. This is because the router is responsible for managing the single `<NavigationContainer />`. Any additional containers will not be automatically managed by Expo Router.
#### `documentTitle`
Use the [Head component](/router/reference/static-rendering#meta-tags) to set the webpage title.
#### `ref`
Use the `useNavigationContainerRef()` hook instead.
---
### Rewrite custom navigators
If your project has a custom navigator, you can rewrite this or port it to Expo Router.
To port, simply use the `withLayoutContext` function:
```js
import { createCustomNavigator } from './my-navigator';
export const CustomNavigator = withLayoutContext(createCustomNavigator().Navigator);
```
To rewrite, use the `Navigator` component, which wraps the [`useNavigationBuilder`](https://react-navigation.nodejs.cn/docs/custom-navigators#usenavigationbuilder) hook from React Navigation.
The return value of `useNavigationBuilder` can be accessed with the `Navigator.useContext()` hook from inside the `<Navigator />` component. Properties can be passed to `useNavigationBuilder` using the props of the `<Navigator />` component, this includes `initialRouteName`, `screenOptions`, `router`.
All of the `children` of a `<Navigator />` component will be rendered as-is.
- `Navigator.useContext`: Access the React Navigation `state`, `navigation`, `descriptors`, and `router` for the custom navigator.
- `Navigator.Slot`: A React component used to render the currently selected route. This component can only be rendered inside a `<Navigator />` component.
#### Example
Custom layouts have an internal context that is ignored when using the `<Slot />` component without a `<Navigator />` component wrapping it.
```jsx
import { View } from 'react-native';
import { TabRouter } from '@react-navigation/native';
import { Navigator, usePathname, Slot, Link } from 'expo-router';
export default function App() {
  return (
      <Header />
      <Slot />
    </Navigator>
  );
}
function Header() {;
  const pathname = usePathname();
  return (
    <View>
      <Link href="/">Home</Link>
      <Link
        href="/profile"
        Profile
      </Link>
      <Link href="/settings">Settings</Link>
    </View>
  );
}
```
### Use Expo Router's Splash Screen wrapper
Expo Router wraps `expo-splash-screen` and adds special handling to ensure it's hidden after the navigation mounts, and whenever an unexpected error is caught. Simply migrate from importing `expo-splash-screen` to importing `SplashScreen` from `expo-router`.
### Navigation state observation
If you're observing the navigation state directly, migrate to the [`usePathname`](/router/reference/hooks/#usepathname), [`useSegments`](/router/reference/hooks/#usesegments), and [`useGlobalSearchParams`](/router/reference/hooks/#useglobalsearchparams) hooks.
### Pass params to nested screens
Instead of using the [nested screen navigation events](https://react-navigation.nodejs.cn/docs/params/#passing-params-to-nested-navigators), use a qualified href:
```js
// React Navigation
navigation.navigate('Account', {
  screen: 'Settings',
  params: { user: 'jane' },
});
// Expo Router
router.push({ pathname: '/account/settings', params: { user: 'jane' } });
```
### Set initial routes for deep linking and server navigation
In React Navigation, you can use the `initialRouteName` property of the linking configuration. In Expo Router, use [layout settings](/router/advanced/router-settings).
### Reset navigation state
You can use the [`reset`](https://react-navigation.nodejs.cn/docs/navigation-actions/#reset) action from the React Navigation library to reset the navigation state. It is dispatched using the [`useNavigation`](/router/reference/hooks/#usenavigation) hook from Expo Router to access the `navigation` prop.
In the below example, the `navigation` prop is accessible from the `useNavigation` hook and the `CommonActions.reset` action from `@react-navigation/native`. The object specified in the `reset` action replaces the existing navigation state with the new one.
```jsx app/screen.js
import { useNavigation } from 'expo-router'
import { CommonActions } from '@react-navigation/native'
export default function Screen() {
  const navigation = useNavigation();
  const handleResetAction = () => {
    navigation.dispatch(CommonActions.reset({
      routes: [{key: "(tabs)", name: "(tabs)"}]
    }))
  }
  return (
    <>
      {/* ...rest of the code */}
      <Button title='Reset' onPress={handleResetAction} />
    </>
  );
}
```
### Migrate TypeScript types
Expo Router can automatically generate [statically typed routes](/router/reference/typed-routes), this will ensure you can only navigate to valid routes.
## Additional information
### React Navigation themes
React Navigation navigators `<Stack>`, `<Drawer>`, and `` use a shared appearance provider. In React Navigation, you set the theme for the entire app using the `<NavigationContainer />` component. Expo Router manages the root container so that you can set the theme using the `ThemeProvider` directly.
```tsx app/_layout.tsx
import { ThemeProvider, DarkTheme, DefaultTheme, useTheme } from '@react-navigation/native';
import { Slot } from 'expo-router';
export default function RootLayout() {
  return (
    <ThemeProvider value={DarkTheme}>
      <Slot />
    </ThemeProvider>
  );
}
```
You can use this technique at any layer of the app to set the theme for a specific layout. The current theme can be accessed via `useTheme` hook from `@react-navigation/native`.
### React Navigation Elements
The [`@react-navigation/elements`](https://react-navigation.nodejs.cn/docs/elements/) library provides a set of UI elements and helpers that can be used to build a navigation UI. These components are designed to be composable and customizable. You can reuse the default functionality from the library or build your navigator's UI on top of it.
To use it with Expo Router, you need to install the library:
For npm: 
```sh
$ npm install @react-navigation/elements
```
For Yarn: 
```sh
$ yarn add @react-navigation/elements
```
要了解有关该库提供的组件和实用程序的更多信息，请参阅 [元素库](https://react-navigation.nodejs.cn/docs/elements/) 文档。
¥To learn more about the components and utilities the library provides, see [Elements library](https://react-navigation.nodejs.cn/docs/elements/) documentation.


## 从 Expo Webpack 迁移

了解如何使用 Expo Webpack 将网站迁移到 Expo Router。

最初的 Web 版本 Expo 基于 Webpack 4，主要侧重于构建单页应用 (SPA)。该方法基于 [创建反应应用](https://cra.nodejs.cn/)，并支持使用 Expo SDK 和 React Native for web 构建简单的 Web 应用。
¥The original **Expo for web** version was based on Webpack 4 and focused primarily on building single-page applications (SPAs). This approach was based on [Create React App](https://cra.nodejs.cn/) and enabled building simple web apps with Expo SDK and React Native for web.
Expo Router 是构建在 Web 和原生上运行的强大通用应用的新方法。本指南将帮助你将现有网站迁移到 Expo Router。
¥Expo Router is the new approach to building powerful universal apps that run on web and native. This guide will help you migrate your existing website to Expo Router.
React Navigation 和 Expo Router 都是用于路由和导航的 Expo 框架。Expo Router 是 React Navigation 的封装器，并且有许多共享概念。
¥Both React Navigation and Expo Router are Expo frameworks for routing and navigation. Expo Router is a wrapper around React Navigation and has many shared concepts.
<a id="pitch"></a>
## 投入
¥Pitch
>  **warning** `@expo/webpack-config` 已弃用，并且未收到任何新功能更新。
>
> ¥`@expo/webpack-config` is deprecated and not receiving any new feature updates.
与 Expo Webpack 不同，Expo Router 支持 [Web 上的静态渲染](/router/reference/static-rendering)，它支持搜索引擎优化 (SEO)、社交媒体预览和更快的加载时间。除了 React Navigation 的优点之外，它还支持自动深度链接、[类型安全](/router/reference/typed-routes)、[延迟打包](/router/reference/async-routes)、[模块化 HTML 模板](/router/reference/static-rendering#root-html)、[Web 上的静态渲染](/router/reference/static-rendering) 等。
¥Expo Router supports [static rendering on web](/router/reference/static-rendering), which enables search engine optimization (SEO), social media previews, and faster loading times, unlike Expo Webpack. Along with the benefits of React Navigation, it enables automatic deep linking, [type safety](/router/reference/typed-routes), [deferred bundling](/router/reference/async-routes), [modular HTML templates](/router/reference/static-rendering#root-html), [static rendering on web](/router/reference/static-rendering), and more.
Expo Router 还旨在通过在 Web 和原生之间共享导航而不影响功能或性能来解决 Expo Webpack 的主要跨平台问题。
¥Expo Router is also designed to fix the main cross-platform issue with Expo Webpack by sharing navigation between web and native without compromising functionality or performance.
<a id="anti-pitch"></a>
## 反投入
¥Anti-pitch
Expo Router 使用基于 [Metro](https://metrobundler.dev/) 的自定义打包器堆栈。它与 React Native 使用的打包器相同。这对于确保最大程度的代码可重用性非常有用，并且解决了跨平台使用不同打包器导致的许多分叉行为问题。这也意味着某些打包功能可能在 Expo Router 中尚不可用。
¥Expo Router uses a custom bundler stack based on [Metro](https://metrobundler.dev/). It is the same bundler used by React Native. This is great for ensuring maximum code reusability and solves many forked behavior issues from using different bundlers across platforms. This also means certain bundling features may not be available in Expo Router yet.
最终，作为一个完整的通用框架，Expo Router 是一个比 `@expo/webpack-config`（打包器集成）更强大的解决方案。它应该用于所有新的 Expo Web 项目。
¥Ultimately as a full universal framework, Expo Router is a substantially more robust solution than `@expo/webpack-config`, which is a bundler integration. It should be used for all new Expo web projects.
<a id="expo-cli"></a>
## Expo CLI
与 `@expo/webpack-config` 不同，Expo Router 对 Web 和原生使用相同的 CLI 命令和功能。有关 Expo Router 和 `@expo/webpack-config` 之间差异的更多信息，请参阅下表。
¥Unlike `@expo/webpack-config`, Expo Router uses the same CLI commands and features for web and native. Refer to the table below for more information on the differences between Expo Router and `@expo/webpack-config`.
| 特性                  | Expo 路由                | `@expo/webpack-config` |
| ------------------- | ---------------------- | ---------------------- |
| 启动命令                | `npx expo start`       | `npx expo start`       |
| 打包命令                | `npx expo export`      | `npx expo export:web`  |
| 输出目录                | **dist**               | **web-build**          |
| 静态目录                | **public**             | **web**                |
| 配置文件                | **metro.config.js**    | **webpack.config.js**  |
| 默认配置                | `@expo/metro-config`   | `@expo/webpack-config` |
| 打包分裂                | （SDK 50 • 网络）          |                        |
| 全局 CSS              | （SDK 50 • 网络）          |                        |
| CSS 模块              | （SDK 50 • 网络）          |                        |
| 静态字体优化              | （SDK 50 • 网络）          |                        |
| API 路由              | （SDK 50）               |                        |
| 多平台                 |                        |                        |
| 快速刷新                |                        |                        |
| 错误叠加                |                        |                        |
| 懒惰打包                |                        |                        |
| 静态生成                |                        |                        |
| 环境变量                |                        |                        |
| `tsconfig.json` 条路径 |                        |                        |
| 摇树                  | ([部分支持][tree-shaking]) |                        |
<a id="html-template"></a>
## HTML 模板
¥HTML template
在 `@expo/webpack-config` 中，所有路由共享一个 HTML 文件。该文件基于 `web/index.html` 中的模板，然后由 `@expo/webpack-config` 修改以包含必要的脚本和样式表。
¥In `@expo/webpack-config` all routes shared a single HTML file. This file was based on the template in `web/index.html` which was then modified by the `@expo/webpack-config` to include the necessary scripts and stylesheets.
在 Expo Router 中，有两种不同的渲染模式：
¥In Expo Router, there are two different rendering patterns:
* 受到推崇的：`web.output: "static"` 为应用中的每个路由输出一个新的 HTML 文件。这种方法可以让你 [使用 app/+html.js 文件动态生成整个 HTML 模板](/router/reference/static-rendering#root-html)。
  ¥**Recommended**: `web.output: "static"` which outputs a new HTML file for each route in the app. This approach lets you [dynamically generate the entire HTML template using the **app/+html.js** file](/router/reference/static-rendering#root-html).
* 不建议：`web.output: "single"` 输出单页应用。这种方法允许你使用 `public/index.html` 作为 HTML 模板文件。
  ¥**Not recommended**: `web.output: "single"` which outputs a single-page application. This approach lets you use `public/index.html` as the template HTML file.
<a id="static-resources"></a>
## 静态资源
¥Static resources
在 `@expo/webpack-config` 中，你可以在 `web` 目录中托管静态文件，该目录将从网站的根目录提供服务。例如，`web/favicon.ico` 由 `https://example.com/favicon.ico` 提供。
¥In `@expo/webpack-config`, you could host static files in the `web` directory, which would be served from the website's root. For example, `web/favicon.ico` was served from `https://example.com/favicon.ico`.
在 Expo Router 中，你可以使用公共目录来托管静态文件。例如，public/favicon.ico 由 `https://example.com/favicon.ico` 提供。与 Webpack 不同，Expo Router 的托管也可以在原生上运行。确保在生产中使用文件之前从服务器托管这些文件。
¥In Expo Router, you can use the **public** directory to host static files. For example, **public/favicon.ico** is served from `https://example.com/favicon.ico`. Unlike Webpack, Expo Router's hosting works on native too. Make sure to host the files from a server before using them in production.
<a id="bundling-for-production"></a>
## 打包用于生产
¥Bundling for production
在 `@expo/webpack-config` 中，你可以使用 `npx expo export:web` 打包你的网站进行生产。这会将包输出到 web-build 目录。
¥In `@expo/webpack-config`, you could bundle your website for production using `npx expo export:web`. This would output a bundle to the **web-build** directory.
在 Expo Router 中，使用 `npx expo export --platform web` 命令导出到 dist 目录。你可以使用 `--dump-sourcemap` 标志生成源映射。在构建时，public 目录的内容将被复制到 dist 目录。
¥In Expo Router, use the `npx expo export --platform web` command to export to the **dist** directory. You can generate sourcemaps with the `--dump-sourcemap` flag. On build, the contents of the **public** directory will be copied to the **dist** directory.
<a id="babel-configuration"></a>
## Babel 配置
¥Babel configuration
与以前一样，根 [**babel.config.js**](/versions/latest/config/babel/) 文件用于 Web 和原生。你可以使用 API 调用程序中的 `platform` 属性更改预设：
¥Like before, the root [**babel.config.js**](/versions/latest/config/babel/) file is used for both web and native. You can change the preset by using the `platform` property in the API caller:
```js babel.config.js
module.exports = api => {
  // Get the platform from the API caller...
  const platform = api.caller(caller => caller && caller.platform);
  return {
    presets: ['babel-preset-expo'],
    plugins: [
      // Add a web-only plugin...
      platform === 'web' && 'custom-web-only-plugin',
    ].filter(Boolean),
  };
};
```
<a id="dev-server"></a>
## 开发服务器
¥Dev server
在 Expo Router 中，所有平台都由同一端口上的同一开发服务器托管。这方便模拟应用的生产行为。所有日志和热模块重新加载也通过同一端口。
¥In Expo Router, all platforms are hosted from the same dev server on the same port. This is convenient for emulating the production behavior of the app. All logs and hot module reloading go through the same port as well.
由于原生的限制，目前不支持使用虚假 HTTPS 进行托管。此功能现在不如 2018 年那么重要，因为你可以使用 Chrome 等网络浏览器在本地主机上测试安全功能，例如摄像头和位置。
¥Due to limitations on native, hosting with fake HTTPS is not currently supported. This feature is less important now than in 2018, as you can test secure features such as camera and location on localhost using a web browser like Chrome.
<a id="expo-constants"></a>
## Expo 常量
¥Expo constants
[`expo-constants`](/versions/latest/sdk/constants/) 库可用于访问应用内的 app.json。在幕后，这是通过使用 app.json 文件的字符串化内容设置 `process.env.APP_MANIFEST` 来完成的。
¥The [`expo-constants`](/versions/latest/sdk/constants/) library can be used to access the **app.json** in-app. Behind the scenes, this is accomplished by setting `process.env.APP_MANIFEST` with the stringified contents of the **app.json** file.
在 Expo Router 中，这是使用 Babel 和 `babel-preset-expo` 来实现的。如果修改了 app.json，请使用 `npx expo start --clear` 重新启动 Babel 缓存以查看更新。
¥In Expo Router, this is done using Babel with the `babel-preset-expo`. If you modify the **app.json**, restart the Babel cache with `npx expo start --clear` to see the updates.
<a id="base-path-and-subpath-hosting"></a>
## 基本路径和子路径托管
¥Base path and subpath hosting
>  **important** 实验功能。
>
> ¥Experimental functionality.
在 `@expo/webpack-config` 中，你可以使用 `PUBLIC_URL` 环境变量或项目的 package.json 中的 `homepage` 字段将网站打包到子路径托管：
¥In `@expo/webpack-config`, you could bundle your website to be hosted from a subpath by using the `PUBLIC_URL` environment variable or the `homepage` field in the project's **package.json**:
```json package.json
{
  "homepage": "/evanbacon/my-website"
}
```
在 Expo Router 中，你可以使用项目 app.json 中的实验性 `baseUrl` 字段：
¥In Expo Router, you can use the experimental `baseUrl` field in the project's **app.json**:
```json app.json
{
  "expo": {
    "experiments": {
      "baseUrl": "/evanbacon/my-website"
    }
  }
}
```
与以前的系统不同，这还将更新路由以考虑基本路径。例如，如果你有一条路由 `/profile`，并将基本路径设置为 `/evanbacon/my-website`，则该路由将为 `/evanbacon/my-website/profile`。
¥Unlike the previous system, this will also update the routing to account for the base path. For example, if you have a route `/profile` and you set the base path to `/evanbacon/my-website`, then the route will be `/evanbacon/my-website/profile`.
请参阅 [带有子路径的托管](/more/expo-cli#hosting-with-sub-paths) 了解更多信息。
¥See [hosting with sub-paths](/more/expo-cli#hosting-with-sub-paths) for more information.
<a id="fast-refresh"></a>
## 快速刷新
¥Fast refresh
在 `@expo/webpack-config` 中，你可以安装 `@pmmmwh/react-refresh-webpack-plugin` 并将以下内容添加到 webpack.config.js 中：
¥In `@expo/webpack-config` you could install `@pmmmwh/react-refresh-webpack-plugin` and add the following to the **webpack.config.js**:
```js webpack.config.js
const createExpoWebpackConfigAsync = require('@expo/webpack-config');
const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
module.exports = async function (env, argv) {
  const config = await createExpoWebpackConfigAsync(env, argv);
  // Use the React refresh plugin in development mode
  if (env.mode === 'development') {
    config.plugins.push(new ReactRefreshWebpackPlugin({ disableRefreshCheck: true }));
  }
  return config;
};
```
在 Expo Router 中，默认情况下使用 Meta 的官方快速刷新实现启用快速刷新。
¥In Expo Router, **Fast Refresh is enabled by default** using the official Fast Refresh implementation by Meta.
<a id="favicons"></a>
## 网站图标
¥Favicons
与 `@expo/webpack-config` 一样，Expo Router 支持根据 app.json 中的 `web.favicon` 字段生成 favicon.ico 文件。
¥Like `@expo/webpack-config`, Expo Router supports generating the **favicon.ico** file based on the `web.favicon` field in the **app.json**.
<a id="service-workers"></a>
## 服务工作线程
¥Service workers
>  **warning** 添加 Service Worker 时要小心，因为众所周知，它们会在网络上导致意外行为。如果你不小心发布了积极缓存你网站的 Service Worker，用户将无法轻松请求更新。为了获得最佳的离线移动体验，请使用 Expo 创建原生应用。与具有 Service Worker 的网站不同，原生应用可以通过应用商店进行更新，以清除缓存的体验。这类似于重置用户的原生浏览器（如果服务工作线程足够积极，他们可能必须这样做）。请参阅 [为什么服务工作进程的表现不佳](https://github.com/facebook/create-react-app/issues/2398) 了解更多信息。
>
> ¥Be careful adding service workers as they are known to cause unexpected behavior on web. If you accidentally ship a service worker that aggressively caches your website, users cannot request updates easily. For the best offline mobile experience, create a native app with Expo. Unlike websites with service workers, native apps can be updated through the app store to clear the cached experience. This would be similar to resetting the user's native browser (which they may have to do if the service worker is aggressive enough). See [why service workers are suboptimal](https://github.com/facebook/create-react-app/issues/2398) for more information.
Expo Webpack 没有内置的 Service Worker 支持。但是，你可以通过使用 `workbox-webpack-plugin` 自行添加它并将其添加到 webpack.config.js 中。
¥Expo Webpack didn't have built-in service worker support. However, you could add it yourself by using the `workbox-webpack-plugin` and adding it to the **webpack.config.js**.
Workbox 没有 Metro 集成，但由于 Workbox 不需要打包器的核心功能之一（转换、解析、序列化），因此可以轻松地将其用作构建后步骤。请遵循 [使用 Workbox CLI](https://developer.chrome.com/docs/workbox/modules/workbox-cli/) 的指南，只要它引用 "构建脚本"，请使用 `npx expo export -p web`。
¥Workbox doesn't have a Metro integration, but because Workbox doesn't require one of the core features of a bundler (transformation, resolution, serialization), it can easily be used as a post-build step. Follow the guide for [using Workbox CLI](https://developer.chrome.com/docs/workbox/modules/workbox-cli/), and wherever it refers to a "build script" use `npx expo export -p web` instead.
例如，以下是设置 Workbox 的可能流程。使用以下命令创建一个新项目：
¥For example, here's a possible flow for setting up Workbox. Create a new project with the following command:
```sh
$ npm create expo -t tabs my-app
$ cd my-app
```
接下来，为应用创建一个根 HTML 文件并添加 Service Worker 注册脚本：
¥Next, create a root HTML file for the app and add the service worker registration script:
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import type { PropsWithChildren } from 'react';
// This file is web-only and used to configure the root HTML for every
// web page during static rendering.
// The contents of this function only run in Node.js environments and
// do not have access to the DOM or browser APIs.
export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
        {/* Bootstrap the service worker. */}
        <script dangerouslySetInnerHTML={{ __html: sw }} />
        {/*
          Disable body scrolling on web. This makes ScrollView components work closer to how they do on native.
          However, body scrolling is often nice to have for mobile web. If you want to enable it, remove this line.
        */}
        <ScrollViewStyleReset />
        {/* Add any additional <head> elements that you want globally available on web... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
const sw = `
if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
        navigator.serviceWorker.register('/sw.js').then(registration => {
            console.log('Service Worker registered with scope:', registration.scope);
        }).catch(error => {
            console.error('Service Worker registration failed:', error);
        });
    });
}
`;
```
现在，在运行向导之前构建应用：
¥Now build the app before running the wizard:
```sh
$ npx expo export -p web
```
运行以下命令开始：
¥Run the wizard command, select `dist` as the root of the app, and the defaults for everything else:
```sh
$ npx workbox-cli wizard
$ ? What is the root of your web app (that is which directory do you deploy)? dist/
$ ? Which file types would you like to precache? js
html
ttf
ico
json
$ ? Where would you like your service worker file to be saved? dist/sw.js
$ ? Where would you like to save these configuration options? workbox-config.js
$ ? Does your web app manifest include search parameter(s) in the 'start_url
other than 'utm_' or 'fbclid' (like '?source=pwa')? No
```
最后，运行 `npx workbox-cli generateSW workbox-config.js` 生成 Service Worker 配置。接下来，你可以在 package.json 中添加构建脚本，以按正确的顺序运行这两个脚本：
¥Finally, run `npx workbox-cli generateSW workbox-config.js` to generate the service worker config. Going forward, you can add a build script in **package.json** to run both scripts in the correct order:
```json package.json
{
  "scripts": {
    "build:web": "expo export -p web && npx workbox-cli generateSW workbox-config.js"
  }
}
```
<a id="pwa-manifests"></a>
## PWA 清单
¥PWA manifests
与 `@expo/webpack-config` 不同，Expo Router 不会自动尝试生成 PWA 清单配置。你可以在 public/manifest.json 中创建一个：
¥Unlike `@expo/webpack-config`, Expo Router does not automatically attempt to generate the PWA manifest configuration. You can create one in **public/manifest.json**:
```json
{
  "short_name": "Expo App",
  "name": "Expo Router Sample",
  "icons": [
    {
      "src": "favicon.ico",
      "sizes": "64x64 32x32 24x24 16x16",
      "type": "image/x-icon"
    },
    {
      "src": "logo192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "logo512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "start_url": ".",
  "display": "standalone",
  "theme_color": "#000000",
  "background_color": "#ffffff"
}
```
你可以使用 `link` 标签将其链接到 HTML 文件中：
¥You can link this in your HTML file using the `link` tag:
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import type { PropsWithChildren } from 'react';
// This file is web-only and used to configure the root HTML for every
// web page during static rendering.
// The contents of this function only run in Node.js environments and
// do not have access to the DOM or browser APIs.
export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
        {/* Link the PWA manifest file. */}
        <link rel="manifest" href="/manifest.json" />
        {/*
          Disable body scrolling on web. This makes ScrollView components work closer to how they do on native.
          However, body scrolling is often nice to have for mobile web. If you want to enable it, remove this line.
        */}
        <ScrollViewStyleReset />
        {/* Add any additional <head> elements that you want globally available on web... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
```
<a id="bundler-plugins"></a>
## 打包器插件
¥Bundler plugins
如果你使用自定义打包器插件，请参阅 [Expo Metro 配置](/versions/latest/config/metro) 以向你的打包器管道添加自定义功能。
¥If you were using custom bundler plugins, see [Expo Metro config](/versions/latest/config/metro) for adding custom functionality to your bundler pipeline.
<a id="navigation"></a>
## 导航
¥Navigation
如果你使用 React Navigation 在 `@expo/webpack-config` 中的屏幕之间导航，请参阅 [React Navigation 迁移指南](/router/migrate/from-react-navigation)。
¥If you used React Navigation for navigating between screens in `@expo/webpack-config`, see the [migration guide for React Navigation](/router/migrate/from-react-navigation).
<a id="deployment"></a>
## 部署
¥Deployment
查看 [发布网站](/guides/publishing-websites)，了解如何将 Expo Router 网站部署到不同的托管服务提供商。
¥Check out [Publishing websites](/guides/publishing-websites) on how to deploy Expo Router websites to various hosting providers.
[tree-shaking]: /guides/tree-shaking


# Expo 模块 API

## Expo 模块 API：概述

概述 Expo 提供的用于开发原生模块的 API 和实用程序。

<a id="what-is-the-expo-modules-api"></a>
## 什么是 Expo Modules API
¥What is the Expo Modules API
Expo Modules API 允许你编写 Swift 和 Kotlin，以使用原生模块和视图为你的应用添加新功能。该 API 旨在利用现代语言功能，在两个平台上尽可能保持一致，需要最少的样板，并提供与 React Native 的 Turbo Modules API 相当的性能特性。Expo 模块全部支持新架构，并自动向后兼容使用旧架构的现有 React Native 应用。
¥The Expo Modules API allows you to write Swift and Kotlin to add new capabilities to your app with native modules and views. The API is designed to take advantage of modern language features, to be as consistent as possible on both platforms, to require minimal boilerplate, and provide comparable performance characteristics to React Native's Turbo Modules API. Expo Modules all support the New Architecture and are automatically backwards compatible with existing React Native apps using the old architecture.
我们相信使用 Expo Modules API 可以尽可能轻松地构建和维护几乎所有类型的 React Native 模块，并且我们认为 Expo Modules API 是绝大多数为其应用构建原生模块的开发者的最佳选择。
¥We believe that using the Expo Modules API makes building and maintaining nearly all kinds of React Native modules about as easy as it can be, and we think that the Expo Modules API is the best choice for the vast majority of developers building native modules for their apps.
<a id="common-questions"></a>
### 常见问题
¥Common questions
Note: Do I need to know the Expo Modules API to build an Expo / React Native app?
---
Most of the time, Expo and React Native developers don't need to write any native code &mdash; libraries are already available for a wide range of use cases, from camera to video to maps to haptics and much more.
But sometimes, nothing does exactly what you need. Maybe you want to integrate an analytics service that your company mandates but that doesn't yet have a React Native library yet, so you need to build a module around their SDK. Or maybe you want to access a system feature that your app requires, but isn't commonly used, so nobody maintains a library for it.
---
Note: When should I use Turbo Modules and when should I use the Expo Modules API?
---
To summarize and paraphrase the [recommendation from the React Native team](https://github.com/react-native-community/discussions-and-proposals/blob/main/proposals/0759-react-native-frameworks.md#what-do-we-recommend-to-react-native-library-developers):
- If you intend to use C++ in your native module, use Turbo Modules since it provides easier access to lower-level mechanisms.
- If you are looking for a better developer experience and you are willing to depend on the `expo` package in your module, then use the Expo Modules API.
---
Note: Where can I find open source Expo Modules to learn from?
---
The [Expo SDK](https://github.com/expo/expo/tree/main/packages) is a great place to look if you want to learn how we have implemented our libraries. Another great resource is open source apps, such as [Bluesky](https://github.com/bluesky-social/social-app/tree/main/modules).
The following libraries are some of our favorites from the community:
- [`react-native-widget-extension`](https://github.com/bndkt/react-native-widget-extension)
- [`burnt`](https://github.com/nandorojo/burnt)
- [`expo-video-metadata`](https://github.com/hirbod/expo-video-metadata)
- [`swiftui-react-native`](https://github.com/andrew-levy/swiftui-react-native)
- [`react-native-ios-context-menu`](https://github.com/dominicstop/react-native-ios-context-menu)
- [`react-native-mlkit`](https://github.com/infinitered/react-native-mlkit)
- [`react-native-passkeys`](https://github.com/peterferguson/react-native-passkeys)
- [`expo-drag-drop-content-view`](https://github.com/AlirezaHadjar/expo-drag-drop-content-view)
---
Note: What impact does using the Expo Modules API have on my app size?
---
Adding the Expo Modules API to your app has a negligible impact on your app size, it may increase the size by a few hundred kilobytes. [Learn more in this blog post](https://blog.expo.dev/embracing-expo-modules-in-your-react-native-projects-cd8ed4cbec3).
---
Note: What impact does using the Expo Modules API have on my app's performance?
---
The Expo Modules API has similar performance characteristics to React Native's Turbo Modules API. Both APIs leverage React Native's JavaScript Interface (JSI), rather than the legacy approach of using a JSON message queue ("bridge") ([learn more about JSI](https://rn.nodejs.cn/docs/the-new-architecture/landing-page#fast-javascriptnative-interfacing)).
Neither Expo Modules nor Turbo Modules are designed to be as fast as technically possible, but rather they are fast where it matters. For example, the Expo Modules API could leverage code generation and the new native Swift / C++ interop to reduce the overhead of individual method calls. However, this imposes some developer experience challenges and overhead, and we have not yet encountered any use cases where such an optimization would provide any meaningful real-world performance improvements. In reality, the time spent executing the body of a native method is often orders of magnitude greater than the overhead of the method invocation. Both Expo Modules and Turbo Modules can easily execute hundreds of thousands of native method calls per second, which is well over what you are likely to find in any app, and the overhead of the method calls is unlikely to be the bottleneck.
If you encounter any performance bottlenecks with the Expo Modules API, [file an issue](https://github.com/expo/expo/issues/new/choose) and we'd be happy to discuss it with you.
---
Note: Does the Expo Modules API support platforms other than Android, iOS, and web?
---
The Expo Modules API has experimental support for macOS and tvOS. See [Additional platform support](/modules/additional-platform-support/) tutorial for more information.
---
Note: How can I use the Expo Modules API to make a third-party SDK available to my Expo app?
---
Learn more about this in the [Integrate an existing library](/modules/existing-library/) tutorial.
---
<a id="next-steps"></a>
## 下一步
¥Next steps


## Expo 模块 API：开始使用

了解 Expo 模块 API 入门。

有两种方法可以开始使用 Expo Modules API：你可以从头开始初始化新模块，也可以将 Expo Modules API 添加到现有模块。本指南将引导你从头开始创建新模块，[集成到现有库中](/modules/existing-library) 涵盖后者。
¥**There are two ways to get started with the Expo Modules API:** you can either initialize a new module from scratch or add the Expo Modules API to an existing module. This guide will walk you through creating a new module from scratch, and the [Integrating in an existing library](/modules/existing-library) covers the latter.
使用 Expo Modules API 创建新模块的两个推荐流程：
¥The two recommended flows to create a new module with Expo Modules API:
* [向现有 Expo 应用添加新模块](#adding-a-new-module-to-an-existing-application)，并使用它来测试和开发你的模块。
  ¥[Add a new module to an existing Expo application](#adding-a-new-module-to-an-existing-application), and use it to test and develop your module.
* [使用生成的示例项目单独创建新模块](#creating-a-new-module-with-an-example-project) 如果你想在多个项目中重复使用它或将其发布到 npm。
  ¥[Create a new module in isolation with a generated example project](#creating-a-new-module-with-an-example-project) if you want to reuse it in multiple projects or publish it to npm.
下一节将介绍这两个流程。
¥Both of these flows are covered in the next sections.
<a id="add-a-new-module-to-an-existing-application"></a>
## 向现有应用添加新模块
¥Add a new module to an existing application
Step 1: 
### Create the local Expo module
Navigate to your project directory (the one that contains the **package.json** file) and run the following command. This is the recommended way to create a local Expo module.
```sh
$ npx create-expo-module@latest --local
```
Then, if your project doesn't have native projects generated (**android** and **ios** directories), run the following command, otherwise skip this command:
```sh
$ npx expo prebuild --clean
```
You can provide a meaningful module name in the CLI prompt. For the rest of the prompts, you can also accept the default suggestions.
> **Note**: If you have a pre-existing **ios** directory in your project's root which was created using `npx expo prebuild`, you must reinstall the pods:
>
> 
> ```sh
$ npx pod-install
```
Step 2: 
### Use the local module
Import the local module in your application, for example in **App.js** or **App.tsx** or **app/index.tsx**:
```tsx App.tsx
import MyModule from './modules/my-module';
export default function App() {
  return (
    <View style={styles.container}>
      <Text>{MyModule.hello()}</Text>
    </View>
  );
}
```
Start the development sever in your terminal so that when you edit the native module and build the app in the next step, the changes will be reflected in the app:
```sh
$ npx expo start
```
Congratulations! You have created a local Expo module. You can now start working on it.
> **info** **Tip**: You can also use absolute import paths [by applying these configuration changes](https://expo.fyi/absolute-path-expo-modules.md).
Step 3: 
### Edit the module
To develop and test your module locally, let's use Android Studio and Xcode for Android and iOS.
#### Android
1. Open the **android** directory (that is generated by `npx expo prebuild` in step 1) from your project in Android Studio. It may take a while for Gradle to finish syncing the native directory project.
2. Once the project is synced, open **modules/my-module/android/src/main/java/expo/modules/mymodule/MyModule.kt** file.
3. Change `hello` function to return a different string, such as "Hello world! 🌎🤖" and save the file.
4. Build the app by clicking **Run 'app'** button from top menu bar and you will see the changes on the screen.
You have to repeat the build step anytime you make a change to the native code to the changes.
#### iOS
1. Open the **ios** directory (that is generated by `npx expo prebuild` in step 1) from your project in Xcode by running `xed ios` command.
2. Under **Pods** > **Development Pods** > **MyModule**, open **MyModule.swift** file.
3. Change `hello` function to return a different string, such as "Hello world! 🌎🍎" and save the file.
4. Build your app by clicking **Run** button from top menu bar or press <kbd>⌘ Cmd</kbd> + <kbd>R</kbd>, you will see the changes on the screen.
You have to repeat the build step anytime you make a change to the native code to the changes.
> **info** **Tip**: Use `npx pod-install` to reinstall the pods if you add new native files to the module or when you modify **expo-module.config.json**.
> **Note**: There are also other flows for working on an Expo module in parallel with your application. For example, you can use a monorepo or publish to npm, as described in the [How to use a standalone Expo module](/modules/use-standalone-expo-module-in-your-project) guide.
## Create a new module with an example project
Step 1: 
### Create the Expo module
To create a new Expo module from scratch, run the `create-expo-module` script as shown below.
The script will ask you a few questions and then generate the native Expo module along with the example app for Android and iOS that uses your new module.
```sh
`$ npx create-expo-module@latest my-module`
```
Step 2: 
### Open the module and start the development server
Navigate to the module directory and then open the Android and/or iOS example project by running the following commands:
```sh
`$ cd my-module`
`$ npm run open:android`
`$ npm run open:ios`
```
Go to **example** directory and start the development sever in your terminal so that when you edit the native module and build the app in the next step, the changes will be reflected in the app:
```sh
$ cd example
$ npx expo start
```
> **Note:** If you're using Windows, you can open the example project by opening the **android** directory in Android Studio, but you cannot open the iOS project files.
Step 3: 
### Edit the module
#### Android
1. Open **my-module/android/src/main/java/expo/modules/mymodule/MyModule.kt** file.
2. Change `hello` function to return a different string, such as "Hello world! 🌎🤖" and save the file.
3. Build the app by clicking **Run 'app'** button from top menu bar and you will see the changes on the screen.
You have to repeat the build step anytime you make a change to the native code to the changes.
#### iOS
1. Under **Pods** > **Development Pods** > **MyModule**, open **MyModule.swift** file.
2. Change `hello` function to return a different string, such as "Hello world! 🌎🍎" and save the file.
3. Build your app by clicking **Run** button from top menu bar or press <kbd>⌘ Cmd</kbd> + <kbd>R</kbd>, you will see the changes on the screen.
You have to repeat the build step anytime you make a change to the native code to the changes.
> **info** **Tip**: Use `npx pod-install` to reinstall the pods if you add new native files to the module or when you modify **expo-module.config.json**.
<a id="next-steps"></a>
## 下一步
¥Next steps
现在你已经了解了如何初始化模块并对其进行简单的更改，你可以继续学习教程或直接深入了解 API 参考。
¥Now that you have learned how to initialize a module and make simple changes to it, you can continue to a tutorial or dive right into the API reference.


# 教程

## 教程：创建原生模块

关于使用 Expo Modules API 创建保留设置的原生模块的教程。

在本教程中，你将构建一个模块来存储用户首选的应用主题：深色、浅色或系统。在 Android 上使用 [`SharedPreferences`](https://developer.android.com/reference/android/content/SharedPreferences)，在 iOS 上使用 [`UserDefaults`](https://developer.apple.com/documentation/foundation/userdefaults)。你可以使用 [`localStorage`](https://web.nodejs.cn/en-US/docs/Web/API/Window/localStorage) 实现 Web 支持，但本教程不介绍这一点。
¥In this tutorial, you build a module that stores the user's preferred app theme: dark, light, or system. On Android, use [`SharedPreferences`](https://developer.android.com/reference/android/content/SharedPreferences), and on iOS, use [`UserDefaults`](https://developer.apple.com/documentation/foundation/userdefaults). You can implement web support with [`localStorage`](https://web.nodejs.cn/en-US/docs/Web/API/Window/localStorage), but this tutorial does not cover that.
Video Tutorial: [Watch: How to create a native module with the Expo Modules API](https://www.youtube.com/watch?v=CdaQSlyGik8)
***
Step 1: 
## Initialize a new module
First, create a new module. For this tutorial, the module is named `expo-settings` or `ExpoSettings`. You can choose a different name, but adjust the instructions to match your choice.
```sh
$ npx create-expo-module expo-settings
```
> **info** Since you aren't going to actually ship this library, you can hit <kbd>return</kbd> for all the prompts to accept the default values.
Step 2: 
## Set up workspace
Clean up the default module to start with a clean slate. Delete the view module since this guide does not use it.
```sh
$ cd expo-settings
$ rm ios/ExpoSettingsView.swift
$ rm android/src/main/java/expo/modules/settings/ExpoSettingsView.kt
$ rm src/ExpoSettingsView.tsx
$ rm src/ExpoSettingsView.web.tsx src/ExpoSettingsModule.web.ts
```
Locate the following files and replace their contents with the provided minimal boilerplate:
```kotlin android/src/main/java/expo/modules/settings/ExpoSettingsModule.kt
package expo.modules.settings
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
class ExpoSettingsModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoSettings")
    Function("getTheme") {
      return@Function "system"
    }
  }
}
```
```swift ios/ExpoSettingsModule.swift
import ExpoModulesCore
public class ExpoSettingsModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoSettings")
    Function("getTheme") { () -> String in
      "system"
    }
  }
}
```
```ts src/ExpoSettings.types.ts
export type ExpoSettingsModuleEvents = {};
```
```ts src/ExpoSettingsModule.ts
import { NativeModule, requireNativeModule } from 'expo';
import { ExpoSettingsModuleEvents } from './ExpoSettings.types';
declare class ExpoSettingsModule extends NativeModule<ExpoSettingsModuleEvents> {
  getTheme: () => string;
}
// This call loads the native module object from the JSI.
export default requireNativeModule<ExpoSettingsModule>('ExpoSettings');
```
```ts src/index.ts
import ExpoSettingsModule from './ExpoSettingsModule';
export function getTheme(): string {
  return ExpoSettingsModule.getTheme();
}
```
```tsx example/App.tsx
import * as Settings from 'expo-settings';
import { Text, View } from 'react-native';
export default function App() {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>Theme: {Settings.getTheme()}</Text>
    </View>
  );
}
```
Step 3: 
## Run the example project
Start the TypeScript compiler to watch for changes.
```sh
$ npm run build
```
In a separate terminal window, run the example app.
```sh
$ cd example
$ npx expo run:android
$ npx expo run:ios
```
You should see the text "Theme: system" in the center of the screen when you launch the example app. The value `"system"` comes from synchronously calling the `getTheme()` function in the native module. You will change this value in the next step.
Step 4: 
## Get, set, and persist the theme preference value
### Android native module
To read the value, look for a `SharedPreferences` string under the key `"theme"`. If the key does not exist, default to `"system"`. Use the `reactContext` (a React Native [ContextWrapper](https://developer.android.com/reference/android/content/ContextWrapper)) to access the `SharedPreferences` instance with `getSharedPreferences()`.
To set the value, use the `edit()` method of `SharedPreferences` to get an `Editor` instance. Then, use `putString()` to set the value. Ensure the `setTheme` function accepts a value of type `String`.
```kotlin android/src/main/java/expo/modules/settings/ExpoSettingsModule.kt
package expo.modules.settings
import android.content.Context
import android.content.SharedPreferences
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
class ExpoSettingsModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoSettings")
    Function("setTheme") { theme: String ->
      getPreferences().edit().putString("theme", theme).commit()
    }
    Function("getTheme") {
      return@Function getPreferences().getString("theme", "system")
    }
  }
  private val context
  get() = requireNotNull(appContext.reactContext)
  private fun getPreferences(): SharedPreferences {
    return context.getSharedPreferences(context.packageName + ".settings", Context.MODE_PRIVATE)
  }
}
```
### iOS native module
To read the value on iOS, look for a `UserDefaults` string under the key `"theme"`. If the key does not exist, default to `"system"`.
To set the value, use the `set(_:forKey:)` method of `UserDefaults`. Ensure the `setTheme` function accepts a value of type `String`.
```swift ios/ExpoSettingsModule.swift
import ExpoModulesCore
public class ExpoSettingsModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoSettings")
    Function("setTheme") { (theme: String) -> Void in
      UserDefaults.standard.set(theme, forKey:"theme")
    }
    Function("getTheme") { () -> String in
      UserDefaults.standard.string(forKey: "theme") ?? "system"
    }
  }
}
```
### TypeScript module
Update the **ExpoSettingsModule.ts** to add a TypeScript interface for the `ExpoSettingsModule` native module to update the theme.
```ts src/ExpoSettingsModule.ts
import { NativeModule, requireNativeModule } from 'expo';
import { ExpoSettingsModuleEvents } from './ExpoSettings.types';
declare class ExpoSettingsModule extends NativeModule<ExpoSettingsModuleEvents> {
  setTheme: (theme: string) => void;
  getTheme: () => string;
}
// This call loads the native module object from the JSI.
export default requireNativeModule<ExpoSettingsModule>('ExpoSettings');
```
Now, call your native modules from TypeScript.
```ts src/index.ts
import ExpoSettingsModule from './ExpoSettingsModule';
export function getTheme(): string {
  return ExpoSettingsModule.getTheme();
}
export function setTheme(theme: string): void {
  return ExpoSettingsModule.setTheme(theme);
}
```
### Example app
You can now use the Settings API in your example app.
```tsx example/App.tsx
import * as Settings from 'expo-settings';
import { Button, Text, View } from 'react-native';
export default function App() {
  const theme = Settings.getTheme();
  // Toggle between dark and light theme
  const nextTheme = theme === 'dark' ? 'light' : 'dark';
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>Theme: {Settings.getTheme()}</Text>
      <Button title={`Set theme to ${nextTheme}`} onPress={() => Settings.setTheme(nextTheme)} />
    </View>
  );
}
```
When you rebuild and run the app, the "system" theme is still set. Pressing the button does nothing, but when you reload the app, the theme changes. This happens because the app does not fetch the new theme value or re-render. You will fix this in the next step.
Step 5: 
## Emit change events for the theme value
Ensure developers using your API can react to theme value changes by emitting a change event whenever the value updates. Use the [Events](/modules/module-api/#events) definition component to describe the events your module emits, `sendEvent` to emit the event from native code, and the [EventEmitter](/modules/module-api/#sending-events) API to subscribe to events in JavaScript. The event payload is `{ theme: string }`.
### Android native module
Events payloads are represented as [`Bundle`](https://developer.android.com/reference/android/os/Bundle.html) instances on Android, which you can create using the [`bundleOf`](<https://developer.android.com/reference/kotlin/androidx/core/os/package-summary#bundleOf(kotlin.Array)>) function.
```kotlin android/src/main/java/expo/modules/settings/ExpoSettingsModule.kt
package expo.modules.settings
import android.content.Context
import android.content.SharedPreferences
import androidx.core.os.bundleOf
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
class ExpoSettingsModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoSettings")
    Events("onChangeTheme")
    Function("setTheme") { theme: String ->
      getPreferences().edit().putString("theme", theme).commit()
      this@ExpoSettingsModule.sendEvent("onChangeTheme", bundleOf("theme" to theme))
    }
    Function("getTheme") {
      return@Function getPreferences().getString("theme", "system")
    }
  }
  private val context
  get() = requireNotNull(appContext.reactContext)
  private fun getPreferences(): SharedPreferences {
    return context.getSharedPreferences(context.packageName + ".settings", Context.MODE_PRIVATE)
  }
}
```
### iOS native module
```swift ios/ExpoSettingsModule.swift
import ExpoModulesCore
public class ExpoSettingsModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoSettings")
    Events("onChangeTheme")
    Function("setTheme") { (theme: String) -> Void in
      UserDefaults.standard.set(theme, forKey:"theme")
      sendEvent("onChangeTheme", [
        "theme": theme
      ])
    }
    Function("getTheme") { () -> String in
      UserDefaults.standard.string(forKey: "theme") ?? "system"
    }
  }
}
```
### TypeScript module
```ts src/ExpoSettings.types.ts
export type ThemeChangeEvent = {
  theme: string;
};
export type ExpoSettingsModuleEvents = {
  onChangeTheme: (params: ThemeChangeEvent) => void;
};
```
```ts src/index.ts
import { EventSubscription } from 'expo-modules-core';
import ExpoSettingsModule from './ExpoSettingsModule';
import { ThemeChangeEvent } from './ExpoSettings.types';
export function addThemeListener(listener: (event: ThemeChangeEvent) => void): EventSubscription {
  return ExpoSettingsModule.addListener('onChangeTheme', listener);
}
export function getTheme(): string {
  return ExpoSettingsModule.getTheme();
}
export function setTheme(theme: string): void {
  return ExpoSettingsModule.setTheme(theme);
}
```
### Example app
```tsx example/App.tsx
import * as Settings from 'expo-settings';
import { useEffect, useState } from 'react';
import { Button, Text, View } from 'react-native';
export default function App() {
  const [theme, setTheme] = useState<string>(Settings.getTheme());
  useEffect(() => {
    const subscription = Settings.addThemeListener(({ theme: newTheme }) => {
      setTheme(newTheme);
    });
    return () => subscription.remove();
  }, [setTheme]);
  // Toggle between dark and light theme
  const nextTheme = theme === 'dark' ? 'light' : 'dark';
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>Theme: {Settings.getTheme()}</Text>
      <Button title={`Set theme to ${nextTheme}`} onPress={() => Settings.setTheme(nextTheme)} />
    </View>
  );
}
```
Step 6: 
## Improve type safety with Enums
It's easy to make mistakes when using the `Settings.setTheme()` API in its current form, as it allows any string value. Improve the type safety of this API by using an enum to restrict the possible values to `system`, `light`, and `dark`.
### Android native module
```kotlin android/src/main/java/expo/modules/settings/ExpoSettingsModule.kt
package expo.modules.settings
import android.content.Context
import android.content.SharedPreferences
import androidx.core.os.bundleOf
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
import expo.modules.kotlin.types.Enumerable
class ExpoSettingsModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoSettings")
    Events("onChangeTheme")
    Function("setTheme") { theme: Theme ->
      getPreferences().edit().putString("theme", theme.value).commit()
      this@ExpoSettingsModule.sendEvent("onChangeTheme", bundleOf("theme" to theme.value))
    }
    Function("getTheme") {
      return@Function getPreferences().getString("theme", Theme.SYSTEM.value)
    }
  }
  private val context
  get() = requireNotNull(appContext.reactContext)
  private fun getPreferences(): SharedPreferences {
    return context.getSharedPreferences(context.packageName + ".settings", Context.MODE_PRIVATE)
  }
}
enum class Theme(val value: String) : Enumerable {
  LIGHT("light"),
  DARK("dark"),
  SYSTEM("system")
}
```
### iOS native module
```swift ios/ExpoSettingsModule.swift
import ExpoModulesCore
public class ExpoSettingsModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoSettings")
    Events("onChangeTheme")
    Function("setTheme") { (theme: Theme) -> Void in
      UserDefaults.standard.set(theme.rawValue, forKey:"theme")
      sendEvent("onChangeTheme", [
        "theme": theme.rawValue
      ])
    }
    Function("getTheme") { () -> String in
      UserDefaults.standard.string(forKey: "theme") ?? Theme.system.rawValue
    }
  }
  enum Theme: String, Enumerable {
    case light
    case dark
    case system
  }
}
```
### TypeScript module
```ts src/ExpoSettings.types.ts
export type Theme = 'light' | 'dark' | 'system';
export type ThemeChangeEvent = {
  theme: Theme;
};
export type ExpoSettingsModuleEvents = {
  onChangeTheme: (params: ThemeChangeEvent) => void;
};
```
```ts src/ExpoSettingsModule.ts
import { NativeModule, requireNativeModule } from 'expo';
import { ExpoSettingsModuleEvents, Theme } from './ExpoSettings.types';
declare class ExpoSettingsModule extends NativeModule<ExpoSettingsModuleEvents> {
  setTheme: (theme: Theme) => void;
  getTheme: () => Theme;
}
// This call loads the native module object from the JSI.
export default requireNativeModule<ExpoSettingsModule>('ExpoSettings');
```
```ts src/index.ts
import { EventSubscription } from 'expo-modules-core';
import ExpoSettingsModule from './ExpoSettingsModule';
import { Theme, ThemeChangeEvent } from './ExpoSettings.types';
export function addThemeListener(listener: (event: ThemeChangeEvent) => void): EventSubscription {
  return ExpoSettingsModule.addListener('onChangeTheme', listener);
}
export function getTheme(): Theme {
  return ExpoSettingsModule.getTheme();
}
export function setTheme(theme: Theme): void {
  return ExpoSettingsModule.setTheme(theme);
}
```
### Example app
If you change `Settings.setTheme(nextTheme)` to `Settings.setTheme("not-a-real-theme")`, TypeScript will raise an error. If you ignore the error and press the button, you will see the following runtime error:
```text
 ERROR  Error: FunctionCallException: Calling the 'setTheme' function has failed (at ExpoModulesCore/SyncFunctionComponent.swift:76)
→ Caused by: ArgumentCastException: Argument at index '0' couldn't be cast to type Enum<Theme> (at ExpoModulesCore/JavaScriptUtils.swift:41)
→ Caused by: EnumNoSuchValueException: 'not-a-real-theme' is not present in Theme enum, it must be one of: 'light', 'dark', 'system' (at ExpoModulesCore/Enumerable.swift:37)
```
The last line of the error message shows that `not-a-real-theme` is not a valid value for the `Theme` enum. The only valid values are `light`, `dark`, and `system`.
恭喜！你已经为 Android 和 iOS 创建了第一个 Expo 模块。
¥Congratulations! You have created your first Expo Module for Android and iOS.
<a id="next-steps"></a>
## 下一步
¥Next steps


## 教程：创建原生视图

关于使用 Expo Modules API 创建渲染 WebView 的原生视图的教程。

在本教程中，你将构建一个带有原生视图的示例模块，该视图可渲染 WebView。对于 Android，你将使用 [`WebView`](https://developer.android.com/reference/android/webkit/WebView) 组件，对于 iOS，你将使用 [`WKWebView`](https://developer.apple.com/documentation/webkit/wkwebview)。可以使用 [`iframe`](https://web.nodejs.cn/en-US/docs/Web/HTML/Element/iframe) 实现 Web 支持，这留给你作为练习。
¥In this tutorial, you'll build an example module with a native view that renders a WebView. For Android, you'll use the [`WebView`](https://developer.android.com/reference/android/webkit/WebView) component, and for iOS, [`WKWebView`](https://developer.apple.com/documentation/webkit/wkwebview). Web support can be implemented using an [`iframe`](https://web.nodejs.cn/en-US/docs/Web/HTML/Element/iframe) and is left as an exercise for you.
Step 1: 
## Initialize a new module
Create a new module by running the following command and name the example module `expo-web-view`:
```sh
$ npx create-expo-module expo-web-view
```
> **info** Since this is an example library and won't be published, press <kbd>return</kbd> for all prompts to accept the default values.
Step 2: 
## Set up workspace
Clean up the default module to start with a clean slate by deleting the following files:
```sh
$ cd expo-web-view
$ rm src/ExpoWebView.types.ts src/ExpoWebViewModule.ts
$ rm src/ExpoWebView.web.tsx src/ExpoWebViewModule.web.ts
```
Locate the following files and replace them with the provided minimal boilerplate:
```kotlin android/src/main/java/expo/modules/webview/ExpoWebViewModule.kt
package expo.modules.webview
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
class ExpoWebViewModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoWebView")
    View(ExpoWebView::class) {}
  }
}
```
```swift ios/ExpoWebViewModule.swift
import ExpoModulesCore
public class ExpoWebViewModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoWebView")
    View(ExpoWebView.self) {}
  }
}
```
```tsx src/ExpoWebView.tsx
import { ViewProps } from 'react-native';
import { requireNativeViewManager } from 'expo-modules-core';
import * as React from 'react';
export type Props = ViewProps;
const NativeView: React.ComponentType<Props> = requireNativeViewManager('ExpoWebView');
export default function ExpoWebView(props: Props) {
  return <NativeView {...props} />;
}
```
```tsx src/index.ts
export { default as WebView, Props as WebViewProps } from './ExpoWebView';
```
```tsx example/App.tsx
import { WebView } from 'expo-web-view';
export default function App() {
  return <WebView style={{ flex: 1, backgroundColor: 'purple' }} />;
}
```
Step 3: 
## Run the example project
To ensure everything is working, start the TypeScript compiler to watch for changes and rebuild the module's JavaScript:
```sh
$ npm run build
```
```sh
$ cd example
$ npx expo run:android
$ npx expo run:ios
```
You should now see a blank purple screen. While it's not very exciting, it's a good start. Next, turn it into a WebView.
Step 4: 
## Add the system WebView as a subview
Add the system `WebView` with a hardcoded URL as a subview of `ExpoWebView`. The `ExpoWebView` class extends `ExpoView`, which extends `RCTView` from React Native, and eventually extends `View` on Android and `UIView` on iOS.
Ensure that the `WebView` subview uses the same layout as `ExpoWebView`, whose layout is calculated by React Native's layout engine.
### Android view
On Android, use `LayoutParams` to set the WebView's layout to match the `ExpoWebView` layout. You can do this when you instantiate the WebView.
```kotlin android/src/main/java/expo/modules/webview/ExpoWebView.kt
package expo.modules.webview
import android.content.Context
import android.webkit.WebView
import android.webkit.WebViewClient
import expo.modules.kotlin.AppContext
import expo.modules.kotlin.views.ExpoView
class ExpoWebView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
  internal val webView = WebView(context).also {
    it.layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
    it.webViewClient = object : WebViewClient() {}
    addView(it)
    it.loadUrl("https://expo.nodejs.cn/modules/")
  }
}
```
### iOS view
On iOS, set `clipsToBounds` to `true` and ensure the WebView's `frame` matches the bounds of `ExpoWebView` in `layoutSubviews`. The `init` method is called when the view is created, and `layoutSubviews` is called when the layout changes.
```swift ios/ExpoWebView.swift
import ExpoModulesCore
import WebKit
class ExpoWebView: ExpoView {
  let webView = WKWebView()
  required init(appContext: AppContext? = nil) {
    super.init(appContext: appContext)
    clipsToBounds = true
    addSubview(webView)
    let url =  URL(string:"https://expo.nodejs.cn/modules/")!
    let urlRequest = URLRequest(url:url)
    webView.load(urlRequest)
  }
  override func layoutSubviews() {
    webView.frame = bounds
  }
}
```
### Example app
No changes are required. Rebuild and run the app using the following commands:
```sh
$ npx expo prebuild --clean
$ npx expo run:android
$ npx expo run:ios
```
After that, you'll see the [Expo Modules API overview page](/modules/overview) rendered. If the changes aren't reflected, try reinstalling the app.
Step 5: 
## Add a prop to set the URL
To set a prop on the view, define the prop name and setter inside `ExpoWebViewModule`. In this case, you can access the `webView` property directly for convenience. However, in real-world scenarios, keep the logic inside the `ExpoWebView` class to minimize how much `ExpoWebViewModule` knows about its internals.
Use the [Prop definition component](/modules/module-api/#prop) to define the prop. In the prop setter block, you can access both the view and the prop. Specify that the URL is of type `URL` &mdash; the Expo modules API will convert strings to the native `URL` type.
### Android module
```kotlin android/src/main/java/expo/modules/webview/ExpoWebViewModule.kt
package expo.modules.webview
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
import java.net.URL
class ExpoWebViewModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoWebView")
    View(ExpoWebView::class) {
      Prop("url") { view: ExpoWebView, url: URL? ->
        view.webView.loadUrl(url.toString())
      }
    }
  }
}
```
### iOS module
```swift ios/ExpoWebViewModule.swift
import ExpoModulesCore
public class ExpoWebViewModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoWebView")
    View(ExpoWebView.self) {
      Prop("url") { (view, url: URL) in
        if view.webView.url != url {
          let urlRequest = URLRequest(url: url)
          view.webView.load(urlRequest)
        }
      }
    }
  }
}
```
### TypeScript module
Next, add the `url` prop to the `Props` type.
```tsx src/ExpoWebView.tsx
import { ViewProps } from 'react-native';
import { requireNativeViewManager } from 'expo-modules-core';
import * as React from 'react';
export type Props = {
  url?: string;
} & ViewProps;
const NativeView: React.ComponentType<Props> = requireNativeViewManager('ExpoWebView');
export default function ExpoWebView(props: Props) {
  return <NativeView {...props} />;
}
```
### Example app
Finally, pass a `URL` to your `WebView` component in the example app.
```tsx example/App.tsx
import { WebView } from 'expo-web-view';
export default function App() {
  return <WebView style={{ flex: 1 }} url="https://expo.dev" />;
}
```
Rebuild the example app:
```sh
$ npx expo prebuild --clean
$ npx expo run:android
$ npx expo run:ios
```
After that, you'll see the [Expo homepage](https://expo.dev) in the WebView.
Step 6: 
## Add an event to notify when the page has loaded
[View callbacks](/modules/module-api/#view-callbacks) allow developers to listen for events on components. They are typically registered through props on the component, for example: `<Image onLoad={...} />`. Use the [Events definition component](/modules/module-api/#events) to define an event for your WebView. Call it `onLoad`.
### Android view and module
On Android, override the `onPageFinished` function. Then, call the `onLoad` event handler that you defined in the module.
```kotlin android/src/main/java/expo/modules/webview/ExpoWebView.kt
package expo.modules.webview
import android.content.Context
import android.webkit.WebView
import android.webkit.WebViewClient
import expo.modules.kotlin.AppContext
import expo.modules.kotlin.viewevent.EventDispatcher
import expo.modules.kotlin.views.ExpoView
class ExpoWebView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
  private val onLoad by EventDispatcher()
  internal val webView = WebView(context).also {
    it.layoutParams = LayoutParams(
      LayoutParams.MATCH_PARENT,
      LayoutParams.MATCH_PARENT
    )
    it.webViewClient = object : WebViewClient() {
      override fun onPageFinished(view: WebView, url: String) {
        onLoad(mapOf("url" to url))
      }
    }
    addView(it)
  }
}
```
Indicate in `ExpoWebViewModule` that the `View` has an `onLoad` event.
```kotlin android/src/main/java/expo/modules/webview/ExpoWebViewModule.kt
package expo.modules.webview
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
import java.net.URL
class ExpoWebViewModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoWebView")
    View(ExpoWebView::class) {
      Events("onLoad")
      Prop("url") { view: ExpoWebView, url: URL? ->
        view.webView.loadUrl(url.toString())
      }
    }
  }
}
```
### iOS view and module
On iOS, implement `webView(_:didFinish:)` and make `ExpoWebView` extend `WKNavigationDelegate`. Then, call `onLoad` from that delegate method.
```swift ios/ExpoWebView.swift
import ExpoModulesCore
import WebKit
class ExpoWebView: ExpoView, WKNavigationDelegate {
  let webView = WKWebView()
  let onLoad = EventDispatcher()
  required init(appContext: AppContext? = nil) {
    super.init(appContext: appContext)
    clipsToBounds = true
    webView.navigationDelegate = self
    addSubview(webView)
  }
  override func layoutSubviews() {
    webView.frame = bounds
  }
  func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
    if let url = webView.url {
      onLoad([
        "url": url.absoluteString
      ])
    }
  }
}
```
Indicate in `ExpoWebViewModule` that the `View` has an `onLoad` event.
```swift ios/ExpoWebViewModule.swift
import ExpoModulesCore
public class ExpoWebViewModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoWebView")
    View(ExpoWebView.self) {
      Events("onLoad")
      Prop("url") { (view, url: URL) in
        if view.webView.url != url {
          let urlRequest = URLRequest(url: url)
          view.webView.load(urlRequest)
        }
      }
    }
  }
}
```
### TypeScript module
Event payloads are included within the `nativeEvent` property of the event. To access the `url` from the `onLoad` event, read `event.nativeEvent.url`.
```tsx src/ExpoWebView.tsx
import { ViewProps } from 'react-native';
import { requireNativeViewManager } from 'expo-modules-core';
import * as React from 'react';
export type OnLoadEvent = {
  url: string;
};
export type Props = {
  url?: string;
  onLoad?: (event: { nativeEvent: OnLoadEvent }) => void;
} & ViewProps;
const NativeView: React.ComponentType<Props> = requireNativeViewManager('ExpoWebView');
export default function ExpoWebView(props: Props) {
  return <NativeView {...props} />;
}
```
### Example app
Update the example app to show an alert when the page has loaded. Copy the following code, then rebuild and run your app, and you'll see the alert!
```tsx example/App.tsx
import { WebView } from 'expo-web-view';
export default function App() {
  return (
    <WebView
      style={{ flex: 1 }}
      url="https://expo.dev"
      onLoad={event => alert(`loaded ${event.nativeEvent.url}`)}
    />
  );
}
```
Step 7: 
## Bonus: Build a web browser UI around it
Now that you have a WebView, build a web browser UI around it. Try rebuilding a browser UI, and feel free to add new native capabilities as needed (for example, support for back or reload buttons). If you need inspiration, see the example below.
Note: example/App.tsx
---
```tsx App.tsx
import { useState } from 'react';
import { ActivityIndicator, Platform, Text, TextInput, View } from 'react-native';
import { WebView } from 'expo-web-view';
export default function App() {
  const [inputUrl, setInputUrl] = useState('https://expo.nodejs.cn/modules/');
  const [url, setUrl] = useState(inputUrl);
  const [isLoading, setIsLoading] = useState(true);
  return (
    <View style={{ flex: 1, paddingTop: Platform.OS === 'ios' ? 80 : 30 }}>
      <TextInput
        value={inputUrl}
        onChangeText={setInputUrl}
        returnKeyType="go"
        autoCapitalize="none"
        onSubmitEditing={() => {
          if (inputUrl !== url) {
            setUrl(inputUrl);
            setIsLoading(true);
          }
        }}
        keyboardType="url"
        style={{
          color: '#fff',
          backgroundColor: '#000',
          borderRadius: 10,
          marginHorizontal: 10,
          paddingHorizontal: 20,
          height: 60,
        }}
      />
      <WebView
        url={url.startsWith('https://') || url.startsWith('http://') ? url : `https://${url}`}
        onLoad={() => setIsLoading(false)}
        style={{ flex: 1, marginTop: 20 }}
      />
      <LoadingView isLoading={isLoading} />
    </View>
  );
}
function LoadingView({ isLoading }: { isLoading: boolean }) {
  if (!isLoading) {
    return null;
  }
  return (
    <View
      style={{
        position: 'absolute',
        bottom: 0,
        left: 0,
        right: 0,
        height: 80,
        backgroundColor: 'rgba(0,0,0,0.5)',
        paddingBottom: 10,
        justifyContent: 'center',
        alignItems: 'center',
        flexDirection: 'row',
      }}>
      <ActivityIndicator animating={isLoading} color="#fff" style={{ marginRight: 10 }} />
      <Text style={{ color: '#fff' }}>Loading...</Text>
    </View>
  );
}
```
---
恭喜！你已经创建了第一个 Expo 模块，其中包含适用于 Android 和 iOS 的原生视图。
¥Congratulations! You've created your first Expo module with a native view for Android and iOS.
<a id="next-steps"></a>
## 下一步
¥Next steps


## 教程：使用配置插件创建模块

有关使用 Expo 模块 API 创建带有配置插件的原生模块的教程。

配置插件可让你自定义使用 `npx expo prebuild` 生成的原生 Android 和 iOS 项目。你可以使用它们将属性添加到原生配置文件、将资源复制到原生项目或应用高级配置，例如添加 [应用扩展目标](/build-reference/app-extensions/)。
¥Config plugins let you customize native Android and iOS projects generated with `npx expo prebuild`. You can use them to add properties to native config files, copy assets to native projects, or apply advanced configurations, such as adding an [app extension target](/build-reference/app-extensions/).
作为应用开发者，配置插件可帮助你应用默认 [应用配置](/workflow/configuration) 中未公开的自定义项。作为库作者，它们使你能够为使用库的开发者自动配置原生项目。
¥As an app developer, config plugins help you apply customizations not exposed in the default [app config](/workflow/configuration). As a library author, they enable you to configure native projects automatically for developers using your library.
本教程介绍如何从头开始创建新的配置插件，并从 Expo 模块读取你的插件注入 AndroidManifest.xml 和 Info.plist 的自定义值。
¥This tutorial explains how to create a new config plugin from scratch and read custom values that your plugin injects into **AndroidManifest.xml** and **Info.plist** from an Expo module.
Step 1: 
## Initialize a module
Start by initializing a new Expo module project with `create-expo-module`. This sets up scaffolding for Android, iOS, and TypeScript and includes an example project to test the module within an app. Run the following command to get started:
```sh
$ npx create-expo-module expo-native-configuration
```
This guide uses the name `expo-native-configuration`/`ExpoNativeConfiguration` for the project. However, you can choose any name you prefer.
Step 2: 
## Set up workspace
In this example, you don't need the view module included by `create-expo-module`. Clean up the default module with the following command:
```sh
$ cd expo-native-configuration
$ rm android/src/main/java/expo/modules/nativeconfiguration/ExpoNativeConfigurationView.kt
$ rm ios/ExpoNativeConfigurationView.swift
$ rm src/ExpoNativeConfigurationView.tsx src/ExpoNativeConfiguration.types.ts
$ rm src/ExpoNativeConfigurationView.web.tsx src/ExpoNativeConfigurationModule.web.ts
```
Locate the following files and replace them with the provided minimal boilerplate:
- **android/src/main/java/expo/modules/nativeconfiguration/ExpoNativeConfigurationModule.kt**
- **ios/ExpoNativeConfigurationModule.swift**
- **src/ExpoNativeConfigurationModule.ts**
- **src/index.ts**
- **example/App.tsx**
```kotlin android/src/main/java/expo/modules/nativeconfiguration/ExpoNativeConfigurationModule.kt
package expo.modules.nativeconfiguration
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
class ExpoNativeConfigurationModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoNativeConfiguration")
    Function("getApiKey") {
      return@Function "api-key"
    }
  }
}
```
```swift ios/ExpoNativeConfigurationModule.swift
import ExpoModulesCore
public class ExpoNativeConfigurationModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoNativeConfiguration")
    Function("getApiKey") { () -> String in
      "api-key"
    }
  }
}
```
```ts src/ExpoNativeConfigurationModule.ts
import { NativeModule, requireNativeModule } from 'expo';
declare class ExpoNativeConfigurationModule extends NativeModule {
  getApiKey(): string;
}
// This call loads the native module object from the JSI.
export default requireNativeModule<ExpoNativeConfigurationModule>('ExpoNativeConfiguration');
```
```ts src/index.ts
import ExpoNativeConfigurationModule from './ExpoNativeConfigurationModule';
export function getApiKey(): string {
  return ExpoNativeConfigurationModule.getApiKey();
}
```
```tsx example/App.tsx
import * as ExpoNativeConfiguration from 'expo-native-configuration';
import { Text, View } from 'react-native';
export default function App() {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>API key: {ExpoNativeConfiguration.getApiKey()}</Text>
    </View>
  );
}
```
Step 3: 
## Run the example project
In the root of your project, run the TypeScript compiler to watch for changes and rebuild the module's JavaScript:
```sh
$ npm run build
```
In another terminal window, compile and run the example app:
```sh
$ cd example
$ npx expo run:ios
$ npx expo run:android
```
You should see a screen with the text "API key: api-key".
Step 4: 
## Create a new config plugin
Plugins are synchronous functions that accept an `ExpoConfig` and return a modified `ExpoConfig`. By convention, these functions are prefixed with the word `with`. Name your plugin `withMyApiKey` or use a different name, as long as it follows this convention.
Here is an example of a basic config plugin function:
```js
const withMyApiKey = config => {
  return config;
};
```
You can also use `mods`, which are async functions that modify files in native projects, such as source code or configuration files (plist, xml). The `mods` object is different from the rest of the app config because it doesn't serialize after the initial reading. This allows you to perform actions _during_ code generation.
When writing config plugins, follow these considerations:
- Plugins must be synchronous, and their return value must be serializable, except for any `mods` that are added.
- `plugins` are invoked whenever the `getConfig` method from `expo/config` reads the configuration. In contrast, `mods` are invoked only during the "syncing" phase of `npx expo prebuild`.
> Although optional, use [`expo-module-scripts`](https://www.npmjs.com/package/expo-module-scripts) to simplify plugin development. It provides a recommended default configuration for TypeScript and Jest. For more information, see the [config plugins guide](https://github.com/expo/expo/tree/main/packages/expo-module-scripts#-config-plugin).
Start creating your plugin with this minimal boilerplate. Create a **plugin** directory for writing the plugin in TypeScript and add an **app.plugin.js** file in the project root, which will be the plugin's entry point.
### Create a plugin/tsconfig.json file
```json plugin/tsconfig.json
{
  "extends": "expo-module-scripts/tsconfig.plugin",
  "compilerOptions": {
    "outDir": "build",
    "rootDir": "src"
  },
  "include": ["./src"],
  "exclude": ["**/__mocks__/*", "**/__tests__/*"]
}
```
### Create a plugin/src/index.ts file for your plugin
```ts plugin/src/index.ts
import { ConfigPlugin } from 'expo/config-plugins';
const withMyApiKey: ConfigPlugin = config => {
  console.log('my custom plugin');
  return config;
};
export default withMyApiKey;
```
### Create an app.plugin.js file in the root directory
```js app.plugin.js
// This file configures the entry file for your plugin.
module.exports = require('./plugin/build');
```
At the root of your project, run `npm run build plugin` to start the TypeScript compiler in watch mode. Next, configure your example project to use your plugin by adding the following line to the **example/app.json** file:
```json example/app.json
{
  "expo": {
    ...
    "plugins": ["../app.plugin.js"]
  }
}
```
When you run the `npx expo prebuild` command inside your **example** directory, the terminal logs "my custom plugin" through a console statement.
```sh
$ cd example
$ npx expo prebuild --clean
```
To inject your custom API keys into **AndroidManifest.xml** and **Info.plist**, use helper [`mods` provided by `expo/config-plugins`](/config-plugins/plugins-and-mods/#what-are-mods). These make it easy to modify native files. For this example, use `withAndroidManifest` and `withInfoPlist`.
As the name suggests, `withAndroidManifest` allows you to read and modify the **AndroidManifest.xml** file. Use `AndroidConfig` helpers to add a metadata item to the main application, as shown below:
```ts
const withMyApiKey: ConfigPlugin<{ apiKey: string }> = (config, { apiKey }) => {
  config = withAndroidManifest(config, config => {
    const mainApplication = AndroidConfig.Manifest.getMainApplicationOrThrow(config.modResults);
    AndroidConfig.Manifest.addMetaDataItemToMainApplication(
      mainApplication,
      'MY_CUSTOM_API_KEY',
      apiKey
    );
    return config;
  });
  return config;
};
```
Similarly, you can use `withInfoPlist` to modify the **Info.plist** values. Using the `modResults` property, you can add custom values as shown in the code snippet below:
```ts
const withMyApiKey: ConfigPlugin<{ apiKey: string }> = (config, { apiKey }) => {
  config = withInfoPlist(config, config => {
    config.modResults['MY_CUSTOM_API_KEY'] = apiKey;
    return config;
  });
  return config;
};
```
You can create a custom plugin by merging everything into a single function:
```ts plugin/src/index.ts
import {
  withInfoPlist,
  withAndroidManifest,
  AndroidConfig,
  ConfigPlugin,
} from 'expo/config-plugins';
const withMyApiKey: ConfigPlugin<{ apiKey: string }> = (config, { apiKey }) => {
  config = withInfoPlist(config, config => {
    config.modResults['MY_CUSTOM_API_KEY'] = apiKey;
    return config;
  });
  config = withAndroidManifest(config, config => {
    const mainApplication = AndroidConfig.Manifest.getMainApplicationOrThrow(config.modResults);
    AndroidConfig.Manifest.addMetaDataItemToMainApplication(
      mainApplication,
      'MY_CUSTOM_API_KEY',
      apiKey
    );
    return config;
  });
  return config;
};
export default withMyApiKey;
```
With the plugin ready to use, update the example app to pass your API key to the plugin as a configuration option. Modify the `plugins` field in **example/app.json** as shown below:
```json example/app.json
{
  "expo": {
    ...
    "plugins": [["../app.plugin.js", { "apiKey": "custom_secret_api" }]]
  }
}
```
After making this change, test that the plugin works correctly by running `npx expo prebuild --clean` inside the **example** directory. This command executes your plugin and updates native files, injecting `"MY_CUSTOM_API_KEY"` into **AndroidManifest.xml** and **Info.plist**. You can verify this by checking the contents of **example/android/app/src/main/AndroidManifest.xml**.
Step 5: 
## Read native values from the module
Now, make your native module read the fields added to **AndroidManifest.xml** and **Info.plist** by using platform-specific methods to access their contents.
On Android, access metadata information from the **AndroidManifest.xml** file using the `packageManager` class. To read the `"MY_CUSTOM_API_KEY"` value, update the **android/src/main/java/expo/modules/nativeconfiguration/ExpoNativeConfigurationModule.kt** file:
```kotlin android/src/main/java/expo/modules/nativeconfiguration/ExpoNativeConfigurationModule.kt
package expo.modules.nativeconfiguration
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
import android.content.pm.PackageManager
class ExpoNativeConfigurationModule() : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoNativeConfiguration")
    Function("getApiKey") {
      val applicationInfo = appContext?.reactContext?.packageManager?.getApplicationInfo(appContext?.reactContext?.packageName.toString(), PackageManager.GET_META_DATA)
      return@Function applicationInfo?.metaData?.getString("MY_CUSTOM_API_KEY")
    }
  }
}
```
On iOS, you can read the content of an **Info.plist** property using the `Bundle.main.object(forInfoDictionaryKey: "")` method. To access the `"MY_CUSTOM_API_KEY"` value added earlier, update the **ios/ExpoNativeConfigurationModule.swift** file as shown:
```swift ios/ExpoNativeConfigurationModule.swift
import ExpoModulesCore
public class ExpoNativeConfigurationModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoNativeConfiguration")
    Function("getApiKey") {
     return Bundle.main.object(forInfoDictionaryKey: "MY_CUSTOM_API_KEY") as? String
    }
  }
}
```
Step 6: 
## Run your module
With your native modules reading the fields added to the native files, you can now run the example app and access your custom API key using the `ExamplePlugin.getApiKey()` function.
```sh
$ cd example
$ npx expo prebuild
$ npx expo run:android
$ npx expo run:ios
```
<a id="next-steps"></a>
## 下一步
¥Next steps
恭喜，你已创建与 Android 和 iOS 的 Expo 模块交互的配置插件！
¥Congratulations, you have created a config plugin that interacts with an Expo module for Android and iOS!
如果你想挑战自己并使插件更加通用，那么这个练习适合你。修改插件以允许传入任意一组配置键和值，并添加从模块读取任意键的功能。
¥If you want to challenge yourself and make the plugin more versatile, this exercise is open for you. Modify the plugin to allow any arbitrary set of config keys and values to be passed in, and add functionality to read arbitrary keys from the module.


## 如何使用独立的 Expo 模块

了解如何通过使用 monorepo 或将包发布到 npm，在项目中使用通过 create-expo-module 创建的独立模块。

[Expo 模块 API：开始使用](/modules/get-started/) 指南中介绍了在现有项目中创建 Expo 模块的推荐方法。本教程介绍了在现有项目中使用 `create-expo-module` 创建的模块的另外两种方法：
¥**The recommended way to create an Expo module** in an existing project is described in the [Expo Modules API: Get Started](/modules/get-started/) guide. This tutorial explains two additional methods for using a module created with `create-expo-module` in an existing project:
* [配置单一存储库](#use-a-monorepo)
  ¥[Configure a monorepo](#use-a-monorepo)
* [将模块发布到 npm](#publish-the-module-to-npm)
  ¥[Publish the module to npm](#publish-the-module-to-npm)
如果你仍然希望将模块与应用分开或与其他开发者共享，这些方法非常有用。
¥These methods are useful if you still want to keep the module separate from the application or share it with other developers.
<a id="use-a-monorepo"></a>
## 使用大仓
¥Use a monorepo
你的项目应使用以下结构：
¥Your project should use the following structure:
* 应用：用于存储多个项目（包括 React Native 应用）的目录。
  ¥**apps**: A directory to store multiple projects, including React Native apps.
* 软件包：用于保存应用使用的不同软件包的目录。
  ¥**packages**: A directory to keep different packages used by your apps.
* package.json：这是包含 Yarn 工作区配置的根包文件。
  ¥**package.json**: This is the root package file that contains the Yarn workspaces configuration.
>  **info** 要了解如何将你的项目配置为 monorepo，请查看 [使用单一存储库](/guides/monorepos/) 指南。
>
> ¥To learn how to configure your project as a monorepo, check out the [Working with monorepos](/guides/monorepos/) guide.
Step 1: 
### Initialize a new module
Once you have set up the basic monorepo structure, create a new module using `create-expo-module` with the flag `--no-example` to skip creating the example app:
```sh
$ npx create-expo-module packages/expo-settings --no-example
```
Step 2: 
### Set up workspace
Configure `autolinking` so your apps can use the new module. Add the following block to the **package.json** file in each app inside the **apps** directory:
```json package.json
"expo": {
  "autolinking": {
    "nativeModulesDir": "../../packages"
  }
}
```
Step 3: 
### Run the module
Run one of your apps to ensure everything works. Then, start the TypeScript compiler in **packages/expo-settings** to watch for changes and rebuild the module's JavaScript:
```sh
$ cd packages/expo-settings
$ npm run build
```
Open another terminal window, select an app from the **apps** directory, and run the `prebuild` command with the `--clean` option. Repeat these steps for each app in your monorepo to use the new module.
```sh
$ npx expo prebuild --clean
```
Compile and run the app with the following command:
```sh
$ npx expo run:android
$ npx expo run:ios
```
You can now use the module in your app. To test it, edit the **app/(tabs)/index.tsx** file in your app and render the text message from the `expo-settings` module:
```tsx app/(tabs)/index.tsx
import React from 'react';
import { Text, View } from 'react-native';
import * as Settings from 'expo-settings';
export default function TabOneScreen() {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>{Settings.hello()}</Text>
    </View>
  );
}
```
After this configuration, the app displays the text "Hello world! 👋".
## Publish the module to npm
You can publish the module on npm and install it as a dependency in your project by following the steps below.
Step 1: 
### Initialize a new module
Start by creating a new module with `create-expo-module`. Follow the prompts carefully, as you will publish this library, and choose a unique name for your npm package.
```sh
$ npx create-expo-module expo-settings
```
Step 2: 
### Run the example project
Run one of your apps to ensure everything works. Then, start the TypeScript compiler in the root of your project to watch for changes and rebuild the module's JavaScript:
```sh
$ npm run build
```
Open another terminal window, compile and run the example app:
```sh
$ cd example
$ npx expo run:android
$ npx expo run:ios
```
Step 3: 
### Publish the package to npm
To publish your package to npm, you need an npm account. If you don't have one, create an account on [the npm website](https://www.npmjs.com/signup). After creating an account, log in by running the following command:
```sh
$ npm login
```
Navigate to the root of your module, then run the following command to publish it:
```sh
$ npm publish
```
Your module will now be published to npm and can be installed in other projects using `npm install`.
Apart from publishing your module to npm, you can use it in your project in the following ways:
- **Create a tarball**: Use `npm pack` to create a tarball of your module, then install it in your project by running `npm install /path/to/tarball`. This method is helpful for testing your module locally before publishing it or sharing it with others who don't have access to the npm registry.
- **Run a local npm registry**: Use a tool such as [Verdaccio](https://verdaccio.org/) to host a local npm registry. You can install your module from this registry, which is useful for managing internal packages within a company or organization.
- **Publish a private package**: [Use a private registry with EAS Build](/build-reference/private-npm-packages/) to manage private modules securely.
Step 4: 
### Test the published module
To test the published module in a new project, create a new app and install the module as a dependency by running the following command:
```sh
$ npx create-expo-app my-app
$ cd my-app
$ npx expo install expo-settings
```
You can now use the module in your app! To test it, edit **app/(tabs)/index.tsx** and render the text message from **expo-settings**.
```tsx app/(tabs)/index.tsx
import React from 'react';
import * as Settings from 'expo-settings';
import { Text, View } from 'react-native';
export default function TabOneScreen() {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>{Settings.hello()}</Text>
    </View>
  );
}
```
Finally, prebuild your project and run the app by executing the following commands:
```sh
$ npx expo prebuild --clean
$ npx expo run:android
$ npx expo run:ios
```
After this configuration, you see the text "Hello world! 👋" displayed in the app.
<a id="next-steps"></a>
## 下一步
¥Next steps


## 封装第三方原生库

了解如何使用 Expo Modules API 为两个单独的原生库创建一个简单的封装器。

Expo 模块使得在 React Native 项目中轻松使用为 Android 和 iOS 构建的原生外部库成为可能。本教程重点介绍如何利用 Expo Modules API 使用可在两个原生平台上访问的两个类似库来创建径向图表。
¥Expo modules make it possible to easily use native, external libraries built for Android and iOS in React Native projects. This tutorial focuses on utilizing the Expo Modules API to create radial charts using two similar libraries accessible on both native platforms.
* [MPAndroidChart by PhilJay](https://github.com/PhilJay/MPAndroidChart)
* [图表由 Daniel Cohen Gindi 绘制](https://github.com/danielgindi/Charts)
  ¥[Charts by Daniel Cohen Gindi](https://github.com/danielgindi/Charts)
iOS 库的灵感来自 Android 库，因此它们都具有相似的 API 和功能。这使它们成为本教程的一个很好的例子。
¥The iOS library is inspired by the Android library, so they both have similar API and functionality. This makes them a good example for this tutorial.
Video Tutorial: [How to wrap native libraries](https://www.youtube.com/watch?v=M8eNfH1o0eE)
***
Step 1: 
## Create a new module
The following steps assume that the new module is created inside a new Expo project. However, you can create a new module inside an existing project by following the alternative instructions.
### Start with a new project
Create a new empty Expo module that can be published on npm and utilized in any Expo app by running the following command:
```sh
$ npx create-expo-module expo-radial-chart
```
> **info** **Tip**: If you aren't going to ship this library, press <kbd>return</kbd> for all the prompts to accept the default values in the terminal window.
Now, open the newly created `expo-radial-chart` directory to start editing the native code.
### Start with an existing project
Alternatively, you can use the new module as a view inside the existing project. Run the following command in your project's directory:
```sh
$ npx create-expo-module --local expo-radial-chart
```
Now, open the newly created `modules/expo-radial-chart` directory to start editing the native code.
Step 2: 
## Run the example project
To verify that everything is functioning correctly, let's run the example project. In a terminal window, start the TypeScript compiler to watch for changes and rebuild the module JavaScript:
```sh
$ npm run build
```
In another terminal window, compile and run the example app:
```sh
$ cd example
$ npx expo run:android
$ npx expo run:ios
```
Step 3: 
## Add native dependencies
Add the native dependencies to the module by editing the **android/build.gradle** and **ios/ExpoRadialChart.podspec** files:
```diff android/build.gradle
dependencies {
  implementation project(':expo-modules-core')
  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${getKotlinVersion()}"
+ implementation 'com.github.PhilJay:MPAndroidChart:v3.1.0'
}
```
```diff ios/ExpoRadialChart.podspec
  s.static_framework = true
  s.dependency 'ExpoModulesCore'
+ s.dependency 'DGCharts', '~> 5.1.0'
  # Swift/Objective-C compatibility
```
Note: Are you trying to use a  dependency?
---
For SDK 52 and above: 
    Inside the **android** directory, create another directory called **libs** and place the **.aar** file inside it. Then, add the file as a Gradle project from autolinking:
```diff expo-module.config.json
    "android": {
+     "gradleAarProjects": [
+       {
+         "name": "test-aar",
+         "aarFilePath": "android/libs/test.aar"
+       }
+     ],
    "modules": [
```
    Finally, add the dependency to the `dependencies` list in the **android/build.gradle** file, using the dependency's specified name with `${project.name}$` prefix:
```diff android/build.gradle
dependencies {
  implementation project(':expo-modules-core')
  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${getKotlinVersion()}"
+ implementation project(":${project.name}\$test-aar")
}
```
For SDK 51 and below: 
    Inside the **android** directory, create another directory called **libs** and place the **.aar** file inside it. Then, add the directory as a repository:
```diff android/build.gradle
  repositories {
    mavenCentral()
+   flatDir {
+       dirs 'libs'
+   }
  }
```
Finally, add the dependency to the `dependencies` list. Instead of the filename, use the package path, which includes the `@aar` at the end:
```diff android/build.gradle
dependencies {
  implementation project(':expo-modules-core')
  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${getKotlinVersion()}"
+ implementation 'com.github.PhilJay:MPAndroidChart:v3.1.0@aar'
}
```
---
Note: Are you trying to use an  or  dependency?
---
On iOS, you can also use dependencies bundled as a framework by using the `vendored_frameworks` config option.
```diff ios/ExpoRadialChart.podspec
    s.static_framework = true
    s.dependency 'ExpoModulesCore'
+   s.vendored_frameworks = 'Frameworks/MyFramework.framework'
    # Swift/Objective-C compatibility
```
> **info** **Note**: The file pattern used to specify the path to the framework is relative to the podspec file,
> and doesn't support traversing the parent directory (`..`), meaning you need to place the framework inside the **ios** directory
> (or a subdirectory of **ios**).
Once the framework is added, make sure that the `source_files` option file pattern doesn't match any files inside the framework. One way to achieve this is to move your iOS source Swift files (that is `ExpoRadialChartView.swift` and `ExpoRadialChartModule.swift`) into a **src** directory separate from where you placed your framework(s) and update the `source_files` option to only match the **src** directory:
```diff ios/ExpoRadialChart.podspec
- s.source_files = '**/*.{h,m,mm,swift,hpp,cpp}'
+ s.source_files = 'src/**/*.{h,m,mm,swift,hpp,cpp}'
```
Your **ios** directory should end up with a file structure similar to this:
---
Step 4: 
## Define an API
To use the module in the app, define the types for the props. It accepts a list of series &mdash; each with a color and a percentage value.
```ts src/ExpoRadialChart.types.ts
import { ViewStyle } from 'react-native/types';
export type ChangeEventPayload = {
  value: string;
};
type Series = {
  color: string;
  percentage: number;
};
export type ExpoRadialChartViewProps = {
  style?: ViewStyle;
  data: Series[];
};
```
Since the module isn't implemented for web in this example, let's replace the **src/ExpoRadialChartView.web.tsx** file:
```tsx src/ExpoRadialChartView.web.tsx
import * as React from 'react';
export default function ExpoRadialChartView() {
  return <div>Not implemented</div>;
}
```
Step 5: 
## Implement the module on Android
Now you can implement the native functionality by editing the placeholder files with the following changes:
1. Create a `PieChart` instance and set its `layoutParams` to match the parent view. Then, add it to the view hierarchy using the `addView` function.
2. Define a `setChartData` function that accepts a list of `Series` objects. You can iterate over the list, create a `PieEntry` for each series and store the colors in a separate list.
3. Create a `PieDataSet`, use it to create a `PieData` object, and set it as data on the `PieChart` instance.
```kotlin android/src/main/java/expo/modules/radialchart/ExpoRadialChartView.kt
package expo.modules.radialchart
import android.content.Context
import android.graphics.Color
import androidx.annotation.ColorInt
import com.github.mikephil.charting.charts.PieChart
import com.github.mikephil.charting.data.PieData
import com.github.mikephil.charting.data.PieDataSet
import com.github.mikephil.charting.data.PieEntry
import expo.modules.kotlin.AppContext
import expo.modules.kotlin.records.Field
import expo.modules.kotlin.records.Record
import expo.modules.kotlin.views.ExpoView
class Series : Record {
  @Field
  val color: String = "#ff0000"
  @Field
  val percentage: Float = 0.0f
}
class ExpoRadialChartView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
  internal val chartView = PieChart(context).also {
    it.layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
    addView(it)
  }
  fun setChartData(data: ArrayList<Series>) {
    val entries: ArrayList<PieEntry> = ArrayList()
    val colors: ArrayList<Int> = ArrayList()
    for (series in data) {
      entries.add(PieEntry(series.percentage))
      colors.add(Color.parseColor(series.color))
    }
    val dataSet = PieDataSet(entries, "DataSet");
    dataSet.colors = colors;
    val pieData = PieData(dataSet);
    chartView.data = pieData;
    chartView.invalidate();
  }
}
```
You also need to use the [`Prop`](/modules/module-api/#prop) function to define the `data` prop and call the native `setChartData` function when the prop changes:
```kotlin android/src/main/java/expo/modules/radialchart/ExpoRadialChartModule.kt
package expo.modules.radialchart
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
class ExpoRadialChartModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("ExpoRadialChart")
    View(ExpoRadialChartView::class) {
      Prop("data") { view: ExpoRadialChartView, prop: ArrayList<Series> ->
        view.setChartData(prop);
      }
    }
  }
}
```
Step 6: 
## Implement the module on iOS
Now you can implement the native functionality by editing the placeholder files with the following changes:
1. Create a new `PieChartView` instance and use the `addSubview` function to add it to the view hierarchy.
2. Set the `clipsToBounds` property and override the `layoutSubviews` function to make sure the chart view is always the same size as the parent view.
3. Create a `setChartData` function that accepts a list of series, creates a `PieChartDataSet` instance with the data, and assigns it to the `data` property of the `PieChartView` instance.
```swift ios/ExpoRadialChartView.swift
import ExpoModulesCore
import DGCharts
struct Series: Record {
  @Field
  var color: UIColor = UIColor.black
  @Field
  var percentage: Double = 0
}
class ExpoRadialChartView: ExpoView {
  let chartView = PieChartView()
  required init(appContext: AppContext? = nil) {
    super.init(appContext: appContext)
    clipsToBounds = true
    addSubview(chartView)
  }
  override func layoutSubviews() {
    chartView.frame = bounds
  }
  func setChartData(data: [Series]) {
    let set1 = PieChartDataSet(entries: data.map({ (series: Series) -> PieChartDataEntry in
      return PieChartDataEntry(value: series.percentage)
    }))
    set1.colors = data.map({ (series: Series) -> UIColor in
      return series.color
    })
    let chartData: PieChartData = [set1]
    chartView.data = chartData
  }
}
```
You also need to use the [`Prop`](/modules/module-api/#prop) function to define the `data` prop and call the native `setChartData` function when the prop changes:
```swift ios/ExpoRadialChartModule.swift
import ExpoModulesCore
public class ExpoRadialChartModule: Module {
  public func definition() -> ModuleDefinition {
    Name("ExpoRadialChart")
    View(ExpoRadialChartView.self) {
      Prop("data") { (view: ExpoRadialChartView, prop: [Series]) in
        view.setChartData(data: prop)
      }
    }
  }
}
```
Step 7: 
## Write an example app to use the module
You can update the app inside the **example** directory to test the module. Use the `ExpoRadialChartView` component to render a pie chart with three slices:
```tsx example/App.tsx
import { ExpoRadialChartView } from 'expo-radial-chart';
import { StyleSheet } from 'react-native';
export default function App() {
  return (
    <ExpoRadialChartView
      style={styles.container}
      data={[
        {
          color: '#ff0000',
          percentage: 0.5,
        },
        {
          color: '#00ff00',
          percentage: 0.2,
        },
        {
          color: '#0000ff',
          percentage: 0.3,
        },
      ]}
    />
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});
```
> **info** **Tip**: If you created the module inside an existing app, make sure to import it directly from your **modules** directory by using a relative import: `import { ExpoRadialChartView } from '../modules/expo-radial-chart';`
Step 8: 
## Rebuild and launch your application
To make sure your app builds successfully on both platforms, rerun the build commands from step 2. After the app is successfully built on any of the platform you'll see a pie chart with three slices:
恭喜！你已经使用 Expo Modules API 为两个单独的第三方原生库创建了第一个简单封装器。
¥Congratulations! You have created your first simple wrapper around two separate third-party native libraries using Expo Modules API.
<a id="next-step"></a>
## 下一步
¥Next step


## 集成到现有库中

了解如何将 Expo Modules API 集成到现有的 React Native 库中。

在某些情况下，你可能希望将 Expo Modules API 集成到现有的 React Native 库中。例如，逐步重写库或利用 [Android 生命周期监听器](/modules/android-lifecycle-listeners/) 和 [iOS AppDelegate 订阅者](/modules/appdelegate-subscribers/) 自动设置库可能会很有用。
¥There are cases where you may want to integrate the Expo Modules API into an existing React Native library. For example, it might be useful to incrementally rewrite your library or to take advantage of [Android lifecycle listeners](/modules/android-lifecycle-listeners/) and [iOS AppDelegate subscribers](/modules/appdelegate-subscribers/) to automatically set up the library.
本指南将帮助你设置现有的 React Native 库以访问 Expo Modules API。
¥This guide will help you set up your existing React Native library to access Expo Modules API.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
在项目根目录下创建 [**expo-module.config.json**](/modules/module-config/) 文件，并在其中添加一个空对象 `{}`。你稍后将填写它以启用特定功能。
¥Create the [**expo-module.config.json**](/modules/module-config/) file at the root of your project and add an empty object `{}` inside it. You will fill it in later to enable specific features.
创建此文件对于 [Expo 自动链接](/modules/autolinking/) 将你的库识别为 Expo 模块并自动链接你的原生代码是必要的。
¥Creating this file is necessary for [Expo Autolinking](/modules/autolinking/) to recognize your library as an Expo module and automatically link your native code.
Step 1: 
## Add the `expo-modules-core` native dependency
Add `expo-modules-core` as a dependency in your **build.gradle** and **podspec** files:
```groovy
// ...
dependencies {
  // ...
  implementation project(':expo-modules-core')
}
```
```ruby
# ...
Pod::Spec.new do |s|
  # ...
  s.dependency 'ExpoModulesCore'
end
```
Step 2: 
## Add Expo packages to dependencies
Add `expo` package as a peer dependency in your **package.json** &mdash; we recommend using `*` as a version range so as not to cause any duplicated packages in user's **node_modules** directory.
Your library also needs to depend on `expo-modules-core` but only as a dev dependency &mdash; it's already provided in the projects depending on your library by the `expo` package with the version of core that is compatible with the specific SDK used in the project.
```json package.json
{
  "devDependencies": {
    "expo-modules-core": "^X.Y.Z"
  },
  "peerDependencies": {
    "expo": "*"
  },
  "peerDependenciesMeta": {
    "expo": {
      "optional": true
    }
  }
}
```
Step 3: 
## Create a native module
Create Kotlin and Swift files from the templates below:
```kotlin
package my.module.package
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
class MyModule : Module() {
  override fun definition() = ModuleDefinition {
    // Definition components go here
  }
}
```
```swift
import ExpoModulesCore
public class MyModule: Module {
  public func definition() -> ModuleDefinition {
    // Definition components go here
  }
}
```
Then, add your classes to Android and/or iOS `modules` in the [**expo-module.config.json**](/modules/module-config/) file. Expo Autolinking will automatically link these classes as native modules in the user's project.
```json expo-module.config.json
{
  "ios": {
    "modules": ["MyModule"]
  },
  "android": {
    "modules": ["my.module.package.MyModule"]
  }
}
```
If you already have an example app in your workspace, ensure that the module is linked correctly.
- **On Android** the native module class will be linked automatically before building, as part of the Gradle build task.
- **On iOS** you need to run `pod install` to link the new class.
These module classes are now accessible from the JavaScript code using the `requireNativeModule` function from the `expo-modules-core` package. We recommend creating a separate file that exports the native module for simplicity.
```ts MyModule.ts
import { requireNativeModule } from 'expo-modules-core';
export default requireNativeModule('MyModule');
```
现在该类已设置并链接，你可以开始实现其功能。查看 [原生模块 API](/modules/module-api/) 参考页面和从简单到中等复杂的真实世界模块到 [examples](/modules/module-api/#examples) 的链接以了解如何使用 API。
¥Now that the class is set up and linked, you can start to implement its functionality. See the [native module API](/modules/module-api/) reference page and links to [examples](/modules/module-api/#examples) from simple to moderately complex real-world modules to understand how to use the API.


## 额外的平台支持

了解如何添加对 macOS 和 tvOS 平台的支持。

Expo Modules API 为 Android 和 iOS 提供一流的支持。然而，由于所有 Apple 平台都基于相同的基础并使用相同的编程语言，因此针对 Expo 模块中的其他 [树外平台](https://rn.nodejs.cn/docs/out-of-tree-platforms) 是可能的。
¥Expo Modules API provides first-class support for Android and iOS. However, since all Apple platforms are based on the same foundation and use the same programming language, targeting other [Out-of-Tree platforms](https://rn.nodejs.cn/docs/out-of-tree-platforms) in the Expo module is possible.
目前，仅支持 macOS 和 tvOS 平台。本指南将引导你添加对这些平台的支持。
¥Currently, only **macOS** and **tvOS** platforms are supported. This guide will walk you through adding support for these platforms.
Step 1: 
## Use the `"apple"` platform in `expo-module.config.json`
To provide seamless support for other Apple platforms, Expo SDK introduced a universal `"apple"` platform to instruct the [autolinking](/modules/autolinking/) that the module may support any of the Apple platform and whether to link the module in the specific CocoaPods target is moved off to the podspec. If you have used `"ios"` before, you can safely replace it:
```diff expo-module.config.json
{
-   "platforms": ["ios"],
-   "ios": {
-     "modules": ["MyModule"]
-   }
+   "platforms": ["apple"],
+   "apple": {
+     "modules": ["MyModule"]
+   }
}
```
Step 2: 
## Update the podspec to declare support for other platforms
The module's podspec needs to be updated with a list of the supported platforms. Otherwise, CocoaPods would fail to install the pod on targets for the other platforms. As mentioned in the first step, this part of the spec is the source of truth for autolinking when the module is configured with a universal `"apple"` platform.
```diff Module's podspec
- s.platform       = :ios, '13.4'
+ s.platforms = {
+   :ios => '13.4',
+   :tvos => '13.4',
+   :osx => '10.15'
+ }
```
Any changes in the podspec require running `pod install` to have an effect.
Step 3: 
## Set up `react-native-macos` or `react-native-tvos` in the app
If you are writing a local module and your app is already set up, you can skip this step. Otherwise, you will need to set up your app or the example app if you are writing a standalone (non-local) module.
- **For macOS**: follow the official [Install React Native for macOS](https://microsoft.github.io/react-native-windows/docs/rnm-getting-started#install-the-macos-extension) guide from `react-native-macos` documentation.
- **For tvOS**: follow the instructions in the [`react-native-tvos`](https://github.com/react-native-tvos/react-native-tvos) repository. If you are building an Expo app, you should also follow the instructions in the [Build Expo apps for TV guide](/guides/building-for-tv/).
Step 4: 
## Review the code for using APIs not supported on these platforms
Platform APIs may differ between Apple platforms. The most noticeable difference comes from relying on different UI frameworks &mdash;`UIKit` on iOS/tvOS and `AppKit` on macOS.
Both `react-native-macos` and `expo-modules-core` provide aliases and polyfills to reference`UIKit` classes on macOS target (for example, `UIView` is an alias to `NSView`, `UIApplication` is an alias to `NSApplication`), but it's usually not enough for iOS-first libraries to support other platforms out of the box. You may need to write conditionally compiled code that uses different implementations depending on the platform.
To do this, use Swift compiler directives with the `os` condition, which includes a given piece of code when our app is being built for a specific platform. In combination with the `#if` and `#else` directives, lets you set up platform-specific branches within the cross-platform code.
```swift
#if os(iOS)
  // iOS implementation
#elseif os(macOS)
  // macOS implementation
#elseif os(tvOS)
  // tvOS implementation
#endif
```
你的模块现在可以在 Out-of-Tree 平台上使用。
¥Your module is now ready to be used on Out-of-Tree platform.


# 参考

## 模块 API 参考

Expo 模块 API 的 API 参考。

原生模块 API 是一个抽象层，位于 [JSI](https://rn.nodejs.cn/architecture/glossary#javascript-interfaces-jsi) 和 React Native 所构建的其他底层原语之上。它采用现代语言（Swift 和 Kotlin）构建，并提供易于使用且方便的 API，该 API 尽可能在跨平台上保持一致。
¥The native modules API is an abstraction layer on top of [JSI](https://rn.nodejs.cn/architecture/glossary#javascript-interfaces-jsi) and other low-level primitives that React Native is built upon. It is built with modern languages (Swift and Kotlin) and provides an easy-to-use and convenient API that is consistent across platforms where possible.
<a id="definition-components"></a>
## 定义组件
¥Definition components
正如你可能在 [开始使用](/modules/get-started) 页面上的代码片段中注意到的那样，每个模块类必须实现 `definition` 函数。模块定义由描述模块功能和行为的 DSL 组件组成。
¥As you might have noticed in the snippets on the [Get Started](/modules/get-started) page, each module class must implement the `definition` function.
The module definition consists of the DSL components that describe the module's functionality and behavior.
#### Name
  设置 JavaScript 代码将用来引用该模块的模块名称。接受一个字符串作为参数。这可以从模块的类名推断出来，但为了清楚起见，建议明确设置它。
  ¥Sets the name of the module that JavaScript code will use to refer to the module. Takes a string as an argument. This can be inferred from the module's class name, but it's recommended to set it explicitly for clarity.
  ```swift Swift / Kotlin
Name("MyModuleName")
```
#### Constants
  设置模块的常量属性。可以采用字典或返回字典的闭包。
  ¥Sets constant properties on the module. Can take a dictionary or a closure that returns a dictionary.
    ```swift
// Created from the dictionary
Constants([
  "PI": Double.pi
])
// or returned by the closure
Constants {
  return [
    "PI": Double.pi
  ]
}
```
    ```kotlin
// Passed as arguments
Constants(
  "PI" to kotlin.math.PI
)
// or returned by the closure
Constants {
  return@Constants mapOf(
    "PI" to kotlin.math.PI
  )
}
```
#### Function
  定义将导出到 JavaScript 的原生同步函数。同步意味着当函数在 JavaScript 中执行时，其原生代码在同一线程上运行，并阻止脚本的进一步执行，直到原生函数返回。
  ¥Defines a native synchronous function that will be exported to JavaScript. Synchronous means that when the function is executed in JavaScript, its native code is run on the same thread and blocks further execution of the script until the native function returns.
  <a id="arguments"></a>
  #### 参数
  ¥Arguments
  * 名称：`String` — 你将从 JavaScript 调用的函数的名称。
    ¥**name**: `String` — Name of the function that you'll call from JavaScript.
  * 主体：`(args...) -> ReturnType` — 调用函数时运行的闭包。
    ¥**body**: `(args...) -> ReturnType` — The closure to run when the function is called.
  该函数最多可以接收 8 个参数。这是由于 Swift 和 Kotlin 中泛型的限制，因为该组件必须为每个数量单独实现。
  ¥The function can receive up to 8 arguments. This is due to the limitations of generics in both Swift and Kotlin because this component must be implemented separately for each arity.
  有关函数体中可以使用哪些类型的更多详细信息，请参阅 [参数类型](#argument-types) 部分。
  ¥See the [Argument types](#argument-types) section for more details on what types can be used in the function body.
    ```swift
Function("mySyncFunction") { (message: String) in
  return message
}
```
    ```kotlin
Function("mySyncFunction") { message: String ->
  return@Function message
}
```
  ```js JavaScript
import { requireNativeModule } from 'expo-modules-core';
// Assume that we have named the module "MyModule"
const MyModule = requireNativeModule('MyModule');
function getMessage() {
  return MyModule.mySyncFunction('bar');
}
```
#### AsyncFunction
  定义一个始终返回 `Promise` 的 JavaScript 函数，并且默认情况下将其原生代码分派到与 JavaScript 运行时运行时不同的线程上。
  ¥Defines a JavaScript function that always returns a `Promise` and whose native code is by default dispatched on a different thread than the JavaScript runtime runs on.
  <a id="arguments-1"></a>
  #### 参数
  ¥Arguments
  * 名称：`String` — 你将从 JavaScript 调用的函数的名称。
    ¥**name**: `String` — Name of the function that you'll call from JavaScript.
  * 主体：`(args...) -> ReturnType` — 调用函数时运行的闭包。
    ¥**body**: `(args...) -> ReturnType` — The closure to run when the function is called.
  如果最后一个参数的类型是 `Promise`，该函数将等待 Promise 被解析或拒绝，然后再将响应传递回 JavaScript。否则，该函数将立即使用返回值进行解析，如果抛出异常则将被拒绝。该函数最多可以接收 8 个参数（包括 Promise）。
  ¥If the type of the last argument is `Promise`, the function will wait for the promise to be resolved or rejected before the response is passed back to JavaScript. Otherwise, the function is immediately resolved with the returned value or rejected if it throws an exception.
  The function can receive up to 8 arguments (including the promise).
  有关函数体中可以使用哪些类型的更多详细信息，请参阅 [参数类型](#argument-types) 部分。
  ¥See the [Argument types](#argument-types) section for more details on what types can be used in the function body.
  在以下情况下，建议使用 `AsyncFunction` 而不是 `Function`：
  ¥It is recommended to use `AsyncFunction` over `Function` when it:
  * 执行 I/O 绑定任务，例如发送网络请求或与文件系统交互
    ¥does I/O bound tasks such as sending network requests or interacting with the file system
  * 需要在不同的线程上运行，例如 UI 相关任务的主 UI 线程
    ¥needs to be run on a different thread, for example, the main UI thread for UI-related tasks
  * 是一个广泛或持久的操作，会阻塞 JavaScript 线程，从而降低应用的响应能力
    ¥is an extensive or long-lasting operation that would block the JavaScript thread which in turn would reduce the responsiveness of the application
    ```swift
AsyncFunction("myAsyncFunction") { (message: String) in
  return message
}
// or
AsyncFunction("myAsyncFunction") { (message: String, promise: Promise) in
  promise.resolve(message)
}
```
    ```kotlin
AsyncFunction("myAsyncFunction") { message: String ->
  return@AsyncFunction message
}
// or
// Make sure to import `Promise` class from `expo.modules.kotlin` instead of `expo.modules.core`.
AsyncFunction("myAsyncFunction") { message: String, promise: Promise ->
  promise.resolve(message)
}
```
  ```js JavaScript
import { requireNativeModule } from 'expo-modules-core';
// Assume that we have named the module "MyModule"
const MyModule = requireNativeModule('MyModule');
async function getMessageAsync() {
  return await MyModule.myAsyncFunction('bar');
}
```
  可以通过对该组件的结果调用 `.runOnQueue` 函数来更改 `AsyncFunction` 的原生队列。
  ¥It is possible to change the native queue of `AsyncFunction` by calling the `.runOnQueue` function on the result of that component.
    ```swift
AsyncFunction("myAsyncFunction") { (message: String) in
  return message
}.runOnQueue(.main)
```
    ```kotlin
AsyncFunction("myAsyncFunction") { message: String ->
  return@AsyncFunction message
}.runOnQueue(Queues.MAIN)
```
  ***
  <a id="kotlin-coroutines"></a>
  #### Kotlin 协程
  ¥Kotlin coroutines
  <PlatformTags prefix="" platforms={['android']} />
  `AsyncFunction` 可以在 Android 上接收可悬挂的主体。但是，它必须在 `Coroutine` 块之后以中缀表示法传递。你可以在 [协程概述](https://kotlinlang.org/docs/coroutines-overview.html) 上阅读有关可挂起函数和协程的更多信息。
  ¥`AsyncFunction` can receive a suspendable body on Android. However, it has to be passed in the infix notation after the `Coroutine` block. You can read more about suspendable functions and coroutines on [coroutine overview](https://kotlinlang.org/docs/coroutines-overview.html).
  具有可挂起主体的 `AsyncFunction` 无法接收 `Promise` 作为参数。它使用挂起机制来执行异步调用。该函数将立即使用所提供的可挂起块的返回值进行解析，如果抛出异常则将被拒绝。该函数最多可以接收 8 个参数。
  ¥`AsyncFunction` with a suspendable body can't receive `Promise` as an argument. It uses a suspension mechanism to execute asynchronous calls.
  The function is immediately resolved with the returned value of the provided suspendable block or rejected if it throws an exception. The function can receive up to 8 arguments.
  默认情况下，挂起函数在模块的协程范围内调度。此外，从主体块调用的所有其他可挂起函数都在同一范围内运行。该作用域的生命周期与模块的生命周期绑定 - 当模块被释放时，所有未完成的挂起函数都将被取消。
  ¥By default, suspend functions are dispatched on the module's coroutine scope. Moreover, every other suspendable function called from the body block is run within the same scope.
  This scope's lifecycle is bound to the module's lifecycle - all unfinished suspend functions will be canceled when the module is deallocated.
  ```kotlin Kotlin
AsyncFunction("suspendFunction") Coroutine { message: String ->
  // You can execute other suspendable functions here.
  // For example, you can use `kotlinx.coroutines.delay` to delay resolving the underlying promise.
  delay(5000)
  return@Coroutine message
}
```
#### Events
  定义模块可以发送到 JavaScript 的事件名称。
  ¥Defines event names that the module can send to JavaScript.
  > 注意：该组件可以在 [`View`](#view) 块内部使用来定义回调名称。见 [`View callbacks`](#view-callbacks)
  >
  > ¥**Note:** This component can be used inside of the [`View`](#view) block to define callback names. See [`View callbacks`](#view-callbacks)
    ```swift
Events("onCameraReady", "onPictureSaved", "onBarCodeScanned")
```
    ```kotlin
Events("onCameraReady", "onPictureSaved", "onBarCodeScanned")
```
  请参阅 [发送事件](#sending-events) 了解如何将事件从原生代码发送到 JavaScript/TypeScript。
  ¥See [Sending events](#sending-events) to learn how to send events from the native code to JavaScript/TypeScript.
#### Property
  直接在表示原生模块的 JavaScript 对象上定义新属性。它与在模块对象上调用 [`Object.defineProperty`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) 相同。
  ¥Defines a new property directly on the JavaScript object that represents a native module. It is the same as calling [`Object.defineProperty`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) on the module object.
  要声明只读属性，你可以使用需要两个参数的简写语法：
  ¥To declare a read-only property, you can use a shorthanded syntax that requires two arguments:
  * 名称：`String` — 你将从 JavaScript 使用的属性的名称。
    ¥**name**: `String` — Name of the property that you'll use from JavaScript.
  * 获取器：`() -> PropertyType` — 调用属性的 getter 时运行的闭包。
    ¥**getter**: `() -> PropertyType` — The closure to run when the getter for a property was called.
    ```swift
Property("foo") {
  return "bar"
}
```
    ```kotlin
Property("foo") {
  return@Property "bar"
}
```
  对于可变属性，getter 和 setter 闭包都是需要的（使用下面的语法也可以声明仅具有 setter 的属性）：
  ¥In the case of the mutable property, both the getter and the setter closure are needed (using the syntax below is also possible to declare a property with only a setter):
  * 名称：`String` — 你将从 JavaScript 使用的属性的名称。
    ¥**name**: `String` — Name of the property that you'll use from JavaScript.
  * 获取器：`() -> PropertyType` — 调用属性的 getter 时运行的闭包。
    ¥**getter**: `() -> PropertyType` — The closure to run when the getter for a property was called.
  * 设置者：`(newValue: PropertyType) -> void` — 调用属性的 setter 时运行的闭包。
    ¥**setter**: `(newValue: PropertyType) -> void` — The closure to run when the setter for a property was called.
    ```swift
Property("foo")
  .get { return "bar" }
  .set { (newValue: String) in
    // do something with new value
  }
```
    ```kotlin
Property("foo")
  .get { return@get "bar" }
  .set { newValue: String ->
    // do something with new value
  }
```
  ```js JavaScript
import { requireNativeModule } from 'expo-modules-core';
// Assume that we have named the module "MyModule"
const MyModule = requireNativeModule('MyModule');
// Obtain the property value
MyModule.foo;
// Set a new value
MyModule.foo = 'foobar';
```
#### View
  使模块能够用作原生视图。被接受为视图定义一部分的定义组件：[`Prop`](#prop)、[`Events`](#events)、[`GroupView`](#groupview) 和 [`AsyncFunction`](#asyncfunction)。
  ¥Enables the module to be used as a native view. Definition components that are accepted as part of the view definition: [`Prop`](#prop), [`Events`](#events), [`GroupView`](#groupview) and [`AsyncFunction`](#asyncfunction).
  视图定义中的 [`AsyncFunction`](#asyncfunction) 被添加到表示原生视图的 React 组件的 React ref 中。此类异步函数会自动接收原生视图的实例作为第一个参数，并默认在 UI 线程上运行。
  ¥[`AsyncFunction`](#asyncfunction) in the view definition is added to the React ref of the React component representing the native view.
  Such async functions automatically receive an instance of the native view as the first argument and run on the UI thread by default.
  <a id="arguments-2"></a>
  #### 参数
  ¥Arguments
  * viewType — 将渲染的原生视图的类。注意：在 Android 上，提供的类必须继承自 [`ExpoView`](#expoview)，在 iOS 上，它是可选的。参见 [`Extending ExpoView`](#extending--expoview)。
    ¥**viewType** — The class of the native view that will be rendered. Note: On Android, the provided class must inherit from the [`ExpoView`](#expoview), on iOS it's optional. See [`Extending ExpoView`](#extending--expoview).
  * 定义：`() -> ViewDefinition` — 视图定义的构建器。
    ¥**definition**: `() -> ViewDefinition` — A builder of the view definition.
    ```swift
View(UITextView.self) {
  AsyncFunction("focus") { (view: UITextView) in
    view.becomeFirstResponder()
  }
}
```
    ```kotlin
View(TextView::class) {
  AsyncFunction("focus") { view: TextView ->
    view.requestFocus()
  }
}
```
  >  **信息** 计划支持渲染 SwiftUI 视图。现在，你可以使用 [`UIHostingController`](https://developer.apple.com/documentation/swiftui/uihostingcontroller) 并将其内容视图添加到你的 UIKit 视图中。
  >
  > ¥Support for rendering SwiftUI views is planned. For now, you can use [`UIHostingController`](https://developer.apple.com/documentation/swiftui/uihostingcontroller) and add its content view to your UIKit view.
#### OnCreate
  定义模块初始化后立即调用的模块生命周期监听器。如果你需要在模块初始化时设置某些内容，请使用它而不是模块的类初始值设定项。
  ¥Defines module's lifecycle listener that is called right after module initialization. If you need to set up something when the module gets initialized, use this instead of module's class initializer.
#### OnDestroy
  定义模块的生命周期监听器，当模块即将被释放时调用该监听器。使用它代替模块的类析构函数。
  ¥Defines module's lifecycle listener that is called when the module is about to be deallocated. Use it instead of module's class destructor.
#### OnStartObserving
  定义添加第一个事件监听器时调用的函数。
  ¥Defines the function that is invoked when the first event listener is added.
#### OnStopObserving
  定义删除所有事件监听器时调用的函数。
  ¥Defines the function that is invoked when all event listeners are removed.
#### OnAppContextDestroys
  定义模块的生命周期监听器，当拥有该模块的应用上下文即将被释放时调用该监听器。
  ¥Defines module's lifecycle listener that is called when the app context owning the module is about to be deallocated.
#### OnAppEntersForeground, Android only
  定义当应用即将进入前台模式时调用的监听器。
  ¥Defines the listener that is called when the app is about to enter the foreground mode.
  > 注意：此功能在 Android 上不可用 — 你可能需要使用 [`OnActivityEntersForeground`](#onactivityentersforeground)。
  >
  > ¥**Note:** This function is not available on Android — you may want to use [`OnActivityEntersForeground`](#onactivityentersforeground) instead.
#### OnAppEntersBackground, Android only
  定义当应用进入后台模式时调用的监听器。
  ¥Defines the listener that is called when the app enters the background mode.
  > 注意：此功能在 Android 上不可用 — 你可能需要使用 [`OnActivityEntersBackground`](#onactivityentersbackground)。
  >
  > ¥**Note:** This function is not available on Android — you may want to use [`OnActivityEntersBackground`](#onactivityentersbackground) instead.
#### OnAppBecomesActive, Android only
  定义当应用再次激活时（`OnAppEntersForeground` 之后）调用的监听器。
  ¥Defines the listener that is called when the app becomes active again (after `OnAppEntersForeground`).
  > 注意：此功能在 Android 上不可用 — 你可能需要使用 [`OnActivityEntersForeground`](#onactivityentersforeground)。
  >
  > ¥**Note:** This function is not available on Android — you may want to use [`OnActivityEntersForeground`](#onactivityentersforeground) instead.
#### OnActivityEntersForeground, Android only
  定义活动恢复后立即调用的活动生命周期监听器。
  ¥Defines the activity lifecycle listener that is called right after the activity is resumed.
  > 注意：此功能在 iOS 上不可用 — 你可能需要使用 [`OnAppEntersForeground`](#onappentersforeground)。
  >
  > ¥**Note:** This function is not available on iOS — you may want to use [`OnAppEntersForeground`](#onappentersforeground) instead.
#### OnActivityEntersBackground, Android only
  定义活动暂停后立即调用的活动生命周期监听器。
  ¥Defines the activity lifecycle listener that is called right after the activity is paused.
  > 注意：此功能在 iOS 上不可用 — 你可能需要使用 [`OnAppEntersBackground`](#onappentersbackground)。
  >
  > ¥**Note:** This function is not available on iOS — you may want to use [`OnAppEntersBackground`](#onappentersbackground) instead.
#### OnActivityDestroys, Android only
  定义当拥有 JavaScript 上下文的活动即将被销毁时调用的活动生命周期监听器。
  ¥Defines the activity lifecycle listener that is called when the activity owning the JavaScript context is about to be destroyed.
  > 注意：此功能在 iOS 上不可用 — 你可能需要使用 [`OnAppEntersBackground`](#onappentersbackground)。
  >
  > ¥**Note:** This function is not available on iOS — you may want to use [`OnAppEntersBackground`](#onappentersbackground) instead.
#### OnActivityResult, Android only
  定义活动生命周期监听器，当使用 `startActivityForResult` 启动的活动返回结果时，该监听器会被调用。
  ¥Defines the activity lifecycle listener that is called when the activity launched with `startActivityForResult` returns a result.
  <a id="arguments-3"></a>
  #### 参数
  ¥Arguments
  * activity — 接收结果的 Android activity。
    ¥**activity** — The Android activity that received the result.
  * payload — 包含活动结果数据的对象。
    ¥**payload** — An object containing data about the activity result.
    * 请求码：`Int` — 最初提供给 `startActivityForResult` 的请求代码，用于标识结果来源。
      ¥**requestCode**: `Int` — The request code originally supplied to `startActivityForResult`, used to identify the source of the result.
    * 结果码：`Int` — 子活动（例如 `Activity.RESULT_OK` 或 `Activity.RESULT_CANCELED`）返回的结果代码。
      ¥**resultCode**: `Int` — The result code returned by the child activity (for example, `Activity.RESULT_OK` or `Activity.RESULT_CANCELED`).
    * data — 一个可选的 Intent，用于携带从启动的活动返回的结果数据。可以是 `null`。
      ¥**data** — An optional intent that carries the result data returned from the launched activity. Can be `null`.
  ```kotlin Kotlin
AsyncFunction('someFunc') {
  activity.startActivityForResult(someIntent, SOME_REQUEST_CODE)
}
OnActivityResult { activity, payload ->
}
```
<a id="view-definition-components"></a>
## 查看定义组件
¥View definition components
视图定义由描述视图功能和行为的 DSL 组件组成。这些组件只能在 [`View`](#view) 闭包中使用。
¥The view definition consists of the DSL components that describe the view's functionality and behavior. Those components can only be used within a [`View`](#view) closure.
#### Name
  设置 JavaScript 代码将用来引用视图的视图名称。接受一个字符串作为参数。这可以从视图的类名推断出来，但建议为了清晰起见明确设置。
  ¥Sets the name of the view that JavaScript code will use to refer to the view. Takes a string as an argument. This can be inferred from the view's class name, but it's recommended to set it explicitly for clarity.
  ```swift Swift / Kotlin
Name("MyViewName")
```
#### Prop
  为给定名称的 view prop 定义一个 setter。
  ¥Defines a setter for the view prop of given name.
  <a id="arguments-4"></a>
  #### 参数
  ¥Arguments
  * 名称：`String` — 你想要定义 setter 的视图 prop 的名称。
    ¥**name**: `String` — Name of view prop that you want to define a setter.
  * 默认值：`ValueType` — 使用 `null` 调用 setter 时使用的可选默认值。
    ¥**defaultValue**: `ValueType` — Optional default value used when the setter is called with `null`.
  * 设置者：`(view: ViewType, value: ValueType) -> ()` - 视图重新渲染时调用的闭包。
    ¥**setter**: `(view: ViewType, value: ValueType) -> ()` — Closure that is invoked when the view rerenders.
  该属性只能在 [`View`](#view) 闭包内使用。
  ¥This property can only be used within a [`View`](#view) closure.
    ```swift
Prop("background") { (view: UIView, color: UIColor) in
  view.backgroundColor = color
}
```
    ```kotlin
Prop("background") { view: View, @ColorInt color: Int ->
  view.setBackgroundColor(color)
}
```
  具有默认值的 Prop 定义。
  ¥Prop definition with default value.
    ```swift
Prop("background", UIColor.black) { (view: UIView, color: UIColor) in
  view.backgroundColor = color
}
```
    ```kotlin
Prop("background", Color.BLACK) { view: View, @ColorInt color: Int ->
  view.setBackgroundColor(color)
}
```
  > 注意：尚不支持函数类型（回调）的 props。
  >
  > ¥**Note:** Props of function type (callbacks) are not supported yet.
#### OnViewDidUpdateProps
  定义视图生命周期方法，当视图完成所有 props 更新后会调用该方法。
  ¥Defines the view lifecycle method that is called when the view finished updating all props.
  ```swift
View(MyView.self) {
  OnViewDidUpdateProps { view: MyView in
  }
}
```
  ```kotlin
View(MyView::class) {
  OnViewDidUpdateProps { view: MyView ->
  }
}
```
#### (View) AsyncFunction
  与模块定义中的 [`AsyncFunction`](#asyncfunction) 类似，你可以定义附加到视图引用的函数，以便直接修改原生视图。
  ¥Similarly to the [`AsyncFunction`](#asyncfunction) inside the module definition, you can define functions attached to the view ref to allow direct modification of the native view.
  视图异步函数将始终在主队列中调度，并可以接收视图实例作为第一个参数。
  ¥View async functions will always be dispatched on the main queue and can receive the view instance as the first argument.
    ```swift
View(MyView.self) {
  AsyncFunction("myAsyncFunction") { (view: MyView, message: String) in
    view.displayMessage(message)
  }
}
```
    ```kotlin
View(MyView::class) {
  AsyncFunction("myAsyncFunction") { view: MyView, message: String ->
    view.displayMessage(message);
  }
}
```
  ```js JavaScript
const MyNativeView = requireNativeViewManager('MyView');
function MyComponent() {
  const ref = React.useRef(null);
  React.useEffect(() => {
    ref.current?.myAsyncFunction();
  }, [ref]);
  return <MyNativeView ref={ref} />;
}
```
#### GroupView, Android only
  使视图能够用作视图组。作为组视图定义的一部分接受的定义组件：[`AddChildView`](#addchildview)、[`GetChildCount`](#getchildcount)、[`GetChildViewAt`](#getchildviewat)、[`RemoveChildView`](#removechildview)、[`RemoveChildViewAt`](#removechildviewat)。
  ¥Enables the view to be used as a view group. Definition components that are accepted as part of the group view definition: [`AddChildView`](#addchildview), [`GetChildCount`](#getchildcount), [`GetChildViewAt`](#getchildviewat), [`RemoveChildView`](#removechildview), [`RemoveChildViewAt`](#removechildviewat).
  <a id="arguments-5"></a>
  #### 参数
  ¥Arguments
  * viewType — 原生视图的类。请注意，提供的类必须继承自 Android `ViewGroup`。
    ¥**viewType** — The class of the native view. Note that the provided class must inherit from the Android `ViewGroup`.
  * 定义：`() -> ViewGroupDefinition` — 视图组定义的构建器。
    ¥**definition**: `() -> ViewGroupDefinition` — A builder of the view group definition.
  该属性只能在 [`View`](#view) 闭包内使用。
  ¥This property can only be used within a [`View`](#view) closure.
  ```kotlin Kotlin
GroupView<ViewGroup> {
}
```
#### AddChildView, Android only
  定义将子视图添加到视图组的操作。
  ¥Defines action that adds a child view to the view group.
  <a id="arguments-6"></a>
  #### 参数
  ¥Arguments
  * 行动：`(parent: ParentType, child: ChildType, index: Int) -> ()` — 将子视图添加到视图组的操作。
    ¥**action**: `(parent: ParentType, child: ChildType, index: Int) -> ()` — An action that adds a child view to the view group.
  该属性只能在 [`GroupView`](#groupview) 闭包内使用。
  ¥This property can only be used within a [`GroupView`](#groupview) closure.
  ```kotlin Kotlin
AddChildView { parent, child: View, index ->
  parent.addView(child, index)
}
```
#### GetChildCount, Android only
  定义检索视图组中子视图数量的操作。
  ¥Defines action the retrieves the number of child views in the view group.
  <a id="arguments-7"></a>
  #### 参数
  ¥Arguments
  * 行动：`(parent: ParentType) -> Int` — 返回子视图数量的函数。
    ¥**action**: `(parent: ParentType) -> Int` — A function that returns number of child views.
  该属性只能在 [`GroupView`](#groupview) 闭包内使用。
  ¥This property can only be used within a [`GroupView`](#groupview) closure.
  ```kotlin Kotlin
GetChildCount { parent ->
  return@GetChildCount parent.childCount
}
```
#### GetChildViewAt, Android only
  定义从视图组中检索特定索引处的子视图的操作。
  ¥Defines action that retrieves a child view at a specific index from the view group.
  <a id="arguments-8"></a>
  #### 参数
  ¥Arguments
  * 行动：`(parent: ParentType, index: Int) -> ChildType` — 从视图组中检索特定索引处的子视图的函数。
    ¥**action**: `(parent: ParentType, index: Int) -> ChildType` — A function that retrieves a child view at a specific index from the view group.
  该属性只能在 [`GroupView`](#groupview) 闭包内使用。
  ¥This property can only be used within a [`GroupView`](#groupview) closure.
  ```kotlin Kotlin
GetChildViewAt { parent, index ->
  parent.getChildAt(index)
}
```
#### RemoveChildView, Android only
  定义从视图组中删除特定子视图的操作。
  ¥Defines action that removes a specific child view from the view group.
  <a id="arguments-9"></a>
  #### 参数
  ¥Arguments
  * 行动：`(parent: ParentType, child: ChildType) -> ()` — 从视图组中删除特定子视图的函数。
    ¥**action**: `(parent: ParentType, child: ChildType) -> ()` — A function that remove a specific child view from the view group.
  该属性只能在 [`GroupView`](#groupview) 闭包内使用。
  ¥This property can only be used within a [`GroupView`](#groupview) closure.
  ```kotlin Kotlin
RemoveChildView { parent, child: View ->
  parent.removeView(child)
}
```
#### RemoveChildViewAt, Android only
  定义从视图组中删除特定索引处的子视图的操作。
  ¥Defines action that removes a child view at a specific index from the view group.
  <a id="arguments-10"></a>
  #### 参数
  ¥Arguments
  * 行动：`(parent: ParentType, child: ChildType) -> ()` — 从视图组中删除特定索引处的子视图的函数。
    ¥**action**: `(parent: ParentType, child: ChildType) -> ()` — A function that removes a child view at a specific index from the view group.
  该属性只能在 [`GroupView`](#groupview) 闭包内使用。
  ¥This property can only be used within a [`GroupView`](#groupview) closure.
  ```kotlin Kotlin
RemoveChildViewAt { parent, index ->
  parent.removeViewAt(child)
}
```
<a id="argument-types"></a>
## 参数类型
¥Argument types
从根本上讲，只有原始数据和可序列化数据可以在运行时之间来回传递。然而，通常原生模块需要接收自定义数据结构 - 比字典/映射更复杂，其中值是未知 (`Any`) 类型，因此每个值都必须自行验证和转换。Expo Modules API 提供的协议使数据对象的处理更加方便，提供自动验证，最后确保每个对象成员的原生类型安全。
¥Fundamentally, only primitive and serializable data can be passed back and forth between the runtimes. However, usually native modules need to receive custom data structures — more sophisticated than just the dictionary/map where the values are of unknown (`Any`) type and so each value has to be validated and cast on its own. The Expo Modules API provides protocols to make it more convenient to work with data objects, to provide automatic validation, and finally, to ensure native type-safety on each object member.
#### Primitives
  所有函数和视图属性设置器都接受 Swift 和 Kotlin 中所有常见的原始类型作为参数。这包括数组、字典/映射以及这些基本类型的选项。
  ¥All functions and view prop setters accept all common primitive types in Swift and Kotlin as the arguments. This includes arrays, dictionaries/maps and optionals of these primitive types.
  | 语言  | 支持的原始类型                                                                                                           |
  | --- | ----------------------------------------------------------------------------------------------------------------- |
  | 迅速  | `Bool`、`Int`、`Int8`、`Int16`、`Int32`、`Int64`、`UInt`、`UInt8`、`UInt16`、`UInt32`、`UInt64`、`Float32`、`Double`、`String` |
  | 科特林 | `Boolean`, `Int`, `Long`, `Float`, `Double`, `String`, `Pair`                                                     |
#### Convertibles
  可转换是原生类型，可以根据从 JavaScript 接收的某些特定类型的数据进行初始化。此类类型允许用作 `Function` 主体中的参数类型。例如，当 `CGPoint` 类型用作函数参数类型时，可以从两个数字 `(x, y)` 的数组或具有数字 `x` 和 `y` 属性的 JavaScript 对象创建其实例。
  ¥*Convertibles* are native types that can be initialized from certain specific kinds of data received from JavaScript. Such types are allowed to be used as an argument type in `Function`'s body. For example, when the `CGPoint` type is used as a function argument type, its instance can be created from an array of two numbers `(x, y)` or a JavaScript object with numeric `x` and `y` properties.
  内置的 Convertibles 已记录在 [下文进一步](#built-in-convertibles) 中。你可以通过使原生 Swift 类型符合 `Convertible` 协议来定义其他 Convertible：
  ¥The built-in Convertibles are documented [further below](#built-in-convertibles). You can define additional Convertibles by making native Swift types conform to the `Convertible` protocol:
  #### Convertible, Android only>
    `Convertible` 是一种具有一个静态方法的 Swift 协议：
    ¥`Convertible` is a Swift protocol with one static method:
    <APIMethod
      name="convert"
      comment="A static method that converts a dynamically typed value from JavaScript to an instance of the Swift type conforming to `Convertible`. Implementers should throw an exception when the given value is invalid or of an unsupported type."
      returnTypeName="Self"
      parameters={[
    {
      name: 'value',
      comment: 'A value from JavaScript to convert',
      typeName: 'Any?',
    },
    {
      name: 'appContext',
      comment: 'The context object for the currently running Expo app instance',
      typeName: 'AppContext',
    },
  ]}
    />
    <a id="example"></a>
    ### 示例
    ¥Example
    ```swift Swift
import ExpoModulesCore
extension CMTime: @retroactive Convertible {
  public static func convert(from value: Any?, appContext: AppContext) throws -> CMTime {
    if let seconds = value as? Double {
      return CMTime(seconds: seconds, preferredTimescale: .max)
    }
    throw Conversions.ConvertingException<CMTime>(value)
  }
}
```
  >  **信息** 计划在 SDK 53 中提供使用 Kotlin 定义 Convertibles 的支持。
  >
  > ¥Support for defining Convertibles with Kotlin is planned to be available by SDK 53.
  ***
  <a id="built-in-convertibles"></a>
  ## 内置可转换程序
  ¥Built-in Convertibles
  `CoreGraphics` 和 `UIKit` 系统框架中的一些常见 iOS 类型已经可转换。
  ¥Some common iOS types from the `CoreGraphics` and `UIKit` system frameworks are already made convertible.
  | 原生 iOS 类型                | TypeScript                                                                                                                         |
  | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
  | `URL`                    | `string` 带有 URL。如果未提供方案，则假定它是文件 URL。                                                                                               |
  | `CGFloat`                | `number`                                                                                                                           |
  | `CGPoint`                | `{ x: number, y: number }` 或 `number[]` 以及 x 和 y 坐标                                                                                |
  | `CGSize`                 | `{ width: number, height: number }` 或 `number[]` 的宽度和高度                                                                            |
  | `CGVector`               | 具有 dx 和 dy 向量微分的 `{ dx: number, dy: number }` 或 `number[]`                                                                         |
  | `CGRect`                 | `{ x: number, y: number, width: number, height: number }` 或 `number[]` 以及 x、y、宽度和高度值                                               |
  | `CGColor``UIColor` | 颜色十六进制字符串（`#RRGGBB`、`#RRGGBBAA`、`#RGB`、`#RGBA`），按照 [C/SVG 规范](https://www.w3.org/TR/css-color-3/#svg-color) 或 `"transparent"` 命名颜色 |
  | `Data`                   | `Uint8Array` <StatusTag note="SDK 50+" />                                                                                          |
  ***
  同样，`java.io`、`java.net` 或 `android.graphics` 等软件包中的一些常见 Android 类型也可转换。
  ¥Similarly, some common Android types from packages like `java.io`, `java.net`, or `android.graphics` are also made convertible.
  > 注意：在 Android 上，应尽可能使用原始数组。
  >
  > ¥**Note:** On Android, primitive arrays should be used whenever possible.
  | 原生安卓类型                                                                                       | TypeScript                                                                                                                         |
  | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
  | `java.net.URL`                                                                               | `string` 带有 URL。请注意，必须提供方案（URL 不应包含任何未编码的 `%` 字符）                                                                                  |
  | `android.net.Uri``java.net.URI`                                                        | `string` 带有 URI。请注意，必须提供方案（URI 不应包含任何未编码的 `%` 字符）                                                                                  |
  | `java.io.File``java.nio.file.Path`（仅适用于 Android API 26）                                | `string` 带有文件路径                                                                                                                    |
  | `android.graphics.Color`                                                                     | 颜色十六进制字符串（`#RRGGBB`、`#RRGGBBAA`、`#RGB`、`#RGBA`），按照 [C/SVG 规范](https://www.w3.org/TR/css-color-3/#svg-color) 或 `"transparent"` 命名颜色 |
  | `kotlin.Pair<A, B>`                                                                          | 具有两个值的数组，其中第一个值的类型为 A，第二个值的类型为 B                                                                                                   |
  | `kotlin.ByteArray`                                                                           | `Uint8Array` <StatusTag note="SDK 50+" />                                                                                          |
  | `kotlin.BooleanArray`                                                                        | `boolean[]`                                                                                                                        |
  | `kotlin.IntArray``kotlin.FloatArray``kotlin.LongArray``kotlin.DoubleArray` | `number[]`                                                                                                                         |
  | `kotlin.time.Duration`                                                                       | `number` 表示持续时间（以秒为单位）<StatusTag note="SDK 52+" />                                                                                 |
#### Records
  Record 是一种可转换类型，相当于字典 (Swift) 或映射 (Kotlin)，但表示为结构体，其中每个字段都可以拥有其类型并提供默认值。这是一种用原生类型安全来表示 JavaScript 对象的更好方法。
  ¥*Record* is a convertible type and an equivalent of the dictionary (Swift) or map (Kotlin), but represented as a struct where each field can have its type and provide a default value.
  It is a better way to represent a JavaScript object with the native type safety.
    ```swift
struct FileReadOptions: Record {
  @Field
  var encoding: String = "utf8"
  @Field
  var position: Int = 0
  @Field
  var length: Int?
}
// Now this record can be used as an argument of the functions or the view prop setters.
Function("readFile") { (path: String, options: FileReadOptions) -> String in
  // Read the file using given `options`
}
```
    ```kotlin
class FileReadOptions : Record {
  @Field
  val encoding: String = "utf8"
  @Field
  val position: Int = 0
  @Field
  val length: Int? = null
}
// Now this record can be used as an argument of the functions or the view prop setters.
Function("readFile") { path: String, options: FileReadOptions ->
  // Read the file using given `options`
}
```
#### Enums
  使用枚举，我们可以进一步使用上面的示例（使用 `FileReadOptions` 记录）并将支持的编码限制为 `"utf8"` 和 `"base64"`。要使用枚举作为参数或记录字段，它必须表示原始值（例如 `String`、`Int`）并符合 `Enumerable`。
  ¥With enums, we can go even further with the above example (with `FileReadOptions` record) and limit supported encodings to `"utf8"` and `"base64"`. To use an enum as an argument or record field, it must represent a primitive value (for example, `String`, `Int`) and conform to `Enumerable`.
    ```swift
enum FileEncoding: String, Enumerable {
  case utf8
  case base64
}
struct FileReadOptions: Record {
  @Field
  var encoding: FileEncoding = .utf8
}
```
    ```kotlin
// Note: the constructor must have an argument called value.
enum class FileEncoding(val value: String) : Enumerable {
  utf8("utf8"),
  base64("base64")
}
class FileReadOptions : Record {
  @Field
  val encoding: FileEncoding = FileEncoding.utf8
}
```
#### Eithers
  在某些用例中，你希望为单个函数参数传递各种类型。这就是任一类型可能派上用场的地方。它们充当几种类型之一的值的容器。
  ¥There are some use cases where you want to pass various types for a single function argument. This is where Either types might come in handy.
  They act as a container for a value of one of a couple of types.
    ```swift
Function("foo") { (bar: Either<String, Int>) in
  if let bar: String = bar.get() {
    // `bar` is a String
  }
  if let bar: Int = bar.get() {
    // `bar` is an Int
  }
}
```
    ```kotlin
Function("foo") { bar: Either<String, Int> ->
  bar.get(String::class).let {
    // `it` is a String
  }
  bar.get(Int::class).let {
    // `it` is an Int
  }
}
```
  当前提供了开箱即用的三种 Either 类型的实现，允许你使用最多四种不同的子类型。
  ¥The implementation for three Either types is currently provided out of the box, allowing you to use up to four different subtypes.
  * `Either<FirstType, SecondType>` — 两种类型之一的容器。
    ¥`Either<FirstType, SecondType>` — A container for one of two types.
  * `EitherOfThree<FirstType, SecondType, ThirdType>` — 三种类型之一的容器。
    ¥`EitherOfThree<FirstType, SecondType, ThirdType>` — A container for one of three types.
  * `EitherOfFour<FirstType, SecondType, ThirdType, FourthType>` — 四种类型之一的容器。
    ¥`EitherOfFour<FirstType, SecondType, ThirdType, FourthType>` — A container for one of four types.
#### JavaScript values
  还可以使用 `JavaScriptValue` 类型，它是可以用 JavaScript 表示的任何值的持有者。当你想要改变给定参数或想要省略类型验证和转换时，此类型非常有用。请注意，使用 JavaScript 特定类型仅限于同步函数，因为 JavaScript 运行时中的所有读取和写入都必须在 JavaScript 线程上进行。从不同线程对这些值的任何访问都会导致崩溃。
  ¥It's also possible to use a `JavaScriptValue` type which is a holder for any value that can be represented in JavaScript.
  This type is useful when you want to mutate the given argument or when you want to omit type validations and conversions.
  Note that using JavaScript-specific types is restricted to synchronous functions as all reads and writes in the JavaScript runtime must happen on the JavaScript thread.
  Any access to these values from different threads will result in a crash.
  除了原始值之外，`JavaScriptObject` 类型可用于仅允许对象类型，而 `JavaScriptFunction<ReturnType>` 类型可用于回调。
  ¥In addition to the raw value, the `JavaScriptObject` type can be used to allow only object types and `JavaScriptFunction<ReturnType>` for callbacks.
    ```swift
Function("mutateMe") { (value: JavaScriptValue) in
  if value.isObject() {
    let jsObject = value.getObject()
    jsObject.setProperty("expo", value: "modules")
  }
}
// or
Function("mutateMe") { (jsObject: JavaScriptObject) in
  jsObject.setProperty("expo", value: "modules")
}
```
    ```kotlin
Function("mutateMe") { value: JavaScriptValue ->
  if (value.isObject()) {
    val jsObject = value.getObject()
    jsObject.setProperty("expo", "modules")
  }
}
// or
Function("mutateMe") { jsObject: JavaScriptObject ->
  jsObject.setProperty("expo", "modules")
}
```
<a id="native-classes"></a>
## 原生类
¥Native classes
#### Module
  原生模块的基类。
  ¥A base class for a native module.
  <a id="properties"></a>
  #### 属性
  ¥Properties
  <APIMethod name="appContext" comment="Provides access to the [`AppContext`](#appcontext)." returnTypeName="AppContext" isProperty isReturnTypeReference />
  <a id="methods"></a>
  #### 方法
  ¥Methods
  <APIMethod
    name="sendEvent"
    comment="Sends an event with a given name and a payload to JavaScript. See [`Sending events`](#sending-events)"
    returnTypeName="void"
    parameters={[
    {
      name: 'eventName',
      comment: 'The name of the JavaScript event',
      typeName: 'string',
    },
    {
      name: 'payload',
      comment: 'The event payload',
      typeName: 'Android: Map<String, Any?> | Bundle\niOS: [String: Any?]',
    },
  ]}
  />
#### AppContext
  应用上下文是单个 Expo 应用的接口。
  ¥The app context is an interface to a single Expo app.
  <a id="properties-1"></a>
  #### 属性
  ¥Properties
  <APIMethod name="constants" comment="Provides access to app's constants from legacy module registry." returnTypeName="Android: ConstantsInterface? iOS: EXConstantsInterface?" isProperty />
  <APIMethod name="permissions" comment="Provides access to the permissions manager from legacy module registry." returnTypeName="Android: Permissions? iOS: EXPermissionsInterface?" isProperty />
  <APIMethod name="imageLoader" comment="Provides access to the image loader from the legacy module registry." returnTypeName="Android: ImageLoaderInterface? iOS: EXImageLoaderInterface?" isProperty />
  <APIMethod name="barcodeScanner" comment="Provides access to the bar code scanner manager from the legacy module registry." returnTypeName="ImageLoaderInterface?" isProperty platforms={['Android']} />
  <APIMethod name="camera" comment="Provides access to the camera view manager from the legacy module registry." returnTypeName="CameraViewInterface?" isProperty platforms={['Android']} />
  <APIMethod name="font" comment="Provides access to the font manager from the legacy module registry." returnTypeName="FontManagerInterface?" isProperty platforms={['Android']} />
  <APIMethod name="sensor" comment="Provides access to the sensor manager from the legacy module registry." returnTypeName="SensorServiceInterface?" isProperty platforms={['Android']} />
  <APIMethod name="taskManager" comment="Provides access to the task manager from the legacy module registry." returnTypeName="TaskManagerInterface?" isProperty platforms={['Android']} />
  <APIMethod name="activityProvider" comment="Provides access to the activity provider from the legacy module registry." returnTypeName="ActivityProvider?" isProperty platforms={['Android']} />
  <APIMethod name="reactContext" comment="Provides access to the react application context." returnTypeName="Context?" isProperty platforms={['Android']} />
  <APIMethod name="hasActiveReactInstance" comment="Checks if there is an not-null, alive react native instance." returnTypeName="Boolean" isProperty platforms={['Android']} />
  <APIMethod name="utilities" comment="Provides access to the utilities from legacy module registry." returnTypeName="EXUtilitiesInterface?" isProperty platforms={['iOS']} />
#### ExpoView
  所有导出视图都应使用的基类。
  ¥A base class that should be used by all exported views.
  在 iOS 上，`ExpoView` 扩展了 `RCTView`，它处理某些样式（例如边框）和可访问性。
  ¥On iOS, `ExpoView` extends the `RCTView` which handles some styles (for example, borders) and accessibility.
  <a id="properties-2"></a>
  #### 属性
  ¥Properties
  <APIMethod name="appContext" comment="Provides access to the [`AppContext`](#appcontext)." returnTypeName="AppContext" isProperty isReturnTypeReference />
  <a id="extending-expoview"></a>
  #### 延长 `ExpoView`
  ¥Extending `ExpoView`
  要使用 [`View`](#view) 组件导出视图，你的自定义类必须继承自 `ExpoView`。通过这样做，你将可以访问 [`AppContext`](#appcontext) 对象。这是与其他模块和 JavaScript 运行时通信的唯一方式。另外，你不能更改构造函数参数，因为提供的视图将由 `expo-modules-core` 初始化。
  ¥To export your view using the [`View`](#view) component, your custom class must inherit from the `ExpoView`. By doing that you will get access to the [`AppContext`](#appcontext) object. It's the only way of communicating with other modules and the JavaScript runtime. Also, you can't change constructor parameters, because provided view will be initialized by `expo-modules-core`.
    ```swift
class LinearGradientView: ExpoView {}
public class LinearGradientModule: Module {
  public func definition() -> ModuleDefinition {
    View(LinearGradientView.self) {
    }
  }
}
```
    ```kotlin
class LinearGradientView(
  context: Context,
  appContext: AppContext,
) : ExpoView(context, appContext)
class LinearGradientModule : Module() {
  override fun definition() = ModuleDefinition {
    View(LinearGradientView::class) {
    }
  }
}
```
<a id="guides"></a>
## 指南
¥Guides
  <a id="sending-events"></a>
  ### 发送事件
  ¥Sending events
  虽然 JavaScript/TypeScript 到 Native 的通信主要由原生函数覆盖，但你可能还想让 JavaScript/TypeScript 代码了解某些系统事件，例如，当剪贴板内容发生更改时。
  ¥While JavaScript/TypeScript to Native communication is mostly covered by native functions, you might also want to let the JavaScript/TypeScript code know about certain system events, for example, when the clipboard content changes.
  为此，在模块定义中，你需要提供模块可以使用 [活动](#events) 定义组件发送的事件名称。之后，你可以在模块实例上使用 `sendEvent(eventName, payload)` 函数来发送带有一些负载的实际事件。例如，发送原生事件的最小剪贴板实现可能如下所示：
  ¥To do this, in the module definition, you need to provide the event names that the module can send using the [Events](#events) definition component. After that, you can use the `sendEvent(eventName, payload)` function on the module instance to send the actual event with some payload. For example, a minimal clipboard implementation that sends native events may look like this:
    ```swift
let CLIPBOARD_CHANGED_EVENT_NAME = "onClipboardChanged"
public class ClipboardModule: Module {
  public func definition() -> ModuleDefinition {
    Events(CLIPBOARD_CHANGED_EVENT_NAME)
    OnStartObserving {
      NotificationCenter.default.addObserver(
        self,
        selector: #selector(self.clipboardChangedListener),
        name: UIPasteboard.changedNotification,
        object: nil
      )
    }
    OnStopObserving {
      NotificationCenter.default.removeObserver(
        self,
        name: UIPasteboard.changedNotification,
        object: nil
      )
    }
  }
  @objc
  private func clipboardChangedListener() {
    sendEvent(CLIPBOARD_CHANGED_EVENT_NAME, [
      "contentTypes": availableContentTypes()
    ])
  }
}
```
    ```kotlin
const val CLIPBOARD_CHANGED_EVENT_NAME = "onClipboardChanged"
class ClipboardModule : Module() {
  override fun definition() = ModuleDefinition {
    Events(CLIPBOARD_CHANGED_EVENT_NAME)
    OnStartObserving {
      clipboardManager?.addPrimaryClipChangedListener(listener)
    }
    OnStopObserving {
      clipboardManager?.removePrimaryClipChangedListener(listener)
    }
  }
  private val clipboardManager: ClipboardManager?
    get() = appContext.reactContext?.getSystemService(Context.CLIPBOARD_SERVICE) as? ClipboardManager
  private val listener = ClipboardManager.OnPrimaryClipChangedListener {
    clipboardManager?.primaryClipDescription?.let { clip ->
      this@ClipboardModule.sendEvent(
        CLIPBOARD_CHANGED_EVENT_NAME,
        bundleOf(
          "contentTypes" to availableContentTypes(clip)
        )
      )
    }
  }
}
```
  要在 JavaScript/TypeScript 中订阅这些事件，请在 `requireNativeModule` 返回的模块对象上使用 [`addListener`](/versions/latest/sdk/expo/#addlistenereventname-listener)。模块正在扩展内置的 [`EventEmitter`](/versions/latest/sdk/expo/#eventemitter) 类。或者，你可以使用 [`useEvent`](/versions/latest/sdk/expo/#useeventeventemitter-eventname-initialvalue) 或 [`useEventListener`](/versions/latest/sdk/expo/#useeventlistenereventemitter-eventname-listener) 钩子。
  ¥To subscribe to these events in JavaScript/TypeScript, use [`addListener`](/versions/latest/sdk/expo/#addlistenereventname-listener) on the module object returned by `requireNativeModule`. Modules are extending the built-in [`EventEmitter`](/versions/latest/sdk/expo/#eventemitter) class.
  Alternatively, you can use [`useEvent`](/versions/latest/sdk/expo/#useeventeventemitter-eventname-initialvalue) or [`useEventListener`](/versions/latest/sdk/expo/#useeventlistenereventemitter-eventname-listener) hooks.
  ```ts TypeScript
import { requireNativeModule, NativeModule } from 'expo';
type ClipboardChangeEvent = {
  contentTypes: string[];
};
type ClipboardModuleEvents = {
  onClipboardChanged(event: ClipboardChangeEvent): void;
};
declare class ClipboardModule extends NativeModule<ClipboardModuleEvents> {}
const Clipboard = requireNativeModule<ClipboardModule>('Clipboard');
Clipboard.addListener('onClipboardChanged', (event: ClipboardChangeEvent) => {
  alert('Clipboard has changed');
});
```
  <a id="view-callbacks"></a>
  ### 查看回调
  ¥View callbacks
  某些事件与特定视图相关。例如，触摸事件应该只发送到被按下的底层 JavaScript 视图。在这种情况下，你不能使用 [`Sending events`](#sending-events) 中描述的 `sendEvent`。`expo-modules-core` 引入了视图回调机制来处理视图绑定事件。
  ¥Some events are connected to a certain view. For example, the touch event should be sent only to the underlying JavaScript view which was pressed. In that case, you can't use `sendEvent` described in [`Sending events`](#sending-events). The `expo-modules-core` introduces a view callbacks mechanism to handle view-bound events.
  要使用它，在视图定义中，你需要提供视图可以使用 [活动](#events) 定义组件发送的事件名称。之后，你需要在视图类中声明一个类型为 `EventDispatcher` 的属性。声明的属性的名称必须与 `Events` 组件中导出的名称相同。稍后，你可以将其作为函数调用，并在 iOS 上传递 `[String: Any?]` 类型的有效负载，在 Android 上传递 `Map<String, Any?>` 类型的有效负载。
  ¥To use it, in the view definition, you need to provide the event names that the view can send using the [Events](#events) definition component. After that, you need to declare a property of type `EventDispatcher` in your view class. The name of the declared property has to be the same as the name exported in the `Events` component. Later, you can call it as a function and pass a payload of type `[String: Any?]` on iOS and `Map<String, Any?>` on Android.
  > 注意：在 Android 上，可以指定有效负载类型。如果类型不转换为对象，则有效负载将被封装并存储在 `payload` 键下：`{payload: <provided value>}`。
  >
  > ¥**Note:**: On Android, it's possible to specify the payload type. In case of types that don't convert into objects, the payload will be encapsulated and stored under the `payload` key: `{payload: <provided value>}`.
    ```swift
class CameraViewModule: Module {
  public func definition() -> ModuleDefinition {
    View(CameraView.self) {
      Events(
        "onCameraReady"
      )
    }
  }
}
class CameraView: ExpoView {
  let onCameraReady = EventDispatcher()
  func callOnCameraReady() {
    onCameraReady([
      "message": "Camera was mounted"
    ]);
  }
}
```
    ```kotlin
class CameraViewModule : Module() {
  override fun definition() = ModuleDefinition {
    View(ExpoCameraView::class) {
      Events(
        "onCameraReady"
      )
    }
  }
}
class CameraView(
  context: Context,
  appContext: AppContext
) : ExpoView(context, appContext) {
  val onCameraReady by EventDispatcher()
  fun callOnCameraReady() {
    onCameraReady(mapOf(
      "message" to "Camera was mounted"
    ));
  }
}
```
  要在 JavaScript/TypeScript 中订阅这些事件，你需要将一个函数传递给原生视图，如下所示：
  ¥To subscribe to these events in JavaScript/TypeScript, you need to pass a function to the native view as shown:
  ```tsx TypeScript
import { requireNativeViewManager } from 'expo-modules-core';
const CameraView = requireNativeViewManager('CameraView');
export default function MainView() {
  const onCameraReady = event => {
    console.log(event.nativeEvent);
  };
  return <CameraView onCameraReady={onCameraReady} />;
}
```
  提供的有效负载在 `nativeEvent` 密钥下可用。
  ¥Provided payload is available under the `nativeEvent` key.
<a id="examples"></a>
## 示例
¥Examples
  ```swift
public class MyModule: Module {
  public func definition() -> ModuleDefinition {
    Name("MyFirstExpoModule")
    Function("hello") { (name: String) in
      return "Hello \(name)!"
    }
  }
}
```
  ```kotlin
class MyModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("MyFirstExpoModule")
    Function("hello") { name: String ->
      return "Hello $name!"
    }
  }
}
```
有关实际模块的更多示例，你可以参考 GitHub 上已经使用此 API 的 Expo 模块：
¥For more examples from real modules, you can refer to Expo modules that already use this API on GitHub:


## Android 生命周期监听器

了解允许你的库使用 Expo 模块 API 钩子 Android 活动和应用功能的机制。

要响应与应用相关的某些 Android 系统事件（例如入站链接和配置更改），有必要覆盖 MainActivity.java 和/或 MainApplication.java 中相应的生命周期回调。
¥To respond to certain Android system events relevant to an app, such as inbound links and configuration changes, it is necessary to override the corresponding lifecycle callbacks in **MainActivity.java** and/or **MainApplication.java**.
React Native 模块 API 不提供任何机制来钩子这些文件，因此 React Native 库的设置说明通常包括将代码复制到这些文件中的步骤。为了简化和自动化设置和维护，Expo Modules API 提供了一种机制，允许你的库挂接到 `Activity` 或 `Application` 函数。
¥The React Native module API does not provide any mechanism to hook into these, and so setup instructions for React Native libraries often include steps to copy code into these files. To simplify and automate setup and maintenance, the Expo Modules API provides a mechanism that allows your library to hook into `Activity` or `Application` functions.
<a id="get-started"></a>
## 开始使用
¥Get started
首先，你需要创建一个 Expo 模块或使用 React Native 模块 API 将 Expo 模块 API 集成到库中。[了解更多](./overview.mdx#setup)。
¥First, you need to have created an Expo module or integrated the Expo modules API in the library using the React Native module API. [Learn more](./overview.mdx#setup).
在模块内部，创建一个实现 [`Package`](https://github.com/expo/expo/tree/main/packages/expo-modules-core/android/src/main/java/expo/modules/core/interfaces/Package.java) 接口的具体类。对于大多数情况，你只需要实现 `createReactActivityLifecycleListeners` 或 `createApplicationLifecycleListeners` 方法。
¥Inside your module, create a concrete class that implements the [`Package`](https://github.com/expo/expo/tree/main/packages/expo-modules-core/android/src/main/java/expo/modules/core/interfaces/Package.java) interface. For most cases, you only need to implement the `createReactActivityLifecycleListeners` or `createApplicationLifecycleListeners` methods.
<a id="activity-lifecycle-listeners"></a>
## `Activity` 生命周期监听器
¥`Activity` lifecycle listeners
你可以使用 `ReactActivityLifecycleListener` 钩子到 `Activity` 生命周期。`ReactActivityLifecycleListener` 使用其 `ReactActivityDelegate` 与 React Native 的 `ReactActivity` 生命周期钩子，并提供与 Android `Activity` 生命周期类似的体验。
¥You can hook into the `Activity` lifecycle using `ReactActivityLifecycleListener`. `ReactActivityLifecycleListener` hooks into React Native's `ReactActivity` lifecycle using its `ReactActivityDelegate` and provides a similar experience to the Android `Activity` lifecycle.
目前支持以下 `Activity` 生命周期回调：
¥The following `Activity` lifecycle callbacks are currently supported:
* `onCreate`
* `onResume`
* `onPause`
* `onDestroy`
* `onNewIntent`
* `onBackPressed`
要创建 `ReactActivityLifecycleListener`，你应该在派生的 `Package` 类中实现 `createReactActivityLifecycleListeners`。例如，`MyLibPackage`。
¥To create a `ReactActivityLifecycleListener`, you should implement `createReactActivityLifecycleListeners` in your derived `Package` class. For example, `MyLibPackage`.
```kotlin
// android/src/main/java/expo/modules/mylib/MyLibPackage.kt
package expo.modules.mylib
import android.content.Context
import expo.modules.core.interfaces.Package
import expo.modules.core.interfaces.ReactActivityLifecycleListener
class MyLibPackage : Package {
  override fun createReactActivityLifecycleListeners(activityContext: Context): List<ReactActivityLifecycleListener> {
    return listOf(MyLibReactActivityLifecycleListener())
  }
}
```
```java
// android/src/main/java/expo/modules/mylib/MyLibPackage.java
package expo.modules.mylib;
import android.content.Context;
import expo.modules.core.interfaces.Package;
import expo.modules.core.interfaces.ReactActivityLifecycleListener;
import java.util.Collections;
import java.util.List;
public class MyLibPackage implements Package {
  @Override
  public List<? extends ReactActivityLifecycleListener> createReactActivityLifecycleListeners(Context activityContext) {
    return Collections.singletonList(new MyLibReactActivityLifecycleListener());
  }
}
```
`MyLibReactActivityLifecycleListener` 是 `ReactActivityLifecycleListener` 派生类，你可以将其挂接到生命周期中。你只能重写你需要的方法。
¥`MyLibReactActivityLifecycleListener` is a `ReactActivityLifecycleListener` derived class that you can hook into the lifecycles. You can only override the methods you need.
```kotlin
// android/src/main/java/expo/modules/mylib/MyLibReactActivityLifecycleListener.kt
package expo.modules.mylib
import android.app.Activity
import android.os.Bundle
import expo.modules.core.interfaces.ReactActivityLifecycleListener
class MyLibReactActivityLifecycleListener : ReactActivityLifecycleListener {
  override fun onCreate(activity: Activity, savedInstanceState: Bundle?) {
    // Your setup code in `Activity.onCreate`.
    doSomeSetupInActivityOnCreate(activity)
  }
}
```
```java
// android/src/main/java/expo/modules/mylib/MyLibReactActivityLifecycleListener.java
package expo.modules.mylib;
import android.app.Activity;
import android.os.Bundle;
import expo.modules.core.interfaces.ReactActivityLifecycleListener;
public class MyLibReactActivityLifecycleListener implements ReactActivityLifecycleListener {
  @Override
  public void onCreate(Activity activity, Bundle savedInstanceState) {
    // Your setup code in `Activity.onCreate`.
    doSomeSetupInActivityOnCreate(activity);
  }
}
```
<a id="application-lifecycle-listeners"></a>
## `Application` 生命周期监听器
¥`Application` lifecycle listeners
你可以使用 `ApplicationLifecycleListener` 钩子到 `Application` 生命周期。
¥You can hook into the `Application` lifecycle using `ApplicationLifecycleListener`.
目前支持以下 `Application` 生命周期回调：
¥The following `Application` lifecycle callbacks are currently supported:
* `onCreate`
* `onConfigurationChanged`
要创建 `ApplicationLifecycleListener`，你应该在派生的 `Package` 类中实现 `createApplicationLifecycleListeners`。例如，`MyLibPackage`。
¥To create an `ApplicationLifecycleListener`, you should implement `createApplicationLifecycleListeners` in your derived `Package` class. For example, `MyLibPackage`.
```kotlin
// android/src/main/java/expo/modules/mylib/MyLibPackage.kt
package expo.modules.mylib
import android.content.Context
import expo.modules.core.interfaces.ApplicationLifecycleListener
import expo.modules.core.interfaces.Package
class MyLibPackage : Package {
  override fun createApplicationLifecycleListeners(context: Context): List<ApplicationLifecycleListener> {
    return listOf(MyLibApplicationLifecycleListener())
  }
}
```
```java
// android/src/main/java/expo/modules/mylib/MyLibPackage.java
import android.content.Context;
import java.util.Collections;
import java.util.List;
import expo.modules.core.interfaces.ApplicationLifecycleListener;
import expo.modules.core.interfaces.Package;
public class MyLibPackage implements Package {
  @Override
  public List<? extends ApplicationLifecycleListener> createApplicationLifecycleListeners(Context context) {
    return Collections.singletonList(new MyLibApplicationLifecycleListener());
  }
}
```
`MyLibApplicationLifecycleListener` 是 `ApplicationLifecycleListener` 派生类，可以钩子到 `Application` 生命周期回调。你应该只重写你需要的方法（[由于可能的维护成本](#interface-stability)）。
¥`MyLibApplicationLifecycleListener` is an `ApplicationLifecycleListener` derived class that can hook into the `Application` lifecycle callbacks. You should only override the methods you need ([due to possible maintenance costs](#interface-stability)).
```kotlin
// android/src/main/java/expo/modules/mylib/MyLibApplicationLifecycleListener.kt
package expo.modules.mylib
import android.app.Application
import expo.modules.core.interfaces.ApplicationLifecycleListener
class MyLibApplicationLifecycleListener : ApplicationLifecycleListener {
  override fun onCreate(application: Application) {
    // Your setup code in `Application.onCreate`.
    doSomeSetupInApplicationOnCreate(application)
  }
}
```
```java
// android/src/main/java/expo/modules/mylib/MyLibApplicationLifecycleListener.java
package expo.modules.mylib;
import android.app.Application;
import expo.modules.core.interfaces.ApplicationLifecycleListener;
public class MyLibApplicationLifecycleListener implements ApplicationLifecycleListener {
  @Override
  public void onCreate(Application application) {
    // Your setup code in `Application.onCreate`.
    doSomeSetupInApplicationOnCreate(application);
  }
}
```
<a id="known-issues"></a>
## 已知的问题
¥Known issues
<a id="why-there-are-no-onstart-and-onstop-activity-listeners"></a>
### 为什么没有 `onStart` 和 `onStop` Activity 监听器
¥Why there are no `onStart` and `onStop` Activity listeners
在当前的实现中，我们没有从 `MainActivity` 设置钩子，而是从 [`ReactActivityDelegate`](https://github.com/facebook/react-native/blob/400902093aa3ccfc05712a996c592a86f342253a/ReactAndroid/src/main/java/com/facebook/react/ReactActivityDelegate.java) 设置钩子。`MainActivity` 和 `ReactActivityDelegate` 之间存在一些细微差别。由于 `ReactActivityDelegate` 没有 `onStart` 和 `onStop`，所以我们这里还不支持它们。
¥In the current implementation, we do not set up the hooks from `MainActivity` but from [`ReactActivityDelegate`](https://github.com/facebook/react-native/blob/400902093aa3ccfc05712a996c592a86f342253a/ReactAndroid/src/main/java/com/facebook/react/ReactActivityDelegate.java). There are some slight differences between `MainActivity` and `ReactActivityDelegate`. Since `ReactActivityDelegate` does not have `onStart` and `onStop`, we don't yet support them here.
<a id="interface-stability"></a>
### 接口稳定性
¥Interface stability
监听器接口可能会在 Expo SDK 版本之间不时发生变化。我们的向后兼容性策略始终是添加新接口并为我们计划删除的接口添加 `@Deprecated` 注释。我们的接口都是基于 Java 8 接口默认方法；你不必也不应该实现所有方法。这样做将有利于你的模块在 Expo SDK 之间的维护成本。
¥The listener interfaces may change from time to time between Expo SDK releases. Our strategy for backward compatibility is always to add new interfaces and add `@Deprecated` annotation for interfaces we plan to remove. Our interfaces are all based on Java 8 interface default method; you don't have to and should not implement all methods. Doing this will benefit your module's maintenance cost between Expo SDKs.


## iOS AppDelegate 订阅者

了解如何使用 Expo 模块 API 订阅与应用相关的 iOS 系统事件，例如入站链接和通知。

为了响应与应用相关的某些 iOS 系统事件，例如入站链接和通知，需要处理 `AppDelegate` 中的相应方法。
¥To respond to certain iOS system events relevant to an app, such as inbound links and notifications, it is necessary to handle the corresponding methods in the `AppDelegate`.
React Native 模块 API 不提供任何机制来钩子这些方法，因此 React Native 库的设置指令通常包括将代码复制到 `AppDelegate` 文件中的步骤。为了简化和自动化设置和维护，Expo Modules API 提供了一种机制，允许你的库订阅对 `AppDelegate` 函数的调用。为此，应用 `AppDelegate` 必须继承自 `ExpoAppDelegate`，这是使用 Expo 模块的要求。
¥The React Native module API does not provide any mechanism to hook into these methods, and so setup instructions for React Native libraries often include a step to copy code into the `AppDelegate` file. To simplify and automate setup and maintenance, the Expo Modules API provides a mechanism that allows your library to subscribe to calls to `AppDelegate` functions. For this to work, the app `AppDelegate` must inherit from `ExpoAppDelegate`, and this is a requirement for using Expo Modules.
`ExpoAppDelegate` 实现 [`UIApplicationDelegate`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate) 协议的大部分功能，并将其调用转发给所有订阅者。
¥`ExpoAppDelegate` implements most functions from [`UIApplicationDelegate`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate) protocol and forwards their calls to all the subscribers.
<a id="get-started"></a>
## 开始使用
¥Get started
首先，你需要创建一个 Expo 模块或使用 React Native 模块 API 将 Expo 模块 API 集成到库中。[了解更多](./overview.mdx#setup)。
¥First, you need to have created an Expo module or integrated the Expo modules API in library using the React Native module API. [Learn more](./overview.mdx#setup).
创建一个新的公共 Swift 类，该类从 `ExpoModulesCore` 扩展 `ExpoAppDelegateSubscriber`，并将其名称添加到 [模块配置](/modules/module-config/) 中的 `apple.appDelegateSubscribers` 数组中。运行 `pod install`，订阅者将在应用项目内的 ExpoModulesProvider.swift 文件中生成。
¥Create a new public Swift class that extends `ExpoAppDelegateSubscriber` from `ExpoModulesCore` and add its name to the `apple.appDelegateSubscribers` array in the [module config](/modules/module-config/). Run `pod install`, and the subscriber will be generated in the **ExpoModulesProvider.swift** file within the application project.
现在，你可以通过向订阅者类添加委托函数来订阅事件。有关你可以订阅的函数的完整列表，请参阅 [`ExpoAppDelegate.swift`](https://github.com/expo/expo/blob/main/packages/expo/ios/AppDelegates/ExpoAppDelegate.swift) 中覆盖的函数。尚不支持提供时可能会导致副作用的应用委托函数（例如，[`application(_:viewControllerWithRestorationIdentifierPath:coder:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623062-application)）。
¥Now you can subscribe to events by adding delegate functions to your subscriber class. For the full list of functions that you can subscribe to, see the functions that are overridden in [`ExpoAppDelegate.swift`](https://github.com/expo/expo/blob/main/packages/expo/ios/AppDelegates/ExpoAppDelegate.swift). App delegate functions that may cause side effects when provided are not supported yet (for example, [`application(_:viewControllerWithRestorationIdentifierPath:coder:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623062-application)).
> 不支持 Objective-C 类。
>
> ¥Objective-C classes are not supported.
<a id="result-values"></a>
## 结果值
¥Result values
需要返回值的委托函数有一些额外的逻辑来协调来自多个订阅者的响应并尝试满足所有这些响应。这种边缘情况有两个很好的例子：
¥Delegate functions that need to return a value have some additional logic to reconcile responses from multiple subscribers and try to satisfy all of them. There are two good examples of such edge cases:
<a id="application_didfinishlaunchingwithoptions---bool"></a>
#### `application(_:didFinishLaunchingWithOptions:) -> Bool`
根据 [苹果文档](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622921-application)，如果应用无法处理 URL 资源或继续用户活动，则应返回 `false`，否则应返回 `true`。如果应用因远程通知而启动，则返回值将被忽略。在这种情况下，如果至少一个订阅者返回 `true`，则 `ExpoAppDelegate` 也会返回 `true`。
¥According to the [Apple documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622921-application), you should return `false` if the app cannot handle the URL resource or continue a user activity, otherwise `true` should be returned. The return value is ignored if the app is launched because of a remote notification.
In such situations, if at least one of the subscribers returns `true`, the `ExpoAppDelegate` will return `true` as well.
<a id="application_didreceiveremotenotificationfetchcompletionhandler"></a>
#### `application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`
此方法告诉应用委托远程通知已到达，并使应用有机会获取新数据。它接收一个完成块，在获取操作完成时执行。应使用最能描述提取请求结果的提取结果值来调用此块。可能的值为：`UIBackgroundFetchResult.newData`、`UIBackgroundFetchResult.noData` 或 `UIBackgroundFetchResult.failed`。在这种情况下，`ExpoAppDelegate` 将新的完成块传递给每个订阅者，等待所有完成并在调用原始完成块之前收集结果。最终结果取决于订阅者收集的结果，按以下顺序排列：
¥This method tells the app delegate that a remote notification arrived and gives the app the opportunity to fetch new data. It receives a completion block to execute when the fetch operation is completed. This block should be called with the fetch result value that best describes the results of your fetch request. Possible values are: `UIBackgroundFetchResult.newData`, `UIBackgroundFetchResult.noData` or `UIBackgroundFetchResult.failed`.
In this scenario, `ExpoAppDelegate` passes a new completion block to each subscriber, waits until all are completed and collects the results before calling the original completion block. The final result depends on the results collected from the subscribers, as follows in the following order:
* 如果至少有一个订阅者使用 `failed` 结果调用完成块，则委托也会返回 `failed`。
  ¥If at least one subscriber called the completion block with `failed` result, the delegate returns `failed` as well.
* 如果至少有一个 `newData` 结果，则委托返回 `newData`。
  ¥If there is at least one `newData` result, the delegate returns `newData`.
* 否则返回 `noData`。
  ¥Otherwise `noData` is returned.
> 要查看其他函数如何处理订阅者的结果，我们建议直接阅读代码：[`ExpoAppDelegate.swift`](https://github.com/expo/expo/blob/main/packages/expo/ios/AppDelegates/ExpoAppDelegate.swift)。
>
> ¥To check out how other functions process the result of your subscriber, we recommend reading the code directly: [`ExpoAppDelegate.swift`](https://github.com/expo/expo/blob/main/packages/expo/ios/AppDelegates/ExpoAppDelegate.swift).
<a id="example"></a>
## 示例
¥Example
```swift AppLifecycleDelegate.swift
import ExpoModulesCore
public class AppLifecycleDelegate: ExpoAppDelegateSubscriber {
  public func applicationDidBecomeActive(_ application: UIApplication) {
    // The app has become active.
  }
  public func applicationWillResignActive(_ application: UIApplication) {
    // The app is about to become inactive.
  }
  public func applicationDidEnterBackground(_ application: UIApplication) {
    // The app is now in the background.
  }
  public func applicationWillEnterForeground(_ application: UIApplication) {
    // The app is about to enter the foreground.
  }
  public func applicationWillTerminate(_ application: UIApplication) {
    // The app is about to terminate.
  }
}
```
```json expo-module.config.json
{
  "apple": {
    "appDelegateSubscribers": ["AppLifecycleDelegate"]
  }
}
```


## 自动链接

了解如何使用 Expo 自动链接自动链接 Expo 项目中的原生依赖。

通常，当你开发原生移动应用并想要安装第三方库时，系统会要求你将依赖添加到包管理器的清单文件中（Android 上的 build.gradle、iOS 上的 CocoaPods 的 Podfile、 iOS 上 SwiftPM 的 Package.swift）。在 Expo 和 React Native 中，你已经通过从 [npm](https://www.npmjs.com) 注册表安装包来使用 package.json 文件执行此操作。由于大多数 React Native 库都附带了一些原生（特定于平台的）代码，因此安装库甚至需要配置最多三个不同的包管理器！
¥Usually, when you're developing a native mobile app and want to install a third-party library, you're asked to add the dependency to the manifest files of your package managers (**build.gradle** on Android, **Podfile** for CocoaPods on iOS, **Package.swift** for SwiftPM on iOS).
In Expo and React Native, you already do that with your **package.json** file by installing the package from the [npm](https://www.npmjs.com) registry. Since most of the React Native libraries come with some native (platform-specific) code,
installing a library will require configuring even up to three different package managers!
Expo Autolinking 是一种自动执行此过程并将库安装过程减少到最少的机制 - 通常只需从 `npm` 安装软件包并重新运行 `pod install`。核心实现可以在 [`expo-modules-autolinking`](https://github.com/expo/expo/tree/main/packages/expo-modules-autolinking) 包中找到，分为三个部分：
¥Expo Autolinking is a mechanism that automates this process and reduces the library installation process to the minimum — usually just installing the package from `npm` and re-running `pod install`.
The core implementation can be found in the [`expo-modules-autolinking`](https://github.com/expo/expo/tree/main/packages/expo-modules-autolinking) package and is divided into three parts:
1. 具有模块解析算法的通用 JavaScript CLI 工具
   ¥common JavaScript CLI tool with the module resolution algorithm
2. 与 Android 平台的 Gradle 构建系统集成的代码
   ¥code that integrates with the Gradle build system for Android platform
3. 与 iOS 平台的 CocoaPods 集成的 Ruby 脚本
   ¥Ruby script that integrates with CocoaPods for iOS platform
<a id="cli-commands"></a>
## CLI 命令
¥CLI commands
  <a id="search"></a>
  ### `search`
  搜索是解决项目中安装的 Expo 模块的第一阶段。它的实现在所有平台之间共享。它找到所有标记为 Expo 模块的模块，并确定哪个版本具有最高优先级（以防重复）。
  ¥Searching is the first phase of resolving the Expo modules installed in a project. Its implementation is shared between all platforms. It finds all modules marked as Expo modules and determines which version is of the highest precedence (in case of duplicates).
  ```sh
$ npx expo-modules-autolinking search
```
  上面的命令返回一个 JSON 格式的对象，其中包含已找到的依赖模块：
  ¥The above command returns an object in JSON format with modules that have been found as dependencies:
  ```json
{
  "expo-random": {
    "path": "/absolute/path/to/node_modules/expo-random",
    "version": "13.0.0",
    "config": {
      // Contents of `expo-module.config.json`
      "platforms": ["ios", "android"],
      "ios": { "modules": ["RandomModule"] },
      "android": { "modules": ["expo.modules.random.RandomModule"] }
    },
    "duplicates": [] // An array of other revisions (with lower precedence) of the same module
  }
  // more modules...
}
```
  <a id="resolve"></a>
  ### `resolve`
  解决是第二阶段，基于 `search` 命令的结果。它将每个搜索结果解析为具有更多（特定于平台）详细信息的对象，例如 podspec 或 build.gradle 文件的路径以及要链接的模块类。
  ¥Resolving is the second phase based on the results from the `search` command. It resolves each search result to an object with more (platform-specific) details, such as the path to the podspec or **build.gradle** files and module classes to link.
  ```sh
$ npx expo-modules-autolinking resolve --platform <apple|android>
```
  例如，使用 `--platform apple` 选项，它会返回一个 JSON 格式的对象，其中包含模块数组和平台的解析详细信息：
  ¥For example, with the `--platform apple` option it returns an object in JSON format with an array of modules and resolved details for the platform:
  ```json
{
  "modules": [
    {
      "packageName": "expo-random",
      "packageVersion": "13.0.0",
      "pods": [
        {
          "podName": "ExpoRandom",
          "podspecDir": "/absolute/path/to/node_modules/expo-random/ios"
        }
      ],
      "swiftModuleNames": ["ExpoRandom"],
      "modules": ["RandomModule"],
      "appDelegateSubscribers": [],
      "reactDelegateHandlers": [],
      "debugOnly": false
    }
    // more modules...
  ]
}
```
  <a id="verify"></a>
  ### `verify`
  通过检查是否没有重复的包来验证搜索结果，否则会显示相应的警告。
  ¥Verifies the search results by checking whether there are no duplicate packages, otherwise an appropriate warning is shown.
  ```sh
$ npx expo-modules-autolinking verify
```
<a id="configuration"></a>
## 配置
¥Configuration
可以使用一些配置选项来自定义模块解析的行为。这些选项可以在三个不同的位置定义，从最低优先级到最高优先级：
¥The behavior of the module resolution can be customized using some configuration options. These options can be defined in three different places, from the lowest to the highest precedence:
* 应用的 package.json 中的 `expo.autolinking` 配置对象
  ¥`expo.autolinking` config object in application's **package.json**
* 每个平台使用 `expo.autolinking.ios` 和 `expo.autolinking.android` 对象覆盖
  ¥per platform overrides with `expo.autolinking.ios` and `expo.autolinking.android` objects
* 提供给 CLI 命令的选项、Podfile 中的 `use_expo_modules!` 方法或 settings.gradle 中的 `useExpoModules` 函数
  ¥options provided to the CLI command, the `use_expo_modules!` method in the **Podfile** or `useExpoModules` function in the **settings.gradle**
  <a id="searchpaths"></a>
  ### `searchPaths`
  相对于应用根目录的路径列表，自动链接脚本应在其中搜索 Expo 模块。它默认为遍历 monorepo 时找到的所有 node_modules 目录的列表，从应用的根目录开始。当你的项目具有自定义结构或你想要从不同于 node_modules 的目录链接本地包时很有用。
  ¥A list of paths relative to the app's root directory where the autolinking script should search for Expo modules.
  It defaults to a list of all **node_modules** directories found when traversing up through a monorepo, starting from the app's root directory.
  Useful when your project has a custom structure or you want to link local packages from directories different than **node_modules**.
  ```json package.json
{
  "expo": {
    "autolinking": {
      "searchPaths": ["../../packages"]
    }
  }
}
```
  与 CLI 一起使用时，你可以将搜索路径作为命令参数传递，如下所示：
  ¥When used with the CLI, you can pass the search paths as command arguments like this:
  ```sh
$ npx expo-modules-autolinking search ../../packages
```
  <a id="exclude"></a>
  ### `exclude`
  要从自动链接中排除的包名称列表。即使在搜索路径中找到这些包，也不会自动链接它们。例如，你可能不想链接某些不在特定平台上使用的包，以减少二进制文件的大小。package.json 中的以下配置将从 Android 上的自动链接中排除 `expo-random` 和 `third-party-expo-module`：
  ¥A list of package names to exclude from autolinking. These packages will not be autolinked even if they are found in the search paths.
  For example, you may want not to link some packages that you don't use on the specific platform to reduce the binary size.
  The following config in **package.json** will exclude `expo-random` and `third-party-expo-module` from autolinking on Android:
  ```json package.json
{
  "expo": {
    "autolinking": {
      "android": {
        "exclude": ["expo-random", "third-party-expo-module"]
      }
    }
  }
}
```
  请注意，`exclude` 选项用于排除 Expo 包的自动链接。要排除任何其他包的自动链接，请在项目的根目录中创建 react-native.config.js 并应用配置，如下例所示：
  ¥Note that the `exclude` option is for excluding the autolinking of Expo packages. To exclude the autolinking for any other packages, create **react-native.config.js** at the root directory of your project and apply the configuration as shown in the example below:
  ```js react-native.config.js
module.exports = {
  dependencies: {
    'library-name': {
      platforms: {
        android: null,
      },
    },
  },
};
```
#### Android Only
  <a id="flags"></a>
  ### `flags`
  CocoaPods 标志传递给每个自动链接的 pod。`inhibit_warnings` 可能是大多数开发者想要使用的唯一标志，以抑制编译自动链接模块时产生的 Xcode 警告。你可以参考 [CocoaPods Podfile 文档](https://guides.cocoapods.org/syntax/podfile.html#pod) 了解可用标志。
  ¥CocoaPods flags to pass to each autolinked pod. `inhibit_warnings` is likely the only flag most developers want to use, to inhibit Xcode warnings produced when compiling the autolinked modules.
  You can refer to the [CocoaPods Podfile documentation](https://guides.cocoapods.org/syntax/podfile.html#pod) for available flags.
    ```ruby
use_expo_modules!({
  flags: {
    :inhibit_warnings => false
  }
})
```
    ```json
{
  "expo": {
    "autolinking": {
      "ios": {
        "flags": {
          "inhibit_warnings": true
        }
      }
    }
  }
}
```
<a id="common-questions"></a>
## 常见问题
¥Common questions
<a id="how-to-set-up-the-autolinking-in-my-app"></a>
### 如何在我的应用中设置自动链接？
¥How to set up the autolinking in my app?
使用 `npx create-expo-app` 命令创建的所有项目都已配置为使用 Expo 自动链接。如果你的项目是使用其他工具创建的，请参阅 [安装 Expo 模块](/bare/installing-expo-modules) 以确保你的项目包含所有必要的更改。
¥All projects created with the `npx create-expo-app` command are already configured to use Expo Autolinking. If your project was created using a different tool, see [Installing Expo modules](/bare/installing-expo-modules) to make sure your project includes all necessary changes.
<a id="what-do-i-need-to-have-in-my-module-to-make-it-autolinkable"></a>
### 我的模块中需要有什么才能使其可自动链接？
¥What do I need to have in my module to make it autolinkable?
模块解析算法仅搜索根目录中 package.json 文件旁边包含 [Expo 模块配置](/modules/module-config/) 文件 (expo-module.config.json) 的包。还需要在 `platforms` 数组中包含支持的平台 - 如果运行自动链接算法的平台不存在于该数组中，则只会在搜索结果中跳过它。
¥The module resolution algorithm searches only for packages that contain the [Expo module config](/modules/module-config/) file (**expo-module.config.json**) at the root directory, next to the **package.json** file.
It's also necessary to include supported platforms in the `platforms` array — if the platform for which the autolinking algorithm is run is not present in this array, it's just skipped in the search results.
<a id="how-is-it-different-from-react-native-community-cli-autolinking"></a>
### 它与 React Native 社区 CLI 自动链接有何不同？
¥How is it different from React Native community CLI autolinking?
* Expo Autolinking 内置了对 monorepos、Yarn 工作区和传递依赖的支持。
  ¥Expo Autolinking comes in with built-in support for monorepos, Yarn workspaces and transitive dependencies.
* 即使模块解析算法更复杂，也更可靠并与节点的模块解析相匹配，它的速度也明显更快。
  ¥It's also significantly faster, even though the module resolution algorithm is more complex to be more reliable and match the Node's module resolution.
* Expo 模块解析还能够检测重复项，这是 monorepos 中的常见问题。
  ¥Expo module resolution is also capable of detecting the duplicates which is a common issue in monorepos.
* 最后但并非最不重要的一点是，它与 Expo Modules API 提供的所有功能很好地集成。
  ¥Last but not least, it integrates well with all the features offered by Expo Modules APIs.
<a id="opting-out-of-expo-autolinking"></a>
### 选择退出 Expo 自动链接
¥Opting out of Expo Autolinking
从 SDK 52 开始，Expo Autolinking 默认启用，如果你想改用 React Native 社区 CLI 自动链接，请设置 `EXPO_USE_COMMUNITY_AUTOLINKING=1` 并将 `@react-native-community/cli` 作为开发依赖添加到你的项目中。
¥Starting from SDK 52, Expo Autolinking comes enabled by default, if you would like to use the React Native community CLI autolinking instead, set `EXPO_USE_COMMUNITY_AUTOLINKING=1` and add `@react-native-community/cli` as a dev dependency to your project.


## expo-module.config.json

了解 expo-module.config.json 中可用的不同配置选项。

Expo 模块在 expo-module.config.json 中配置。该文件当前能够配置自动链接和模块注册。可以使用以下属性：
¥Expo modules are configured in **expo-module.config.json**. This file currently is capable of configuring autolinking and module registration. The following properties are available:
* `platforms` — 一系列受支持的平台。可接受的值为 `android`、`apple`（或使用更精细的 `ios` / `macos` / `tvos`）、`web` 和 `devtools`（参见 [创建开发工具插件](/debugging/create-devtools-plugins)）。
  ¥`platforms` — An array of supported platforms. Acceptable values are `android`, `apple` (or use the more granular `ios` / `macos` / `tvos`), `web` and `devtools` (see [Create a dev tools plugin](/debugging/create-devtools-plugins)).
* `apple` — 使用特定于 Apple 平台的选项进行配置
  ¥`apple` — Config with options specific to Apple platforms
  * `modules` — 要放入生成的模块提供程序文件的 Swift 原生模块类的名称。
    ¥`modules` — Names of Swift native modules classes to put to the generated modules provider file.
  * `appDelegateSubscribers` — 钩子到 `ExpoAppDelegate` 以接收 AppDelegate 生命周期事件的 Swift 类的名称。
    ¥`appDelegateSubscribers` — Names of Swift classes that hook into `ExpoAppDelegate` to receive AppDelegate lifecycle events.
* `android` — 使用特定于 Android 平台的选项进行配置
  ¥`android` — Config with options specific to Android platform
  * `modules` — 要放入生成的包提供程序文件的 Kotlin 原生模块类的全名（包 + 类名）。
    ¥`modules` — Full names (package + class name) of Kotlin native modules classes to put to the generated package provider file.


## 在 Expo 模块中模拟原生调用

了解如何在 Expo 模块中模拟原生调用。

为 Expo 项目编写单元测试的推荐方法是使用 [Jest](https://jest.nodejs.cn/) 和 `jest-expo` 预设。
¥The recommended way to write unit tests for an Expo project is to use [Jest](https://jest.nodejs.cn/) and the `jest-expo` preset.
要为使用原生代码的应用编写单元测试，你需要模拟原生调用。术语“模拟”意味着用不执行任何操作的虚假版本替换函数的实际实现。此方法对于在本地计算机上运行单元测试非常有用，因为它涉及绕过对仅在设备上可用的原生代码的需求，并且调用本地计算机上的原生函数的任何代码都将不起作用。
¥To write a unit test for an app that uses native code, you need to mock native calls.
The term **Mocking** means to replace the actual implementation of a function with a fake version that does not perform any actions. This approach is useful for running unit tests on a local computer as it involves bypassing the need for native code which is only available on a device, and any code that calls native functions on a local machine will not work.
Expo SDK 包含针对我们每个社区包的一组默认模拟。你还可以使用内置 Jest API（例如 [模拟函数](https://jest.nodejs.cn/docs/mock-functions)）自行模拟任何 JS 代码。
¥Expo SDK includes a set of default mocks for each of our community packages. You can also mock any JS code yourself using built-in Jest APIs such as [mock functions](https://jest.nodejs.cn/docs/mock-functions).
但是，为了在你的 Expo 模块中提供默认模拟，我们提供了一种打包它们的方法。这确保了当你的模块用户运行单元测试时，他们将自动使用模拟的实现。
¥However, to provide default mocks in your Expo Module, we offer a method to bundle them. This ensures that when your module user runs unit tests, they will automatically use a mocked implementation.
<a id="providing-mocks-for-a-module"></a>
## 为模块提供模拟
¥Providing mocks for a module
创建一个与要模拟的原生模块同名的文件，并将其放置在模块的模拟目录中。确保从此文件导出模拟实现。在单元测试期间运行时，由于 `requireNativeModule` 调用，`jest-expo` 预设将自动返回导出的函数。
¥Create a file with the same name as the native module you want to mock and place it in your module's **mocks** directory. Make sure to export the mock implementation from this file.
The `jest-expo` preset will automatically return the exported functions because of a `requireNativeModule` call when running during a unit test.
例如，`expo-clipboard` 库有一个名为 `ExpoClipboard` 的原生模块。你将在 mocks 目录中创建一个 ExpoClipboard.ts 来模拟它。
¥For example, the `expo-clipboard` library has a native module called `ExpoClipboard`. You will create a **ExpoClipboard.ts** in the **mocks** directory to mock it.
```ts ExpoClipboard.ts
export async function hasStringAsync(): Promise<boolean> {
  return false;
}
```
现在，在单元测试中，调用 `ExpoClipboard.hasStringAsync()` 将返回 `false`。
¥Now, in a unit test, calling `ExpoClipboard.hasStringAsync()` returns `false`.
<a id="automatic-generation-of-mocks"></a>
## 自动生成模拟
¥Automatic generation of mocks
如果原生模块有多个方法，则维护原生模块的模拟可能会是一项繁重的工作。为了使这更容易，我们提供了一个脚本，可以自动为模块中的所有原生函数生成模拟。它适用于根据模块中的 Swift 实现生成 TypeScript 和 JavaScript 中的模拟。
¥Maintaining mocks for native modules can be a lot of work if the native module has multiple methods. To make this easier, we provide a script that automatically generates mocks for all native functions in a module.
It works for generating mocks in TypeScript and JavaScript based on the Swift implementation in your module.
要使用此脚本，你必须安装 [SourceKitten](https://github.com/jpsim/SourceKitten) 框架。然后，导航到模块目录（模块的 expo-module.config.json 所在的位置）并运行 `generate-ts-mocks` 命令。
¥To use this script, you have to install [SourceKitten](https://github.com/jpsim/SourceKitten) framework. Then, navigate to the module directory (where your module's **expo-module.config.json** is located) and run the `generate-ts-mocks` command.
```sh
$ brew install sourcekitten
$ npx expo-modules-test-core generate-ts-mocks
```
上面的命令会在模块的 mocks 目录中生成 ExpoModuleName.ts。它包含模块中每个原生方法和视图的模拟实现。
¥The command above generates **ExpoModuleName.ts** in the **mocks** directory of your module. It contains a mock implementation for each native method and view in your module.
> 提示：你还可以运行 `generate-js-mocks` 以在 JavaScript 中生成模拟。
>
> ¥**Tip:** You can also run `generate-js-mocks` to generate mocks in JavaScript.
<a id="more"></a>
## 更多
¥More


## Expo 模块 API：设计注意事项

关于 Expo Modules API 背后的设计考虑因素的概述。

Expo 团队维护着大量的库，随着时间的推移和在不断变化的环境中维护原生模块可能具有挑战性。借助 Expo Modules API，我们着手构建强大的工具，使构建和维护这些库更加容易。
¥The Expo team maintains a large set of libraries, and maintaining native modules over time and in a constantly changing environment can be challenging. With the Expo Modules API, we set out to build powerful tooling that would make building and maintaining these libraries easier.
<a id="take-advantage-of-modern-language-features"></a>
### 测试深层链接
¥Take advantage of modern language features
经过几年维护 Expo SDK 中的 50 多个原生模块，我们发现许多问题是由未处理的空值或不正确的类型引起的。现代语言功能可以帮助开发者避免这些错误；例如，可选类型的缺乏与 Objective-C 的动态性相结合，使得捕获某些类型的 bug 变得困难，而这些 bug 本来可以被 Swift 的编译器捕获。
¥After several years of maintaining over 50 native modules in the Expo SDK, we have discovered that many issues were caused by unhandled null values or incorrect types. Modern language features can help developers avoid these bugs; for example, the lack of optional types combined with the dynamism of Objective-C made it tough to catch certain classes of bugs that would have been caught by the compiler in Swift.
编写 React Native 模块的另一个困难是在每个平台上编写原生模块的截然不同的语言和范例之间进行上下文切换。由于这些平台之间的差异，无法完全避免。我们认为需要只有一个通用的 API 和文档来尽可能简化开发，并使单个开发者更容易在多个平台上维护库。
¥Another difficulty of writing React Native modules is context switching between the vastly different languages and paradigms for writing native modules on each platform. Due to the differences between these platforms, it cannot be avoided completely. We feel the need to have just one common API and documentation to simplify the development as much as possible and make it easier for a single developer to maintain a library on multiple platforms.
这就是 Expo Modules 生态系统从头开始设计用于现代母语的原因之一：Swift 和科特林。
¥This is one of the reasons why the Expo Modules ecosystem was designed from the ground up to be used with modern native languages: Swift and Kotlin.
<a id="make-it-easy-to-pass-data-between-runtimes"></a>
### 轻松在运行时之间传递数据
¥Make it easy to pass data between runtimes
Expo Modules API 完全了解原生函数所需的参数类型。它可以为你预先验证和转换参数，并且字典可以表示为我们称之为 [记录](/modules/module-api/#records) 的原生结构。
¥The Expo Modules API has full knowledge of the argument types the native function expects. It can pre-validate and convert the arguments for you, and dictionaries can be represented as native structs that we call [Records](/modules/module-api/#records).
我们旨在通过 API 解决的一个大痛点是验证从 JavaScript 传递给原生函数的参数。当涉及到 `NSDictionary` 或 `ReadableMap` 时，这尤其容易出错、耗时且难以维护，其中值的类型在运行时是未知的，并且每个属性都需要由开发者单独验证。
¥One big pain point we aimed to solve with the API is the validation of arguments passed from JavaScript to native functions. This is especially error-prone, time-consuming, and difficult to maintain when it comes to `NSDictionary` or `ReadableMap`, where the type of values is unknown in runtime, and each property needs to be validated separately by the developer.
知道参数类型后，还可以将 [自动转换参数](/modules/module-api/#convertibles) 转换为某些特定于平台的类型（例如，为了方便起见，可以将 `{ x: number, y: number }` 或 `[number, number]` 转换为 CoreGraphics 的 `CGPoint`）。
¥Knowing the argument types, it is also possible to [automatically convert arguments](/modules/module-api/#convertibles) to some platform-specific types (for example, `{ x: number, y: number }` or `[number, number]` can be translated to CoreGraphics's `CGPoint` for your convenience).
总之，Expo Modules 具有强大的内置和可扩展类型转换和类型安全。它支持自动原始值（例如，`Bool`/`Int`/`UInt`/`Float32`/`Double`/`Pair`/`String`）、复杂内置类型（例如，`URL`、`CGPoint`、`UIColor`、`Data`、`java.net.URL`、`android.graphics.Color`、`kotlin.ByteArray`）、记录（用户定义类型，如 `struct`/`Object`）和枚举。
¥In summary, Expo Modules has powerful built-in and extensible type conversion and type safety. It supports automatic of primitive values (for example, `Bool`/`Int`/`UInt`/`Float32`/`Double`/`Pair`/`String`), complex built-in types (for example, `URL`, `CGPoint`, `UIColor`, `Data`, `java.net.URL`, `android.graphics.Color`, `kotlin.ByteArray`), records (user defined types, like a `struct`/`Object`), and enums.
<a id="support-expressive-object-oriented-apis"></a>
### 支持新架构，同时保持向后兼容
¥Support expressive object-oriented APIs
将原生模块状态的真实来源保存在一个地方，而不是将其分散在 JavaScript 和原生中并自己进行相关的簿记。我们将此功能称为共享对象。例如，[`expo-sqlite` 数据库实例由共享对象支持](https://github.com/expo/expo/blob/718a9ac107231475ca4b2e6427317ade9d1e70fa/packages/expo-sqlite/src/SQLiteDatabase.ts#L421)。共享对象的详细文档即将推出。
¥Keep the source of truth for the state of your native module in one place, rather than spreading it across JavaScript and native and doing the associated book-keeping yourself. We call this feature **Shared Objects**. For example, [`expo-sqlite` database instances are backed by Shared Objects](https://github.com/expo/expo/blob/718a9ac107231475ca4b2e6427317ade9d1e70fa/packages/expo-sqlite/src/SQLiteDatabase.ts#L421). Detailed documentation for Shared Objects is coming soon.
<a id="provide-a-safe-and-composable-mechanism-to-hook-into-app-lifecycle-events"></a>
### 为你的应用发布签名更新
¥Provide a safe and composable mechanism to hook into app lifecycle events
[Android 生命周期监听器](/modules/android-lifecycle-listeners/) 和 [iOS AppDelegate 订阅者](/modules/appdelegate-subscribers/) 是一项强大的功能，可让你加入应用的生命周期，而无需将模块代码分散到 `MainActivity` 和 `AppDelegate` 类中，也不需要库的用户也这样做。这对于与 [持续的原生生成](/workflow/continuous-native-generation/) 的顺利集成特别有用，因为它为库提供了一种以可组合方式挂载到应用生命周期事件的机制 - 而不必担心其他库可能在做什么。
¥[Android lifecycle listeners](/modules/android-lifecycle-listeners/) and [iOS AppDelegate subscribers](/modules/appdelegate-subscribers/) are a powerful feature that allows you to hook into the lifecycle of your app, without needing to spread the code out for your module across your `MainActivity` and `AppDelegate` classes or require that users of your library do the same. This is particularly useful for smooth integration with [Continuous Native Generation](/workflow/continuous-native-generation/) because it provides libraries with a mechanism to hook into app lifecycle events in a composable way — without having to be concerned about what other libraries might be doing.
<a id="support-the-new-architecture-while-remaining-backwards-compatible"></a>
### 支持 格式
¥Support the New Architecture while remaining backwards compatible
React Native 0.68 版本引入了 [新架构](https://rn.nodejs.cn/docs/the-new-architecture/landing-page)，它为开发者提供了构建移动应用的新功能。它由名为 [涡轮增压模块](https://rn.nodejs.cn/docs/the-new-architecture/pillars-turbomodules) 的新原生模块系统和名为 [Fabric](https://rn.nodejs.cn/architecture/fabric-renderer) 的新渲染系统组成。本地库需要进行调整才能利用这些新系统。对于 Fabric 来说，它需要更多的工作，因为它不提供任何兼容性层，这意味着以旧方式编写的视图管理器不能与 Fabric 一起使用，反之亦然 — Fabric 原生组件不能与旧方式一起使用 渲染器。这基本上意味着现有的库必须在一段时间内为两种架构提供支持，从而增加了技术债务。
¥React Native version 0.68 introduced the [New Architecture](https://rn.nodejs.cn/docs/the-new-architecture/landing-page), which offers developers new capabilities for building mobile apps. It consists of the new native modules system called [Turbo Modules](https://rn.nodejs.cn/docs/the-new-architecture/pillars-turbomodules) and the new rendering system called [Fabric](https://rn.nodejs.cn/architecture/fabric-renderer).
Native libraries need to be adapted to take advantage of these new systems. For Fabric, it needs even more work as it doesn't provide any compatibility layer, which means that view managers written in the old way don't work with Fabric and the other way around — Fabric native components don't work with the old renderer. It basically implies that existing libraries have to provide support for both architectures for a while, increasing the technical debt.
新的架构主要是用 C++ 编写的，因此你最终可能还会为你的库编写一些 C++ 代码。由于我们都是 React Native 开发者，每天都使用高级 JavaScript，因此我们不太愿意编写 C++，因为它处于频谱的另一端。此外，在库中包含 C++ 代码会对构建时间产生负面影响，尤其是在 Android 上，并且可能更难以调试。
¥The new architecture is mostly written in C++, so you may end up writing some C++ code for your library as well. As we all React Native developers, use high-level JavaScript on a daily basis, we are rather reluctant to write C++, which is on the opposite side of the spectrum. Moreover, including C++ code in the library has a negative impact on build times, especially on Android, and can be more difficult to debug.
我们在设计 Expo Modules API 时考虑到了这些因素，目标是使其与渲染器无关，这样模块就不需要知道应用是否在新架构上运行，从而显着降低了成本 库开发者。
¥We took these into account when designing the Expo Modules API with the goal in mind to make it renderer-agnostic, so that the module doesn't need to know whether the app is run on the new architecture or not, significantly reducing the cost for library developers.


# 推送通知

## Expo 推送通知：概述

Expo 推送通知服务概述。

Expo 通过处理与 Firebase Cloud Messaging (FCM) 或 Apple Push Notification Service (APNs) 通信所涉及的大部分复杂性，简化了推送通知的实现。这允许你以相同的方式处理 Android 和 iOS 通知，并节省前端和后端的时间。
¥Expo simplifies implementing push notifications by handling much of the complexity involved in communicating with Firebase Cloud Messaging (FCM) or Apple Push Notification Service (APNs). This allows you to treat Android and iOS notifications in the same way and save time both on the front-end and back-end.
请按照以下视频或链接了解如何设置推送通知、发送它们以及处理应用中的传入通知。
¥Follow the video or links below to learn how to set up push notifications, send them, and handle incoming notifications in your app.
Video Tutorial: [Expo Notifications with EAS | Complete Guide](https://www.youtube.com/watch?v=BCCjGtKtBjE)


## 你需要了解的有关通知的信息

在开始之前，了解通知类型及其行为。

通知是一种警报，即使应用未处于活动状态，也会通知用户新的信息或事件。它们的覆盖范围很广，跨平台的差异可能会使通知的实现变得令人生畏。
¥Notifications are alerts that inform users of new information or events, even when the app isn't actively in use. They have a large surface area and differences across platforms can make implementing notifications intimidating.
无论你是刚开始使用通知还是已有相关知识，本文档都将解释不同类型的通知及其行为。
¥Whether you are starting with notifications or have existing knowledge, this document explains the different types of notification and their behaviors.
Expo 的通知支持建立在 Android 和 iOS 提供的原生功能之上。原生平台的相同概念和行为也适用于 Expo 应用。如果你不确定某个特定的通知功能，请参阅每个平台的 [官方文档](#external-references)。
¥Expo's notification support builds on top of the native functionality provided by Android and iOS. The same concepts and behaviors from native platforms apply to Expo apps. If you are unsure about a specific notification feature, see each platform's [official documentation](#external-references).
<a id="remote-and-local-notifications"></a>
## 远程和本地通知
¥Remote and Local notifications
1. 推送通知：（也称为 "远程通知"）从远程服务器发送到用户设备的通知。
   ¥**Push Notifications**: (also known as "remote notifications") Notifications that are sent to a user's device from a remote server.
2. 本地通知：（也称为 "应用内通知"）从应用内部创建和显示的通知。由于创建这些通知的许多 API 都会在特定时间创建它们，因此有时它们也可能被称为 "预定通知"。
   ¥**Local Notifications**: (also known as "in-app notifications") Notifications that are created and displayed from within the app. Since many of the APIs that create these notifications will create them at a particular time, these may also sometimes be called "scheduled notifications".
`expo-notifications` 支持推送和本地通知。你必须使用 [开发构建](/develop/development-builds/introduction/) 才能使用推送通知，因为 Expo Go 不内置此功能。
¥`expo-notifications` supports both push and local notifications. You must use a [development build](/develop/development-builds/introduction/) to use push notifications since the capability is not built into Expo Go.
查看 [应用内通知](/versions/latest/sdk/notifications/#present-a-local-in-app-notification-to-the-user) 了解如何创建和显示本地通知。本指南的其余部分重点介绍推送通知。
¥See [in-app notifications](/versions/latest/sdk/notifications/#present-a-local-in-app-notification-to-the-user) on how to create and display a local notification. The rest of this guide focuses on push notifications.
<a id="push-notification-delivery"></a>
## 推送通知传递
¥Push Notification delivery
当推送通知到达你的应用时，其行为取决于应用的状态和通知类型。让我们澄清一下术语：
¥When a push notification arrives to your app, its behavior depends on the app's state and the type of notification. Let's clarify the terminology:
<a id="application-states"></a>
### 应用状态
¥Application states
* 前台：应用正在前台积极运行。其界面当前正在屏幕上显示。
  ¥**Foreground**: The app is actively running in the foreground. Its interface is currently being displayed on the screen.
* 后台：应用正在后台运行，"minimized"。其界面当前未显示在屏幕上。
  ¥**Background**: The app is running in the background, "minimized". Its interface is not currently being displayed on the screen.
* 已终止：该应用是 "killed"，通常通过应用切换器中的滑动手势来实现。在 Android 上，如果用户从设备设置中强制停止应用，则必须手动重新打开它才能使通知开始工作（这是 Android 的限制）。
  ¥**Terminated**: The app was "killed", usually by a swipe-away gesture in the app switcher. On Android, if the user force-stops the app from device settings, it must be manually reopened for notifications to start working (this is a limitation of Android).
<a id="push-notification-behaviors"></a>
### 推送通知行为
¥Push Notification behaviors
对于任何类型的通知，当应用处于前台时，应用可以控制如何处理传入的通知。应用可能会直接显示它，显示一些自定义的应用内 UI，甚至忽略它（这由 [`NotificationHandler`](/versions/latest/sdk/notifications/#setnotificationhandlerhandler) 控制）。当应用不在前台时，行为取决于通知的类型。
¥For any kind of notification, when the app is in the foreground, the app is in control of how an incoming notification is handled. The app may present it directly, show some custom in-app UI, or even ignore it (this is controlled by [`NotificationHandler`](/versions/latest/sdk/notifications/#setnotificationhandlerhandler)). When the app is not in the foreground, the behavior depends on the type of notification.
下表总结了将推送通知发送到设备时发生的情况：
¥The table below summarizes what happens when a push notification is delivered to the device:
| 通知类型                                                                                                                                                                       | 前台应用                                                                                                                                                                                        | 后台应用                                                                        | 应用已终止                                                                       |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [通知消息](/push-notifications/what-you-need-to-know/#notification-message) 和 [带有数据负载的通知消息](/push-notifications/what-you-need-to-know/#notification-message-with-data-payload) | 交付运行 [`NotificationReceivedListener`](/versions/latest/sdk/notifications/#addnotificationreceivedlistenerlistener) 和 [JS 任务](/versions/latest/sdk/notifications/#registertaskasynctaskname) | 操作系统显示通知                                                                    | 操作系统显示通知                                                                    |
| [无头后台通知](/push-notifications/what-you-need-to-know/#headless-background-notifications)                                                                                     | 交付运行 [`NotificationReceivedListener`](/versions/latest/sdk/notifications/#addnotificationreceivedlistenerlistener) 和 [JS 任务](/versions/latest/sdk/notifications/#registertaskasynctaskname) | 交付运行 [JS 任务](/versions/latest/sdk/notifications/#registertaskasynctaskname) | 交付运行 [JS 任务](/versions/latest/sdk/notifications/#registertaskasynctaskname) |
对于用户与通知交互的情况（例如，按下操作按钮），你可以使用以下处理程序。
¥For the cases when the user interacts with the notification (for example, by pressing an action button), the following handlers are made available to you.
| 应用状态 | iOS 监听器已触发                             | 已触发 Android 监听器                                                                                                 |
| ---- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 前景   | `NotificationResponseReceivedListener` | `NotificationResponseReceivedListener`                                                                          |
| 背景   | `NotificationResponseReceivedListener` | `NotificationResponseReceivedListener` 和 [JS 任务](/versions/latest/sdk/notifications/#registertaskasynctaskname) |
| 已终止  | `NotificationResponseReceivedListener` | [JS 任务](/versions/latest/sdk/notifications/#registertaskasynctaskname)                                          |
在上表中，每当触发 `NotificationResponseReceivedListener` 时，`useLastNotificationResponse` 的返回值也会发生变化。
¥In the table above, whenever `NotificationResponseReceivedListener` is triggered, also `useLastNotificationResponse` return value would change.
>  **info** 当应用未运行或已终止，并通过点击通知启动时，应尽早注册 `NotificationResponseReceivedListener`（模块顶层），以便在 iOS 上触发。对于将应用置于前台的操作按钮，我们建议在应用启动后使用 `useLastNotificationResponse` 或 `getLastNotificationResponseAsync` 捕获响应。
>
> ¥When the app is not running or killed and is started by tapping on a notification, the `NotificationResponseReceivedListener` should be registered early (module top-level) to be triggered on iOS. For action buttons that bring the app to the foreground, we recommend to capture the response using `useLastNotificationResponse` or `getLastNotificationResponseAsync` after the app starts.
<a id="push-notification-types"></a>
## 推送通知类型
¥Push Notification types
<a id="notification-message"></a>
### 通知消息
¥Notification Message
通知消息是一种指定演示信息（例如标题或正文）的通知。
¥A Notification Message is a notification that specifies presentational information, such as a title or body text.
* 在 Android 上，这对应于包含 [`AndroidNotification`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidNotification) 的推送通知请求
  ¥On Android, this corresponds to a push notification request that contains [`AndroidNotification`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidNotification)
* 在 iOS 上，这对应于包含 [`aps.alert` dictionary](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Create-the-JSON-payload) 和设置为 `alert` 的 `apns-push-type` 标头的推送通知请求。
  ¥On iOS, this corresponds to a push notification request that contains [`aps.alert` dictionary](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Create-the-JSON-payload) and the `apns-push-type` header set to `alert`.
当你使用 Expo 推送服务并指定 `title`、`subtitle`、`body`、`icon` 或 `channelId` 时，生成的推送通知请求是通知消息。
¥When you use the Expo Push Service, and specify `title`, `subtitle`, `body`, `icon`, or `channelId`, the resulting push notification request is a Notification Message.
[//]: # "TODO vonovak clarify what fields make a notification to be considered a Notification Message"
通知消息的典型用例是立即将其渲染给用户，而无需进行任何额外处理。
¥The typical use case for a Notification Message is to have it presented to the user immediately without any extra processing being done.
<a id="notification-message-with-data-payload"></a>
### 带有数据负载的通知消息
¥Notification Message with data payload
这是一个仅适用于 Android 的术语 ([查看官方文档](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages))，其中推送通知请求包含 `data` 字段和 `notification` 字段。
¥This is an Android-only term ([see the official docs](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages)) where a push notification request contains both `data` field and a `notification` field.
在 iOS 上，额外数据可能是常规通知消息请求的一部分。Apple 不区分携带和不携带数据的通知消息。
¥On iOS, extra data may be part of a regular Notification Message request. Apple doesn't distinguish between Notification Message which does and does not carry data.
<a id="headless-background-notifications"></a>
### 无头后台通知
¥Headless Background Notifications
无头通知是一种远程通知，它不直接指定标题或正文等展示信息。除了以下* 例外，无头通知不会渲染给用户。相反，它们携带数据（JSON），这些数据由通过 [`registerTaskAsync`](/versions/latest/sdk/notifications/#registertaskasynctaskname) 在你的应用中定义的 JavaScript 任务处理。任务可以执行任意逻辑。例如，写入 `AsyncStorage`，发出 api 请求，或显示其内容取自推送通知数据的本地通知。
¥Headless Notification is a remote notification that doesn't directly specify presentational information such as the title or body text. With the exception below*, headless notifications are not presented to users. Instead, they carry data (JSON) which is processed by a JavaScript task defined in your app via [`registerTaskAsync`](/versions/latest/sdk/notifications/#registertaskasynctaskname). The task may perform arbitrary logic. For example, write to `AsyncStorage`, make an api request, or present a local notification whose content is taken from the push notification's data.
>  **info** 我们使用术语 "无头后台通知" 来指代 Android 上的 [数据消息](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) 和 iOS 上的 [后台通知](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#Create-a-background-notification)。它们的主要相似之处在于这两种通知类型都允许仅发送 JSON 数据，并由应用进行后台处理。
>
> ¥We use the term "Headless Background Notification" to refer to the [Data Message](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) on Android and the [background notification](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#Create-a-background-notification) on iOS. Their key similarities are that both of these notification types allow sending only JSON data, and background processing by the app.
无头后台通知能够运行自定义 JavaScript 来响应通知，即使应用已终止。这很强大，但有一个限制：即使通知已传送到设备，操作系统也不能保证将其传送到你的应用。这可能由于多种原因而发生，例如在 Android 上启用 [休眠模式](https://developer.android.com/training/monitoring-device-state/doze-standby) 时，或者当你发送太多后台通知时 - Apple 建议不要启用 [发送超过两三个小时](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#overview)。
¥Headless Background Notifications have the ability to run custom JavaScript in response to a notification *even when the app is terminated*. This is powerful but comes with a limitation: even when the notification is delivered to the device, the OS does not guarantee its delivery to your app. This may happen due to a variety of reasons, such as when [Doze mode](https://developer.android.com/training/monitoring-device-state/doze-standby) is enabled on Android, or when you send too many background notifications — Apple recommends not to [send more than two or three per hour](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#overview).
当你使用 Expo 推送服务并仅指定 `data` 和 `_contentAvailable: true`（以及其他非交互式字段，如 `ttl`）时，生成的推送通知请求会产生无头背景通知。
¥When you use the Expo Push Service, and specify only `data` and `_contentAvailable: true` (and other non-interactive fields such as `ttl`), the resulting push notification request produces a Headless Background Notification.
[//]: # "TODO vonovak clarify how setting priority behaves here, because apns-priority field should be 5 on iOS but can be specified on Android"
> 要在 iOS 上使用无头后台通知，你必须先对其进行 [configure](/versions/latest/sdk/notifications/#background-notification-configuration) 操作。
>
> ¥To use Headless Background Notifications on iOS, you have to [configure](/versions/latest/sdk/notifications/#background-notification-configuration) them first.
经验法则是，如果你不需要在后台运行 JavaScript，则最好使用常规通知消息。
¥The rule of thumb is to prefer a regular Notification Message if you don't require running JavaScript in the background.
* 例外情况是当你在 [`data`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidConfig) 中指定 `title` 或 `message` 时。在这种情况下，`expo-notifications` 包会自动在 Android 上显示无头通知，但不会在 iOS 上显示。我们计划在未来的版本中使此行为在各个平台上更加一致。
¥* The exception is when you specify `title` or `message` inside of [`data`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidConfig). In that case, `expo-notifications` package automatically presents the headless notification on Android, but not on iOS. We plan to make this behavior more consistent across platforms in a future release.
<a id="data-only-notifications"></a>
### 仅数据通知
¥Data-only notifications
Android 有 [数据消息](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) 的概念。iOS 没有完全相同的概念，但与之相近的概念是 [无头后台通知](#headless-background-notifications)。
¥Android has a concept of [Data Messages](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages). iOS does not have exactly the same concept, but a close equivalent is [Headless Background Notifications](#headless-background-notifications).
你可能还会遇到术语 "静默通知"，这是不向用户显示任何内容的通知的另一个名称 - 我们将其描述为 [无头后台通知](#headless-background-notifications)。
¥You may also come across the term "silent notification", which is yet another name for notifications that don't present anything to the user — we describe these as [Headless Background Notifications](#headless-background-notifications).
<a id="external-references"></a>
## 外部参考
¥External references
这是 Android 和 iOS 上推送通知的官方资源的非详尽列表：
¥This is a non-exhaustive list of official resources for push notifications on Android and iOS:
* [安卓 - 关于 FCM 消息](https://firebase.google.com/docs/cloud-messaging/concept-options)
  ¥[Android - About FCM messages](https://firebase.google.com/docs/cloud-messaging/concept-options)
* [iOS 系统 - 生成远程通知](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)
  ¥[iOS - Generating a remote notification](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)
* [iOS 系统 - 将后台更新推送到你的应用](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app)
  ¥[iOS - Pushing background updates to your app](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app)


## Expo 推送通知设置

了解如何设置推送通知、获取开发和生产凭据以及发送测试推送通知。

要使用 Expo 推送通知服务，你必须通过安装一组库来配置你的应用，实现处理通知的函数，并为 Android 和 iOS 设置凭据。
¥To utilize Expo push notification service, you must configure your app by installing a set of libraries, implement functions to handle notifications, and set up credentials for Android and iOS.
完成本指南中概述的步骤或按照下面更详细的视频进行操作。最后，你将能够发送推送通知并在设备上接收它。
¥Complete the steps outlined in this guide or follow the more detailed video below. At the end, you'll be able to send a push notification and receive it on a device.
Video Tutorial: [Expo Notifications with EAS | Complete Guide](https://www.youtube.com/watch?v=BCCjGtKtBjE)
要让客户端准备好推送通知，需要执行以下操作：
¥To get the client-side ready for push notifications, the following things are required:
* 用户向其发送推送通知的权限。
  ¥The user's permission to send them push notifications.
* 应用的 [`ExpoPushToken`](/versions/latest/sdk/notifications/#expopushtoken)。
  ¥The app's [`ExpoPushToken`](/versions/latest/sdk/notifications/#expopushtoken).
Note: Do you want to use FCM / APNs directly, instead of the Expo push notification service?
---
If you need finer-grained control over your notifications, communicating directly with FCM and APNs may be necessary. Expo does not lock you into using Expo Application Services, and the `expo-notifications` API is push-service agnostic. Learn how to ["Send notifications with FCM and APNs"](/push-notifications/sending-notifications-custom/).
---
## Prerequisites
> **warning** **Important:** Push notifications are not supported on Android Emulators and iOS Simulators. A real device is required.
The following steps described in this guide use [EAS Build](/build/introduction/). This is the easiest way to set up notifications since your EAS project will also contain the [notification credentials](#get-credentials-for-development-builds). However, you can use the `expo-notifications` library without EAS Build by building [your project locally](/guides/local-app-development/).
Step 1: 
## Install libraries
Run the following command to install the `expo-notifications`, `expo-device` and `expo-constants` libraries:
```sh
$ npx expo install expo-notifications expo-device expo-constants
```
- [`expo-notifications`](/versions/latest/sdk/notifications) library is used to request a user's permission and to obtain the `ExpoPushToken` for sending push notifications.
- [`expo-device`](/versions/latest/sdk/device) is used to check whether the app is running on a physical device.
- [`expo-constants`](/versions/latest/sdk/constants) is used to get the `projectId` value from the app config.
Step 2: 
## Add a minimal working example
The code below shows a working example of how to register for, send, and receive push notifications in a React Native app. Copy and paste it into your project:
!!!IG0!!!
### Configure `projectId`
Using the previous example, when you are registering for push notifications, you need to use [`projectId`](/versions/latest/sdk/constants/#easconfig). This property is used to attribute Expo push token to the specific project. For projects using EAS, the `projectId` property represents the Universally Unique Identifier (UUID) of that project.
`projectId` is set automatically when you create a development build. However, **we recommend setting it manually in your project's code**. To do so, you can use [`expo-constants`](/versions/latest/sdk/constants/) to get the `projectId` value from the app config.
!!!IG1!!!
One advantage of attributing the Expo push token to your project's ID is that it doesn't change when a project is transferred between different accounts or the existing account gets renamed.
Step 3: 
## Get credentials for development builds
For Android and iOS, there are different requirements to set up your credentials.
!!!IG2!!!
!!!IG3!!!
    For Android, you need to configure **Firebase Cloud Messaging (FCM)** to get credentials and set up your Expo project.
    Follow the steps in [Add Android FCM V1 credentials](/push-notifications/fcm-credentials) to set up your credentials.
!!!IG4!!!
!!!IG5!!!
    > **warning** A paid Apple Developer Account is required to generate credentials.
    For iOS, make sure you have [registered your iOS device](/develop/development-builds/create-a-build/#create-a-development-build-for-the-device) on which you want to test before running the `eas build` command for the first time.
    If you create a development build for the first time, you'll be asked to enable push notifications. Answer yes to the following questions when prompted by the EAS CLI:
    - Setup Push Notifications for your project
    - Generating a new Apple Push Notifications service key
!!!IG6!!!
!!!IG7!!!
> If you are not using EAS Build, run `eas credentials` manually.
Step 4: 
## Build the app
```sh
$ eas build
```
Step 5: 
## Test using the push notifications tool
After creating and installing the development build, you can use [Expo push notifications tool](https://expo.dev/notifications) to quickly send a test notification to your device.
1. Start the development server for your project:
   ```sh
$ npx expo start
```
2. Open the development build on your device.
3. After the `ExpoPushToken` is generated, enter the value in the Expo push notifications tool with other details (for example, a message title and body).
4. Click on the **Send a Notification** button.
After sending the notification from the tool, you should see the notification on your device. Below is an example of an Android device receiving a push notification.


## 使用 Expo Push Service 发送通知

了解如何调用 Expo Push Service API 从你的服务器发送推送通知。

[`expo-notifications`](/versions/latest/sdk/notifications) 库提供推送通知的所有客户端功能。Expo 还负责将推送通知发送到 FCM 和 APN，然后将其发送到特定设备。你需要做的就是使用通过 [`getExpoPushTokenAsync`](/versions/latest/sdk/notifications/#getexpopushtokenasyncoptions) 获得的 `ExpoPushToken` 向 Expo Push API 发送请求。
¥The [`expo-notifications`](/versions/latest/sdk/notifications) library provides all the client-side functionality for push notifications. Expo also handles sending push notifications off to FCM and APNs which then send them to particular devices. All you need to do is send a request to Expo Push API with the `ExpoPushToken` you obtain with [`getExpoPushTokenAsync`](/versions/latest/sdk/notifications/#getexpopushtokenasyncoptions).
> 如果你希望构建直接与 APN 和 FCM 通信的服务器，请参阅 [使用 FCM 和 APN 发送通知](/push-notifications/sending-notifications-custom/)。它比使用 Expo Push Service 更复杂，但允许更细粒度的控制，并可以完全访问所有 FCM 和 APNs 功能。
>
> ¥If you'd rather build a server that communicates with APNs and FCM directly, see [Send notifications with FCM and APNs](/push-notifications/sending-notifications-custom/). It's more complex than using Expo Push Service, but allows finer-grained control, and full access to all FCM and APNs features.
<a id="send-push-notifications-using-a-server"></a>
## 使用服务器发送推送通知
¥Send push notifications using a server
设置推送通知凭据并添加逻辑以获取 `ExpoPushToken` 后，你可以使用 HTTPS POST 请求将其发送到 Expo API。你可以通过设置带有数据库的服务器来完成此操作（或者你也可以编写命令行工具来发送它们或直接从你的应用发送它们）。
¥After you setup your push notification credentials and add logic to get the `ExpoPushToken`, you can send it to the Expo API using an HTTPS POST request. You can do this by setting up a server with a database (or you can also write a command line tool to send them or send them straight from your app).
Expo 团队和社区已经用几种不同的语言为你创建了后端：
¥The Expo team and community have taken care of creating back-ends for you in a few different languages:
| SDKs                                                                                                     | 后端      | 维护者     |
| -------------------------------------------------------------------------------------------------------- | ------- | ------- |
| [expo-server-sdk-node](https://github.com/expo/expo-server-sdk-node)                                     | Node.js | Expo 团队 |
| [expo-server-sdk-python](https://github.com/expo/expo-server-sdk-python)                                 | Python  | 社区      |
| [expo-server-sdk-ruby](https://github.com/expo/expo-server-sdk-ruby)                                     | Ruby    | 社区      |
| [expo-push-notification-client-rust](https://github.com/katayama8000/expo-push-notification-client-rust) | Rust    | 社区      |
| [expo-notifier](https://github.com/symfony/expo-notifier)                                                | 交响乐团    | 交响乐团    |
| [exponent-server-sdk-php](https://github.com/Alymosul/exponent-server-sdk-php)                           | PHP     | 社区      |
| [expo-server-sdk-php](https://github.com/ctwillie/expo-server-sdk-php)                                   | PHP     | 社区      |
| [exponent-server-sdk-golang](https://github.com/oliveroneill/exponent-server-sdk-golang)                 | Golang  | 社区      |
| [exponent](https://github.com/9ssi7/exponent)                                                            | Golang  | 社区      |
| [exponent-server-sdk-elixir](https://github.com/rdrop/exponent-server-sdk-elixir)                        | 灵丹妙药    | 社区      |
| [expo-server-sdk-dotnet](https://github.com/glyphard/expo-server-sdk-dotnet)                             | dotnet  | 社区      |
| [expo-server-sdk-java](https://github.com/hlspablo/expo-server-sdk-java)                                 | Java    | 社区      |
| [laravel-expo-notifier](https://github.com/YieldStudio/laravel-expo-notifier)                            | 拉维尔     | 社区      |
上面的每个示例服务器都是 Expo Push Service API 的封装器。
¥Each of the example servers above is a wrapper around Expo Push Service API.
<a id="implement-push-notifications-reliably"></a>
## 可靠地实现推送通知
¥Implement push notifications reliably
推送通知通过多个系统从服务器传输到接收设备。大部分时间都会发送通知。但是，偶尔会出现系统及其之间的网络连接问题。处理错误有助于推送通知更可靠地到达目的地。
¥Push Notifications travel through several systems from your server to recipient devices. Notifications are delivered most of the time. However, occasionally there are issues with systems along the way and the network connections between them. Handling errors helps push notifications to arrive at their destinations more reliably.
<a id="limit-concurrent-connections"></a>
### 限制并发连接数
¥Limit concurrent connections
一次发送大量推送通知时，请限制并发连接数。[节点 SDK](https://github.com/expo/expo-server-sdk-node) 为你实现了这一点，并打开最多六个并发连接。这可以平滑你的峰值负载并帮助 Expo 推送通知服务成功接收推送通知请求。
¥When sending a large number of push notifications at once, limit the number of your concurrent connections. The [Node SDK](https://github.com/expo/expo-server-sdk-node) implements this for you and opens a maximum of six concurrent connections. This smooths out your peak load and helps the Expo push notification service receive push notification requests successfully.
<a id="retry-on-failure"></a>
### 失败重试
¥Retry on failure
发送推送通知的第一步是将它们传递给 Expo 推送通知服务，该服务在内部将它们添加到队列中以传递给 Google (FCM v1) 和 Apple (APNs)。第一步可能会因以下几个原因而失败：
¥The first step in sending push notifications is to deliver them to the Expo push notification service, which internally adds them to a queue for delivery to Google (FCM v1) and Apple (APNs). This first step can fail for several reasons:
* 你的服务器和 Expo 推送通知服务之间的网络问题
  ¥network issues between your server and the Expo push notification service
* Expo 通知服务中断或可用性下降
  ¥an outage or degraded availability of the Expo notification service
* 推送凭据配置错误
  ¥misconfigured push credentials
* 无效的通知负载
  ¥an invalid notification payload
其中一些失败是暂时的。例如，如果 Expo 推送通知服务已关闭或无法访问，并且你收到网络错误 - HTTP 429 错误（太多请求）或 HTTP 5xx 错误（服务器错误） - 使用 [指数退避](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) 等待几秒钟后再重试。如果第一次重试尝试不成功，请等待更长时间（遵循指数退避），然后重试。这可以让暂时不可用的服务在你重试之前恢复。
¥Some of these failures are temporary. For example, if the Expo push notification service is down or unreachable and you get a network error - a HTTP 429 error (Too Many Requests), or a HTTP 5xx error (Server Errors) - use [exponential backoff](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) to wait a few seconds before retrying. If the first retry attempt is unsuccessful, wait for longer (follow exponential backoff) and retry again. This lets the temporarily unavailable service recover before you retry.
其他故障不会自行解决。例如，如果你的推送通知负载格式错误，你可能会收到 HTTP 400 响应，解释负载的问题。如果你的项目没有推送凭据，或者你在同一请求中发送不同项目的推送通知，你也会收到错误消息。
¥Other failures will not resolve themselves. For example, if your push notification payload is malformed, you may get an HTTP 400 response explaining the issue with the payload. You will also get an error if there are no push credentials for your project or if you send push notifications for different projects in the same request.
<a id="check-push-receipts-for-errors"></a>
### 检查推送收据是否有错误
¥Check push receipts for errors
成功接收通知后，Expo 推送通知服务会响应 [**推票**](#push-tickets)。推送票证表明 Expo 已收到你的通知负载，但可能仍需要发送。每个推送票证都包含一个票证 ID，稍后你可以使用该 ID 来查找 [推送收据](#push-receipts)。Expo 尝试将通知传递给 FCM 或 APN 后，即可获得推送回执。它告诉你是否已成功发送到推送通知提供商。
¥The Expo push notification service responds with [**push tickets**](#push-tickets) upon successfully receiving notifications. A push ticket indicates that Expo has received your notification payload but may still need to send it. Each push ticket contains a ticket ID, which you later use to look up a [push receipt](#push-receipts). A push receipt is available after Expo has tried to deliver the notification to FCM or APNs. It tells you whether delivery to the push notification provider was successful.
你必须检查你的推送收据。如果推送通知出现问题，推送收据是获取根本原因信息的最佳方式。例如，收据可能表明 FCM 或 APN、Expo 推送通知服务或你的通知负载存在问题。
¥You must check your push receipts. If there is an issue delivering push notifications, the push receipts are the best way to get information about the underlying cause. For example, the receipts may indicate a problem with FCMs or APNs, the Expo push notification service, or your notification payload.
如果 APNs 或 FCM 响应该信息，推送回执还可能告诉你接收设备是否已取消订阅通知（例如，通过撤销通知权限或卸载你的应用）。推送收据将包含设置为 `DeviceNotRegistered` 的 `details` → `error` 字段。在这种情况下，请停止向该设备的推送令牌发送通知，直到它重新注册到你的服务器，这样你的应用仍然是一个好公民。仅当 Google 或 Apple 认为设备未注册时，`DeviceNotRegistered` 错误才会出现在推送回执中。这需要不确定的时间，并且通常无法通过卸载应用并在不久后发送推送通知来进行测试。
¥Push receipts may also tell you if a recipient device has unsubscribed from notifications (for example, by revoking notification permissions or uninstalling your app) if APNs or FCM responds with that information. The push receipt will contain a `details` → `error` field set to `DeviceNotRegistered`. In this scenario, stop sending notifications to this device's push token until it re-registers with your server, so your app remains a good citizen. The `DeviceNotRegistered` error appears in push receipts only when Google or Apple deems the device to be unregistered. It takes an undefined amount of time and is often impossible to test by uninstalling your app and sending a push notification shortly after.
我们建议你在发送推送通知 15 分钟后检查推送收据。虽然推送收据通常可以更快获得，但 15 分钟的窗口期为 Expo 推送通知服务提供了足够的时间来向你提供收据。如果 15 分钟后没有推送回执，则可能表示 Expo 推送通知服务出现错误。最后，推送收据将在 24 小时后清除。
¥We recommend checking push receipts 15 minutes after sending your push notifications. While push receipts are often available much sooner, a 15-minute window gives the Expo push notification service a comfortable amount of time to make the receipts available to you. If after 15 minutes there is no push receipt, this likely indicates an error with the Expo push notification service. Lastly, push receipts are cleared after 24 hours.
<a id="slas"></a>
### SLAs
Expo 推送通知服务没有 SLA，FCM 和 APNs 服务也可能偶尔出现中断。通过遵循上述指导，你可以使你的应用能够抵御临时服务中断。
¥The Expo push notification service does not have an SLA and the FCM and APNs services also may have occasional outages. By following the guidance above, you can make your application robust against temporary service interruptions.
<a id="http2-api"></a>
## HTTP/2 API
你可能希望直接向我们的 HTTP/2 API 发送请求（此 API 目前不需要任何身份验证），而不是使用前面列出的库之一。
¥Instead of using one of the libraries listed earlier, you may want to send requests directly to our HTTP/2 API (this API currently does not require any authentication).
为此，请使用以下 HTTP 标头向 `https://exp.host/--/api/v2/push/send` 发送 POST 请求：
¥To do so, send a POST request to `https://exp.host/--/api/v2/push/send` with the following HTTP headers:
```text
host: exp.host
accept: application/json
accept-encoding: gzip, deflate
content-type: application/json
```
这是使用 cURL 的 "你好世界" 推送通知，你可以使用终端发送（将占位符推送令牌替换为你自己的）：
¥This is a "hello world" push notification using cURL that you can send using your terminal (replace the placeholder push token with your own):
```sh
curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/send" -d '{
  "to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "title":"hello",
  "body": "world"
}'
```
请求正文必须是 JSON。它可以是单个 [消息对象](#message-request-format)（如上例所示），也可以是最多 100 个消息对象的数组，只要它们都用于同一项目，如下所示。当你想要发送多条消息时，我们建议你使用数组，以有效地减少需要向 Expo 服务器发出的请求数量。以下是发送四条消息的请求正文示例：
¥The request body must be JSON. It may either be a single [message object](#message-request-format) (as shown in the example above) or an array of up to 100 message objects, as long as they are all for the same project as shown below. **We recommend using an array when you want to send multiple messages to efficiently minimize the number of requests you need to make to Expo servers.** Here's an example request body that sends four messages:
```json
[
  {
    "to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
    "sound": "default",
    "body": "Hello world!"
  },
  {
    "to": "ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]",
    "badge": 1,
    "body": "You've got mail"
  },
  {
    "to": [
      "ExponentPushToken[zzzzzzzzzzzzzzzzzzzzzz]",
      "ExponentPushToken[aaaaaaaaaaaaaaaaaaaaaa]"
    ],
    "body": "Breaking news!"
  }
]
```
Expo Push Service 还可以选择接受 gzip 压缩的请求主体。这可以大大减少发送大量通知所需的上传带宽量。[节点 Expo 服务器 SDK](https://github.com/expo/expo-server-sdk-node) 会自动为你压缩请求并自动限制你的请求以平滑负载，因此我们强烈推荐它。
¥The Expo Push Service also optionally accepts gzip-compressed request bodies. This can greatly reduce the amount of upload bandwidth needed to send large numbers of notifications. The [Node Expo Server SDK](https://github.com/expo/expo-server-sdk-node) automatically gzips requests for you and automatically throttles your requests to smooth out the load, so we highly recommend it.
<a id="push-tickets"></a>
### 推票
¥Push tickets
上述请求将使用带有两个可选字段 `data` 和 `errors` 的 JSON 对象进行响应。`data` 将包含一个 [**推票**](#push-ticket-format) 数组，其顺序与消息发送的顺序相同（或者一个推送票据对象，如果你向单个收件人发送一条消息）。每张票证都包含一个 `status` 字段，指示 Expo 是否成功收到通知，如果成功，还包含一个 `id` 字段，可用于稍后检索推送收据。
¥The requests above will respond with a JSON object with two optional fields, `data` and `errors`. `data` will contain an array of [**push tickets**](#push-ticket-format) in the same order in which the messages were sent (or one push ticket object, if you send a single message to a single recipient). Each ticket includes a `status` field indicating whether Expo successfully received the notification and, if successful, an `id` field that can be used to retrieve a push receipt later.
> 状态 `ok` 和收据 ID 意味着该消息是由 Expo 的服务器接收的，而不是由用户接收的（为此，你需要检查 [推送收据](#push-receipts)）。
>
> ¥A status of `ok` along with a receipt ID means that the message was received by Expo's servers, **not** that it was received by the user (for that you will need to check the [push receipt](#push-receipts)).
继续上面的示例，成功的响应正文如下所示：
¥Continuing the above example, this is what a successful response body looks like:
```json
{
  "data": [
    { "status": "ok", "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" },
    { "status": "ok", "id": "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY" },
    { "status": "ok", "id": "ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ" },
    { "status": "ok", "id": "AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA" }
  ]
}
```
如果个别消息有错误，但不是整个请求有错误，则错误消息对应的推送票证的状态将为 `error`，并且描述错误的字段如下所示：
¥If there were errors with individual messages, but not the entire request, the bad messages' corresponding push tickets will have a status of `error`, and fields that describe the error as shown below:
```json
{
  "data": [
    {
      "status": "error",
      "message": "\"ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]\" is not a registered push notification recipient",
      "details": {
        "error": "DeviceNotRegistered"
      }
    },
    {
      "status": "ok",
      "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
  ]
}
```
如果整个请求失败，HTTP 状态代码为 4xx 或 5xx，`errors` 字段将是一个错误对象数组（通常只有一个）。否则，HTTP 状态代码将为 200，并且你的消息将发送至 Android 和 iOS 推送通知服务。
¥If the entire request failed, the HTTP status code is 4xx or 5xx and the `errors` field will be an array of error objects (usually just one). Otherwise, the HTTP status code will be 200 and your messages will be on their way to the Android and iOS push notification services.
<a id="push-receipts"></a>
### 推送收据
¥Push receipts
收到一批通知后，Expo 将每个通知放入队列以传送到 Android 和 iOS 推送通知服务（分别为 FCM 和 APN）。大多数通知通常会在几秒钟内发送。但是，有时可能需要更长时间才能发送通知，特别是如果 Android 或 iOS 推送通知服务比平时花费更长的时间来接收和发送通知，或者 Expo 的推送服务基础设施处于高负载状态。
¥After receiving a batch of notifications, Expo enqueues each notification to deliver to the Android and iOS push notification services (FCM and APNs, respectively). Most notifications are typically delivered within a few seconds. However, sometimes it may take longer to deliver notifications, particularly if the Android or iOS push notification services take longer than usual to receive and deliver notifications or if Expo's Push Service infrastructure is under high load.
一旦 Expo 将通知发送到 Android 或 iOS 推送通知服务，Expo 就会创建一个 [**推送收据**](#push-receipt-response-format) 来指示 Android 或 iOS 推送通知服务是否成功接收到该通知。如果在发送通知时出现错误（可能是由于凭据错误或服务停机），推送回执将包含有关该错误的更多信息。
¥Once Expo delivers a notification to the Android or iOS push notification service, Expo creates a [**push receipt**](#push-receipt-response-format) that indicates whether the Android or iOS push notification service successfully received the notification. If there was an error in delivering the notification, perhaps due to faulty credentials or service downtime, the push receipt will contain more information regarding that error.
要获取推送收据，请向 `https://exp.host/--/api/v2/push/getReceipts` 发送 POST 请求。[请求正文](#push-receipt-request-format) 必须是一个 JSON 对象，其字段名称 `ids` 是票证 ID 字符串的数组：
¥To fetch the push receipts, send a POST request to `https://exp.host/--/api/v2/push/getReceipts`. The [request body](#push-receipt-request-format) must be a JSON object with a field name `ids` that is an array of ticket ID strings:
```sh
curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/getReceipts" -d '{
  "ids": [
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY",
    "ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ"
  ]
}'
```
推送收据的 [响应体](#push-receipt-response-format) 与推送票据的 [响应体](#push-receipt-response-format) 非常相似；它是一个 JSON 对象，具有两个可选字段 `data` 和 `errors`。`data` 包含收据 ID 到收据的映射。收据包括一个 `status` 字段以及两个可选的 `message` 和 `details` 字段（在 `"status": "error"` 的情况下）。如果所请求的收据 ID 没有推送收据，则映射将不包含该 ID。对上述请求的成功响应如下所示：
¥The [response body](#push-receipt-response-format) for push receipts is very similar to that of push tickets; it is a JSON object with two optional fields, `data` and `errors`. `data` contains a mapping of receipt IDs to receipts. Receipts include a `status` field, and two optional `message` and `details` fields (in the case where `"status": "error"`). If there is no push receipt for a requested receipt ID, the mapping won't contain that ID. This is what a successful response to the above request looks like:
```json
{
  "data": {
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": { "status": "ok" },
    "ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ": { "status": "ok" }
    // When there is no receipt with a given ID (YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY in this
    // example), the ID is omitted from the response.
  }
}
```
你必须检查每个推送收据，因为它可能包含有关你需要解决的错误的信息。例如，如果设备不再有资格接收通知，Apple 的文档会要求你停止向该设备发送通知。推送回执包含有关这些错误的信息。
¥**You must check each push receipt, since it may contain information about errors you need to resolve.** For example, if a device is no longer eligible to receive notifications, Apple's documentation asks that you stop sending notifications to that device. The push receipts contain information about these errors.
> 即使收据的 `status` 表示 `ok`，这也不能保证设备已收到该消息；推送回执中的 "ok" 表示 Android (FCM) 或 iOS (APNs) 推送通知服务已成功收到通知。例如，如果接收方设备已关闭，iOS 或 Android 推送通知服务将尝试传递消息，但设备不一定会收到该消息。
>
> ¥Even if a receipt's `status` says `ok`, this doesn't guarantee that the device has received the message; "ok" in a push receipt means that the Android (FCM) or iOS (APNs) push notification service successfully received the notification. If the recipient device is turned off, for example, the iOS or Android push notification service will try to deliver the message but the device won't necessarily receive it.
如果整个请求失败，HTTP 状态代码将为 4xx 或 5xx，`errors` 字段将是一组错误对象（通常只有一个）。否则，HTTP 状态代码将为 200，并且你的消息将发送至用户的设备。
¥If the entire request failed, the HTTP status code will be 4xx or 5xx and the `errors` field will be an array of error objects (usually just one). Otherwise, the HTTP status code will be 200 and your messages will be on their way to your users' devices.
<a id="errors"></a>
## 错误
¥Errors
Expo 提供了有关整个过程中发生的任何错误的详细信息。我们将在下面介绍一些最常见的错误，以便你可以在服务器上实现自动处理这些错误的逻辑。
¥Expo provides details regarding any errors that occur during this entire process. We'll cover some of the most common errors below so that you can implement logic to handle them automatically on your server.
如果出于某种原因，Expo 无法将消息传送到 Android 或 iOS 推送通知服务，则推送收据的详细信息还可能包括特定于服务的信息。这主要用于调试并向 Expo 报告可能的错误。
¥If for whatever reason, Expo couldn't deliver the message to the Android or iOS push notification service, the push receipt's details may also include service-specific information. This is useful mostly for debugging and reporting possible bugs to Expo.
<a id="individual-errors"></a>
### 个别错误
¥Individual errors
在推送票证和推送收据中，查找带有 `error` 字段的 `details` 对象。如果存在，它可能是以下值之一，你应该像这样处理这些错误：
¥Inside both push tickets and push receipts, look for a `details` object with an `error` field. If present, it may be one of the following values, and you should handle these errors like so:
<a id="push-ticket-errors"></a>
### 推送票据错误
¥Push ticket errors
* `DeviceNotRegistered`：设备无法再接收推送通知，你应该停止向相应的 Expo 推送令牌发送消息。
  ¥`DeviceNotRegistered`: The device cannot receive push notifications anymore and you should stop sending messages to the corresponding Expo push token.
<a id="push-receipt-errors"></a>
### 推送收据错误
¥Push receipt errors
* `DeviceNotRegistered`：设备无法再接收推送通知，你应该停止向相应的 Expo 推送令牌发送消息。
  ¥`DeviceNotRegistered`: The device cannot receive push notifications anymore and you should stop sending messages to the corresponding Expo push token.
* `MessageTooBig`：总通知负载太大。在 Android 和 iOS 上，总负载不得超过 4096 字节。
  ¥`MessageTooBig`: The total notification payload was too large. On Android and iOS, the total payload must be at most 4096 bytes.
* `MessageRateExceeded`：你向给定设备发送消息过于频繁。实现指数退避并缓慢重试发送消息。
  ¥`MessageRateExceeded`: You are sending messages too frequently to the given device. Implement exponential backoff and slowly retry sending messages.
* `MismatchSenderId`：这表明你的 FCM 推送凭据存在问题。FCM 推送凭证有两部分：你的 FCM 服务器密钥和 google-services.json 文件。两者必须与相同的发送者 ID 关联。你可以在 [你可以在同一位置找到服务器密钥](/push-notifications/push-notifications-setup/#upload-server-credentials).txt 中找到你的发送者 ID。检查你项目 EAS 信息中心的“凭据”>“应用标识符”>“服务凭据”>“FCM V1 服务账户密钥”下的服务器密钥，以及你项目的 google-services.json 文件 > `project_number` 中的发送者 ID，是否与 Firebase 控制台中“项目设置”>“云消息传递”选项卡 >“云消息传递 API（旧版）”下显示的一致。
  ¥`MismatchSenderId`: This indicates that there is an issue with your FCM push credentials. There are two pieces to FCM push credentials: your FCM server key, and your **google-services.json** file. Both must be associated with the same sender ID. You can find your sender ID in the [same place you find your server key](/push-notifications/push-notifications-setup/#upload-server-credentials). Check that the server key from your project's EAS dashboard under **Credentials** > **Application identifier** > **Service Credentials** > **FCM V1 service account key** and that the sender ID from your project's **google-services.json** > `project_number` is the same as shown in the Firebase console under **Project Settings** > **Cloud Messaging** tab > **Cloud Messaging API (Legacy)**.
* `InvalidCredentials`：你的独立应用的推送通知凭据无效（例如，你可能已撤销它们）。
  ¥`InvalidCredentials`: Your push notification credentials for your standalone app are invalid (for example, you may have revoked them).
  * 安卓：确保你已按照 [上传 FCM V1 服务器凭据](/push-notifications/fcm-credentials) 中的指定从 Firebase 控制台正确上传服务器密钥。
    ¥**Android**: Make sure that you have correctly uploaded the server key from the Firebase Console as specified in [uploading FCM V1 server credentials](/push-notifications/fcm-credentials).
  * iOS：运行 `eas credentials` 并按照提示重新生成新的推送通知凭据。如果你撤销 APN 密钥，则所有依赖该密钥的应用将无法再发送或接收推送通知，直到你上传新密钥来替换它。上传新的 APN 密钥不会更改用户的 Expo Push 令牌。有时，这些错误将包含声称存在 `InvalidProviderToken` 错误的更多详细信息。这实际上与你的 APN 密钥和配置文件相关。要解决此错误，你应该重建应用并重新生成新的推送密钥和配置文件。
    ¥**iOS**: Run `eas credentials` and follow the prompts to regenerate new push notification credentials. If you revoke an APN key, all apps that rely on that key will no longer be able to send or receive push notifications until you upload a new key to replace it. Uploading a new APN key will **not** change your users' Expo Push Tokens. Sometimes, these errors will contain further details claiming an `InvalidProviderToken` error. This is actually tied to both your APN key **and** your provisioning profile. To resolve this error, you should rebuild the app and regenerate a new push key and provisioning profile.
> 为了更好地了解 iOS 凭据（包括推送通知凭据），请阅读我们的 [应用签名文档](/app-signing/app-credentials#ios)。
>
> ¥For a better understanding of iOS credentials, including push notification credentials, read our [App Signing docs](/app-signing/app-credentials#ios).
<a id="request-errors"></a>
### 请求错误
¥Request errors
如果推送票证或推送收据的整个请求存在错误，则 `errors` 对象可能具有以下值之一，你应该处理这些错误：
¥If there's an error with the entire request for either push tickets or push receipts, the `errors` object might have one of the following values, and you should handle these errors:
* `TOO_MANY_REQUESTS`：你超出了每个项目每秒 600 个通知的请求限制。我们建议在你的服务器中实现速率限制，以防止每秒发送超过 600 个通知（请注意，如果你使用 [expo-server-sdk-node](https://github.com/expo/expo-server-sdk-node)，这已经与重试的指数退避一起实现）。
  ¥`TOO_MANY_REQUESTS`: You are exceeding the request limit of 600 notifications per second per project. We recommend implementing rate-limiting in your server to prevent sending more than 600 notifications per second (note that if you use [expo-server-sdk-node](https://github.com/expo/expo-server-sdk-node), this is already implemented along with exponential backoffs for retries).
* `PUSH_TOO_MANY_EXPERIENCE_IDS`：你正在尝试向不同的 Expo 体验发送推送通知，例如 `@username/projectAAA` 和 `@username/projectBBB`。检查 `details` 字段以获取请求中体验名称与其关联的推送令牌的映射，并从其他体验中删除任何内容。
  ¥`PUSH_TOO_MANY_EXPERIENCE_IDS`: You are trying to send push notifications to different Expo experiences, for example, `@username/projectAAA` and `@username/projectBBB`. Check the `details` field for a mapping of experience names to their associated push tokens from the request, and remove any from another experience.
* `PUSH_TOO_MANY_NOTIFICATIONS`：你正尝试在一个请求中发送 100 多个推送通知。确保你在每个请求中仅发送 100 个（或更少）通知。
  ¥`PUSH_TOO_MANY_NOTIFICATIONS`: You are trying to send more than 100 push notifications in one request. Make sure you are only sending 100 (or fewer) notifications in each request.
* `PUSH_TOO_MANY_RECEIPTS`：你正尝试在一个请求中获取超过 1000 个推送收据。确保你仅发送 1000 个（或更少）票证 ID 字符串的数组来获取推送收据。
  ¥`PUSH_TOO_MANY_RECEIPTS`: You are trying to get more than 1000 push receipts in one request. Make sure you are only sending an array of 1000 (or fewer) ticket ID strings to get your push receipts.
<a id="additional-security"></a>
## 额外的安全保障
¥Additional security
你可以要求在我们将推送请求发送给你的用户之前发送带有有效 [访问令牌](/accounts/programmatic-access) 的任何推送请求。你可以从 [EAS 仪表板](https://expo.dev/settings/access-tokens) 启用此增强的推送安全性。
¥You can require any push requests to be sent with a valid [access token](/accounts/programmatic-access) before we will deliver them to your users. You can enable this enhanced push security from your [EAS Dashboard](https://expo.dev/settings/access-tokens).
默认情况下，你可以通过发送 Expo Push Token 以及消息所需的任何文本或其他数据来向用户发送通知。这很容易设置，但如果令牌泄露，恶意用户将能够冒充你的服务器并向你的用户发送消息。我们从未有过这样的报道。但是，为了遵循最佳安全实践，我们提供使用访问令牌和推送令牌作为附加安全层。
¥By default, you can send a notification to your users by sending their Expo Push Token and any text or additional data needed for the message. This is easy to set up, but **if the tokens are leaked, a malicious user would be able to impersonate your server and send their message to your users.** We have never had an instance of this report. However, to follow best security practices, we offer the use of an access token alongside the push token as an additional layer of security.
如果你使用的是 [`expo-server-sdk-node`](https://github.com/expo/expo-server-sdk-node#usage)，请至少升级到 `v3.6.0` 并将 `accessToken` 作为构造函数中的选项传递。否则，将标头 `'Authorization': 'Bearer ${accessToken}'` 与任何请求一起传递给我们的推送 API。
¥If you're using the [`expo-server-sdk-node`](https://github.com/expo/expo-server-sdk-node#usage), upgrade to at least `v3.6.0` and pass your `accessToken` as an option in the constructor. Otherwise, pass in the header `'Authorization': 'Bearer ${accessToken}'` with any requests to our push API.
启用推送安全性后，发送的任何没有有效访问令牌的请求都将导致代码错误：`UNAUTHORIZED`。
¥Any requests sent *without* a valid access token *after* you enable push security will result in an error with code: `UNAUTHORIZED`.
<a id="formats"></a>
## 格式
¥Formats
<a id="message-request-format"></a>
### 消息请求格式
¥Message request format
每条消息必须是具有给定字段的 JSON 对象（仅需要 `to` 字段）：
¥Each message must be a JSON object with the given fields (only the `to` field is required):
| Field               | Platform        | Type                                                      | Description                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------- | --------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `to`                | Android and iOS | `string \| string[]`                                      | An Expo push token or an array of Expo push tokens specifying the recipient(s) of this message.                                                                                                                                                                                                                                                                                |
| `_contentAvailable` | iOS Only        | `boolean \| undefined`                                    | When this is set to true, the notification will cause the iOS app to start in the background to run a [background task](/versions/latest/sdk/notifications/#background-notifications). Your app needs to be [configured](/versions/unversioned/sdk/notifications/#background-notification-configuration) to support this.                                                      |
| `data`              | Android and iOS | `Object`                                                  | A JSON object delivered to your app. It may be up to about 4KiB; the total notification payload sent to Apple and Google must be at most 4KiB or else you will get a "Message Too Big" error.                                                                                                                                                                                  |
| `title`             | Android and iOS | `string`                                                  | The title to display in the notification. Often displayed above the notification body. Maps to [`AndroidNotification.title`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidNotification) and [`aps.alert.title`](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Payload-key-reference).        |
| `body`              | Android and iOS | `string`                                                  | The message to display in the notification. Maps to [`AndroidNotification.body`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidNotification) and [`aps.alert.body`](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Payload-key-reference).                                                     |
| `ttl`               | Android and iOS | `number`                                                  | Time to Live: the number of seconds for which the message may be kept around for redelivery if it hasn't been delivered yet. Defaults to `undefined` to use the respective defaults of each provider (1 month for Android/FCM as well as iOS/APNs).                                                                                                                            |
| `expiration`        | Android and iOS | `number`                                                  | Timestamp since the Unix epoch specifying when the message expires. Same effect as `ttl` (`ttl` takes precedence over `expiration`).                                                                                                                                                                                                                                           |
| `priority`          | Android and iOS | `'default' \| 'normal' \| 'high'`                         | The delivery priority of the message. Specify `default` or omit this field to use the default priority on each platform ("normal" on Android and "high" on iOS).                                                                                                                                                                                                               |
| `subtitle`          | iOS Only        | `string`                                                  | The subtitle to display in the notification below the title. Maps to [`aps.alert.subtitle`](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Payload-key-reference).                                                                                                                                                               |
| `sound`             | iOS Only        | `string \| null`                                          | Play a sound when the recipient receives this notification. Specify `default` to play the device's default notification sound, or omit this field to play no sound. Custom sounds need to be [configured](/versions/unversioned/sdk/notifications/#configurable-properties) via the config plugin and then specified including the file extension. Example: `bells_sound.wav`. |
| `badge`             | iOS Only        | `number`                                                  | Number to display in the badge on the app icon. Specify zero to clear the badge.                                                                                                                                                                                                                                                                                               |
| `interruptionLevel` | iOS Only        | `'active' \| 'critical' \| 'passive' \| 'time-sensitive'` | The importance and delivery timing of a notification. The string values correspond to the [`UNNotificationInterruptionLevel`](https://developer.apple.com/documentation/usernotifications/unnotificationinterruptionlevel) enumeration cases.                                                                                                                                  |
| `channelId`         | Android Only    | `string`                                                  | ID of the Notification Channel through which to display this notification. If an ID is specified but the corresponding channel does not exist on the device (that has not yet been created by your app), the notification will not be displayed to the user.                                                                                                                   |
| `icon`              | Android Only    | `string`                                                  | The notification's icon. Name of an Android drawable resource (example: `myicon`). Defaults to the icon specified in the [config plugin](/versions/latest/sdk/notifications/#configurable-properties).                                                                                                                                                                         |
| `richContent`       | Android and iOS | `Object`                                                  | Currently supports setting a notification image. Provide an object with key `image` and value of type `string`, which is the image URL. Android will show the image out of the box. On iOS, you need to add a Notification Service Extension target to your app. See [this example](https://github.com/expo/expo/pull/36202) on how to do that.                                |
| `categoryId`        | Android and iOS | `string`                                                  | ID of the notification category that this notification is associated with. [Find out more about notification categories here](/versions/latest/sdk/notifications/#manage-notification-categories-interactive-notifications).                                                                                                                                                   |
| `mutableContent`    | iOS Only        | `boolean`                                                 | Specifies whether this notification can be [intercepted by the client app](https://developer.apple.com/documentation/usernotifications/modifying_content_in_newly_delivered_notifications?language=objc). Defaults to `false`.                                                                                                                                                 |
关于 `ttl` 的注意事项：在 Android 上，我们尽最大努力立即传递 TTL 为零的消息，并且不会限制它们。但是，将 TTL 设置为较低值（例如零）可以防止普通优先级通知到达处于打瞌睡模式的 Android 设备。为了保证通知已送达，TTL 必须足够长，以便设备从休眠模式唤醒。当两者都指定时，该字段优先于 `expiration`。
¥**Note on `ttl`**: On Android, we make our best effort to deliver messages with zero TTL immediately and do not throttle them. However, setting TTL to a low value (for example, zero) can prevent normal-priority notifications from ever reaching Android devices that are in doze mode. To guarantee that a notification is delivered, TTL must be long enough for the device to wake from doze mode. This field takes precedence over `expiration` when both are specified.
关于 `priority` 的注意事项：在 Android 上，普通优先级消息不会在睡眠设备上打开网络连接，并且可能会延迟发送以节省电池。高优先级消息更有可能被立即传递，并可能唤醒休眠设备以打开网络连接，从而消耗能源。在 iOS 上，正常优先级消息的发送时间会考虑设备的功耗，并且可能会分组并突发传送。它们受到限制，可能不会由 Apple 提供。高优先级消息通常会立即发送。普通优先级对应于 APN 优先级 5，高优先级对应于 10。
¥**Note on `priority`**: On Android, normal-priority messages won't open network connections on sleeping devices and their delivery may be delayed to conserve the battery. High-priority messages are more likely to be delivered immediately and may wake sleeping devices to open network connections, consuming energy. On iOS, normal-priority messages are sent at a time that takes into account power considerations for the device and may be grouped and delivered in bursts. They are throttled and may not be delivered by Apple. High-priority messages are usually sent immediately. Normal priority corresponds to APNs priority level 5 and high priority to 10.
关于 `channelId` 的注意事项：如果保留为空，则使用 "默认" 通道，并且 Expo 会在设备上创建该通道（如果尚不存在）。但是，请谨慎使用，因为 "默认" 通道是面向用户的，你可能无法完全删除它。
¥**Note on `channelId`**: If left null, a "Default" channel is used, and Expo creates the channel on the device if it does not yet exist. However, use caution, as the "Default" channel is user-facing and you may not be able to fully delete it.
<a id="push-ticket-format"></a>
### 推送票格式
¥Push ticket format
```js
{
  "data": [
    {
      "status": "error" | "ok",
      "id": string, // this is the Receipt ID
      // if status === "error"
      "message": string,
      "details": JSON
    },
    ...
  ],
  // only populated if there was an error with the entire request
  "errors": [{
    "code": string,
    "message": string
  }]
}
```
<a id="push-receipt-request-format"></a>
### 推送回执请求格式
¥Push receipt request format
```js
{
  "ids": string[]
}
```
<a id="push-receipt-response-format"></a>
### 推送回执响应格式
¥Push receipt response format
```js
{
  "data": {
    Receipt ID: {
      "status": "error" | "ok",
      // if status === "error"
      "message": string,
      "details": JSON
    },
    ...
  },
  // only populated if there was an error with the entire request
  "errors": [{
    "code": string,
    "message": string
  }]
}
```
<a id="delivery-guarantees"></a>
## 交货保证
¥Delivery guarantees
Expo 尽最大努力将通知传送到 Google 和 Apple 运营的推送通知服务。Expo 的基础架构设计用于至少一次尝试传送到底层推送通知服务。通知更有可能多次发送给 Google 或 Apple，而不是根本不发送；但是，这两种结果都不常见。
¥Expo makes a best effort to deliver notifications to the push notification services operated by Google and Apple. Expo's infrastructure is designed for at least one attempt at delivery to the underlying push notification services. It is more likely for a notification to be delivered to Google or Apple more than once rather than not at all; however, both these results are uncommon.
将通知移交给底层推送通知服务后，Expo 会创建一个 "推送收据" 来记录移交是否成功。推送收据表示底层推送通知服务是否收到通知。
¥After a notification has been handed off to an underlying push notification service, Expo creates a "push receipt" that records whether the handoff was successful. A push receipt denotes whether the underlying push notification service received the notification.
最后，来自 Google 和 Apple 的推送通知服务遵循自己的政策将通知传递给设备。
¥Finally, the push notification services from Google and Apple follow their own policies to deliver the notifications to the device.
<a id="troubleshooting"></a>
## 故障排除
¥Troubleshooting
Note: Network connectivity issues
---
This section helps you diagnose and resolve common network issues. Your server must have connectivity to Google Cloud Platform services in the United States region, as this is where Expo's push notification service is hosted.
#### DNS resolution
Test if your server can resolve Expo's push service domain name:
!!!IG10!!!
#### Network routing and connectivity
Verify your server can reach Expo's endpoints:
!!!IG11!!!
Common issues to check:
- Firewall rules blocking outbound HTTPS (port 443) traffic
- Corporate proxy servers that may require authentication or special configuration
- Network ACLs or security groups (in cloud environments) restricting outbound connections
- Packet fragmentation due to MTU size issues
#### TLS certificate validation
Ensure your server can validate the server's TLS certificate:
!!!IG12!!!
We use standard TLS certificates signed by major service providers including Cloudflare, Google, and Let's Encrypt.
---


## 处理传入通知

了解如何响应应用收到的通知并根据事件采取行动。

[`expo-notifications`](/versions/latest/sdk/notifications) 库包含事件监听器，用于处理应用在收到通知时如何响应。
¥The [`expo-notifications`](/versions/latest/sdk/notifications) library contains event listeners that handle how your app responds when receiving a notification.
<a id="notification-event-listeners"></a>
## 通知事件监听器
¥Notification event listeners
当接收到通知或与之交互时，[`addNotificationReceivedListener`](/versions/latest/sdk/notifications/#addnotificationreceivedlistenerlistener) 和 [`addNotificationResponseReceivedListener`](/versions/latest/sdk/notifications/#addnotificationresponsereceivedlistenerlistener) 事件监听器会接收一个对象。
¥The [`addNotificationReceivedListener`](/versions/latest/sdk/notifications/#addnotificationreceivedlistenerlistener) and [`addNotificationResponseReceivedListener`](/versions/latest/sdk/notifications/#addnotificationresponsereceivedlistenerlistener) event listeners receive an object when a notification is received or interacted with.
这些监听器允许你在应用打开和前台时以及应用后台或关闭且用户点击通知时收到通知时添加行为。
¥These listeners allow you to add behavior when notifications are received while your app is open and foregrounded and when your app is backgrounded or closed and the user taps on the notification.
```js
useEffect(() => {
  registerForPushNotificationsAsync().then(token => setExpoPushToken(token));
  notificationListener.current = Notifications.addNotificationReceivedListener(notification => {
    setNotification(notification);
  });
  responseListener.current = Notifications.addNotificationResponseReceivedListener(response => {
    console.log(response);
  });
  return () => {
    Notifications.removeNotificationSubscription(notificationListener.current);
    Notifications.removeNotificationSubscription(responseListener.current);
  };
}, []);
```
Note: Android notification object example from 
---
Sample of the `notification` object received by the callback function when using `Notifications.addNotificationReceivedListener`:
```json
// console.log(notification);
{
  "request": {
    "trigger": {
      "remoteMessage": {
        "originalPriority": 2,
        "sentTime": 1724782348210,
        "notification": {
          "usesDefaultVibrateSettings": false,
          "color": null,
          "channelId": null,
          "visibility": null,
          "sound": null,
          "tag": null,
          "bodyLocalizationArgs": null,
          "imageUrl": null,
          "title": "Chat App",
          "ticker": null,
          "eventTime": null,
          "body": "New message from John Doe",
          "titleLocalizationKey": null,
          "notificationPriority": null,
          "icon": null,
          "usesDefaultLightSettings": false,
          "sticky": false,
          "link": null,
          "titleLocalizationArgs": null,
          "bodyLocalizationKey": null,
          "usesDefaultSound": false,
          "clickAction": null,
          "localOnly": false,
          "lightSettings": null,
          "notificationCount": null
        },
        "data": {
          "channelId": "default",
          "message": "New message from John Doe",
          "title": "Chat App",
          "body": "{\"senderId\":\"user123\",\"senderName\":\"John Doe\",\"messageId\":\"msg789\",\"conversationId\":\"conversation-456\",\"messageType\":\"text\",\"timestamp\":1724766427}",
          "scopeKey": "@betoatexpo/expo-notifications-app",
          "experienceId": "@betoatexpo/expo-notifications-app",
          "projectId": "51092087-87a4-4b12-8008-145625477434"
        },
        "to": null,
        "ttl": 0,
        "collapseKey": "dev.expo.notificationsapp",
        "messageType": null,
        "priority": 2,
        "from": "115310547649",
        "messageId": "0:1724782348220771%0f02879c0f02879c"
      },
      "channelId": "default",
      "type": "push"
    },
    "content": {
      "autoDismiss": true,
      "title": "Chat App",
      "badge": null,
      "sticky": false,
      "sound": "default",
      "body": "New message from John Doe",
      "subtitle": null,
      "data": {
        "senderId": "user123",
        "senderName": "John Doe",
        "messageId": "msg789",
        "conversationId": "conversation-456",
        "messageType": "text",
        "timestamp": 1724766427
      }
    },
    "identifier": "0:1724782348220771%0f02879c0f02879c"
  },
  "date": 1724782348210
}
```
You can directly access the notification custom data by logging the `notification.request.content.data` object:
```json
// console.log(notification.request.content.data);
{
  "senderId": "user123",
  "senderName": "John Doe",
  "messageId": "msg789",
  "conversationId": "conversation-456",
  "messageType": "text",
  "timestamp": 1724766427
}
```
---
Note: iOS notification object example from 
---
Sample of the `notification` object received by the callback function when using `Notifications.addNotificationReceivedListener`:
```json
// console.log(notification);
{
  "request": {
    "trigger": {
      "class": "UNPushNotificationTrigger",
      "type": "push",
      "payload": {
        "experienceId": "@betoatexpo/expo-notifications-app",
        "projectId": "51092087-87a4-4b12-8008-145625477434",
        "scopeKey": "@betoatexpo/expo-notifications-app",
        "aps": {
          "thread-id": "",
          "category": "",
          "badge": 1,
          "alert": {
            "subtitle": "Hey there! How's your day going?",
            "title": "Chat App",
            "launch-image": "",
            "body": "New message from John Doe"
          },
          "sound": "default"
        },
        "body": {
          "messageId": "msg789",
          "timestamp": 1724766427,
          "messageType": "text",
          "senderId": "user123",
          "senderName": "John Doe",
          "conversationId": "conversation-456"
        }
      }
    },
    "identifier": "3AEB849E-9059-4D09-BC3B-9A0B104CF062",
    "content": {
      "body": "New message from John Doe",
      "sound": "default",
      "launchImageName": "",
      "badge": 1,
      "subtitle": "Hey there! How's your day going?",
      "title": "Chat App",
      "data": {
        "conversationId": "conversation-456",
        "senderName": "John Doe",
        "senderId": "user123",
        "messageType": "text",
        "timestamp": 1724766427,
        "messageId": "msg789"
      },
      "summaryArgument": null,
      "categoryIdentifier": "",
      "attachments": [],
      "interruptionLevel": "active",
      "threadIdentifier": "",
      "targetContentIdentifier": null,
      "summaryArgumentCount": 0
    }
  },
  "date": 1724798493.0589335
}
```
You can directly access the notification custom data by logging the `notification.request.content.data` object:
```json
// console.log(notification.request.content.data);
{
  "senderId": "user123",
  "senderName": "John Doe",
  "messageId": "msg789",
  "conversationId": "conversation-456",
  "messageType": "text",
  "timestamp": 1724766427
}
```
---
有关这些对象的更多信息，请参阅 [`Notification`](/versions/latest/sdk/notifications/#notification) 文档。
¥For more information on these objects, see [`Notification`](/versions/latest/sdk/notifications/#notification) documentation.
<a id="foreground-notification-behavior"></a>
## 前台通知行为
¥Foreground notification behavior
要处理应用处于前台时收到通知时的行为，请使用 [`Notifications.setNotificationHandler`](/versions/latest/sdk/notifications/#handling-incoming-notifications-when-the-app-is) 和 `handleNotification()` 回调来设置以下选项：
¥To handle the behavior when notifications are received when your app is **foregrounded**, use [`Notifications.setNotificationHandler`](/versions/latest/sdk/notifications/#handling-incoming-notifications-when-the-app-is) with the `handleNotification()` callback to set the following options:
* `shouldPlaySound`
* `shouldSetBadge`
* `shouldShowBanner`
* `shouldShowList`
```jsx
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldPlaySound: false,
    shouldSetBadge: false,
    shouldShowBanner: true,
    shouldShowList: true,
  }),
});
```
<a id="closed-notification-behavior"></a>
## 关闭通知行为
¥Closed notification behavior
在 Android 上，用户可以设置某些操作系统级别的设置，通常围绕性能和电池优化，这可以防止在应用关闭时发送通知。例如，使用 Android 9 及更低版本的 OnePlus 设备上的 Deep Clear 选项就是此类设置之一。
¥On Android, users can set certain OS-level settings, usually revolving around performance and battery optimization, that can prevent notifications from being delivered when the app is closed. For example, one such setting is the **Deep Clear** option on OnePlus devices using Android 9 and lower versions.


# 参考

## 使用 FCM V1 获取 Google 服务账户密钥

了解如何创建或使用 Google 服务账户密钥通过 FCM 发送 Android 通知。

<a id="create-a-new-google-service-account-key"></a>
## 创建新的 Google 服务账户密钥
¥Create a new Google Service Account Key
以下是在 EAS 中配置新的 Google 服务账户密钥以使用 FCM V1 发送 Android 通知的步骤。
¥Here are the steps to configure a new Google Service Account Key in EAS for sending Android Notifications using FCM V1.
Step 1: 
Create a new Firebase project for your app in the [Firebase Console](https://console.firebase.google.com). If you already have a Firebase project for your app, continue to the next step.
Step 2: 
In the Firebase console, open **Project settings** > [**Service accounts**](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk) for your project.
Step 3: 
Click **Generate New Private Key**, then confirm by clicking **Generate Key**. Securely store the JSON file containing the private key.
Step 4: 
Upload the JSON file to EAS and configure it for sending Android notifications. This can be done using EAS CLI or in [EAS dashboard](https://expo.dev).
!!!IG2!!!
!!!IG3!!!
- Run `eas credentials`
- Select `Android` > `production` > `Google Service Account`
- Select `Manage your Google Service Account Key for Push Notifications (FCM V1)`
- Select `Set up a Google Service Account Key for Push Notifications (FCM V1)` > `Upload a new service account key`
- If you've previously stored the JSON file in your project directory, the EAS CLI automatically detects the file and prompts you to select it. Press <kbd>Y</kbd> to continue.
> **Note**: Add the JSON file to your version source control's ignore file (for example, **.gitignore**) to avoid committing it to your repository since it contains sensitive data.
!!!IG4!!!
!!!IG5!!!
- Under **Project settings**, click [**Credentials**](https://expo.dev/accounts/[account]/projects/[project]/credentials) in the navigation menu
- For **Android**, click **Add Application Identifier** or select an existing **Application identifier**
- Under **Service Credentials** > **FCM V1 service account key**, click **Add a service account key**
- Under **Upload new key**, upload your JSON credential and click **Save**
!!!IG6!!!
!!!IG7!!!
Step 5: 
Configure the **google-services.json** file in your project. Download it from the Firebase Console and place it at the root of your project directory. If you're using version control, add it to your ignore file (for example, **.gitignore**) as it contains sensitive data.
**Note**: You can skip this step if **google-services.json** has already been set up.
In **app.json**, add [`expo.android.googleServicesFile`](/versions/latest/config/app/#googleservicesfile) with its value as the path of the **google-services.json**.
!!!IG0!!!
Step 6: 
You're all set! You can now send notifications to Android devices via Expo Push Notifications using the FCM V1 protocol.
## Use an existing Google Service Account Key
Step 1: 
Open the [IAM Admin page](https://console.cloud.google.com/iam-admin/iam?authuser=0) in Google Cloud Console. In the Permissions tab, locate the **Principal** you intend to modify and click the pencil icon for **Edit Principal**.
Step 2: 
Click **Add Role** and select the **Firebase Messaging API Admin** role from the dropdown. Click **Save**.
Step 3: 
You have to specify to EAS which JSON credential file to use for sending FCM V1 notifications, using EAS CLI or in [EAS dashboard](https://expo.dev). You can upload a new JSON file or select a previously uploaded file.
!!!IG8!!!
!!!IG9!!!
- Run `eas credentials`
- Select `Android` > `production` > `Google Service Account`
- Select `Manage your Google Service Account Key for Push Notifications (FCM V1)`
- Select `Set up a Google Service Account Key for Push Notifications (FCM V1)` > `Upload a new service account key`
- The EAS CLI automatically detects the file on your local machine and prompts you to select it. Press <kbd>Y</kbd> to continue.
> **Note**: Add the JSON file to your version source control's ignore file (for example, **.gitignore**) to avoid committing it to your repository since it contains sensitive data.
!!!IG10!!!
!!!IG11!!!
- Under **Project settings**, click [**Credentials**](https://expo.dev/accounts/[account]/projects/[project]/credentials) in the navigation menu
- For **Android**, click **Add Application Identifier** or select an existing **Application identifier**
- Under **Service Credentials** > **FCM V1 service account key**, click **Add a service account key**
- Under **Upload new key**, upload your JSON credential and click **Save**
!!!IG12!!!
!!!IG13!!!
Step 4: 
Configure the **google-services.json** file in your project. Download it from the Firebase Console and place it at the root of your project directory. If you're using version control, add it to your ignore file (for example, **.gitignore**) as it contains sensitive data.
**Note**: You can skip this step if **google-services.json** has already been set up.
In **app.json**, add [`expo.android.googleServicesFile`](/versions/latest/config/app/#googleservicesfile) with its value as the path of the **google-services.json**.
!!!IG1!!!
Step 5: 
You're all set! You can now send notifications to Android devices via Expo Push Notifications using the FCM V1 protocol.


## 使用 FCM 和 APN 发送通知

了解如何使用 FCM 和 APN 发送通知。

你可能需要对通知进行更细粒度的控制，在这种情况下，可能需要直接与 FCM 和 APNs 通信。Expo 平台不会限制你使用 Expo 应用服务，`expo-notifications` API 与推送服务无关。
¥You may need finer-grained control over your notifications, in which case communicating directly with FCM and APNs may be necessary. The Expo platform does not lock you into using Expo Application Services, and the `expo-notifications` API is push-service agnostic.
> 注意：本指南并非旨在成为通过 FCM 或 APN 发送通知的综合资源。我们建议你阅读官方文档以确保你遵循最新的说明。
>
> ¥**Note**: This guide does not aim to be a comprehensive resource for sending notifications via FCM or APNs. We recommend you read the official documentation to make sure you're following the latest instructions.
<a id="obtaining-a-device-token-for-fcm-or-apns"></a>
## 获取 FCM 或 APN 的设备令牌
¥Obtaining a device token for FCM or APNs
使用 Expo 通知服务时，你使用通过 [`getExpoPushTokenAsync`](/versions/latest/sdk/notifications/#getexpopushtokenasyncoptions-expotokenoptions-expopushtoken) 获得的 `ExpoPushToken`。
¥When using Expo notification service, you use the `ExpoPushToken` obtained with [`getExpoPushTokenAsync`](/versions/latest/sdk/notifications/#getexpopushtokenasyncoptions-expotokenoptions-expopushtoken).
如果你希望通过 FCM 或 APNs 发送通知，则需要使用 [`getDevicePushTokenAsync`](/versions/latest/sdk/notifications/#getdevicepushtokenasync-devicepushtoken) 获取原生设备令牌。
¥If you instead want to send notifications via FCM or APNs, you need to obtain the native device token with [`getDevicePushTokenAsync`](/versions/latest/sdk/notifications/#getdevicepushtokenasync-devicepushtoken).
```diff
import * as Notifications from 'expo-notifications';
...
- const token = (await Notifications.getExpoPushTokenAsync()).data;
+ const token = (await Notifications.getDevicePushTokenAsync()).data;
// send token to your server
```
<a id="fcmv1-server"></a>
## FCMv1 服务器
¥FCMv1 server
本指南基于 [Firebase 官方文档](https://firebase.google.com/docs/cloud-messaging/server)。
¥This guide is based on [Firebase official documentation](https://firebase.google.com/docs/cloud-messaging/server).
与 FCM 的通信是通过发送 POST 请求来完成的。但是，在发送或接收任何通知之前，你需要按照 [配置 FCM](/push-notifications/fcm-credentials/) 的步骤操作并获取你的 `FCM-SERVER-KEY`。
¥Communicating with FCM is done by sending a POST request. However, before sending or receiving any notifications, you'll need to follow the steps to [configure FCM](/push-notifications/fcm-credentials/) and get your `FCM-SERVER-KEY`.
<a id="getting-an-authentication-token"></a>
### 获取身份验证令牌
¥Getting an authentication token
FCM 需要 Oauth 2.0 访问令牌，必须通过 ["更新发送请求的授权"](https://firebase.google.com/docs/cloud-messaging/migrate-v1#update-authorization-of-send-requests) 中描述的方法之一获取。
¥FCM requires an Oauth 2.0 access token, which must be obtained via one of the methods described in ["Update authorization of send requests"](https://firebase.google.com/docs/cloud-messaging/migrate-v1#update-authorization-of-send-requests).
出于测试目的，你可以使用 Google Auth 库和上面获得的私钥文件来获取单个通知的短期令牌，如从 Firebase 文档改编的此 Node 示例所示：
¥For testing purposes, you can use the Google Auth Library and your private key file obtained above, to obtain a short lived token for a single notification, as in this Node example adapted from Firebase documentation:
```ts
import { JWT } from 'google-auth-library';
function getAccessTokenAsync(
  key: string // Contents of your FCM private key file
) {
  return new Promise(function (resolve, reject) {
    const jwtClient = new JWT(
      key.client_email,
      null,
      key.private_key,
      ['https://www.googleapis.com/auth/cloud-platform'],
      null
    );
    jwtClient.authorize(function (err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}
```
<a id="sending-the-notification"></a>
### 发送通知
¥Sending the notification
下面的示例代码调用上面的 `getAccessTokenAsync()` 来获取 Oauth 2.0 令牌，然后构造并发送通知 POST 请求。请注意，与 FCM 旧协议不同，请求的端点包含你的 Firebase 项目的名称。
¥The example code below calls `getAccessTokenAsync()` above to get the Oauth 2.0 token, then constructs and sends the notification POST request. Note that unlike FCM legacy protocol, the endpoint for the request includes the name of your Firebase project.
```ts
// FCM_SERVER_KEY: Environment variable with the path to your FCM private key file
// FCM_PROJECT_NAME: Your Firebase project name
// FCM_DEVICE_TOKEN: The client's device token (see above in this document)
async function sendFCMv1Notification() {
  const key = require(process.env.FCM_SERVER_KEY);
  const firebaseAccessToken = await getAccessTokenAsync(key);
  const deviceToken = process.env.FCM_DEVICE_TOKEN;
  const messageBody = {
    message: {
      token: deviceToken,
      data: {
        channelId: 'default',
        message: 'Testing',
        title: `This is an FCM notification message`,
        body: JSON.stringify({ title: 'bodyTitle', body: 'bodyBody' }),
        scopeKey: '@yourExpoUsername/yourProjectSlug',
        experienceId: '@yourExpoUsername/yourProjectSlug',
      },
    },
  };
  const response = await fetch(
    `https://fcm.googleapis.com/v1/projects/${process.env.FCM_PROJECT_NAME}/messages:send`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${firebaseAccessToken}`,
        Accept: 'application/json',
        'Accept-encoding': 'gzip, deflate',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(messageBody),
    }
  );
  const readResponse = (response: Response) => response.json();
  const json = await readResponse(response);
  console.log(`Response JSON: ${JSON.stringify(json, null, 2)}`);
}
```
`experienceId` 和 `scopeKey` 字段仅在使用 Expo Go 时适用（从 SDK 53 开始，Expo Go 不再支持推送通知）。否则，你的通知将不会发送到你的应用。FCM 在 [通知负载](https://firebase.google.com/docs/cloud-messaging/http-server-ref#notification-payload-support) 中有一个支持的字段列表，你可以通过查看 [FirebaseRemoteMessage](/versions/latest/sdk/notifications/#firebaseremotemessage) 来了解 Android 上的 `expo-notifications` 支持哪些字段。
¥The `experienceId` and `scopeKey` fields are only applicable when using Expo Go (from SDK 53, push notifications support is removed from Expo Go). Otherwise, your notifications will not go through to your app. FCM has a list of supported fields in the [notification payload](https://firebase.google.com/docs/cloud-messaging/http-server-ref#notification-payload-support), and you can see which ones are supported by `expo-notifications` on Android by looking at the [FirebaseRemoteMessage](/versions/latest/sdk/notifications/#firebaseremotemessage).
FCM 还提供了一些你可以使用的 [几种不同语言的服务器端库](https://firebase.google.com/docs/cloud-messaging/send-message#node.js)，而不是原始 `fetch` 请求。
¥FCM also provides some [server-side libraries in a few different languages](https://firebase.google.com/docs/cloud-messaging/send-message#node.js) you can use instead of raw `fetch` requests.
<a id="how-to-find-fcm-server-key"></a>
### 如何查找 FCM 服务器密钥
¥How to find FCM server key
你可以通过确保遵循 [配置步骤](/push-notifications/push-notifications-setup/#android) 来找到你的 FCM 服务器密钥，并且无需将 FCM 密钥上传到 Expo，而是直接在服务器中使用该密钥（如上例中的 `FCM-SERVER-KEY`）。
¥Your FCM server key can be found by making sure you've followed the [configuration steps](/push-notifications/push-notifications-setup/#android), and instead of uploading your FCM key to Expo, you would use that key directly in your server (as the `FCM-SERVER-KEY` in the previous example).
<a id="apns-server"></a>
## APNs 服务器
¥APNs server
>  **info** 本文档基于 [苹果的文档](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html)，本节介绍了帮助你入门的基础知识。
>
> ¥This documentation is based on [Apple's documentation](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html), and this section covers the basics to get you started.
与 APN 的通信比与 FCM 的通信稍微复杂一些。有些库将所有这些功能封装到一两个函数调用中，例如 [`node-apn`](https://github.com/node-apn/node-apn)。但是，在下面的示例中，使用了最少的库集。
¥Communicating with APNs is a little more complicated than with FCM. Some libraries wrap all of this functionality into one or two function calls such as [`node-apn`](https://github.com/node-apn/node-apn). However, in the examples below, a minimum set of libraries are used.
<a id="client-apns-entitlement"></a>
### 客户端 APN 授权
¥Client APNs entitlement
仅当你的 iOS 应用拥有 APNs 授权时，才能接收推送通知。对于使用 [CNG](/workflow/continuous-native-generation/) 的应用，Expo 配置需要通过以下两种方式之一进行修改：
¥Receiving push notifications only works if your iOS app has the APNs entitlement. For apps using [CNG](/workflow/continuous-native-generation/),
the Expo config needs to be modified in one of two ways:
* 受到推崇的：将 `expo-notifications` 库添加到你的应用，并确保其插件出现在 [应用配置](/workflow/configuration/) 的 `plugins` 数组中：
  ¥**Recommended**: Add the `expo-notifications` library to your app, and ensure that its plugin appears in the `plugins` array of your [app config](/workflow/configuration/):
```json app.json
{
  "expo": {
    "plugins": [
      "expo-notifications"
      ]
  }
}
```
* 如果你不打算使用 `expo-notifications` 库，则应该选择 [将 `aps-environment` 授权手动添加到 Expo 配置](/build-reference/ios-capabilities/#entitlements)，如下例所示：
  ¥If you do not plan to use the `expo-notifications` library, then you should [add the `aps-environment` entitlement manually to the Expo configuration](/build-reference/ios-capabilities/#entitlements),
  as in the example below:
```json app.json
{
  "expo": {
    "ios": {
      "entitlements": {
        "aps-environment": "development"
      }
    }
  }
}
```
如果你不使用 CNG，则应该选择 [在 Xcode 中添加推送通知授权](https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns)。
¥If you are not using CNG, then you should [add the push notification entitlement in Xcode](https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns).
> 注意：如果你要从 SDK 51 之前的版本升级 Expo 应用，则应参考 [此 FYI 文档](https://expo.fyi/apns-entitlement-sdk-51)。
>
> ¥**Note**: If you are upgrading an Expo app from a version before SDK 51, you should refer to [this FYI document](https://expo.fyi/apns-entitlement-sdk-51).
<a id="authorization"></a>
### 授权
¥Authorization
最初，在向 APNS 发送请求之前，你需要获得向应用发送通知的权限。这是通过使用 iOS 开发者凭据生成的 JSON Web 令牌授予的：
¥Initially, before sending requests to APNS, you need permission to send notifications to your app. This is granted via a JSON web token which is generated using iOS developer credentials:
* 与你的应用关联的 APN 密钥（`.p8` 文件）
  ¥APN key (`.p8` file) associated with your app
* 上述 `.p8` 文件的密钥 ID
  ¥Key ID of the above `.p8` file
* 你的 Apple 团队 ID
  ¥Your Apple Team ID
```js
const jwt = require("jsonwebtoken");
const authorizationToken = jwt.sign(
  {
    iss: "YOUR-APPLE-TEAM-ID"
    iat: Math.round(new Date().getTime() / 1000),
  },
  fs.readFileSync("./path/to/appName_apns_key.p8", "utf8"),
  {
    header: {
      alg: "ES256",
      kid: "YOUR-P8-KEY-ID",
    },
  }
);
```
<a id="http2-connection"></a>
### HTTP/2 连接
¥HTTP/2 connection
获得 `authorizationToken` 后，你可以打开与 Apple 服务器的 HTTP/2 连接。在开发中，向 `api.sandbox.push.apple.com` 发送请求。在生产中，将请求发送到 `api.push.apple.com`。
¥After getting the `authorizationToken`, you can open up an HTTP/2 connection to Apple's servers. In development, send requests to `api.sandbox.push.apple.com`. In production, send requests to `api.push.apple.com`.
以下是构建请求的方法：
¥Here's how to construct the request:
```js
const http2 = require('http2');
const client = http2.connect(
  IS_PRODUCTION ? 'https://api.push.apple.com' : 'https://api.sandbox.push.apple.com'
);
const request = client.request({
  ':method': 'POST',
  ':scheme': 'https',
  'apns-topic': 'YOUR-BUNDLE-IDENTIFIER',
  ':path': '/3/device/' + nativeDeviceToken, // This is the native device token you grabbed client-side
  authorization: `bearer ${authorizationToken}`, // This is the JSON web token generated in the "Authorization" step
});
request.setEncoding('utf8');
request.write(
  JSON.stringify({
    aps: {
      alert: {
        title: "\uD83D\uDCE7 You've got mail!",
        body: 'Hello world! \uD83C\uDF10',
      },
    },
    experienceId: '@yourExpoUsername/yourProjectSlug', // Required when testing in the Expo Go app
    scopeKey: '@yourExpoUsername/yourProjectSlug', // Required when testing in the Expo Go app
  })
);
request.end();
```
> 此示例是最小的，不包含错误处理和连接池。出于测试目的，你可以参考 [`sendNotificationToAPNS`](https://github.com/expo/expo/blob/main/docs/public/static/examples/sendNotificationToAPNS.js) 示例代码。
>
> ¥This example is minimal and includes no error handling and connection pooling. For testing purposes, you can refer to [`sendNotificationToAPNS`](https://github.com/expo/expo/blob/main/docs/public/static/examples/sendNotificationToAPNS.js) example code.
APNs 在 [通知负载](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Payload-key-reference) 中提供了受支持字段的完整列表。
¥APNs provide their full list of supported fields in the [notification payload](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Payload-key-reference).


## 推送通知故障排除和常见问题解答

有关 Expo 推送通知服务的常见问题集。

使用 `expo-notifications` 库和 Expo 推送通知服务设置推送通知时的常见问题和常见问题解答集合。
¥A collection of common issues and FAQs when setting up push notifications with the `expo-notifications` library and Expo push notification service.
<a id="expo-push-notification-service-faq"></a>
## Expo 推送通知服务常见问题解答
¥Expo push notification service FAQ
<a id="cost-of-the-push-notification-service"></a>
### 推送通知服务的费用
¥Cost of the push notification service
通过 Expo 推送通知服务发送通知没有任何成本。
¥There is no cost associated with sending notifications through Expo push notification service.
<a id="limit-of-sending-notifications"></a>
### 发送通知的限制
¥Limit of sending notifications
每个项目每秒可发送的通知数上限为 600 个。如果超过此速率，后续请求将失败，直到速率再次低于每秒 600 个。
¥There is a limit of 600 notifications per second per project that can be sent. If you exceed this rate, subsequent requests will fail until the rate falls below 600 per second again.
为了获得最佳结果，我们建议你向服务器添加限制（在 [`expo-server-sdk-node`](https://github.com/expo/expo-server-sdk-node) 中自动处理）和重试逻辑。
¥For best results, we recommend you add throttling (which is handled automatically in the [`expo-server-sdk-node`](https://github.com/expo/expo-server-sdk-node)) and retry logic to your server.
<a id="using-expo-push-notification-service-is-not-mandatory"></a>
### 使用 Expo 推送通知服务不是强制性的
¥Using Expo push notification service is not mandatory
你可以使用 Expo 项目的任何推送通知服务。[`expo-notifications` 的 `getDevicePushTokenAsync` 方法](/versions/latest/sdk/notifications/#getdevicepushtokenasync-devicepushtoken) 允许你获取原生设备推送令牌，然后你可以将其与其他服务甚至 [直接通过 FCM 和 APN 发送通知](/push-notifications/sending-notifications-custom) 一起使用。
¥You can use any push notification service for Expo projects. The [`getDevicePushTokenAsync` method from `expo-notifications`](/versions/latest/sdk/notifications/#getdevicepushtokenasync-devicepushtoken) allows you to get the native device push token, which you can then use with other services, or even [send your notifications directly through FCM and APNs](/push-notifications/sending-notifications-custom).
<a id="connections-to-notification-service-are-encrypted"></a>
### 与通知服务的连接已加密
¥Connections to notification service are encrypted
Expo 与 Apple 和 Google 的连接已加密并使用 HTTPS。
¥Expo's connections to Apple and Google are encrypted and use HTTPS.
<a id="contents-of-the-notification-are-not-stored"></a>
### 通知的内容不被存储
¥Contents of the notification are not stored
Expo 存储推送通知内容的时间不会超过将其传送到 Google 和 Apple 运营的推送通知服务所需的时间。通知仅存储在内存和消息队列中，而不存储在数据库中。
¥Expo doesn't store the contents of push notifications any longer than it takes to deliver them to the push notification services operated by Google and Apple. Notifications are stored only in memory and in message queues, not in databases.
<a id="contents-of-the-notifications-may-be-seen-by-expo-staff"></a>
### Expo 工作线程可以看到通知内容
¥Contents of the notifications may be seen by Expo staff
如果 Expo 团队正在积极调试推送通知服务，我们可能会看到通知内容（例如，在断点处），但 Expo 否则无法看到推送通知内容。
¥If the Expo team is actively debugging the push notifications service, we may see notification contents (for example, at a breakpoint) but Expo cannot see push notification contents otherwise.
<a id="delivery-guarantees"></a>
### 交货保证
¥Delivery guarantees
Expo 尽最大努力向 Google 和 Apple 运营的推送通知服务发送通知。Expo 的基础设施旨在至少向底层推送通知服务传递一次。在某些情况下，通知可能会多次发送给 Google 或 Apple，或者根本不会发送，尽管这种情况很少见。
¥Expo makes the best effort to deliver notifications to the push notification services operated by Google and Apple. Expo's infrastructure is designed for at-least-once delivery to the underlying push notification services. In some cases, a notification may be delivered to Google or Apple more than once or not at all, although these cases are rare.
将通知移交给底层推送通知服务后，Expo 会创建一个 "推送收据" 来记录移交是否成功。推送收据表示底层推送通知服务是否收到通知。
¥After a notification has been handed off to an underlying push notification service, Expo creates a "push receipt" that records whether the handoff was successful. A push receipt denotes whether the underlying push notification service received the notification.
最后，来自 Google 和 Apple 的推送通知服务遵循自己的政策将通知传递给设备。
¥Finally, the push notification services from Google and Apple follow their policies to deliver the notification to the device.
<a id="when-and-why-does-the-expopushtoken-change"></a>
### `ExpoPushToken` 何时以及为何改变
¥When and why does the `ExpoPushToken` change
`ExpoPushToken` 在应用升级过程中保持不变。在 Android 上，重新安装应用可能会导致令牌发生变化。在 iOS 上，即使卸载应用并重新安装后，令牌也保持不变。
¥The `ExpoPushToken` remains the same across app upgrades. On Android, reinstalling the app may result in the token changing. On iOS, the token also remains the same even after uninstalling the app and reinstalling it.
如果你更改 [`applicationId`](/versions/latest/sdk/application/#applicationapplicationid) 或 `experienceId`（通常是 `@expoUsername/projectSlug`），它也会更改。
¥It also changes if you change your [`applicationId`](/versions/latest/sdk/application/#applicationapplicationid) or `experienceId` (usually `@expoUsername/projectSlug`).
`ExpoPushToken` 永不过期。但是，如果你的一位用户卸载了该应用，你将从 Expo 的服务器返回 `DeviceNotRegistered` 错误。这意味着你应该停止向此令牌发送通知。
¥The `ExpoPushToken` never expires. However, if one of your users uninstalls the app, you'll receive a `DeviceNotRegistered` error back from Expo's servers. This means you should stop sending notifications to this token.
<a id="push-notifications-troubleshooting"></a>
## 推送通知故障排除
¥Push notifications troubleshooting
<a id="notifications-arent-working"></a>
### 通知不起作用
¥Notifications aren't working
推送通知有很多移动部分，因此这可能是由于多种原因造成的。要缩小范围，请检查 [推票](/push-notifications/sending-notifications/#push-tickets) 和 [推送收据](/push-notifications/sending-notifications/#push-receipts) 是否有错误消息。
¥Push notifications have a lot of moving parts, so this can be due to a wide variety of reasons. To narrow things down, check the [push ticket](/push-notifications/sending-notifications/#push-tickets) and [push receipt](/push-notifications/sending-notifications/#push-receipts) for error messages.
你还可以通过在应用中测试 [本地通知](/versions/latest/sdk/notifications/#schedulenotificationasyncnotificationrequest-notificationrequestinput-promisestring) 来进一步缩小范围。这可确保你的所有客户端逻辑都是正确的，并将范围缩小到服务器端或应用凭据。
¥You can also narrow things even further by testing [local notifications](/versions/latest/sdk/notifications/#schedulenotificationasyncnotificationrequest-notificationrequestinput-promisestring) in your app. This ensures all of your client-side logic is correct, and narrow things down to the server side or app credentials.
Note: See here for some quick terminal commands you can use to get the push receipt
---
1. Send a notification:
```sh
curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/send" -d '{
  "to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "title":"hello",
  "body": "world"
}'
```
2. Use the resulting ticket `id` to request the push receipt:
```sh
curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/getReceipts" -d '{
  "ids": [
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  ]
}'
```
---
### Notifications work in development, but not in release mode
This indicates that you have either misconfigured your credentials or didn't configure them at all in your production app. Expo Go uses Expo's credentials, which allows working on notifications in development.
When you build your app for the app stores, you need to generate and use your own credentials. On Android, follow [this guide](/push-notifications/fcm-credentials). On iOS, this is handled by your [push key](/app-signing/app-credentials/#push-notification-keys) (revoking the push key associated with your app results in your notifications failing to be delivered. To fix that, add a new push key with `eas credentials`).
For more information, see [app signing](/app-signing/app-credentials).
### Notifications occasionally stop coming through on Android
This is likely due to the `priority` level of the notifications you're sending. You can learn more about [Android priority](https://firebase.google.com/docs/cloud-messaging/http-server-ref#downstream-http-messages-json). [Expo accepts four priorities](/push-notifications/sending-notifications/#message-request-format):
- `default`: manually mapped to the default priority documented by Apple and Google
- `high`: mapped to the high priority level documented by Apple and Google
- `normal`: mapped to the normal priority level documented by Apple and Google
- (priority omitted): treated exactly as if `default` were specified
Setting the priority to `high` gives your notification the greatest likelihood that Android will display the notification.
### Handle expired push notification credentials
When your push notification credentials have expired, run `eas credentials`, choose iOS and a build profile, then remove your push notification key and generate a new one.
### No valid aps-environment entitlement string found error for iOS
This error occurs if you haven't set up a push notification key for your iOS project. To check, go to the [Project Credentials page](https://expo.dev/accounts/[account]/projects/[project]/credentials/ios).
To generate a new push notification key, trigger a new build by running:
```sh
$ eas build --profile [profile] --platform ios
```
For a visual guide, see the [Expo Notifications with EAS video](https://youtu.be/BCCjGtKtBjE?t=2123).
### Error message when sending a notification
Check the `details` property of the returned push ticket or receipt for more information. [Read this](/push-notifications/sending-notifications/#errors) for common error code responses and their associated solutions.
### Fetching a push token takes a long time on iOS
`getDevicePushTokenAsync` and `getExpoPushTokenAsync` can sometimes take a long time to resolve on iOS. This is outside of `expo-notifications`'s control, as stated in Apple's [Troubleshooting Push Notifications](https://developer.apple.com/library/archive/technotes/tn2265/_index.html) technical note:
> This is not necessarily an error condition. The system may not have Internet connectivity at all because it is out of range of any cell towers or Wi-Fi access points, or it may be in airplane mode. Instead of treating this as an error, your app should continue normally, disabling only that functionality that relies on push notifications.
Here are some ways our community members have resolved this issue:
Note: Read the Apple's Technical Note on troubleshooting push notifications
---
Read Apple's [Technical Note on troubleshooting push notifications](https://developer.apple.com/library/archive/technotes/tn2265/_index.html)! This is the single most reliable source of information on this problem. To help you grasp what they're suggesting:
- Make sure the device has a reliable connection to the Internet (try turning off Wi-Fi or switching to another network, and disabling the firewall block on port 5223, as suggested in [this SO answer](https://stackoverflow.com/a/34332047/1123156)).
- **Bare React Native apps** must [manually enable the **Push Notifications** capability](/build-reference/ios-capabilities#manual-setup). If you have trouble setting this up, refer to [this Stack Overflow answer](https://stackoverflow.com/a/10791240/1123156). You may also want to try to debug this even further by logging persistent connection debug information as outlined by [this Stack Overflow answer](https://stackoverflow.com/a/8036052/1123156).
---
Note: Try again in a little while
---
- APNS servers near the device may be down as indicated by [this forum thread](https://developer.apple.com/forums/thread/52224). Take a walk and try again later!
- Try again in a few days as suggested by [this GitHub comment](https://github.com/expo/expo/issues/10369#issuecomment-717872956).
---
Note: Disable network sharing on your device
---
You may need to disable network sharing as this may impact the registration as suggested by [this Stack Overflow answer](https://stackoverflow.com/a/59156989/1123156).
---
Note: Restart your device
---
If you just changed the APNS servers where the app should be registering (by installing a TestFlight build over an Xcode build on the same device) you may need to restart your device as suggested by [this Stack Overflow answer](https://stackoverflow.com/a/59864028/1123156).
---
Note: Setup your device with a SIM card
---
If the device you're experiencing this on hasn't been setup with a SIM card it looks like configuring it may help mitigate this bug as suggested by [this Stack Overflow answer](https://stackoverflow.com/a/19432504/1123156).
---
<a id="miscellaneous"></a>
## 各种各样的
¥Miscellaneous
<a id="sending-notifications-directly-through-fcm-and-apns"></a>
### 直接通过 FCM 和 APN 发送通知
¥Sending notifications directly through FCM and APNs
如果你不使用 [Expo 推送通知服务](/push-notifications/sending-notifications)，而是想直接与 Google 和 Apple 沟通，请参阅 [使用 FCM 和 APN 发送通知](/push-notifications/sending-notifications-custom)。
¥If you are not using [Expo push notification service](/push-notifications/sending-notifications) and instead, would like to communicate with Google and Apple directly, see [Send notifications with FCM and APNs](/push-notifications/sending-notifications-custom).
<a id="notification-icon-on-android-is-a-grey-or-white-square"></a>
### Android 上的通知图标是灰色或白色方块
¥Notification icon on Android is a grey or white square
这表明你提供的图片资源存在问题。图片应为全白色并具有透明背景（这是 Google 而非 Expo 所要求和强制执行的）。欲了解更多信息，请参阅 [本文](https://clevertap.com/blog/fixing-notification-icon-for-android-lollipop-and-above/)。
¥This indicates an issue with the image asset you're providing. The image should be all white with a transparent background (this is required and enforced by Google, not Expo). For more information, see [this article](https://clevertap.com/blog/fixing-notification-icon-for-android-lollipop-and-above/).


# 更多

## 升级 Expo SDK

了解如何增量升级项目中的 Expo SDK 版本。

>  **info** 我们建议逐步升级 SDK 版本，一次一个。这样做将帮助你查明升级过程中出现的损坏和问题。
>
> ¥We recommend upgrading SDK versions incrementally, one at a time. Doing so will help you pinpoint breakages and issues that arise during the upgrade process.
随着新 SDK 的发布，最新版本将进入当前发布状态。这适用于 Expo Go，因为它仅支持最新的 SDK 版本，并且不再支持以前的版本。我们建议将 [开发构建](/develop/development-builds/introduction/) 用于生产应用，因为 EAS 服务上旧 SDK 版本的向后兼容性往往会更长，但不会永远持续下去。
¥With a new SDK release, the latest version enters the current release status. This applies to Expo Go as it only supports the latest SDK version and previous versions are no longer supported. We recommend using [development builds](/develop/development-builds/introduction/) for production apps as the backwards compatibility for older SDK versions on EAS services tends to be much longer, but not forever.
如果你希望安装特定版本的 Expo Go，请访问 [expo.dev/go](https://expo.dev/go)。它支持 Android 设备/模拟器和 iOS 模拟器的下载。但是，由于 iOS 平台限制，只有最新版本的 Expo Go 可用于在物理 iOS 设备上安装。
¥If you are looking to install a specific version of Expo Go, visit [expo.dev/go](https://expo.dev/go). It supports downloads for Android devices/emulators and iOS simulators. However, due to iOS platform restrictions, only the latest version of Expo Go is available for installation on physical iOS devices.
<a id="how-to-upgrade-to-the-latest-sdk-version"></a>
## 如何升级到最新的 SDK 版本
¥How to upgrade to the latest SDK version
Step 1: 
### Upgrade the Expo SDK
Install the new version of the Expo package:
!!!IG0!!!
!!!IG1!!!
```sh
$ npx expo install expo@latest
SDK 53)
$ npx expo install expo@^53.0.0
```
!!!IG2!!!
!!!IG3!!!
```sh
$ yarn expo install expo@latest
SDK 53)
$ yarn expo install expo@^53.0.0
```
!!!IG4!!!
!!!IG5!!!
Step 2: 
### Upgrade dependencies
Upgrade all dependencies to match the installed SDK version.
```sh
$ npx expo install --fix
```
Step 3: 
### Update native projects
- **If you use [Continuous Native Generation](/workflow/continuous-native-generation/)**: Delete the **android** and **ios** directories if you generated them for a previous SDK version in your local project directory. They'll be re-generated next time you run a build, either with `npx expo run:ios`, `npx expo prebuild`, or with EAS Build.
- **If you don't use [Continuous Native Generation](/workflow/continuous-native-generation/)**: Run `npx pod-install` if you have an `ios` directory. Apply any relevant changes from the [Native project upgrade helper](/bare/upgrade/). Alternatively, you could consider [adopting prebuild](/guides/adopting-prebuild/) for easier upgrades in the future.
Step 4: 
### Follow the release notes for any other instructions
Read the [SDK changelogs](#sdk-changelogs) for the SDK version you are upgrading to. They contain important information about breaking changes, deprecations, and other changes that may affect your app. Refer to tue "Upgrading your app" section at the bottom of the release notes page for any additional instructions.
## SDK Changelogs
Each SDK announcement release notes post contains information deprecations, breaking changes, and anything else that might be unique to that particular SDK version. When upgrading, be sure to check these out to make sure you don't miss anything.
- **SDK 53**: [Release notes](https://expo.dev/changelog/sdk-53)
- **SDK 52**: [Release notes](https://expo.dev/changelog/2024-11-12-sdk-52)
  - **React Native 0.77 is available with Expo SDK 52**. To upgrade, see these [Release notes](https://expo.dev/changelog/2025/01-21-react-native-0.77).
- **SDK 51**: [Release notes](https://expo.dev/changelog/2024-05-07-sdk-51)
### Deprecated SDK Version Changelogs
The following blog posts may included outdated information, but they are still useful for reference if you happen to fall far behind on SDK upgrades.
Note: See a full list of deprecated SDK release changelogs
---
- **SDK 50**: [Release notes](https://expo.dev/changelog/2024-01-18-sdk-50)
- **SDK 49**: [Release notes](https://blog.expo.dev/expo-sdk-49-c6d398cdf740)
- **SDK 48**: [Release notes](https://blog.expo.dev/expo-sdk-48-ccb8302e231)
- **SDK 47**: [Release notes](https://blog.expo.dev/expo-sdk-47-a0f6f5c038af)
- **SDK 46**: [Release notes](https://blog.expo.dev/expo-sdk-46-c2a1655f63f7)
- **SDK 45**: [Release notes](https://blog.expo.dev/expo-sdk-45-f4e332954a68)
- **SDK 44**: [Release notes](https://blog.expo.dev/expo-sdk-44-4c4b8306584a)
- **SDK 43**: [Release notes](https://blog.expo.dev/expo-sdk-43-aa9b3c7d5541)
- **SDK 42**: [Release notes](https://blog.expo.dev/expo-sdk-42-579aee2348b6)
- **SDK 41**: [Release notes](https://blog.expo.dev/expo-sdk-41-12cc5232f2ef)
- **SDK 40**: [Release notes](https://dev.to/expo/expo-sdk-40-is-now-available-1in0)
- **SDK 39**: [Release notes](https://dev.to/expo/expo-sdk-39-is-now-available-1lm8)
- **SDK 38**: [Release notes](https://dev.to/expo/expo-sdk-38-is-now-available-5aa0)
- **SDK 37**: [Release notes](https://dev.to/expo/expo-sdk-37-is-now-available-69g)
- **SDK 36**: [Release notes](https://blog.expo.dev/expo-sdk-36-is-now-available-b91897b437fe)
- **SDK 35**: [Release notes](https://blog.expo.dev/expo-sdk-35-is-now-available-beee0dfafbf4)
---


# 杂项

## 使用 OAuth 或 OpenID 提供商进行身份验证

了解如何利用 expo-auth-session 库通过 OAuth 或 OpenID 提供商实现身份验证。

[`expo-auth-session`](/versions/latest/sdk/auth-session) 提供了统一的 API，用于在 Android、iOS 和 Web 上实现 OAuth 和 OpenID Connect 提供程序。本指南将通过几个示例向你展示如何使用 `AuthSession` API。
¥[`expo-auth-session`](/versions/latest/sdk/auth-session) provides a unified API for implementing OAuth and OpenID Connect providers on Android, iOS, and web. This guide will show you how to use the `AuthSession` API using a few examples.
<a id="rules-for-all-authentication-providers"></a>
## 所有身份验证提供程序的规则
¥Rules for all authentication providers
使用 `AuthSession` API 时，以下规则适用于所有身份验证提供程序：
¥When using the `AuthSession` API, the following rules apply to all authentication providers:
* 使用 `WebBrowser.maybeCompleteAuthSession()` 关闭 Web 弹出窗口。如果你忘记添加此项，则弹出窗口将不会关闭。
  ¥Use `WebBrowser.maybeCompleteAuthSession()` to dismiss the web popup. If you forget to add this then the popup window will not close.
* 使用 `AuthSession.makeRedirectUri()` 创建重定向，这完成了与通用平台支持相关的大量繁重工作。在幕后，它使用 `expo-linking`。
  ¥Create redirects with `AuthSession.makeRedirectUri()` this does a lot of the heavy lifting involved with universal platform support. Behind the scenes, it uses `expo-linking`.
* 使用 `AuthSession.useAuthRequest()` 构建请求，该钩子允许异步设置，这意味着移动浏览器不会阻止身份验证。
  ¥Build requests using `AuthSession.useAuthRequest()`, the hook allows for async setup which means mobile browsers won't block the authentication.
* 确保在定义 `request` 之前禁用提示。
  ¥Be sure to disable the prompt until `request` is defined.
* 你只能在 Web 上的用户交互中调用 `promptAsync`。
  ¥You can only invoke `promptAsync` in user interaction on the web.
* 由于无法自定义你的应用方案，Expo Go 无法用于本地开发和测试支持 OAuth 或 OpenID Connect 的应用。你可以改为使用 [开发构建](/develop/development-builds/introduction/)，它可以实现类似于 Expo Go 的开发体验，并支持登录后 OAuth 重定向回你的应用，其工作方式与生产中的工作方式相同。
  ¥Expo Go cannot be used for local development and testing of OAuth or OpenID Connect-enabled apps due to the inability to customize your app scheme. You can instead use a [Development Build](/develop/development-builds/introduction/), which enables an Expo Go-like development experience and supports OAuth redirects back to your app after login in a manner that works just like it would in production.
<a id="obtaining-access-tokens"></a>
## 获取访问令牌
¥Obtaining access tokens
大多数提供程序使用 [OAuth 2](https://oauth.net/2/) 标准进行安全身份验证和授权。在授权代码授予中，身份提供者返回一次性代码。然后将此代码交换为用户的访问令牌。
¥Most providers use the [OAuth 2](https://oauth.net/2/) standard for secure authentication and authorization. In the authorization code grant, the identity provider returns a one-time code. This code is then exchanged for the user's access token.
由于 [你的客户端应用代码不是存储密钥的安全场所](https://rn.nodejs.cn/docs/security#storing-sensitive-info)，有必要在服务器中交换授权代码，例如与 [API 路由](/router/reference/api-routes) 或 [反应服务器组件](/guides/server-components)。这将允许你安全地存储和使用客户端密钥来访问提供商的令牌端点。
¥Since [your client application code is not a secure place to store secrets](https://rn.nodejs.cn/docs/security#storing-sensitive-info), it is necessary to exchange the authorization code in a server such as with [API routes](/router/reference/api-routes) or [React Server Components](/guides/server-components). This will allow you to securely store and use a client secret to access the provider's token endpoint.
<a id="examples"></a>
## 示例
¥Examples
以下示例展示了如何使用 `AuthSession` API 与一些常用提供商进行身份验证。
¥The following examples show how to use the `AuthSession` API to authenticate with a few popular providers.
<Box
  name="GitHub"
  createUrl="https://github.com/settings/developers"
  image={ASSETS.github}
>
| 网站                                               | 提供者       | PKCE | 自动发现 |
| ------------------------------------------------ | --------- | ---- | ---- |
| [获取你的配置](https://github.com/settings/developers) | OAuth 2.0 | 支持的  | 无法使用 |
* 提供商仅允许每个应用使用一个重定向 URI。对于要使用的每种方法，你都需要一个单独的应用：
  ¥Provider only allows one redirect URI per app. You'll need an individual app for every method you want to use:
  * 独立/开发构建：`com.your.app://*`
    ¥Standalone / development build: `com.your.app://*`
  * 网址：`https://yourwebsite.com/*`
    ¥Web: `https://yourwebsite.com/*`
* `redirectUri` 需要两个斜杠（`://`）。
  ¥The `redirectUri` requires two slashes (`://`).
* `revocationEndpoint` 是动态的，需要你的 `config.clientId`。
  ¥`revocationEndpoint` is dynamic and requires your `config.clientId`.
```tsx GitHub Auth Example
import { useEffect } from 'react';
import * as WebBrowser from 'expo-web-browser';
import { makeRedirectUri, useAuthRequest } from 'expo-auth-session';
import { Button } from 'react-native';
WebBrowser.maybeCompleteAuthSession();
// Endpoint
const discovery = {
  authorizationEndpoint: 'https://github.com/login/oauth/authorize',
  tokenEndpoint: 'https://github.com/login/oauth/access_token',
  revocationEndpoint: 'https://github.com/settings/connections/applications/<CLIENT_ID>',
};
export default function App() {
  const [request, response, promptAsync] = useAuthRequest(
    {
      clientId: 'CLIENT_ID',
      scopes: ['identity'],
      redirectUri: makeRedirectUri({
        scheme: 'your.app'
      }),
    },
    discovery
  );
  useEffect(() => {
    if (response?.type === 'success') {
      const { code } = response.params;
    }
  }, [response]);
  return (
    <Button
      disabled={!request}
      title="Login"
      onPress={() => {
        promptAsync();
      }}
    />
  );
}
```
</Box>
<Box
  name="Okta"
  createUrl="https://developer.okta.com/signup"
  image={ASSETS.okta}
>
| 网站                                            | 提供者    | PKCE | 自动发现 |
| --------------------------------------------- | ------ | ---- | ---- |
| [报名](https://developer.okta.com/signup/) > 应用 | OpenID | 支持的  | 可用的  |
* 你无法定义自定义 `redirectUri`，Okta 将为你提供一个。
  ¥You cannot define a custom `redirectUri`, Okta will provide you with one.
```tsx Okta Auth Example
import { useEffect } from 'react';
import * as WebBrowser from 'expo-web-browser';
import { makeRedirectUri, useAuthRequest, useAutoDiscovery } from 'expo-auth-session';
import { Button, Platform } from 'react-native';
WebBrowser.maybeCompleteAuthSession();
export default function App() {
  // Endpoint
  const discovery = useAutoDiscovery('https://<OKTA_DOMAIN>.com/oauth2/default');
  // Request
  const [request, response, promptAsync] = useAuthRequest(
    {
      clientId: 'CLIENT_ID',
      scopes: ['openid', 'profile'],
      redirectUri: makeRedirectUri({
        native: 'com.okta.<OKTA_DOMAIN>:/callback',
      }),
    },
    discovery
  );
  useEffect(() => {
    if (response?.type === 'success') {
      const { code } = response.params;
    }
  }, [response]);
  return (
    <Button
      disabled={!request}
      title="Login"
      onPress={() => {
        promptAsync();
      }}
    />
  );
}
```
</Box>
{/* End Okta */}
<a id="redirect-uri-patterns"></a>
## 重定向 URI 模式
¥Redirect URI patterns
以下是你可能最终使用的一些常见重定向 URI 模式的示例。
¥Here are a few examples of some common redirect URI patterns you may end up using.
<a id="standalonedevelopment-build"></a>
### 独立/开发构建
¥Standalone/development build
> `yourscheme://path`
在某些情况下，会有 1 到 3 个斜杠 (`/`)。
¥In some cases there will be anywhere between 1 to 3 slashes (`/`).
* **环境：**
  ¥**Environment:**
  * 裸工作流程
    ¥Bare workflow
    * `npx expo prebuild`
  * 在 App 或 Play Store 中独立构建或在本地测试
    ¥Standalone builds in the App or Play Store or testing locally
    * 安卓：`eas build` 或 `npx expo run:android`
      ¥Android: `eas build` or `npx expo run:android`
    * iOS：`eas build` 或 `npx expo run:ios`
      ¥iOS: `eas build` or `npx expo run:ios`
* 创造：在正确的环境中运行时使用 `AuthSession.makeRedirectUri({ native: '<YOUR_URI>' })` 选择原生。
  ¥**Create:** Use `AuthSession.makeRedirectUri({ native: '<YOUR_URI>' })` to select native when running in the correct environment.
  * `your.app://redirect` -> `makeRedirectUri({ scheme: 'your.app', path: 'redirect' })`
  * `your.app:///` -> `makeRedirectUri({ scheme: 'your.app', isTripleSlashed: true })`
  * `your.app:/authorize` -> `makeRedirectUri({ native: 'your.app:/authorize' })`
  * `your.app://auth?foo=bar` -> `makeRedirectUri({ scheme: 'your.app', path: 'auth', queryParams: { foo: 'bar' } })`
  * `exp://u.expo.dev/[project-id]?channel-name=[channel-name]&runtime-version=[runtime-version]` -> `makeRedirectUri()`
  * 此链接通常可以自动创建，但我们建议你至少定义 `scheme` 属性。可以通过传递 `native` 属性在应用中覆盖整个 URL。通常，这将用于 Google 或 Okta 等要求你使用自定义原生 URI 重定向的提供商。你可以使用 `npx uri-scheme` 添加、列出和打开 URI 方案。
    ¥This link can often be created automatically but we recommend you define the `scheme` property at least. The entire URL can be overridden in apps by passing the `native` property. Often this will be used for providers like Google or Okta which require you to use a custom native URI redirect. You can add, list, and open URI schemes using `npx uri-scheme`.
  * 如果在弹出后更改 `expo.scheme`，则需要使用 `expo apply` 命令将更改应用到原生项目，然后重建它们（`yarn ios`、`yarn android`）。
    ¥If you change the `expo.scheme` after ejecting then you'll need to use the `expo apply` command to apply the changes to your native project, then rebuild them (`yarn ios`, `yarn android`).
* 用法：`promptAsync({ redirectUri })`
  ¥**Usage:** `promptAsync({ redirectUri })`
<a id="improving-user-experience"></a>
## 改善用户体验
¥Improving user experience
"登录流程" 是一件需要做好的重要事情，在很多情况下，这是用户 promise 再次使用你的应用的地方。糟糕的体验可能会导致用户在真正开始使用你的应用之前就放弃它。
¥The "login flow" is an important thing to get right, in a lot of cases this is where the user will *commit* to using your app again. A bad experience can cause users to give up on your app before they've really gotten to use it.
以下是一些技巧，可帮助你快速、轻松、安全地进行用户身份验证：
¥Here are a few tips you can use to make authentication quick, easy, and secure for your users:
<a id="warming-the-browser"></a>
### 预热浏览器
¥Warming the browser
在 Android 上，你可以选择在使用网络浏览器之前对其进行预热。这允许浏览器应用在后台预先初始化自身。这样做可以显着加快提示用户进行身份验证的速度。
¥On Android you can optionally warm up the web browser before it's used. This allows the browser app to pre-initialize itself in the background. Doing this can significantly speed up prompting the user for authentication.
```tsx
import { useEffect } from 'react';
import * as WebBrowser from 'expo-web-browser';
function App() {
  useEffect(() => {
    WebBrowser.warmUpAsync();
    return () => {
      WebBrowser.coolDownAsync();
    };
  }, []);
  // Do authentication ...
}
```
<a id="implicit-login"></a>
### 隐式登录
¥Implicit login
由于没有安全的方法来将客户端密钥存储在应用包中，因此历史上许多提供商都提供了 "隐式流"，它使你能够在没有客户端密钥的情况下请求访问令牌。由于固有的安全风险（包括访问令牌注入的风险），不再建议这样做。相反，大多数提供商现在支持带有 PKCE（代码交换证明密钥）扩展的授权代码，以便在客户端应用代码中安全地交换授权代码以获取访问令牌。了解有关 [从隐式流程过渡到使用 PKCE 的授权代码](https://oauth.net/2/grant-types/implicit/) 的更多信息。
¥Because there was no secure way to do this to store client secrets in your app bundle, historically, many providers have offered an "Implicit flow" which enables you to request an access token without the client secret. **This is no longer recommended** due to inherent security risks, including the risk of access token injection. Instead, most providers now support the authorization code with PKCE (Proof Key for Code Exchange) extension to securely exchange an authorization code for an access token within your client app code. Learn more about [transitioning from Implicit flow to authorization code with PKCE](https://oauth.net/2/grant-types/implicit/).
`expo-auth-session` 仍然支持用于旧版代码目的的隐式流。下面是隐式流程的示例实现。
¥`expo-auth-session` still supports Implicit flow for legacy code purposes. Below is an example implementation of the Implicit flow.
```tsx
import { useEffect } from 'react';
import * as WebBrowser from 'expo-web-browser';
import { makeRedirectUri, useAuthRequest, ResponseType } from 'expo-auth-session';
WebBrowser.maybeCompleteAuthSession();
// Endpoint
const discovery = {
  authorizationEndpoint: 'https://accounts.spotify.com/authorize',
};
function App() {
  const [request, response, promptAsync] = useAuthRequest(
    {
      responseType: ResponseType.Token,
      clientId: 'CLIENT_ID',
      scopes: ['user-read-email', 'playlist-modify-public'],
      redirectUri: makeRedirectUri({
        scheme: 'your.app'
      }),
    },
    discovery
  );
  useEffect(() => {
    if (response && response.type === 'success') {
      const token = response.params.access_token;
    }
  }, [response]);
  return <Button disabled={!request} onPress={() => promptAsync()} title="Login" />;
}
```
<a id="storing-data"></a>
### 存储数据
¥Storing data
在 Android 和 iOS 等原生平台上，你可以使用名为 [`expo-secure-store`](/versions/latest/sdk/securestore) 的库在本地保护访问令牌等内容（这与不安全的 `AsyncStorage` 不同）。Android 上支持原生访问加密的 [`SharedPreferences`](https://developer.android.com/training/basics/data-storage/shared-preferences.html)，iOS 上支持 [密钥扣服务](https://developer.apple.com/documentation/security/keychain_services)。目前没有与此功能等效的 Web 应用。
¥On native platforms such as Android and iOS, you can secure things like access tokens locally using a library called [`expo-secure-store`](/versions/latest/sdk/securestore) (This is different to `AsyncStorage` which is not secure). It provides native access to encrypted [`SharedPreferences`](https://developer.android.com/training/basics/data-storage/shared-preferences.html) on Android and [keychain services](https://developer.apple.com/documentation/security/keychain_services) on iOS and . There is no web equivalent to this functionality.
你可以存储身份验证结果并在以后重新水化它们，以避免提示用户再次登录。
¥You can store your authentication results and rehydrate them later to avoid having to prompt the user to login again.
```tsx
import * as SecureStore from 'expo-secure-store';
const MY_SECURE_AUTH_STATE_KEY = 'MySecureAuthStateKey';
function App() {
  const [, response] = useAuthRequest({});
  useEffect(() => {
    if (response && response.type === 'success') {
      const auth = response.params;
      const storageValue = JSON.stringify(auth);
      if (Platform.OS !== 'web') {
        // Securely store the auth on your device
        SecureStore.setItemAsync(MY_SECURE_AUTH_STATE_KEY, storageValue);
      }
    }
  }, [response]);
  // More login code...
}
```


## 使用 Hermes Engine

有关在 Expo 项目中为 Android 和 iOS 配置 Hermes 的指南。

[Hermes](https://hermesengine.dev/) 是一个针对 React Native 优化的 JavaScript 引擎。通过提前将 JavaScript 编译为字节码，Hermes 可以缩短你的应用启动时间。Hermes 的二进制大小也比其他 JavaScript 引擎小，例如 JavaScriptCore (JSC)。它还在运行时使用更少的内存，这对于低端 Android 设备尤其有价值。
¥[Hermes](https://hermesengine.dev/) is a JavaScript engine optimized for React Native. By compiling JavaScript into bytecode ahead of time, Hermes can improve your app start-up time. The binary size of Hermes is also smaller than other JavaScript engines, such as JavaScriptCore (JSC). It also uses less memory at runtime, which is particularly valuable on lower-end Android devices.
<a id="support"></a>
## 支持
¥Support
Hermes 引擎是 Expo 使用的默认 JavaScript 引擎，所有 Expo 工具都完全支持它。
¥The Hermes engine is the default JavaScript engine used by Expo and it is fully supported across all Expo tooling.
<a id="switch-javascript-engine-on-a-specific-platform"></a>
### 在特定平台上切换 JavaScript 引擎
¥Switch JavaScript engine on a specific platform
你可能想在一个平台上使用 Hermes，而在另一平台上使用 JSC。一种方法是在应用配置的顶层将 `"jsEngine"` 设置为 `"hermes"`，然后在 `"ios"` 键下用 `"jsc"` 覆盖它。在这种情况下，你可能更愿意仅在 `"android"` 键上显式设置 `"hermes"`。
¥You may want to use Hermes on one platform and JSC on another. One way to do this is to set the `"jsEngine"` to `"hermes"` at the top level in app config and then override it with `"jsc"` under the `"ios"` key. You may alternatively prefer to explicitly set `"hermes"` on just the `"android"` key in this case.
```json app.json
{
  "expo": {
    "jsEngine": "hermes",
    "ios": {
      "jsEngine": "jsc"
    }
  }
}
```
<a id="publish-updates"></a>
## 发布更新
¥Publish updates
使用 `eas update` 和 `npx expo export` 发布更新将生成 Hermes 字节码包及其源映射。
¥Publishing updates with `eas update` and `npx expo export` will generate Hermes bytecode bundles and their source maps.
请注意，Hermes 字节码格式可能会在不同的 Hermes 版本之间发生变化 - 为特定版本的 Hermes 生成的更新将无法在不同版本的 Hermes 上运行。从 Expo SDK 46（React Native 0.69）、[Hermes 打包在 React Native 中](https://rn.nodejs.cn/architecture/bundled-hermes) 开始。更新 React Native 版本或 Hermes 版本可以被视为与更新任何其他原生模块相同的方式。因此，如果你更新 `react-native` 版本，你还应该更新 app.json 中的 `runtimeVersion`。如果你不这样做，你的应用可能会在启动时崩溃，因为更新可能是由使用与更新的字节码格式不兼容的旧 Hermes 版本的现有二进制文件加载的。请参阅 [`runtimeVersion`](/eas-update/runtime-versions/) 了解更多信息。
¥Note that the Hermes bytecode format may change between different Hermes versions — an update produced for a specific version of Hermes will not run on a different version of Hermes. Starting from Expo SDK 46 (React Native 0.69), [Hermes is bundled within React Native](https://rn.nodejs.cn/architecture/bundled-hermes). Updating React Native version or Hermes version can be thought of in the same way as updating any other native module. So if you update the `react-native` version you should also update the `runtimeVersion` in **app.json**. If you don't do this, your app may crash on launch because the update may be loaded by an existing binary that uses an older Hermes version that is incompatible with the updated bytecode format. See [`runtimeVersion`](/eas-update/runtime-versions/) for more information.
<a id="javascript-debugger"></a>
## JavaScript 调试器
¥JavaScript debugger
要调试使用 Hermes 运行的 JavaScript 代码，你可以使用 `npx expo start` 启动项目，然后按 <kbd>j</kbd> 在 Google Chrome 或 Microsoft Edge 中打开调试器。开发版本和 Expo Go 的开发者菜单也有 Open JS Debugger 选项来执行相同的操作。
¥To debug JavaScript code running with Hermes, you can start your project with `npx expo start` then press <kbd>j</kbd> to open the debugger in Google Chrome or Microsoft Edge. The developer menu of development builds and Expo Go also have the **Open JS Debugger** option to do the same.
或者，你可以通过打开 [手动使用 Google Chrome DevTools](https://rn.nodejs.cn/docs/other-debugging-methods#remote-javascript-debugging-deprecated) 来使用 JavaScript 检查器。
¥Alternatively, you can use the JavaScript inspector by opening [Google Chrome DevTools manually](https://rn.nodejs.cn/docs/other-debugging-methods#remote-javascript-debugging-deprecated)
<a id="troubleshooting"></a>
### 故障排除
¥Troubleshooting
>  **warning** 打开调试器时的 `No compatible apps connected. JavaScript Debugging can only be used with the Hermes engine.`。
>
> ¥`No compatible apps connected. JavaScript Debugging can only be used with the Hermes engine.` when opening the debugger.
* 确保你 [在 `jsEngine` 字段设立 Hermes](#setup)。
  ¥Make sure you [set up Hermes in the `jsEngine` field](#setup).
* 如果你的应用是由 `eas build`、`npx expo run:android` 或 `npx expo run:ios` 构建的，请确保它是调试版本。
  ¥If your app is built by `eas build`, `npx expo run:android` or `npx expo run:ios`, make sure it is a debug build.
* 在内部，应用将建立 WebSocket 连接，确保你的应用已连接到开发服务器。
  ¥Internally, the app will establish a WebSocket connection, make sure your app is connected to the development server.
  * 尝试通过在 Expo CLI 终端 UI 中按 <kbd>r</kbd> 来重新加载应用。
    ¥Try to reload the app by pressing <kbd>r</kbd> in the Expo CLI Terminal UI.
  * 通过运行以下命令测试调试可用性：`curl http://127.0.0.1:8081/json/list`（调整 `127.0.0.1:8081` 以匹配你的开发服务器 URL）。HTTP 响应应该是一个数组，如下所示。如果是空响应，请将 `--localhost` 或 `--tunnel` 标志添加到 `npx expo start` 命令中。
    ¥Test debugging availability by running the command: `curl http://127.0.0.1:8081/json/list` (adjust the `127.0.0.1:8081` to match your dev server URL). The HTTP response should be an array, as shown below. If it is an empty response, add either the `--localhost` or `--tunnel` flag to the `npx expo start` command.
```json
  [
    {
      "id": "0-2",
      "description": "host.exp.Exponent",
      "title": "Hermes ABI47_0_0React Native",
      "faviconUrl": "https://react.nodejs.cn/favicon.ico",
      "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=%5B%3A%3A1%5D%3A8081%2Finspector%2Fdebug%3Fdevice%3D0%26page%3D2",
      "type": "node",
      "webSocketDebuggerUrl": "ws://[::1]:8081/inspector/debug?device=0&page=2",
      "vm": "Hermes"
    },
    {
      "id": "0--1",
      "description": "host.exp.Exponent",
      "title": "React Native Experimental (Improved Chrome Reloads)",
      "faviconUrl": "https://react.nodejs.cn/favicon.ico",
      "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=%5B%3A%3A1%5D%3A8081%2Finspector%2Fdebug%3Fdevice%3D0%26page%3D-1",
      "type": "node",
      "webSocketDebuggerUrl": "ws://[::1]:8081/inspector/debug?device=0&page=-1",
      "vm": "don't use"
    }
  ]
  ```
<a id="can-i-use-remote-debugging-with-hermes"></a>
### 我可以使用 Hermes 进行远程调试吗？
¥Can I use Remote Debugging with Hermes?
[远程调试](/more/glossary-of-terms/#remote-debugging) 的众多限制之一是它不能与构建在 [JSI](https://github.com/react-native-community/discussions-and-proposals/issues/91) 之上的模块一起使用，例如 [`react-native-reanimated`](https://github.com/software-mansion/react-native-reanimated) 版本 2 或更高版本。
¥One of the many limitations of [remote debugging](/more/glossary-of-terms/#remote-debugging) is that it does not work with modules built on top of [JSI](https://github.com/react-native-community/discussions-and-proposals/issues/91), such as [`react-native-reanimated`](https://github.com/software-mansion/react-native-reanimated) version 2 or higher.
Hermes 支持 [Chrome 开发者工具协议](https://chromedevtools.github.io/devtools-protocol/v8/) 通过连接到设备上运行的引擎来就地调试 JavaScript，而不是远程调试（在桌面 Chrome 选项卡中执行 JavaScript）。当你在 Expo Go 或开发版本中打开调试器时，Hermes 应用会自动使用此调试技术。
¥Hermes supports [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/v8/) to debug JavaScript in place by connecting to the engine running on the device, as opposed to remote debugging, which executes JavaScript within a desktop Chrome tab. Hermes apps use this debugging technique automatically when you open the debugger in Expo Go or a development build.


## iOS 开发者模式

了解如何在 iOS 16 及更高版本上启用 iOS 开发者模式以运行内部发行版本和本地开发版本。

> 这不适用于使用企业配置签名的构建或安装在 iOS 模拟器上的任何构建。
>
> ¥This does not apply to builds signed using enterprise provisioning or to any builds installed on an iOS Simulator.
运行 iOS 16 及更高版本的设备需要启用操作系统级别的开发者模式设置，然后才能在设备上安装后运行 [内部分配](/build/internal-distribution) 版本（包括使用 EAS 构建的版本）或本地开发版本。
¥Devices running iOS 16 and above need to enable OS-level **Developer Mode** setting before they can run [internal distribution](/build/internal-distribution) builds (including those built with EAS) or local development builds after installing them on the device.
你可以通过两种方式在设备上启用开发者模式：
¥There are two ways you can enable Developer Mode on your device:
* 直接在 iOS 设备上
  ¥Directly on an iOS device
* 通过将 iOS 设备与安装了 Xcode 的 Mac 连接
  ¥By connecting an iOS device with a Mac that has Xcode installed
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
每个设备都需要遵循下面指定的说明一次。
¥The instructions specified below need to be followed once per device.
<a id="enable-developer-mode"></a>
## 启用开发者模式
¥Enable Developer Mode
<a id="directly-on-an-ios-device"></a>
### 直接在 iOS 设备上
¥Directly on an iOS device
要按照以下步骤操作，请在启用开发者模式之前在你的设备上安装你的开发版本。构建完成后，请按照 EAS 仪表板上的说明将其安装到你的 iOS 设备上。
¥To follow the steps below, **install your development build on your device before enabling the Developer Mode.** When the build is created, follow the instructions on the EAS dashboard to install it on your iOS device.
Step 1: 
Once the build is installed on your device, press the app icon. This will open an alert asking you to enable Developer Mode. Press **OK**.
Step 2: 
Go to the Settings app, and navigate to **Privacy & Security** > **Developer Mode**.
Step 3: 
Enable the toggle. You will receive a prompt from iOS to restart your device. Press **Restart**.
Step 4: 
After the device restarts, unlock your device. A system alert should appear. Press **Turn On** and then, when prompted, enter your device's passcode.
Developer Mode is now enabled. You can now interact with your internal distribution builds and local development builds.
You can turn off Developer Mode at any time. However, you'll need to repeat this same process to re-enable it.
### Connect an iOS device with a Mac
> **Note:** Xcode must be installed on the Mac device before following the steps below.
You don't need to install the development build on your iOS device first to enable Developer Mode by connecting it to a Mac. You can:
Step 1: 
Connect your iOS device to a Mac using a USB cable. Press **Trust** on your iOS device when **Trust This Computer?** alert is prompted.
Step 2: 
Open Xcode, and from the menu bar, navigate to **Window** > **Devices and Simulators**.
Under **Devices**, you'll see a warning "Previous preparation error: Developer Mode disabled" with instructions on enabling Developer Mode on the iOS device.
Step 3: 
On the iOS device, open **Settings** > **Privacy & Security** > **Developer Mode**.
Enable the toggle. You will receive a prompt from iOS to restart your device. Press **Restart**.
Step 4: 
After the device restarts, unlock your device. A system alert should appear. Press **Turn On**, and enter your device's passcode when prompted.
开发者模式现已启用。你现在可以与内部发行版本和本地开发版本进行交互。
¥Developer Mode is now enabled. You can now interact with your internal distribution builds and local development builds.
你可以随时关闭开发者模式。但是，你需要重复相同的过程才能重新启用它。
¥You can turn off Developer Mode at any time. However, you'll need to repeat this same process to re-enable it.


## Expo 矢量图标

了解如何在 Expo 应用中使用各种类型的图标，包括 React Native 矢量图标、自定义图标字体、图标图片和图标按钮。

并非每个应用都需要使用表情符号作为图标。你可以通过图标字体（例如 FontAwesome、Glyphicons 或 Ionicons）使用流行的图标集，或者选择 [名词项目](https://thenounproject.com/) 中的 PNG。本指南介绍了在 Expo 应用中使用图标的各种方法。
¥Not every app needs to use emojis for icons. You can use a popular icon set through an icon font such as FontAwesome, Glyphicons, or Ionicons, or choose PNGs from [The Noun Project](https://thenounproject.com/). This guide explains various ways to use icons in your Expo app.
<a id="expovector-icons"></a>
## `@expo/vector-icons`
`@expo/vector-icons` 库默认安装在使用 `npx create-expo-app` 的模板项目上，并且是 `expo` 包的一部分。它构建在 [`react-native-vector-icons`](https://github.com/oblador/react-native-vector-icons) 之上并使用类似的 API。它包括你可以在 [icons.expo.fyi](https://icons.expo.fyi) 浏览的流行图标集。
¥The `@expo/vector-icons` library is installed by default on the template project using `npx create-expo-app` and is part of the `expo` package. It is built on top of [`react-native-vector-icons`](https://github.com/oblador/react-native-vector-icons) and uses a similar API. It includes popular icon sets you can browse at [icons.expo.fyi](https://icons.expo.fyi).
在以下示例中，该组件加载 `Ionicons` 字体并渲染复选标记图标：
¥The component loads the `Ionicons` font and renders a checkmark icon in the following example:
#### Vector icons
  ```jsx collapseHeight=350
import { View, StyleSheet } from 'react-native';
import Ionicons from '@expo/vector-icons/Ionicons';
export default function App() {
  return (
    <View style={styles.container}>
      <Ionicons name="checkmark-circle" size={32} color="green" />
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
> 与 Expo 中的 [任何自定义字体](/develop/user-interface/fonts/#use-a-local-font-file) 一样，你可以在渲染应用之前预加载图标字体。字体对象可用作字体组件上的静态属性。因此，在上面的例子中，它是 `Ionicons.font`，其计算结果是 `{ionicons: require('path/to/ionicons.ttf')}`。
>
> ¥As with [any custom font](/develop/user-interface/fonts/#use-a-local-font-file) in Expo, you can preload icon fonts before rendering your app. The font object is available as a static property on the font component. So, in the case above, it is `Ionicons.font`, which evaluates to `{ionicons: require('path/to/ionicons.ttf')}`.
<a id="custom-icon-fonts"></a>
## 自定义图标字体
¥Custom icon fonts
要使用自定义图标字体，请首先将其导入到你的项目中。只有在字体加载后，你才能创建图标集。[了解有关加载自定义字体的更多信息](/develop/user-interface/fonts/#handle-expovector-icons-initial-load)。
¥To use a custom icon font, first import it into your project. Only after the font has loaded, can you create an Icon set. [Learn more about loading custom fonts](/develop/user-interface/fonts/#handle-expovector-icons-initial-load).
`@expo/vector-icons` 公开了三种方法来帮助你创建图标集：
¥`@expo/vector-icons` exposes three methods to help you create an icon set:
<a id="createiconset"></a>
### `createIconSet`
`createIconSet` 方法返回基于 `glyphMap` 的自定义字体，其中键是图标名称，值是 UTF-8 字符或其字符代码。
¥The `createIconSet` method returns a custom font based on the `glyphMap` where the key is the icon name and the value is either a UTF-8 character or its character code.
在下面的示例中，定义了 `glyphMap` 对象，然后将其作为第一个参数传递给 `createIconSet` 方法。第二个参数 `fontFamily` 是字体的名称（不是文件名）。或者，你可以传递 Android 支持的第三个参数，即自定义字体文件名。
¥In the example below, the `glyphMap` object is defined and then passed as the first argument to the `createIconSet` method. The second argument `fontFamily` is the name of the font (not the filename). Optionally, you can pass the third argument for Android support, which is the custom font file name.
```jsx createIconSet example
import createIconSet from '@expo/vector-icons/createIconSet';
const glyphMap = { 'icon-name': 1234, test: '∆' };
const CustomIcon = createIconSet(glyphMap, 'fontFamily', 'custom-icon-font.ttf');
export default function CustomIconExample() {
  return <CustomIcon name="icon-name" size={32} color="red" />;
}
```
<a id="createiconsetfromicomoon"></a>
### `createIconSetFromIcoMoon`
`createIconSetFromIcoMoon` 方法用于基于 [IcoMoon](https://icomoon.io/) 配置文件创建自定义字体。你必须将 selection.json 和.ttf 保存在项目中，最好保存在 assets 目录中，然后使用 `useFonts` 钩子或 `expo-font` 中的 `Font.loadAsync` 方法加载字体。
¥The `createIconSetFromIcoMoon` method is used to create a custom font based on an [IcoMoon](https://icomoon.io/) config file. You have to save the **selection.json** and **.ttf** in your project, preferably in the **assets** directory, and then load the font using either `useFonts` hook or `Font.loadAsync` method from `expo-font`.
请参阅下面的示例，该示例使用 `useFonts` 钩子来加载字体：
¥See the example below that uses the `useFonts` hook to load the font:
#### Icomoon Icons
  ```jsx
import React from 'react';
import { View, StyleSheet } from 'react-native';
import { useFonts } from 'expo-font';
import createIconSetFromIcoMoon from '@expo/vector-icons/createIconSetFromIcoMoon';
const Icon = createIconSetFromIcoMoon(
  require('./assets/icomoon/selection.json'),
  'IcoMoon',
  'icomoon.ttf'
);
export default function App() {
  const [fontsLoaded] = useFonts({
    IcoMoon: require('./assets/icomoon/icomoon.ttf'),
  });
  if (!fontsLoaded) {
    return null;
  }
  return (
    <View style={styles.container}>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
<a id="createiconsetfromfontello"></a>
### `createIconSetFromFontello`
`createIconSetFromFontello` 方法用于基于 [Fontello](http://fontello.com/) 配置文件创建自定义字体。你必须将 config.json 和 .ttf 保存在项目中方便的位置，最好是在 asset 目录中，然后使用 `useFonts` 钩子或 `expo-font` 中的 `Font.loadAsync` 方法加载字体。
¥The `createIconSetFromFontello` method is used to create a custom font based on a [Fontello](http://fontello.com/) config file. You have to save the **config.json** and **.ttf** somewhere convenient in your project, preferably in the **assets** directory, and then load the font using either `useFonts` hook or `Font.loadAsync` method from `expo-font`.
它遵循与 `createIconSetFromIcoMoon` 类似的配置，如示例所示：
¥It follows a similar configuration as `createIconSetFromIcoMoon` as shown in the example:
```js Fontello Icons
// Import the createIconSetFromFontello method
import createIconSetFromFontello from '@expo/vector-icons/createIconSetFromFontello';
// Import the config file
import fontelloConfig from './config.json';
// Both the font name and files exported from Fontello are most likely called "fontello".
// Ensure this is the `fontname.ttf` and not the file path.
const Icon = createIconSetFromFontello(fontelloConfig, 'fontello', 'fontello.ttf');
```
<a id="icon-images"></a>
## 图标图片
¥Icon images
你可以使用 [Expo 图片](/versions/latest/sdk/image/) 或 React Native 中的 `Image` 组件来显示图标。`source` 属性采用相对路径来引用图片。
¥You can use the `Image` component from [Expo Image](/versions/latest/sdk/image/) or React Native to display an icon. The `source` prop takes the relative path to refer to the image.
For Expo Image: 
#### Usage with Expo Image
  ```jsx collapseHeight=440
import { Image } from 'expo-image';
import { View, StyleSheet } from 'react-native';
export default function App() {
  return (
    <View style={styles.container}>
      <Image source={require('./assets/images/slack-icon.png')} style={{ width: 50, height: 50 }} />
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
For React Native Image: 
#### Usage with React Native Image
  ```jsx
import { Image, View, StyleSheet } from 'react-native';
export default function App() {
  return (
    <View style={styles.container}>
      <Image source={require('./assets/images/slack-icon.png')} style={{ width: 50, height: 50 }} />
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
你还可以提供不同像素密度的不同版本的图标。`Image` 组件负责自动使用具有适当像素密度的图片。例如，如果图片具有 `icon@2x.png` 和 `icon@3x.png` 等变体，则 `@2x` 后缀用于表示 iPhone 8 等较旧设备的设备屏幕密度，而 `@3x` 后缀用于表示 iPhone 13 等较新设备上的设备屏幕密度。[在 React Native 文档中了解有关提供不同密度的更多信息](https://rn.nodejs.cn/docs/images#static-image-resources)。
¥You can also provide different versions of your icon at various pixel densities. The `Image` component takes care of using the image with appropriate pixel density automatically. For example, if the image has variants such as `icon@2x.png` and `icon@3x.png`, the `@2x` suffix is served for a device's screen density for older devices such as iPhone 8 and the `@3x` suffix is served for a device's screen density on newer devices such as iPhone 13. [Learn more about serving different densities in React Native documentation](https://rn.nodejs.cn/docs/images#static-image-resources).
<a id="button-component"></a>
## 按钮组件
¥Button component
你可以使用 `Font.Button` 语法创建图标按钮，其中 `Font` 是你从 `@expo/vector-icons` 导入的图标集。
¥You can create an Icon Button using the `Font.Button` syntax where the `Font` is the icon set that you import from `@expo/vector-icons`.
在下面的示例中，登录按钮使用 `FontAwesome` 图标集。请注意，`FontAwesome.Button` 组件接受 props 来处理按下按钮时的操作，并且可以封装按钮的文本。
¥In the example below, a login button uses the `FontAwesome` icon set. Notice that the `FontAwesome.Button` component accepts props to handle action when a button is pressed and can wrap the text of the button.
#### Icon Button Component
  ```jsx
import React from 'react';
import { View, StyleSheet } from 'react-native';
import FontAwesome from '@expo/vector-icons/FontAwesome';
export default function App() {
  const loginWithFacebook = () => {
    console.log('Button pressed');
  };
  return (
    <View style={styles.container}>
      <FontAwesome.Button name="facebook" backgroundColor="#3b5998" onPress={loginWithFacebook}>
        Login with Facebook
      </FontAwesome.Button>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
<a id="properties"></a>
### 属性
¥Properties
除以下属性之外的任何 [`Text`](http://rn.nodejs.cn/docs/text)、[`TouchableHighlight`](http://rn.nodejs.cn/docs/touchablehighlight) 或 [`TouchableWithoutFeedback`](http://rn.nodejs.cn/docs/touchablewithoutfeedback) 属性：
¥Any [`Text`](http://rn.nodejs.cn/docs/text), [`TouchableHighlight`](http://rn.nodejs.cn/docs/touchablehighlight), or [`TouchableWithoutFeedback`](http://rn.nodejs.cn/docs/touchablewithoutfeedback) property in addition to these:
| 属性                | 描述                                                      | 默认                  |
| ----------------- | ------------------------------------------------------- | ------------------- |
| `color`           | 文本和图标颜色，如果需要不同的颜色，请使用 `iconStyle` 或嵌套 `Text` 组件。        | `white`             |
| `size`            | 图标大小。                                                   | `20`                |
| `iconStyle`       | 仅应用于图标的样式，适合设置边距或不同的颜色。注意：使用 `iconStyle` 作为边距或预期不稳定的行为。 | `{marginRight: 10}` |
| `backgroundColor` | 按钮的背景颜色。                                                | `#007AFF`           |
| `borderRadius`    | 按钮的边框半径，设置为 `0` 即可禁用。                                   | `5`                 |
| `onPress`         | 按下按钮时调用的函数。                                             | 没有任何                |


## 本土化

了解如何使用 expo-localization 在 Expo 项目中开始和配置本地化。

如果你希望你的应用易于使用不同语言或来自不同文化的用户，则应该对其进行本地化。本地化应用可以使其适应用户设备的区域设置。该应用将显示用户知道和理解的翻译和货币。数字、列表等将以用户习惯的方式格式化。
¥If you want your app to be easy to use for users who speak different languages or come from different cultures, you should localize it. Localizing an app makes it adapt to the locale of the user's device. The app will show translations and currencies that the user knows and understands. Numbers, lists, and more will be formatted in a way that the user is used to.
本指南使用 `expo-localization` 库来访问用户语言设置并添加对多种语言的支持。以 `i18n-js` 为例添加多语言支持。
¥This guide uses the `expo-localization` library for accessing user language settings and adding support for multiple languages. It uses `i18n-js` as an example to add multi-language support.
<a id="getting-the-users-language"></a>
## 获取用户的语言
¥Getting the user's language
使用 [`expo-localization`](/versions/latest/sdk/localization/) 库获取用户当前的语言。通过运行以下命令来安装该软件包：
¥Use the [`expo-localization`](/versions/latest/sdk/localization/) library to get the user's current language. Install the package by running the following command:
```sh
$ npx expo install expo-localization
```
然后，你将能够在应用中访问本地化方法和数据：
¥Then, you will be able to access localization methods and data in your app:
```tsx
import { getLocales } from 'expo-localization';
const deviceLanguage = getLocales()[0].languageCode;
```
`getLocales` 方法根据设备的系统设置返回当前区域设置。在较新的 Android 和 iOS 版本上，可以为每个应用设置应用语言，因此你通常不需要构建自定义 UI 来允许用户更改应用内部的当前区域设置。
¥The `getLocales` method returns the current locale based on the system settings of the device. On newer Android and iOS versions, app language can be set per app, so you usually don't need to build a custom UI to allow users to change the current locale inside of your app.
有时，构建一个 UI 以允许用户在每个应用的基础上设置其他本地化首选项是有意义的。作为一般规则，你应该允许用户更改以下内容：
¥Sometimes, it makes sense to build a UI to allow the user to set other localization preferences on a per-app basis. As a general rule, you should allow the user to change the following:
* 本地化单位（如果你的应用至少适度使用它们）（例如公制/英制测量、货币、温度等）
  ¥Localized units if your app makes at least a moderate use of them (such as metric/imperial measurements, currency, temperature, and more)
* 如果没有 API 可以在你想要支持的平台上获取默认值，则其他首选项（有关详细信息，请查看 [`expo-localization`](/versions/latest/sdk/localization) API 文档）
  ¥Other preferences if there's no API to get the default value on platforms you want to support (check [`expo-localization`](/versions/latest/sdk/localization) API documentation for details)
<a id="enabling-per-app-language-selection-via-system-settings"></a>
### 通过系统设置启用每个应用的语言选择
¥Enabling per-app language selection via system settings
Android 和 iOS 都允许用户通过系统设置为各个应用选择首选语言。要支持此功能，你的应用必须向系统声明其支持的语言环境。
¥Both Android and iOS allow users to choose a preferred language for individual apps via the system settings. To support this feature, your app must declare its supported locales to the system.
为此，请使用 [`expo-localization`](/versions/latest/sdk/localization/#installation) 配置插件并将 `supportedLocales` 属性传递给 `expo-localization` 配置插件。你可以直接提供支持的语言环境数组，也可以使用 `supportedLocales.ios` 和 `supportedLocales.android` 字段指定特定于平台的值：
¥To do so, use the [`expo-localization`](/versions/latest/sdk/localization/#installation) config plugin and pass the `supportedLocales` property to the `expo-localization` config plugin.
You can either provide an array of supported locales directly, or use the `supportedLocales.ios` and `supportedLocales.android` fields to specify platform-specific values:
```json app.json
{
      [
        "expo-localization",
        {
          "supportedLocales": {
            "ios": ["en", "ja"],
            "android": ["en", "ja"]
          }
        }
      ]
  }
}
```
> 在 Android 上，请参考 [语言环境命名指南](https://developer.android.com/guide/topics/resources/app-languages#locale-names) 和 [最常用语言环境列表](https://developer.android.com/guide/topics/resources/app-languages#sample-config)。
>
> ¥On Android, refer to the [locale naming guidelines](https://developer.android.com/guide/topics/resources/app-languages#locale-names) and the [list of most commonly used locales](https://developer.android.com/guide/topics/resources/app-languages#sample-config).
>
> 在 iOS 上，使用语言名称或 ISO 语言标识符。
>
> ¥On iOS, use the language name or ISO language designator.
<a id="translating-an-app"></a>
## 翻译应用
¥Translating an app
快速创建和管理翻译成为一项艰巨的任务。你可以手动处理翻译，但最好使用库来为你处理此操作。
¥Creating and managing translations quickly becomes a large task. You can handle translations manually, but it's best to use a library to handle this for you.
让我们让应用支持英语和日语。要实现此目的，请安装 i18n 软件包 `i18n-js`：
¥Let's make the app support English and Japanese. To achieve this install the i18n package `i18n-js`:
```sh
$ npx expo install i18n-js
```
然后，为你的应用配置语言：
¥Then, configure the languages for your app:
```tsx
import { getLocales } from 'expo-localization';
import { I18n } from 'i18n-js';
// Set the key-value pairs for the different languages you want to support.
const i18n = new I18n({
  en: { welcome: 'Hello' },
  ja: { welcome: 'こんにちは' },
});
// Set the locale once at the beginning of your app.
i18n.locale = getLocales()[0].languageCode;
console.log(i18n.t('welcome'));
```
现在，你可以使用 `i18n.t` 函数在整个应用中翻译字符串。
¥Now, you can use the `i18n.t` function to translate strings throughout your application.
你可以避免本地化某些内容的文本，例如名称。在这种情况下，你可以使用默认语言定义它们一次，然后在 `i18n.enableFallback = true;` 中重用它们。
¥You can refrain from localizing text for certain things, for example, names. In this case, you can define them *once* in your default language and reuse them with `i18n.enableFallback = true;`.
在 Android 上，当用户更改设备语言时，应用不会重置。你可以使用 [`AppState`](https://rn.nodejs.cn/docs/appstate#basic-usage) API 监听应用状态的更改，并在每次应用状态更改时调用 `getLocales()` 函数。
¥On Android, when a user changes the device's language, the app will not reset. You can use the [`AppState`](https://rn.nodejs.cn/docs/appstate#basic-usage) API to listen for changes to the app's state and call the `getLocales()` function each time the app's state changes.
在 iOS 上，当用户更改设备语言时，应用将重置。这意味着你可以设置一次语言，而无需更新任何 React 组件来应对语言更改。
¥On iOS, when a user changes the device's language, the app will reset. This means you can set the language once without updating any of your React components to account for the language changes.
<a id="complete-example"></a>
### 完整示例
¥Complete example
#### Localization
  ```tsx
import { View, StyleSheet, Text } from 'react-native';
import { getLocales } from 'expo-localization';
import { I18n } from 'i18n-js';
// Set the key-value pairs for the different languages you want to support.
const translations = {
  en: { welcome: 'Hello', name: 'Charlie' },
  ja: { welcome: 'こんにちは' },
};
const i18n = new I18n(translations);
// Set the locale once at the beginning of your app.
i18n.locale = getLocales()[0].languageCode ?? 'en';
// When a value is missing from a language it'll fall back to another language with the key present.
i18n.enableFallback = true;
// To see the fallback mechanism uncomment the line below to force the app to use the Japanese language.
// i18n.locale = 'ja';
export default function App() {
  return (
    <View style={styles.container}>
      <Text style={styles.text}>
        {i18n.t('welcome')} {i18n.t('name')}
      </Text>
      <Text>Current locale: {i18n.locale}</Text>
      <Text>Device locale: {getLocales()[0].languageCode}</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
    flex: 1,
  },
  text: {
    fontSize: 20,
    marginBottom: 16,
  },
});
```
<a id="other-translation-libraries"></a>
### 其他翻译库
¥Other translation libraries
本指南以 `i18n-js` 为例。其他库也可以帮助你进行翻译，每个库都有不同的功能：
¥This guide uses `i18n-js` as an example. Other libraries can also help you with translations, and each has different features:
* 创建翻译是一项巨大的工作。考虑聘请专家并使用具有管理工具的翻译库，以更轻松地进行编辑和自动化。一些翻译库可以与翻译管理工具集成（本质上是一种 Web 服务，可让你外包、自动生成或更轻松地创建翻译）。
  ¥Creating translations is a huge effort. Consider hiring experts and using translation libraries with management tools for easier edits and automation. Some translation libraries can integrate with translation management tools (essentially, a web service that lets you outsource, auto-generate, or make it easier to create translations).
* 一些库允许根据翻译字符串重新排列组件结构。例如，你想要本地化包含 `<Pressable>` 链接的字符串，并且根据翻译，你希望链接的顺序与文本其余部分的顺序不同。
  ¥Some libraries allow rearranging component structures based on translation strings. For example, you want to localize a string that includes a `<Pressable>` link, and depending on the translation you want the link to be in a different order from the rest of the text.
以下是一些库：
¥Here are some libraries:
* [`React i18next`](https://react.i18next.com/) 是一个基于 `i18next` 的稳定、维护良好的库。
  ¥[`React i18next`](https://react.i18next.com/) is a stable, well-maintained library based on `i18next`.
* [`typesafe-i18n`](https://github.com/ivanhofer/typesafe-i18n) 编译翻译以节省生产包中的空间。它还为你的翻译生成 TypeScript 类型，以便你可以在代码中使用它们并获得自动补齐和类型安全。它需要 `Intl` API 来实现某些功能，因此它只能在启用了 Hermes 的项目中使用。
  ¥[`typesafe-i18n`](https://github.com/ivanhofer/typesafe-i18n) compiles translations to save space in the production bundle. It also generates TypeScript types for your translations so that you can use them in your code and get autocomplete and type safety. It requires the `Intl` API for some features, so it's only usable in projects with Hermes enabled.
<a id="translating-app-metadata"></a>
### 翻译应用元数据
¥Translating app metadata
如果你计划将应用发布到不同的国家或地区或希望它支持多种语言，你可以为显示名称和系统对话框等内容提供 [localized](/versions/latest/sdk/localization) 字符串。这很容易设置 [在应用配置中](/workflow/configuration) 文件。首先，设置 `ios.infoPlist.CFBundleAllowMixedLocalizations: true`，然后提供 `locales` 的文件路径列表。
¥If you plan on shipping your app to different countries or regions or want it to support various languages, you can provide [localized](/versions/latest/sdk/localization) strings for things like the display name and system dialogs. This is easily set up [in the app config](/workflow/configuration) file. First, set `ios.infoPlist.CFBundleAllowMixedLocalizations: true`, then provide a list of file paths to `locales`.
```json app.json
{
  "expo": {
    "ios": {
      "infoPlist": {
        "CFBundleAllowMixedLocalizations": true
      }
    },
    "locales": {
      "ja": "./languages/japanese.json"
    }
  }
}
```
提供给 `locales` 的键应该是 [语言标识符](https://developer.apple.com/documentation/xcode/choosing-localization-regions-and-scripts)，由所需语言的 [2 个字母的语言代码](https://www.loc.gov/standards/iso639-2/php/code_list.php) 组成，带有可选的区域代码（例如 `en-US` 或 `en-GB`），并且该值应指向如下所示的 JSON 文件：
¥The keys provided to `locales` should be the [language identifier](https://developer.apple.com/documentation/xcode/choosing-localization-regions-and-scripts), made up of a [2-letter language code](https://www.loc.gov/standards/iso639-2/php/code_list.php) of your desired language, with an optional region code (for example, `en-US` or `en-GB`), and the value should point to a JSON file that looks something like below:
```json japanese.json
{
  "ios": {
    "CFBundleDisplayName": "こんにちは",
    "NSContactsUsageDescription": "日本語のこれらの言葉"
  },
  "android": {
    "app_name": "こんにちは"
  }
}
```
现在，只要你的应用安装在语言设置为日语的设备上，其显示名称就会设置为 `こんにちは`。
¥Now, the display name of your app is set to `こんにちは` whenever it's installed on a device with the language set to Japanese.
<a id="enabling-rtl-support"></a>
## 启用 RTL 支持
¥Enabling RTL support
世界上的一些地区从右到左书写文本。如果你想要本地化你的应用，使其在 RTL 语言中看起来符合预期，你需要确保你的应用相应地处理这些布局和文本方向更改。
¥Several regions around the world write text from right to left. If you want to localize your app, so it looks as expected in RTL languages, you need to make sure your app handles these layout and text direction changes accordingly.
要启用 RTL 支持，请使用 [`expo-localization`](/versions/latest/sdk/localization/#installation) 配置插件并在应用配置中启用 `extra.supportsRTL` 属性：
¥To enable RTL support, use the [`expo-localization`](/versions/latest/sdk/localization/#installation) config plugin and enable `extra.supportsRTL` property in app config:
```json app.json
{
  "expo": {
    "extra": {
      "supportsRTL": true
    },
    "plugins": ["expo-localization"]
  }
}
```
当你的应用加载到 Expo Go、Expo dev Client 以及使用 EAS Build 或 `npx expo prebuild` 构建的应用中时，这将启用 RTL。
¥This enables RTL when your app is loaded in Expo Go, in Expo dev Client, and in applications built using EAS Build or `npx expo prebuild`.
当应用启动时，Expo 会检查当前设备区域设置是否应以 RTL 布局渲染，以便看起来正确。例如，在应用配置文件中标记为支持 RTL 的应用将在希伯来语或阿拉伯语区域设置中以 RTL 模式渲染。
¥When an application starts, Expo checks if the current device locale should render in RTL layout to look correctly. For example, an app marked to support RTL in the app config file will render in RTL mode in Hebrew or Arabic locale.
<a id="forcing-rtl-layout"></a>
### 强制 RTL 布局
¥Forcing RTL layout
你还可以通过在应用配置中启用 `extra.forcesRTL` 属性来强制 RTL 布局进行测试或仅针对 RTL 语言环境进行本地化的应用：
¥You can also force the RTL layout for testing or for applications that are only localized for RTL locales by enabling `extra.forcesRTL` property in the app config:
```json app.json
{
  "expo": {
    "extra": {
      "supportsRTL": true,
      "forcesRTL": true
    },
    "plugins": ["expo-localization"]
  }
}
```
Note: Dynamically overriding RTL settings
---
If you want to override the default RTL detection from your application code dynamically, you cannot use the static configuration in app config. Instead, apply these changes dynamically from your application code.
This does not work in Expo Go, as Expo Go resets RTL preferences when opening the launcher or individual projects.
#### Overriding RTL settings
```tsx
import { Text, View, StyleSheet, I18nManager, Platform } from 'react-native';
import Constants from 'expo-constants';
import * as Updates from 'expo-updates';
export default function App() {
  const shouldBeRTL = true;
  if (shouldBeRTL !== I18nManager.isRTL && Platform.OS !== 'web') {
    I18nManager.allowRTL(shouldBeRTL);
    I18nManager.forceRTL(shouldBeRTL);
    Updates.reloadAsync();
  }
  return (
    <View style={styles.container}>
      <Text style={styles.paragraph}>{I18nManager.isRTL ? ' RTL' : ' LTR'}</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    paddingTop: Constants.statusBarHeight,
    padding: 8,
  },
  paragraph: {
    fontSize: 18,
    fontWeight: 'bold',
    textAlign: 'left',
    width: '50%',
    backgroundColor: 'pink',
  },
});
```
---
## Making an app behave correctly on RTL locales
### Layouts and views
You don't need to manually adjust `<View>` styling properties based on locale. You can use properties like `justifyContent`, `alignItems`, and others. Their property values change behavior as required.
- On LTR locales, `start` and `end` are the same as `left` and `right`.
- On RTL locales, `start` and `end` are the same as `right` and `left`.
> **info** For more details on how RTL works in React Native check out the React Native [blog article](https://rn.nodejs.cn/blog/2016/08/19/right-to-left-support-for-react-native-apps) introducing RTL support.
#### Web support
Web support for RTL layouts requires no app config changes.
Expo uses `react-native-web` for running Expo projects in the browser. To make `react-native-web` automatically adapt to locale direction, add a `dir` property to your root `<View>` component.
```tsx App.tsx
import { View } from 'react-native';
import { getLocales } from 'expo-localization';
// ...
return <View dir={getLocales()[0].textDirection || 'ltr'}>...</View>;
```
> **warning** `textDirection` is not available on Firefox and older browser versions. [Detect it manually](https://stackoverflow.com/a/15726039) if needed.
### Text alignment
The React Native's `textDirection` property does not accept `start` or `end` values that you can use in flex properties. Instead, `left` effectively works as `start` (aligns to the left on LTR and the right on RTL), and `right` works as `end`.
However, the default unset value of `textDirection` property signifies the actual left (aligns to the left both on LTR and RTL). This means each `<Text>` tag should have the `textDirection: left` or `textDirection: right` style set if you want it to be aligned correctly.
It's best to define this style in your custom reusable `<Text>` component that you can then import everywhere you need to render text strings.
```tsx MobileText.tsx
import { Text as RNText, TextProps as RNTextProps } from 'react-native';
const MobileText = (props: RNTextProps) => {
  return <RNText style={{ textAlign: 'left', ...props.style }} {...props} />;
};
export default MobileText;
```
#### Web support
For each text tag, you need to add the `lang` property with the current locale identifier. It's best to define this style in a custom reusable component.
```tsx WebText.tsx
import { getLocales } from 'expo-localization';
const deviceLanguage = getLocales()[0].languageCode;
const WebText = (props: RNTextProps) => {
  return <RNText lang={deviceLanguage} {...props} />;
};
export default WebText;
```
You can then pick either the mobile or web Text component based on the current platform.
```tsx Text.tsx
const Text = Platform.OS === 'web' ? WebText : MobileText;
export default Text;
```
### Selecting assets based on locale direction
If you need to use different icons for LTR/RTL or change styles based on this setting, you can use [`I18nManager.isRTL`](https://rn.nodejs.cn/docs/next/i18nmanager#isrtl) to get the current layout direction.
```tsx
import { I18nManager } from 'react-native';
const isRTL = I18nManager.isRTL;
```
## Locale settings and units
Expo provides the `expo-localization` library to allow you to read the user's locale and other preferences. You can use synchronous `getLocales()` and `getCalendars()` methods to get the current locale settings of the user device:
- `getLocales()` returns a list of locales based on the order in which the user prefers them. There will always be at least one locale in the list.
- `getCalendars()` returns a list of calendars based on the order in which the user prefers them. There will always be at least one calendar on the list.
```ts
import { getLocales, getCalendars } from 'expo-localization';
const {
  languageTag,
  languageCode,
  textDirection,
  digitGroupingSeparator,
  decimalSeparator,
  measurementSystem,
  currencyCode,
  currencySymbol,
  regionCode,
} = getLocales()[0];
const { calendar, timeZone, uses24hourClock, firstWeekday } = getCalendars()[0];
```
Note: Limitations
---
There are a few limitations to keep in mind when relying on auto-detected locale preferences from `expo-localization`.
- There is yet to be a way to read temperature units from user preferences. On Android, you can use a lookup table based on locale. However, on iOS, the user can change it in device preferences.
- Some properties can be null when they are unavailable on the current platform.
---
## Intl API
If you're using Hermes in your app, you can use the [`Intl`](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API on all platforms.
It provides a set of utilities you can use to format lists, dates, numbers, monetary amounts, units, plural forms, and more.
If you pass `default` as the locale string, the `Intl` API will use the device's locale, so you don't need to rely on `expo-localization` to get the current locale (such as `"en-US"`).
```ts
new Intl.NumberFormat('default', { style: 'currency', currency: 'EUR' }).format(5.0);
```
> You can use `Intl` APIs to format strings and values once you know what the user expects to see.
>
> `Intl` APIs do not provide information about the device or current locale, so you can't use the `Intl` APIs to get current locale units, currencies, or measurement systems.
>
>
为此，你需要在 Web 上使用 `expo-localization`、JS 代码，或者在 Android 和 iOS 上使用第三方或自定义原生代码。
¥For this you need to use `expo-localization`, JS code on the web, or third-party or custom native code on Android and iOS.


## 配置 JS 引擎

有关在 Expo 项目中为 Android 和 iOS 配置 JS 引擎的指南。

JavaScript 引擎执行你的应用代码并提供各种功能，例如内存管理、优化和错误处理。默认情况下，Expo 项目使用 [Hermes](https://hermesengine.dev/) 作为 JavaScript 引擎（在 SDK 47 及更低版本中，默认为 [JavaScriptCore](https://developer.apple.com/documentation/javascriptcore)）。可以切换到适用于 Android 和 iOS 平台的其他引擎，例如 JSC 或 V8。但是，不适用于 Web，因为 JavaScript 引擎包含在 Web 浏览器中。
¥JavaScript engines execute your application code and provide various features such as memory management, optimization, and error handling. By default, Expo projects use [Hermes](https://hermesengine.dev/) as the JavaScript engine (in SDK 47 and lower, the default was [JavaScriptCore](https://developer.apple.com/documentation/javascriptcore)). Switching to other engines, such as JSC or V8, for Android and iOS platforms is possible. However, not for the web because the JavaScript engine is included in the web browser.
<a id="configuring-the-jsengine-through-app-config"></a>
## 通过应用配置配置 `jsEngine`
¥Configuring the `jsEngine` through app config
>  **warning** 从 SDK 52 开始，Expo Go 中无法更改 JS 引擎（仅 Hermes 引擎可用）。使用此自定义需要 [开发构建](/develop/development-builds/introduction/)。
>
> ¥Changing the JS engine is unavailable in Expo Go from SDK 52 (only the Hermes engine is available). A [development build](/develop/development-builds/introduction/) is required to use this customization.
我们推荐 Hermes，因为它是专门为 React Native 应用构建和优化的，并且具有最佳的调试体验。如果你熟悉不同 JavaScript 引擎的权衡并希望放弃 Hermes，则 [应用配置](/workflow/configuration/) 内的 [`jsEngine`](/versions/latest/config/app/#jsengine) 字段允许你为应用指定 JavaScript 引擎。默认值为 `hermes`。
¥We recommend Hermes because it is purpose built and optimized for React Native apps, and it has the best debugging experience. If you are familiar with the tradeoffs of different JavaScript engines and would like to change away from Hermes, the [`jsEngine`](/versions/latest/config/app/#jsengine) field inside [app config](/workflow/configuration/) allows you to specify the JavaScript engine for your app. The default value is `hermes`.
如果你想改用 JSC，请在应用配置中设置 `jsEngine` 字段：
¥If you want to use JSC instead, set the `jsEngine` field in the app config:
```json app.json
{
  "expo": {
    "jsEngine": "jsc"
  }
}
```
Note: Usage in bare React Native projects
---
To change the JavaScript engine in a bare React Native project, update the `expo.jsEngine` value in **android/gradle.properties** and **ios/Podfile.properties.json**.
---
It's important to highlight that changing the JS engine will require you to recompile development builds with `eas build` to work properly.
## Using the V8 engine
To use the V8 engine, you need to install [`react-native-v8`](https://github.com/Kudo/react-native-v8), an opt-in package that adds V8 runtime support for React Native. You can install it by running the following command:
```sh
$ npx expo install react-native-v8 v8-android-jit
```
Make sure to remove the `jsEngine` field from the app config.
Note: Usage with Expo Prebuild
---
Run `npx expo prebuild -p android --clean` after the installation to prebuild again.
---
<a id="switch-javascript-engine-on-a-specific-platform"></a>
## 在特定平台上切换 JavaScript 引擎
¥Switch JavaScript engine on a specific platform
要在一个特定平台上使用不同的引擎，你可以在顶层设置 `"jsEngine"` 值，然后使用 `"android"` 或 `"ios"` 键下的不同值覆盖它。为平台指定的值将优先于公共字段。
¥To use a different engine on one specific platform, you can set the `"jsEngine"` value at the top level and then override it with a different value under the `"android"` or `"ios"` key. The value specified for the platform will take precedence over the common field.
```json app.json
{
  "expo": {
    "jsEngine": "hermes",
    "ios": {
      "jsEngine": "jsc"
    }
  }
}
```


## 使用 Bun

有关将 Bun 与 Expo 和 EAS 结合使用的指南。

[Bun](https://bun.sh/) 是一个 JavaScript 运行时，也是 [Node.js](https://nodejs.cn/en) 的替代品。在 Expo 项目中，Bun 可用于安装 npm 包并运行 Node.js 脚本。使用 Bun 的好处是比 npm、pnpm 或 Yarn 和 [与 Node.js 相比，启动时间至少快 4 倍](https://bun.sh/docs#design-goals) 更快的软件包安装，这极大地提升了你的本地开发体验。
¥[Bun](https://bun.sh/) is a JavaScript runtime and a drop-in alternative for [Node.js](https://nodejs.cn/en). In Expo projects, Bun can be used to install npm packages and run Node.js scripts. The benefits of using Bun are faster package installation than npm, pnpm, or Yarn and [at least 4x faster startup time compared to Node.js](https://bun.sh/docs#design-goals), which gives a huge boost to your local development experience.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
> 注意：虽然 Bun 可以在项目中的大多数用例中替代 Node.js，但目前仍需要安装 [Node.js LTS 版本](https://nodejs.cn/) 才能使用 `bun create expo` 和 `bun expo prebuild` 命令。这些命令使用 `npm pack` 下载项目模板。
>
> ¥**Note:** While Bun replaces Node.js for most use cases in your project, at this time, a [Node.js LTS version](https://nodejs.cn/) is still required to be installed for the `bun create expo` and `bun expo prebuild` commands. These commands use `npm pack` to download project templates.
要使用 Bun、[在本地计算机上安装 Bun](https://bun.sh/docs/installation#installing) 创建新应用。
¥To create a new app using Bun, [install Bun on your local machine](https://bun.sh/docs/installation#installing).
<a id="start-a-new-expo-project-with-bun"></a>
## 与 Bun 一起启动一个新的 Expo 项目
¥Start a new Expo project with Bun
要创建新项目，请运行以下命令：
¥To create a new project, run the command:
```sh
$ bun create expo my-app
```
你还可以使用 `bun run` 运行任何 package.json 脚本：
¥You can also run any **package.json** script with `bun run`:
```sh
$ bun run ios
```
要安装任何 Expo 库，你可以使用 `bun expo install`：
¥To install any Expo library, you can use `bun expo install`:
```sh
$ bun expo install expo-av
```
<a id="use-bun-for-eas-builds"></a>
## 使用 Bun 进行 EAS 构建
¥Use Bun for EAS builds
EAS 根据代码库中的锁定文件决定使用哪个包管理器。如果你希望 EAS 使用 Bun，请在你的代码库中运行 `bun install`，这将创建一个 bun.lockb（Bun 锁文件）。只要此锁定文件位于你的代码库中，Bun 将用作你构建的包管理器。确保删除其他包管理器生成的所有锁定文件。
¥EAS decides which package manager to use based on the lockfile in your codebase. If you want EAS to use Bun, run `bun install` in your codebase which will create a **bun.lockb** (the Bun lockfile). As long as this lockfile is in your codebase, Bun will be used as the package manager for your builds. Make sure to delete any lockfiles generated by other package managers.
<a id="customize-bun-version-on-eas"></a>
### 在 EAS 上自定义 Bun 版本
¥Customize Bun version on EAS
使用 EAS 时，默认情况下会安装 Bun。请参阅 [Android 服务器镜像](/build-reference/infrastructure/#android-server-images) 和 [iOS 服务器镜像](/build-reference/infrastructure/#ios-server-images)，了解你的构建映像使用了哪个版本的 Bun。
¥Bun is installed by default when using EAS. See the [Android server images](/build-reference/infrastructure/#android-server-images) and [iOS server images](/build-reference/infrastructure/#ios-server-images) to learn which version of Bun is used by your build's image.
要将 [Bun 的确切版本](/eas/json/#bun) 与 EAS 一起使用，请在构建配置文件的配置下在 eas.json 中添加版本号。例如，以下配置为 `development` 构建配置文件指定了 Bun 版本 `1.0.0`：
¥To use an [exact version of Bun](/eas/json/#bun) with EAS, add the version number in **eas.json** under the build profile's configuration. For example, the configuration below specifies Bun version `1.0.0` for the `development` build profile:
```json eas.json
{
  "build": {
    "development": {
      "bun": "1.0.0"
    }
  }
}
```
<a id="trusted-dependencies"></a>
## 可信依赖
¥Trusted dependencies
与其他包管理器不同，Bun 不会自动从已安装的库执行生命周期脚本，因为这被认为存在安全风险。但是，如果你要安装的包包含要运行的 `postinstall` 脚本，则必须通过将该库包含在 package.json 的 [`trustedDependencies`](https://bun.sh/guides/install/trusted) 数组中来明确声明。
¥Unlike other package managers, Bun does not automatically execute lifecycle scripts from installed libraries, as this is considered a security risk. However, if a package you are installing has a `postinstall` script that you want to run, you have to explicitly state that by including that library in your [`trustedDependencies`](https://bun.sh/guides/install/trusted) array in your **package.json**.
例如，如果你安装 `packageA`，它依赖于 `packageB`，而 `packageB` 有 `postinstall` 脚本，则必须在 `trustedDependencies` 中添加 `packageB`。
¥For example, if you install `packageA`, which has a dependency on `packageB` and `packageB` has a `postinstall` script, you must add `packageB` in your `trustedDependencies`.
要在 package.json 中添加可信依赖，请添加：
¥To add a trusted dependency in your **package.json**, add:
```json package.json
"trustedDependencies": ["your-dependency"]
```
然后，删除锁定文件并重新安装依赖：
¥Then, remove your lockfile and re-install the dependencies:
```sh
$ rm -rf node_modules
$ rm bun.lockb
$ bun install
```
<a id="common-errors"></a>
## 常见错误
¥Common errors
<a id="eas-build-fails-when-using-sentry-and-bun"></a>
### 使用 Sentry 和 Bun 时 EAS 构建失败
¥EAS Build fails when using Sentry and Bun
如果你使用 `sentry-expo` 或 `@sentry/react-native`，则它们依赖于 `@sentry/cli`，后者会在构建期间将源映射更新到 Sentry。`@sentry/cli` 软件包有一个 `postinstall` 脚本，需要运行该脚本才能使 "上传源地图" 脚本可用。
¥If you're using `sentry-expo` or `@sentry/react-native`, these depend on `@sentry/cli`, which updates source maps to Sentry during your build. The `@sentry/cli` package has a `postinstall` script which needs to run for the "upload source maps" script to become available.
要解决此问题，请将 `@sentry/cli` 添加到 package.json 中的 [可信依赖](/#trusted-dependencies) 数组中：
¥To fix this, add `@sentry/cli` to your [trusted dependencies](/#trusted-dependencies) array in **package.json**:
```json package.json
"trustedDependencies": ["@sentry/cli"]
```


## 编辑富文本

了解在 React Native 中预览和编辑富文本的当前方法。

许多应用需要允许用户输入文本。例如，如果你想构建消息传递或社交媒体应用，你可能会严重依赖文本输入。React Native 有一个内置的 `<TextInput>` 组件来实现这一点，对于许多简单的情况不需要太多努力。
¥A lot of applications need to allow users to type in text. For example, if you want to build a messaging or social media app, you will probably rely heavily on text inputs. React Native has a built-in `<TextInput>` component to implement this without much effort for many simple cases.
然而，有时你需要更加灵活。想想长篇社交媒体帖子、注意应用或文档编辑器。理想情况下，你需要允许不同的文本样式、列表、标题、嵌入图片等。这称为富文本编辑器，在任何地方都很难解决，包括在 React Native 中。
¥However, sometimes you need to be more flexible. Think of long social media posts, note apps, or document editors. Ideally, you need to allow different text styles, lists, headings, embedded images, and more. This is called a rich text editor, and it's a difficult problem to solve everywhere, including in React Native.
目前 React Native 生态系统中没有针对此问题的默认解决方案。但是，本指南探讨了一些选项和有前途的方法，每种方法都有自己的权衡。
¥There is currently no default solution for that in the React Native ecosystem. However, this guide explores some options and promising approaches, each with its own tradeoffs.
Video Tutorial: [Watch: How to implement a Rich Text Editor using DOM components](https://www.youtube.com/watch?v=CxORa1tXMjw)
<a id="render-rich-text"></a>
## 渲染富文本
¥Render rich text
有很多很好的选项来显示富文本：
¥There are a lot of good options to display rich text:
* 对于 Markdown 内容，你可以使用 Markdown 渲染器，例如 [`react-native-markdown-display`](https://www.npmjs.com/package/react-native-markdown-display) 或其他。
  ¥For markdown content, you can use a markdown renderer such as [`react-native-markdown-display`](https://www.npmjs.com/package/react-native-markdown-display) or another.
* 对于 HTML 内容，你可以使用 [`@expo/html-elements`](https://www.npmjs.com/package/@expo/html-elements) 或 webview ([`react-native-webview`](/versions/latest/sdk/webview/))。
  ¥For HTML content, you can use [`@expo/html-elements`](https://www.npmjs.com/package/@expo/html-elements) or a webview ([`react-native-webview`](/versions/latest/sdk/webview/)).
* 要拥有自定义格式和更多控制，你可以利用嵌套 `<Text>` 组件来渲染样式和布局。
  ¥To have a custom format and more control, you can take advantage of nesting `<Text>` components to render styles and layouts.
```jsx
  <TextInput>
    <Text>
      <Text style={{ fontWeight: 900 }}>Some bold text</Text>Some regular text
    </Text>
  </TextInput>
  ```
* 你还可以使用 [Expo 模块](/modules/overview/) 使用第三方库（例如 Android 上的 [马克旺](https://github.com/noties/Markwon) 和 iOS 上的 `AttributedString`）使用原生平台原语编写自定义渲染器组件。
  ¥You can also use [Expo Modules](/modules/overview/) to write a custom renderer component with native platform primitives using third-party libraries such as [Markwon](https://github.com/noties/Markwon) on Android and `AttributedString` on iOS.
<a id="approaches-to-edit-rich-text"></a>
## 编辑富文本的方法
¥Approaches to edit rich text
有几种方法可以实现富文本渲染。然而，它们都有不同的限制。
¥There are a few approaches to get rich text rendering to work. However, all have different limitations.
<a id="webview-based-editors"></a>
### 基于 Webview 的编辑器
¥Webview-based editors
虽然大多数 React Native UI 组件都封装了原生平台原语，因此具有快速、高性能和原生的感觉，但基于 Webview 的富文本编辑器使用不同的方法。
¥While most React Native UI components wrap native platform primitives and are fast, performant, and **native feeling** as a result, the webview-based rich text editors use a different approach.
他们将现有的富文本编辑器用 JavaScript 封装在 [`react-native-webview`](/versions/latest/sdk/webview/) 中。它适用于所有平台（Android、iOS、Web），并且可以利用可用于 Web 平台的流行富文本编辑器，但它会降低性能和用户体验。
¥They wrap an existing rich text editor built for web with JavaScript inside a [`react-native-webview`](/versions/latest/sdk/webview/). It works on all platforms (Android, iOS, Web) and can take advantage of popular rich text editors available for the Web platform, but it has a performance and UX penalty.
你将无法在编辑器内使用原生 UI 组件。提及或图片嵌入等功能的任何实现都会重复功能，并且需要付出巨大的努力才能实现。
¥You will not be able to use native UI components inside the editor. Any implementation of features like mentions or image embedding will duplicate features and require significant effort to implement.
<a id="existing-webview-based-react-native-libraries"></a>
### 现有的基于 webview 的 React Native 库
¥Existing webview-based React Native libraries
有几个现有的 React Native 库允许富文本编辑。如果你需要一个具有有限配置的基本富文本编辑器，并且没有严格的性能或用户体验要求，这些是最简单的入门选项：
¥There are a couple of existing React Native libraries to allow rich-text editing. These are the easiest options to get started if you need a basic rich text editor with limited configuration and don't have strict performance or UX requirements:
* [`react-native-rich-editor`](https://github.com/wxik/react-native-rich-editor)
* [`react-native-cn-quill`](https://github.com/imnapo/react-native-cn-quill)
* [`@10play/tentap-editor`](https://github.com/10play/10Tap-Editor)
<a id="custom-webview-based-editor"></a>
### 基于 webview 的自定义编辑器
¥Custom webview-based editor
如果你需要更多的可配置性，你可以使用现有的纯 Web 编辑器构建类似的库。但是，你必须自己处理消息传递和 Web 实现。这为你提供了底层编辑器提供的所有选项，并允许你实现更多功能。
¥If you need more configurability, you can build a similar library with an existing web-only editor. However, you have to handle the message passing and web implementation yourself. This gives you all the options that the underlying editor offers and lets you implement more features.
* [鹅毛笔](https://quill.nodejs.cn/)
  ¥[Quill](https://quill.nodejs.cn/)
* [lexical](https://github.com/facebook/lexical)
* [slate](https://github.com/ianstormtaylor/slate)
你将需要使用消息传递将文本和 `onChange` 事件传递到 Web 视图或从 Web 视图传递文本和 `onChange` 事件。由于富文本通常很长，因此最好将其建模为不受控制的组件，以防止每次击键时都出现滞后。此外，如果你可以避免在每次击键时序列化和发送整个状态，也可以提高性能。
¥You will need to use message passing to pass text and `onChange` events to and from the webview. Since rich texts often end up long, it's better to model it as an uncontrolled component to prevent lag on each keystroke. Also, if you can avoid serializing and sending the entire state on each keystroke that also improves performance.
<a id="building-on-top-of-react-native-textinput"></a>
## 构建在 React Native TextInput 之上
¥Building on top of React Native TextInput
在本节中，我们将讨论是否可以拥有用于通用目的的完整富文本输入功能。
¥In this section, let's discuss if it is possible to have a feature complete rich text input for general purposes.
React Native 允许嵌套 `<Text>` 组件，并允许它们用作 `<TextInput>` 的子组件来渲染和编辑样式文本。它与新的 React Native 架构同步（在文本输入字段中输入新字符后立即触发 `onChange` 事件）。
¥React Native allows nested `<Text>` components and allows them to be used as children of `<TextInput>` to render and edit styled text. It is synchronous with the new React Native architecture (the `onChange` event fires immediately after a new character is typed into the text input field).
不幸的是，`<TextInput>` 组件是针对处理常规文本而构建的，它仅在其 `onTextChange` 回调中返回一个字符串。这是一个很大的限制。
¥Unfortunately, the `<TextInput>` component is built towards working with regular text, and it only returns a string in it's `onTextChange` callback. This is a significant limitation.
这是一个简单的例子。让我们首先使用以下粗体文本渲染文本输入：
¥Here is a quick example. Let's start by rendering a text input with the following bold text:
```jsx
<TextInput>
  <Text>
    {/* The following will render a bold text in this format: **aa**aa */}
    <Text style={{ fontWeight: 900 }}>aa</Text>aa
  </Text>
</TextInput>
```
然后，我们将第五个字母 `a` 添加到文本输入中。光标的位置应确定新字母是否是粗体字符串的一部分。不幸的是，回调只返回 `aaaaa`。
¥Then, let's append a fifth letter `a` to the text input. The position of your cursor should determine if the new letter is a part of the bold string or not. Unfortunately, the callback only returns `aaaaa`.
还有一个额外的 `onSelectionChange` 属性可用于获取该信息。然而，这使得任务变得更加困难。插入其他字符（例如列表的换行符或项目符号点）也会使选择不同步。
¥There is an additional `onSelectionChange` prop that can be used to get that information. However, it makes the task significantly harder. Inserting additional characters (such as newlines for lists or bullet points) also desynchronizes the selection.
有一些尝试构建这样的编辑器，例如 [`markdown-editor`](https://github.com/shakogegia/markdown-editor)（未积极维护）和 [`rn-text-editor`](https://github.com/amjadbouhouch/rn-text-editor)（测试版），但不存在广泛使用的软件包。
¥There are some attempts to build such an editor, such as [`markdown-editor`](https://github.com/shakogegia/markdown-editor) (not actively maintained) and [`rn-text-editor`](https://github.com/amjadbouhouch/rn-text-editor) (in beta), but no widely used packages exist.
<a id="markdown-editors-with-visible-styling-markers"></a>
## 带有可见样式标记的 Markdown 编辑器
¥Markdown editors with visible styling markers
如果使用 Markdown 来设置文本样式满足你的要求，你可以在编辑时在单独的、不可编辑的视图中渲染 Markdown。使用任何 Markdown 渲染器自行构建并不复杂。你还可以使用第三方库，例如 [`react-native-markdown-editor`](https://github.com/kunall17/react-native-markdown-editor)。
¥If using a markdown to style text fulfills your requirement, you can render the markdown in a separate, non-editable view while editing. It is not complex to build on your own using any markdown renderer. You can also use a third-party library such as [`react-native-markdown-editor`](https://github.com/kunall17/react-native-markdown-editor).
这种编辑体验适合高级用户或编程/技术应用。你还可以探索渲染富文本，同时仅在选定的文本块中显示 Markdown 或其他混合方法。
¥This editing experience suits power users or programming/tech applications. You can also explore rendering rich text while showing markdown only in the selected chunk of text or other hybrid approaches.
<a id="native-editors"></a>
## 原生编辑器
¥Native editors
你可以使用封装在 React Native 模块中的原生 Android 或 iOS 富文本编辑器。有以下几种选择：
¥You can use a native Android or iOS rich text editor wrapped into a React Native module. There are a few options:
* [`react-native-aztec`](https://github.com/WordPress/gutenberg/tree/trunk/packages/react-native-aztec)
* [`gutenberg-mobile`](https://github.com/wordpress-mobile/gutenberg-mobile)
* [`react-native-live-markdown`](https://github.com/Expensify/react-native-live-markdown)
你还可以使用 [Expo 模块](/modules/overview/) 封装任何原生富文本编辑器，但如果你在每个平台上使用不同的富文本编辑器，则需要统一它们的 API 和输入格式。
¥You can also wrap any native rich text editor using [Expo Modules](/modules/overview/), but if you use different ones on each platform, you need to unify their APIs and input formats.
> 富文本通常使用 [抽象语法树](https://en.wikipedia.org/wiki/Abstract_syntax_tree) 表示。例如，项目符号列表可以是类型为 `bulleted-list` 的节点，具有多个类型为 `list-item` 的子节点。你可以将 HTML 和 Markdown 转换为合适的 AST 格式。
>
> ¥Rich text is usually represented using [abstract syntax trees](https://en.wikipedia.org/wiki/Abstract_syntax_tree). For example, a bullet list can be a node of type `bulleted-list` with several children of type `list-item`. You can convert both HTML and markdown to a suitable AST format.
还有一项努力是将词汇编辑器移植到 Android 和 iOS，并提供 React Native 封装器 [在此处跟踪](https://github.com/facebook/lexical/discussions/2410)。
¥There is also an effort to port the lexical editor to Android and iOS and provide a React Native wrapper, [track it here](https://github.com/facebook/lexical/discussions/2410).
<a id="summary"></a>
## 概括
¥Summary
虽然显示富文本有很多不错的选项，但在 React Native 中没有一种通用的富文本编辑解决方案。没有一种流行的解决方案足以满足大多数用例。需要社区的进一步贡献来改进现有解决方案或添加新解决方案。
¥While there are many great options for showing rich text, there is no one-size-fits-all solution for rich text editing in React Native. There's no popular solution that is sufficient in most use cases. Further contribution from the community is needed to improve existing solutions or add new ones.
目前，你需要仔细选择更复杂、提供更多功能但可能更难维护的原生编辑器，或者基于 react-native 原语构建的编辑器。这取决于该功能对你的应用的核心程度、你的编辑器中需要多少功能以及你愿意花费多少精力来构建它。
¥For now, you need to carefully choose between a more complex, native editor that offers more features but may be harder to maintain, or an editor built on top of react-native primitives. This depends on how core the feature is to your app, how many features you need in your editor, and how much effort you are willing to spend on building it out.


## 创建应用商店资源

了解如何为应用的商店页面创建屏幕截图和预览。

在将应用提交到 Google Play 商店和 Apple App Store 之前，你需要为商店列表页面提供一些资源。这些图片和视频的目标是让你的潜在用户了解你的应用体验是什么样的。
¥Before submitting your app to the Google Play Store and Apple App Store, you need to provide some assets for your store listing page. The goal of these images and videos is to give your prospective users an idea of what your app experience is going to be like.
你需要上传两个应用商店的应用屏幕截图。尽管它们在两家商店中都被称为 "应用截图"，但它们确实必须包含应用的准确视觉效果。没有规定规定这些图片必须是在特定设备上拍摄的屏幕截图。
¥You will need to upload app screenshots for both app stores. Even though they are called "app screenshots" on both stores, they *do* have to include accurate visuals of your app. There is no rule citing that these images have to be screenshots taken on specific devices.
两个应用商店对图片格式和大小都有要求。但是，在这些限制范围内，你可以发挥创造力。例如，一种常见的方法是使用 Figma 等设计工具来设计资源，并将实际应用屏幕截图（或设计）与补充消息结合起来。
¥Both app stores have requirements on image format and size. However, within these restrictions, you can be creative. For example, a common approach is to design the assets using a design tool such as Figma and incorporate actual app screenshots (or designs) with supplementary messaging.
<a id="different-approaches-for-creating-screenshots"></a>
## 创建 "screenshots" 的不同方法
¥Different approaches for creating "screenshots"
创建商店屏幕截图有三种常用方法。你可以选择最适合你应用的需求和资源的方法。
¥There are three commonly used approaches to creating your store screenshots. You can choose whichever approach works best for your app's needs and resources.
<a id="option-1-actual-screenshots"></a>
### 选项 1：实际截图
¥Option 1: actual screenshots
最简单的选择 - 在真实设备上打开你的应用并截取屏幕截图。
¥The most straightforward option — open up your app on a real device and take screenshots.
优点：简单易行。最准确地代表你的应用。
¥**Pros**: Straightforward to do. Most accurate representation of your app.
缺点：需要在不同设备上加载应用才能获得全方位的屏幕截图。
¥**Cons**: Need to load the app on different devices for a full range of screenshots.
<a id="option-2-screenshots-within-a-design"></a>
### 选项 2：设计中的屏幕截图
¥Option 2: screenshots within a design
大多数应用都使用这种方法。它涉及拍摄应用的屏幕截图（或者在某些情况下，使用现有设计而不是实际屏幕截图）并将它们与适当的消息一起嵌入到商店资源中。
¥The majority of apps use this approach. It involves taking screenshots of the app (or in some cases, using existing designs instead of actual screenshots) and embedding them in the store assets along with appropriate messaging.
优点：允许在资源内传达额外的消息。
¥**Pros:** Allows to convey additional messaging within the assets.
缺点：需要使用设计程序创建资源。
¥**Cons:** The assets need to be created using a design program.
<a id="option-3-make-it-fancy"></a>
### 选项 3：让它变得花哨
¥Option 3: make it fancy
在此选项中，在应用商店页面上，你可以合并应用设计元素和创意消息来突出你的产品。
¥In this option, on the app store pages, you can incorporate elements of your app design and creative messaging to highlight your product.
优点：你可以使你的商店页面富有创意且有趣。
¥**Pros:** You can make your store page creative and fun.
缺点：需要经验丰富的设计师来创建和维护资源。
¥**Cons:** Need an experienced designer to create and maintain the assets.
<a id="google-play-store-asset-requirements"></a>
## Google Play 商店资源要求
¥Google Play Store Asset Requirements
Google 对商店资源格式和尺寸有具体要求，与 Apple 不同。有关最新规范，请参阅 [官方文档](https://support.google.com/googleplay/android-developer/answer/9866151) 了解 Google Play 商店资源的详细要求。
¥Google has specific requirements for the store asset format and dimensions, which are different from Apple's. For the most up-to-date specifications, see [official documentation](https://support.google.com/googleplay/android-developer/answer/9866151) for detailed requirements for your Google Play Store assets.
<a id="app-icon"></a>
### 应用图标
¥App icon
与 Apple App Store 中的应用图标始终从应用包中自动获取不同，在 Google Play 商店中，你还必须为商店列表上传单独的应用图标。
¥Unlike on the Apple App Store, where the app icon is always taken automatically from the app bundle, on the Google Play Store, you must also upload a separate App Icon for your store listing.
<a id="feature-graphic"></a>
### 特性图
¥Feature graphic
必须提供专题图片才能发布你的商品详情。它是显示在商品详情页面顶部的横幅。
¥A feature graphic must be provided to publish your Store Listing. It is a banner that is displayed at the top of your store listing page.
<a id="screenshots"></a>
### 截图
¥Screenshots
你需要上传至少四张屏幕截图才能发布你的应用。
¥You need to upload at least four screenshots to publish your app.
<a id="video-optional"></a>
### 视频（可选）
¥Video (optional)
你可以将一个预览视频添加到你的商品详情中。视频需要上传到 YouTube，你可以通过在预览视频字段中输入 YouTube URL 来添加视频。
¥You can add one preview video to your Store Listing. The video needs to be uploaded to YouTube, and you can add it by entering a YouTube URL in the **preview video** field.
<a id="ios-app-store-asset-requirements"></a>
## iOS 应用商店资源要求
¥iOS App Store Asset Requirements
对于 iOS App Store，你可以上传屏幕截图（图片）和预览（视频）。对于每一个，Apple 都要求特定的宽度和高度。请务必参考 [Apple 的屏幕截图规范](https://developer.apple.com/help/app-store-connect/reference/screenshot-specifications/) 以了解准确的尺寸。即使有一个像素缺失也意味着你无法提交图片。
¥For the iOS App Store, you can upload screenshots (images) and previews (videos). For each, Apple requires specific widths and heights. Make sure to reference the [Screenshot specifications from Apple](https://developer.apple.com/help/app-store-connect/reference/screenshot-specifications/) for the exact sizing. Even a single pixel-off will mean you cannot submit the images.
<a id="screenshots-1"></a>
### 截图
¥Screenshots
至少，Apple 要求你上传带有动态岛（6.9 英寸）的 iPhone 屏幕截图。你可以选择上传其他屏幕尺寸的其他屏幕截图。如果没有提供特定的屏幕截图，则将使用从最接近的上传尺寸缩小的屏幕截图。
¥At a minimum, Apple requires you to upload screenshots for iPhone with the dynamic island (6.9 inch). You can optionally upload additional screenshots for other screen sizes. If specific screenshots are not provided, scaled down screenshots from the closest uploaded size will be used instead.
如果你的应用在 iPad 上运行，你还必须提供一组 iPad 屏幕截图（13 英寸）。
¥If your app runs on iPad, you must also provide one set of iPad screenshots (13 inch).
每个本地化版本你最多可以上传十张屏幕截图。如果你的应用提供多种语言版本，并且你的屏幕截图包含文本，则你应该针对每种本地化上传具有适当语言的屏幕截图。
¥You can upload up to ten screenshots per localization. If your app is available in multiple languages and your screenshots include text, you should upload screenshots with the appropriate language for each localization.
屏幕截图可以是纵向或横向。
¥Screenshots can be portrait or landscape.
<a id="preview-optional"></a>
### 预览（可选）
¥Preview (optional)
你可以添加应用预览视频来演示你的应用的工作原理。你可以为每种屏幕尺寸添加最多三个应用预览。
¥You can include An app preview video to demonstrate how your app works. You can add up to three app previews for each screen size.
有关视频大小和格式的摘要，请参阅 Apple 文档中的 [应用预览规范](https://developer.apple.com/help/app-store-connect/reference/app-preview-specifications/)。
¥See [App Preview Specifications](https://developer.apple.com/help/app-store-connect/reference/app-preview-specifications/) from Apple documentation for a summary of video size and format.
<a id="bare-minimum"></a>
## 最低限度
¥Bare minimum
以下是发布应用所需的最低限度。
¥Below is the bare minimum needed to publish your apps.
<a id="play-store---android"></a>
### 应用商店 - 安卓
¥Play Store - Android
| 类型   | 数量   | 方面                                       | 要求                               |
| ---- | ---- | ---------------------------------------- | -------------------------------- |
| 应用图标 | 1    | 512 × 512                                | 32 位 PNG（带 Alpha）；最大文件大小：1024 KB |
| 专题图  | 1    | 1024 × 500                               | JPEG 或 24 位 PNG（无 Alpha）         |
| 截图   | 4-10 | 最低限度：1024 × 500 最大宽度：3840px:16 宽高比 | JPEG 或 24 位 PNG（无 Alpha）         |
<a id="app-store---iphone"></a>
### 应用商店 - iPhone
¥App Store - iPhone
| 类型                  | 数量   | 尺寸（选择一个）           | 要求                 |
| ------------------- | ---- | ------------------ | ------------------ |
| 屏幕截图（带有动态岛的 iPhone） | 2-10 | 1320 × 2868 × 2796 | JPG 或 PNG（无 Alpha） |
<a id="app-store---ipad"></a>
### 应用商店 - iPad
¥App Store - iPad
如果你的应用也在 iPad 上运行，你需要提供额外的屏幕截图。
¥If your app also runs on an iPad, you need to supply additional screenshots.
| 类型 | 数量   | 尺寸（选择一个）           | 要求                 |
| -- | ---- | ------------------ | ------------------ |
| 截图 | 2-10 | 2064 × 2752 × 2732 | JPG 或 PNG（无 Alpha） |


## 带有 Expo 的本地优先架构

新兴的本地优先软件运动的介绍，包括相关学习资源和工具的链接。

>  **info** 本指南正在进行中。如果你有任何反馈，请访问我们 GitHub 存储库中的 [React Navigation 中显示的选项文档](https://github.com/expo/expo/issues/new/choose)。
>
> ¥This guide is a work in progress. If you have any feedback, [open an issue](https://github.com/expo/expo/issues/new/choose) in our GitHub repository.
术语 "local-first" 最早是在由研究实验室 [Ink & Switch](https://www.inkandswitch.com/) 撰写的论文 ["本地优先软件"](https://www.inkandswitch.com/local-first/) 中提出的，但其背后的想法已经存在很长时间了。它是支持我们最喜欢的一些应用的架构，例如 [Linear](https://linear.app/)、[Superhuman](https://superhuman.com/)、[Excalidraw](https://excalidraw.com/) 甚至 [Apple 说明](https://en.wikipedia.org/wiki/Notes_\(Apple\))。
¥The term "local-first" was first coined in the paper ["Local-first software"](https://www.inkandswitch.com/local-first/), written by the research lab [Ink & Switch](https://www.inkandswitch.com/), but the ideas behind it have been around for a long time. It's the architecture that powers some of our favorite apps, like [Linear](https://linear.app/), [Superhuman](https://superhuman.com/), [Excalidraw](https://excalidraw.com/), and even [Apple Notes](https://en.wikipedia.org/wiki/Notes_\(Apple\)).
在本地优先软件中，"另一台计算机的可用性绝不会妨碍你工作"（[在 YouTube 上观看](https://www.youtube.com/watch?v=NMq0vncHJvU)）。离线时，你仍然可以直接从设备上的数据库读取和写入。你可以信任该软件离线工作，并且你知道当你连接到互联网时，你的数据将无缝同步并可在运行该应用的任何设备上使用。当你在线时，此架构非常适合 "multiplayer" 应用、[由 Figma 推广](https://www.figma.com/blog/how-figmas-multiplayer-technology-works/)。
¥In local-first software, "the availability of another computer should never prevent you from working" ([via Martin Kleppmann](https://www.youtube.com/watch?v=NMq0vncHJvU)). When you are offline, you can still read and write directly from/to a database on your device. You can trust the software to work offline, and you know that when you are connected to the internet, your data will be seamlessly synced and available on any of your devices running the app. When you're online, this architecture is well suited for "multiplayer" apps, [as popularized by Figma](https://www.figma.com/blog/how-figmas-multiplayer-technology-works/).
要深入了解本地优先是什么以及它是如何工作的，请参阅下面的 [其他资源](#additional-resources)。
¥To dig deeper into what local-first is and how it works, refer to the [additional resources](#additional-resources) below.
<a id="why-use-local-first-architecture"></a>
## 为什么使用本地优先架构？
¥Why use local-first architecture?
<a id="user-experience-benefits"></a>
### 用户体验优势
¥User experience benefits
本地优先软件感觉很快，因为交互不再受网络限制，你可以直接从设备上的数据库读取和写入。
¥Local-first software feels **fast** because interactions are no longer network-bound, you can read and write directly from/to a database on your device.
你可以信任该软件离线工作，并且你知道当你连接到互联网时，你的数据将无缝同步并可在运行该应用的任何设备上使用。
¥You can trust the software to work offline, and you know that when you are connected to the internet, your data will be seamlessly synced and available on any of your devices running the app.
本地优先软件的另一个特点是它具有协作性 - 多个设备可以处理相同的数据，并且更改会在所有设备上同步。当你在 [菲格玛](https://www.figma.com/) 中协作设计时，这可以实时发生，或者当你在 Linear 中离线创建任务时，这可以异步发生，当你再次在线时它会同步。
¥Another characteristic of local-first software is that it is collaborative — multiple devices can work on the same data, and changes are synced across all of them. This can happen in real-time when you collaborate on a design in [Figma](https://www.figma.com/) or asynchronously when you create a task while offline in Linear and it is synced when you are online again.
<a id="developer-experience-benefits"></a>
### 开发者体验优势
¥Developer experience benefits
你不再需要为每个网络请求管理应用的各种状态 — "loaded"、"loading"、"error" 等，以及它们对应的 UI 状态和其他逻辑。写入本地数据库，应用将自动将更改同步到服务器。这意味着你可以专注于构建应用，而不必担心网络和离线状态。
¥You no longer have to manage various states of your app for each network request — "loaded", "loading", "error", and so on, with their corresponding UI states and other logic. Write to a local database, and the app will automatically sync the changes to the server. This means that you can focus on building the app, and not worry as much about the networking and offline states.
你的服务器可用性可能仍然很重要，但如果发生中断，你的用户仍然可以访问应用并继续工作。你甚至可以提供一种无需通过服务器即可同步数据的机制。
¥Your server availability may still be important, but in the event of an outage your users can still access the app and continue working. You may even provide a mechanism to sync the data without going through your server.
<a id="challenges-in-building-local-first-apps"></a>
## 构建本地优先应用的挑战
¥Challenges in building local-first apps
目前可用的工具仍处于早期阶段，因此你可能会发现自己正在解决你期望通过当前使用的工具解决的问题。例如，你可能需要实现自定义同步层，或者你可能必须弄清楚如何处理对同一数据进行操作的多个用户的权限。随着生态系统的发展，我们预计构建本地优先应用将变得更加容易。如果你不准备成为早期采用者，以及随之而来的一切，你可能需要等待工具成熟后再开始使用本地优先工具构建应用。
¥The tools available today are still in their early stages, and so you may find yourself solving problems that you would expect to be solved by the tools you are using today. For example, you may need to implement a custom sync layer, or you may have to figure out how to handle permissions for multiple users operating on the same data. As the ecosystem evolves, we expect it to become easier to build local-first apps. If you're not prepared to be an early adopter, and everything that comes with that, you might want to wait for the tools to mature before you start building your app with local-first tools.
<a id="tools-for-building-local-first-apps"></a>
## 用于构建本地优先应用的工具
¥Tools for building local-first apps
["本地优先软件" 社区网站](https://localfirstweb.dev/) 上提供了全面的工具列表。以下是我们在 Expo 有直接使用经验的工具的简短列表。
¥A comprehensive list of tools is available on the ["Local-first software" community website](https://localfirstweb.dev/). The following is a shorter list of tools that we at Expo have had direct experience working with.
考虑本地优先工具的一种方法是按以下类别对它们进行分组：持久性、状态管理和同步。如果某些工具可以处理问题的多个方面，它们将适合多个类别。同步可以进一步细分为可同步的数据结构和传输层。
¥One way to think of local-first tools is to group them by the following categories: persistence, state management, and syncing. Some tools will fit into multiple categories if they handle multiple aspects of the problem. Syncing can be further subdivided into syncable data structures and transport layers.
<a id="legend-state"></a>
### 图例状态
¥Legend-State
[图例状态](https://legendapp.com/open-source/state/v3/) 是一个超快的一体化状态和同步库，让你可以编写更少的代码来制作更快的应用。它有以下主要目标：
¥[Legend-State](https://legendapp.com/open-source/state/v3/) is a super fast all-in-one state and sync library that lets you write less code to make faster apps. It has the following primary goals:
* React 应用的更快状态管理
  ¥Faster state management for React apps
* 最小渲染的细粒度反应
  ¥Fine-grained reactivity for minimal renders
* 强大的同步和持久性（内置 Supabase 支持）
  ¥Powerful sync and persistence (with Supabase support built-in)
它与 Expo 和 React Native 一起使用（通过 [`react-native-async-storage`](https://github.com/react-native-async-storage/async-storage?tab=readme-ov-file#react-native-async-storage)）。这使其成为构建本地优先移动和网络应用的完美选择。使用 [图例状态 Supabase 示例](https://github.com/expo/examples/tree/master/with-legend-state-supabase) 开始：
¥It works with Expo and React Native (via [`react-native-async-storage`](https://github.com/react-native-async-storage/async-storage?tab=readme-ov-file#react-native-async-storage)). This makes it a perfect match for building local-first mobile and web apps. Get started by using the [Legend-State Supabase example](https://github.com/expo/examples/tree/master/with-legend-state-supabase):
```sh
$ npx create-expo-app --example with-legend-state-supabase
```
<a id="tinybase"></a>
### TinyBase
[TinyBase](https://tinybase.org/) 自称为 "本地优先应用的反应式数据存储"。它是一个状态管理库，可插入许多最流行的同步和持久层，例如 [Yjs](#yjs) 和 [SQLite](#sqlite)。它是构建需要持久化和同步数据的本地优先应用的绝佳选择。使用 [TinyBase 示例](https://github.com/expo/examples/tree/master/with-tinybase) 开始：
¥[TinyBase](https://tinybase.org/) calls itself "the reactive data store for local-first apps". It is a state management library that plugs in to many of the most popular syncing and persistence layers, such as [Yjs](#yjs) and [SQLite](#sqlite). It's a great choice for building local-first apps that need to persist and sync data. Get started by using the [TinyBase example](https://github.com/expo/examples/tree/master/with-tinybase):
```sh
$ npx create-expo-app --example with-tinybase
```
TinyBase 与 Expo Go 无缝协作，让你快速开发。在 Android 和 iOS 上，它使用 [`expo-sqlite`](/versions/latest/sdk/sqlite/) 库来保存数据。在网络上，它依赖于 [`localStorage`](https://web.nodejs.cn/en-US/docs/Web/API/Window/localStorage) API。[Beto Moedano](https://github.com/betomoedano) 在以下视频中演示了如何构建 [通用本地优先购物清单应用](https://github.com/betomoedano/groceries-shopping-list-app)：
¥TinyBase works seamlessly with Expo Go, allowing you to develop quickly. On Android and iOS, it uses the [`expo-sqlite`](/versions/latest/sdk/sqlite/) library to persist data. On the web, it relies on the [`localStorage`](https://web.nodejs.cn/en-US/docs/Web/API/Window/localStorage) API. [Beto Moedano](https://github.com/betomoedano) demonstrates how to build a [Universal Local-first Shopping List App](https://github.com/betomoedano/groceries-shopping-list-app) in the following video:
Video Tutorial: [Watch: Build a Local-First Real-Time Shopping List App with Expo and TinyBase](https://www.youtube.com/watch?v=HqOiB2tDM8Q)
<a id="sqlite"></a>
### SQLite
[Expo SQLite](/versions/latest/sdk/sqlite/) 是一个 SQLite 库，是本地优先应用持久性的绝佳选择。你可以在 SQLite 前面使用不同的状态管理和同步层，例如 [`y-expo-sqlite`](https://github.com/brentvatne/y-expo-sqlite) 用于持久化 [Yjs](#yjs) 文档，[TinyBase](#tinybase) 作为状态管理层。使用 SQLite 非常灵活，但你需要将其与其他工具结合使用或构建自己的工具以获得完整的本地优先解决方案。请参阅 [Expo SQLite API 参考](/versions/latest/sdk/sqlite/) 了解更多信息。
¥[Expo SQLite](/versions/latest/sdk/sqlite/) is a SQLite library that is a great choice for persistence for local-first apps. You can use SQLite with different state management and syncing layers in front of it, such as [`y-expo-sqlite`](https://github.com/brentvatne/y-expo-sqlite) to persist [Yjs](#yjs) documents, and [TinyBase](#tinybase) as a state management layer. Using SQLite is flexible, but you will need to combine it with other tools or build your own tools to get a complete local-first solution. See [Expo SQLite API reference](/versions/latest/sdk/sqlite/) for more information.
<a id="yjs"></a>
### Yjs
[Yjs](https://github.com/yjs/yjs) 是一个 [CRDT 实现](https://github.com/yjs/yjs?tab=readme-ov-file#yjs-crdt-algorithm)，它提供可以在多个客户端之间同步的数据类型。当使用 Yjs 构建应用并处理你希望能够同步的数据时，你将使用 `Y.Array` 和 `Y.Map` 来表示你的数据，而不是 `Array` 和 `Object`。你可以在 Yjs 之上使用像 [TinyBase](#tinybase) 这样的库进行状态管理，并且持久性可以通过各种工具来处理，从文件系统上的 JSON 文件到成熟的数据库（例如 [`y-expo-sqlite`](https://github.com/brentvatne/y-expo-sqlite)）以及介于两者之间的所有内容。请参阅 [Yjs 的 GitHub 存储库](https://github.com/yjs/yjs) 了解更多信息。
¥[Yjs](https://github.com/yjs/yjs) is a [CRDT implementation](https://github.com/yjs/yjs?tab=readme-ov-file#yjs-crdt-algorithm) that provides data types that can be synced across multiple clients. When building an app with Yjs and working with data that you would like to be able to sync, then you would use `Y.Array` and `Y.Map` to represent your data rather than `Array` and `Object`. You may use a library like [TinyBase](#tinybase) for state management on top of Yjs, and persistence can be handled by a variety of tools, from a JSON file on your filesystem to a full-fledged database (such as [`y-expo-sqlite`](https://github.com/brentvatne/y-expo-sqlite)) and everything in between. See [Yjs's GitHub repository](https://github.com/yjs/yjs) for more information.
<a id="prisma"></a>
### Prisma
[Prisma](https://prisma.nodejs.cn) 是众所周知的 Node.js 和 TypeScript 后端最流行的 ORM，现在可用于 [Expo 和 React Native 早期访问](https://www.prisma.io/blog/bringing-prisma-orm-to-react-native-and-expo)。Prisma 旨在提供完整的本地优先解决方案，为你涵盖状态管理、同步和持久性。虽然还处于早期阶段，但 [Beto Moedano](https://github.com/betomoedano) 已经整理了使用 Prisma 和 Expo 构建本地优先 Notion 克隆 [在 GitHub 上查看代码](https://github.com/betomoedano/React-Native-Notion-Clone) 的完整演练。
¥[Prisma](https://prisma.nodejs.cn) is well known as the most popular ORM for Node.js and TypeScript backends, and it's now available for [Expo and React Native in early access](https://www.prisma.io/blog/bringing-prisma-orm-to-react-native-and-expo). Prisma aims to provide a complete local-first solution, with state management, syncing, and persistence all covered for you. While it's still early, [Beto Moedano](https://github.com/betomoedano) has put together a full walkthrough of using Prisma with Expo to build a local-first Notion clone, [check out the code on GitHub](https://github.com/betomoedano/React-Native-Notion-Clone).
Video Tutorial: [Watch: Building a Local-first Notion Clone with React Native Expo and Prisma](https://www.youtube.com/watch?v=uTrPte0sCiw)
<a id="jazz"></a>
### Jazz
[Jazz.tools](https://jazz.tools/docs/react-native) 是一个用于构建本地优先应用的框架。它是开源的，为 Expo 提供一流的支持，你可以自行托管它或使用 [Jazz Cloud](https://jazz.tools/cloud) 快速启动。[Jazz](https://jazz.tools)。要了解更多信息，请查看 [examples](https://jazz.tools/examples#react-native) 或查看 [入门指南](https://jazz.tools/docs/react-native) 以获取详细说明。
¥[Jazz.tools](https://jazz.tools/docs/react-native) is a framework for building local-first apps. It is open source, provides first-class support for Expo and you can self-host it or use [Jazz Cloud](https://jazz.tools/cloud) to start quickly. [Jazz](https://jazz.tools). To learn more, check out the [examples](https://jazz.tools/examples#react-native) or see the [Getting Started Guide](https://jazz.tools/docs/react-native) for detailed instructions.
<a id="livestore"></a>
### LiveStore
[LiveStore](https://docs.livestore.dev/getting-started/expo/) 是一个以客户端为中心的本地优先数据层，适用于高性能应用。它为 Expo 提供一流的支持，是构建本地优先应用的绝佳选择。请参阅有关 [LiveStore:用于本地优先应用的基于 SQLite 的数据层](https://expo.dev/blog/local-first-application-development-with-livestore) 的博客文章。
¥[LiveStore](https://docs.livestore.dev/getting-started/expo/) is a client-centric local-first data layer for high-performance applications. It provides first-class support for Expo, and it's a great choice for building local-first apps. See the blog post on [LiveStore: SQLite-based data layer for local-first apps](https://expo.dev/blog/local-first-application-development-with-livestore).
Video Tutorial: [Watch: How to build local-first native apps with LiveStore and Expo](https://www.youtube.com/watch?v=zQIhJqYU1Qw)
<a id="turso"></a>
### Turso
[Turso](https://turso.tech) 是基于 SQLite 构建的现代数据库服务。现在支持 [离线同步](https://turso.tech/blog/turso-offline-sync-public-beta)，从而实现真正的本地优先体验。你可以使用双向同步和内置冲突检测在本地和远程源之间同步数据库。虽然自动冲突解决功能尚不可用，但此功能仍然是向前迈出的重要一步。你现在就可以将 Turso 与​​ [expo-sqlite](/versions/latest/sdk/sqlite) 一起使用。要了解更多信息，请阅读 [Turso:离线同步公测版](https://turso.tech/blog/turso-offline-sync-public-beta) 博客文章。如需集成示例，请查看 [注意应用](https://github.com/betomoedano/notes-app)。
¥[Turso](https://turso.tech) is a modern database service built on SQLite. It now supports [Offline Sync](https://turso.tech/blog/turso-offline-sync-public-beta), which enables true local-first experiences. You can sync databases between local and remote sources with bidirectional sync and built-in conflict detection. While automatic conflict resolution isn't available yet, this feature is still a major step forward. You can use Turso today with [expo-sqlite](/versions/latest/sdk/sqlite). To learn more, read the [Turso: Offline Sync Public Beta](https://turso.tech/blog/turso-offline-sync-public-beta) blog post. For an example integration, check out the [Notes App](https://github.com/betomoedano/notes-app).
Video Tutorial: [Watch: How to build a local-first Notes App with Turso and Expo](https://www.youtube.com/watch?v=SBv32tmyb3k)
<a id="instant"></a>
### 即时
¥Instant
[即时](https://www.instantdb.com/) 是 Firebase 的现代替代方案。它为你提供实时数据库，让你可以专注于构建应用的前端。要开始使用，请查看 [入门指南](https://www.instantdb.com/docs/start-rn)。你还可以观看以下视频，探索 [Sketch 应用](https://github.com/betomoedano/sketch-app) 的精彩内容。
¥[Instant](https://www.instantdb.com/) is a modern alternative to Firebase. It gives you a real-time database so you can focus on building your app's frontend. To get started, check out the [Getting Started Guide](https://www.instantdb.com/docs/start-rn). You can also explore the [Sketch App](https://github.com/betomoedano/sketch-app) featured in the video below.
Video Tutorial: [Watch: Build a Local-First Sketch App with Expo, Instant & Reanimated](https://www.youtube.com/watch?v=DEJIcaGN3vY)
<a id="other-tools"></a>
### 其他工具
¥Other tools
以下列表远非全面，它提供了引起我们注意的其他工具，你可能会觉得很有趣。有关更详细的工具列表，请参阅 ["本地优先软件" 社区网站](https://localfirstweb.dev/)。
¥The following list, far from being comprehensive, provides other tools that have caught our attention and that you may find interesting to explore. For a more thorough list of tools, see ["Local-first software" community website](https://localfirstweb.dev/).
* [自动合并](https://automerge.org/)
  ¥[Automerge](https://automerge.org/)
* [ElectricSQL](https://electric-sql.com/)
* [PowerSync](https://www.powersync.com/)
<a id="additional-resources"></a>
## 其他资源
¥Additional resources
* Martin Kleppmann 的 ["本地优先的过去、现在和未来"](https://www.youtube.com/watch?v=NMq0vncHJvU)
  ¥["The past, present, and future of local-first"](https://www.youtube.com/watch?v=NMq0vncHJvU) by Martin Kleppmann
* Ink & Switch 的 ["本地优先软件"](https://www.inkandswitch.com/local-first/)
  ¥["Local-first software"](https://www.inkandswitch.com/local-first/) by Ink & Switch
* ["本地优先软件" 社区网站](https://localfirstweb.dev/) 和 [最低 Xcode 版本要求](https://www.youtube.com/playlist?list=PLTbD2QA-VMnXFsLbuPGz1H-Najv9MD2-H)
  ¥["Local-first software" community website](https://localfirstweb.dev/) and [meetup playlist on YouTube](https://www.youtube.com/playlist?list=PLTbD2QA-VMnXFsLbuPGz1H-Najv9MD2-H)
* Johannes Schickling 的 [YouTube 上的聚会播放列表](https://localfirst.fm/)
  ¥[localfirst.fm podcast](https://localfirst.fm/) by Johannes Schickling


## 键盘处理

处理 Android 或 iOS 设备上常见键盘交互的指南。

键盘处理对于在你的 Expo 应用中创造出色的用户体验至关重要。React Native 提供 [`Keyboard`](https://rn.nodejs.cn/docs/keyboard) 和 [`KeyboardAvoidingView`](https://rn.nodejs.cn/docs/keyboardavoidingview)，它们通常用于处理键盘事件。对于更复杂或自定义的键盘交互，你可以考虑使用 [`react-native-keyboard-controller`](https://kirillzyusko.github.io/react-native-keyboard-controller)，这是一个提供高级键盘处理功能的库。
¥Keyboard handling is crucial for creating an excellent user experience in your Expo app. React Native provides [`Keyboard`](https://rn.nodejs.cn/docs/keyboard) and [`KeyboardAvoidingView`](https://rn.nodejs.cn/docs/keyboardavoidingview), which are commonly used to handle keyboard events. For more complex or custom keyboard interactions, you can consider using [`react-native-keyboard-controller`](https://kirillzyusko.github.io/react-native-keyboard-controller), which is a library that offers advanced keyboard handling capabilities.
本指南介绍常见的键盘交互以及如何有效地管理它们。
¥This guide covers common keyboard interactions and how to manage them effectively.
Video Tutorial: [Keyboard Handling tutorial for React Native apps](https://www.youtube.com/watch?v=Y51mDfAhd4E)
<a id="keyboard-handling-basics"></a>
## 键盘处理基础
¥Keyboard handling basics
以下部分介绍如何使用通用 API 处理键盘交互。
¥The following sections explain how to handle keyboard interactions with common APIs.
<a id="keyboard-avoiding-view"></a>
### 键盘避免视图
¥Keyboard avoiding view
`KeyboardAvoidingView` 是一个组件，它根据键盘高度自动调整键盘的高度、位置或底部填充，以在显示时保持可见。
¥The `KeyboardAvoidingView` is a component that automatically adjusts a keyboard's height, position, or bottom padding based on the keyboard height to remain visible while it is displayed.
Android 和 iOS 与 `behavior` 属性的交互方式不同。在 iOS 上，`padding` 通常效果最好，而对于 Android，仅使用 `KeyboardAvoidingView` 即可防止覆盖输入。这就是以下示例使用 Android 的 `undefined` 的原因。尝试使用 `behavior` 是一种很好的做法，因为不同的选项可能最适合你的应用。
¥Android and iOS interact with the `behavior` property differently. On iOS, `padding` is usually what works best, and for Android, just having the `KeyboardAvoidingView` prevents covering the input. This is why the following example uses `undefined` for Android. Playing around with the `behavior` is a good practice since a different option could work best for your app.
```tsx HomeScreen.tsx
import { KeyboardAvoidingView, TextInput } from 'react-native';
export default function HomeScreen() {
  return (
    <KeyboardAvoidingView behavior={Platform.OS === 'ios' ? 'padding' : undefined} style={{ flex: 1 }}>
      <TextInput placeholder="Type here..." />
    </KeyboardAvoidingView>;
  );
}
```
在上面的例子中，`KeyboardAvoidingView` 的高度会根据设备的键盘高度自动调整，从而确保输入始终可见。
¥In the above example, the height of the `KeyboardAvoidingView` automatically adjusts based on the device's keyboard height, which ensures that the input is always visible.
在 Android 上使用底部选项卡导航器时，你可能会注意到，聚焦于输入字段会导致底部选项卡被推到键盘上方。要解决此问题，请将 `softwareKeyboardLayoutMode` 属性添加到 [应用配置](/workflow/configuration/) 中的 Android 配置中并将其设置为 `pan`。
¥When using a Bottom Tab navigator on Android, you might notice that focusing on an input field causes the bottom tabs to be pushed above the keyboard. To address this issue, add the `softwareKeyboardLayoutMode` property to your Android configuration in [app config](/workflow/configuration/) and set it to `pan`.
```json app.json
"expo" {
  "android": {
    "softwareKeyboardLayoutMode": "pan"
  }
}
```
添加此属性后，重新启动开发服务器并重新加载你的应用以应用更改。
¥After adding this property, restart the development server and reload your app to apply the changes.
当使用 [`tabBarHideOnKeyboard`](https://react-navigation.nodejs.cn/docs/bottom-tab-navigator/#tabbarhideonkeyboard) 打开键盘时，还可以隐藏底部选项卡。它是底部选项卡导航器的一个选项。如果设置为 `true`，它将在键盘打开时隐藏栏。
¥It's also possible to hide the bottom tab when the keyboard opens using [`tabBarHideOnKeyboard`](https://react-navigation.nodejs.cn/docs/bottom-tab-navigator/#tabbarhideonkeyboard). It is an option with the Bottom Tab Navigator. If set to `true`, it will hide the bar when the keyboard opens.
```tsx app/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs
      screenOptions={{
        tabBarHideOnKeyboard: true,
      }}>
      <Tabs.Screen name="index" />
    </Tabs>
  );
}
```
<a id="keyboard-events"></a>
### 键盘事件
¥Keyboard events
React Native 的 `Keyboard` 模块允许你监听原生事件、对其做出反应并对键盘进行更改（例如关闭键盘）。
¥The `Keyboard` module from React Native allows you to listen for native events, react to them, and make changes to the keyboard, such as dismissing it.
要监听键盘事件，请使用 `Keyboard.addListener` 方法。此方法接受事件名称和回调函数作为参数。当显示或隐藏键盘时，将使用事件数据调用回调函数。
¥To listen for keyboard events, use the `Keyboard.addListener` method. This method accepts an event name and a callback function as arguments. When the keyboard is shown or hidden, the callback function is called with the event data.
以下示例说明了添加键盘监听器的用例。每次键盘显示或隐藏时，状态变量 `isKeyboardVisible` 都会切换。基于此变量，按钮允许用户仅在键盘处于活动状态时关闭键盘。另请注意，按钮使用 `Keyboard.dismiss` 方法。
¥The following example illustrates a use case for adding a keyboard listener. The state variable `isKeyboardVisible` is toggled each time the keyboard shows or hides. Based on this variable, a button allows the user to dismiss the keyboard only if the keyboard is active. Also, notice that the button uses the `Keyboard.dismiss` method.
```tsx HomeScreen.tsx
import { useEffect, useState } from 'react';
import { Keyboard, View, Button, TextInput } from 'react-native';
export default function HomeScreen() {
  const [isKeyboardVisible, setIsKeyboardVisible] = useState(false);
  useEffect(() => {
    const showSubscription = Keyboard.addListener('keyboardDidShow', handleKeyboardShow);
    const hideSubscription = Keyboard.addListener('keyboardDidHide', handleKeyboardHide);
    return () => {
      showSubscription.remove();
    };
  }, []);
  const handleKeyboardShow = event => {
    setIsKeyboardVisible(true);
  };
  const handleKeyboardHide = event => {
    setIsKeyboardVisible(false);
  };
  return (
    <View>
      {isKeyboardVisible && <Button title="Dismiss keyboard" onPress={Keyboard.dismiss} />}
      <TextInput placeholder="Type here..." />
    </View>
  );
}
```
<a id="advanced-keyboard-handling-with-keyboard-controller"></a>
## 使用键盘控制器进行高级键盘处理
¥Advanced keyboard handling with Keyboard Controller
对于更复杂的键盘交互，例如带有多个文本输入字段的更大的可滚动输入表单，请考虑使用 [`react-native-keyboard-controller`（键盘控制器）](https://kirillzyusko.github.io/react-native-keyboard-controller) 库。它提供了内置 React Native 键盘 API 之外的附加功能，以最少的配置提供跨 Android 和 iOS 的一致性，并提供用户期望的原生体验。
¥For more complex keyboard interactions, such as larger scrollable entry forms with several text input fields, consider using the [`react-native-keyboard-controller` (Keyboard Controller)](https://kirillzyusko.github.io/react-native-keyboard-controller) library. It offers additional functionality beyond the built-in React Native keyboard APIs, providing consistency across Android and iOS with minimal configuration and offering the native feel users expect.
<a id="prerequisites"></a>
### 先决条件
¥Prerequisites
由于 Expo Go 中不包含键盘控制器库，因此使用 [开发构建](/develop/development-builds/introduction/) 描述以下步骤。请参阅 [创建开发版本](/develop/development-builds/create-a-build/) 了解更多信息。
¥The following steps are described using a [development build](/develop/development-builds/introduction/) since the Keyboard Controller library is not included in Expo Go. See [Create a development build](/develop/development-builds/create-a-build/) for more information.
[键盘控制器](https://kirillzyusko.github.io/react-native-keyboard-controller) 还需要 `react-native-reanimated` 才能正常工作。要安装它，请按照这些 [安装说明](/versions/latest/sdk/reanimated/#installation) 进行操作。
¥[Keyboard Controller](https://kirillzyusko.github.io/react-native-keyboard-controller) also requires `react-native-reanimated` to work correctly. To install it, follow these [installation instructions](/versions/latest/sdk/reanimated/#installation).
<a id="install"></a>
### 安装
¥Install
首先在你的 Expo 项目中安装键盘控制器库：
¥Start by installing the Keyboard Controller library in your Expo project:
```sh
$ npx expo install react-native-keyboard-controller
```
<a id="set-up-provider"></a>
### 设置双向关联
¥Set up provider
要完成设置，请将 `KeyboardProvider` 添加到你的应用中。
¥To finalize the setup, add the `KeyboardProvider` to your app.
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
import { KeyboardProvider } from 'react-native-keyboard-controller';
export default function RootLayout() {
  return (
    <KeyboardProvider>
      <Stack>
        <Stack.Screen name="home" />
        <Stack.Screen name="chat" />
      </Stack>
    </KeyboardProvider>
  );
}
```
<a id="handling-multiple-inputs"></a>
### 处理多个输入
¥Handling multiple inputs
[`KeyboardAvoidingView`](#keyboard-avoiding-view) 组件非常适合原型设计，但它需要特定于平台的配置，并且可定制性较差。
¥The [`KeyboardAvoidingView`](#keyboard-avoiding-view) component is excellent for prototyping, but it requires platform-specific configuration and is not very customizable.
作为更强大的替代方案，你可以使用 [`KeyboardAwareScrollView`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/components/keyboard-aware-scroll-view) 组件。它会自动滚动到聚焦的 `TextInput` 窗口，并提供类似原生的性能。对于只有少量元素的简单屏幕，使用 `KeyboardAwareScrollView` 是一种很好的方法。
¥As a more powerful alternative, you can use the [`KeyboardAwareScrollView`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/components/keyboard-aware-scroll-view) component. It automatically scrolls to a focused `TextInput` and provides native-like performance. For simple screens with only a few elements, using `KeyboardAwareScrollView` is a great approach.
对于具有多个输入的屏幕，键盘控制器库还提供了一个 `KeyboardToolbar` 组件，可与 `KeyboardAwareScrollView` 一起使用。这些组件共同处理输入导航，并防止键盘在无需自定义配置的情况下遮挡屏幕：
¥For screens with multiple inputs, the Keyboard Controller library also provides a `KeyboardToolbar` component to use alongside `KeyboardAwareScrollView`. Together, these components handle input navigation and prevent the keyboard from covering the screen without custom configuration:
```tsx FormScreen.tsx
import { TextInput, View, StyleSheet } from 'react-native';
import { KeyboardAwareScrollView, KeyboardToolbar } from 'react-native-keyboard-controller';
export default function FormScreen() {
  return (
    <>
      <KeyboardAwareScrollView bottomOffset={62} contentContainerStyle={styles.container}>
        <View>
          <TextInput placeholder="Type a message..." style={styles.textInput} />
          <TextInput placeholder="Type a message..." style={styles.textInput} />
        </View>
        <TextInput placeholder="Type a message..." style={styles.textInput} />
        <View>
          <TextInput placeholder="Type a message..." style={styles.textInput} />
          <TextInput placeholder="Type a message..." style={styles.textInput} />
          <TextInput placeholder="Type a message..." style={styles.textInput} />
        </View>
        <TextInput placeholder="Type a message..." style={styles.textInput} />
      </KeyboardAwareScrollView>
      <KeyboardToolbar />
    </>
  );
}
const styles = StyleSheet.create({
  container: {
    gap: 16,
    padding: 16,
  },
  listStyle: {
    padding: 16,
    gap: 16,
  },
  textInput: {
    width: 'auto',
    flexGrow: 1,
    flexShrink: 1,
    height: 45,
    borderWidth: 1,
    borderRadius: 8,
    borderColor: '#d8d8d8',
    backgroundColor: '#fff',
    padding: 8,
    marginBottom: 8,
  },
});
```
上述示例用 `KeyboardAwareScrollView` 封装输入，以防止键盘覆盖它们。`KeyboardToolbar` 组件显示导航控件和关闭按钮。虽然它无需配置即可工作，但你可以根据需要自定义工具栏内容。
¥The above example wraps the inputs with `KeyboardAwareScrollView` to prevent the keyboard from covering them. The `KeyboardToolbar` component displays navigation controls and a dismiss button. While it works without configuration, you can customize the toolbar content if needed.
<a id="animating-views-in-sync-with-keyboard-height"></a>
### 与键盘高度同步的动画视图
¥Animating views in sync with keyboard height
对于更高级和可定制的方法，你可以使用 [`useKeyboardHandler`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/keyboard/use-keyboard-handler)。它提供对键盘生命周期事件的访问。它允许我们确定键盘何时开始动画以及它在动画的每一帧中的位置。
¥For a more advanced and customizable approach, you can use [`useKeyboardHandler`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/keyboard/use-keyboard-handler). It provides access to keyboard lifecycle events. It allows us to determine when the keyboard starts animating and its position in every frame of the animation.
使用 `useKeyboardHandler` 钩子，你可以创建一个自定义钩子来访问每帧键盘的高度。它使用来自 reanimated 的 `useSharedValue` 返回高度，如下所示。
¥Using the `useKeyboardHandler` hook, you can create a custom hook to access the height of the keyboard at each frame. It uses `useSharedValue` from reanimated to return the height, as shown below.
```tsx ChatScreen.tsx
import { useKeyboardHandler } from 'react-native-keyboard-controller';
import Animated, { useAnimatedStyle, useSharedValue } from 'react-native-reanimated';
const useGradualAnimation = () => {
  const height = useSharedValue(0);
  useKeyboardHandler(
    {
      onMove: event => {
        'worklet';
        height.value = Math.max(event.height, 0);
      },
    },
    []
  );
  return { height };
};
```
你可以使用 `useGradualAnimation` 钩子为视图设置动画，并在键盘处于活动状态或关闭状态时为其提供流畅的动画，例如在聊天屏幕组件中（如下例所示）。此组件从钩子中获取键盘高度。然后，它使用来自 reanimated 的 `useAnimatedStyle` 钩子创建一个名为 `fakeView` 的动画样式。此样式仅包含一个属性：`height`，设置为键盘的高度。
¥You can use the `useGradualAnimation` hook to animate a view and give it a smooth animation when the keyboard is active or dismissed, for example, in a chat screen component (shown in the example below). This component gets the keyboard height from the hook. It then creates an animated style called `fakeView` using the `useAnimatedStyle` hook from reanimated. This style only contains one property: `height`, which is set to the keyboard's height.
`fakeView` 动画样式用于 `TextInput` 之后的动画视图中。此视图的高度将根据每帧的键盘高度进行动画处理，从而有效地将内容以流畅的动画推到键盘上方。当键盘关闭时，它还会将其高度减小到零。
¥The `fakeView` animated style is used in an animated view after the `TextInput`. This view's height will animate based on the keyboard's height at each frame, which effectively pushes the content above the keyboard with a smooth animation. It also decreases its height to zero when the keyboard is dismissed.
```tsx ChatScreen.tsx
import { StyleSheet, Platform, FlatList, View, StatusBar, TextInput } from 'react-native';
import Animated, { useAnimatedStyle, useSharedValue } from 'react-native-reanimated';
import { useKeyboardHandler } from 'react-native-keyboard-controller';
import MessageItem from '@/components/MessageItem';
import { messages } from '@/messages';
const useGradualAnimation = () => {
};
export default function ChatScreen() {
  const { height } = useGradualAnimation();
  const fakeView = useAnimatedStyle(() => {
    return {
      height: Math.abs(height.value),
    };
  }, []);
  return (
    <View style={styles.container}>
      <FlatList
        data={messages}
        renderItem={({ item }) => <MessageItem message={item} />}
        keyExtractor={item => item.createdAt.toString()}
        contentContainerStyle={styles.listStyle}
      />
      <TextInput placeholder="Type a message..." style={styles.textInput} />
      <Animated.View style={fakeView} />
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    paddingTop: Platform.OS === 'android' ? StatusBar.currentHeight : 0,
  },
  listStyle: {
    padding: 16,
    gap: 16,
  },
  textInput: {
    width: '95%',
    height: 45,
    borderWidth: 1,
    borderRadius: 8,
    borderColor: '#d8d8d8',
    backgroundColor: '#fff',
    padding: 8,
    alignSelf: 'center',
    marginBottom: 8,
  },
});
```
<a id="additional-resources"></a>
## 其他资源
¥Additional resources


# 集成

## React Native 分析 SDK 和库

Expo 和 React Native 生态系统中可用的分析服务概述。

分析服务允许你跟踪用户如何与你的应用交互。有了这些数据，你就可以在改进应用时采取谨慎的方法。
¥An analytics service allows you to track how users interact with your app. With this data, you can take a measured approach when improving your app.
以下列表提供了 Expo 和 React Native 生态系统中可用的常见分析提供程序。
¥The following list provides common analytics providers that are available in the Expo and React Native ecosystem.
> 大多数分析 SDK 需要配置自定义原生代码。使用 Expo Go 时，原生代码不可配置。但是，你可以创建 [开发构建](/develop/development-builds/introduction/)，这将允许你使用以下任何服务。
>
> ¥Most analytics SDK requires configuring custom native code. Native code is not configurable when using Expo Go. However, you can create a [development build](/develop/development-builds/introduction/), which will allow you to use any of the services below.


## 使用 Facebook 身份验证

有关使用 React-native-fbsdk-next 库将 Facebook 身份验证集成到 Expo 项目中的指南。

[`react-native-fbsdk-next`](https://github.com/thebergamo/react-native-fbsdk-next/) 库提供了 Facebook 的 Android 和 iOS SDK 的封装器。它允许将 Facebook 身份验证集成到你的 Expo 项目中，并提供对原生组件的访问。
¥The [`react-native-fbsdk-next`](https://github.com/thebergamo/react-native-fbsdk-next/) library provides a wrapper around Facebook's Android and iOS SDKs. It allows integrating Facebook authentication into your Expo project and provide access to native components.
本指南提供了有关使用 Expo for Android 配置库的更多信息。
¥This guide provides additional information on configuring the library with Expo for Android.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
`react-native-fbsdk-next` 库无法在 Expo Go 应用中使用，因为它需要自定义原生代码。了解有关 [将自定义原生代码添加到你的应用](/workflow/customizing/) 的更多信息。
¥The `react-native-fbsdk-next` library can't be used in the Expo Go app because it requires custom native code. Learn more about [adding custom native code to your app](/workflow/customizing/).
<a id="installation"></a>
## 安装
¥Installation
有关如何安装和配置库的说明，请参阅 `react-native-fbsdk-next` 文档：
¥See `react-native-fbsdk-next` documentation for instructions on how to install and configure the library:
<a id="configuration-for-android"></a>
## 安卓配置
¥Configuration for Android
将 Android 添加为 Facebook 项目中的平台需要你的应用获得 Google Play 商店的批准，以便它具有有效的 Play 商店 URL 以及与你的应用关联的 [`package`](/versions/latest/config/app/#package) 名称。否则，你将遇到以下错误：
¥Adding Android as a platform in your Facebook project requires you to have your app approved by Google Play Store so that it has a valid Play Store URL, and the [`package`](/versions/latest/config/app/#package) name associated with your app. Otherwise, you'll run into the following error:
有关如何为应用商店构建项目的更多信息，请参阅以下指南：
¥See the following guides for more information on how to build your project for app stores:
将应用上传到 Play 商店后，你就可以提交应用评论。一旦获得批准，Facebook 项目将能够通过 Play 商店 URL 访问它。
¥Once you have uploaded the app to the Play Store you can submit your app review. When it is approved the Facebook project will be able to access it at a Play Store URL.
之后，转到 Facebook 项目的“设置”>“基本”并添加 Android 平台。你需要提供密钥哈希、包名称和类名称。
¥After that, go to your Facebook project's **Settings** > **Basic** and add the **Android** platform. You'll need to provide the Key hash, Package name and Class name.
* 要添加密钥哈希，请转至 Play 商店控制台，从“发布”>“设置”>“应用完整性”>“应用签名密钥证书”获取 SHA-1 证书指纹。然后，[将证书的 Hex 值转换为 Base64](https://base64.guru/converter/encode/hex) 并将其添加到 Facebook 项目中的 Android > Key hashes 下。
  ¥To add Key hash, go to your Play Store Console to obtain the SHA-1 certificate fingerprint from **Release** > **Setup** > **App Integrity** > **App signing key certificate**. Then, [convert the value of the Hex value of the certificate to Base64](https://base64.guru/converter/encode/hex) and add it under the **Android** > **Key hashes** in your Facebook project.
* 你可以在 [应用配置](/versions/latest/config/app) 的 [`android.package`](/versions/latest/config/app/#package) 字段下找到包名称。
  ¥You can find the Package name in your [app config](/versions/latest/config/app) under the [`android.package`](/versions/latest/config/app/#package) field.
* 默认情况下，类名是 `MainActivity`，你可以使用 `package.MainActivity`，其中 `package` 是项目应用配置中的 `android.package`。例如，`com.myapp.example.MainActivity`，其中 `com.myapp.example` 是应用的 `package` 名称。
  ¥The Class name is `MainActivity` by default, and you can use `package.MainActivity` where `package` is the `android.package` in your project's app config. For example, `com.myapp.example.MainActivity`, where `com.myapp.example` is the `package` name of your app.
* 然后，单击保存更改以保存配置。
  ¥Then, click **Save changes** to save the configuration.
现在，你可以使用 Facebook 项目来开发或发布构建和生产应用。
¥Now, you can use your Facebook project for development or release builds and production apps.


## 使用 Supabase

使用 Supabase 将 Postgres 数据库和用户身份验证添加到你的 React Native 应用。

[苏帕贝斯](https://supabase.com/?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) 是一个后端即服务 (BaaS) 应用开发平台，提供托管后端服务，例如 Postgres 数据库、用户身份验证、文件存储、边缘功能、实时同步以及矢量和 AI 工具包。它是 Google Firebase 的开源替代品。
¥[Supabase](https://supabase.com/?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) is a Backend-as-a-Service (BaaS) app development platform that provides hosted backend services such as a Postgres database, user authentication, file storage, edge functions, realtime syncing, and a vector and AI toolkit. It's an open-source alternative to Google's Firebase.
Supabase 自动从你的数据库中进行 [生成 REST API](https://supabase.com/docs/guides/api?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native)，并采用名为 [行级安全性 (RLS)](https://supabase.com/docs/guides/auth/row-level-security?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) 的概念来保护你的数据，从而可以从 React Native 应用直接与数据库进行交互，而无需通过服务器！
¥Supabase automatically [generates a REST API](https://supabase.com/docs/guides/api?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) from your database and employs a concept called [row level security (RLS)](https://supabase.com/docs/guides/auth/row-level-security?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) to secure your data, making it possible to directly interact with your database from your React Native application without needing to go through a server!
Supabase 提供了一个名为 [`supabase-js`](https://supabase.com/docs/reference/javascript/introduction?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) 的 TypeScript 客户端库来与 REST API 进行交互。或者，Supabase 还公开了 [GraphQL API](https://supabase.com/docs/guides/database/extensions/pg_graphql?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native)，允许你根据需要使用你最喜欢的 GraphQL 客户端（例如 [Apollo 客户端](https://supabase.github.io/pg_graphql/usage_with_apollo/)）。
¥Supabase provides a TypeScript client library called [`supabase-js`](https://supabase.com/docs/reference/javascript/introduction?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) to interact with the REST API. Alternatively, Supabase also exposes a [GraphQL API](https://supabase.com/docs/guides/database/extensions/pg_graphql?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) allowing you to use your favorite GraphQL client (for example, [Apollo Client](https://supabase.github.io/pg_graphql/usage_with_apollo/)) should you wish to.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
前往 [database.new](https://database.new?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) 创建一个新的 Supabase 项目。
¥Head over to [database.new](https://database.new?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) to create a new Supabase project.
<a id="get-the-api-keys"></a>
### 获取 API 密钥
¥Get the API Keys
从 API 设置中获取项目 URL 和 `anon` 密钥。
¥Get the Project URL and `anon` key from the API settings.
1. 转到仪表板中的 [API 设置](https://supabase.com/dashboard/project/_/settings/api) 页面。
   ¥Go to the [API Settings](https://supabase.com/dashboard/project/_/settings/api) page in the Dashboard.
2. 在此页面上找到你的项目 `URL`、`anon` 和 `service_role` 密钥。
   ¥Find your Project `URL`, `anon`, and `service_role` keys on this page.
<a id="using-the-supabase-typescript-sdk"></a>
## 使用 Supabase TypeScript SDK
¥Using the Supabase TypeScript SDK
使用 [`supabase-js`](https://supabase.com/docs/reference/javascript/introduction?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) 是充分利用 Supabase 堆栈功能的最便捷方式，因为它可以方便地将所有不同的服务（数据库、身份验证、实时、存储、边缘功能）组合在一起。
¥Using [`supabase-js`](https://supabase.com/docs/reference/javascript/introduction?utm_source=expo\&utm_medium=referral\&utm_term=expo-react-native) is the most convenient way of leveraging the full power of the Supabase stack as it conveniently combines all the different services (database, auth, realtime, storage, edge functions) together.
<a id="install-and-initialize-the-supabase-typescript-sdk"></a>
### 安装并初始化 Supabase TypeScript SDK
¥Install and initialize the Supabase TypeScript SDK
Step 1: 
After you have created your [Expo project](/get-started/create-a-project/), install `@supabase/supabase-js` and the required dependencies using the following command:
```sh
$ npx expo install @supabase/supabase-js @react-native-async-storage/async-storage react-native-url-polyfill
```
Step 2: 
Create a helper file to initialize the Supabase client (`@supabase/supabase-js`). You need the API URL and the `anon` key copied [earlier](#get-the-api-keys). These variables are safe to expose in your Expo app since Supabase has [Row Level Security](https://supabase.com/docs/guides/auth/row-level-security?utm_source=expo&utm_medium=referral&utm_term=expo-react-native) enabled in the Database.
```ts utils/supabase.ts
import 'react-native-url-polyfill/auto';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { createClient } from '@supabase/supabase-js';
const supabaseUrl = YOUR_REACT_NATIVE_SUPABASE_URL;
const supabaseAnonKey = YOUR_REACT_NATIVE_SUPABASE_ANON_KEY;
export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: {
    storage: AsyncStorage,
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false,
  },
});
```
Now you can `import { supabase } from '/utils/supabase'` throughout your application to leverage the full power of Supabase!
<a id="next-steps"></a>
## 下一步
¥Next steps


## 使用 Firebase

有关入门和使用 Firebase JS SDK 和 React Native Firebase 库的指南。

[Firebase](https://firebase.google.com/) 是一个后端即服务 (BaaS) 应用开发平台，提供托管后端服务，例如实时数据库、云存储、身份验证、崩溃报告、分析等。它建立在 Google 的基础设施之上，并可自动扩展。
¥[Firebase](https://firebase.google.com/) is a Backend-as-a-Service (BaaS) app development platform that provides hosted backend services such as real-time database, cloud storage, authentication, crash reporting, analytics, and so on.
It is built on Google's infrastructure and scales automatically.
你可以通过两种不同的方式在项目中使用 Firebase：
¥There are two different ways you can use Firebase in your projects:
* 使用 [Firebase JS SDK](#using-firebase-js-sdk)
  ¥Using [Firebase JS SDK](#using-firebase-js-sdk)
* 使用 [React Native Firebase](#using-react-native-firebase)
  ¥Using [React Native Firebase](#using-react-native-firebase)
React Native 同时支持 JS SDK 和原生 SDK。以下部分将指导你了解何时使用哪个 SDK 以及在 Expo 项目中使用 Firebase 所需的所有配置步骤。
¥React Native supports both the JS SDK and the native SDK. The following sections will guide you through when to use which SDK and all the configuration steps required to use Firebase in your Expo projects.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
在继续之前，请确保你已创建一个新的 Firebase 项目或使用 [Firebase 控制台](https://console.firebase.google.com/)。
¥Before proceeding, make sure that you have created a new Firebase project or have an existing one using the [Firebase console](https://console.firebase.google.com/).
<a id="using-firebase-js-sdk"></a>
## 使用 Firebase JS SDK
¥Using Firebase JS SDK
[Firebase JS SDK](https://firebase.google.com/docs/web/setup) 是一个 JavaScript 库，可让你与项目中的 Firebase 服务进行交互。它支持 React Native 应用中的 [验证](https://firebase.google.com/docs/auth)、[Firestore](https://firebase.google.com/docs/firestore)、[实时数据库](https://firebase.google.com/docs/database) 和 [贮存](https://firebase.google.com/docs/storage) 等服务。
¥The [Firebase JS SDK](https://firebase.google.com/docs/web/setup) is a JavaScript library that allows you to interact with Firebase services in your project.
It supports services such as [Authentication](https://firebase.google.com/docs/auth), [Firestore](https://firebase.google.com/docs/firestore), [Realtime Database](https://firebase.google.com/docs/database), and [Storage](https://firebase.google.com/docs/storage) in a React Native app.
<a id="when-to-use-firebase-js-sdk"></a>
### 何时使用 Firebase JS SDK
¥When to use Firebase JS SDK
当你满足以下条件时，可以考虑使用 Firebase JS SDK：
¥You can consider using the Firebase JS SDK when you:
* 想要在你的应用中使用 Firebase 服务，例如身份验证、Firestore、实时数据库和存储，并且想要使用 [**Expo**](/get-started/set-up-your-environment/) 开发你的应用。
  ¥Want to use Firebase services such as Authentication, Firestore, Realtime Database, and Storage in your app and want to develop your app with [**Expo Go**](/get-started/set-up-your-environment/).
* 想要快速开始使用 Firebase 服务。
  ¥Want a quick start with Firebase services.
* 想要创建适用于 Android、iOS 和 Web 的通用应用。
  ¥Want to create a universal app for Android, iOS, and the web.
<a id="caveats"></a>
#### 注意事项
¥Caveats
Firebase JS SDK 不支持移动应用的所有服务。其中一些服务包括 Analytics、Dynamic Links 和 Crashlytics。如果你想使用这些服务，请参阅 [React Native Firebase](#using-react-native-firebase) 部分。
¥Firebase JS SDK does not support all services for mobile apps. Some of these services are Analytics, Dynamic Links and Crashlytics. See the [React Native Firebase](#using-react-native-firebase) section if you want to use these services.
<a id="install-and-initialize-firebase-js-sdk"></a>
### 安装并初始化 Firebase JS SDK
¥Install and initialize Firebase JS SDK
以下小节使用 `firebase@9.x.x`。Expo SDK 不会强制或推荐在你的应用中使用任何特定版本的 Firebase。
¥The following sub-sections use `firebase@9.x.x`. Expo SDK does not enforce or recommend any specific version of Firebase to use in your app.
如果你在项目中使用旧版本的 firebase 库，则可能需要在 [Firebase JS SDK 文档](https://github.com/firebase/firebase-js-sdk) 的帮助下调整代码示例以匹配你正在使用的版本。
¥If you are using an older version of the firebase library in your project, you may have to adapt the code examples to match the version that you are using with the help of the [Firebase JS SDK documentation](https://github.com/firebase/firebase-js-sdk).
Step 1: 
#### Install the SDK
After you have created your [Expo project](/get-started/create-a-project/), you can install the Firebase JS SDK using the following command:
```sh
$ npx expo install firebase
```
Step 2: 
#### Initialize the SDK in your project
To initialize the Firebase instance in your Expo project, you must create a config object and pass it to the `initializeApp()` method imported from the `firebase/app` module.
The config object requires an API key and other unique identifiers. To obtain these values, you will have to register a web app in your Firebase project. You can find these instructions in the [Firebase documentation](https://firebase.google.com/docs/web/setup#register-app).
After you have the API key and other identifiers, you can paste the following code snippet by creating a new **firebaseConfig.js** file in your project's root directory or any other directory where you keep the configuration files.
```js firebaseConfig.js
import { initializeApp } from 'firebase/app';
// Optionally import the services that you want to use
// import {...} from 'firebase/auth';
// import {...} from 'firebase/database';
// import {...} from 'firebase/firestore';
// import {...} from 'firebase/functions';
// import {...} from 'firebase/storage';
// Initialize Firebase
const firebaseConfig = {
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
};
const app = initializeApp(firebaseConfig);
// For more information on how to access Firebase in your project,
// see the Firebase documentation: https://firebase.google.com/docs/web/setup#access-firebase
```
You do not have to install other plugins or configurations to use Firebase JS SDK.
Firebase version 9 and above provide a modular API. You can directly import any service you want to use from the `firebase` package. For example, if you want to use an authentication service in your project, you can import the `auth` module from the `firebase/auth` package.
> **info** **Troubleshooting tip:** If you encounter issues related to authentication persistence with Firebase JS SDK, see the guide for [setting up persistence to keep users logged in between reloads](https://expo.fyi/firebase-js-auth-setup).
Step 3: 
#### Configure Metro
> **info** If you are using Firebase version `9.7.x` and above, you need to add the following configuration to a **metro.config.js** file to make sure that the Firebase JS SDK is bundled correctly.
Expo CLI uses [Metro](https://metrobundler.dev/) to bundle your JavaScript code and assets, and add [support for more file extensions](/guides/customizing-metro/#adding-more-file-extensions-to--assetexts).
Start by generating the template file **metro.config.js** in your project's root directory using the following command:
```sh
$ npx expo customize metro.config.js
```
Then, update the file with the following configuration:
```js metro.config.js
const { getDefaultConfig } = require('@expo/metro-config');
const config = getDefaultConfig(__dirname);
config.resolver.sourceExts.push('cjs');
config.resolver.unstable_enablePackageExports = false;
module.exports = config;
```
### Next steps
## Using React Native Firebase
[React Native Firebase](https://rnfirebase.io/) provides access to native code by wrapping the native SDKs for Android and iOS into a JavaScript API.
Each Firebase service is available as a module that can be added as a dependency to your project. For example, the `auth` module provides access to the Firebase Authentication service.
### When to use React Native Firebase
You can consider using React Native Firebase when:
- Your app requires access to Firebase services not supported by the Firebase JS SDK, such as [Dynamic Links](https://rnfirebase.io/dynamic-links/usage), [Crashlytics](https://rnfirebase.io/crashlytics/usage), and so on.
  For more information on the additional capabilities offered by the native SDK's, see [React Native Firebase documentation](https://rnfirebase.io/faqs-and-tips#why-react-native-firebase-over-firebase-js-sdk).
- You want to use native SDKs in your app.
- You have a bare React Native app with React Native Firebase already configured but are migrating to use Expo SDK.
- You want to use [Firebase Analytics](https://rnfirebase.io/analytics/usage) in your app.
Note: Migrating from Expo Firebase packages?
---
If your project has been previously using `expo-firebase-analytics` and `expo-firebase-recaptcha` packages, you can migrate to the React Native Firebase library. For more information, see [Firebase migration guide](https://expo.fyi/firebase-migration-guide).
---
#### Caveats
React Native Firebase requires [custom native code and cannot be used with Expo Go](/workflow/customizing/).
### Install and initialize React Native Firebase
Step 1: 
#### Install expo-dev-client
Since React Native Firebase requires custom native code, you need to install the `expo-dev-client` library in your project.
It allows configuring any native code required by React Native Firebase using [Config plugins](/config-plugins/introduction/) without writing native code yourself.
To install [`expo-dev-client`](/development/getting-started/#installing--expo-dev-client--in-your-project), run the following command in your project:
```sh
$ npx expo install expo-dev-client
```
Step 2: 
#### Install React Native Firebase
To use React Native Firebase, it is necessary to install the `@react-native-firebase/app` module. This module provides the core functionality for all other modules.
It also adds custom native code in your project using a config plugin. You can install it using the following command:
```sh
$ npx expo install @react-native-firebase/app
```
**At this point, you must follow the instructions from [React Native Firebase documentation](https://rnfirebase.io/#managed-workflow)** as it covers all the steps required to configure your project with the library.
Once you have configured the React Native Firebase library in your project, come back to this guide to learn how to run your project in the next step.
Step 3: 
#### Run the project
If you are using **[EAS Build](/build/introduction/), you can create and install a development build** on your devices. You do not need to run the project locally before creating a development build.
For more information on creating a development build, see the section on [installing a development build](/develop/development-builds/create-a-build/).
Note: Run project locally?
---
If you want to run the project locally, you need both Android Studio and Xcode installed and configured on your machine. See [Local app development](/guides/local-app-development/) guide for more information.
If a particular React Native Firebase module requires custom native configuration steps, you must add it as a `plugin` to [app config](/workflow/configuration/) file. Then, to run the project locally, run the `npx expo prebuild --clean` command to apply the native changes before the `npx expo run` commands.
---
<a id="next-steps"></a>
### 下一步
¥Next steps
配置 React Native Firebase 库后，你可以在 Expo 项目中使用它提供的任何模块。
¥After configuring React Native Firebase library, you can use any module it provides in your Expo project.


## 使用 Google 身份验证

有关使用 @react-native-google-signin/google-signin 库将 Google 身份验证集成到 Expo 项目中的指南。

[`@react-native-google-signin/google-signin`](https://github.com/react-native-google-signin/google-signin) 库提供了一种在 Expo 应用中集成 Google 身份验证的方法。它还提供原生登录按钮，并支持对用户进行身份验证以及获取用户使用 Google API 的授权。你可以通过在 [应用配置](/versions/latest/config/app/) 中添加 [配置插件](/config-plugins/introduction/) 来在项目中使用该库。
¥The [`@react-native-google-signin/google-signin`](https://github.com/react-native-google-signin/google-signin) library provides a way integrate Google authentication in your Expo app. It also provides native sign-in buttons and supports authenticating the user as well as obtaining their authorization to use Google APIs. You can use the library in your project by adding the [config plugin](/config-plugins/introduction/) in the [app config](/versions/latest/config/app/).
本指南提供了有关如何为你的项目配置库的信息。
¥This guide provides information on how to configure the library for your project.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
`@react-native-google-signin/google-signin` 库无法在 Expo Go 应用中使用，因为它需要自定义原生代码。了解有关 [将自定义原生代码添加到你的应用](/workflow/customizing/) 的更多信息。
¥The `@react-native-google-signin/google-signin` library can't be used in the Expo Go app because it requires custom native code. Learn more about [adding custom native code to your app](/workflow/customizing/).
<a id="installation"></a>
## 安装
¥Installation
有关如何安装和配置库的说明，请参阅 `@react-native-google-signin/google-signin` 文档：
¥See `@react-native-google-signin/google-signin` documentation for instructions on how to install and configure the library:
<a id="configure-google-project-for-android-and-ios"></a>
## 为 Android 和 iOS 配置 Google 项目
¥Configure Google project for Android and iOS
以下是有关如何为 Android 和 iOS 配置 Google 项目的说明。
¥Below are instructions on how to configure your Google project for Android and iOS.
<a id="upload-app-to-google-play-store"></a>
### 将应用上传到 Google Play 商店
¥Upload app to Google Play Store
如果你的应用打算在生产环境中运行，我们建议将应用上传到 Google Play 商店。即使你的项目仍在开发中，你也可以将你的应用提交到商店进行测试。这允许你在应用通过 EAS 签名进行测试时以及通过 [Google Play 应用签名](https://support.google.com/googleplay/android-developer/answer/9842756?hl=en) 签名进行商店部署时测试 Google 登录。要了解有关应用提交流程的更多信息，请按指定顺序参阅以下指南：
¥We recommend uploading the app to the Google Play Store if your app intends to run in production. You can submit your app to the stores for testing even if your project is still in development. This allows you to test Google Sign In when your app is signed by EAS for testing, and when it is signed by [Google Play App Signing](https://support.google.com/googleplay/android-developer/answer/9842756?hl=en) for store deployment. To learn more about the app submission process, see the guides below in the order they are specified:
<a id="configure-your-firebase-or-google-cloud-console-project"></a>
### 配置你的 Firebase 或 Google Cloud Console 项目
¥Configure your Firebase or Google Cloud Console project
> 有关更深入的配置指南，请参阅 [库的文档](https://react-native-google-signin.github.io/docs/setting-up/get-config-file)。
>
> ¥Refer to the [library's documentation](https://react-native-google-signin.github.io/docs/setting-up/get-config-file) for a more in-depth configuration guide.
对于 Android，上传应用后，你需要在 Firebase 或 Google Cloud Console 中配置项目时提供 SHA-1 证书指纹值。你可以提供两种类型的值：
¥For Android, once you have uploaded your app, you need to provide the SHA-1 certificate fingerprint values when asked while configuring the project in Firebase or Google Cloud Console. There are two types of values that you can provide:
* 你构建的 .apk 的指纹（在你的计算机上或使用 EAS Build）。你可以在 Google Play Console 的“发布”>“设置”>“应用完整性”>“上传密钥证书”下找到 SHA-1 证书指纹。
  ¥Fingerprint of the **.apk** you built (on your machine or using EAS Build). You can find the SHA-1 certificate fingerprint in the Google Play Console under **Release** > **Setup** > **App Integrity** > **Upload key certificate**.
* 从 Play 商店下载的生产应用的指纹。你可以在 Google Play 控制台的“发布”>“设置”>“应用完整性”>“应用签名密钥证书”下找到 SHA-1 证书指纹。
  ¥Fingerprint(s) of a **production app** downloaded from the play store. You can find the SHA-1 certificate fingerprint(s) in the Google Play Console under **Release** > **Setup** > **App Integrity** > **App signing key certificate**.
<a id="with-firebase"></a>
### 使用 Firebase
¥With Firebase
有关如何使用 Firebase 配置你的 Android 和 iOS 项目的更多说明：
¥For more instructions on how to configure your project for Android and iOS with Firebase:
<a id="upload-google-servicesjson-and-googleservice-infoplist-to-eas"></a>
#### 将 google-services.json 和 GoogleService-Info.plist 上传到 EAS
¥Upload google-services.json and GoogleService-Info.plist to EAS
如果你在 Android 和 iOS 系统中使用 Firebase 方法（如上文所述），则需要确保 google-services.json 和 GoogleService-Info.plist 在 EAS 中可用，以便构建应用。你可以将它们签入到你的代码库中，因为这些文件不应包含敏感值；或者，你可以将这些文件视为密钥信息，将其添加到 .gitignore 文件，然后使用以下指南使其在 EAS 中可用。
¥If you use the Firebase method for Android and iOS (as shared in sections above), you'll need to make sure **google-services.json** and **GoogleService-Info.plist** are available in EAS for building the app. You can check them into your repository because the files should not contain sensitive values, or you can treat the files as secrets, add them to **.gitignore** and use the guide below to make them available in EAS.
<a id="with-google-cloud-console"></a>
### 使用 Google Cloud Console
¥With Google Cloud Console
这是当你不使用 [Firebase](#with-firebase) 时配置 Google 项目的另一种方法。
¥This is an alternate method to configure a Google project when you are not using [Firebase](#with-firebase).
有关如何使用 Google Cloud Console 配置你的 Google Android 和 iOS 项目的更多说明：
¥For more instructions on how to configure your Google project Android and iOS with Google Cloud Console:


## 使用 ESLint 和 Prettier

有关配置 ESLint 和 Prettier 以格式化 Expo 应用的指南。

[ESLint](https://eslint.nodejs.cn/) 是一个 JavaScript linter，可以帮助你查找并修复代码中的错误。它是一个很棒的工具，可以帮助你编写更好的代码并在错误投入生产之前发现错误。你可以结合使用 [Prettier](https://prettier.nodejs.cn/docs/en/)，这是一种代码格式化程序，可确保所有代码文件遵循一致的样式。
¥[ESLint](https://eslint.nodejs.cn/) is a JavaScript linter that helps you find and fix errors in your code. It's a great tool to help you write better code and catch mistakes before they make it to production. In conjunction, you can use [Prettier](https://prettier.nodejs.cn/docs/en/), a code formatter that ensures all the code files follow a consistent styling.
本指南提供设置和配置 ESLint 和 Prettier 的步骤。
¥This guide provides steps to set up and configure ESLint and Prettier.
<a id="eslint"></a>
## ESLint
<a id="setup"></a>
### 设置
¥Setup
>  **info** 从 SDK 53 开始，默认的 ESLint 配置文件使用 [扁平化配置](https://eslint.nodejs.cn/blog/2022/08/new-config-system-part-2/) 格式。它也支持旧版配置。对于 SDK 52 及以下版本，默认的 ESLint 配置文件使用旧版配置，不支持扁平化配置。
>
> ¥**From SDK 53 onwards**, the default ESLint config file uses the [Flat config](https://eslint.nodejs.cn/blog/2022/08/new-config-system-part-2/) format. It also supports legacy config. **For SDK 52 and below**, the default ESLint config file uses legacy config and does not support Flat config.
要在你的 Expo 项目中设置 ESLint，你可以使用 Expo CLI 安装必要的依赖。运行此命令还会在项目根目录创建一个 eslint.config.js 文件，该文件扩展了 [`eslint-config-expo`](https://github.com/expo/expo/tree/main/packages/eslint-config-expo) 的配置。
¥To set up ESLint in your Expo project, you can use the Expo CLI to install the necessary dependencies. Running this command also creates a **eslint.config.js** file at the root of your project which extends configuration from [`eslint-config-expo`](https://github.com/expo/expo/tree/main/packages/eslint-config-expo).
```sh
$ npx expo lint
```
<a id="usage"></a>
### 用法
¥Usage
>  **info** 受到推崇的：如果你使用的是 VS Code，请安装 [ESLint 扩展](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) 以便在键入时检查代码。
>
> ¥**Recommended:** If you're using VS Code, install the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) to lint your code as you type.
你可以使用 `npx expo lint` 脚本从命令行手动检查代码：
¥You can lint your code manually from the command line with the `npx expo lint` script:
```sh
run the command again to lint your code.
$ npx expo lint
```
运行上述命令将从 package.json 中运行 `lint` 脚本。
¥Running the above command will run the `lint` script from **package.json**.
```sh
/app/components/HelloWave.tsx
  22:6 warning React Hook useEffect has a missing dependency: "rotateAnimation".
       Either include it or remove the dependency array react-hooks/exhaustive-deps
✖ 1 problem (0 errors
1 warning)
```
<a id="environment-configuration"></a>
### 环境配置
¥Environment configuration
ESLint 通常针对单一环境进行配置。但是，源代码是用 JavaScript 编写的，并且运行在多个不同环境中的 Expo 应用中。例如，app.config.js、metro.config.js、babel.config.js 和 app/+html.tsx 文件都在 Node.js 环境中运行。这意味着他们可以访问全局 `__dirname` 变量，并可以使用 Node.js 模块，例如 `path`。标准的 Expo 项目文件（例如 app/index.js）可以在 Hermes、Node.js 或 Web 浏览器中运行。
¥ESLint is generally configured for a single environment. However, the source code is written in JavaScript in an Expo app that runs in multiple different environments. For example, the **app.config.js**, **metro.config.js**, **babel.config.js**, and **app/+html.tsx** files are run in a Node.js environment. It means they have access to the global `__dirname` variable and can use Node.js modules such as `path`. Standard Expo project files like **app/index.js** can be run in Hermes, Node.js, or the web browser.
你可以在文件顶部添加 `eslint-env` 注释指令，以告知 ESLint 该文件在哪个环境中运行。例如，要告诉 ESLint 某个文件在 Node.js 中运行，请在文件顶部添加以下注释：
¥You can add the `eslint-env` comment directive to the top of a file to tell ESLint which environment the file is running in. For example, to tell ESLint that a file is run in Node.js, add the following comment to the top of the file:
```js metro.config.js
/* eslint-env node */
const { getDefaultConfig } = require('expo/metro-config');
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(
);
module.exports = config;
```
<a id="prettier"></a>
## Prettier
<a id="installation"></a>
### 安装
¥Installation
要在你的项目中安装 Prettier：
¥To install Prettier in your project:
For macOS/Linux: 
```sh
$ npx expo install prettier eslint-config-prettier eslint-plugin-prettier --dev
```
For Windows: 
```sh
$ npx expo install prettier eslint-config-prettier eslint-plugin-prettier "--" --dev
```
<a id="setup-1"></a>
### 设置
¥Setup
For Flat config: 
要将 Prettier 与 ESLint 集成，请更新你的 eslint.config.js：
¥To integrate Prettier with ESLint, update your **eslint.config.js**:
```js eslint.config.js
const { defineConfig } = require('eslint/config');
const expoConfig = require('eslint-config-expo/flat');
const eslintPluginPrettierRecommended = require('eslint-plugin-prettier/recommended');
module.exports = defineConfig([
  expoConfig,
  eslintPluginPrettierRecommended,
  {
    ignores: ['dist/*'],
  },
]);
```
For Legacy config: 
要将 Prettier 与 ESlint 集成，请更新你的 .eslintrc.js：
¥To integrate Prettier with ESlint, update your **.eslintrc.js**:
```js .eslintrc.js
module.exports = {
  extends: ['expo', 'prettier'],
  ignorePatterns: ['/dist/*'],
  plugins: ['prettier'],
  rules: {
    'prettier/prettier': 'error',
  },
};
```
> 注意：在上述配置中，如果你希望这些格式问题作为警告而不是错误，则可以使用 `"prettier/prettier": "warn"`。
>
> ¥**Note:** In the above configuration, you can use `"prettier/prettier": "warn"` if you prefer these formatting issues as warnings instead of errors.
现在，当你运行 `npx expo lint` 时，任何与 Prettier 格式不一致的内容都将被捕获为错误。
¥Now, when you run `npx expo lint`, anything that is not aligned with Prettier formatting will be caught as an error.
要自定义 Prettier 设置，请在项目根目录下创建一个 .prettierrc 文件并添加你的配置。
¥To customize Prettier settings, create a **.prettierrc** file at the root of your project and add your configuration.
<a id="troubleshooting"></a>
## 故障排除
¥Troubleshooting
<a id="eslint-is-not-updating-in-vs-code"></a>
### ESLint 在 VS Code 中未更新
¥ESLint is not updating in VS Code
如果你使用的是 VS Code，请安装 [ESLint 扩展](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) 以便在键入时检查代码。你可以尝试从 [命令面板](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) 运行命令 `ESLint: Restart ESLint Server` 来重新启动 ESLint 服务器。
¥If you're using VS Code, install the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) to lint your code as you type. You can try restarting the ESLint server by running the command `ESLint: Restart ESLint Server` from the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette).
<a id="eslint-is-slow"></a>
### ESLint 运行缓慢
¥ESLint is slow
ESLint 在大型项目上运行速度可能较慢。加快此过程的最简单方法是减少 lint 文件数量。将 .eslintignore 文件添加到项目根目录以忽略某些文件和目录，例如：
¥ESLint can be slow to run on large projects. The easiest way to speed up the process is to lint fewer files. Add a **.eslintignore** file to your project root to ignore certain files and directories such as:
```sh .eslintignore
# @info Ignore the root <b>.expo</b> directory. #
/.expo
# @end #
node_modules
```
<a id="migration-to-flat-config"></a>
## 迁移到 Flat 配置
¥Migration to Flat config
>  **info** 注意：Expo SDK 53 及更高版本支持扁平配置。
>
> ¥**Note:** Flat config is supported in Expo SDK 53 and above.
升级 ESLint 和 `eslint-config-expo`：
¥Upgrade ESLint and `eslint-config-expo`:
For macOS/Linux: 
```sh
$ npx expo install eslint eslint-config-expo  --dev
```
For Windows: 
```sh
$ npx expo install eslint eslint-config-expo "--" --dev
```
如果你根本没有自定义 ESLint 配置，请删除 .eslintrc.js 并使用以下命令生成新配置：
¥If you haven't customized your ESLint config at all, delete your **.eslintrc.js** and generate the new config with:
```sh
$ npx expo lint
```
或者，你可以根据 [ESLint 迁移指南](https://eslint.nodejs.cn/docs/latest/use/configure/migration-guide) 迁移你的配置。`npx expo lint` 同时支持旧版配置和扁平化配置，因此 CLI 将自动选择新配置。
¥Alternatively, migrate your config based on the [ESLint's migration guide](https://eslint.nodejs.cn/docs/latest/use/configure/migration-guide). `npx expo lint` supports both legacy and flat config, so the new config will automatically be picked up by the CLI.


## 将 Next.js 与 Expo for Web 结合使用

将 Next.js 与 Expo 网页版集成的指南。

>  **warning** 使用 Next.js 并不是 Expo 通用应用开发工作流程的官方部分。
>
> ¥Using Next.js is not an official part of Expo's universal app development workflow.
[Next.js](https://next.nodejs.cn/) 是一个 React 框架，提供简单的基于页面的路由以及服务器端渲染。要将 Next.js 与 Expo SDK 结合使用，我们建议使用 [`@expo/next-adapter`](https://github.com/expo/expo-cli/tree/main/packages/next-adapter) 库来处理配置。
¥[Next.js](https://next.nodejs.cn/) is a React framework that provides simple page-based routing as well as server-side rendering. To use Next.js with the Expo SDK, we recommend using [`@expo/next-adapter`](https://github.com/expo/expo-cli/tree/main/packages/next-adapter) library to handle the configuration.
将 Expo 与 Next.js 结合使用意味着你可以在移动和 Web 应用中共享一些现有组件和 API。Next.js 有自己的 CLI，你在为 Web 平台进行开发时需要使用它，因此你需要使用 Next.js CLI 而不是使用 `npx expo start` 来启动你的 Web 项目。
¥Using Expo with Next.js means you can share some of your existing components and APIs across your mobile and web app. Next.js has its own CLI that you'll need to use when developing for the web platform, so **you'll need to start your web projects with the Next.js CLI and not with `npx expo start`**.
> Next.js 只能与 Expo for Web 一起使用，因为不支持原生应用的服务器端渲染 (SSR)。
>
> ¥Next.js can only be used with Expo for web as there is no support for Server-Side Rendering (SSR) for native apps.
<a id="automatic-setup"></a>
## 自动设置
¥Automatic setup
要快速开始，请使用 [with-nextjs](https://github.com/expo/examples/tree/master/with-nextjs) 模板创建一个新项目：
¥To quickly get started, create a new project using [with-nextjs](https://github.com/expo/examples/tree/master/with-nextjs) template:
```sh
$ npx create-expo-app -e with-nextjs
```
* 本国的：`npx expo start` - 启动 Expo 项目
  ¥**Native**: `npx expo start` — start the Expo project
* 网址：`npx next dev` — 启动 Next.js 项目
  ¥**Web**: `npx next dev` — start the Next.js project
<a id="manual-setup"></a>
## 手动设置
¥Manual setup
<a id="install-dependencies"></a>
### 安装依赖
¥Install dependencies
确保你的项目中安装了 `expo`、`next`、`@expo/next-adapter`：
¥Ensure you have `expo`, `next`, `@expo/next-adapter` installed in your project:
```sh
$ yarn add expo next @expo/next-adapter
```
<a id="transpilation"></a>
### 转译
¥Transpilation
配置 Next.js 来转换语言特性：
¥Configure Next.js to transform language features:
Note: Next.js with swc. (Recommended)
---
Using Next.js with SWC is recommended. You can configure the [**babel.config.js**](/versions/latest/config/babel/) to only account for native:
```js babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
  };
};
```
You will also have to [force Next.js to use SWC](https://next.nodejs.cn/docs/messages/swc-disabled) by adding the following to your **next.config.js**:
```js next.config.js
module.exports = {
  experimental: {
    forceSwcTransforms: true,
  },
};
```
---
Note: Next.js with Babel. (Not recommended)
---
Adjust your **babel.config.js** to conditionally add `next/babel` when bundling with webpack for web:
```js babel.config.js
module.exports = function (api) {
  // Detect web usage (this may change in the future if Next.js changes the loader)
  const isWeb = api.caller(
    caller =>
      caller && (caller.name === 'babel-loader' || caller.name === 'next-babel-turbo-loader')
  );
  return {
    presets: [
      // Only use next in the browser, it'll break your native project
      isWeb && require('next/babel'),
      'babel-preset-expo',
    ].filter(Boolean),
  };
};
```
---
### Next.js configuration
Add the following to your **next.config.js**:
```js next.config.js
const { withExpo } = require('@expo/next-adapter');
module.exports = withExpo({
  // transpilePackages is a Next.js +13.1 feature.
  // older versions can use next-transpile-modules
  transpilePackages: [
    'react-native',
    'react-native-web',
    'expo',
    // Add more React Native/Expo packages here...
  ],
});
```
The fully qualified Next.js config may look like:
```js next.config.js
const { withExpo } = require('@expo/next-adapter');
/** @type {import('next').NextConfig} */
const nextConfig = withExpo({
  reactStrictMode: true,
  swcMinify: true,
  transpilePackages: [
    'react-native',
    'react-native-web',
    'expo',
    // Add more React Native/Expo packages here...
  ],
  experimental: {
    forceSwcTransforms: true,
  },
});
module.exports = nextConfig;
```
### React Native Web styling
The package `react-native-web` builds on the assumption of reset CSS styles. Here's how you reset styles in Next.js using the **pages** directory.
```jsx pages/_document.js
import { Children } from 'react';
import Document, { Html, Head, Main, NextScript } from 'next/document';
import { AppRegistry } from 'react-native';
// Follows the setup for react-native-web:
// https://necolas.github.io/react-native-web/docs/setup/#root-element
// Plus additional React Native scroll and text parity styles for various
// browsers.
// Force Next-generated DOM elements to fill their parent's height
const style = `
html, body, #__next {
  -webkit-overflow-scrolling: touch;
}
#__next {
  display: flex;
  flex-direction: column;
  height: 100%;
}
html {
  scroll-behavior: smooth;
  -webkit-text-size-adjust: 100%;
}
body {
  /* Allows you to scroll below the viewport; default value is visible */
  overflow-y: auto;
  overscroll-behavior-y: none;
  text-rendering: optimizeLegibility;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  -ms-overflow-style: scrollbar;
}
`;
export default class MyDocument extends Document {
  static async getInitialProps({ renderPage }) {
    AppRegistry.registerComponent('main', () => Main);
    const { getStyleElement } = AppRegistry.getApplication('main');
    const page = await renderPage();
    const styles = [
      <style key="react-native-style" dangerouslySetInnerHTML={{ __html: style }} />,
      getStyleElement(),
    ];
    return { ...page, styles: Children.toArray(styles) };
  }
  render() {
    return (
      <Html style={{ height: '100%' }}>
        <Head />
        <body style={{ height: '100%', overflow: 'hidden' }}>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}
```
```jsx pages/_app.js
import Head from 'next/head';
export default function App({ Component, pageProps }) {
  return (
    <>
      <Head>
        <meta name="viewport" content="width=device-width, initial-scale=1" />
      </Head>
      <Component {...pageProps} />
    </>
  );
}
```
## Transpiling modules
By default, modules in the React Native ecosystem are not transpiled to run in web browsers. React Native relies on advanced caching in Metro to reload quickly. Next.js uses webpack, which does not have the same level of caching, so no node modules are transpiled by default. You will have to manually mark every module you want to transpile with the `transpilePackages` option in **next.config.js**:
```js next.config.js
const { withExpo } = require('@expo/next-adapter');
module.exports = withExpo({
  experimental: {
    transpilePackages: [
      // NOTE: Even though `react-native` is never used in Next.js,
      // you need to list `react-native` because `react-native-web`
      // is aliased to `react-native`.
      'react-native',
      'react-native-web',
      'expo',
      // Add more React Native/Expo packages here...
    ],
  },
});
```
## Deploy to Vercel
This is Vercel's preferred method for deploying Next.js projects to production.
Step 1: 
Add a `build` script to your **package.json**:
```json package.json
{
  "scripts": {
    "build": "next build"
  }
}
```
Step 2: 
Install the Vercel CLI:
```sh
$ npm i -g vercel
```
Step 3: 
Deploy to Vercel:
```sh
$ vercel
```
<a id="limitations-or-differences-compared-to-the-default-expo-for-web"></a>
## 与默认 Web 版 Expo 相比的限制或差异
¥Limitations or differences compared to the default Expo for Web
在 Web 中使用 Next.js 意味着你将与 Next.js webpack 配置打包在一起。这将导致你开发应用与网站的方式存在一些核心差异。
¥Using Next.js for the web means you will be bundling with the Next.js webpack config. This will lead to some core differences in how you develop your app vs your website.
* Expo Next.js 适配器不支持实验应用目录。
  ¥Expo Next.js adapter does not support the experimental **app** directory.
* 对于原生上基于文件的路由，我们建议使用 [Expo 路由](https://github.com/expo/router)。
  ¥For file-based routing on native, we recommend using [Expo Router](https://github.com/expo/router).
<a id="contributing"></a>
## 贡献
¥Contributing
如果你想帮助改善 Expo 中的 Next.js 支持，请随时打开 PR 或提交问题：
¥If you would like to help make Next.js support in Expo better, feel free to open a PR or submit an issue:
* [@expo/next-adapter](https://github.com/expo/expo-cli/tree/main/packages/next-adapter)
<a id="troubleshooting"></a>
## 故障排除
¥Troubleshooting
<a id="cannot-use-import-statement-outside-a-module"></a>
### 不能在模块外部使用 import 语句
¥Cannot use import statement outside a module
找出哪个模块有 import 语句并将其添加到 next.config.js 中的 `transpilePackages` 选项中：
¥Figure out which module has the import statement and add it to the `transpilePackages` option in **next.config.js**:
```js next.config.js
const { withExpo } = require('@expo/next-adapter');
module.exports = withExpo({
  experimental: {
    transpilePackages: [
      'react-native',
      'react-native-web',
      'expo',
      // Add the failing package here, and restart the server...
    ],
  },
});
```


## 使用 LogRocket

有关安装和配置 LogRocket 以进行会话重放和错误监控的指南。

[LogRocket](https://logrocket.com) 记录用户会话并在用户使用你的应用时识别错误。你可以按更新 ID 过滤会话，还可以在 EAS 仪表板上连接到你的 LogRocket 账户，以快速访问应用的会话数据。
¥[LogRocket](https://logrocket.com) records user sessions and identifies bugs as your users use your app. You can filter sessions by update IDs and also connect to your LogRocket account on the EAS dashboard to get quick access to your app's session data.
<a id="install-and-configure-logrocket"></a>
## 安装和配置 LogRocket
¥Install and configure LogRocket
你可以使用以下命令安装 LogRocket SDK：
¥You can install the LogRocket SDK with the following command:
```sh
$ npx expo install @logrocket/react-native expo-build-properties
```
然后，在你的 [应用配置](/workflow/configuration/) 中包含 LogRocket 配置插件：
¥Then, in your [app config](/workflow/configuration/), include the LogRocket config plugin:
```json app.json
{
  "plugins": [
    [
      "expo-build-properties",
      {
        "android": {
          "minSdkVersion": 25
        }
      }
    ],
    "@logrocket/react-native"
  ]
}
```
最后，在你的应用中的顶层文件（如 app/_layout.tsx）中初始化 LogRocket：
¥Finally, initialize LogRocket in your app in a top-level file, like **app/_layout.tsx**:
```tsx app/_layout.tsx
import { useEffect } from 'react';
import * as Updates from 'expo-updates';
import LogRocket from '@logrocket/react-native';
const App = () => {
  useEffect(() => {
    LogRocket.init('<App ID>', {
      updateId: Updates.isEmbeddedLaunch ? null : Updates.updateId,
      expoChannel: Updates.channel,
    });
  }, []);
};
```
在上面的代码中，将 `<App ID>` 替换为你的 [LogRocket 应用 ID](https://app.logrocket.com/r/settings/setup)。
¥In the code above, replace `<App ID>` with your [LogRocket App ID](https://app.logrocket.com/r/settings/setup).
<a id="connecting-logrocket-on-the-eas-dashboard"></a>
## 在 EAS 仪表板上连接 LogRocket
¥Connecting LogRocket on the EAS dashboard
你可以在 Expo 的仪表板上将你的 LogRocket 账户和项目链接到你的 Expo 账户和项目，以便你可以在部署和更新仪表板中查看应用的最后几个会话。
¥You can link your LogRocket account and project to your Expo account and project on Expo's dashboard, so that you can see the last few sessions from your app in the deployments and updates dashboards.
前往你的账户设置 > [**概述**](https://expo.dev/accounts/%5Baccount%5D/settings) > 连接，然后点击“连接”以通过 LogRocket 进行身份验证：
¥Go to your **Account settings** > [**Overview**](https://expo.dev/accounts/%5Baccount%5D/settings) > **Connections** and click **Connect** to authenticate with LogRocket:
然后，前往你的项目，在“项目设置”>“[**常规**](https://expo.dev/accounts/%5Baccount%5D/projects/%5BprojectName%5D/settings)”下，点击“连接”，将你的 LogRocket 项目与 Expo 上的项目关联起来：
¥Then, go to your project, under **Project settings** > [**General**](https://expo.dev/accounts/%5Baccount%5D/projects/%5BprojectName%5D/settings) and click **Connect** to link your LogRocket project with your project on Expo:
之后，你将在 EAS 信息中心的“原生部署”和“更新”信息中心中看到“在 LogRocket 上查看”按钮，以及应用的最近几次会话。
¥Then, you'll start to see **View on LogRocket** buttons in the EAS dashboard in the Native Deployments and Updates dashboards, along with the last few sessions from your app.
<a id="learn-more-about-logrocket"></a>
## 了解有关 LogRocket 的更多信息
¥Learn more about LogRocket
要了解有关如何将 LogRocket 与 Expo 结合使用的更多信息，请查看 [LogRocket 文档](https://docs.logrocket.com/reference/react-native-expo-adding-the-sdk)。
¥To learn more about how to use LogRocket with Expo, check out the [LogRocket documentation](https://docs.logrocket.com/reference/react-native-expo-adding-the-sdk).


## 使用 Sentry

有关安装和配置 Sentry 以进行崩溃报告的指南。

[Sentry](http://getsentry.com/) 是一个崩溃报告平台，可让你实时了解生产部署，并提供重现和修复崩溃的信息。
¥[Sentry](http://getsentry.com/) is a crash reporting platform that provides you with **real-time insight into production deployments with info to reproduce and fix crashes**.
它会通知你用户在使用你的应用时遇到的异常或错误，并在网络仪表板上为你组织它们。自动报告的异常包括堆栈跟踪、设备信息、版本和其他相关上下文。你还可以提供特定于你的应用的其他上下文，例如当前路由和用户 ID。
¥It notifies you of exceptions or errors that your users run into while using your app and organizes them for you on a web dashboard. Reported exceptions include stacktraces, device info, version, and other relevant context automatically. You can also provide additional context that is specific to your application such as the current route and user id.
<a id="what-youll-learn"></a>
## 你将学到什么
¥What you'll learn
本指南涵盖了将 Sentry 与你的 Expo 项目集成的三个主要方面：
¥This guide covers three main aspects of integrating Sentry with your Expo projects:
* React Native 应用中的 [安装和配置 Sentry](#install-and-configure-sentry)
  ¥[Install and configure Sentry](#install-and-configure-sentry) in your React Native app
* 将 Sentry 与 EAS 结合使用：
  ¥Using Sentry with EAS:
  * 用于构建应用的 [EAS 构建](#usage-with-eas-build)
    ¥[EAS Build](#usage-with-eas-build) for building your app
  * [EAS 更新](#usage-with-eas-update) 用于无线更新
    ¥[EAS Update](#usage-with-eas-update) for over-the-air updates
* [设置 Sentry-Expo 集成](#sentry-integration-with-eas-dashboard) 可直接在 EAS 仪表板中查看崩溃报告和会话重放。
  ¥[Setting up the Sentry-Expo integration](#sentry-integration-with-eas-dashboard) to view crash reports and session replays directly in your EAS dashboard
<PlatformsSection title="Platform compatibility" android emulator ios simulator web />
<a id="install-and-configure-sentry"></a>
## 安装和配置 Sentry
¥Install and configure Sentry
Step 1: 
### Sign up for a Sentry account and create a project
Before proceeding with installing Sentry, you'll need to make sure you have created a Sentry account and project:
Step 1.1: 
[Sign up for Sentry](https://sentry.io/signup/) (the free tier supports up to 5,000 events per month), and create a project in your
Dashboard. Take note of your **organization slug**, **project name**, and **DSN** as you'll need
them later:
- **organization slug** is available in your **Organization settings** tab
- **project name** is available in your project's **Settings** > **Projects** tab (find it in the list)
- **DSN** is available in your project's **Settings** > **Projects** > **Project name** > Under **SDK Setup** section > **Client Keys (DSN)** tab.
Step 1.2: 
Go to the [Developer Settings > Auth Tokens](https://sentry.io/settings/auth-tokens/) page and create a new [Organization Auth Token](https://docs.sentry.io/account/auth-tokens/#organization-auth-tokens). The token is automatically scoped for Source Map Upload and Release Creation. Save it.
Once you have each of these: **organization slug**, **project name**, **DSN**, and **auth token**, you're all set to proceed.
Step 2: 
### Use the Sentry wizard to set up your project
The easiest way to set up Sentry in your Expo project is to use the Sentry wizard. This tool will automatically configure your project with the right settings.
Run the following command in your project directory:
```sh
$ npx @sentry/wizard@latest -i reactNative
```
The wizard will:
- Install the required dependencies
- Configure your project to use Sentry
- Set up the Metro configuration automatically
- Add the necessary initialization code to your app
Follow the prompts in the wizard to complete the setup process. The wizard will guide you to log in to your Sentry account and fetch all the correct information regarding your project.
Step 3: 
### Verify the configuration
Create a new release build of your app and verify that it uploads source maps correctly. You may want to add a button in your app to test that it is working and sourcemaps are wired up as expected, for example:
```jsx
import { Button } from 'react-native';
// Inside some component
<Button title="Press me" onPress={() => { throw new Error('Hello, again, Sentry!'); }}/>
```
## Usage with EAS Build
Ensure that `SENTRY_AUTH_TOKEN` is set in your build environment, and Sentry will automatically upload source maps for you. If you use environment variables rather than properties in your app config, ensure that those are set as well.
Using the above instructions, no additional work is needed to integrate Sentry into your project when using EAS Build.
## Usage with EAS Update
After running `eas update`, upload the source maps to Sentry:
```sh
$ npx sentry-expo-upload-sourcemaps dist
```
That's it! Errors for your updates will now be properly symbolicated in Sentry.
Note: Do you want to publish an update and the sourcemaps in one command?
---
You can chain the commands together with `&&` to publish an update and upload the sourcemaps in one step:
```sh
$ eas update --branch <branch> && npx sentry-expo-upload-sourcemaps dist
```
---
Note: Do you want to append additional update-related metadata to error reports?
---
Configuring Sentry to tag your scope with information about your update allows you to see errors happening on certain updates in the Sentry dashboard.
Add the following snippet in the global scope as early as possible in your application's lifecycle.
```js
import * as Sentry from '@sentry/react-native';
import * as Updates from 'expo-updates';
const manifest = Updates.manifest;
const metadata = 'metadata' in manifest ? manifest.metadata : undefined;
const extra = 'extra' in manifest ? manifest.extra : undefined;
const updateGroup = metadata && 'updateGroup' in metadata ? metadata.updateGroup : undefined;
Sentry.init({
  // dsn, release, dist, etc...
});
const scope = Sentry.getGlobalScope();
scope.setTag('expo-update-id', Updates.updateId);
scope.setTag('expo-is-embedded-update', Updates.isEmbeddedLaunch);
if (typeof updateGroup === 'string') {
  scope.setTag('expo-update-group-id', updateGroup);
  const owner = extra?.expoClient?.owner ?? '[account]';
  const slug = extra?.expoClient?.slug ?? '[project]';
  scope.setTag(
    'expo-update-debug-url',
    `https://expo.dev/accounts/${owner}/projects/${slug}/updates/${updateGroup}`
  );
} else if (Updates.isEmbeddedLaunch) {
  // This will be `true` if the update is the one embedded in the build, and not one downloaded from the updates server.
  scope.setTag('expo-update-debug-url', 'not applicable for embedded updates');
}
```
Once configured, information about the associated update will show up in an error's tag section:
---
## Sentry integration with EAS dashboard
The Sentry integration with Expo allows you to view crash reports and Session Replays for your Expo app deployments directly within your EAS dashboard. This integration provides a direct link to Sentry stack traces with full context, session replays, and debugging capabilities.
### Install
> **info** Sentry owner, manager, or admin permissions are required to install this integration.
1. Log in to you Expo account and open [**Account settings > Overview**](https://expo.dev/accounts/[your-account]/settings).
2. Under **Connections** and click **Connect** next to Sentry.
3. Log in to your Sentry account and accept the integration into your organization. You will be redirected back to **Account settings**.
### Link your project
After connecting your accounts, you need to link your EAS Project to your Sentry Project:
1. Open **Projects > [Your Project] > Configuration > Project settings** in EAS.
2. Click **Link** and select your Sentry Project from the dropdown.
### Usage
To see your Sentry data in EAS dashboard, open **Projects > [Your Project] > Updates > Deployments >
[Deployment]** 用于从发布版本查看 Sentry 数据。
¥[Deployment]** to view Sentry data from a Release.
通过此集成，你可以：
¥With this integration, you can:
* 直接在 EAS 仪表板中查看崩溃报告
  ¥View crash reports directly in your EAS dashboard
* 访问会话回放，查看错误发生前的具体情况
  ¥Access Session Replays to see exactly what happened before an error occurred
* 获取包含完整上下文的详细堆栈跟踪
  ¥Get detailed stack traces with full context
* 在 EAS 和 Sentry 之间无缝导航以进行调试
  ¥Navigate seamlessly between EAS and Sentry for debugging
<a id="learn-more-about-sentry"></a>
## 了解有关 Sentry 的更多信息
¥Learn more about Sentry
Sentry 的作用不仅仅是捕获致命错误，还可以从其 [JavaScript 使用](https://docs.sentry.io/platforms/javascript/) 文档中了解有关如何使用 Sentry 的更多信息。
¥Sentry does more than just catch fatal errors, learn more about how to use Sentry from their [JavaScript usage](https://docs.sentry.io/platforms/javascript/) documentation.


## 使用 BugSnag

有关安装和配置 BugSnag 以进行端到端错误报告和分析的指南。

[BugSnag](https://www.bugsnag.com) 是一种稳定性监控解决方案，可提供丰富的端到端错误报告和分析，以快速、精确地重现和修复错误。BugSnag 支持包含 [50 个平台](https://www.bugsnag.com/platforms) 多个开源库的完整堆栈，包括 [React Native](https://docs.bugsnag.com/platforms/react-native/react-native/)。
¥[BugSnag](https://www.bugsnag.com) is a stability monitoring solution that provides rich, end-to-end error reporting and analytics to reproduce and fix errors with speed and precision. BugSnag supports the full stack with open-source libraries for more than [50 platforms](https://www.bugsnag.com/platforms), including [React Native](https://docs.bugsnag.com/platforms/react-native/react-native/).
借助 BugSnag，开发者和工程组织可以：
¥With BugSnag, developers and engineering organizations can:
* 稳定：通过了解何时构建新功能和修复错误来加快创新速度。使用发布运行状况仪表板、稳定性分数和目标，以及通过电子邮件、Slack、PagerDuty 等提供的内置警报。
  ¥**Stabilize:** Innovate faster by knowing when to build new features versus fix bugs. Use the release health dashboard, stability scores and targets, and built-in alerts via email, Slack, PagerDuty, and more.
* 优先考虑：通过识别对应用稳定性影响最大的错误并确定优先级来改善客户体验。分析按根本原因分组的问题，并按业务影响、客户细分、A/B 测试和实验结果排序。
  ¥**Prioritize:** Improve customer experience by identifying and prioritizing bugs that have the greatest impact on app stability. Analyze issues grouped by root cause and sorted by business impact, customer segmentation, A/B testing and experiment results.
* 使固定：通过减少重现和修复错误的时间来提高生产力。利用强大的诊断数据、完整的堆栈跟踪和自动面包屑。
  ¥**Fix:** Increase productivity by spending less time on reproducing and fixing bugs. Utilize powerful diagnostic data, full stacktraces and automatic breadcrumbs.
<a id="integration"></a>
## 一体化
¥Integration
请参阅下面的集成指南，了解有关将 BugSnag 添加到 Expo 应用以报告 JavaScript 错误的说明。它还包括上传 [EAS 更新](/eas-update/introduction/) 发布的更新的源映射的说明。
¥See the integration guide below for instructions on adding BugSnag to your Expo apps to report JavaScript errors. It also includes instructions for uploading source maps for updates published with [EAS Update](/eas-update/introduction/).
如果你是 BugSnag 新手，你可以选择 [创建一个账户](https://app.bugsnag.com/user/new/) 或 [请求演示](https://www.bugsnag.com/demo-request)。
¥If you're new to BugSnag, you can [create an account](https://app.bugsnag.com/user/new/) or [request a demo](https://www.bugsnag.com/demo-request).


## 使用 Vexo

有关安装和配置 Vexo 以进行实时用户分析的指南。

[维克斯](https://www.vexo.co/) 为你的 Expo 应用提供实时用户分析，帮助你了解用户如何与你的应用交互、识别摩擦点并提高参与度。
¥[Vexo](https://www.vexo.co/) provides real-time user analytics for your Expo application, helping you understand how users interact with your app, identify friction points, and improve engagement.
通过两行集成，Vexo 开始自动收集数据，为你提供可操作的见解，以优化应用的用户体验。如果需要，你还可以创建自定义事件。
¥With a two-line integration, Vexo starts collecting data automatically, giving you actionable insights to optimize your app's user experience. If needed, you can also create custom events.
<a id="features"></a>
## 特性
¥Features
1. **完整仪表板**
   ¥**Complete Dashboard**
   * 活跃用户
     ¥Active Users
   * 会话时间
     ¥Session Time
   * 下载
     ¥Downloads
   * 操作系统分布
     ¥OS Distribution
   * 版本采用
     ¥Version Adoption
   * 地理洞察
     ¥Geographic Insights
   * 热门屏幕
     ¥Popular Screens
2. **会话重播**
   ¥**Session Replays**
   * 观看真实用户会话以了解它们的交互。
     ¥Watch real user sessions to understand their interactions.
3. **热图**
   ¥**Heatmaps**
   * 确定应用中最受关注的区域。
     ¥Identify the most engaged areas of your app.
4. **渠道**
   ¥**Funnels**
   * 分析用户流并优化转化率。
     ¥Analyze user flows and optimize conversion rates.
5. **自定义事件和仪表板个性化**
   ¥**Custom Events and Dashboard Personalization**
   * 通过创建自定义事件来跟踪特定用户操作。
     ¥Track specific user actions by creating custom events.
   * 自定义仪表板以可视化关键指标。
     ¥Customize your dashboard to visualize key metrics.
<a id="getting-started"></a>
## 入门
¥Getting started
1. 创建账户：注册 [Vexo 账户](https://www.vexo.co/)。
   ¥Create an account: Sign up for a [Vexo account](https://www.vexo.co/).
2. 创建新应用：系统将提示你创建一个新的应用。给它一个名字（你可以稍后更改），提交后，你将收到一个 API 密钥。
   ¥Create a new app: You'll be prompted to create a new app. Give it a name (you can change it later), and once you submit it, you'll receive an API key.
3. 安装 Vexo 包：在你的项目中运行以下命令：
   ¥Install the Vexo package: Run the following command in your project:
For npm: 
```sh
$ npm install vexo-analytics
```
For yarn: 
```sh
$ yarn add vexo-analytics
```
4. 初始化 Vexo：将以下代码添加到应用的入口文件（例如，如果使用 Expo Router，则为 index.js、App.js 或 app/_layout.tsx）：
   ¥Initialize Vexo: Add the following code in your app's entry file (for example, **index.js**, **App.js**, or **app/_layout.tsx** if using Expo Router):
```tsx app/_layout.tsx
   import { vexo } from 'vexo-analytics';
   // You may want to wrap this with `if (!__DEV__) { ... }` to only run Vexo in production.
   vexo('YOUR_API_KEY');
   ```
5. 重建并运行你的应用：由于 `vexo-analytics` 包含原生代码，你需要重建应用。
   ¥Rebuild and run your app: Since `vexo-analytics` includes native code, you need to rebuild your application.
6. 验证集成：转到 Vexo 上的应用页面，你应该会看到你的第一个事件！
   ¥Verify integration: Go to your app's page on Vexo and you should see your first event!
<a id="compatibility"></a>
## 兼容性
¥Compatibility
* Expo：Vexo 与 [开发构建](/development/introduction/) 兼容，不需要额外的配置插件。
  ¥Expo: Vexo is compatible with [Development builds](/development/introduction/) and does not require additional configuration plugins.
* Expo Go：不支持，因为 Vexo 需要自定义原生代码。
  ¥Expo Go: Not supported, as Vexo requires custom native code.
<a id="learn-more-about-vexo"></a>
## 了解有关 Vexo 的更多信息
¥Learn more about Vexo
要了解有关将 Vexo 与 Expo 结合使用的更多信息，请查看 [Vexo 文档](https://docs.vexo.co/)。
¥To learn more about using Vexo with Expo, check out the [Vexo documentation](https://docs.vexo.co/).


## 构建电视 Expo 应用

为 Android TV 或 Apple TV 目标构建 Expo 应用的指南。

>  **警告** 并非所有 Expo 功能和 SDK 库都可在 TV 上使用。有关更多详细信息，请查看 [查看支持哪些库](#see-which-libraries-are-supported)。
>
> ¥Not all Expo features and SDK libraries are available on TV. For more details, check the [See which libraries are supported](#see-which-libraries-are-supported).
Android TV 和 Apple TV 通过 [React Native 电视项目](https://github.com/react-native-tvos/react-native-tvos) 支持 React Native。这项技术超越了电视，提供了全面的核心存储库分支，支持手机和电视目标，包括 Hermes 和 Fabric。
¥React Native is supported on Android TV and Apple TV through the [React Native TV project](https://github.com/react-native-tvos/react-native-tvos). This technology extends beyond TV, offering a comprehensive core repo fork with support for phone and TV targets, including Hermes and Fabric.
使用 React Native TV 库作为 Expo 项目中的 `react-native` 依赖，它能够同时针对移动（Android、iOS）和电视（Android TV、Apple TV）设备。
¥Using the React Native TV library as the `react-native` dependency in an Expo project, it becomes capable of targeting both mobile (Android, iOS) and TV (Android TV, Apple TV) devices.
<a id="prerequisites"></a>
## 先决条件
¥Prerequisites
对原生 Android 和 iOS 文件的必要更改很少，如果你使用 [prebuild](/workflow/prebuild/)，则可以使用 [配置插件](https://github.com/react-native-tvos/config-tv/tree/main/packages/config-tv) 实现自动化。以下是配置插件所做的更改列表，你也可以手动应用这些更改：
¥The necessary changes to the native Android and iOS files are minimal and can be automated with a [config plugin](https://github.com/react-native-tvos/config-tv/tree/main/packages/config-tv) if you use [prebuild](/workflow/prebuild/). Below is a list of changes made by the config plugins, which you can alternatively apply manually:
<a id="android"></a>
### 安卓
¥Android
* AndroidManifest.xml 修改为：
  ¥**AndroidManifest.xml** is modified:
  * 删除默认手机纵向方向
    ¥The default phone portrait orientation is removed
  * 添加了电视应用所需的意图
    ¥The required intent for TV apps is added
* 修改 MainApplication.kt 以删除不支持的 Flipper 调用
  ¥**MainApplication.kt** is modified to remove unsupported Flipper invocations
<a id="ios"></a>
### iOS 系统
¥iOS
* ios/Podfile 已修改为目标 tvOS 而不是 iOS
  ¥**ios/Podfile** is modified to target tvOS instead of iOS
* Xcode 项目已修改为目标 tvOS 而不是 iOS
  ¥The Xcode project is modified to target tvOS instead of iOS
* 启动画面 (SplashScreen.storyboard) 已修改以在 tvOS 上运行
  ¥The splash screen (**SplashScreen.storyboard**) is modified to work on tvOS
<a id="system-requirements-for-tv-development"></a>
## TV 开发的系统要求
¥System requirements for TV development
<a id="android-tv"></a>
### Android TV
* macOS 或 Linux 上的 [Node.js (LTS)](https://nodejs.cn/)。
  ¥[Node.js (LTS)](https://nodejs.cn/) on macOS or Linux.
* Android Studio（Iguana 或更高版本）。
  ¥Android Studio (Iguana or later).
* 在 Android Studio SDK 管理器中，选择你正在使用的 Android SDK（API 版本 31 或更高版本）的下拉列表，并确保选择安装 Android TV 系统映像。（对于 Apple 芯片，请选择 ARM 64 映像。否则，请选择 Intel x86_64 映像）。
  ¥In the Android Studio SDK manager, select the dropdown for the Android SDK you are using (API version 31 or later), and make sure an Android TV system image is selected for installation. (For Apple silicon, choose the ARM 64 image. Otherwise, choose the Intel x86_64 image).
* 安装 Android TV 系统映像后，使用该映像创建 Android TV 模拟器（该过程与创建 Android 手机模拟器相同）。
  ¥After installing the Android TV system image, create an Android TV emulator using that image (the process is the same as creating an Android phone emulator).
<a id="apple-tv"></a>
### Apple TV
* macOS 上的 [Node.js (LTS)](https://nodejs.cn/)。
  ¥[Node.js (LTS)](https://nodejs.cn/) on macOS.
* Xcode 15 或更高版本。
  ¥Xcode 15 or later.
* tvOS SDK 17 或更高版本。（这不会随 Xcode 自动安装。你可以稍后使用 `xcodebuild -downloadAllPlatforms` 安装它）。
  ¥tvOS SDK 17 or later. (This is not installed automatically with Xcode. You can install it later with `xcodebuild -downloadAllPlatforms`).
<a id="quick-start"></a>
## 快速开始
¥Quick start
Expo 示例存储库中的 [电视示例](https://github.com/expo/examples/tree/master/with-tv) 描述了生成新项目的最快方法：
¥The fastest way to generate a new project is described in the [TV example](https://github.com/expo/examples/tree/master/with-tv) within the Expo examples repository:
```sh
$ npx create-expo-app MyTVProject -e with-tv
```
对于 SDK 51 及更高版本，你可以从 [电视路由示例](https://github.com/expo/examples/tree/master/with-router-tv) 开始：
¥For SDK 51 and later, you can start with the [TV Router example](https://github.com/expo/examples/tree/master/with-router-tv):
```sh
$ npx create-expo-app MyTVProject -e with-router-tv
```
这将创建一个新项目，该项目使用 [Expo 路由](/router/introduction/) 进行基于文件的导航，以 [create-expo-app 默认模板](/get-started/create-a-project/) 为模型。
¥This creates a new project that uses [Expo Router](/router/introduction/) for file-based navigation, modeled after the [**create-expo-app** default template](/get-started/create-a-project/).
Note: See which libraries are supported
---
At this time, TV applications work with the following libraries and APIs listed below:
- [AppleAuthentication](/versions/latest/sdk/apple-authentication/)
- [Application](/versions/latest/sdk/application/)
- [Audio](/versions/latest/sdk/audio)
- [Asset](/versions/latest/sdk/asset/)
- [AsyncStorage](/versions/latest/sdk/async-storage/)
- [AV](/versions/latest/sdk/av/)
- [BlurView](/versions/latest/sdk/blur-view/)
- [BuildProperties](/versions/latest/sdk/build-properties/)
- [Constants](/versions/latest/sdk/constants/)
- [Crypto](/versions/latest/sdk/crypto/)
- [Device](/versions/latest/sdk/device/)
- [FileSystem](/versions/latest/sdk/filesystem/)
- [FlashList](/versions/latest/sdk/flash-list/)
- [Font](/versions/latest/sdk/font/)
- [Image](/versions/latest/sdk/image)
- [KeepAwake](/versions/latest/sdk/keep-awake/)
- [LinearGradient](/versions/latest/sdk/linear-gradient/)
- [Localization](/versions/latest/sdk/localization/)
- [Manifests](/versions/latest/sdk/manifests/)
- [MediaLibrary](/versions/latest/sdk/media-library/)
- [NetInfo](/versions/latest/sdk/netinfo/)
- [Network](/versions/latest/sdk/network/)
- [Reanimated](/versions/latest/sdk/reanimated/)
- [SafeAreaContext](/versions/latest/sdk/safe-area-context/)
- [SecureStore](/versions/latest/sdk/securestore/)
- [SplashScreen](/versions/latest/sdk/splash-screen/)
- [Svg](/versions/latest/sdk/svg/)
- [SystemUI](/versions/latest/sdk/system-ui/)
- [TrackingTransparency](/versions/latest/sdk/tracking-transparency/)
- [Updates](/versions/latest/sdk/updates/)
- [Video](/versions/latest/sdk/video/)
TV also works with [React Navigation](https://react-navigation.nodejs.cn/), [React Native Skia](https://shopify.github.io/react-native-skia/), and many other commonly used third-party React Native libraries. See [React Native directory](https://reactnative.directory/?tvos=true) to learn more about supported third-party libraries.
#### Limitations
- The [Expo DevClient](/versions/latest/sdk/dev-client/) library is not supported at this time.
- The [Expo Router](/router/introduction/) library is only supported in SDK 51 and later.
---
## Integration with an existing Expo project
The following walkthrough describes the steps required to modify an Expo project for TV.
Step 1: 
### Modify dependencies for TV
In **package.json**, modify the `react-native` dependency to use the TV repo, and exclude this dependency from [`npx expo install` version validation](/more/expo-cli/#configuring-dependency-validation).
```json package.json
{
  "dependencies": {
    "react-native": "npm:react-native-tvos",
  },
  "expo": {
    "install": {
      "exclude": [
        "react-native"
      ]
    }
  }
}
```
Step 2: 
### Add the TV config plugin
```sh
$ npx expo install @react-native-tvos/config-tv -- --dev
```
When installed, the plugin will modify the project for TV when either:
- The environment variable `EXPO_TV` is set to `1`
- The plugin parameter `isTV` is set to `true`
Verify that this plugin appears in **app.json**:
```json app.json
{
  "plugins": ["@react-native-tvos/config-tv"]
}
```
To see additional information on the plugin's actions during prebuild, you can set [debug environment variables](https://github.com/debug-js/debug#conventions) before running prebuild. (See also our documentation on [Expo CLI environment variables](/more/expo-cli/#environment-variables).)
```sh
$ export DEBUG=expo:*
$ export DEBUG=expo:react-native-tvos:config-tv
```
Step 3: 
### Run prebuild
Set the `EXPO_TV` environment variable, and run prebuild to make the TV modifications to the project.
```sh
$ export EXPO_TV=1
$ npx expo prebuild --clean
```
> **Note**: The `--clean` argument is recommended, and is required if you have existing Android and iOS directories in the project.
Step 4: 
### Build for Android TV
Start an Android TV emulator and use the following command to start the app on the emulator:
```sh
$ npx expo run:android
```
Step 5: 
### Build for Apple TV
Run the following command to build and run the app on an Apple TV simulator:
```sh
$ npx expo run:ios
```
Step 6: 
### Revert TV changes and build for phone
You can revert the changes for TV and go back to phone development by unsetting `EXPO_TV` and running prebuild again:
```sh
$ unset EXPO_TV
$ npx expo prebuild --clean
```
Step 7: 
### Create EAS Build profiles for both TV and phone
Since the TV build can be driven by the value of an environment variable, it is easy to set up EAS Build profiles that build from the same source but target TV instead of phone.
The following example **eas.json** shows how to extend existing profiles (`development` and `preview`) to create TV profiles (`development_tv` and `preview_tv`).
```json eas.json
{
  "cli": {
    "version": ">= 5.2.0"
  },
  "build": {
    "base": {
      "distribution": "internal",
      "ios": {
        "simulator": true
      },
      "android": {
        "buildType": "apk",
        "withoutCredentials": true
      },
      "channel": "base"
    },
    "development": {
      "extends": "base",
      "android": {
        "gradleCommand": ":app:assembleDebug"
      },
      "ios": {
        "buildConfiguration": "Debug"
      },
      "channel": "development"
    },
    "development_tv": {
      "extends": "development",
      "env": {
        "EXPO_TV": "1"
      },
      "channel": "development"
    },
    "preview": {
      "extends": "base",
      "channel": "preview"
    },
    "preview_tv": {
      "extends": "preview",
      "env": {
        "EXPO_TV": "1"
      },
      "channel": "preview"
    }
  },
  "submit": {}
}
```
<a id="examples-and-demonstration-projects"></a>
## 示例和演示项目
¥Examples and demonstration projects


## 使用 TypeScript

有关使用 TypeScript 配置 Expo 项目的深入指南。

Expo 对 [TypeScript](https://ts.nodejs.cn/) 有一流的支持。Expo SDK 的 JavaScript 接口是用 TypeScript 编写的。
¥Expo has first-class support for [TypeScript](https://ts.nodejs.cn/). The JavaScript interface of Expo SDK is written in TypeScript.
本指南提供了一种快速开始新项目的方法，以及将现有的基于 JavaScript 的 Expo 项目迁移到使用 TypeScript 的步骤。
¥This guide provides a quick way to get started for a new project and also steps to migrate your existing JavaScript based Expo project to use TypeScript.
<a id="quick-start"></a>
## 快速开始
¥Quick start
要创建新项目，请使用包含基本 TypeScript 配置、示例代码和基本导航结构的默认模板：
¥To create a new project, use the default template which includes base TypeScript configuration, example code, and basic navigation structure:
```sh
$ npx create-expo-app@latest
```
使用上述命令创建新项目后，请确保遵循以下说明：
¥After you create a new project using the command above, make sure to follow instructions from:
* [设置你的环境](/get-started/set-up-your-environment/) 提供设置本地开发环境所需的步骤。
  ¥[Set up your environment](/get-started/set-up-your-environment/) which provides required steps for setting local development environment.
* [开始开发](/get-started/start-developing/) 提供有关触发开发服务器、文件结构和其他功能的详细信息。
  ¥[Start developing](/get-started/start-developing/) which provides information on triggering a development server, file structure, and details about other features.
<a id="migrating-existing-javascript-project"></a>
## 迁移现有 JavaScript 项目
¥Migrating existing JavaScript project
要迁移你现有的基于 JavaScript 的项目以使用 TypeScript，请按照以下说明操作：
¥To migrate your existing JavaScript based project to use TypeScript, follow the instructions below:
Step 1: 
### Rename files to use .tsx or .ts extension
Rename files to convert them to TypeScript. For example, start with the root component file such as **App.js** and rename it to **App.tsx**:
```sh
$ mv App.js App.tsx
```
> **info** **Tip:** Use the **.tsx** extension if the file includes React components (JSX). If the file does not include any JSX, you can use the **.ts** file extension.
Step 2: 
### Install required development dependencies
To install required `devDependencies` such as `typescript` and `@types/react` in **package.json**:
For macOS/Linux: 
```sh
$ npx expo install typescript @types/react --dev
```
For Windows: 
```sh
$ npx expo install typescript @types/react "--" --dev
```
> **info** Alternatively, run `npx expo start` command to install `typescript` and `@types/react` dev dependencies.
Note: Type checking project files with 
---
To type check your project's files run `tsc` command within the root of your project directory:
```sh
$ npm run tsc
$ yarn tsc
```
---
Step 3: 
### Add base configuration with tsconfig.json
A project's **tsconfig.json** should extend `expo/tsconfig.base` by default. You can automatically generate a **tsconfig.json** file by running the command:
```sh
$ npx expo customize tsconfig.json
```
The default configuration in **tsconfig.json** is user-friendly and encourages adoption. If you prefer **strict type checking** and reduce the chances of runtime errors, enable `strict` under [`compilerOptions`](https://ts.nodejs.cn/docs/handbook/compiler-options.html):
```json tsconfig.json
{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true
  }
}
```
Step 4: 
### Path aliases (Optional)
Expo CLI supports [path aliases](https://ts.nodejs.cn/docs/handbook/module-resolution.html#path-mapping) in **tsconfig.json** automatically. It allows importing modules with custom aliases instead of relative paths.
For example, to import `Button` component from **src/components/Button.tsx** using the alias **@/components/Button**, add the alias `@/*` in **tsconfig.json** and set it to the **src** directory:
```json tsconfig.json
{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```
Note: Disable path aliases
---
`tsconfigPaths` is enabled by default which allows you to set path aliases. You can disable it by setting `tsconfigPaths` to `false` in the project's [app config](/workflow/configuration/):
```json app.json
{
  "expo": {
    "experiments": {
      "tsconfigPaths": false
    }
  }
}
```
---
#### Considerations
When using path aliases, consider the following:
- Restart Expo CLI after modifying **tsconfig.json** to update path aliases. You don't need to clear the Metro cache when the aliases change.
- If not using TypeScript, **jsconfig.json** can serve as an alternative to **tsconfig.json**.
- Path aliases add additional resolution time when defined.
- Path aliases are only supported by Metro (including Metro web) and not by the deprecated `@expo/webpack-config`.
- Bare projects require additional setup for this feature. See the [Metro setup guide](/versions/latest/config/metro#bare-workflow-setup) for more information.
Step 5: 
### Absolute imports (Optional)
To enable absolute imports from a project's root directory, define [`compilerOptions.baseUrl`](https://ts.nodejs.cn/docs/handbook/module-resolution.html#base-url) the **tsconfig.json** file:
```json tsconfig.json
{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "baseUrl": "./"
  }
}
```
For example, setting the above configuration allows importing `Button` component from the path **src/components/Button**:
```tsx
import Button from 'src/components/Button';
```
#### Considerations
When using absolute imports, consider the following:
- `compilerOptions.paths` are resolved relative to the `compilerOptions.baseUrl` if it is defined, otherwise they're resolved against the project root directory.
- `compilerOptions.baseUrl` is resolved before node modules. This means if you have a file named `./path.ts`, it can be imported instead of a node module named `path`.
- Restarting Expo CLI is necessary to update [`compilerOptions.baseUrl`](https://ts.nodejs.cn/docs/handbook/module-resolution.html#base-url) after modifying the **tsconfig.json**.
- If you're not using TypeScript, **jsconfig.json** can serve as an alternative to **tsconfig.json**.
- Absolute imports are only supported by Metro (including Metro web) and not by `@expo/webpack-config`.
- Bare projects require additional setup for this feature. See the [versioned Metro setup guide](/versions/latest/config/metro#bare-workflow-setup) for more information.
## Type generation
Some Expo libraries provide both static types and type generation capabilities. These types are automatically generated when the project builds or by running the `npx expo customize tsconfig.json` command.
## TypeScript for project's config files
Additional setup is required to use TypeScript for configuration files such as **metro.config.js** or **app.config.js**. You need to utilize [`tsx/cjs` require hook](https://tsx.is/dev-api/entry-point#commonjs-mode-only) to import TypeScript files within your JS config file. This hook allows TypeScript imports while keeping the root file as JavaScript.
For macOS/Linux: 
```sh
$ npx expo install tsx --dev
```
For Windows: 
```sh
$ npx expo install tsx "--" --dev
```
### metro.config.js
Update **metro.config.js** to require **metro.config.ts** file:
```js metro.config.js
require('tsx/cjs');
module.exports = require('./metro.config.ts');
```
Update **metro.config.ts** file with your project's metro configuration:
```ts metro.config.ts
import { getDefaultConfig } from 'expo/metro-config';
const config = getDefaultConfig(__dirname);
module.exports = config;
```
Note: Deprecated: webpack.config.js
---
Install the `@expo/webpack-config` package.
```js webpack.config.js
require('tsx/cjs');
module.exports = require('./webpack.config.ts');
```
```ts webpack.config.ts
import createExpoWebpackConfigAsync from '@expo/webpack-config/webpack';
import { Arguments, Environment } from '@expo/webpack-config/webpack/types';
module.exports = async function (env: Environment, argv: Arguments) {
  const config = await createExpoWebpackConfigAsync(env, argv);
  // Customize the config before returning it.
  return config;
};
```
---
<a id="appconfigjs"></a>
### app.config.js
默认支持 app.config.ts。但是，它不支持外部 TypeScript 模块或 tsconfig.json 自定义。你可以使用以下方法来获得更全面的 TypeScript 设置：
¥**app.config.ts** is supported by default. However, it doesn't support external TypeScript modules, or **tsconfig.json** customization. You can use the following approach to get a more comprehensive TypeScript setup:
```ts app.config.ts
import 'tsx/cjs'; // Add this to import TypeScript files
import { ExpoConfig } from 'expo/config';
const config: ExpoConfig = {
  name: 'my-app',
  slug: 'my-app',
};
export default config;
```
<a id="other-typescript-features"></a>
## 其他 TypeScript 功能
¥Other TypeScript features
某些语言功能可能需要额外的配置。例如，如果你想使用装饰器，则需要添加 `experimentalDecorators` 选项。有关可用属性的更多信息，请参阅 [TypeScript 编译器选项](https://ts.nodejs.cn/docs/handbook/compiler-options.html) 文档。
¥Some language features may require additional configuration. For example, if you want to use decorators you'll need to add the `experimentalDecorators` option. For more information on the available properties see the [TypeScript compiler options](https://ts.nodejs.cn/docs/handbook/compiler-options.html) documentation.
<a id="learn-how-to-use-typescript"></a>
## 了解如何使用 TypeScript
¥Learn how to use TypeScript
官方 [TypeScript 手册](https://ts.nodejs.cn/docs/handbook/2/everyday-types.html) 是开始学习 TypeScript 的好地方。
¥A good place to start learning TypeScript is the official [TypeScript Handbook](https://ts.nodejs.cn/docs/handbook/2/everyday-types.html).
对于 TypeScript 和 React 组件，我们建议参考 [React TypeScript 备忘单](https://github.com/typescript-cheatsheets/react) 来了解如何在各种常见情况下键入 React 组件。
¥**For TypeScript and React components,** we recommend referring to the [React TypeScript CheatSheet](https://github.com/typescript-cheatsheets/react) to learn how to type your React components in a variety of common situations.


## 使用应用内购买

了解如何在 Expo 应用中使用应用内购买。

应用内购买 (IAP) 是移动或桌面应用内的事务，用户可以在其中购买数字商品或附加功能。本指南提供了在 Expo 应用中实现 IAP 的流行库和教程的列表。
¥In-app purchases (IAP) are transactions within a mobile or desktop application where users can buy digital goods or additional features. This guide provides a list of popular libraries and tutorials for implementing IAP in your Expo app.
> 应用内购买库需要配置自定义原生代码。使用 Expo Go 时，原生代码不可配置。相反，创建一个 [开发构建](/develop/development-builds/introduction/)，它允许在你的项目中使用原生库。
>
> ¥In-app purchase libraries require configuring custom native code. Native code is not configurable when using Expo Go. Instead, create a [development build](/develop/development-builds/introduction/), which allows using a native library in your project.
<a id="tutorial"></a>
## 教程
¥Tutorial
<a id="libraries"></a>
## 库
¥Libraries
以下库为应用内购买功能以及使用 [CNG](/workflow/continuous-native-generation/) 和 [配置插件](/config-plugins/introduction/) 与 Expo 应用的开箱即用兼容性提供了强大的支持，以便在你的应用中无缝集成。
¥The following libraries provide robust support for in-app purchase functionality and out-of-the-box compatibility with Expo apps using [CNG](/workflow/continuous-native-generation/) and [Config Plugins](/config-plugins/introduction/) for seamless integration in your app.


## 使用推送通知

了解与 Expo 和 React Native 应用兼容的推送通知服务。

Expo 应用可以与任何通知服务或 Android 和 iOS 操作系统提供的任何通知功能配合使用。即使某个功能的包尚不存在，也可以编写原生代码通过 [Expo 模块 API](/modules/overview/) 访问它，并且可以使用 [配置插件](/config-plugins/introduction/) 自动化原生项目配置。以下选项提供专门构建的 Expo 集成，包括必要的配置插件，用于在你的应用中实现推送通知：
¥Expo apps can work with any notification service or any of the notification capabilities offered by the Android and iOS operating systems. Even if a package doesn't yet exist for a feature, native code can be written to access it via the [Expo Modules API](/modules/overview/), and native project configurations can be automated using [config plugins](/config-plugins/introduction/). The following options provide purpose-built Expo integrations, including config plugins where necessary, for implementing push notifications in your app:
> [`expo-notifications`](/versions/latest/sdk/notifications/) 库经过设计和测试，可与 Expo 的推送通知服务以及直接从 FCM 和 APNS 发送的通知配合使用。某些高级功能可能与第三方提供商不兼容，因为他们通常有自己的原生和针对其服务优化的 React Native SDK。
>
> ¥The [`expo-notifications`](/versions/latest/sdk/notifications/) library is designed and tested to work with Expo's push notification service and notifications sent directly from FCM and APNS. Some advanced features may not be compatible with third-party providers, as they often have their own native and React Native SDKs optimized for their services.
<a id="expo-push-notifications"></a>
## Expo 推送通知
¥Expo push notifications
[Expo 通知](/versions/latest/sdk/notifications/) 提供了一个统一的 API，用于处理 Android 和 iOS 上的推送通知。它与你的 Expo 账户无缝集成，并且可以免费使用。
¥[Expo Notifications](/versions/latest/sdk/notifications/) provides a unified API for handling push notifications across Android and iOS. It integrates seamlessly with your Expo account and is free to use.
<a id="key-capabilities"></a>
### 关键功能
¥Key capabilities
* 与 [`expo-notifications`](/versions/latest/sdk/notifications/) 库完全兼容
  ¥Fully compatible with the [`expo-notifications`](/versions/latest/sdk/notifications/) library
* 包含一个 EAS 仪表板，用于跟踪通知发送到 FCM 和 APNs 的情况
  ¥Includes an EAS dashboard to track notification delivery to FCM and APNs
* 支持使用 [Expo 通知工具](https://expo.dev/notifications) 测试通知
  ¥Supports testing notifications with the [Expo Notifications Tool](https://expo.dev/notifications)
<a id="considerations-and-limitations"></a>
### 注意事项和限制
¥Considerations and limitations
* 用于向通知添加其他内容（例如图片）的 iOS 通知服务扩展尚未正式包含在内，但你可以使用包含自定义原生代码和配置 ([example](https://github.com/expo/expo/pull/36202)) 的配置插件来添加它。
  ¥iOS Notification Service Extension for adding additional content to notifications, such as images, is not formally included, but you can add it using a config plugin with custom native code and configuration ([example](https://github.com/expo/expo/pull/36202)).
* 每个项目每秒的通知量限制为 600 条。
  ¥Volumes are limited to 600 notifications per second per project.
有关实现详细信息，请参阅以下指南：
¥For implementation details, see the following guides:
<a id="onesignal"></a>
## OneSignal
[OneSignal](https://onesignal.com/) 是一个客户互动平台，可为网络和移动应用提供推送通知、应用内消息、短信和电子邮件服务。OneSignal 支持通知和参与度分析中的富媒体。它包括一个 [Expo 配置插件](https://github.com/OneSignal/onesignal-expo-plugin)，可直接集成到你的 Expo 项目中。
¥[OneSignal](https://onesignal.com/) is a customer engagement platform that provides push notifications, in-app messaging, SMS, and email services for web and mobile apps. OneSignal supports rich media in notifications and engagement analytics. It includes an [Expo config plugin](https://github.com/OneSignal/onesignal-expo-plugin) for direct integration into your Expo project.
<a id="braze"></a>
## Braze
[Braze](https://www.braze.com/) 是一个客户互动平台，可通过推送通知、应用内消息、电子邮件、短信和网络提供个性化的跨渠道消息传递。Braze 支持丰富的通知内容、推送通知活动，并支持在 Android 上交付失败后重新发送通知。它提供了 [React Native SDK](https://github.com/braze-inc/braze-react-native-sdk) 和 [配置插件](https://github.com/braze-inc/braze-expo-plugin/tree/main)。查看 [Expo 示例应用](https://github.com/braze-inc/braze-expo-plugin/tree/main/example) 了解更多详细信息。
¥[Braze](https://www.braze.com/) is a customer engagement platform that delivers personalized, cross-channel messaging through push notifications, in-app messaging, email, SMS, and web. Braze supports rich notification content, push notification campaigns, and support for resending notifications after failed deliveries on Android. It provides a [React Native SDK](https://github.com/braze-inc/braze-react-native-sdk) and a [config plugin](https://github.com/braze-inc/braze-expo-plugin/tree/main). Check out the [Expo example app](https://github.com/braze-inc/braze-expo-plugin/tree/main/example) for more details.
<a id="customerio"></a>
## Customer.io
[Customer.io](http://Customer.io) 是一个客户参与平台，可让你利用推送通知、应用内消息、电子邮件、短信功能等设计强大的自动化工作流程。其可视化工作流构建器允许你跨多个渠道自动化复杂的数据驱动活动。Customer.io 支持设备端指标收集，可用于根据用户行为和偏好定制推送通知。Customer.io 提供 [Expo 插件](https://github.com/customerio/customerio-expo-plugin) 以直接与你的 Expo 项目集成，并提供使用 Customer.io 推送通知以及其他提供商的文档。
¥[Customer.io](http://Customer.io) is a customer engagement platform that allows you to design powerful automated workflows utilizing push notifications, in-app messaging, email, SMS capabilities, and more. Its visual workflow builder allows you to automate complex, data-driven campaigns across multiple channels. Customer.io supports device-side metrics collection that can be used to customize push notifications tailored to user behaviors and preferences. Customer.io provides an [Expo plugin](https://github.com/customerio/customerio-expo-plugin) for direct integration with your Expo project and documentation for using Customer.io push notifications alongside other providers.
<a id="clevertap"></a>
## CleverTap
[CleverTap](https://clevertap.com/) 是一个一体化客户互动平台，可帮助你通过推送通知、应用内消息、电子邮件等方式传递个性化、实时、全渠道的消息。它提供高级细分、分析和营销活动自动化功能，可根据你的业务规模进行扩展。[CleverTap React Native SDK](https://developer.clevertap.com/docs/react-native) 和 [Expo 配置插件](https://github.com/CleverTap/clevertap-expo-plugin) 可以轻松地将 CleverTap 集成到你的 Expo 项目中。配置插件在预构建过程中处理所有原生模块的设置，使你可以通过应用配置来配置 CleverTap，而无需手动修改原生代码。更多信息，请查看 [CleverTap 示例插件](https://github.com/CleverTap/clevertap-expo-plugin/tree/main/CTExample)。
¥[CleverTap](https://clevertap.com/) is an all-in-one customer engagement platform that helps you deliver personalized, real-time, omnichannel messaging across push notifications, in-app messages, email, and more. It offers advanced segmentation, analytics, and campaign automation — built to scale with your business. The [CleverTap React Native SDK](https://developer.clevertap.com/docs/react-native) and [Expo config plugin](https://github.com/CleverTap/clevertap-expo-plugin) make it easy to integrate CleverTap into your Expo projects. The config plugin handles all the native module setup during the prebuild process, allowing you to configure CleverTap through your app config without having to manually modify native code. For more information, check out the [CleverTap Example Plugin](https://github.com/CleverTap/clevertap-expo-plugin/tree/main/CTExample).
<a id="send-notifications-directly-via-fcm-and-apns"></a>
## 通过 FCM 和 APN 直接发送通知
¥Send notifications directly via FCM and APNs
你可以选择从后端直接发送到平台推送 API。在这种情况下，你仍然可以使用 [`expo-notifications`](/versions/latest/sdk/notifications/) 检索原生推送令牌并为每个平台单独配置通知。
¥You may choose to send directly to platform push API's from your backend. In this case, you can still use [`expo-notifications`](/versions/latest/sdk/notifications/) to retrieve the native push token and configure notifications separately for each platform.
尽管客户端代码与 [`expo-notifications`](/versions/latest/sdk/notifications/) 保持跨平台，但你需要实现服务器端逻辑以分别与 [FCM](https://firebase.google.com/docs/cloud-messaging) 和 [APNs](https://developer.apple.com/documentation/usernotifications) API 交互。
¥Although the client-side code remains cross-platform with [`expo-notifications`](/versions/latest/sdk/notifications/), you will need to implement server-side logic to interact with the [FCM](https://firebase.google.com/docs/cloud-messaging) and [APNs](https://developer.apple.com/documentation/usernotifications) APIs individually.
<a id="react-native-firebase-messaging"></a>
## React Native Firebase 消息传递
¥React Native Firebase messaging
[React Native Firebase](https://rnfirebase.io/) 提供了一个消息模块，让你可以将 [Firebase 云消息传递 (FCM)](https://firebase.google.com/docs/cloud-messaging) 用作 Android 和 iOS 的统一推送通知服务。虽然 FCM 通常与 Android 通知相关联，但它也通过在后台通过 Apple Push Notification 服务 (APN) 路由消息来支持 iOS。
¥[React Native Firebase](https://rnfirebase.io/) provides a messaging module that lets you use [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging) as a unified push notification service for both Android and iOS. While FCM is often associated with Android notifications, it also supports iOS by routing messages through Apple Push Notification service (APNs) behind the scenes.
这种方法不同于仅将 FCM 用于 Android 通知。相反，Firebase 的跨平台 SDK 通过单一服务处理两个平台的通知。
¥This approach differs from using FCM solely for Android notifications. Instead, Firebase's cross-platform SDK handles notifications for both platforms through a single service.
> 即使 FCM 处理两个平台的通知，iOS 通知仍会通过 APN。Firebase 会自动管理此路由。在 [React Native Firebase 消息传递文档](https://rnfirebase.io/messaging/usage) 中了解更多信息。
>
> ¥Even though FCM handles notifications for both platforms, iOS notifications still go through APNs. Firebase automatically manages this routing. Learn more in the [React Native Firebase messaging documentation](https://rnfirebase.io/messaging/usage).
<a id="tips-and-important-considerations"></a>
## 提示和重要提示注意事项
¥Tips and important considerations
* 避免混合客户端实现：不同的通知服务可能有冲突的客户端实现。使用一致的方法防止潜在问题。
  ¥**Avoid mixing client-side implementations**: Different notification services may have conflicting client-side implementations. Use a consistent approach to prevent potential issues.
* Web 通知：Expo 通知不支持 Web 通知。但是，某些第三方解决方案可能会提供此功能。选择服务时，请考虑应用的要求。
  ¥**Web notifications**: Expo notifications do not support web notifications. However, some third-party solutions may offer this capability. Consider your app's requirements when choosing a service.
* 令牌管理：在你的数据库中跟踪 Expo 推送令牌和原生设备令牌。这为未来的集成提供了灵活性，尤其是通过 FCM 或 APN 直接发送通知的营销工具。
  ¥**Token management**: Track both Expo push tokens and native device tokens in your database. This provides flexibility for future integrations, especially with marketing tools that send notifications directly via FCM or APNs.


## React Native 功能开关服务

Expo 和 React Native 生态系统中可用的功能开关服务概述。

功能开关（也称为功能门控）是一种远程启用和禁用功能的机制。它们是一种安全地向应用用户推出新功能的方法，无需部署额外的代码。你可以使用它们进行生产环境测试、A/B 测试，或发布新的应用功能（例如 UI 元素）。
¥A feature flag (also known as a *feature gate*) is a mechanism that enables and disables features remotely. They are a safe way to rollout new features to your app users without deploying additional code. You can use them for testing in production, A/B testing, or to ship new app features such as UI elements.
<a id="feature-flag-services"></a>
## 功能标志服务
¥Feature flag services
以下库为功能标记功能提供强大的支持，并与使用 [持续的原生生成 (CNG)](/workflow/continuous-native-generation/) 和 [配置插件](/config-plugins/introduction/) 的 Expo 应用提供开箱即用的兼容性，从而实现与你的应用的无缝集成。
¥The following libraries provide robust support for feature flag functionality and out-of-the-box compatibility with Expo apps using [Continuous Native Generation (CNG)](/workflow/continuous-native-generation/) and [config plugins](/config-plugins/introduction/) for seamless integration in your app.
<a id="posthog"></a>
### Posthog
[PostHog](https://posthog.com/) 是一个开源产品分析平台，提供全面的功能标记功能以及分析、会话记录和 A/B 测试。它支持实时功能切换、用户细分以及即时回滚功能，对于希望在单一平台上进行分析和功能管理的团队来说，它是一个绝佳的选择。它包含内置的 A/B 测试和多变量测试功能，允许你直接通过功能开关运行实验，同时收集有关功能采用率和性能指标的详细分析数据。该服务还支持引导标志，以消除加载状态并提升用户体验。
¥[PostHog](https://posthog.com/) is an open-source product analytics platform that provides comprehensive feature flagging capabilities alongside analytics, session recordings, and A/B testing. It supports real-time feature toggles with user segmentation and the ability to roll back features instantly, making it an excellent choice for teams that want analytics and feature management in a single platform. It includes built-in A/B testing and multivariate testing functionality, allowing you to run experiments directly through feature flags while collecting detailed analytics on feature adoption and performance metrics. The service also supports bootstrap flags to eliminate loading states and improve user experience.
<a id="statsig"></a>
### Statsig
[Statsig](https://statsig.com/) 是一个功能管理平台，专为数据驱动的产品开发而设计，它提供高级统计分析、逐步推出和复杂的定位功能，并内置功能发布的指标和性能监控。该平台为 React Native 和 Expo 提供了强大的 SDK，具有自动事件日志记录和动态配置功能，尤其适合专注于严谨实验和数据驱动决策的团队。
¥[Statsig](https://statsig.com/) is a feature management platform designed for data-driven product development that provides advanced statistical analysis, gradual rollouts, and sophisticated targeting capabilities with built-in metrics and performance monitoring for feature releases. The platform offers a robust SDK for React Native and Expo, with automatic event logging and dynamic configurations, making it particularly well-suited for teams focused on rigorous experimentation and data-driven decision-making.
<a id="launchdarkly"></a>
### LaunchDarkly
[LaunchDarkly](https://launchdarkly.com/) 是一个企业级功能管理平台，它支持即时功能切换和定向部署，并具备全面的仪表板控制、高级用户定位功能以及提供实时标志更新的强大实验工具。SDK 包含一些高级功能，例如用于 React 集成的钩子、上下文识别和修改、全面的日志记录、开发工作流中的多环境支持、用于处理敏感数据的私有属性以及用于增强安全性和性能的中继代理配置。
¥[LaunchDarkly](https://launchdarkly.com/) is an enterprise-grade feature management platform that enables instant feature toggles and targeted rollouts with comprehensive dashboard controls, advanced user targeting, and robust experimentation tools that provide real-time flag updates. The SDK includes advanced features such as hooks for React integration, context identification and modification, comprehensive logging, support for multiple environments in development workflows, private attributes for handling sensitive data, and relay proxy configuration for enhanced security and performance.
<a id="firebase-remote-config"></a>
### Firebase 远程配置
¥Firebase Remote Config
[Firebase 远程配置](https://firebase.google.com/docs/remote-config) 是一项云服务，允许你更改应用的外观和功能，而无需更新应用。远程配置值通过 Firebase 控制台进行管理，并通过 JavaScript API 访问，这使你可以完全控制这些值何时以及如何影响你的应用。该服务支持基于用户属性、应用版本、自定义属性和实时更新的条件定位。
¥[Firebase Remote Config](https://firebase.google.com/docs/remote-config) is a cloud service allows you to change the appearance and functionality of your app without requiring an app update. Remote Config values are managed through the Firebase console and accessed via a JavaScript API, which gives you full control over when and how these values affect your app. The service supports conditional targeting based on user properties, app versions, custom attributes and real-time updates.


# 故障排除

## 故障排除概述

使用 Expo 和 EAS 进行应用开发故障排除指南的概述。

此页面列出了 Expo 和 EAS 的各种故障排除指南集合。
¥This page lists a collection of various troubleshooting guides for Expo and EAS.
<a id="error-and-warnings"></a>
## 错误和警告
¥Error and warnings
<a id="runtime-issues-in-development-and-production"></a>
## 开发和生产中的运行时问题
¥Runtime issues in development and production
<a id="expo-router"></a>
## Expo 路由
¥Expo Router
<a id="push-notifications"></a>
## 推送通知
¥Push notifications
<a id="eas"></a>
## EAS


## "应用尚未注册" 错误

了解应用未注册错误的含义以及如何在 Expo 或 React Native 应用中解决该错误。

在开发 Expo 或 React Native 应用时，经常会遇到类似这样的错误：
¥When developing an Expo or React Native app, it's common to run into an error that looks like:
```sh
Application "main" has not been registered.
Invariant Violation: "main" has not been registered.
```
在此特定错误中，`"main"` 可以是任何字符串。
¥In this particular error, `"main"` can be any string.
<a id="what-this-error-means"></a>
## 这个错误意味着什么
¥What this error means
<a id="an-exception-may-be-preventing-your-app-from-registering-itself"></a>
### 异常可能会阻止你的应用自行注册
¥An exception may be preventing your app from registering itself
导致此错误的最常见原因是应用在能够自行注册之前引发了异常。当 React Native 应用加载时，有两个步骤：
¥The most common cause of this error is that there is an exception thrown in your application before it's able to register itself. When a React Native application loads, there are two steps:
1. 加载 JavaScript 代码，如果一切成功，那么你的应用将被注册。如果加载打包包时出现任何异常，则执行将中止，并且永远不会到达应用注册的部分。
   ¥Load the JavaScript code, and if everything is successful, then your application will be registered. If there is any exception when loading the bundle then execution will be aborted and it will never reach the part where your application is registered.
2. 运行注册的应用。如果加载代码失败，则应用将不会注册，你将看到本页主题的错误。
   ¥Run the registered application. If loading the code failed, then the application won't be registered and you will see the error that is the subject of this page.
如果你遇到这种情况，你看到的错误消息是 [红鲱鱼](https://en.wikipedia.org/wiki/Red_herring)，它会分散你对导致应用未注册的真正错误的注意力。
¥If you're in this situation, the error message you're seeing is a [red herring](https://en.wikipedia.org/wiki/Red_herring), it's distracting you from the real error that led to the application not being registered.
查看此错误消息之前的日志，了解可能导致该错误的原因。一个常见的原因是原生模块依赖的多个版本将自身注册为视图 - 例如 [这个 Stack Overflow 线程](https://stackoverflow.com/questions/67543844/invariant-violation-main-has-not-been-registered-while-running-react-native-a/67550379)，其中发布者的依赖中有多个版本的 `react-native-safe-area-context`。
¥Look at your logs before this error message to see what may have caused it. A frequent cause is multiple versions of a native module dependency that registers itself as a view — for example [this Stack Overflow thread](https://stackoverflow.com/questions/67543844/invariant-violation-main-has-not-been-registered-while-running-react-native-a/67550379) where the poster has multiple versions of `react-native-safe-area-context` in their dependencies.
<a id="your-app-root-component-may-not-be-registered"></a>
### 你的应用根组件可能未注册
¥Your app root component may not be registered
另一种可能性是提供给 [`AppRegistry.registerComponent`](https://rn.nodejs.cn/docs/appregistry#registercomponent) 的 `AppKey` 与在原生 iOS 或 Android 端注册的 `AppKey` 之间存在不匹配。
¥Another possibility is that there is a mismatch between the `AppKey` being provided to [`AppRegistry.registerComponent`](https://rn.nodejs.cn/docs/appregistry#registercomponent), and the `AppKey` being registered on the native iOS or Android side.
在托管项目中，默认行为是使用 "main" 作为 `AppKey`。这是自动为你处理的，只要你不更改 package.json 中的 `"main"` 字段的默认值，那么这就会起作用。如果你想自定义应用入口点，请参阅 [registerRootComponent](/versions/latest/sdk/expo/#registerrootcomponentcomponent) API 参考。
¥In managed projects, the default behavior is to use "main" as the `AppKey`. This is handled for you automatically, and as long as you don't change the `"main"` field in your **package.json** from the default value then this will just work. If you want to customize the app entry point, see [registerRootComponent](/versions/latest/sdk/expo/#registerrootcomponentcomponent) API reference.
在使用原生代码的项目中，默认情况下你将在 index.js 中看到类似以下内容：
¥In projects with native code, you will see something like this in your **index.js** by default:
```js
import { registerRootComponent } from 'expo';
import App from './App';
registerRootComponent(App);
```
其中 `registerRootComponent` 的实现为：
¥where `registerRootComponent` is implemented as:
```js
function registerRootComponent(component) {
  AppRegistry.registerComponent('main', () => component);
}
```
在原生方面，在 AppDelegate.m 中你应该看到：
¥And on the native side, in **AppDelegate.m** you should see:
```objectivec
RCTRootView *rootView = [[RCTRootView alloc] initWithBridge:bridge moduleName:@"main" initialProperties:nil];
```
在 MainActivity.java 中：
¥and in **MainActivity.java**:
```java
@Override
protected String getMainComponentName() {
  return "main";
}
```
默认情况下，"main" 在整个项目中一致使用。如果你遇到此错误，则某些内容可能已发生变化，并且这些值不再一致。确保你在 JavaScript 端注册的名称是原生端所需的名称（如果你使用 Expo 的 `registerRootComponent` 函数，则为 "main"）。
¥By default, "main" is consistently used throughout the project. If you're running into this error, something has likely changed and these values no longer coincide. Ensure that the names you are registering on the JavaScript side are the ones expected on the native side (if you're using Expo's `registerRootComponent` function, that would be "main").
<a id="other-considerations"></a>
## 其他考虑因素
¥Other considerations
此错误也可能发生在其他一些情况下，但它不太可预测，并且修复将更针对你的项目。例如，其他一些情况是：
¥This error can also occur in a few other scenarios, but it's less predictable and the fixes would be more specific to your project. For example, some other cases are:
* 你正在连接到错误项目的本地开发服务器。尝试关闭其他 Expo CLI 或 React Native 社区 CLI 进程（使用 `ps -A | grep "expo\|react-native"` 查找它们）。
  ¥You're connecting to the wrong project's local development server. Try closing out other Expo CLI or React Native community CLI processes (find them with `ps -A | grep "expo\|react-native"`).
* 如果此错误仅发生在你的生产应用中，请尝试使用 `npx expo start --no-dev --minify` 在生产模式下本地运行该应用以查找错误根源。
  ¥If this error is only occurring in your production app, then try running the app locally in production mode with `npx expo start --no-dev --minify` to find the source of the error.


## 清除 macOS 和 Linux 上的打包程序缓存

了解如何在 macOS 和 Linux 上使用 Yarn 或 npm 与 Expo CLI 或 React Native CLI 时清除打包器缓存。

> 需要清除 Windows 上的开发缓存吗？[在这里找到相关命令。](/troubleshooting/clear-cache-windows/)
>
> ¥Need to clear development caches on Windows? [Find the relevant commands here.](/troubleshooting/clear-cache-windows/)
有许多与你的项目关联的不同缓存可能会阻止你的项目按预期运行。清除缓存有时可以帮助你解决与旧的或损坏的数据相关的问题，并且在故障排除和调试时通常很有用。
¥There are a number of different caches associated with your project that can prevent your project from running as intended. Clearing a cache sometimes can help you work around issues related to stale or corrupt data and is often useful when troubleshooting and debugging.
要清除各种缓存，请运行：
¥To clear the various caches, run:
<a id="expo-cli-and-yarn"></a>
## Expo CLI 和 Yarn
¥Expo CLI and Yarn
```sh
you may need to delete node_modules in each workspace
$ rm -rf node_modules
$ yarn cache clean
$ yarn
$ watchman watch-del-all
$ rm -fr $TMPDIR/haste-map-*
$ rm -rf $TMPDIR/metro-cache
$ npx expo start --clear
```
<a id="expo-cli-and-npm"></a>
## Expo CLI 和 npm
¥Expo CLI and npm
```sh
$ rm -rf node_modules
$ npm cache clean --force
$ npm install
$ watchman watch-del-all
$ rm -fr $TMPDIR/haste-map-*
$ rm -rf $TMPDIR/metro-cache
$ npx expo start --clear
```
<a id="react-native-cli-and-yarn"></a>
## React Native CLI 和 Yarn
¥React Native CLI and Yarn
```sh
you may need to delete node_modules in each workspace
$ rm -rf node_modules
$ yarn cache clean
$ yarn
$ watchman watch-del-all
$ rm -fr $TMPDIR/haste-map-*
$ rm -rf $TMPDIR/metro-cache
$ yarn start -- --reset-cache
```
<a id="react-native-cli-and-npm"></a>
## React Native CLI 和 npm
¥React Native CLI and npm
```sh
$ rm -rf node_modules
$ npm cache clean --force
$ npm install
$ watchman watch-del-all
$ rm -fr $TMPDIR/haste-map-*
$ rm -rf $TMPDIR/metro-cache
$ npm start -- --reset-cache
```
<a id="what-these-commands-are-doing"></a>
## 这些命令在做什么
¥What these commands are doing
在运行之前了解在互联网上找到的命令是一个好习惯。我们解释了下面针对 Expo CLI、npm 和 Yarn 的每个命令，但相应的命令 React Native CLI 具有相同的行为。
¥It is a good habit to understand commands you find on the internet before you run them. We explain each command below for Expo CLI, npm, and Yarn, but the corresponding commands React Native CLI have the same behavior.
| 命令                        | 描述                           |
| ------------------------- | ---------------------------- |
| `rm -rf node_modules`     | 清除项目的所有依赖                    |
| `yarn cache clean`        | 清除全局 Yarn 缓存                 |
| `npm cache clean --force` | 清除全局 npm 缓存                  |
| `yarn`/`npm install`      | 重新安装所有依赖                     |
| `watchman watch-del-all`  | 重置 `watchman` 文件监视器          |
| `rm -rf $TMPDIR/<cache>`  | 清除给定的打包程序/打包程序缓存文件或目录        |
| `npx expo start --clear`  | 重新启动开发服务器并清除 JavaScript 转换缓存 |


## 清除 Windows 上的打包程序缓存

了解如何在 Windows 上使用 Expo CLI 或 React Native CLI 时清除 Yarn 或 npm 的打包器缓存。

> 需要清除 macOS 或 Linux 上的开发缓存吗？[在这里找到相关命令。](/troubleshooting/clear-cache-macos-linux/)
>
> ¥Need to clear development caches on macOS or Linux? [Find the relevant commands here.](/troubleshooting/clear-cache-macos-linux/)
有许多与你的项目关联的不同缓存可能会阻止你的项目按预期运行。清除缓存有时可以帮助你解决与旧的或损坏的数据相关的问题，并且在故障排除和调试时通常很有用。
¥There are a number of different caches associated with your project that can prevent your project from running as intended. Clearing a cache sometimes can help you work around issues related to stale or corrupt data and is often useful when troubleshooting and debugging.
<a id="expo-cli-and-yarn"></a>
## Expo CLI 和 Yarn
¥Expo CLI and Yarn
```sh
you may need to delete node_modules in each workspace
$ rm -rf node_modules
$ yarn cache clean
$ yarn
$ watchman watch-del-all
$ del %localappdata%\Temp\haste-map-*
$ del %localappdata%\Temp\metro-cache
$ npx expo start --clear
```
<a id="expo-cli-and-npm"></a>
## Expo CLI 和 npm
¥Expo CLI and npm
```sh
$ rm -rf node_modules
$ npm cache clean --force
$ npm install
$ watchman watch-del-all
$ del %localappdata%\Temp\haste-map-*
$ del %localappdata%\Temp\metro-cache
$ npx expo start --clear
```
<a id="react-native-cli-and-yarn"></a>
## React Native CLI 和 Yarn
¥React Native CLI and Yarn
```sh
you may need to delete node_modules in each workspace
$ rm -rf node_modules
$ yarn cache clean
$ yarn
$ watchman watch-del-all
$ del %localappdata%\Temp\haste-map-*
$ del %localappdata%\Temp\metro-cache
$ yarn start -- --reset-cache
```
<a id="react-native-cli-and-npm"></a>
## React Native CLI 和 npm
¥React Native CLI and npm
```sh
$ rm -rf node_modules
$ npm cache clean --force
$ npm install
$ watchman watch-del-all
$ del %localappdata%\Temp\haste-map-*
$ del %localappdata%\Temp\metro-cache
$ npm start -- --reset-cache
```
<a id="what-these-commands-are-doing"></a>
## 这些命令在做什么
¥What these commands are doing
在运行之前了解在互联网上找到的命令是一个好习惯。我们解释了下面针对 Expo CLI、npm 和 Yarn 的每个命令，但相应的命令 React Native CLI 具有相同的行为。
¥It is a good habit to understand commands you find on the internet before you run them. We explain each command below for Expo CLI, npm, and Yarn, but the corresponding commands React Native CLI have the same behavior.
| 命令                                | 描述                           |
| --------------------------------- | ---------------------------- |
| `del node_modules`                | 清除项目的所有依赖                    |
| `yarn cache clean`                | 清除全局 Yarn 缓存                 |
| `npm cache clean --force`         | 清除全局 npm 缓存                  |
| `yarn`/`npm install`              | 重新安装所有依赖                     |
| `watchman watch-del-all`          | 重置 `watchman` 文件监视器          |
| `del %localappdata%\Temp/<cache>` | 清除给定的打包程序/打包程序缓存文件或目录        |
| `npx expo start --clear`          | 重新启动开发服务器并清除 JavaScript 转换缓存 |


## "React Native 版本不匹配" 错误

了解 React Native 版本不匹配的含义以及如何在 Expo 或 React Native 应用中解决该问题。

在开发 Expo 或 React Native 应用时，经常会遇到类似这样的错误：
¥When developing an Expo or React Native app, it's common to run into an error that looks like:
```sh
React Native version mismatch.
JavaScript version: X.XX.X
Native version: X.XX.X
Make sure you have rebuilt the native code...
```
<a id="what-this-error-means"></a>
## 这个错误意味着什么
¥What this error means
你在终端中运行的打包程序（使用 `npx expo start`）使用的 `react-native` JavaScript 版本与设备或模拟器上的原生应用不同。升级 React Native 或 Expo SDK 版本后，或者连接到错误的本地开发服务器时，可能会发生这种情况。
¥The bundler that you're running in your terminal (using `npx expo start`) is using a different JavaScript version of `react-native` than the native app on your device or emulator. This can happen after upgrading your React Native or Expo SDK version, *or* when connecting to the wrong local development server.
<a id="how-to-fix-it"></a>
## 如何修复它
¥How to fix it
* 关闭你正在运行的所有开发服务器（你可以使用 `ps` 命令列出所有终端进程，并使用 `ps -A | grep "expo\|react-native"` 搜索 Expo CLI 或 React Native 社区 CLI 进程）。
  ¥Close out any development servers that you have running (you can list all terminal processes with the `ps` command, and search for Expo CLI or React Native community CLI processes with `ps -A | grep "expo\|react-native"`).
* 如果这是一个 Expo 项目，请从你的 app.json 文件中删除 `sdkVersion` 字段，或者确保它与你的 package.json 文件中的 `expo` 依赖的值匹配。
  ¥If this is a Expo project, either remove the `sdkVersion` field from your **app.json** file, or make sure it matches the value of the `expo` dependency in your **package.json** file.
* 如果这是一个 Expo 项目，你应该确保你的 `react-native` 版本正确。运行 `npx expo-doctor` 将在你应安装 `react-native` 版本的位置显示警告。如果你确实升级到较新的 SDK，请确保运行 `npx expo install --fix` 并按照提示操作。Expo CLI 将确保 `expo` 和 `react-native` 等软件包的依赖版本保持一致。
  ¥If this is a Expo project, you should make sure your `react-native` version is correct. Run `npx expo-doctor` will show a warning where the `react-native` version you should install. If you did upgrade to a newer SDK, make sure to run `npx expo install --fix` and follow the prompts. Expo CLI will make sure that your dependency versions for packages like `expo` and `react-native` are aligned.
* 如果这是一个裸 React Native 项目，并且在升级你的 React Native 版本后立即发生此错误，你应该仔细检查你是否已正确执行每个升级步骤。
  ¥If this is a bare React Native project, and this error is occurring right after upgrading your React Native version, you should double-check that you have performed each of the upgrade steps correctly.
* 最后：
  ¥Finally:
  * 通过运行 `rm -rf node_modules && npm cache clean --force && npm install && watchman watch-del-all && rm -rf $TMPDIR/haste-map-* && rm -rf $TMPDIR/metro-cache && npx expo start --clear` 清除打包程序缓存
    ¥Clear your bundler caches by running `rm -rf node_modules && npm cache clean --force && npm install && watchman watch-del-all && rm -rf $TMPDIR/haste-map-* && rm -rf $TMPDIR/metro-cache && npx expo start --clear`
    * 如果你使用 npm，命令可以找到 [这里。](clear-cache-macos-linux)
      ¥Commands if you are using npm can be found [here.](clear-cache-macos-linux)
    * 如果你使用的是 Windows，则可以找到命令 [这里。](clear-cache-windows)
      ¥Commands if you are using Windows can be found [here.](clear-cache-windows)
  * 如果这是一个裸 React Native 项目，请运行 `npx pod-install`，然后重建你的原生项目（运行 `yarn android` 为 Android 重建，运行 `yarn ios` 为 iOS 重建）
    ¥If this is a bare React Native project, run `npx pod-install`, then rebuild your native projects (run `yarn android` to rebuild for Android, and `yarn ios` to rebuild iOS)


## 代理故障排除

了解如何使用一组推荐的工具对代理进行故障排除。

<a id="macos-proxy-configuration-sierra"></a>
## macOS 代理配置 (Sierra)
¥macOS proxy configuration (Sierra)
> 如果出现任何问题，你可以使用自动代理配置 `your-corporate-proxy-uri:port-number/proxy.pac` 恢复到系统网络首选项中的 "自动代理设置"。
>
> ¥If anything goes wrong, you can revert to the "Automatic Proxy settings" in System Network Preferences using Automatic Proxy Configuration `your-corporate-proxy-uri:port-number/proxy.pac`.
<a id="overview"></a>
### 概述
¥Overview
要在公司 Wi-Fi 网络上在本地 iOS 模拟器中运行此操作，需要本地代理管理器。你可以使用本地代理应用，例如 [Charles](http://charlesproxy.com)。
¥To run this in the local iOS Simulator while on your corporate Wi-Fi network, a local proxy manager is required. You can use a local proxy application such as [Charles](http://charlesproxy.com).
<a id="open-macos-network-preferences"></a>
#### 打开 macOS 网络偏好设置
¥Open macOS network preferences
1. 打开 Mac 的 `System Preferences`（Apple 菜单 > 系统偏好设置）。
   ¥Open `System Preferences` for your Mac (Apple Menu > System Preferences).
2. 转到网络。
   ¥Go to Network.
3. 确保你的 `Location` 设置为你的代理网络，而不是 "自动的"。
   ¥Be sure your `Location` is set to your proxy network, and not "Automatic".
4. 在左侧选择 Wi-Fi 和/或以太网连接后，单击窗口右下角的 `Advanced...`。
   ¥With Wi-Fi selected on the left and/or ethernet connection, click `Advanced...` on the bottom right side of the window.
<a id="configure-proxy-address"></a>
#### 配置代理地址
¥Configure proxy address
1. 如果已设置，则禁用/取消选中 "自动代理配置"。
   ¥Disable/uncheck "Automatic Proxy Configuration" if it is set.
2. 检查 "网络代理 (HTTP)" 并将 "网络代理服务器" 设置为 127.0.0.1 : 8888
   ¥Check "Web Proxy (HTTP)" and set "Web Proxy Server" to 127.0.0.1 : 8888
3. 检查 "安全网络代理 (HTTPS)" 并将 "安全网络代理服务器" 设置为 127.0.0.1 : 8888
   ¥Check "Secure Web Proxy (HTTPS)" and set "Secure Web Proxy Server" to 127.0.0.1 : 8888
<a id="configure-charles"></a>
### 配置 `Charles`
¥Configure `Charles`
1. 打开查尔斯
   ¥Open Charles
2. 如果它询问，请不要允许它管理你的 macOS 网络配置，前面的步骤就是这样做的。（如果更改 Charles 端口，请将上一步更新为正确的端口，而不是默认的 8888）
   ¥If it asks, don't allow it to manage your macOS Network Configuration, the previous steps do that. (If you change Charles port, update the previous step to the correct port instead of default 8888)
3. 在 Charles 的菜单中转到 `Proxy > External Proxy Settings`，选中 `Use external proxy servers`
   ¥In the menu of Charles go to `Proxy > External Proxy Settings`, check `Use external proxy servers`
4. 勾选 `Web Proxy (HTTP)`，然后输入 `your-corporate-proxy-uri:port-number`
   ¥Check `Web Proxy (HTTP)`, and enter `your-corporate-proxy-uri:port-number`
5. 检查 `Proxy server requires a password`
   ¥Check `Proxy server requires a password`
6. 字段：你的域名、用户名：你的用户名密码：你的密码
   ¥Domain: YOUR DOMAIN,
   Username: YOUR USERNAME
   Password: YOUR PASSWORD
7. 安全 Web 代理 (HTTPS) 也是如此。请务必填写相同的代理、用户名和密码地址字段。
   ¥Same for Secure Web Proxy (HTTPS). *Be sure to fill in the same proxy, username, and password address* fields.
8. 在 `Bypass external proxies for the following hosts:` 的文本区域中输入：
   ¥In the text area for `Bypass external proxies for the following hosts:` enter:
```text
   localhost
   *.local
   ```
你可能需要包含你的邮件服务器或其他公司网络地址。
¥You may need to include your mail server or other corporate network addresses.
9. 检查 "始终绕过本地主机的外部代理"
   ¥Check "Always bypass external proxies for localhost"
<a id="ios-simulator-configuration"></a>
### iOS 模拟器配置
¥iOS Simulator configuration
如果你现有的 iOS 模拟器自定义设置无法正常工作，请从菜单中选择 "模拟器 > 重置内容和设置"。
¥If you have an existing iOS Simulator custom setup going that is not working, "Simulator > Reset Content and Settings" from the menu.
如果模拟器仍处于打开状态，请退出它。
¥If you have the Simulator open still, quit it.
现在，在 Charles 中的 "帮助" 菜单下 > 安装 Charles 根证书，然后再次在 iOS 模拟器中安装 Charles 根证书
¥Now, in Charles under the "Help" menu > Install Charles Root Certificate, and then again for Install Charles Root Certificate in iOS Simulators
> 技术说明：这整个过程是必需的，因为 iOS 模拟器提供的是一个临时代理证书而不是实际证书，并且不允许它，对于运行 Expo 所需的 [https://exp.host/](https://exp.host/)。 另请注意：配置需要互联网访问的应用（例如 Spotify）以使用 [http://localhost:8888](http://localhost:8888) 作为代理。某些应用（例如 Chrome 和 Firefox），你可以在设置中配置为使用 "系统网络偏好设置"，该 "系统网络偏好设置" 将使用 Charles : 8888，或不使用代理，具体取决于你在 Apple 菜单/网络首选项中设置 "定位" 的方式。如果设置为 "自动的"，则不使用代理；如果设置为 "你的代理网络"，则使用代理，并且需要运行 Charles。
>
> ¥**Technical note:** This whole process is required because the iOS Simulator is served a bum proxy certificate instead of the actual certificate, and doesn't allow it, for [https://exp.host/](https://exp.host/) which is required to run Expo.  **Also note:** Configure applications that need internet access, such as Spotify, to use [http://localhost:8888](http://localhost:8888) as your proxy. Some apps, such as Chrome and Firefox, you can configure in the settings to use your "System Network Preferences" which will use Charles : 8888, or no proxy, depending on how you have your "Location" set in the Apple menu/network preferences. If you are set to "Automatic" no proxy is used, if it is set to "your proxy network" the proxy is used and Charles will need to be running.
<a id="command-line-application-proxy-configuration"></a>
## 命令行应用代理配置
¥Command line application proxy configuration
npm、git、Brew、Curl 和任何其他命令行应用也需要代理访问。
¥npm, git, Brew, Curl, and any other command line applications need proxy access too.
<a id="for-npm"></a>
#### 对于 npm
¥For npm
打开 `~/.npmrc` 并设置：
¥Open `~/.npmrc` and set:
```ini .npmrc
http_proxy=http://localhost:8888
https_proxy=http://localhost:8888
```
<a id="for-git"></a>
### 对于 git
¥For git
打开 `~/.gitconfig` 并设置
¥Open `~/.gitconfig` and set
```ini .gitconfig
[http]
  proxy = http://localhost:8888
[https]
  proxy = http://localhost:8888
```
<a id="for-command-line-applications"></a>
### 对于命令行应用
¥For command line applications
根据你的 shell 和配置，打开 `~/.bashrc`、`~/.bash_profile` 或 `~/.zshrc` 或你设置 shell 变量的位置并设置：
¥Depending on your shell, and config, Open `~/.bashrc`, `~/.bash_profile`, or `~/.zshrc` or wherever you set your shell variables and set:
```bash
export HTTP_PROXY="http://localhost:8888"
export http_proxy="http://localhost:8888"
export ALL_PROXY="http://localhost:8888"
export all_proxy="http://localhost:8888"
export HTTPS_PROXY="http://localhost:8888"
export https_proxy="http://localhost:8888"
```
> 如果你将网络位置切换回 "自动的" 以使用 npm 或 git，则需要在要禁用的行之前使用 `#` 注释掉这些行。如果你愿意，也可以使用命令行代理管理器。
>
> ¥If you switch your network location back to "Automatic" to use npm or git, you will need to comment these lines out using a `#` before the line you wish to disable. You could alternatively use a command-line proxy manager if you prefer.


# 监管合规性

## 数据和隐私保护

Expo 提供的数据和隐私保护政策概述。

在 Expo，我们团队的目标是为开发者提供工具和服务，使他们能够创建强大且高质量的应用。我们的重点不是收集大量数据。我们仅收集极少量的数据，以帮助我们就我们的产品和服务做出明智的决策。我们的最终目标是提供卓越的用户体验。
¥At Expo, our team's aim is to provide developers with tools and services that enable them to create robust and high-quality apps. Our focus is not on gathering huge amounts of data. We only collect a minimal amount of data that aids us in making informed decisions about our products and services. Our ultimate goal is to provide excellent user experiences.
至关重要的是，Expo 对其用户收集的数据、收集方式以及收集原因保持透明。随着越来越多的法律、政策和框架的出台来规范公司处理用户数据的方式，这一点尤为重要。作为开发者，你需要了解你使用的工具如何处理终端用户的数据，以确保你遵守行业中的相关法律、框架或准则。
¥It's crucial that Expo is transparent with its users about the data it collects, how it does so, and why. This is particularly important as more laws, policies, and frameworks are being introduced to regulate how companies handle user data. As a developer, you need to be aware of how the tools you use treat your end users' data to ensure that you comply with relevant laws, frameworks, or guidelines in your industry.
为了实现这一目标，我们不仅提供 [隐私政策](https://expo.dev/privacy)（如果你是律师，这最有用），还提供 [隐私说明页面](https://expo.dev/privacy-explained)。此页面准确列出了 Expo 从我们的开发者和你的终端用户那里收集的数据，以及我们收集这些数据的原因。在所有涉及用户数据的场景中，Expo 均符合 GDPR、CCPA 和数据隐私框架。
¥To accomplish this, we provide not only our [privacy policy](https://expo.dev/privacy), (which is most useful if you're a lawyer) and also our [privacy explained page](https://expo.dev/privacy-explained). This page lays out exactly what data Expo collects, both from our developers and your end users, and why we collect it. In all scenarios regarding our users' data, Expo is GDPR-, CCPA-, and Data Privacy Framework-compliant.
了解更多：
¥Find out more about:


## GDPR 合规性和 Expo

了解使用 Expo 构建的应用如何符合 GDPR。

<a id="are-apps-built-with-expo-gdpr-compliant"></a>
## 使用 Expo GDPR 构建的应用是否符合 GDPR 标准？
¥Are apps built with Expo GDPR compliant?
**他们可以！如果你遵循要求，则可以使用 Expo 构建符合 GDPR 的应用。**
¥**They can be! You can build GDPR compliant apps with Expo if you follow the requirements.**
虽然 Expo 确保正确处理和处理开发者数据和终端用户数据，但我们不能保证使用 Expo 构建应用的开发者自己遵循类似的数据隐私实践。
¥While Expo ensures the proper handling and processing of developer data and end-user data, we cannot guarantee that the developers who build apps with Expo follow similar data privacy practices themselves.


## HIPAA 合规性和 Expo

了解使用 Expo 构建的应用如何符合 HIPAA 要求。

<a id="are-apps-built-with-expo-hipaa-compliant"></a>
## 使用 Expo HIPAA 构建的应用是否符合要求？
¥Are apps built with Expo HIPAA compliant?
**他们可以！如果你遵循要求，则可以使用 Expo 构建符合 HIPAA 的应用。**
¥**They can be! You can build HIPAA compliant apps with Expo if you follow the requirements.**
Expo 不收集任何可识别个人身份的健康数据，你可以在 [我们的隐私说明页面](https://expo.dev/privacy-explained) 上查看 Expo 收集的所有数据。话虽这么说，你最终控制着从用户那里收集的数据，因此我们不能保证使用 Expo 构建的所有应用都符合 HIPAA，因为最终这取决于你作为个人应用开发者。但使用 Expo 不应该存在合规问题。
¥Expo doesn't collect any individually identifiable health data, and you can see all the data that Expo collects on [our privacy explained page](https://expo.dev/privacy-explained). That being said, you are ultimately in control of the data you collect from your users, so we cannot guarantee that all apps built with Expo are HIPAA compliant, as in the end, it is up to you as an individual application developer. But there should be no compliance issues with using Expo.