# 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应用服务(EAS)](https://expo.dev/eas)，这套服务在开发流程的每个环节都为Expo框架提供补充支持。
开始使用请访问：


## 创建项目

学习如何创建一个新的Expo项目。

系统要求：
- [Node.js (LTS)](https://nodejs.org/en/)。
- 支持 macOS、Windows（需 Powershell 和 [WSL 2](https://expo.fyi/wsl)）及 Linux 系统。
建议从 `create-expo-app` 生成的默认项目开始。该项目包含示例代码以助您快速入门。
创建新项目请执行以下命令：
```sh
$ npx create-expo-app@latest
```
> 您可以通过添加 [`--template` 选项](/more/create-expo/#--template) 来选择不同的模板。
## 下一步
您已经创建了一个项目。现在是时候设置开发环境，以便您可以开始开发。


## 设置您的环境

学习如何设置您的开发环境，以便开始使用 Expo 构建应用程序。

让我们为在 Android 和 iOS 上运行您的项目设置本地开发环境。
## 您希望在哪里开发？
我们建议使用真实设备进行开发，因为您将能够准确看到用户所看到的内容。
## 您希望如何开发？
Expo Go 是一个快速尝试 Expo 的沙盒环境。开发构建是您自己应用的构建，其中包含 Expo 的开发工具。
---
# Android Emulator Setup

## 设置模拟器
Step 1: 
在 Android Studio 主屏幕上，点击 **More Actions**，然后在下拉菜单中选择 **Virtual Device Manager**。
Step 2: 
点击 **Create device** 按钮。
Step 3: 
在 **Add device** 下，选择您想要模拟的硬件类型。我们建议测试多种设备，但如果您不确定从哪里开始，Pixel 系列中的最新设备可能是一个不错的选择。
Step 4: 
选择要在模拟器上加载的操作系统版本（可能是系统映像之一），并下载该映像（如果需要）。
Step 5: 
更改任何其他设置，然后按 **Finish** 创建模拟器。您现在可以通过在 AVD 管理器窗口中点击播放按钮随时运行此模拟器。


# Android Studio Environment Setup

## 安装 Watchman 和 JDK
<Tab label='macOS'>
#### 先决条件
使用包管理器，例如 [Homebrew](https://brew.sh/)，安装以下依赖项。
#### 安装依赖项
Step 1: 
使用工具如 Homebrew [安装 Watchman](https://facebook.github.io/watchman/docs/install#macos)：
```sh
$ brew install watchman
```
Step 2: 
使用 Homebrew 安装名为 Azul Zulu 的 OpenJDK 发行版。该发行版提供适用于 Apple Silicon 和 Intel Mac 的 JDK。
在终端中运行以下命令：
```sh
$ brew install --cask zulu@17
```
安装 JDK 后，在 **~/.bash_profile**（如果使用 Zsh，请在 **~/.zshrc** 中）添加 `JAVA_HOME` 环境变量：
```bash
export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
```
<Tab label='Windows'>
#### 先决条件
使用包管理器，例如 [Chocolatey](https://chocolatey.org/)，安装以下依赖项。
#### 安装依赖项
安装 [Java SE Development Kit (JDK)](https://openjdk.org/)：
```sh
$ choco install -y microsoft-openjdk17
```
For Linux: 
#### 安装依赖项
Step 1: 
按照 [Watchman 文档中的说明](https://facebook.github.io/watchman/docs/install#linux) 从源代码编译和安装它。
Step 2: 
安装 [Java SE Development Kit (JDK)](https://openjdk.org/)：
您可以从 [AdoptOpenJDK](https://adoptopenjdk.net/) 或您的系统打包程序下载并安装 [OpenJDK@17](http://openjdk.java.net/)。


# Android Studio Setup

## 设置 Android Studio
For macOS: 
Step 1: 
下载并安装 [Android Studio](https://developer.android.com/studio)。
Step 2: 
打开 **Android Studio** 应用程序，您将看到 **SDK Components setup** 屏幕。点击 **Next** 继续安装 Android SDK 和 Android SDK 平台。再次点击 **Next** 验证设置并安装。
Step 3: 
默认情况下，Android Studio 将安装最新版本的 Android SDK。但是，要编译 React Native 应用，需要 Android 15 (`VanillaIceCream`) SDK。
打开 Android Studio，转到 **Settings** &gt; **Languages & Frameworks** &gt; **Android SDK**。在 **SDK Platforms** 选项卡下，在 **Android 15 (`VanillaIceCream`)** 下，选择 **Android SDK 平台 35** 和 **Android 35 的源代码**。
Step 4: 
然后，点击 **SDK Tools** 选项卡，确保您至少安装了一版 **Android SDK Build-Tools** 和 **Android Emulator**。
Step 5: 
复制或记住框中显示的 **Android SDK Location**。
Step 6: 
将以下行添加到您的 **/.zprofile** 或 **~/.zshrc** （如果您使用 bash，则为 **~/.bash_profile** 或 **~/.bashrc**）配置文件中：
```sh
$ export ANDROID_HOME=$HOME/Library/Android/sdk
$ export PATH=$PATH:$ANDROID_HOME/emulator
$ export PATH=$PATH:$ANDROID_HOME/platform-tools
```
Step 7: 
在您当前的 shell 中重新加载路径环境变量：
```sh
$ source $HOME/.zshrc
$ source $HOME/.bashrc
```
Step 8: 
最后，确保您可以从终端运行 `adb`。
Note: 故障排除：Android Studio 未识别 JDK
---
如果 Android Studio 无法识别您通过 homebrew 安装的 JDK，您可以创建一个 Gradle 配置文件以明确设置 Java 路径：
1.  在您的主目录中创建一个 Gradle 属性文件：
    ```sh
$ touch ~/.gradle/gradle.properties
```
2.  将以下行添加到 **gradle.properties** 文件中，用您的实际 Java 安装路径替换路径：
    ```bash gradle.properties
    java.home=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
    ```
3.  如果您的项目目录中已有 `.gradle` 文件夹，请删除它并在 Android Studio 中重新打开项目：
    ```sh
$ rm -rf .gradle
```
这应该解决 Android Studio 无法检测到您 JDK 安装的问题。
---
For Windows: 
Step 1: 
下载 [Android Studio](https://developer.android.com/studio)。
Step 2: 
打开 **Android Studio 安装程序**。在 **Select components to install** 下，选择 Android Studio 和 Android 虚拟设备。然后，点击 **Next**。
Step 3: 
在 Android Studio 安装向导中，选择 **Install Type**，选择 **Standard** 并点击 **Next**。
Step 4: 
Android Studio 安装向导将要求您验证设置，例如 Android SDK 的版本、平台工具等。在您验证后点击 **Next**。
Step 5: 
在下一个窗口中，接受所有可用组件的许可证。
Step 6: 
默认情况下，Android Studio 将安装最新版本的 Android SDK。但是，要编译 React Native 应用，需要 Android 15 (`VanillaIceCream`) SDK。
打开 Android Studio，转到 **Settings** &gt; **Languages & Frameworks** &gt; **Android SDK**。在 **SDK Platforms** 选项卡下，在 **Android 15 (`VanillaIceCream`)** 下，选择 **Android SDK Platform 35** 和 **Sources for Android 35**。
Step 7: 
然后，点击 **SDK Tools** 选项卡，确保您至少安装了一版 **Android SDK Build-Tools** 和 **Android Emulator**。
Step 8: 
工具安装完成后，配置 `ANDROID_HOME` 环境变量。转到 **Windows Control Panel** > **User Accounts** > **User Accounts**（再次）> **Change my environment variables**，点击 **New** 创建新的 `ANDROID_HOME` 用户变量。该变量的值将指向您的 Android SDK 路径：
Note: 如何找到已安装的 SDK 位置？
---
默认情况下，Android SDK 安装在以下位置：
```bash
%LOCALAPPDATA%\Android\Sdk
```
要在 Android Studio 中手动查找 SDK 位置，转到 **Settings** > **Languages & Frameworks** > **Android SDK**。查看 **Android SDK Location** 旁边的地址。
---
Step 9: 
要验证新的环境变量是否已加载，打开 **PowerShell**，并复制粘贴以下命令：
```sh
$ Get-ChildItem -Path Env: 
```
该命令将输出所有用户环境变量。在此列表中，查看是否已添加 `ANDROID_HOME`。
Step 10: 
要将平台工具添加到路径中，转到 **Windows Control Panel** > **User Accounts** > **User Accounts**（再次）> **Change my environment variables** > **Path** > **Edit** > **New**，并将平台工具的路径添加到列表中，如下所示：
Note: 如何找到已安装的平台工具位置
---
默认情况下，平台工具安装在以下位置：
```bash
%LOCALAPPDATA%\Android\Sdk\platform-tools
```
---
Step 11: 
最后，确保您可以从 PowerShell 运行 `adb`。例如，运行 `adb --version` 查看您的系统正在运行哪个版本的 `adb`。


# Xcode Setup

Step 1: 
### 安装 Xcode
打开 Mac App Store，搜索 [Xcode](https://apps.apple.com/us/app/xcode/id497799835)，然后点击 **Install**（如果已经安装，则点击 **Update**）。
Step 2: 
### 安装 Xcode 命令行工具
打开 Xcode，从 Xcode 菜单中选择 **Settings...**（或按 <kbd>cmd ⌘</kbd> + <kbd>,</kbd>）。然后转到 **Locations**，通过在 **Command Line Tools** 下拉菜单中选择最新版本来安装工具。
Step 3: 
### 在 Xcode 中安装 iOS 模拟器
要安装 iOS 模拟器，请打开 **Xcode > Settings... > Components**，在 **Platform Support > iOS ...** 下点击 **Get**。
Step 4: 
### 安装 Watchman
[Watchman](https://facebook.github.io/watchman/docs/install#macos) 是一个监视文件系统变化的工具。安装它将提高性能。你可以通过以下命令安装它：
```sh
$ brew update
$ brew install watchman
```


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

## 使用开发构建设置 Android 设备
<BuildEnvironmentSwitch />
Step 1: 
### 安装 EAS CLI
要构建您的应用程序，您需要安装 EAS CLI。您可以通过在终端中运行以下命令来完成此操作：
```sh
$ npm install -g eas-cli
```
Step 2: 
### 创建 Expo 账户并登录
要构建您的应用程序，您需要创建一个 Expo 账户并登录到 EAS CLI。
1. [注册](https://expo.dev/signup) Expo 账户。
2. 在终端中运行以下命令以登录到 EAS CLI：
   ```sh
$ eas login
```
Step 3: 
### 配置您的项目
运行以下命令以在您的项目中创建 EAS 配置：
```sh
$ eas build:configure
```
Step 4: 
### 创建构建
运行以下命令以创建开发构建：
```sh
$ eas build --platform android --profile development
```
Step 5: 
### 在您的设备上安装开发构建
构建完成后，扫描终端中的二维码或在您的设备上打开链接。点击 **安装** 以下载构建到您的设备上，然后点击 **打开** 进行安装。


# Create a development build for a physical Android device locally

## 设置一个带开发构建的 Android 设备
<BuildEnvironmentSwitch />
<AndroidStudioEnvironmentInstructions />
<AndroidStudioInstructions />
## 在 Android 设备上运行你的应用
Step 1: 
### 安装 expo-dev-client
在你的项目根目录下运行以下命令：
```sh
$ npx expo install expo-dev-client
```
Step 2: 
### 启用 USB 调试
默认情况下，大多数 Android 设备只能从 Google Play 下载并运行应用。你需要在设备上启用 USB 调试，以便在开发期间安装你的应用。
要启用设备上的 USB 调试，你首先需要通过访问 **设置** > **关于手机** > **软件信息**，然后点击底部的 `构建编号` 行七次来启用“开发者选项”菜单。然后，你可以返回 **设置** > **开发者选项** 启用“USB 调试”。
Step 3: 
### 通过 USB 连接你的设备
通过 USB 将你的 Android 设备连接到计算机。
通过在终端中运行 `adb devices` 检查你的设备是否正确连接到 ADB（Android 调试桥）。你应该看到你的设备列在其中，旁边会有 `device` 字样。例如：
```sh
$ adb devices
已连接设备列表
8AHX0T32K	device
```
Step 4: 
### 运行你的应用
从终端运行以下命令：
```sh
$ npx expo run:android
```
> 此命令在构建应用后运行开发服务器。你可以在下一页跳过运行 `npx expo start`。


# Run on a physical Android device with Expo Go

## 设置 Android 设备与 Expo Go
扫描二维码从 Google Play 商店下载应用，或访问 [Google Play 商店](https://play.google.com/store/apps/details?id=host.exp.exponent&referrer=docs) 上的 Expo Go 页面。
<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

## 设置带开发版本的 Android 模拟器
<BuildEnvironmentSwitch />
<AndroidStudioInstructions />
<AndroidEmulatorInstructions />
## 创建开发版本
Step 1: 
### 安装 EAS CLI
要构建您的应用程序，您需要安装 EAS CLI。您可以通过在终端中运行以下命令来完成此操作：
```sh
$ npm install -g eas-cli
```
Step 2: 
### 创建 Expo 账户并登录
要构建您的应用程序，您需要创建一个 Expo 账户并登录到 EAS CLI。
1. [注册](https://expo.dev/signup) 一个 Expo 账户。
2. 在终端中运行以下命令以登录到 EAS CLI：
   ```sh
$ eas login
```
Step 3: 
### 配置您的项目
运行以下命令在项目中创建 EAS 配置：
```sh
$ eas build:configure
```
Step 4: 
### 创建构建
运行以下命令以创建开发版本：
```sh
$ eas build --platform android --profile development
```
Step 5: 
### 在模拟器上安装开发版本
构建完成后，CLI 会提示您自动下载并在 Android 模拟器上安装它。当提示时，按 <kbd>Y</kbd> 以直接在模拟器上安装。
如果您错过了此提示，您可以从终端提供的链接下载构建，并将其拖放到 Android 模拟器上进行安装。


# Create a development build for Android Emulator locally

## 设置一个带有开发构建的安卓模拟器
<BuildEnvironmentSwitch />
<AndroidStudioEnvironmentInstructions />
<AndroidStudioInstructions />
<AndroidEmulatorInstructions />
## 在安卓模拟器上运行您的应用程序
Step 1: 
### 安装 expo-dev-client
在您的项目根目录中运行以下命令：
```sh
$ npx expo install expo-dev-client
```
Step 2: 
从终端运行以下命令：
```sh
$ npx expo run:android
```
> 该命令在构建您的应用后运行开发服务器。您可以跳过下一页的 `npx expo start`。


# Run on Android Emulator with Expo Go

## 使用 Expo Go 设置 Android 模拟器
<AndroidStudioInstructions />
<AndroidEmulatorInstructions />
## 安装 Expo Go
当您在 [开始开发](/get-started/start-developing) 页面上使用 `npx expo start` 启动开发服务器时，按 <kbd>a</kbd> 打开 Android 模拟器。Expo CLI 会自动安装 Expo Go。


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

## 设置带开发构建的 iOS 设备
<BuildEnvironmentSwitch />
Step 1: 
### 注册 Apple 开发者计划
要在您的 iOS 设备上安装开发构建，您需要一个有效的 Apple 开发者计划订阅。 在此注册 [Apple 开发者计划](https://developer.apple.com/programs/)。
Step 2: 
### 安装 EAS CLI
要构建您的应用，您需要安装 EAS CLI。 您可以通过在终端中运行以下命令来完成此操作：
```sh
$ npm install -g eas-cli
```
Step 3: 
### 创建 Expo 账户并登录
接下来，您需要创建一个 Expo 账户并登录到 EAS CLI。
1. [注册](https://expo.dev/signup)一个 Expo 账户。
2. 在终端中运行以下命令以登录 EAS CLI：
   ```sh
$ eas login
```
Step 4: 
### 配置您的项目
运行以下命令在您的项目中创建 EAS 配置：
```sh
$ eas build:configure
```
Step 5: 
### 创建临时配置文件
要在您的 iOS 设备上安装开发构建，您需要创建一个临时配置文件。通过在终端中运行以下命令来创建一个：
```sh
$ eas device:create
```
Step 6: 
### 创建开发构建
运行以下命令以创建开发构建：
```sh
$ eas build --platform ios --profile development
```
Step 7: 
### 在设备上安装开发构建
构建完成后，扫描终端中的二维码，当它在相机应用中出现时，点击 **使用 iTunes 打开**。 或者，在您的设备上打开终端显示的链接。
确认安装后，应用将出现在您设备的应用库中。
Step 8: 
### 打开开发者模式
1. 打开 **设置** > **隐私与安全性**，向下滚动到 **开发者模式** 列表项并进入。
2. 点击开关以启用 **开发者模式**。 完成后，设置会显示警报，提醒您开发者模式会降低设备的安全性。 要继续启用 **开发者模式**，请点击警报中的 **重启** 按钮。
3. 设备重启并解锁后，会显示一个确认您想启用开发者模式的警报。 点击 **开启**，并在提示时输入您的设备密码。
> 或者，如果您在 Mac 上安装了 Xcode，您可以使用它来 [启用 iOS 开发者模式](/guides/ios-developer-mode/#connect-an-ios-device-with-a-mac)。


# Create a development build for a physical iOS device locally

## 设置 iOS 设备以进行开发构建
<BuildEnvironmentSwitch />
## 设置 Xcode 和 Watchman
<XcodeInstructions />
## 配置您的项目
Step 1: 
### 安装 expo-dev-client
在您项目的根目录中运行以下命令：
```sh
$ npx expo install expo-dev-client
```
Step 2: 
### 通过 USB 连接您的设备并启用开发者模式
1. 使用 USB 数据线将您的 iOS 设备连接到您的 Mac。解锁设备并在提示时点击 **信任**。
2. 打开 Xcode。在菜单栏中选择 **窗口** > **设备与模拟器**。您将在 Xcode 中看到一个警告，提示您启用开发者模式。
3. 在您的 iOS 设备上，打开 **设置** > **隐私与安全性**，向下滚动到 **开发者模式** 列表项并导航进入。
4. 点击开关以启用 **开发者模式**。完成后，设置将显示一个警告，提醒您开发者模式会降低设备的安全性。要继续启用 **开发者模式**，请点击警告的 **重新启动** 按钮。
5. 设备重启后，解锁设备时，将显示一个确认您要启用开发者模式的警报。点击 **开启**，并在提示时输入您的设备密码。
Step 3: 
### 在您的设备上运行项目
1. 在根目录中的 **app.json** 文件中添加 `ios.bundleIdentifier`，并设置为唯一值，以便 Xcode 为应用签名步骤生成配置文件。
2. 在您项目的根目录中运行以下命令，并从列表中选择已插入的设备：
```sh
$ npx expo run:ios --device
```
> 此命令在构建应用后运行开发服务器。您可以跳过在下一页运行 `npx expo start`。


# Run on a physical iOS device with Expo Go

## 使用 Expo Go 设置 iOS 设备
扫描二维码从 App Store 下载应用，或访问 [App Store](https://itunes.apple.com/app/apple-store/id982107779) 上的 Expo Go 页面。
<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

## 设置带有开发构建的 iOS 模拟器
<BuildEnvironmentSwitch />
## 设置 Xcode
<XcodeInstructions />
## 创建开发构建
Step 1: 
### 安装 EAS CLI
要构建您的应用，您需要安装 EAS CLI。您可以通过在终端中运行以下命令来完成：
```sh
$ npm install -g eas-cli
```
Step 2: 
### 创建 Expo 账户并登录
接下来，您需要创建一个 Expo 账户并登录到 EAS CLI。
1. [注册](https://expo.dev/signup) 一个 Expo 账户。
2. 在终端中运行以下命令以登录到 EAS CLI：
   ```sh
$ eas login
```
Step 3: 
### 配置您的项目
运行以下命令在您的项目中创建 EAS 配置：
```sh
$ eas build:configure
```
Step 4: 
### 调整您的构建配置文件
要创建一个与模拟器兼容的开发构建，您需要在 **eas.json** 中更新您的构建配置文件，设置 `ios.simulator` 属性为 `true`：
```json eas.json
{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": {
        "simulator": true
      }
    }
  }
}
```
Step 6: 
### 创建开发构建
运行以下命令以创建开发构建：
```sh
$ eas build --platform ios --profile development
```
Step 7: 
### 在您的模拟器上安装开发构建
构建完成后，CLI 将提示您自动下载并在 iOS 模拟器上安装它。当提示时，按 <kbd>Y</kbd> 直接在模拟器上安装。
如果您错过了此提示，您可以从终端提供的链接下载构建，并将其拖放到 iOS 模拟器上进行安装。


# Create a development build for iOS Simulator locally

## 设置一个带有开发构建的 iOS 模拟器
<BuildEnvironmentSwitch />
## 设置 Xcode 和 Watchman
<XcodeInstructions />
## 在 iOS 模拟器上运行你的应用
Step 1: 
### 安装 expo-dev-client
在你项目的根目录下运行以下命令：
```sh
$ npx expo install expo-dev-client
```
Step 2: 
从你的终端运行以下命令：
```sh
$ npx expo run:ios
```
> 此命令在构建你的应用后运行开发服务器。你可以跳过在下一页运行 `npx expo start`。


# Run on iOS Simulator with Expo Go

## 设置 iOS 模拟器与 Expo Go
## 设置 Xcode
<XcodeInstructions />
## 安装 Expo Go
当你在 [开始开发](/get-started/start-developing) 页面使用 `npx expo start` 启动开发服务器时，按 <kbd>i</kbd> 打开 iOS 模拟器。Expo CLI 将自动安装 Expo Go。



## 下一步
您有一个项目和一个开发环境。现在是时候开始开发了。


## 开始开发

对 Expo 项目进行首次修改，即可在设备上实时查看效果。

Step 1: 
## 启动开发服务器
要启动开发服务器，请运行以下命令：
```sh
$ npx expo start
```
Step 2: 
## 在设备上打开应用
运行上述命令后，您将在终端中看到一个二维码。扫描此二维码以在设备上打开应用。
如果您使用的是 Android 模拟器或 iOS 模拟器，可以分别按 <kbd>a</kbd> 或 <kbd>i</kbd> 来打开应用。
Note: 遇到问题？
---
请确保您的计算机和设备在同一 Wi-Fi 网络上。
如果仍然无法正常工作，可能是由于路由器配置问题——这在公共网络中很常见。您可以通过在启动开发服务器时选择 **Tunnel** 连接类型，然后再次扫描二维码来解决此问题。
```sh
$ npx expo start --tunnel
```
> 使用 **Tunnel** 连接类型会使应用的重新加载速度明显慢于 **LAN** 或 **Local**，因此最好在可能的情况下避免使用 Tunnel。如果需要通过其他设备访问您的计算机，您可能希望安装并使用模拟器来加快开发速度。
---
Step 3: 
## 进行首次更改
打开 **app/(tabs)/index.tsx** 文件并进行更改。
```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: 更改未在设备上显示？
---
Expo Go 默认配置为在文件更改时自动重新加载应用，但我们还是要确保检查启用它的步骤，以防某些情况未能正常工作。
- 确保您在 Expo CLI 中启用了 [开发模式](/workflow/development-mode#development-mode)。
- 关闭 Expo 应用并重新打开它。
- 一旦应用再次打开，摇动设备以显示开发者菜单。如果您使用的是模拟器，请按 <kbd>Ctrl</kbd> + <kbd>M</kbd>（Android）或 <kbd>Cmd ⌘</kbd> + <kbd>D</kbd>（iOS）。
- 如果您看到 **启用快速刷新**，请按它。如果您看到 **禁用快速刷新**，请关闭开发者菜单。现在尝试进行另一个更改。
---
---
## 文件结构
下面，您可以熟悉默认项目的文件结构：
<ProjectStructure />
## 功能
默认项目模板具有以下功能：
<TemplateFeatures />


## 下一步

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

以下是继续构建您的应用的下一步操作：
### 重置您的项目
您可以移除样板代码，并以一个新项目重新开始。运行以下命令以重置您的项目：
```sh
$ npm run reset-project
```
此命令会将现有的 **app** 文件夹中的文件移动到 **app-example**，然后创建一个新的 **app** 目录，并生成一个新的 **index.tsx** 文件。
### 开发、审核和部署
通过阅读“开发”部分的文档，学习如何进行开发。你将学会如何创建 [UI 元素](/develop/user-interface/splash-screen-and-app-icon/) 、添加 [单元测试](/develop/unit-testing/) 、集成 [原生模块](/config-plugins/introduction/) ，以及更多内容。
开发完应用后，您可以与团队成员分享以进行[评审](/review/overview) 。
最后，您可以[构建](/deploy/build-project/)并[提交](/deploy/submit-to-app-stores/)您的项目到应用商店。
### 分步指南
如果您需要从头到尾使用 Expo 构建应用的分步指导，请查看[教程](/tutorial/introduction/) 。


# 开发

## 开发工具

概述 Expo 工具和网站，帮助您在项目构建过程中各个方面。

当你使用 Expo 创建新项目时，了解以下重要工具和网站可以帮助你在应用开发过程中更加顺利。本页面将为你概述一系列推荐工具。
## Expo CLI
Expo CLI 是一个开发工具，在你创建新项目时会随着 `expo` 包自动安装。你可以通过使用 `npx`（一个 Node.js 包运行器）来使用它。
它旨在帮助你在应用开发阶段更快地推进。例如，你与 Expo CLI 的第一次交互通常是通过运行命令 `npx expo start` 来启动开发服务器。
以下是你在开发应用时会与 Expo CLI 一起使用的一些常用命令列表：
| 命令                            | 描述                                                                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `npx expo start`                | 启动开发服务器（无论你使用的是开发构建还是 Expo Go）。                                                                                     |
| `npx expo prebuild`             | 使用 [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 已经配置好，此命令将[对你的项目文件进行 lint 检查](/guides/using-eslint/#usage) 。 |
简而言之，Expo CLI 允许你开发、编译、启动你的应用等。更多可用选项和可执行操作请参见 [Expo CLI 参考文档](/more/expo-cli/) 。
## EAS CLI
EAS CLI 用于登录你的 Expo 账号，并通过不同的 EAS 服务（如 Build、Update 或 Submit）编译你的应用。你还可以使用此工具来：
- 将你的应用发布到应用商店
- 创建你的应用的开发、预览或生产版本
- 创建 over-the-air（OTA）更新
- 管理你的应用凭证
- 为 iOS 设备创建临时配置文件
要使用 EAS CLI，您需要在本地机器上全局安装它，运行以下命令：
```sh
$ npm install -g eas-cli
```
您可以在终端窗口中使用 `eas --help` 了解更多可用命令。完整参考请参见 [`eas-cli` npm 页面](https://www.npmjs.com/package/eas-cli) 。
## Expo Doctor
Expo Doctor 是一个用于诊断 Expo 项目问题的命令行工具。要使用它，请在项目的根目录下运行以下命令：
```sh
$ npx expo-doctor
```
此命令会检查并分析你的项目代码库中常见的问题，包括 [应用配置](/workflow/configuration/) 和 **package.json** 文件、依赖兼容性、配置文件以及项目的整体健康状况。检查完成后，Expo Doctor 会输出结果。
如果 Expo Doctor 发现问题，它会提供问题的描述，并给出修复建议或寻求帮助的途径。
默认情况下，Expo Doctor 会根据 [React Native 目录](https://reactnative.directory/)验证你项目的包，并在存在原生目录时检查 app 配置属性是否正确同步。你可以在项目的 **package.json** 文件中配置这些检查。详细信息请参阅 [`reactNativeDirectoryCheck`](/versions/latest/config/package-json/#reactnativedirectorycheck) 和 [`appConfigFieldsNotSyncedCheck`](/versions/latest/config/package-json/#appconfigfieldsnotsynced)。
你也可以使用 `npx expo-doctor --help` 来显示使用信息。
## Orbit
Orbit 是一款适用于 macOS 和 Windows 的应用程序，能够：
- 在实体设备和模拟器上安装并启动来自 EAS 的构建。
- 在 Android 模拟器或 iOS 模拟器上安装并启动来自 EAS 的更新。
- 在 Android 模拟器或 iOS 模拟器上启动 snack 项目。
- 使用本地文件安装和启动应用。Orbit 支持任何 Android **.apk**、iOS Simulator 兼容的 **.app**，或临时签名的应用。
- 在你的 EAS 仪表盘中查看已固定项目列表。
### 安装
For macOS: 
你可以通过 Homebrew 在 macOS 上下载 Orbit，或直接从 [GitHub releases](https://github.com/expo/orbit/releases) 获取。
```sh
$ brew install expo-orbit
```
如果你希望 Orbit 在登录时自动启动，请点击菜单栏中的 Orbit 图标，然后进入 **设置** ，选择 **登录时启动** 选项。
For Windows: 
> **important** Windows 版 Orbit 目前为预览版，仅兼容 x64 和 x86 机器。未来将会支持其他架构。
你可以直接从 [GitHub releases](https://github.com/expo/orbit/releases) 下载 Windows 版 Orbit。
> **info** Orbit 在 macOS 和 Windows 上都依赖于 Android SDK，并且在 macOS 上仅用于设备管理的 `xcrun`，这需要同时设置 [Android Studio](/workflow/android-studio-emulator/) 和 [Xcode](/workflow/ios-simulator/)。
## Expo Tools for VS Code
Expo Tools 是一个 VS Code 扩展，可以提升你在处理应用配置文件时的开发体验。它为应用配置、EAS 配置、商店配置和 Expo Module 配置等文件提供自动补全和智能感知等功能。
你还可以使用 VS Code 内置的调试器来调试你的应用程序，设置断点、检查变量、通过调试控制台执行代码等。关于如何使用此扩展进行调试，请参阅 [使用 VS Code 进行调试](/debugging/tools/#debugging-with-vs-code) 。
## 使用 Snack 和 Expo Go 测试原型
### Snack
Snack 是一个浏览器内的开发环境，工作方式类似于 Expo Go。它是分享代码片段和在不下载任何工具到电脑上的情况下尝试 React Native 的绝佳方式。
要使用它，请访问 [snack.expo.dev](https://snack.expo.dev/)，编辑 **App.js** 中的 `<Text>` 组件，在右侧面板选择一个平台（Android、iOS 或 web），即可实时查看更改效果。
### Expo Go
[Expo Go](https://expo.dev/go) 是一个免费的开源沙盒，用于学习和实验 React Native。它支持 Android 和 iOS。
有关如何使用它的更多信息：
- 点击[此链接](/get-started/set-up-your-environment/?mode=expo-go)前往设置您的环境指南
- 在**您想在哪里进行开发？** 下选择一个平台
- 在**您想如何进行开发？** 下选择 Expo Go
- 按照该指南中描述的说明进行操作
> **注意：** 不建议用于构建和分发生产环境的应用到应用商店。请改用[开发构建](/get-started/set-up-your-environment/?mode=development-build) 。
Note: What if I open a project with an unsupported SDK version?
---
当你在 Expo Go 中运行一个为不受支持的 SDK 版本创建的项目时，你会看到以下错误：
```sh
"Project is incompatible with this version of Expo Go"
```
---
Note: How do I upgrade my project from an unsupported SDK version?
---
“项目与此版本的 Expo Go 不兼容”
为了解决这个问题，建议将你的项目升级到[受支持的 SDK 版本](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version) 。如果你想了解如何操作，请参阅[将项目升级到新的 SDK 版本](#how-do-i-upgrade-my-project-from) 。
---
Note: How do I upgrade my project from an unsupported SDK version?
---
请参阅[升级 Expo SDK 指南](/workflow/upgrading-expo-sdk-walkthrough) ，获取升级到特定 SDK 版本的操作说明。
---
## React Native 目录
当你使用开发构建来创建项目时，任何兼容 React Native 的库都可以在 Expo 项目中使用。
[reactnative.directory](https://reactnative.directory/) 是一个可搜索的 React Native 库数据库。如果你需要的库未包含在 Expo SDK 中，可以使用该目录为你的项目查找兼容的库。


## Expo 与 React Native 应用中的导航

了解在 Expo 和 React Native 项目中集成导航的推荐方法。

核心 React Native 库不包含内置的导航解决方案，因此你可以选择最适合你需求的导航库。对于 Expo 和 React Native 应用，通常是在 [React Navigation](https://reactnavigation.org/) 和 [Expo Router](/router/introduction/) 之间作出选择。
## 为什么 React Native 应用需要导航库
React Native 核心包含基础 UI 组件、触控处理、设备 API 和网络，但不包括存储、摄像头、地图、大多数设备传感器等，以及**导航** ！这些功能旨在由社区库来覆盖。
## React Navigation
React Navigation 是一个基于组件的导航库，在 React Native 生态系统中广泛使用。它让你完全用代码组合栈导航、标签导航和抽屉导航，从而实现复杂的流程、自定义过渡和应用特定的用户体验模式。
该库提供基于平台的外观与流畅的动画与手势，统一的移动端和网页路由、自动深度链接、带静态配置的类型路由，并且高度可定制。
## Expo Router（推荐用于 Expo 项目）
Expo Router 是一个基于文件的路由库，适用于 Expo 和 React Native 项目，且构建在 React Navigation 之上。通过遵循 **app** 目录约定，它将文件转换为路由，并与 Expo 集成，实现 [Expo CLI](/more/expo-cli/) 和打包，无需额外设置。该库还新增了诸如类型化路由、动态路由、开发环境下的懒加载、网页端静态渲染，以及自动深度链接等功能。
使用 `npx create-expo-app@latest` 创建的新 Expo 项目默认包含 Expo Router，因此你可以快速发布跨平台导航，同时在需要时仍然可以访问 React Navigation 的 API。


## 在 Expo 和 React Native 应用中的身份验证

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

身份验证是现代应用中90%到95%的一个关键部分。本指南解释了常见的方法、模式和解决方案，以帮助您在 Expo 应用中实现身份验证。
> **info** **TL;DR**：身份验证很难。如果您想跳过复杂性，请跳到 [身份验证解决方案](/#auth-solutions) 部分，获取即成解决方案。否则，请继续阅读。
实现身份验证不仅仅是编写客户端代码。您需要管理服务器请求、密码流程、第三方提供商（如 Google 或 Apple）、电子邮件处理和 OAuth 标准。这个过程会迅速变得复杂。
身份验证方法有几种类型。一些方法简单有效，而另一些方法提供更好的用户体验，但需要更多的工作。让我们看看最常见的方法以及如何实现它们。
## 导航身份验证流程
首先，让我们从基础知识开始：任何身份验证系统都需要将 **公开屏幕**（如登录或注册）与 **受保护屏幕**（如主页或个人资料）分开。在导航层面，这归结为一个简单的检查：用户是否已认证？
开始时，您可以使用硬编码的布尔值模拟此功能，例如 `isAuthenticated = true`，并围绕此构建导航逻辑。一旦一切正常工作，您可以插入真正的身份验证流程。
Note: 使用 Expo Router
---
Expo Router v5 引入了 [受保护路由](/router/advanced/protected)，它阻止用户在未认证的情况下访问某些屏幕。此功能非常适合客户端导航，并简化您的设置。
如果您使用的是旧版本的 Expo Router，您可以使用 [重定向](/router/advanced/authentication-rewrites)。重定向提供相同的结果，但需要更多的手动配置。为了向后兼容，它们在 Expo Router v5 中仍然受到支持。
Video Tutorial: [Expo Router 受保护路由](https://www.youtube.com/watch?v=zHZjJDTTHJg)
---
Note: 使用 React Navigation
---
如果您使用的是 React Navigation，他们提供了一个有用的 [身份验证流程指南](https://reactnavigation.org/docs/auth-flow/)，该指南解释了如何构建您的导航逻辑。它包含基于用户身份验证状态的 [静态](https://reactnavigation.org/docs/auth-flow/?config=static#how-it-will-work) 和 [动态](https://reactnavigation.org/docs/auth-flow/?config=dynamic#how-it-will-work) 方法的示例。
---
无论是 Expo Router 还是 React Navigation，都为您提供灵活的工具，以基于用户是否已登录实现受保护的导航。
## 电子邮件和密码
电子邮件和密码是为应用添加身份验证时的流行选择。
为了使此流程用户友好，您还需要实现忘记密码和重置密码的功能，以便失去访问权限的用户能够恢复账户。
如果您想要更快的解决方案，几项服务提供内置电子邮件和密码身份验证，包括 [Clerk](/#clerk)、[Supabase](/#supabase)、[Cognito](/#cognito)、[Firebase](/#firebase-auth) 和 [Better Auth](/#better-auth)。其中大多数服务提供慷慨的免费层，但如果您的应用快速增长，评估定价是个好主意。
这些服务的最大优势是易于集成。它们通常提供清晰的文档、入门套件和预构建组件，节省您的时间。
Note: 安全检查清单（OWASP）和应用商店审核陷阱
---
如果您自己构建这个流程，请务必查看 OWASP 的 [身份验证备忘单](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#authentication-cheat-sheet)。它列出了密码长度、加密、恢复、可靠存储等方面的最佳实践。
> **info** 添加电子邮件和密码身份验证通常足以通过 App Store 和 Play Store 审核。您可以先提交包含此方法的应用。如果您包括“使用 Google 登录”，Apple 可能会拒绝您的应用，除非您还支持“使用 Apple 登录”。在 Google Play 上，反向适用同样的规则。
---
## 无密码登录
无密码登录消除了用户创建或记住密码的需要。相反，他们在注册时提供电子邮件地址或手机号码。您的应用随后会向他们的收件箱或设备发送一个 [魔法链接](https://auth0.com/docs/authenticate/passwordless/authentication-methods/email-magic-link#classic-login-flow-with-magic-links) 或 [一次性密码（OTP）](https://en.wikipedia.org/wiki/One-time_password)。这为大多数用户提供了更流畅的体验，并减少了入门时的摩擦。
Note: 魔法链接
---
使用魔法链接，用户收到一封包含将他们重定向回您应用的链接的电子邮件。如果一切正常，会议将被验证和建立。
这里的一个关键细节是 [深层链接](/linking/into-your-app)。由于用户需要离开应用检查电子邮件，因此链接必须打开您的应用并将他们引导到正确的屏幕。如果深层链接失败，则无法验证会议，登录流程将中断。
如果您使用的是 Expo Router，则深层链接会自动处理（在大多数情况下）。您通常不需要配置任何额外的内容来使魔法链接正常工作，这使得此方法更易于采用。有关更多信息，请参阅 [链接到您的应用](/linking/into-your-app)。
[React Navigation](https://reactnavigation.org/) 也支持深层链接，但您需要手动配置。有关更多详细信息，请查看其 [深层链接指南](https://reactnavigation.org/docs/deep-linking/)。
---
Note: 一次性密码（OTP）
---
魔法链接的另一种替代方案是通过电子邮件或短信发送一次性密码。用户无需点击链接，而是复制代码并手动返回应用输入。此操作必须在特定的时间窗口内完成，以便代码不会过期。
这里不涉及深层链接。用户控制着流程，必须自己返回应用。
幸运的是，较新的 Android 和 iOS 版本会自动检测到传入消息中的密码。这使得在键盘上方提供自动填充建议，允许用户通过一次点击输入代码。当这一过程顺利时，体验是无缝的。
---
> **info** 魔法链接和一次性密码都是 Google Play Store 和 Apple App Store 审核的有效身份验证方法。您可以仅使用这些方法之一提交应用并获得批准，甚至在添加社交或 OAuth 登录选项之前。
## OAuth 2.0
要让用户使用 Google、Apple、GitHub 等服务的现有账户登录，您可以使用 OAuth 2.0。
[OAuth 2.0](https://oauth.net/2) 是一种广泛使用的安全协议，允许您的应用访问来自其他服务的用户信息，而无需要处理密码。它让用户可以通过一次点击登录，节省时间，建立信任，并免去管理密码的需要。
> **info** OAuth 流程可能很复杂。如果您正在寻找简单的集成，大多数提供商都提供 SDK 和服务，帮您处理所有事情。您可以在 [身份验证解决方案](#auth-solutions) 部分中了解更多信息。
如果您希望完全控制或想了解 OAuth 的内部工作原理，以下部分将展示如何使用 Expo 自己实现完整的 OAuth 流程。
### OAuth 的工作原理
OAuth 通过引入一个作为安全中介的授权服务器来工作。用户不将密码提供给您的应用，而是通过该服务器登录并批准访问特定数据（例如名称或电子邮件）。然后，服务器发放一个临时代码，您的应用可以用它来交换安全访问令牌。
一旦您了解了这一模式，您就可以将其应用于任何提供商。Google、Apple 或 GitHub 的设置将遵循相同的一般步骤。
### 使用 Expo API 路由的自定义 OAuth
前面的图表显示了 OAuth 流程的高级概述。然而，客户端获得用户的授权授予的首选方法是使用授权服务器作为中介，而这正是您可以使用 Expo API 路由构建的。
以下图表详细说明了这一流程：
Expo 让您可以在应用中直接实现整个 OAuth 流程，使用：
一些提供商提供原生 API，以直接在应用内处理登录流程。Google 在 Android 上提供原生的使用 Google 登录体验。如果您正在寻找原生实现，请参阅 [Google 身份验证指南](/guides/google-authentication)。Apple 提供使用原生底部面板和 iOS 的面部识别的 Apple 登录。请查看 [`expo-apple-authentication`](/versions/latest/sdk/apple-authentication) 参考。
以下设置使您可以全面控制 Android、iOS 和 Web 的登录体验。
Note: 什么是 Expo API 路由？
---
[Expo Router API 路由](/router/reference/api-routes) 允许您在 Expo 应用中直接编写服务器端逻辑。您可以定义处理请求的函数，就像 Express 或 Next.js 后端一样，无需外部服务器。
这使得可以轻松安全地处理身份验证流程中的敏感部分，例如 [授权代码交换](https://www.oauth.com/oauth2-servers/pkce/authorization-code-exchange)，直接在您的应用中进行。由于这些路由在服务器上运行，您可以安全地管理秘密、发行 JWT 和验证令牌。
> **info** 您本质上是在为您自己的应用构建一个轻量级的自定义身份验证服务器，全部使用您的 Expo 项目。
---
Note: 什么是 Expo AuthSession？
---
[Expo AuthSession](/versions/latest/sdk/auth-session) 是一个客户端包，帮助您打开网页浏览器或原生模态以开始 OAuth 登录流程。它处理重定向、解析授权响应，并将用户带回您的应用。
这是启动流程的工具，并在用户授权访问后与您的 API 路由进行交互。有关更多信息，请参阅 [使用 OAuth 或 OpenID 提供者的身份验证](/guides/authentication/)。
---
此设置让您可以：
- 使用 AuthSession 启动登录流程
- 在您的 API 路由中接收身份验证代码
- 安全地交换代码以获取令牌
- 使用您自己的逻辑生成自定义 JWT
- 将该令牌返回给客户端
- 使用 Cookie（Web）或 JWT（原生）存储会话
- 使用 EAS Hosting 立即部署（免费启动）
以下教程涵盖如何在 Android、iOS 和 Web 上实现 OAuth，包括如何创建和验证自定义 JWT、管理会话和保护 API 路由。如果您对这个流程不熟悉，建议从 Google 教程开始。
Video Tutorial: [使用 Expo OAuth 实现 Google 登录](https://www.youtube.com/watch?v=V2YdhR1hVNw)
Video Tutorial: [使用 Expo 实现 Apple 登录](https://www.youtube.com/watch?v=tqxTijhYhp8)
Note: 在 OAuth 后管理会话
---
安全处理 OAuth 流程仅仅是开始。一旦用户通过身份验证，您还需要考虑如何存储、恢复和验证他们的会话。
这包括：
- 在客户端安全地存储会话
- 当应用重新启动时恢复会话
- 保护您的 API 路由，以便只有经过身份验证的用户可以访问
传统上，[Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies#what_cookies_are_used_for) 用于在 Web 上存储会话，而 [JSON Web 令牌（JWT）](https://en.wikipedia.org/wiki/JSON_Web_Token) 在原生应用中很常见。
以上教程准确地展示了如何处理这一点。在从 Google 或 Apple 等提供商接收到 ID 令牌后，您使用 Expo API 路由在服务器上生成自定义 JWT。
这让您全面控制会话，包括：
- 使用各个提供商一致字段结构化有效负载
- 自定义过期时间
- 使用秘密密钥签署令牌，以便您的服务器可以稍后验证
一旦令牌创建：
- 对于 Android 和 iOS 应用，您可以使用 [`expo-secure-store`](/versions/latest/sdk/securestore/) 安全地存储它
- 对于 Web 应用，您可以将其设置为安全 Cookie，以维持会话
在每次请求中，令牌会发送回您的服务器，在那里您验证签名并检查过期。如果一切正常，您可以继续处理请求。
这种会话模型使您的后端保持无状态、可扩展且安全，在各个平台上始终如一地运行。
所有这些都在上述视频教程中涵盖，包括：
- 生成和验证自定义 JWT
- 使用 Secure Store 和 Cookie 处理会话存储
- 使用身份验证逻辑保护 API 路由
---
## 身份验证解决方案
如果您不想从头开始构建完整的身份验证系统，有几项服务提供内置解决方案，并对 Expo 的支持一流。以下是一些最受欢迎的选项：
Note: Better Auth
---
[BetterAuth](https://www.better-auth.com/docs/integrations/expo) 是一个现代的开源身份验证提供商，专为开发人员构建。它与 Expo 的集成十分顺畅，他们提供一份指南，展示如何与 [Expo API 路由](https://www.better-auth.com/docs/integrations/expo) 一起使用，以便进行全面控制。它可以很好地与任何提供商合作，并且容易与 EAS Hosting 部署。
---
Note: Clerk
---
[Clerk](https://clerk.com/expo-authentication) 是一个功能强大的全功能身份验证服务，具有出色的 Expo 支持。它包括电子邮件/密码、密码、魔法链接、OAuth 提供商，甚至是密码钥匙。它们还提供一个原生 Expo 模块，为您处理许多集成。
---
Note: Supabase
---
[Supabase](https://supabase.com/docs/guides/getting-started/tutorials/with-expo-react-native) 提供完整的后端平台，包括一个与任何 OAuth 提供商配合使用的内置身份验证服务。它与 Expo 应用集成良好，并且还支持电子邮件、魔法链接等。
---
Note: Cognito
---
[AWS Cognito](https://medium.com/@juliuscecilia33/aws-cognito-and-react-native-bf23ef7fea23) 是亚马逊管理用户池和身份的解决方案。它与其他 AWS 服务无缝连接，并可以通过 AWS Amplify 集成到 Expo 应用中。虽然它需要更多的配置，但它功能强大且可扩展。
---
Note: Firebase Auth
---
[Firebase 身份验证](https://rnfirebase.io/auth/usage) 是谷歌的身份验证平台，支持电子邮件、魔法链接和 OAuth 提供商。它通过 [`react-native-firebase`](https://github.com/invertase/react-native-firebase) 与 React Native 兼容，该库与 Expo 开发构建兼容。
---
## 现代方法
一旦您的身份验证系统运行正常，您可以通过添加可选但强大的增强功能（如生物识别和密码钥匙）来改善用户体验。这些功能为您的登录流程增添了便利、信任和速度。
Note: 生物识别
---
生物识别技术，如 Face ID 和 Touch ID，可用于解锁应用或在有效会话建立后确认身份。这些不是独立的身份验证方法，而是作为一个本地网关，使重新身份验证更快、更安全。
React Native 通过像 [`expo-local-authentication`](/versions/latest/sdk/local-authentication) 或 [`react-native-biometrics`](https://github.com/SelfLender/react-native-biometrics) 等库访问生物识别 API。
---
Note: 密码钥匙
---
[密码钥匙](https://safety.google/authentication/passkey) 是一种新的无密码登录应用和网站的方式。受苹果、谷歌和微软支持，它们利用平台级加密技术和生物识别来无密码认证用户。
密码钥匙提供了无缝和安全的体验，但它要求用户在注册之前已经通过身份验证。如果您不使用负责处理它们的提供商，则还需要额外配置。
- React Native 密码钥匙支持：[`react-native-passkeys`](https://github.com/peterferguson/react-native-passkeys)
- 与 Clerk 的原生密码钥匙支持：[Clerk Passkeys for Expo](https://clerk.com/docs/references/expo/passkeys)
---
## 建议
本指南涵盖了许多内容，从基本的电子邮件和密码流程到完全自定义的 OAuth 实现、会话管理以及现代方法（如生物识别和密码钥匙）。并非所有内容都需要一次性实施。
在许多情况下，从简单的开始是最佳方法。使用像魔法链接或一次性密码这样的电子邮件认证方法发布应用通常就足够了，可以完成 App Store 审核流程，并开始收集真实用户的反馈。
也就是说，如果您正在构建一个预期从第一天就会有高流量的应用，或需要支持跨平台的登录并且摩擦最小，早期投资于更完整的身份验证流程会有很大差别。这可以帮助您从一开始就改善用户入门、信任和保留。
现代解决方案如 OAuth、生物识别和密码钥匙并不是必需的，但一旦核心系统建立，它们可以是很好的补充。
关键是构建适合您当前需求的身份验证，同时保持足够灵活，以便随着您的产品成长。


## 使用 Jest 的单元测试

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

[Jest](https://jestjs.io) 是最常用的单元测试和快照测试的 JavaScript 测试框架。在本指南中，你将学习如何在你的项目中设置 Jest、编写单元测试、编写快照测试，以及在使用 Jest 与 React Native 时对测试结构的最佳实践。
你还将使用 [`jest-expo`](https://github.com/expo/expo/tree/main/packages/jest-expo) 库，它是一个 Jest 预设，仿制 Expo SDK 的原生部分并处理你在 Expo 项目中所需的大部分配置。
## 安装与配置
创建 Expo 项目后，按以下说明在你的项目中安装和配置 `jest-expo`：
Step 1: 
在你的项目中安装 `jest-expo` 和其他所需的开发依赖。请从项目的根目录运行以下命令：
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
```
> **注：** 如果你的项目不使用 TypeScript，可以跳过安装 `@types/jest`。
Step 2: 
打开 **package.json**，添加一个用于运行测试的脚本，并添加使用 `jest-expo` 基本配置的预设：
```json package.json
{
  "scripts": {
  },
  "jest": {
    "preset": "jest-expo"
  }
}
```
Step 3: 
在 **package.json** 中，添加 `jest-expo` 作为 preset，以便为 Jest 的配置设置一个基础：
```json package.json
{
  "jest": {
    "preset": "jest-expo"
  }
}
```
Note: 使用  的其他配置
---
你可以通过在你的 **package.json** 中配置 [`transformIgnorePatterns`](https://jestjs.io/docs/configuration#transformignorepatterns-arraystring) 来对项目使用的 node_modules 进行转译。该属性接受一个正则表达式模式作为其值：
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 有大量的配置选项，但上述配置应覆盖大部分需求。不过，你始终可以向此模式列表添加更多项。有关更多细节，请参阅 [Configuring Jest](https://jestjs.io/docs/configuration)。
---
## 安装 React Native Testing Library
[React Native Testing Library (`@testing-library/react-native`)](https://callstack.github.io/react-native-testing-library/) 是一个用于测试 React Native 组件的轻量级解决方案。它提供实用函数，并可与 Jest 一起使用。
要安装，请运行以下命令：
For macOS/Linux: 
```sh
$ npx expo install @testing-library/react-native --dev
```
For Windows: 
```sh
$ npx expo install @testing-library/react-native "--" --dev
```
> **warning** **已弃用：** `@testing-library/react-native` 取代了已弃用的 `react-test-renderer`，因为 `react-test-renderer` 不支持 React 19 及以上版本。如果你当前在使用它，请从项目中移除该已弃用的库。有关更多信息，请参阅 React 的文档 [React's documentation for more information](https://react.dev/warnings/react-test-renderer)。
## Unit test
一个单元测试检查代码中最小的单元，通常是一个函数。要编写你的第一个单元测试，请看下面的示例：
Step 1: 
在你项目的 **app** 目录中，创建一个名为 **index.tsx** 的新文件，并添加以下代码来渲染一个简单组件：
```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: 
在你的项目根目录下创建一个 **\_\_tests\_\_** 目录。如果该目录在你的项目中已经存在，请使用现有的目录。然后，创建一个名为 **HomeScreen-test.tsx** 的新文件。`jest-expo` 预设会自定义 Jest 配置，此外还会将扩展名为 **\-test.ts|tsx** 的文件识别为测试文件。
在 **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!');
  });
});
```
在上面的示例中，`getByText` 查询帮助你的测试在应用的用户界面中找到相关元素，并对该元素是否存在进行断言。React Native Testing Library 提供了此查询，每个 [query 变体](https://callstack.github.io/react-native-testing-library/docs/api/queries#query-variant) 在返回类型上有所不同。欲了解更多示例和详细 API 信息，请参阅 React Native Testing Library 的 [Queries API reference](https://callstack.github.io/react-native-testing-library/docs/api/queries)。
Step 3: 
在终端窗口中运行以下命令以执行测试：
```sh
$ npm run test
```
你会看到一个测试通过。
## 结构化你的测试
组织你的测试文件对于让它们更易于维护非常重要。一个常见的模式是创建一个 **\_\_tests\_\_** 目录并将所有测试放在其中。
下面给出一个放在 **components** 目录旁边的测试示例结构：
```
__tests__/
│   └── ThemedText-test.tsx
components/
    ├── ThemedText.tsx
    └── ThemedView.tsx
```
或者，你也可以为项目的不同部分创建多个 **\_\_tests\_\_** 子目录。例如，为 **components** 创建一个单独的测试目录，依此类推：
```
components/
│   ├── ThemedText.tsx
│   └── __tests__/
│       └── ThemedText-test.tsx
utils/
    ├── index.tsx
    └── __tests__/
        └── index-test.tsx
```
一切都关乎偏好，由你来决定如何组织你的项目目录。
## 快照测试
> **info** **注意：** 对于 UI 测试，我们推荐进行端到端测试，而不是快照单元测试。请参阅 [E2E tests with Maestro](/eas/workflows/examples/e2e-tests/) 指南。
一个 [快照测试](https://jestjs.io/docs/en/snapshot-testing) 用来确保 UI 保持一致，特别是当项目使用全局样式且可能在组件之间共享时。
要为 `<HomeScreen />` 添加快照测试，请在 **HomeScreen-test.tsx** 的 `describe()` 中加入以下代码片段：
```tsx HomeScreen-test.tsx
describe('<HomeScreen />', () => {
  test('CustomText renders correctly', () => {
    const tree = render(<CustomText>Some text</CustomText>).toJSON();
    expect(tree).toMatchSnapshot();
  });
});
```
运行 `npm run test` 命令，你将会在 **\_\_tests\_\_\\\_\_snapshots\_\_** 目录看到一个快照被创建，并且有两个测试通过。
## Code coverage 报告
Code coverage 报告可以帮助你了解有多少代码被测试到。若要在你的项目中以 HTML 格式查看代码覆盖率报告，在 **package.json** 中，在 `jest` 下，将 `collectCoverage` 设置为 true，并使用 `collectCoverageFrom` 指定在收集覆盖率时要忽略的文件列表。
```json package.json
"jest": {
  ...
  "collectCoverage": true,
  "collectCoverageFrom": [
    "**/*.{ts,tsx,js,jsx}",
    "!**/coverage/**",
    "!**/node_modules/**",
    "!**/babel.config.js",
    "!**/expo-env.d.ts",
    "!**/.expo/**"
  ]
}
```
运行 `npm run test`。你将看到在你的项目中创建一个 **coverage** 目录。找到 **lcov-report/index.html** 并在浏览器中打开它以查看覆盖率报告。
> 通常，我们不建议将 **index.html** 文件上传到 git。请在 **.gitignore** 文件中添加 `coverage/**/*`，以防止被追踪。
## Jest 流程（可选）
您也可以使用不同的流程来运行测试。下面是一些可尝试的示例脚本：
```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 Options](https://jestjs.io/docs/en/cli)。
## 附加信息


# 用户界面

## 启动画面和应用图标

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

启动画面和应用图标是移动应用的基本元素。它们在用户体验和应用品牌塑造中起着重要作用。本指南将介绍如何创建并将它们添加到你的应用中。
Video Tutorial: [Create an App Icon and Splash Screen](https://www.youtube.com/watch?v=3Bsw8a1BJoQ)
---
## 启动画面
启动画面，也称为启动屏幕，是用户打开应用时看到的第一个界面。在应用加载期间，它会一直显示。你还可以通过使用原生的 [SplashScreen API](/versions/latest/sdk/splash-screen) 来控制启动画面消失的时机。
[`expo-splash-screen`](/versions/latest/sdk/splash-screen) 内置了一个 [配置插件](/config-plugins/introduction) ，可以让你配置启动图标和背景颜色等属性。
> **warning** **不要使用 Expo Go 或开发构建来测试你的启动画面** 。Expo Go 会在启动画面可见时渲染你的应用图标，这可能会影响测试。开发构建包含 `expo-dev-client`，它有自己的启动画面，可能会导致冲突。 **请改用 [预览构建](/build/eas-json/#preview-builds) 或 [生产构建](/build/eas-json/#production-builds)** 。
Step 1: 
### 创建启动画面图标
要创建启动屏幕图标，你可以使用这个 [Figma 模板](https://www.figma.com/community/file/1466490409418563617) 。它为 Android 和 iOS 提供了最基本的图标和启动图片设计。
**推荐：**
- 使用 1024x1024 的图片。
- 使用 **.png** 文件。
- 使用透明背景。
Step 2: 
### 将启动图标导出为 .png 格式
创建启动屏幕图标后，将其导出为 **.png** 格式，并保存到 **assets/images** 目录下。默认情况下，Expo 使用 **splash-icon.png** 作为文件名。如果你决定更改启动屏幕文件的名称，请确保在下一步中使用该名称。
> **注意：** **目前仅支持 .png 图片**作为 Expo 项目中的启动屏幕图标。如果你使用其他图片格式，应用的生产构建将会失败。
Step 3: 
### 配置启动屏幕图标
打开应用配置文件，在 plugins 下设置以下属性：
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-splash-screen",
        {
          "backgroundColor": "#232323",
          "image": "./assets/images/splash-icon.png",
          "dark": {
            "image": "./assets/images/splash-icon-dark.png",
            "backgroundColor": "#000000"
          },
          "imageWidth": 200
        }
      ]
    ]
  }
}
```
要测试您的新启动画面，请为[内部分发](/tutorial/eas/internal-distribution-builds)或生产环境构建您的应用，参阅 [Android](/tutorial/eas/android-production-build/) 和 [iOS](/tutorial/eas/ios-production-build/) 的指南。
Note: 为 Android 和 iOS 分别配置  属性
---
[`expo-splash-screen`](/versions/latest/sdk/splash-screen) 还支持 `android` 和 `ios` 属性，用于为特定平台配置启动屏幕。请参见以下示例：
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-splash-screen",
        {
          "ios": {
            "backgroundColor": "#ffffff",
            "image": "./assets/images/splash-icon.png",
            "resizeMode": "cover"
          },
          "android": {
            "backgroundColor": "#0c7cff",
            "image": "./assets/images/splash-android-icon.png",
            "imageWidth": 150
          }
        }
      ]
    ]
  }
}
```
---
Note: 未使用 prebuild？
---
如果您的应用没有使用 [Expo Prebuild](/workflow/prebuild)（以前称为 _托管工作流_ ）来生成原生的 **android** 和 **ios** 目录，那么应用配置中的更改将不会生效。更多信息请参见 [如何手动自定义配置](https://github.com/expo/expo/tree/main/packages/expo-splash-screen#-installation-in-bare-react-native-projects) 。
---
Note: 故障排除：iOS设备上未显示新启动画面
---
对于 SDK 版本低于 52 的情况，在 iOS 开发构建中，启动屏有时会在不同构建之间保持缓存，这会导致测试新图片变得更加困难。Apple 建议在重新构建前清除 _derived data_ 目录，可以通过运行 Expo CLI 来完成：
```sh
$ npx expo run:ios --no-build-cache
```
请参阅 [Apple 关于测试启动屏幕的指南](https://developer.apple.com/documentation/technotes/tn3118-debugging-your-apps-launch-screen)以获取更多信息。
---
## 应用图标
应用的图标是用户在其设备主屏幕和应用商店中看到的内容。Android 和 iOS 对此有不同且严格的要求。
Step 1: 
### 创建应用图标
要创建应用图标，你可以使用这个 [Figma 模板](https://www.figma.com/community/file/1466490409418563617) 。它为 Android 和 iOS 提供了最基本的图标和启动图片设计。
Step 2: 
### 将图标图片导出为 .png 格式
创建好应用图标后，将其导出为 **.png** 格式，并保存在 **assets/images** 目录下。默认情况下，Expo 使用 **icon.png** 作为文件名。如果你决定使用其他文件名，请确保在下一步中也使用该文件名。
Step 3: 
### 在应用配置中添加图标
打开应用配置，并将本地路径作为 [`icon`](/versions/latest/config/app/#icon) 属性的值，指向你的新应用图标：
```json app.json
{
  "icon": "./assets/images/icon.png"
}
```
Note: Android 与 iOS 的自定义配置技巧
---
#### Android
可以通过使用 [`android.adaptiveIcon`](/versions/latest/config/app/#adaptiveicon) 属性进一步自定义 Android 图标，该属性会覆盖前面提到的两项设置。
Android 自适应图标由两个独立的图层组成——前景图片和背景颜色或图片。这使得操作系统能够将图标遮罩成不同的形状，并支持视觉效果。对于 Android 13 及更高版本，操作系统支持主题应用图标，可根据设备主题使用壁纸和主题来确定颜色。
您提供的设计应遵循 [Android 自适应图标指南](https://developer.android.com/develop/ui/views/launch/icon_design_adaptive) ，用于启动器图标。您还应：
- 使用 **.png** 文件。
- 使用 `android.adaptiveIcon.foregroundImage` 属性来指定前景图片的路径。
- 使用 `android.adaptiveIcon.monochromeImage` 属性来指定单色图片的路径。
- 默认的背景颜色为白色；如需指定其他背景颜色，请使用 `android.adaptiveIcon.backgroundColor` 属性。你也可以使用 `android.adaptiveIcon.backgroundImage` 属性来指定背景图片。请确保其尺寸与前景图片相同。
你可能还需要为不支持自适应图标的旧版 Android 设备提供单独的图标。可以通过 `android.icon` 属性实现。该图标应将前景和背景图层合并为一个。
> 请参阅 [Apple 最佳实践](https://developer.apple.com/design/human-interface-guidelines/app-icons/#Best-practices) ，以确保你的图标看起来专业，例如在不同壁纸上测试图标，并避免在产品字标旁添加文字。请提供至少 512x512 像素的图标。
#### iOS
对于 iOS，您的应用图标应遵循 [Apple 人机界面指南](https://developer.apple.com/design/human-interface-guidelines/app-icons/) 。您可以使用 [Icon Composer](https://developer.apple.com/icon-composer/) 应用来创建您的应用图标。该应用会输出一个 **.icon** 目录，您可以将其添加到项目的 **assets** 目录中。然后，您可以在应用配置中提供该目录的路径。暗黑模式的支持已在 Icon Composer 中处理，因此使用此方法时无需提供变体。
> **info** **注意：** 通过 `ios.icon` 提供 Icon Composer 的 **.icon** 目录在 **SDK 54** 及更高版本中受支持。
```json app.json
{
  "expo": {
    "ios": {
      "icon": "./assets/app.icon"
    }
  }
}
```
另外，之前提供图片的方式仍然受支持。你应该：
- 使用 **.png** 文件。
- 1024x1024 是一个不错的尺寸。如果你是使用 `npx create-expo-app` 创建的 Expo 项目，[EAS Build](/build/setup/) 会为你生成其他尺寸的图标。如果是裸 React Native 项目，则需要你自行生成图标。EAS Build 生成的最大尺寸为 1024x1024。
- 图标必须是完全正方形的。例如，1023x1024 的图标是无效的。
- 请确保图标填满整个正方形，没有圆角或其他透明像素。操作系统会在适当的时候自动为你的图标添加遮罩。
- 可以使用 `ios.icon` 为不同的系统外观（例如深色和有色）指定不同的图标。如果指定了该项，将会覆盖应用配置文件中的顶级 icon 键。请参见下面的示例：
```json app.json
{
  "expo": {
    "ios": {
      "icon": {
        "dark": "./assets/images/ios-dark.png",
        "light": "./assets/images/ios-light.png",
        "tinted": "./assets/images/ios-tinted.png"
      }
    }
  }
}
```
---


## 安全区域

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

创建安全区域可以确保你的应用屏幕内容被正确地定位。这意味着内容不会被刘海、状态栏、主屏指示器以及其他设备物理硬件或操作系统控制的界面元素覆盖。当内容被覆盖时，会被这些界面元素遮挡。
以下是应用屏幕内容被 Android 状态栏遮挡的示例。在 iOS 上，相同的内容会被圆角、刘海和状态栏遮挡。
## 使用 `react-native-safe-area-context` 库
[`react-native-safe-area-context`](https://github.com/AppAndFlow/react-native-safe-area-context) 提供了一个灵活的 API，用于处理 Android 和 iOS 设备的安全区域内边距。它还提供了一个 `SafeAreaView` 组件，你可以用它来替代 [`<View>`](https://reactnative.dev/docs/view)，以便在屏幕组件中自动适配安全区域。
使用该库后，前面示例的结果会发生变化，因为内容会显示在安全区域内，如下所示：
### 安装
如果你是使用 [默认模板](/get-started/create-a-project/) 创建的项目，可以跳过 `react-native-safe-area-context` 的安装。该库作为 Expo Router 库的 peer 依赖被自动安装。否则，请运行以下命令进行安装：
```sh
$ npx expo install react-native-safe-area-context
```
### 用法
你可以直接使用 [`SafeAreaView`](https://appandflow.github.io/react-native-safe-area-context/api/safe-area-view) 来包裹你屏幕组件的内容。它是一个普通的 `<View>`，但会将安全区域的内边距作为额外的 padding 或 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: 使用了不同的Expo模板，但未安装Expo Router？
---
在你的屏幕组件中使用 `SafeAreaView` 之前，需在根组件文件（如 **App.tsx**）中导入并添加 [`SafeAreaProvider`](https://appandflow.github.io/react-native-safe-area-context/api/safe-area-provider)。
```tsx App.tsx
import { SafeAreaProvider } from 'react-native-safe-area-context';
export default function App() {
  return (
    return <SafeAreaProvider>...</SafeAreaProvider>;
  );
}
```
---
## 可选：`useSafeAreaInsets` 钩子
作为 `SafeAreaView` 的替代方案，你可以在屏幕组件中使用 [`useSafeAreaInsets`](https://appandflow.github.io/react-native-safe-area-context/api/use-safe-area-insets) hook。它可以直接访问安全区域的内边距（insets），让你能够根据该 hook 返回的内边距为 `<View>` 的每个边缘添加相应的 padding。
下面的示例使用了 `useSafeAreaInsets` hook。它通过 `insets.top` 为 `<View>` 添加了顶部内边距。
```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>
  );
}
```
该 hook 提供的 insets 对象如下：
```ts
{
  top: number,
  right: number,
  bottom: number,
  left: number
}
```
## 附加信息
### 最小示例
下面是一个最小可用示例，演示如何使用 `useSafeAreaInsets` hook 为视图应用顶部内边距。
#### 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>
  );
}
```
### 与 React Navigation 一起使用
默认情况下，React Navigation 支持安全区域，并将 `react-native-safe-area-context` 作为并列依赖。更多信息请参见 [React Navigation 文档](https://reactnavigation.org/docs/handling-safe-area/) 。
### 与 Web 一起使用
如果你的目标平台是 Web，请按照 [使用部分](#usage) 中的说明设置 `SafeAreaProvider`。如果你在进行服务端渲染（SSR），请参见该库文档中的 [Web SSR 部分](https://appandflow.github.io/react-native-safe-area-context/optimizations#web-ssr) 。


## 系统栏

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

系统栏是位于屏幕边缘的用户界面元素，用于提供基本的设备信息和导航控制。根据移动操作系统的不同，它们包括状态栏（[Android](https://developer.android.com/design/ui/mobile/guides/foundations/system-bars) 和 [iOS](https://developer.apple.com/design/human-interface-guidelines/status-bars)）、标题栏（仅限 [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)）、导航栏（[Android](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）。
这些组件用于显示设备信息，如电池电量、时间、通知提醒，并允许用户在设备界面的任何位置直接与设备交互。例如，应用用户可以下拉状态栏以访问快捷设置和通知，无论当前正在使用哪个应用。
系统栏是移动体验的基础，正确理解如何与它们协作对于开发你的应用程序非常重要。
## 使用安全区域处理重叠
您的应用部分内容可能会绘制在系统栏后面。为了解决这个问题，您需要正确定位应用内容，避免重叠，并确保系统栏中的控件可见。
以下指南将带您了解如何使用 `SafeAreaView` 或钩子为屏幕的每个边缘直接应用内边距。
### Android 上的安全区域与边到边布局
在 Android 上启用 [edge-to-edge](https://expo.dev/blog/edge-to-edge-display-now-streamlined-for-android) 之前，通常会使用半透明的状态栏和导航栏。采用这种方式时，绘制在这些栏后面的内容已经位于其下方，通常不需要考虑安全区域。
现在， [在 Android 上启用 edge-to-edge](https://expo.dev/blog/edge-to-edge-display-now-streamlined-for-android) 后，你需要使用安全区域，以确保内容不会与系统栏重叠。
## 自定义系统栏
系统栏可以根据你的应用设计进行自定义，并在不同场景下提供更好的可见性。在使用 Expo 时，有两个可用的库：`expo-status-bar` 和 `expo-navigation-bar`（仅限 Android）。
### 状态栏配置
状态栏会显示在 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) 方法，在应用运行时控制状态栏的外观：
```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`。它会根据您的应用当前使用的配色方案（浅色或深色模式）自动选择合适的样式。
要控制 `StatusBar` 的可见性，您可以将 [`hidden`](/versions/latest/sdk/status-bar/#hidden) 属性设置为 `true`，或使用 [`setStatusBarHidden`](/versions/latest/sdk/status-bar/#statusbarsetstatusbarhiddenhidden-animation) 方法。
**在 Android 上启用 edge-to-edge 后，`expo-status-bar` 中依赖于不透明状态栏的功能 [将不可用](https://developer.android.com/about/versions/15/behavior-changes-15#edge-to-edge)** 。只能自定义样式和可见性。其他属性将无效并发出警告。
### 导航栏配置（仅限 Android）
在 Android 设备上，导航栏显示在屏幕底部。你可以使用 [`expo-navigation-bar`](/versions/latest/sdk/navigation-bar) 库进行自定义。该库提供了一个 `NavigationBar` 组件，你可以通过 [`setStyle`](/versions/latest/sdk/navigation-bar/#navigationbarsetstylestyle) 方法设置导航栏的样式：
```tsx app/_layout.tsx
import { Platform } from 'react-native';
import * as 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) 方法。
**在 Android 上启用边到边后，依赖不透明导航栏的 `expo-navigation-bar` 功能[将不可用](https://developer.android.com/about/versions/15/behavior-changes-15#edge-to-edge)** 。只能自定义样式和可见性。其他属性将无效并发出警告。


## 字体

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

Android 和 iOS 自带一套平台字体。为了提供一致的用户体验并提升应用的品牌形象，可以使用自定义字体。
本指南介绍了在项目中添加和加载自定义字体的不同方法，并提供与字体相关的额外信息。
## 添加自定义字体
有两种方法可以将自定义字体添加到您的项目中：
- 将字体文件放入本地资产中。例如，将字体文件放在 **assets/fonts** 目录。
- 安装一个 Google Font 包。例如，安装 [`@expo-google-fonts/inter`](https://www.npmjs.com/package/@expo-google-fonts/inter) 包。
### 支持的字体格式
Expo SDK 官方在 Android、iOS 和网页平台上原生支持 OTF 和 TTF 字体格式。如果你的字体是其他字体格式，则需要在项目中进行高级配置以支持该格式。
### 可变字体
可变字体（包括 OTF 和 TTF 的可变字体实现）并非在所有平台上都得到支持。要获得完整的跨平台支持，请使用静态字体。或者，使用诸如 [fontTools](https://fonttools.readthedocs.io/en/latest/varLib/mutator.html) 之类的工具，从可变字体中提取你想要使用的特定轴配置，并将其保存为单独的字体文件。
### 如何在 OTF 与 TTF 之间进行选择
如果你使用的字体同时有 OTF 和 TTF 版本，优先选择 OTF。**.otf** 文件比 **.ttf** 文件小。某些情况下，OTF 在某些上下文中还会有略微更好的渲染效果。
## 使用本地图形字体
将文件复制到你项目的 **assets/fonts** 目录中。
> **info** **assets/fonts** 目录路径是在 React Native 应用中放置字体文件的常见约定。若遵循自定义约定，您也可以将这些文件放在其他位置。
在项目中使用本地字体文件的两种方式：
- 将字体文件嵌入使用 [`expo-font` 配置插件](/versions/latest/sdk/font/#configuration-in-app-config) 。
- 在运行时使用 [`useFonts`](/versions/latest/sdk/font/#usefontsmap) 钩子异步加载字体文件。
### 使用 `expo-font` 配置插件
`expo-font` 配置插件允许在项目的原生代码中嵌入一个或多个字体文件。它对 Android 和 iOS 同时支持 `ttf` 和 `otf`，并且仅在 iOS 上支持 `woff` 和 `woff2`。这是向应用中添加字体的推荐方法，原因如下：
- 字体在设备上应用启动时即可立即可用。
- 应用启动时无需额外的代码来异步加载字体。
- 字体在应用安装的所有设备上都可用，因为它们被捆绑在应用中。
然而，这种方法也有一些局限性：
- 不适用于 Expo Go，因为此方法需要 [创建开发构建](/develop/development-builds/create-a-build/) 。
要在项目中嵌入字体，请按照以下步骤：
Step 1: 
在项目中添加自定义字体文件后，安装 `expo-font` 库。
```sh
$ npx expo install expo-font
```
Step 2: 
将配置插件添加到你的 [应用配置](/versions/latest/config/app/#plugins) 文件中。配置必须包含使用 [`fonts`, `android` 或 `ios`](/versions/latest/sdk/font/#configurable-properties) 属性的字体文件路径，这些属性接收一个或多个字体定义的数组。每个字体文件的路径相对于项目根目录。
下面的示例展示了所有有效的字体指定方式：可以是一个包含 `fontFamily` 和其他属性的对象数组，，也可以是字体文件路径的数组。
对于 Android，您可以指定 `fontFamily`、`weight`，以及可选的 `style`（默认为 `"normal"`），这将把字体嵌入为本地 [XML 资源](https://developer.android.com/develop/ui/views/text-and-emoji/fonts-in-xml) 。如果您仅在数组中提供字体文件路径，文件名将成为 Android 上的字体族名称。iOS 始终从字体文件本身提取字体族名称。
如果你计划仅使用 `fontFamily` 来引用字体，请提供一个字体路径数组（请参见下方的 `FiraSans-MediumItalic.ttf`）并遵循我们在 [文件命名的推荐](#how-to-determine-which-font-family-name-to-use) 。
如果你想使用 `fontFamily`、`weight` 和 `style` 的组合来引用字体，请提供一个对象数组（见下方的 `Inter`）。
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-font",
        {
          "fonts": [
            "./assets/fonts/FiraSans-MediumItalic.ttf"
          ],
          "android": {
            "fonts": [
              {
                "fontFamily": "Inter",
                "fontDefinitions": [
                  {
                    "path": "./assets/fonts/Inter-BoldItalic.ttf",
                    "weight": 700,
                    "style": "italic"
                  },
                  {
                    "path": "./assets/fonts/Inter-Bold.ttf",
                    "weight": 700
                  }
                ]
              }
            ]
          },
          "ios": {
            "fonts": ["./assets/fonts/Inter-Bold.ttf", "./assets/fonts/Inter-BoldItalic.ttf"]
          }
        }
      ]
    ]
  }
}
```
Step 3: 
在使用配置插件嵌入字体后，创建一个 [新的开发构建](/develop/development-builds/create-a-build/) ，并在你的设备、Android 模拟器或 iOS 模拟器上安装。
你可以通过指定 `fontFamily` 样式属性，使用 `<Text>` 字体。下面的示例对应于上面配置中定义的字体。
```tsx
<Text style={{ fontFamily: 'Inter', fontWeight: '700' }}>Inter Bold</Text>
<Text style={{ fontFamily: 'Inter', fontWeight: '700', fontStyle: 'italic' }}>Inter Bold Italic</Text>
<Text style={{ fontFamily: 'FiraSans-MediumItalic' }}>Fira Sans Medium Italic</Text>
```
<ConfigReactNative title="在现有的 React Native 项目中使用此方法？">
- **Android:** 将字体文件复制到 **android/app/src/main/assets/fonts**.
- **iOS：** 请在 Apple Developer 文档中查看 [Adding a Custom Font to Your App](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app)。
</ConfigReactNative>
#### 如何确定要使用的字体族名称
- 如果你按照上面所述将字体作为文件路径数组提供，在 Android 上，文件名（不包含扩展名）将成为字体族名称。在 iOS 上，字体族名称是从字体文件本身读取的。我们建议将字体文件命名为与其 [PostScript name](#what-is-postscript-name-of-a-font) 相同，这样在两个平台上的字体族名称就保持一致。
- 如果你使用对象语法，请提供 "Family Name"。可以在 macOS 的 Font Book 应用、[fontdrop.info](https://fontdrop.info/) 或其他程序中找到。
Note: 字体文件的 PostScript 名称是什么？
---
字体文件的 **PostScript 名称** 是按 Adobe 的 PostScript 标准分配给字体的唯一标识符。它被操作系统和应用程序用于引用该字体。它不是字体的 **显示名称** 。
例如，Inter Black 字体文件的 PostScript 名称是 `Inter-Black`。
_来自 macOS 的 Font Book 应用截图。_
---
### 使用 `useFonts` 钩子
`useFonts` 钩子来自 `expo-font` 库，允许异步加载字体文件。该钩子会跟踪加载状态，并在应用初始化时加载字体。
它可与所有 Expo SDK 版本以及 Expo Go 一起使用。要在使用 `useFonts` 钩子的项目中加载字体，请按照以下步骤：
在项目中添加自定义字体文件后，安装 `expo-font` 和 `expo-splash-screen` 库。
Step 1: 
```sh
$ npx expo install expo-font expo-splash-screen
```
[`expo-splash-screen`](/versions/latest/sdk/splash-screen/) 库提供 `SplashScreen` 组件，您可以使用它在字体加载并就绪之前防止应用渲染。
Step 2: 
在项目中的顶层组件（例如根布局 **app/layout.tsx** 文件）中使用 `useFonts` 钩子映射字体文件：
```tsx app/_layout.tsx
import {useEffect} from 'react';
SplashScreen.preventAutoHideAsync();
export default function RootLayout() {
  const [loaded, error] = useFonts({
    'Inter-Black': require('./assets/fonts/Inter-Black.otf'),
  });
  useEffect(() => {
    if (loaded || error) {
      SplashScreen.hideAsync();
    }
  }, [loaded, error]);
  if (!loaded && !error) {
    return null;
  }
  return (
  )
}
```
Step 3: 
在 React 组件中通过使用 `fontFamily` 样式属性来使用 `<Text>` 的字体：
```tsx
<Text style={{ fontFamily: 'Inter-Black' }}>Inter Black</Text>
```
## 使用 Google Fonts
Expo 对 Google Fonts 列出的所有字体提供一流的支持。它们可以通过 [Google Fonts](https://fonts.google.com/) 使用 [`@expo-google-fonts`](https://github.com/expo/google-fonts) 库获得。使用此库中的任意字体包，您可以快速集成该字体及其变体。
在你的项目中使用 Google Font 的两种方式：
- 使用 [`expo-font` 配置插件](/versions/latest/sdk/font/#configuration-in-appjsonappconfigjs) 将已安装的字体嵌入。
- 在运行时异步地通过 [`useFonts`](/versions/latest/sdk/font/#usefontsmap) 钩子加载已安装的字体。
### 使用 `expo-font` 配置插件
> **注意：** 使用 `expo-font` 配置插件嵌入 Google Fonts，与自行嵌入自定义字体具有相同的好处与限制。有关更多信息，请参见 [使用本地字体文件配合 `expo-font` 配置插件](#with-expo-font-config-plugin) 。
Step 1: 
安装字体包。例如，要使用 Inter Black 字体，请使用下面的命令安装 [`@expo-google-fonts/inter`](https://www.npmjs.com/package/@expo-google-fonts/inter) 包。
```sh
$ npx expo install expo-font @expo-google-fonts/inter
```
Step 2: 
将配置插件添加到你的 [应用配置](/versions/latest/config/app/#plugins) 文件中。该配置必须包含字体文件的路径，通过 [`fonts`](/versions/latest/sdk/font/#configurable-properties) 属性指定，该属性接收一个或多个字体文件的数组。字体文件的路径从 `node_modules` 目录中的字体包中定义。例如，如果你有一个名为 `@expo-google-fonts/inter` 的字体包，那么字体文件的名称是 **Inter_900Black.ttf**。
```json app.json
{
  "plugins": [
    [
      "expo-font",
      {
        "fonts": ["node_modules/@expo-google-fonts/inter/900Black/Inter_900Black.ttf"]
      }
    ]
  ]
}
```
Step 3: 
在使用配置插件嵌入字体后，创建一个 [新的开发构建](/develop/development-builds/create-a-build/) 并将其安装在你的设备、Android 模拟器或 iOS 模拟器上。
在 Android 上，你可以使用字体文件名。例如，`Inter_900Black`。在 iOS 上，使用字体及其重量名称（[PostScript 名称](#what-is-postscript-name-of-a-font) ）。下方示例展示如何使用 [`Platform`](https://reactnative.dev/docs/platform-specific-code#platform-module) 为每个平台选择正确的字体族名称：
```tsx
import { Platform } from 'react-native';
// Inside a React component:
<Text
  style={{
    fontFamily: Platform.select({
      android: 'Inter_900Black',
      ios: 'Inter-Black',
    }),
  }}>
  Inter Black
</Text>
```
### 使用 `useFonts` hook
> **注意：** 使用 `useFonts` hook 加载 Google Font 与自行嵌入自定义字体具有相同的优点与限制。有关更多信息，请参阅 [使用本地字体文件与 `useFonts` hook](#with-usefonts-hook)。
每个 google Fonts 包都提供 `useFonts` hook，用以异步加载字体。该 hook 会跟踪加载状态，并在应用初始化时加载字体。该字体包还会导入字体文件，因此你无需显式导入。
Step 1: 
安装 Google Fonts 包、`expo-font` 和 `expo-splash-screen` 库。
```sh
$ npx expo install @expo-google-fonts/inter expo-font expo-splash-screen
```
[`expo-splash-screen`](/versions/latest/sdk/splash-screen/) 库提供了 `SplashScreen` 组件，您可以使用它在字体加载并就绪之前阻止渲染应用。
Step 2: 
安装字体包后，在项目中的顶层组件（例如根布局文件 **app/layout.tsx**）中使用 `useFonts` 钩子映射字体：
```tsx app/_layout.tsx
// Rest of the import statements
import { Inter_900Black, useFonts } from '@expo-google-fonts/inter';
import * as SplashScreen from 'expo-splash-screen';
import {useEffect} from 'react';
SplashScreen.preventAutoHideAsync();
export default function RootLayout() {
  const [loaded, error] = useFonts({
    Inter_900Black,
  });
  useEffect(() => {
    if (loaded || error) {
      SplashScreen.hideAsync();
    }
  }, [loaded, error]);
  if (!loaded && !error) {
    return null;
  }
  return (
  )
}
```
Step 3: 
在 React 组件中使用 `<Text>` 的字体，通过 `fontFamily` 样式属性：
```tsx
<Text style={{ fontFamily: 'Inter_900Black' }}>Inter Black</Text>
```
## 附加信息
### 最小示例
### 超出 OTF 和 TTF
如果你的字体格式不是 OTF 或 TTF，你需要 [自定义 Metro bundler 配置，将其作为额外的资源](/guides/customizing-metro#adding-more-file-extensions-to-assetexts) ，以使其能够工作。在某些情况下，渲染一个平台不支持的字体格式可能会导致应用崩溃。
供参考，以下表格提供在每个原生平台上可使用的列表格式：
| 格式  | 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 /> |
### 平台内置字体
如果你不想通过指定 `fontFamily` 使用自定义字体，系统默认字体将被使用。每个平台都具有一组内置字体。在 Android 上，默认字体是 Roboto。在 iOS 上，是 SF Pro。
平台的默认字体通常易于阅读。然而，当系统默认字体被更改为另一种不易阅读的字体时，也不要感到惊讶。在这种情况下，使用你的自定义字体，这样你就可以对用户看到的内容进行精确控制。
### 处理 `@expo/vector-icons` 的初始加载
当 `@expo/vector-icons` 库的图标首次加载时，它们在你的应用中会以不可见的图标呈现。加载完成后，它们会被缓存，供应用的后续使用。为避免在应用首次加载时显示不可见的图标，可以在初始加载屏幕阶段通过 [`useFonts`](/versions/latest/sdk/font/#usefontsmap) 进行预加载。例如：
```tsx app/_layout.tsx
import { useFonts } from 'expo-font';
import Ionicons from '@expo/vector-icons/Ionicons';
export default function RootLayout() {
  useFonts([require('./assets/fonts/Inter-Black.otf', Ionicons.font)]);
  return (
  )
}
```
现在，您可以在 React 组件中使用 `Ionicons` 库中的任意图标：
```tsx
<Ionicons name="checkmark-circle" size={32} color="green" />
```
### 直接从网络加载远程字体
> **warning** **如果你正在加载远程字体，请确保它们来自一个正确配置 CORS 的源** 。如果你不这样做，远程字体在网页平台上可能无法正确加载。
从本地资源加载字体是应用程序中加载字体的最安全方式。当将字体作为本地资源包含时，在你将应用提交到应用商店后，这些字体会随应用下载打包并可立即使用。你无需担心 CORS 或其他潜在问题。
然而，直接从网页加载字体文件，是通过将 `require('./assets/fonts/FontName.otf')` 替换为下面示例所示的字体 URL 来实现。
#### 使用远程字体
```tsx
import { useFonts } from 'expo-font';
import { Text, View, StyleSheet } from 'react-native';
export default function App() {
  const [loaded, error] = useFonts({
    'Inter-SemiBoldItalic': 'https://rsms.me/inter/font-files/Inter-SemiBoldItalic.otf?v=3.12',
  });
  if (!loaded || !error) {
    return null;
  }
  return (
    <View style={styles.container}>
      <Text style={{ fontFamily: 'Inter-SemiBoldItalic', fontSize: 30 }}>Inter SemiBoldItalic</Text>
      <Text style={{ fontSize: 30 }}>Platform Default</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```


## 资产

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

一个 **静态资源** 是与应用程序二进制文件（本地二进制）打包在一起的文件。此文件类型不属于包含应用程序代码的 JavaScript 包。常见的静态资源类型包括图片、视频、声音、用于 SQLite 的数据库文件以及字体。这些资源可以从你的项目本地提供，或者通过网络远程提供服务。
本地加载并使用静态资源的不同方式，以及关于如何优化和压缩资源的附加信息。
## 本地提供资源（Serve an asset locally）
当资产存储在项目的文件系统中时，它可以在构建时嵌入到应用二进制中，或在运行时加载。你可以像 JavaScript 模块一样通过 `require` 或 `import` 语句来导入它。
例如，要在 **App.js** 中渲染名为 **example.png** 的图片，可以使用 `require` 从项目的 **assets/images** 目录导入图片，并将其传递给 `<Image>` 组件：
```tsx app/index.tsx
<Image source={require('./assets/images/example.png')} />
```
在上面的示例中，打包工具会读取所导入图片的元数据并自动提供宽度和高度。有关更多信息，请参阅 [Static Image Resources](https://reactnative.dev/docs/images#static-image-resources).
类似于本地资源的 `expo-image` 和 `expo-file-system` 的库，与 `<Image>` 组件的工作方式类似。
### 资产如何本地提供
本地存储的资产在开发时通过 HTTP 提供。对于生产应用，它们会在构建时自动捆绑到你的应用二进制中，并在设备上从磁盘提供。
### 在构建时通过 `expo-asset` 配置插件加载资源
要在构建时加载资产，可以使用来自 `expo-asset` 库的 [config plugin](/versions/latest/sdk/asset/#example-appjson-with-config-plugin)。该插件会将资产文件嵌入到你的本地项目中。
Step 1: 
安装 `expo-asset` 库。
```sh
$ npx expo install expo-asset
```
Step 2: 
将 config plugin 添加到你项目的 [app config](/versions/latest/config/app/#plugins) 文件中。配置必须包含使用 [`assets`](/versions/latest/sdk/asset/#configurable-properties) 属性指向资产文件的路径，该属性接受一个或多个要链接到本地项目的文件或目录的数组。
每个资产文件的路径必须相对于你项目的根目录，因为应用配置文件位于项目的根目录中。
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-asset",
        {
          "assets": ["./assets/images/example.png"]
        }
      ]
    ]
  }
}
```
Step 3: 
在使用配置插件内嵌资产后， [创建一个新的开发构建](/develop/development-builds/create-a-build/) 。现在，您可以在项目中导入并使用该资产，而不需要使用 `require` 或 `import` 语句。
例如，上面的配置插件链接了 **example.png**。你可以直接将其导入到你的组件中，并将其资源名称作为 URI 使用。注意，在不使用 `require` 渲染资源时，需要显式提供宽度 / 高度。
```tsx app/index.tsx
import { Image } from 'expo-image';
export default function HomeScreen() {
  return <Image source={{ uri: 'example' }} style={{ width: 100, height: 100 }} />;
}
```
> **info** 不同的文件格式通过 `expo-asset` 配置插件得到支持。有关这些格式的更多信息，请参阅 [Assets API reference](/versions/latest/sdk/asset/#configurable-properties)。如果你没有看到配置插件支持的文件格式，你可以在运行时使用 [`useAssets`](#load-an-asset-at-runtime-with-useassets-hook) 钩子来加载资源。
### 在运行时使用 `useAssets` 钩子加载资源
`useAssets` 钩子来自 `expo-asset` 库，允许异步加载资源。该钩子会下载并将资源本地存储，资源加载完成后，它会返回该资源的实例列表。
Step 1: 
安装 `expo-asset` 库。
```sh
$ npx expo install expo-asset
```
Step 2: 
在你的屏幕组件中，从 `expo-asset` 库导入 [`useAssets`](/versions/latest/sdk/asset/#useassetsmoduleids) 钩子：
```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;
}
```
## 远程提供资源
当资源是远程提供时，它不会在构建时打包进应用二进制文件中。如果资源托管在远程位置，你可以在项目中使用该资源的 URL。例如，将 URL 传递给 `<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 }} />
  );
}
```
无法保证通过网页 URL 提供的远程图片的可用性，因为可能无法连接到互联网，或资源已被移除。
此外，加载远程资源还需要你提供资源的元数据。在上面的示例中，由于打包工具（bundler）无法检索图片的宽度和高度，因此将这些值明确传递给 `<Image>` 组件。如果不这样做，图片将默认为 0px x 0px。
## 附加信息
### 手动优化方法
#### 图像
您可以使用以下方法压缩图像：
- [`guetzli`](https://github.com/google/guetzli)
- [`pngcrush`](https://pmt.sourceforge.io/pngcrush/)
- [`optipng`](http://optipng.sourceforge.net/)
一些图片优化器是无损的。它们会重新编码你的图片，使其在像素显示上没有任何改变或损失，从而变小。当你需要确保每个像素都保持原样时，无损优化器和像 PNG 这样的无损图片格式是一个不错的选择。
其他图片优化器是有损的。优化后的图片与原始图片不同。通常，有损优化器更高效，因为它们会丢弃会降低文件大小的视觉信息，同时让图片在人眼看来几乎不变。像 `imagemagick` 这样的工具可以使用诸如 [SSIM](https://en.wikipedia.org/wiki/Structural_similarity) 的比较算法来显示两张图片看起来有多相似。对于一个与原始图片相似度超过 95% 的优化图片，实际的文件大小往往远小于原始文件的 95%。
#### 其他资源块
对于 GIF 动图、视频等非代码、非图片资源，是否对这些资源进行优化和最小化取决于你。
> **注意：** GIF 是一种非常低效的格式。现代视频编解码器可以在更高的画质下产生显著更小的文件大小。
### 字体
请参阅 [Add a custom font](/develop/user-interface/fonts/#add-a-custom-font) 获取有关如何将自定义字体添加到您的应用程序的更多信息。


## 颜色主题

了解如何在应用中支持亮色和暗色模式。

应用通常支持明暗两种颜色模式。下面是一个在 Expo 项目中同时支持这两种模式的示例：
## 配置
> **info** 对于 Android 和 iOS 项目，需要额外的配置来支持在明暗模式之间切换。对于 Web，不需要额外的配置。
要配置所支持的外观样式，可以在项目的 [`userInterfaceStyle`](/versions/latest/config/app/#userinterfacestyle) 属性中进行设置，位于 [应用配置（app config）](/versions/latest/config/app) 中。默认情况下，当你使用 [默认模板](/get-started/create-a-project/) 创建新项目时，此属性被设置为 `automatic`。
以下是一个配置示例：
```json app.json
{
  "expo": {
    "userInterfaceStyle": "automatic"
  }
}
```
您也可以通过将 `android.userInterfaceStyle` 或 [`ios.userInterfaceStyle`](/versions/latest/config/app/#userinterfacestyle-1) 设置为首选值来为特定平台配置 `userInterfaceStyle` 属性。
> **info** 如果该属性缺失，应用将默认使用 `light` 样式。
在你创建开发构建时，必须安装 [`expo-system-ui`](/versions/latest/sdk/system-ui/#installation) 以支持 Android 的外观样式。否则，`userInterfaceStyle` 属性将被忽略。
```sh
$ npx expo install expo-system-ui
```
如果项目配置错误且未安装 `expo-system-ui`，在终端中将显示以下警告：
```sh
» android: userInterfaceStyle: Install expo-system-ui in your project to enable this feature.
```
你也可以使用以下命令检查项目是否配置错误：
```sh
$ npx expo config --type introspect
```
Note: 使用裸 React Native 应用？
---
#### Android
确保在你的 `MainActivity`（以及任何希望实现此行为的其他活动）中，以及在 **AndroidManifest.xml** 中，包含 `uiMode` 标志：
```xml
<activity android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode">
```
在 **MainActivity.java** 中实现 `onConfigurationChanged` 方法：
```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
您可以在应用的 **Info.plist** 中通过 [`UIUserInterfaceStyle`](https://developer.apple.com/documentation/bundleresources/information_property_list/uiuserinterfacestyle) 键配置受支持的样式。使用 `Automatic` 以同时支持明亮模式和暗黑模式。
---
### 支持的外观风格
`userInterfaceStyle` 属性支持以下值：
- `automatic`：跟随系统外观设置，并在用户做出任何更改时进行通知。
- `light`：将应用限制为仅支持浅色主题。
- `dark`：将应用限为仅支持暗色主题。
## 检测配色方案
要在你的项目中检测配色方案，请使用 `Appearance` 或 `useColorScheme` 来自 `react-native`：
```tsx app/index.tsx
import { Appearance, useColorScheme } from 'react-native';
```
然后，你可以像下面这样使用 `useColorScheme()` 钩子：
```tsx app/index.tsx
function MyComponent() {
  let colorScheme = useColorScheme();
  if (colorScheme === 'dark') {
    // render some dark thing
  } else {
    // render some light thing
  }
}
```
在某些情况下，您会发现以命令方式获取当前颜色方案非常有用，例如使用 [`Appearance.getColorScheme()`](https://reactnative.dev/docs/appearance)，或通过 `Appearance.addChangeListener()` 监听变化。
## 附加信息
### 最小示例
#### 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',
  },
});
```
### 提示
在开发项目时，您可以通过以下快捷方式来更改模拟器或设备的外观：
- 如果使用 Android 模拟器，您可以运行 `adb shell "cmd uimode night yes"` 来开启深色模式，且 `adb shell "cmd uimode night no"` 来关闭深色模式。
- 如果使用实体 Android 设备或 Android 模拟器，您可以在设备设置中切换系统的深色模式设置。
- 如果在本地使用 iOS 模拟器，您可以使用 Cmd ⌘ + Shift + a 快捷方式在明暗模式之间切换。


## 动画

了解如何集成 React Native 动画并在你的 Expo 项目中使用它。

动画是提升体验、提供更好用户体验的好方法。在你的 Expo 项目中，你可以使用 React Native 的 [Animated API](https://reactnative.dev/docs/next/animations)。然而，如果你想使用更高级的动画、获得更好的性能，可以使用 [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/) 库。它提供了一个简化创建平滑、强大且易维护的动画的 API。
## 安装
如果你使用 [默认模板](/get-started/create-a-project/) 创建了项目，可以跳过安装 `react-native-reanimated`。这个库已经安装好。否则，请通过以下命令安装：
```sh
$ npx expo install react-native-reanimated
```
## 用法
### 最小示例
下面的示例展示如何使用 `react-native-reanimated` 库来创建一个简单动画。有关 API 和高级用法的更多信息，请参阅 [`react-native-reanimated` 文档](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/your-first-animation) 。
#### 使用 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,
  },
});
```
## 其他动画库
你可以在你的 Expo 项目中使用其他动画包，例如 [Moti](https://moti.fyi/)。它在 Android、iOS 和网页上都能工作。


## 存储数据

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

存储数据对于你移动应用中实现的功能可能至关重要。根据你要存储的数据类型以及应用的安全性要求，在你的 Expo 项目中有不同的保存数据方式。本页列出多种库，帮助你决定哪种解决方案最适合你的项目。
## Expo SecureStore
`expo-secure-store` 提供了一种在设备本地对键值对进行加密并安全存储的方法。
## Expo FileSystem
`expo-file-system` 提供对设备本地存储的文件系统的访问。在 Expo Go 中，每个项目都有独立的文件系统，且无法访问其他 Expo 项目的文件。不过，它可以将其他项目共享的内容保存到本地文件系统，并与其他项目共享本地文件。它也能够从网络 URL 上传和下载文件。
## Expo SQLite
`expo-sqlite` 包让您的应用能够访问一个可以通过类似 WebSQL 的 API 进行查询的数据库。该数据库在应用重新启动后仍然持久化。你可以用它来导入现有数据库、打开数据库、创建表、插入项、查询并显示结果，以及使用预处理语句。
## Async Storage
[Async Storage](https://react-native-async-storage.github.io/async-storage/) 是一个用于 React Native 应用的异步、未加密、持久化的键值存储。它有一个简单的 API，是存储少量数据的好选择。对于不需要加密的数据（如用户偏好或应用状态）也是一个不错的选择。
## 其他库
还有用于存储不同用途数据的其他库。例如，你的项目可能不需要加密，或你在寻找一个类似于 Async Storage 的更快的解决方案。
我们建议查看 [React Native for a list of libraries](https://reactnative.directory/?search=storage) 以帮助您存储项目的数据。


## 下一步

了解如何在应用中实现导航和 UI 的更多有用资源清单。

# 开发构建

## 开发构建简介

为什么使用开发构建以及如何入门。

**开发构建** 是我们用来表示应用程序的“调试”构建的术语，该构建包含 [`expo-dev-client`](/versions/latest/sdk/dev-client/) 库。该库在内置的 React Native 开发工具基础上增加了额外的功能，例如支持检查网络请求以及一个“启动器”界面，允许你在不同的开发服务器之间切换（例如在你本机的服务器与队友的服务器之间）以及应用程序的部署版本（如通过 EAS Update 发布的更新）。
Note: Expo Go 与开发版本的差异
---
当你使用 `npx create-expo-app` 创建第一个 React Native 项目并使用 `npx expo start` 运行时，你很可能会先使用用于开发的 [Expo Go](https://expo.dev/go) 应用进行开发。Expo Go 是 Expo 团队开发并提交到 [Google Play Store](https://play.google.com/store/apps/details?id=host.exp.exponent) 和 [Apple App Store](https://apps.apple.com/us/app/expo-go/id982107779) 的原生应用，方便你快速开始编码。它是一个沙盒应用，内置了大量原生库（请参阅 [dependencies list](https://github.com/expo/expo/blob/main/apps/expo-go/package.json#L23)）。这意味着开发者可以在本地机器上更新应用的 JavaScript 代码，并在 Expo Go 上看到更改。
一个 React Native 应用由两部分组成： **原生应用程序（Expo Go）** 和 **JavaScript 包（`npx expo start`）**。它是不可变的，当你在开发中使用 Expo Go 应用时，你只能依赖 Expo Go 中存在的原生代码和工具。唯一的解决办法是自行构建原生应用程序，而不是使用 Expo 的预打包沙盒。这正是 **Development Build 的含义，即你自己的 Expo Go 版本** ，你可以自由使用任意原生库并修改任意原生配置。
---
Note: 本机应用与 JavaScript 包
---
**本地应用程序（ Expo Go ）** 一旦安装即不可变。需要原生构建工具来创建此打包，并且需要进行签名才能在真实设备上安装。要添加具有原生代码的新库或更改随应用程序打包的元数据（例如应用名称、图标、启动画面），需要重新构建并在设备上重新安装应用。
**JavaScript 打包（`npx expo start`）** 是您应用的 UI 代码和业务逻辑所在。在生产应用中，随应用本身一起打包的是一个 **main.js** 打包。在开发阶段，这个 JS 打包会从本地机器进行热更新。React Native 的主要作用是为 JavaScript 代码提供访问原生 API（Image、Camera、Notifications 等）的方式。然而，只有在**本地应用**中打包的 API 和库才能使用。
---
Video Tutorial: [Expo Go 与 Development Builds：应该使用哪一个？](https://www.youtube.com/watch?v=FdjczjkwQKE)
## 为何要使用开发构建（也就是说 _在 Expo Go 中不能做的事_ ，以及原因）
Expo Go 是学习、原型设计和试验的完美工具，但大多数生产应用迟早会转向使用开发构建版本。了解在 Expo Go 中什么是*不可能*实现以及*原因* ，会帮助你在何时以及为何进行这一步迁移时做出明智决定。
Note: 使用本地代码库但不在 Expo Go 中
---
以 [`react-native-webview`](/versions/latest/sdk/webview/) 为例，它是一个包含原生代码的库，但 [被包含在 Expo Go 中](https://github.com/expo/expo/blob/main/apps/expo-go/package.json#L23)。当你在你的项目中运行 `npx expo install react-native-webview` 命令时，它会把该库安装到你的 **node_modules** 目录中，其中既有 JS 代码也有原生代码。但是你正在构建的 JS 代码块 _仅_ 使用 JS 代码。接着，你的 JS 代码块会被上传到 Expo Go，并与已随应用打包的原生代码进行交互。
相反，当你尝试使用未包含的库时，例如 [`react-native-firebase`](/guides/using-firebase/#using-react-native-firebase)，你可以使用 JS 代码并热重载新 bundle 到 Expo Go，但它会立即报错，因为 JS 代码试图调用 React Native Firebase 包中在 Expo Go 中不存在的原生代码。除非已经包含在上传到应用商店的 bundle 中，否则无法将原生代码集成到 Expo Go 应用中。
---
Note: 测试应用图标、名称、启动画面的更改
---
如果你仅在 Expo Go 中开发应用，你可以构建一个商店版本，该版本将使用你提供的值和图片；只是无法在 Expo Go 中进行测试。
这些原生资源与原生 bundle 一起打包，一旦应用安装就不可变。Expo Go 应用确实会显示启动画面，即你的应用图标在纯色背景上。这是一种开发专用的模拟，用于查看启动画面大致会呈现的效果。然而，它是有限制的，例如你不能测试 `SplashScreen.setOptions` 来为启动画面做动画。
---
Note: 远程推送通知
---
虽然 [in-app notifications](/versions/latest/sdk/notifications/) 在 Expo Go 中可用，但远程推送通知（即从服务器向应用发送的推送通知）不可用。这是因为推送通知服务应绑定到你自己的推送通知证书，虽然在 Expo Go 中让它工作是可能的，但在生产构建中常常会带来混淆。建议在开发构建中测试远程推送通知，以确保开发和生产之间的行为一致性。
---
Note: 实现 App/通用链接
---
两者 [Android App Links](/linking/android-app-links/) 和 [iOS Universal Links](/linking/ios-universal-links/) 需要本地应用与网站之间建立双向关联。具体而言，要求本地应用中包含被链接网站的 URL。由于上述原生代码不可变，这在 Expo Go 中是不可实现的。
---
Note: 使用较旧的 SDK 打开的项目（仅 iOS 设备）
---
Expo Go 只能同时支持一个 SDK 版本。当发布新的 SDK 版本时，Expo Go 会更新以支持较新的版本，这将是商店中可安装的唯一 Expo Go 版本。
如果你在 Android 设备、Android 模拟器或 iOS 模拟器上进行开发，兼容版本的 Expo Go 可以 [下载安装](https://expo.dev/go) 。唯一不可能的平台是 iPhone 设备，因为苹果不支持侧加载旧版本应用。
---


## 从 Expo Go 转换为开发构建

如何将你的 Expo Go 项目迁移以使用开发构建。

要从 Expo Go 迁移到开发构建，您需要按照以下步骤进行：
Step 1: 
## 安装 `expo-dev-client`
Expo Dev Client 库包含启动器 UI（如下图所示）、开发菜单、用于测试 OTA 更新的扩展等。Expo Go 应用内置了开发菜单，这也是为什么您需要单独为开发构建安装它。
```sh
$ npx expo install expo-dev-client
```
> 我们建议使用 `expo-dev-client` 以获得最佳开发体验，但也可以在不安装此库的情况下使用开发构建。如果不使用开发客户端，在 [Step 3](/develop/development-builds/expo-go-to-dev-build/#start-the-dev-client) 中，请使用 `--dev-client` 启动 bundler。否则，它将默认在 Expo Go 中打开。
Step 2: 
## 构建您的原生应用
使用 Expo Go 时，只需要构建 JavaScript bundle，但在开发构建中你还需要编译原生应用。使用 Expo 构建原生应用分为两部分：
1. 生成原生的 **android** 和/或 **ios** 目录（[read more](/develop/development-builds/expo-go-to-dev-build/#cng-and-prebuild) 何时以及如何需要这样做）
2. 使用原生构建工具来编译原生应用程序
一旦你构建了原生应用，除非你添加或更新带有原生代码的库，或更改任何原生代码或配置（如应用名称），否则你不需要再次构建它。
> **android** 和 **ios** 目录在创建新项目时会自动添加到 **.gitignore**，因此它们不会被提交到 Git。这确保您在需要时可以在本地或 CI 上使用 [CNG](/workflow/continuous-native-generation/) 重新生成代码，并且永远不需要手动编辑原生代码。
### 选项 1：在本地机器构建
要在本地机器上构建原生应用，请按照您的环境指南为 [Android](/workflow/android-studio-emulator/) 和 [iOS](/workflow/ios-simulator/) 平台设置。这包括为 Android 设置 Android Studio、为 iOS 设置 Xcode 等原生构建工具的配置。
一旦一切就绪，运行以下命令：
For 为 Android 构建: 
```sh
$ npx expo run:android
```
For 为 iOS 构建: 
```sh
$ npx expo run:ios
```
默认情况下，这将构建并在 Android 模拟器/iOS 模拟器上安装应用。如果你需要在手机上运行构建，请将手机连接到计算机（在 Android 上，选择信任设备并在提示时允许 USB 调试；在 iOS 上，启用 [开发者模式](/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) ），然后使用上面的命令并带上 `--device` 标志。
### 选项 2：在 EAS 上构建
在 EAS 服务器上构建很有用的情景：
- 你不能或不想设置本地开发环境
- 你想构建一个 iOS 应用但没有 Mac
- 你想与团队分享开发构建结果
Step 3: 
## 启动打包程序
本地构建完成后，`npx expo run:android|ios` 将自动启动 bundler。但如果你已经关闭了 bundler，或是在开发客户端上工作，且你之前构建了开发客户端，请使用以下命令（重新）启动 Metro bundler：
```sh
$ npx expo start
```
当你的项目安装了 `expo-dev-client` 时，bundler 会输出 **Using development build**，它显示的二维码将指向你所创建的开发构建，而不是 Expo Go。
## Prebuild
[**Prebuild**](/workflow/continuous-native-generation/#prebuild) 是 Expo 项目特有的一个概念。它指的是根据你本地的配置和属性生成 **android** 和 **ios** 目录的过程。
### 何时应运行 prebuild
如果你通过 `npx expo run:android|ios` 进行构建，并且对任何原生依赖项或配置进行了修改，例如：
- 安装或更新包含本地代码的库
- 更改 [应用程序配置](/workflow/configuration/) （`app.json`）
- 升级你的 Expo SDK 版本
在这些情况下，你需要使用以下命令重新构建本地目录：
```sh
$ npx expo prebuild --clean
```
然后，使用更新后的本地代码重新构建您的应用：
For 为 Android 构建: 
```sh
$ npx expo run:android
```
For 为 iOS 构建: 
```sh
$ npx expo run:ios
```
### 当你不需要运行 prebuild 时
所有 Expo 构建工具（`npx expo run:android|ios` 和 `eas build`）将在未发现现有本地文件夹时自动进行 **prebuild**。这意味着在第一次运行 `npx expo run:android|ios` 或 `eas build` 时，无需手动执行 prebuild。


## 在 EAS 上创建开发构建

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

当你使用 `npx create-expo-app` 创建一个新的 Expo 应用时，你会得到一个项目，在本地机器上更新 JavaScript 代码并在 Expo Go 应用中查看更改。一个 **development build** 本质上是 **你自己版本的 Expo Go**，你可以自由使用任何原生库并修改任何原生配置。在本指南中，你将学习如何将运行在 Expo Go 上的项目转换为 development build，从而使应用的原生端完全可定制。
Video Tutorial: [如何创建开发构建](https://www.youtube.com/watch?v=uQCE9zl3dXU)
## 先决条件
这些说明假设你已经有一个可在 Expo Go 上运行的现有 Expo 项目。
构建原生应用的要求取决于你使用的平台、你要构建的平台，以及你是想在 EAS 上构建还是在本地机器上构建。
Note: 在 EAS 上构建
---
这是构建原生应用的最简单方式，因为它不需要你这边的原生构建工具。这些构建是在 EAS 服务器上完成的，因此可以从非 macOS 平台触发 iOS 构建。
|             | Android    | iOS 模拟器 | iPhone 设备     |
| ----------- | ---------- | ---------- | --------------- |
| **macOS**   | <YesIcon/> | <YesIcon/> | <YesIcon/> (\*) |
| **Windows** | <YesIcon/> | <YesIcon/> | <YesIcon/> (\*) |
| **Linux**   | <YesIcon/> | <YesIcon/> | <YesIcon/> (\*) |
(\*) 所有在 iPhone 设备上运行的构建都需要一个付费的 [Apple Developer](https://developer.apple.com) 账户来进行构建签名。
---
Note: 使用 EAS CLI 在本地构建
---
任何 EAS CLI 命令都可以在本地计算机上使用 `--local` 标志进行构建。这要求您的本地 [开发环境](https://reactnative.dev/docs/set-up-your-environment?os=macos&platform=ios) 已经安装并设置了原生构建工具。了解更多关于 [本地应用开发](/build-reference/local-builds/) 的内容。
|         | Android | iOS 模拟器 | iPhone 设备 |
| ------- | ------- | ---------- | ----------- |
| macOS   |         |            | (\*)        |
| Windows | (\*\*)  |            |             |
| Linux   |         |            |             |
(\*) 运行在 iPhone 设备上的所有构建都需要付费的 [Apple Developer](https://developer.apple.com) 账户用于构建签名。
(\*\*) 虽然没有一等支持，但可以通过 [WSL](http://expo.fyi/wsl.md) 实现。
---
Note: 在本地构建，不依赖 EAS
---
要在本地不使用 EAS 进行构建，需要在本地的 [开发环境](https://reactnative.dev/docs/set-up-your-environment?os=macos&platform=ios) 中设置原生构建工具。这是唯一在没有付费 Apple Developer 账户的情况下，在 iPhone 设备上测试 iOS 构建的方法（仅在 macOS 上可能）。了解更多关于 [本地应用编译](/guides/local-app-development/#local-app-compilation) 的信息，并查看 [Expo Go 到 Development Build](/develop/development-builds/expo-go-to-dev-build/) 指南。
|             | Android    | iOS 模拟器 | iPhone 设备 |
| ----------- | ---------- | ---------- | ----------- |
| **macOS**   | <YesIcon/> | <YesIcon/> | <YesIcon/>  |
| **Windows** | <YesIcon/> | <NoIcon /> | <NoIcon />  |
| **Linux**   | <YesIcon/> | <NoIcon /> | <NoIcon />  |
---
## 开始使用
如需详细的分步说明，请参阅我们的 [EAS Tutorial](/tutorial/eas/introduction)。也可在 YouTube 上作为 [教程系列](https://www.youtube.com/playlist?list=PLsXDmrmFV_AS14tZCBin6m9NIS_VCUKe2)观看。
Step 1: 
### 安装 expo-dev-client
```sh
$ npx expo install expo-dev-client
```
Note: 您是否在现有的（空的）React Native 应用中使用这个库？
---
使用 [Continuous Native Generation](/workflow/continuous-native-generation/) 的应用程序或使用 `npx react-native` 创建的应用，在安装此库后需要进一步配置。请参阅来自 [在现有 React Native 应用中安装 `expo-dev-client`](/bare/install-dev-builds-in-bare/) 的步骤 1 和 2。
---
Step 2: 
### 构建原生应用程序（Android）
<Prerequisites numberOfRequirements={3}>
  <Requirement number={1} title="Expo account">
    如果尚未，请注册一个 [Expo](https://expo.dev/signup) 账户。
  </Requirement>
  <Requirement number={2} title="EAS CLI">
    [EAS CLI](/build/setup/#install-the-latest-eas-cli) 已安装并已登录。
    ```sh
$ npm install -g eas-cli && eas login
```
  </Requirement>
  <Requirement number={3} title="An Android Emulator (optional)">
    如果你想在模拟器上测试应用，可以使用 [Android
    Emulator](/workflow/android-studio-emulator/)，这是可选的。
  </Requirement>
</Prerequisites>
```sh
$ eas build --platform android --profile development
```
了解更多关于 [在 EAS 上进行 Android 构建](/tutorial/eas/android-development-build) 。
Step 2: 
### 构建原生应用（iOS 模拟器）
<Prerequisites numberOfRequirements={3}>
  <Requirement number={1} title="Expo 账户">
    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="安装了 iOS 模拟器的 macOS">
    iOS Simulators are available only on macOS. Make sure you have the [iOS
    Simulator](/workflow/ios-simulator/) installed.
  </Requirement>
</Prerequisites>
在 `development` 配置文件中编辑 **eas.json**，将 [`simulator`](/eas/json/#simulator) 选项设为 `true`（如果你也想为该项目创建 iOS 设备构建，请为模拟器构建创建一个单独的配置文件。）
```json eas.json
{
  "build": {
    "development": {
      "ios": {
        "simulator": true
      }
    }
  }
}
```
```sh
$ eas build --platform ios --profile development
```
iOS 模拟器构建只能安装在模拟器上，不能安装到真实设备。
阅读更多关于 [iOS Simulator builds on EAS](/tutorial/eas/ios-development-build-for-simulators/)。
Step 2: 
### 构建本地应用（iOS 设备）
<Prerequisites numberOfRequirements={3}>
  <Requirement number={1} title="Expo 账户">
    如果还没有，请注册一个 [Expo](https://expo.dev/signup) 账户。
  </Requirement>
  <Requirement number={2} title="EAS CLI">
    [EAS CLI](/build/setup/#install-the-latest-eas-cli) 已安装并已登录。
    ```sh
$ npm install -g eas-cli && eas login
```
  </Requirement>
  <Requirement number={3} title="Apple 开发者账户">
    一个用于创建 [签名] 的付费 [Apple Developer](https://developer.apple.com/) 账户
    凭据](/app-signing/managed-credentials/#generating-app-signing-credentials)
    以便应用程序能够安装到 iOS 设备上。
  </Requirement>
</Prerequisites>
```sh
$ eas build --platform ios --profile development
```
iOS 设备构建只能安装在 iPhone 设备上，不能安装在 iOS 模拟器上。
了解更多关于 [在 EAS 上的 iOS 设备构建](/tutorial/eas/ios-development-build-for-devices/) 。
Step 3: 
### 安装应用
您需要在您的设备、模拟器或仿真器上安装原生应用。
#### 在 EAS 上构建
如果你在 EAS 上进行开发构建，CLI 将在构建完成后提示你安装应用。你也可以从 [expo.dev](https://expo.dev/) 仪表板或使用 [Expo Orbit](https://expo.dev/orbit) 安装先前的构建版本。
#### 使用 EAS CLI 本地构建时
本地构建的输出将是一个归档文件。你可以将其拖放到 Android 模拟器/ iOS 模拟器上进行安装，或使用 [Expo Orbit](https://expo.dev/orbit) 从本地计算机安装构建版本。
Step 4: 
### 启动打包器
在 **步骤 2** 构建的开发客户端是你应用的本地端（基本相当于你自己的 Expo Go 版本）。为了继续开发，你还需要启动 JavaScript 打包器。
根据你构建应用的方式，打包器可能已经在运行，但如果出于某种原因你关闭了进程，则无需重新构建你的开发客户端。只需使用以下命令重新启动 JavaScript 打包器：
```sh
$ npx expo start
```
这与你在 Expo Go 时使用的命令相同。它会检测你的项目是否安装了 `expo-dev-client`，在这种情况下，它将默认以开发构建为目标，而不是 Expo Go。
## 视频演练


## 使用开发构建

了解如何为项目使用开发构建。

通常，从头开始创建一个新的原生构建需要相当长的时间，以至于你会被诱导去切换任务、分散注意力。然而，一旦在你的设备或仿真器/模拟器上安装了开发构建，你就不必等待原生构建过程，直到你[改变为你的应用提供支持的底层原生代码](#rebuild-a-development-build) 。
## 启动开发服务器
要开始开发，请运行以下命令来启动开发服务器：
```sh
$ npx expo start
```
在你的开发客户端中打开项目：
- 按下 <kbd>a</kbd> 或 <kbd>i</kbd> 键，在 Android 模拟器或 iOS 模拟器上打开你的项目。
- 在实际设备上，通过系统相机或二维码阅读器扫描二维码，即可在你的设备上打开项目。
## 启动器屏幕
如果你在设备的主屏幕上启动开发构建，你将看到启动器屏幕，其外观类似于以下内容：
如果在本地网络上检测到一个 bundler，或如果你在 Expo CLI 和开发构建中都已登录 Expo 帐户，则可以直接从此屏幕连接到它。否则，你可以通过扫描 Expo CLI 显示的二维码来连接。
## 重建开发构建
如果你往项目中添加一个包含原生代码 API 的库，例如 [`expo-secure-store`](/versions/latest/sdk/securestore/)，你将需要重新构建开发客户端。这是因为在将库作为依赖项安装到项目中时，库的原生代码不会自动包含在开发客户端中。
## 调试开发构建
在需要时，您可以在 Expo CLI 中通过按下 Cmd ⌘ + d 或 Ctrl + d 来访问菜单，或摇动手机或平板。 在这里，您将能够访问开发构建的所有功能、所需的调试功能，或切换到应用的不同版本。
请参阅 [Debugging](/debugging/runtime-issues/) 指南以获取更多信息。


## 与团队共享开发构建

了解如何安装并与团队共享开发构建，或在多台设备上运行。

Android 和 iOS 都提供直接在设备上安装应用构建版本的方式。这使您能够对特定构建进行完整控制，便于快速迭代，并且同一时间可以拥有多个应用构建版本待审阅。您也可以与团队共享，或在多个测试设备上运行。
## 分享链接
开发构建就绪时，会为您的构建生成一个可分享的 URL，并附带如何启动和运行该构建的说明。您可以将此 URL 与同事共享，或发送给测试设备以安装该构建。生成的 URL 对您的项目的构建是唯一的。
> 如果在创建开发构建后注册了任何新的 iOS 设备，则需要创建一个新的开发构建以便在这些设备上安装。欲了解更多信息，请参见 [internal distribution](/build/internal-distribution/)。
### 使用 EAS 仪表板
您也可以将构建页面直接指引给您的团队成员，从而让他们在设备上直接下载构建产物。
### 使用 EAS CLI
你的队友也可以使用 EAS CLI 下载并安装开发构建。他们必须确保他们的 Expo 账户与开发构建关联的账户已签署，然后即可运行以下命令：
```sh
$ eas build:run --profile development
```
如果开发构建的 profile 名称与 `development` 不同，请改用该名称并添加 `--profile`。
### 仅限 iOS 的说明
> 如果你正在运行 iOS 16 及以上版本且尚未开启 Developer Mode，那么在你运行构建之前，你需要 [启用它](/guides/ios-developer-mode) 。 (如果你使用的是企业配置，这条不适用。)
你可以使用 `eas build:resign` 将现有的 **.ipa** 为 iOS 重新签名并换成新的 ad hoc provisioning profile。这有助于在与你的团队分发时节省时间。举例来说，如果你想把一个新的测试设备添加到现有的构建中，你可以使用此命令来更新 provisioning profile，让其包含该设备而无需从头重新构建整个应用。更多信息，请参阅 [Re-signing new credentials](/app-signing/app-credentials/#re-signing-new-credentials)。
## 后续步骤


## 工具、工作流与扩展

了解在开发构建中可用的不同工具、工作流和扩展的更多信息。

开发构建让你能够快速迭代。然而，你也可以扩展开发构建的能力，以在团队协作时提供更好的开发者体验，或自定义构建以满足你的需求。
## 工具
### 隧道 URL
有时，受限的网络条件会使连接到开发服务器变得困难。`npx expo start` 命令会在一个公开可访问的 URL 上暴露你的开发服务器，全球的防火墙都能通过该 URL 访问。这在你无法使用默认的 LAN 选项连接到开发服务器，或在开发过程中想要获得对实现的反馈时非常有用。
要获取隧道 URL，请从命令行中向 `npx expo start` 传递 [`--tunnel` flag](/more/expo-cli/#tunneling)。
### 发布的更新
EAS CLI 的 `eas update` 命令将你当前的 JavaScript 和资源文件的状态打包成一个优化的“更新”。该更新由 Expo 存储在一个托管服务上。你应用的开发构建可以加载已发布的更新，而不需要检出特定提交或让开发机器一直运行。
### 手动输入更新的 URL
当开发构建启动时，它将暴露一个 UI 用以加载开发服务器，或选择“手动输入 URL”。你可以手动提供一个 URL，以启动特定分支。该 URL 的格式如下：
```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，请使用在 [app config 的 `expo.updates.url`](/versions/latest/config/app/#url) 字段中的 URL。要查看通道列表，请运行 `eas channel:list`。
### 更新的 URL 的深度链接
你可以通过打开形如 `{scheme}://expo-development-client/?url={manifestUrl}` 的 URL，在具有与你的自定义客户端兼容版本的设备上加载你的应用。你将需要传递以下参数：
| 参数          | 值                                                                                                                    |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `scheme`      | 你客户端的 URL scheme（默认为 `exp+{slug}`，其中 [`slug`](/versions/latest/config/app/#slug) 是在应用配置中设置的值） |
| `manifestUrl` | 要加载的更新清单的 URL 编码形式。该 URL 将是 `https://u.expo.dev/[your-project-id]?channel-name=[channel-name]`       |
示例：
```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`。
#### 在自动化场景中使用更新深链接
在使用自动化（如 CI/CD 工作流）在模拟器或仿真器中启动开发构建的更新 URL 时，您可以在 URL 中添加 `disableOnboarding=1` 查询参数，以跳过首次安装开发构建后首次启动时出现的引导屏幕。
#### 应用程序特定的深链接
在开发构建中测试深链接时，例如在 Expo Router 应用中导航到特定屏幕或在 OAuth 登录流程中测试回到应用程序的重定向，请按您在深度链接到独立构建的应用程序时的方式来构造 URL（例如，`myscheme://path/to/screen`）。
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.
### QR codes
You can use our endpoint to generate a QR code that can be easily loaded by a development build.
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.
| 参数        | 值                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `appScheme` | 开发构建的 URL 编码的深度链接 scheme（默认为 `exp+{slug}`，其中 [`slug`](/versions/latest/config/app/#slug) 是在应用配置中设置的值） |
| `url`       | 更新清单的 URL 编码 URL 用于加载。该 URL 将是 `https://u.expo.dev/[your-project-id]?channel-name=[channel-name]`                     |
示例：
```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`。
## 示例工作流
这些只是一些工作流示例，帮助你的团队充分利用开发构建的优势。如果你想出对其他团队也有用的做法，请[提交一个 PR](https://github.com/expo/expo/tree/main/CONTRIBUTING.md#-updating-documentation) 分享你的知识！
### PR 预览
你可以将 CI 过程设置为在拉取请求更新时发布一个 EAS Update，并添加一个用于在兼容的开发构建中查看变更的二维码。
请参阅[在拉取请求上发布应用预览的说明](/eas-update/github-actions/#publish-previews-on-pull-requests) ，以在您的项目中使用 GitHub Actions 实现此工作流，或在您选择的 CI 中作为模板使用。
## 扩展
扩展允许您为开发客户端添加额外的功能。
### 扩展开发菜单
开发者菜单可以通过使用 `registerDevMenuItems` API 来扩展，添加额外的按钮：
```tsx
import { registerDevMenuItems } from 'expo-dev-menu';
const devMenuItems = [
  {
    name: 'My Custom Button',
    callback: () => console.log('Hello world!'),
  },
];
registerDevMenuItems(devMenuItems);
```
这将创建一个 dev menu 新的部分，其中包含您已注册的按钮：
> 后续调用 `registerDevMenuItems` 将覆盖所有先前的条目。
### EAS 更新
EAS Update 扩展提供在你的开发客户端中查看和加载已发布更新的能力。
它可用于所有开发客户端 `v0.9.0` 及以上版本。要安装它，你需要获取 `expo-updates` 的最新发布版本：
```sh
$ npx expo install expo-dev-client expo-updates
```
#### 配置 EAS Update
如果您尚未在项目中配置 EAS Updates，可以在这里找到 [关于如何进行的额外说明。](/eas-update/getting-started/)
现在，您可以通过 `Extensions` 面板在开发构建中查看并加载 EAS Updates。
## 在应用配置中设置 runtimeVersion
当您为项目创建一个开发构建时，您将获得一个稳定的环境，以加载应用中用 JavaScript 或其他资源相关变更所定义的任何更改。对应用的其他更改，无论是在 **android** 和 **ios** 目录中直接定义，还是通过您选择安装的包或 SDK 定义，都需要您创建一个新的开发构建版本。
为强制应用的 JavaScript 层与本地层之间的 API 合同，您应在应用配置中设置 [`runtimeVersion`](/eas-update/runtime-versions) 值。您所做的每次构建都会将该值嵌入，并且在开发和生产环境中只加载具有相同 `runtimeVersion` 的 bundle。


## 下一步

用于了解开发构建和 EAS Build 的有用资源清单。

# 配置插件

## 配置插件简介

Expo 配置插件入门。

在一个项目中使用 [Continuous Native Generation (CNG)](/workflow/continuous-native-generation/) 时，原生项目（**android** 和 **ios** 目录）的变更是在不直接与原生项目文件交互的情况下实现的。相反，你可以使用配置插件在默认应用配置属性无法配置的范围内，自动配置你的原生项目。
## 什么是配置插件
配置插件是一个顶层的自定义配置点，它并未内置在 [app config](/workflow/configuration) 中。使用配置插件，你可以修改在 CNG 项目的 [prebuild](/workflow/continuous-native-generation/#usage) 过程中创建的原生项目。
一个配置插件在应用配置文件的 `plugins` 属性中被引用，并由一个或多个插件函数组成。这些插件函数使用 JavaScript 编写，并在预构建过程期间执行。
## 术语表
一个典型的配置插件由一个或多个插件函数组成，它们协同工作。下图展示了配置插件的不同部分如何相互作用：
<ConfigPluginHierarchy highlightedNodeId="1" />
在下列指南中，我们将使用上述图示来突出下面所解释的特定术语：
### 插件
顶层配置插件，在应用配置的 `plugins` 数组中引用。这是插件的入口点。通常命名为 `with<Plugin Name>`。例如，`withMyPlugin`。它由一个或多个 [插件函数](#plugin-function) 组成。
### 插件函数
配置插件中的一个或多个函数，被称为 _插件函数_ 。它们封装执行平台特定修改的底层逻辑。严格来说，插件函数看起来就像顶层插件本身的函数，可以作为插件独立使用。将插件拆分成更小的函数通常有助于测试和调试。
### Mod 插件函数
来自 `expo/config-plugins` 库的包装函数，提供一种安全的方式使用 `mods` 来修改原生文件。作为开发者，您将在配置插件中使用这些函数，而不是底层的 `mods`。
### Mod
底层的、特定平台的修饰符（如 `mods.android.manifest` 和 `mods.ios.infoplist`），在预构建阶段直接修改原生项目文件。
## 为什么使用配置插件
配置插件可以向你的项目添加本地配置，而不是默认包含。它们可用于生成应用图标、设置应用名称、配置 **AndroidManifest.xml** 和 **Info.plist**，等等。
在 CNG 项目中，最好避免手动修改这些原生项目，因为在不小心覆盖手动修改的情况下，你无法安全地重新生成它们。配置插件通过将本地项目的更改集中到一个配置文件中并在运行 `npx expo prebuild` 时应用它们（无论是手动还是在 CI/CD 流程中自动执行），从而以 _可预测的方式_ 修改这些原生项目。例如，当你在应用配置中更改应用名称并运行 `npx expo prebuild` 时，名称将在你的本地原生项目中自动更改，而无需手动更新 **AndroidManifest.xml** 和 **Info.plist** 文件。
## 配置插件的特征
Config 插件具有以下特征：
- 插件是 **同步** 函数，接受一个 [ExpoConfig](/workflow/configuration) 并返回经过修改的 `ExpoConfig`。在极少数情况下，如果用于与原生项目通信的方法是异步的，插件也可以是异步的，但它们的性能不会好。
- 插件应使用以下命名约定：`with<Plugin Functionality>`，例如 `withFacebook`
- 插件应为同步的，并且它们的返回值应可序列化，除了添加任何 [`mods`](#mods)。
- 插件在应用配置评估阶段始终会被评估。
- 可选地，可以将第二个参数传递给插件以对其进行配置
- Mods 仅在 **同步** 阶段的 `npx expo prebuild`（prebuild 过程）中进行评估，并在代码生成期间修改原生文件。因此，为确保在非 prebuild 配置场景中执行，配置插件对应用配置所做的任何修改应位于 mod 之外。
## 开始使用


## 创建和使用配置插件

学习如何在你的 Expo 项目中创建和使用配置插件。

本指南涵盖如何创建配置插件、如何向配置插件传递参数，以及如何将多个配置插件串联在一起的部分。还包括如何从 Expo 库中使用配置插件。
通过下方图表，在本指南中你将学习配置插件层级结构的前两部分：
<ConfigPluginHierarchy highlightedNodeIds={['1', '2']} />
> **info** **注意：** 以下各节使用动态 [应用配置](/workflow/configuration/) （**app.config.js/app.config.ts** 而非 **app.json**），这并非使用简单配置插件所必需。然而，当你想创建/使用一个接受参数的基于函数的配置插件时，需要使用动态应用配置。
## 创建一个配置插件
在下节中，我们让我们创建一个本地配置插件，为 Android 的 **AndroidManifest.xml** 和 iOS 的 **Info.plist** 添加任意属性 `HelloWorldMessage`。
此示例将创建并修改以下文件。若要跟随，请在项目根目录创建一个 **plugins** 目录，并在其中创建 **withAndroidPlugin.ts**、**withIosPlugins.ts**，以及 **withPlugin.ts** 文件。
```
plugins/
│   ├── withAndroidPlugin.ts  # Contains Android-specific modifications
│   ├── withIosPlugin.ts  # Contains iOS-specific modifications
│   └── withPlugin.ts  # Main plugin file that combines both Android and iOS plugins
app.config.ts  # Dynamic app config file that uses the plugin
```
Step 1: 
### 创建 Android 插件
在 **withAndroidPlugin.ts** 中，添加以下代码：
```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;
```
上面的示例代码通过从 expo/config-plugins 库导入 `ConfigPlugin` 和 `withAndroidManifest`，向 **android/app/src/main/AndroidManifest.xml** 文件添加一个 meta-data 条目 `HelloWorldMessage`。[`withAndroidManifest`](/config-plugins/mods/#mod-plugins) mod 插件是一个异步函数，接受一个 config 和一个 data 对象，并在返回对象之前修改值。
Step 2: 
### Create iOS plugin
在 **withIosPlugin.ts** 中，添加以下代码：
```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;
```
上面的示例代码通过从 expo/config-plugins 库导入 `ConfigPlugin` 和 `withInfoPlist`，在 **ios/\<your-project-name\>/Info.plist** 文件中将 `HelloWorldMessage` 作为自定义 key、并附加自定义消息。[`withInfoPlist`](/config-plugins/mods/#mod-plugins) 模块插件是一个异步函数，接收一个 config 和一个 data 对象，并在返回对象前修改其值。
Step 3: 
### 创建一个组合插件
现在你可以创建一个组合插件，应用两个平台特定的插件。这种方法可以将平台相关的代码分开维护，同时提供一个统一的入口点。
在 **withPlugin.ts** 中，添加以下代码：
```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: 
### 添加 TypeScript 支持并转换为动态应用配置
我们建议使用 TypeScript 编写配置插件，因为这将为配置对象提供 IntelliSense。但是，您的应用配置最终由 Node.js 评估，而 Node.js 默认不识别 TypeScript 代码。因此，您需要将来自 **plugins** 目录的 TypeScript 文件的解析器添加到 **app.config.ts** 文件中。
通过以下命令安装 `tsx` 库：
```sh
$ npm install --save-dev tsx
```
接着，将静态应用配置 (**app.json**) 更改为 [动态应用配置 (**app.config.ts**)](/workflow/configuration/#dynamic-configuration) 文件。您可以将 **app.json** 文件重命名为 **app.config.ts**，并将文件内容修改如下所示。请确保在 **app.config.ts** 文件顶部添加以下 import 语句：
```ts app.config.ts
import 'tsx/cjs';
module.exports = () => {
};
```
Step 5: 
### 从你的动态应用配置调用 config 插件
现在，你可以从你的动态应用配置中调用 config 插件。要做到这一点，你需要将 **withPlugin.ts** 文件的路径添加到你的应用配置中的 plugins 数组：
```ts app.config.ts
import "tsx/cjs";
import { ExpoConfig } from "expo/config";
  plugins: [
      ["./plugins/withPlugin.ts"],
    ],
};
```
要在本机项目中查看已应用的自定义配置，请运行以下命令：
```sh
$ npx expo prebuild --clean --no-install
```
要验证已应用的自定义配置插件，请打开 **android/app/src/main/AndroidManifest.xml** 和 **ios/\<your-project-name\>/Info.plist** 文件：
```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>
```
## 向配置插件传递参数
你的 config 插件可以接受来自应用配置的参数。为此，你需要在你的配置插件函数中读取该参数，然后将包含该参数的对象与配置插件函数一起在你的应用配置中传递。
Step 1: 
考虑前面的示例，让我们向插件传递一个自定义消息。在 **withAndroidPlugin.ts** 中添加一个 `options` 对象，并将 `message` 变量更新为使用 `options.message` 属性：
```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: 
类似地，在 **withIosPlugin.ts** 中再添加一个 `options` 对象，并更新 `message` 变量以使用 `options.message` 属性：
```ts withIosPlugin.ts
type IosProps = {
  message?: string;
};
  const message = options.message || 'Hello world, from Expo plugin!';
};
export default withIosPlugin;
```
Step 3: 
将 **withPlugin.ts** 文件更新为将 `options` 对象传递给两个插件：
```ts withPlugin.ts
  config = withAndroidPlugin(config, options);
  return withIosPlugin(config, options);
};
```
Step 4: 
要将值动态传递给插件，您可以在应用配置中向插件传递一个具有 `message` 属性的对象：
```ts app.config.ts
{
  plugins: [
    [
      "./plugins/withPlugin.ts",
      { message: "Custom message from app.config.ts" },
    ],
  ],
}
```
## 链式配置插件
可以将配置插件链式连接，以应用多项修改。链中的每个插件按出现的顺序运行，一个插件的输出成为下一个插件的输入。这种顺序执行确保插件之间的依赖关系被遵循，并让你能够精确控制对原生代码修改的顺序。
要链接配置插件，您可以将插件数组传递给应用配置中的 `plugins` 数组属性。这在 JSON 应用配置文件格式（**app.json**）中也受支持。
```ts app.config.ts
module.exports = ({ config }: { config: ExpoConfig }) => {
  name: 'my app',
  plugins: [
    [withFoo, 'input 1'],
    [withBar, 'input 2'],
    [withDelta, 'input 3'],
  ],
};
```
`plugins` 数组在底层使用 `withPlugins` 方法来串联插件。如果你的 plugins 数组变得很长或配置很复杂，你可以直接使用 `withPlugins` 方法来让配置更易读。`withPlugins` 会将插件串联起来并按顺序执行。
```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);
};
```
## 使用配置插件
Expo 配置插件通常包含在 Node.js 模块中。你可以像在项目中安装其他库一样安装它们。
例如，`expo-camera` 有一个插件，可以将相机权限添加到 **AndroidManifest.xml** 和 **Info.plist** 中。要在你的项目中安装它，请运行以下命令：
```sh
$ npx expo install expo-camera
```
在你的 [app 配置](/versions/latest/config/app/) 中，可以将 `expo-camera` 添加到插件列表中：
```json app.json
{
  "expo": {
    "plugins": ["expo-camera"]
  }
}
```
一些配置插件通过允许传递选项来自定义它们的配置来提供灵活性。为此，您可以传递一个数组，将 Expo 库名作为第一个参数，将包含选项的对象作为第二个参数。例如，`expo-camera` 插件允许您自定义相机权限提示消息：
```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) 。
在运行 `npx expo prebuild` 时，[`mods`](/config-plugins/introduction/#mods) 会被编译，原生文件也会发生变化。
在重新构建原生项目之前，变更不会生效，例如在 Xcode 中。 **如果您在没有原生目录的项目中使用配置插件（CNG 项目），它们将会在 EAS Build 的 prebuild 步骤中应用，或在本地运行 `npx expo prebuild|android|ios` 时应用。**


## 模块

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

本指南解释了什么是模块和模块插件，它们的工作原理，以及在为您的 Expo 项目创建配置插件时如何有效地使用它们。
使用下面的图表，在本指南中，您将学习配置插件层次结构的最后两个部分：
<ConfigPluginHierarchy highlightedNodeIds={['3', '4']} />
## 模块插件
模块插件提供了一种在预构建过程中修改本机项目文件的方法。它们来自 `expo/config-plugins` 库，并封装了顶级模块（也称为 _默认 [模块](#mods)_），因为顶级模块是平台特定的并执行一些难以理解的各种任务。
> **info** **提示：** 如果您正在开发需要模块的功能，则应使用 _模块插件_ 而不是直接与顶级模块交互。
### 可用模块插件
以下模块插件可在 `expo/config-plugins` 库中使用：
#### 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))                          | <WarningIcon /> | 将 **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))                                             | <WarningIcon /> | 将 **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))                                              | <WarningIcon /> | 将 **android/app/build.gradle** 作为字符串修改。                                                         |
| `mods.android.projectBuildGradle` | `withProjectBuildGradle` ([示例](https://github.com/expo/expo/blob/main/packages/%40expo/config-plugins/src/android/GoogleServices.ts#L5))                                          | <WarningIcon /> | 将 **android/build.gradle** 作为字符串修改。                                                             |
| `mods.android.settingsGradle`     | `withSettingsGradle` ([示例](https://github.com/expo/expo/blob/main/packages/install-expo-modules/src/plugins/android/withAndroidSettingsGradle.ts#L2))                             | <WarningIcon /> | 将 **android/settings.gradle** 作为字符串修改。                                                          |
#### 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))                      | <WarningIcon /> | 将 **ios/&lt;name&gt;/AppDelegate.m** 作为字符串修改。                                                                       |
> **信息** **关于默认 Android 和 iOS 模块的说明：** 
> 默认模块由模块编译器提供，以便于常见的文件操作。危险的修改依赖于正则表达式（regex）来修改应用代码，这可能导致构建失败。正则模块的版本控制也很困难，因此应谨慎使用。始终倾向于使用应用代码来修改应用代码，即使用 [Expo Modules](https://github.com/expo/expo/tree/main/packages/expo-modules-core) 原生 API。
## 模块
配置插件使用 **模块**（modifiers 的缩写）在预构建过程中修改本机项目文件。模块是异步函数，允许您在不必手动编辑它们的情况下，对平台特定文件（如 **AndroidManifest.xml** 和 **Info.plist** 以及其他本机配置文件）进行更改。它们仅在 `npx expo prebuild`（预构建过程） 的 **同步** 阶段执行。
它们接受一个配置和一个数据对象，然后修改并将两者作为一个单一对象返回。例如，在本机项目中，`mods.android.manifest` 修改 **AndroidManifest.xml**，而 `mods.ios.plist` 修改 **Info.plist**。
**您并不直接在配置插件中使用模块作为顶级函数（例如 `with.android.manifest`）。** 当您需要使用模块时，您在配置插件中使用 _模块插件_。这些模块插件由 `expo/config-plugins` 库提供，并封装了顶级模块函数，幕后执行各种任务。要查看可用模块的列表，请查看 [由 `expo/config-plugins` 提供的模块插件](#available-mod-plugins)。
Note: 默认模块的工作原理及其主要特征
---
当默认模块解析时，它被添加到应用配置的 `mods` 对象中。这个 `mods` 对象与应用配置的其余部分不同，因为它不会被序列化，这意味着您可以在代码生成 _期间_ 执行操作。尽可能使用可用的模块插件，而不是默认模块，因为它们更容易使用。
以下是默认模块工作原理的高层概述：
- 使用 [`getPrebuildConfig`](https://github.com/expo/expo/blob/efc2db4eb1c909544e28792a15c89f8d22113c5b/packages/%40expo/prebuild-config/src/getPrebuildConfig.ts#L28) 从 `@expo/prebuild-config` 读取配置
- 所有 Expo 支持的核心功能通过 `withIosExpoPlugins` 中的插件添加。这包括名称、版本、图标、区域设置等。
- 配置传递给编译器 `compileModsAsync`
- 编译器添加负责读取数据（如 **Info.plist**）的基本模块，执行命名模块（如 `mods.ios.infoPlist`），然后将结果写入文件系统
- 编译器遍历所有模块并异步评估它们，提供一些基本属性，例如 `projectRoot`
  - 每个模块后，错误处理会检查模块链是否由于无效模块而被破坏
以下是默认模块的一些主要特征：
- `mods` 被省略在清单中，**无法** 通过 `Updates.manifest` 访问。模块存在的唯一目的是在代码生成期间修改本机项目文件！
- `mods` 可在 `npx expo prebuild` 命令期间安全地读取和写入文件。这就是 Expo CLI 如何修改 **Info.plist**、权限、xcproj 等等。
- `mods` 是平台特定的，应始终添加到平台特定对象中：
  ```ts app.config.ts
  module.exports = {
    name: 'my-app',
    mods: {
      ios: {
        /* iOS 模块... */
      },
      android: {
        /* Android 模块... */
      },
    },
  };
  ```
在模块解析后，每个模块的内容将被写入磁盘。可以添加自定义模块以支持新的本机文件。例如，您可以创建一个模块来支持 **GoogleServices-Info.plist**，并将其传递给其他模块。
---
### 模块插件的工作原理
当执行模块插件时，会传递一个带有附加属性的 `config` 对象：`modResults` 和 `modRequest`。
#### `modResults`
`modResults` 对象包含要修改和返回的数据。其类型取决于正在使用的模块。
#### `modRequest`
`modRequest` 对象包含模块编译器提供的以下附加属性。
| 属性                  | 类型          | 描述                                                                             |
| --------------------- | ------------- | -------------------------------------------------------------------------------- |
| `projectRoot`         | `string`      | 通用应用的项目根目录。                                                           |
| `platformProjectRoot` | `string`      | 特定平台的项目根目录。                                                           |
| `modName`             | `string`      | 模块的名称。                                                                     |
| `platform`            | `ModPlatform` | 在模块配置中使用的平台名称。                                                     |
| `projectName`         | `string`      | （仅限 iOS）用于查询项目文件的路径组件。例如，`projectRoot/ios/[projectName]/`。 |
## 创建您自己的模块
例如，如果您想编写一个模块来更新 Xcode 项目的“产品名称”，您将创建一个配置插件文件，使用 [`withXcodeProject`](#ios) 模块插件。
```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;
    }
  );
};
// 用法：
/// 创建一个配置
const config = {
  name: 'my app',
};
/// 使用插件
export default withCustomProductName(config, 'new_name');
```
## 插件模块解析
在实现插件时，有两种基本方法需要考虑：
1. **在您应用项目中定义的插件**：这些插件本地存在于您的项目中，使其容易与应用代码一起自定义和维护。它们非常适合于项目特定的自定义。
2. **独立包插件**：这些插件作为单独的包存在并发布到 npm。此方法适合于可以跨多个项目共享的可重用插件。
这两种方法都提供了相同的功能来修改您的本机配置，但在结构和导入方式上有所不同。下面的部分解释了每种方法的模块解析是如何工作的。
> 任何未在下面指定的解析模式都是意外行为，并可能面临破坏性更改。
### 在您应用项目中定义的插件
对于在您应用项目中定义的插件，您可以通过多种方式直接实现插件：
#### 文件导入
您可以通过创建 JavaScript/TypeScript 文件快速在您的项目中创建插件，并在您的配置中像使用任何其他 JS/TS 文件一样使用它。
在上述示例中，配置插件文件包含一个最基本的函数：
```ts my-config-plugin.ts
module.exports = ({ config }: { config: ExpoConfig }) => {};
```
#### 动态应用配置中的内联函数
Expo 配置对象还支持将函数原样传递给 `plugins` 数组。这对于测试很有用，或者如果您想在不创建文件的情况下使用插件。
```js app.config.ts
const withCustom = (config, props) => config;
const config = {
  plugins: [
    [
      withCustom,
      {
        /* props */
      },
    ],
    withCustom,
  ],
};
```
使用函数而不是字符串的一个注意事项是，序列化将用函数的名称替换函数。这使得 **清单**（有点像您应用的 **index.html**）正常工作。序列化后的配置看起来如下所示：
```json
{
  "plugins": [["withCustom", {}], "withCustom"]
}
```
### 独立包插件
> **信息** 请参阅 [创建带有配置插件的模块](/modules/config-plugin-and-native-module-tutorial/) 以获取逐步指南，了解如何创建独立包插件。
独立包插件可以通过两种方式实现：
#### 1. 专用配置插件包
这些是 npm 包，其唯一目的是提供配置插件。对于专用配置插件包，您可以使用 `app.plugin.js` 导出您的插件：
#### 2. 带有伴生包的配置插件
当配置插件是没有 **app.plugin.js** 的 Node 模块的一部分时，它会使用该包的 `main` 入口点：
### 插件解析顺序
当您导入插件包时，文件以以下特定顺序解析：
1. **包根目录中的 app.plugin.js**
2. **包的主入口（来自 package.json）**
3. **直接内部导入**（不推荐）
> **error** 避免直接导入模块内部，因为这会绕过标准解析顺序，可能在未来更新中造成问题。
### 为什么使用 app.plugin.js 来处理插件
`app.plugin.js` 方法被首选用于配置插件，因为它允许与主包代码不同的转译设置。这一点特别重要，因为 Node 环境通常需要与 Android、iOS 或 Web JS 环境不同的转译预设（例如，使用 `module.exports` 而不是 `import/export`）。
[xml2js]: https://www.npmjs.com/package/xml2js
[expo-plist]: https://www.npmjs.com/package/@expo/plist


## 使用危险的 mod

了解危险的 mods 及其在创建配置插件时的使用方法。

Expo 中的危险 mods 通过字符串操作和正则表达式提供对原生项目文件的直接访问。虽然 [现有的 mod 插件](/config-plugins/mods) 是推荐的方法，但危险的 mods 作为无法通过现有 mod 插件实现的修改的逃生开关。
Note: 为什么它们被认为是危险的？
---
自动的直接源代码操作通常效果不佳。例如，如果一个危险 mod 替换了源文件中的文本，而后来的危险 mod 又期望原始文本存在（可能它将原始文本用作正则表达式的锚点），那么它很可能无法产生所需的结果——根据其编写方式，它可能出现错误或生成日志。其他类型的 mods 较少容易出现此类问题，虽然直接操作源文件的 mods，如 `withAndroidManifest` 和 `withPodfile` 也可能遇到这种情况。
与可以安全运行多次的标准 mods 不同，危险 mods 很少被保证是幂等的。多次运行同一危险 mod 可能会产生不同的结果、导致重复修改或完全破坏目标文件。
---
## 何时使用危险 mod
考虑在以下情况下使用危险 mod：
- **无法使用标准 mod 进行修改**：所需的修改不被现有的 mod 插件支持，如 [`withAndroidManifest`](/config-plugins/mods/#android)、[`withPodfile`](/config-plugins/mods/#ios) 等，或者库需要特定的原生修改，而这些并不在标准插件的覆盖范围内。
- **老旧 Expo SDK 兼容性**：您正在针对一个不包含所需 mod 插件的旧版本 Expo SDK。
- **需要用正则表达式或替换函数修改文本**：您需要进行现有 mod 插件不支持的复杂文本操作。例如，Expo 在内部使用危险 mods 进行大型文件系统重构，例如库名更改时。
## 如何使用危险 mod
在实际场景中，您可以直接在项目中使用本节中描述的示例配置插件，遵循 [创建配置插件部分](/config-plugins/plugins/#creating-a-config-plugin) 的标准配置插件使用模式。然而，对于名为 [`withPodfile`](/config-plugins/mods/#ios) 的现有 mod 插件，您无需使用危险 mod。下面的示例只是为了演示如何创建和使用危险 mod。
让我们看看一个示例配置插件，以修改原生目录中的一个文件 (**ios**)。当您在 Expo 项目中使用持续的原生生成时，这非常有用。在该配置插件的帮助下，原生文件 (**ios/Podfile**) 将在每次运行 `npx expo prebuild` 命令时更新，无论您是手动运行还是使用 EAS Build)。当现有 mod 插件无法编辑和更新原生目录中的文件时，此示例是一个理想的用例。
遵循 [创建配置插件部分](/config-plugins/plugins/#creating-a-config-plugin) 中创建配置插件的目录结构和步骤（步骤 3、4 和 5），假设该配置插件是在您 Expo 项目的 **plugins** 目录中创建的：
```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** 将在预构建过程中自动向您的项目的原生 **ios/Podfile** 添加 CocoaPod 依赖项。它使用 `withDangerousMod` 直接访问原生文件系统，并在生成原生项目之后但在安装任何 CocoaPod 依赖项之前运行。
**Podfile** 需要直接文本操作，这通过 `addCustomMod` 函数中的正则表达式模式进行。该过程还需要在 `use_expo_modules!` 语句之后，在 **Podfile** 的特定位置插入 CocoaPod 依赖项。
## `withDangerousMod` 语法和要求
使用 `withDangerousMod` 需要某些参数：
1. 一个原生平台（**android** 或 **ios**）
2. 一个异步函数，它接收 `config` 对象，并具有文件系统访问权限
3. 相对文件名/路径，以便在原生目录中访问
4. 读取现有文件、修改其内容并写回文件
5. （可选）在插件在预构建过程中执行时记录成功和失败状态的自定义消息
下面的代码片段提供了所需字段的框架以及在使用 `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. 异步修改函数
      // 3. 构建文件路径
      const filePath = path.join(
        config.modRequest.platformProjectRoot, // 原生项目根目录
        'path/to/file' // 相对路径到目标文件
      );
      try {
        // 4. 读取现有文件，修改其内容，并写回文件
        let contents = await fs.readFile(filePath, 'utf8');
        contents = modifyContents(contents);
        await fs.writeFile(filePath, contents);
        // 5. 记录成功和失败状态
        console.log('✅ Successfully modified file');
      } catch (error) {
        console.warn('⚠️ File modification failed:', error);
      }
      return config;
    },
  ]);
};
// 使用正则表达式修改文件内容的帮助函数
```
### 配置插件中的可用路径
配置插件中可用的不同路径属性：
| 路径                                          | 类型      | 描述                                                                                                                                                                    |
| --------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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` 时，mods 应仅读取和分析文件而不进行写操作。用于配置分析和验证。                                 |
| `config.modRequest.ignoreExistingNativeFiles` | `boolean` | 是否忽略现有的原生文件。用于基于模板的操作，特别影响授权和其他原生配置，以确保与预构建期望的一致性。                                                                    |
## 使用危险 mod 时的注意事项
使用危险 mod 时，请考虑以下几点：
- **有限的幂等性保证。** 与通常具有幂等性的标准 mods 不同，危险 mods **很少被保证是幂等的**。这意味着多次运行同一危险 mod 可能会产生不同的结果或导致问题。
- **实验性和易破坏。** 使用 `withDangerousMod` 时要小心，因为它可能在将来发生变化。请在每个 SDK 发布版本中彻底测试您的危险 mods，因为它们在原生模板更改发生时尤其容易出现问题。
- **使用标准 mod 插件**。 Android 和 iOS 都提供像 `withAndroidManifest`、`withPodfile`、`withPodfileProperties` 等 mod 插件来执行常见的原生文件修改。仅在没有 [现有 mod 插件可用](/config-plugins/mods/#available-mod-plugins) 处理您的用例时使用危险 mod。
- **不要假设文件存在**。在读取/写入之前始终检查原生目录及文件的相对路径。如果您使用 CNG，可以始终运行 `npx expo prebuild` 来创建原生 **android** 和 **ios** 目录，并手动验证文件的存在。
- **危险 mods 首先运行。** 危险 mods 的执行顺序可能不可靠，因为危险 mods 在其他修饰符之前运行。这可能会影响您的构建过程的可预测性，并导致与其他修改的冲突。


## 库的插件开发

学习如何为 Expo 和 React Native 库开发配置插件。

Expo 配置插件在 React Native 库中代表了一种自动化本地项目配置的变革性方法。与其要求库用户手动编辑 **AndroidManifest.xml**、**Info.plist** 等本地文件，不如提供一个插件，在预构建过程中自动处理这些配置。这将开发者的体验从容易出错的手动设置变为可靠的、自动化的配置，可以在不同项目中一致工作。
本指南解释了可以在库中实现配置插件的关键配置步骤和策略。
## 库中配置插件的战略价值
配置插件往往解决相互关联的问题，这些问题在历史上使得 React Native 库的采用比应有的更困难。有时，当用户安装 React Native 库时，他们会面临一组复杂的本地配置步骤，这些步骤必须正确执行才能使库正常工作。这些步骤是平台特定的，有时需要对本地开发概念有深入了解。
通过在库中创建配置插件，您可以将这个复杂的手动过程转换为用户可以在其 Expo 项目的应用配置文件（通常是 **app.json**）中应用的简单配置声明。这降低了您库的采纳门槛，同时使设置过程变得可靠。
除了即时用户体验的改善，配置插件还支持与 [持续本地生成](/workflow/continuous-native-generation/) 的兼容性，在这种情况下，本地目录会自动生成，而不是检入版本控制。如果没有配置插件，采用 CNG 的开发者面临一个艰难的选择：要么放弃 CNG 工作流手动配置本地文件，要么投入大量精力创建自己的自动化解决方案。这为现代 Expo 开发工作流中的库采纳创建了相当大的障碍。
## 项目结构
目录结构是在库中维护配置插件的基础。以下是一个示例目录结构：
```
./
    ├── android/  # Android 本地模块代码
    │   ├── src/
    │   │   └── main/
    │   │       └── java/
    │   │           └── com/
    │   │               └── your-awesome-library
    │   └── build.gradle
    ├── ios/  # iOS 本地模块代码
    │   ├── YourAwesomeLibrary
    │   └── YourAwesomeLibrary.podspec
    ├── src/
    │   ├── index.ts  # 主库入口点
    │   ├── YourAwesomeLibrary.ts  # 核心库实现
    │   └── types.ts  # TypeScript 类型定义
    ├── plugin/
    │   ├── src/
    │   │   ├── index.ts  # 插件入口点
    │   │   ├── withAndroid.ts  # Android 特定配置
    │   │   └── withIos.ts  # iOS 特定配置
    │   ├── build/
    │   │   └──   # 编译的插件输出（生成）
    │   ├── __tests__/
    │   │   └──   # 插件特定测试
    │   └── tsconfig.json  # 插件特定 TypeScript 配置
    ├── example/
    │   ├── app.json  # 示例应用配置
    │   ├── App.tsx  # 示例应用实现
    │   └── package.json  # 示例应用依赖
    ├── __tests__/
    │   └──   # 主库测试
    ├── app.plugin.js  # Expo CLI 的插件入口点
    ├── package.json  # 包配置
    ├── tsconfig.json  # 主要 TypeScript 配置
    ├── jest.config.js  # 测试配置
    └── README.md  # 文档
```
上面的目录结构示例突出了以下组织原则：
- **根级分离**：库代码（**src**）和插件实现（**plugin**）之间清晰的边界
- **插件目录组织**：平台特定文件（**withAndroid.ts**、**withIos.ts**）使得测试和维护更为集中
- **构建输出管理**：编译的 JavaScript 和 TypeScript 声明在 **plugins/build/** 目录
- **测试**：将插件测试与库测试分开，以反映不同的关注点。
## 开发的安装和配置
利用 Expo 工具的最简单方法是使用 `expo` 和 [`expo-module-scripts`](https://www.npmjs.com/package/expo-module-scripts)。
- `expo` 提供配置插件 API 及您插件将使用的类型。
- `expo-module-scripts` 提供专门为 Expo 模块和配置插件设计的构建工具。它还处理 TypeScript 编译。
```sh
$ npx expo install package
```
使用 `expo-module-scripts` 时，需要以下 **package.json** 配置。对于任何已存在的相同脚本名称，请替换它。
```json package.json
{
  "scripts": {
    "build": "expo-module build",
    "build:plugin": "expo-module build plugin",
    "clean": "expo-module clean",
    "test": "expo-module test",
    "prepare": "expo-module prepare",
    "prepublishOnly": "expo-module prepublishOnly"
  },
  "devDependencies": {
    "expo": "^54.0.0"
  },
  "peerDependencies": {
    "expo": ">=54.0.0"
  },
  "peerDependenciesMeta": {
    "expo": {
      "optional": true
    }
  }
}
```
下一步是在 **plugins** 目录中添加 TypeScript 支持。打开 **plugins/tsconfig.json** 文件并添加以下内容：
```json plugins/tsconfig.json
{
  "extends": "expo-module-scripts/tsconfig.plugin",
  "compilerOptions": {
    "outDir": "build",
    "rootDir": "src"
  },
  "include": ["./src"],
  "exclude": ["**/__mocks__/*", "**/__tests__/*"]
}
```
您还需要在 **app.plugin.js** 文件中定义您配置插件的主要入口点，该文件会从 **plugin/build** 目录导出编译后的插件代码：
```js app.plugin.js
module.exports = require('./plugin/build');
```
上述配置至关重要，因为当 Expo CLI 查找插件时，它会在您库的项目根目录中检查此文件。 **plugin/build** 目录包含从您配置插件的 TypeScript 源代码生成的 JavaScript 文件。
## 关键实现模式
成功的配置插件实现的基本模式包括：
- **插件结构**：每个插件应遵循的核心模式
- **平台特定实现**：有效处理 Android 和 iOS 配置
- **测试策略**：通过测试验证您的插件代码
### 插件结构和平台特定实现
每个配置插件遵循相同的模式：接收配置和参数，通过修改应用变换，并返回修改后的配置。考虑以下核心插件结构的样子：
For Index file: 
```ts plugin/src/index.ts|collapseHeight=480
import { type ConfigPlugin, withAndroidManifest, withInfoPlist } from 'expo/config-plugins';
export interface YourLibraryPluginProps {
  customProperty?: string;
  enableFeature?: boolean;
}
const withYourLibrary: ConfigPlugin<YourLibraryPluginProps> = (config, props = {}) => {
  // 应用 Android 配置
  config = withAndroidConfiguration(config, props);
  // 应用 iOS 配置
  config = withIosConfiguration(config, props);
  return config;
};
export default withYourLibrary;
```
For Android: 
```ts plugin/src/withAndroid.ts
import { type ConfigPlugin, withAndroidManifest, AndroidConfig } from 'expo/config-plugins';
export const withAndroidConfiguration: ConfigPlugin<YourLibraryPluginProps> = (config, props) => {
  return withAndroidManifest(config, config => {
    const mainApplication = AndroidConfig.Manifest.getMainApplicationOrThrow(config.modResults);
    AndroidConfig.Manifest.addMetaDataItemToMainApplication(
      mainApplication,
      'your_library_config_key',
      props.customProperty || 'default_value'
    );
    return config;
  });
};
```
For iOS: 
```ts plugin/src/withIos.ts
import { type ConfigPlugin, withInfoPlist } from 'expo/config-plugins';
export const withIosConfiguration: ConfigPlugin<YourLibraryPluginProps> = (config, props) => {
  return withInfoPlist(config, config => {
    config.modResults.YourLibraryCustomProperty = props.customProperty || 'default_value';
    if (props.enableFeature) {
      config.modResults.YourLibraryFeatureEnabled = true;
    }
    return config;
  });
};
```
### 测试策略
配置插件测试与常规库测试不同，因为您是测试配置转换而不是运行时行为。您的插件接收配置对象并返回修改后的配置对象。
有效的配置插件测试可以是以下一种或多种组合：
- **单元测试**：使用模拟的 Expo 配置对象测试配置转换逻辑
- **跨平台验证**：使用示例应用验证实际预构建输出
- **错误条件测试**：使用错误处理
由于单元测试关注插件的转换逻辑而不涉及文件系统，您可以使用 Jest 创建并运行模拟配置对象，将它们传递给您的插件，并验证预期的修改是否正确完成。例如：
```ts plugin/__tests__/withYourLibrary.test.ts
import { withYourLibrary } from '../src';
describe('withYourLibrary', () => {
  it('should configure Android with custom property', () => {
    const config = {
      name: 'test-app',
      slug: 'test-app',
      platforms: ['android', 'ios'],
    };
    const result = withYourLibrary(config, {
      customProperty: 'test-value',
    });
    // 验证插件是否正确应用
    expect(result.plugins).toBeDefined();
  });
});
```
错误应该在您的配置插件中优雅地处理，以提供清晰的反馈，当配置失败时。使用 `try-catch` 块提前拦截错误：
```ts plugin/src/index.ts
const withYourLibrary: ConfigPlugin<YourLibraryPluginProps> = (config, props = {}) => {
  try {
    // 早期验证配置
    validateProps(props);
    // 应用配置
    config = withAndroidConfiguration(config, props);
    config = withIosConfiguration(config, props);
    return config;
  } catch (error) {
    // 如有需要则重新抛出以提供更多上下文
    throw new Error(`Failed to configure YourLibrary plugin: ${error.message}`);
  }
};
```
## 替代构建方法
如果您的库不使用 `expo-module-scripts`，您有两个选项：
### 将插件添加到您的主包
对于使用不同构建工具的库（如使用 `create-react-native-library` 创建的库），添加一个 **app.plugin.js** 文件并与您的主包一起构建：
```js app.plugin.js
module.exports = require('./lib/plugin');
```
### 创建独立的插件包
一些库将其配置插件作为与其主库分开的独立包分发。这种方法允许您独立于其余的本地模块维护您的配置插件。您需要在 **app.plugin.js** 中包含导出并从您的插件编译 **build** 目录。
```js app.plugin.js
{
  "name": "your-library-expo-plugin",
  "main": "app.plugin.js",
  "files": ["app.plugin.js", "build/"],
  "peerDependencies": {
    "expo": "*",
    "your-library": "*"
  }
}
```
## 插件开发最佳实践
- **在您的 README 中提供说明**：如果插件与 React Native 模块相关，则应为该包记录手动设置说明。如果插件出现任何问题，开发者应该能够手动添加插件自动化的项目修改。这还允许您支持未使用 [CNG](/workflow/continuous-native-generation/) 的项目。
  - 记录插件可用属性，指明是否需要任何属性。
  - 如果可能，插件应为幂等的，这意味着无论是在新的本地项目模板上运行还是在已经存在其更改的项目模板上运行，它们所做的更改都是相同的。这允许开发者在不使用 `--clean` 标志的情况下运行 `npx expo prebuild` 来同步配置的更改，而不是完全重新创建本地项目。这在危险的修改下可能更困难。
- **命名约定**：如果插件适用所有平台，则使用 `withFeatureName` 作为插件函数名称。如果插件是平台特定的，则在 “with” 后直接使用 camel case 命名平台名称。例如，`withAndroidSplash`，`withIosSplash`。
- **利用内置插件**：如果在 [应用配置](/versions/latest/config/app/) 和 [预构建配置](https://github.com/expo/expo/blob/main/packages/%40expo/prebuild-config/src/plugins/withDefaultPlugins.ts) 中已经有可用配置，则无需为其编写配置插件。
- **按平台拆分插件**：在使用配置插件中的函数时，按平台拆分它们。例如，`withAndroidSplash`，`withIosSplash`。这使得在 `npx expo prebuild` 中使用 `--platform` 标志更容易跟随，因为日志将显示正在执行的特定于平台的函数。
- **单元测试您的插件**：为复杂的修改编写 Jest 测试。如果您的插件需要访问文件系统，使用模拟系统（我们强烈推荐 [`memfs`](https://www.npmjs.com/package/memfs)），您可以在 [`expo-notifications`](https://github.com/expo/expo/blob/fc3fb2e81ad3a62332fa1ba6956c1df1c3186464/packages/expo-notifications/plugin/src/__tests__/withNotificationsAndroid-test.ts#L34) 插件测试中看到此类示例。
  - 请注意根 [\*\*/\_\_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)。
- TypeScript 插件总是优于 JavaScript 插件，因为它具有更高的类型安全性。有关更多信息，请查看 [`expo-module-scripts` 插件](https://github.com/expo/expo/tree/main/packages/expo-module-scripts#-config-plugin) 工具。
- 请勿通过配置插件修改 `sdkVersion`，这可能会破坏 `expo install` 等命令并导致其他意外问题。


## 开发和调试插件

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

开发插件是扩展 Expo 生态系统的好方法。然而，有时你需要调试你的插件。本页面提供了一些开发和调试插件的最佳实践。
## 插件开发
> 使用 [modifier previews](https://github.com/expo/vscode-expo#expo-preview-modifier) 实时调试插件的结果。
为了简化插件开发，我们已将插件支持添加到 [`expo-module-scripts`](https://www.npmjs.com/package/expo-module-scripts) 中。
有关使用 TypeScript 和 Jest 构建插件的更多信息，请参考 [config plugins guide](https://github.com/expo/expo/tree/main/packages/expo-module-scripts#-config-plugin)。
### 安装依赖
在提供配置插件的库中使用以下依赖：
```json package.json
{
  "dependencies": {},
  "devDependencies": {
    "expo": "^54.0.0"
  },
  "peerDependencies": {
    "expo": ">=54.0.0"
  },
  "peerDependenciesMeta": {
    "expo": {
      "optional": true
    }
  }
}
```
- 你可以更新 `expo` 的确切版本，以构建特定版本。
- 对于依赖核心稳定 API 的简单配置插件，例如仅修改 **AndroidManifest.xml** 或 **Info.plist** 的插件，可以使用如上示例中的松散依赖。
- 你可能还想将 [`expo-module-scripts`](https://github.com/expo/expo/blob/main/packages/expo-module-scripts/README.md) 安装为开发依赖，但这并不是必需的。
### 导入配置插件包
`expo/config-plugins` 和 `expo/config` 包从 `expo` 包中重新导出。
```js
const { ... } = require('expo/config-plugins');
const { ... } = require('expo/config');
```
通过 `expo` 包导入可以确保使用与 `expo` 包所依赖的 `expo/config-plugins` 和 `expo/config` 包的版本。
如果不通过这种方式导入包，你可能意外地导入了不兼容的版本（这取决于开发人员所用的包管理器中的模块提升实现细节），或者根本无法导入模块（如果使用例如 Yarn Berry 或 pnpm 的“即插即用”功能）。
配置类型直接从 `expo/config` 导出，因此无需安装或从 `expo/config-types` 导入：
```ts
import { ExpoConfig, ConfigContext } from 'expo/config';
```
### 模块的最佳实践
- 避免使用正则表达式：[静态修改](#static-modification) 是关键。如果你想修改 Android gradle 文件中的某个值，请考虑使用 `gradle.properties`。如果你想修改 Podfile 中的一些代码，请考虑写入 JSON 并让 Podfile 读取静态值。
- 避免在模块中执行长期任务，比如发起网络请求或安装 Node 模块。
- 不要在模块中添加交互式终端提示。
- 仅在危险的模块中生成、移动和删除新文件。不这样做会破坏 [自省](#introspection)。
- 利用内置的配置插件，如 `withXcodeProject`，以最小化文件读取和解析的次数。
- 坚持使用预编译内部使用的 XML 解析库，这有助于防止不必要的代码重排。
## 插件结构与脚手架
### 版本控制
默认情况下，`npx expo prebuild` 对与项目使用的 Expo SDK 版本相关联的 [源模板](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum) 运行转换。SDK 版本定义在 **app.json** 中，或从项目安装的 `expo` 的版本推断。
例如，当 Expo SDK 升级到新版本的 React Native 时，模板可能会进行重大更改，以考虑 React Native 的变化或 Android 或 iOS 的新版本。
如果你的插件主要使用 [静态修改](#static-modification)，那么它通常可以在 SDK 版本间良好工作。如果它使用正则表达式来转换应用代码，那么你确实需要记录你的插件适用的 Expo SDK 版本。在 SDK 发布周期中，有一个 [beta 期间](https://github.com/expo/expo/blob/main/guides/releasing/Release%20Workflow.md#stage-4---beta-release)，你可以在新版本发布之前测试插件的工作情况。
### 插件属性
属性用于自定义插件在预构建期间的工作方式。它们必须始终是静态值（不支持函数或 Promise）。考虑以下类型：
```ts
type StaticValue = boolean | number | string | null | StaticArray | StaticObject;
type StaticArray = StaticValue[];
interface StaticObject {
  [key: string]: StaticValue | undefined;
}
```
静态属性是必需的，因为应用配置必须可序列化为 JSON，以用作应用清单。
如果可能，尽量让你的插件在没有 props 的情况下工作，这将帮助解析工具，如 [`expo install`](#expo-install) 或 [VS Code Expo Tools](https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools) 更好地工作。请记住，每个你添加的属性都会增加复杂性，使将来更难以更改，并增加需要测试的功能数量。良好的默认值优于必要的配置（如果可行）。
## 开发环境
### 工具
我们强烈建议安装 [Expo Tools VS Code extension](https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools)，因为这将对插件进行自动验证，并提供错误信息以及其他配置插件开发的生活质量改进。
### 设置一个游乐场环境
你可以使用 JS 轻松开发插件，但如果你想设置 Jest 测试并使用 TypeScript，则需要一个单一代码仓库（monorepo）。
单一代码仓库使你能够像在 npm 中发布一样，在应用配置中导入一个 Node 模块。Expo 配置插件内置完全支持单一代码仓库，因此你所需要做的就是设置一个项目。
在你单一代码仓库的 `packages/` 目录中，创建一个模块，并在其中 [引导配置插件](https://github.com/expo/expo/tree/main/packages/expo-module-scripts#-config-plugin)。
### 手动运行插件
如果你不熟悉设置单一代码仓库，你可以尝试手动运行插件：
- 在具有配置插件的包中运行 `npm pack`
- 在你的测试项目中运行 `npm install path/to/react-native-my-package-1.0.0.tgz`，这将把包添加到你的 **package.json** `dependencies` 对象中。
- 将包添加到你的 **app.json** 中的 `plugins` 数组： `{ "plugins": ["react-native-my-package"] }`
  - 如果你已经安装 [VS Code Expo Tools](https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools)，自动完成功能应该能正常工作。
- 如果你需要更新包，更改包的 **package.json** 中的 `version` 并重复该过程。
## 使用插件修改本机文件
### 修改 AndroidManifest.xml
包应该尝试在使用配置插件之前使用内置的 **AndroidManifest.xml** [合并系统](https://developer.android.com/studio/build/manage-manifests)。这可以用于静态的、非可选的特性，如权限。这将确保特性在构建时合并，而不是在预构建时，从而减少由于用户忘记预构建而遗漏配置的可能性。缺点是用户无法使用 [自省](#introspection) 来预览更改和调试潜在问题。
这是一个包的 **AndroidManifest.xml** 示例，注入了所需的权限：
```xml AndroidManifest.xml
<!-- @info 包含 <code>xmlns:android="..."</code> 以在你的清单中使用 <code>android:*</code> 属性，如 <code>android:name</code>。 -->
<manifest package="expo.modules.filesystem" xmlns:android="http://schemas.android.com/apk/res/android">
  <!-- @end -->
  <uses-permission android:name="android.permission.INTERNET"/>
</manifest>
```
如果你正在为本地项目构建插件，或者如果你的包需要更多的控制，那么你应该实现一个插件。
你可以使用内置的类型和帮助程序来简化处理复杂对象的过程。
这是一个将 `<meta-data android:name="..." android:value="..."/>` 添加到默认 `<application android:name=".MainApplication" />` 的示例。
```ts my-config-plugin.ts
import { AndroidConfig, ConfigPlugin, withAndroidManifest } from 'expo/config-plugins';
import { ExpoConfig } from 'expo/config';
// 使用帮助程序使错误消息统一，并帮助减少 XML 格式更改。
const { addMetaDataItemToMainApplication, getMainApplicationOrThrow } = AndroidConfig.Manifest;
export const withMyCustomConfig: ConfigPlugin = config => {
  return withAndroidManifest(config, async config => {
    // 修改器可以是异步的，但尽量保持快速。
    config.modResults = await setCustomConfigAsync(config, config.modResults);
    return config;
  });
};
// 将此函数从修改中分离出来，可以更轻松地进行测试。
async function setCustomConfigAsync(
  config: Pick<ExpoConfig, 'android'>,
  androidManifest: AndroidConfig.Manifest.AndroidManifest
): Promise<AndroidConfig.Manifest.AndroidManifest> {
  const appId = 'my-app-id';
  // 获取 <application /> 标签，并在不存在时断言它。
  const mainApplication = getMainApplicationOrThrow(androidManifest);
  addMetaDataItemToMainApplication(
    mainApplication,
    // `android:name` 的值
    'my-app-id-key',
    // `android:value` 的值
    appId
  );
  return androidManifest;
}
```
### 修改 Info.plist
使用 `withInfoPlist` 比在 **app.json** 中静态修改 `expo.ios.infoPlist` 对象更安全，因为它读取 Info.plist 的内容并将其与 `expo.ios.infoPlist` 合并，这意味着你可以尝试保持你的更改不被覆盖。
这是一个将 `GADApplicationIdentifier` 添加到 **Info.plist** 的示例：
```ts my-config-plugin.ts
import { ConfigPlugin, withInfoPlist } from 'expo/config-plugins';
// 传递 `<string>` 以指定此插件需要一个字符串属性。
export const withCustomConfig: ConfigPlugin<string> = (config, id) => {
  return withInfoPlist(config, config => {
    config.modResults.GADApplicationIdentifier = id;
    return config;
  });
};
```
### 修改 iOS Podfile
iOS **Podfile** 是 CocoaPods 的配置文件，是 iOS 的依赖管理器。它类似于 iOS 的 **package.json**。
**Podfile** 是一个 Ruby 文件，这意味着你 **不能** 安全地从 Expo 配置插件中修改它，而应该选择其他方法，例如 [Expo Autolinking](/modules/autolinking) 钩子。
我们确实提供了一种与 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 引擎。
### 将插件添加到 `pluginHistory`
`_internal.pluginHistory` 被创建以防止在从遗留的 UNVERSIONED 插件迁移到版本控制插件时重复执行插件。
```ts my-config-plugin.ts
import { ConfigPlugin, createRunOncePlugin } from 'expo/config-plugins';
// 保持名称和版本与其包同步。
const pkg = require('my-cool-plugin/package.json');
const withMyCoolPlugin: ConfigPlugin = config => config;
// 一个帮助方法，包装 `withRunOnce` 并将项目附加到 `pluginHistory`。
export default createRunOncePlugin(
  // 要保护的插件。
  withMyCoolPlugin,
  // 用于跟踪插件是否已运行的标识符。
  pkg.name,
  // 可选版本属性，如果省略，默认为 UNVERSIONED。
  pkg.version
);
```
### 配置 Android 应用启动
你可能会发现你的项目需要在 JS 引擎启动之前设置配置。
例如，在 Android 的 `expo-splash-screen` 中，我们需要在 **MainActivity.java** 的 `onCreate` 方法中指定缩放模式。
我们不尝试通过危险的修改将这些更改注入到 `MainActivity` 中，而是使用生命周期钩子和静态设置的系统
安全地确保特性在所有支持的 Android 语言（Java、Kotlin）、Expo 版本和配置插件组合中有效。
该系统由三个组件组成：
- `ReactActivityLifecycleListeners`: 一个接口，由 `expo-modules-core` 提供，用于在项目的 `ReactActivity` 的 `onCreate` 方法被调用时获取本机回调。
- `withStringsXml`: 一个由 `expo/config-plugins` 提供的修改器，它将一个属性写入 Android **strings.xml** 文件，库可以安全地读取 strings.xml 值并做初始设置。字符串 XML 值遵循指定格式以保持一致性。
- `SingletonModule`（可选）：一个由 `expo-modules-core` 提供的接口，用于在本机模块和 `ReactActivityLifecycleListeners` 之间创建共享接口。
考虑这个例子：我们希望在 `onCreate` 方法被调用后，直接将一个自定义的“值”字符串设置为 Android `Activity` 的一个属性。
我们可以通过创建 Node 模块 `expo-custom`，实现 `expo-modules-core` 和 Expo 配置插件来安全地完成这一点：
首先，我们在 Android 本机模块中注册 `ReactActivity` 监听器，只有在用户在其项目中有 `expo-modules-core` 支持时，这将被调用（在使用 Expo CLI、Create React Native App、Ignite CLI 和 Expo 预构建引导的项目中默认设置）。
```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** 文件中读取。
```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?) {
    // 在 JS 引擎启动之前执行静态任务。
    // 这些值是通过配置插件定义的。
    var value = getValue(activity)
    if (value != "") {
      // 做一些需要静态值的 Activity 处理...
    }
  }
  // 命名是节点模块名（`expo-custom`）加上值名（`value`）使用下划线作为分隔符
  // 例如 `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` 属性进行本地覆盖。
```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` 支持）：
```xml ./android/app/src/main/res/values/strings.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="expo_custom_value" translatable="false">我爱 Expo</string>
</resources>
```
对于托管用户，我们可以通过 Expo 配置插件（安全地）公开此功能：
```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) {
  // 帮助程序，用于添加 string.xml JSON 项目或使用相同名称覆盖现有项目。
  return AndroidConfig.Strings.setStringItem(
    [
      // 表示为 JSON 的 XML
      // <string name="expo_custom_value" translatable="false">值</string>
      { $: { name: 'expo_custom_value', translatable: 'false' }, _: value },
    ],
    strings
  );
}
```
托管 Expo 用户现在可以像这样使用此 API：
```json app.json
{
  "expo": {
    "plugins": [["expo-custom", "I Love Expo"]]
  }
}
```
通过重新运行 `npx expo prebuild -p`（`eas build -p android`，或 `npx expo run:ios`），用户现在可以看到在其托管项目中安全应用的更改！
从示例中可以看出，我们在与应用代码（expo-modules-core）交互时高度依赖应用代码（本机项目）。这确保了我们的配置插件安全可靠，希望能够长久使用！
## 调试配置插件
你可以通过运行 `EXPO_DEBUG=1 expo prebuild` 来调试配置插件。如果启用 `EXPO_DEBUG`，插件堆栈日志将被打印，这对于查看运行了哪些修改以及它们运行的顺序非常有用。要查看所有静态插件解析错误，请启用 `EXPO_CONFIG_PLUGIN_VERBOSE_ERRORS`，这通常只有在插件作者需要时才需要。默认情况下，某些自动插件错误是隐藏的，因为它们通常与版本问题有关，并不是很有帮助（也就是说，遗留包尚未具备配置插件）。
运行 `npx expo prebuild --clean` 将在编译之前删除生成的本机目录。
你还可以运行 `npx expo config --type prebuild` 打印插件的结果，未评估的 mods（不会生成代码）。
Expo CLI 命令可以使用 `EXPO_PROFILE=1` 进行性能分析。
## 自省
自省是一种先进的技术，用于读取修饰符的评估结果，而不生成项目中的任何代码。
这可以用于快速调试 [静态修改](#static-modification) 的结果，而无需运行预构建。
你可以通过使用 `vscode-expo` 的 [预览特性](https://github.com/expo/vscode-expo#expo-preview-modifier) 实时与自省交互。
你可以尝试通过在项目中运行 `expo config --type introspect` 进行自省。
自省仅支持一部分修改器：
- `android.manifest`
- `android.gradleProperties`
- `android.strings`
- `android.colors`
- `android.colorsNight`
- `android.styles`
- `ios.infoPlist`
- `ios.entitlements`
- `ios.expoPlist`
- `ios.podfileProperties`
> 自省仅适用于安全的修饰符（静态文件，如 JSON、XML、plist、properties），除了 `ios.xcodeproj`，因为它通常需要文件系统更改，使其不可重复执行。
自省通过创建与默认基础方法类似的自定义基础方法工作，只是它们在最后不会将 `modResults` 写入磁盘。
它们并不持久，而是将结果保存到应用配置中的 `_internal.modResults` 下，后面跟着 mod 的名称，例如 `ios.infoPlist` mod 保存到 `_internal.modResults.ios.infoPlist: {}`。
作为实例，自省被 `eas-cli` 用于确定托管应用中最终的 iOS 权限，以便在构建之前能够与 Apple 开发者门户同步。自省也可作为便利的调试和开发工具使用。
## 遗留插件
为了使 `eas build` 的工作方式与经典的 `expo build` 服务相同，我们添加了对 “遗留插件”的支持，这些插件在项目中安装后会自动应用。
例如，假设项目中安装了 `expo-camera`，但在其 **app.json** 中没有 `plugins: ['expo-camera']`。
Expo CLI 会自动将 `expo-camera` 添加到插件中，以确保所需的相机和麦克风权限被添加到项目中。
用户仍然可以通过手动将其添加到 `plugins` 数组来定制 `expo-camera` 插件，手动定义的插件将优先于自动插件。
你可以通过运行 `expo config --type prebuild` 和查看 `_internal.pluginHistory` 属性来调试添加了哪些插件。
这将显示一个对象，其中包含使用来自 `expo/config-plugins` 的 `withRunOnce` 添加的所有插件。
注意，`expo-location` 使用 `version: '11.0.0'`，而 `react-native-maps` 使用 `version: 'UNVERSIONED'`。这意味着：
- `expo-location` 和 `react-native-maps` 都已安装在项目中。
- `expo-location` 正在使用来自项目的 `node_modules/expo-location/app.plugin.js` 的插件。
- 安装在项目中的 `react-native-maps` 的版本没有插件，因此它退回到随 `expo-cli` 发货的未经版本控制的插件，以支持遗留功能。
```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 本机代码或插件发生重大更改，会中断项目预构建的方式，导致构建错误。
## 静态修改
插件可以使用正则表达式转换应用代码，但如果模板随时间而变化，这些修改是危险的，那么正则表达式就变得难以预测（类似于用户手动修改文件或使用自定义模板）。以下是一些不应手动修改的文件示例，以及替代方案。
### Android Gradle 文件
Gradle 文件使用 Groovy 或 Kotlin 编写。它们用于管理依赖、版本控制和 Android 应用中的其他设置。
不要使用 `withProjectBuildGradle`、`withAppBuildGradle` 或 `withSettingsGradle` 方法直接修改它们，而是利用静态的 `gradle.properties` 文件。
`gradle.properties` 是静态的键/值对，Groovy 文件可以读取。例如，假设你想控制 Groovy 中的某个开关：
```properties gradle.properties
# @info 使用 <code>withGradleProperties()</code> 修改。 #
expo.react.jsEngine=hermes
# @end #
```
然后在 Gradle 文件中：
```groovy app/build.gradle
```
- 对于 `gradle.properties` 中的键，使用以 `.` 分隔的 camel case，通常以 `expo` 前缀开头，以表示该属性由预构建管理。
- 要访问属性，使用两种全局方法之一：
  - `property`：获取属性，如果未定义则抛出错误。
  - `findProperty`：在属性缺失时不抛出错误获取属性。这通常可以与 `?:` 操作符一同使用，以提供默认值。
通常，你应仅通过 Expo [Auto-linking](/more/glossary-of-terms/#autolinking) 与 Gradle 文件交互，这提供了与项目文件的编程接口。
### iOS AppDelegate
某些模块可能需要将代理方法添加到项目 AppDelegate。这可以通过使用 [AppDelegate subscribers](/modules/appdelegate-subscribers/) 安全完成，或者通过 `withAppDelegate` 方法冒险执行（_强烈不推荐_）。
使用 AppDelegate 订阅者可以让本机 Expo 模块以安全可靠的方式响应重要事件。
以下是 AppDelegate 订阅者作用的示例。此外，你会在 GitHub 上的社区仓库中找到许多示例（[其中一个示例](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)
### iOS CocoaPods Podfile
**Podfile** 可以通过正则表达式进行自定义（这被认为是危险的，因为这些类型的更改不易组合，多次更改可能会发生冲突），但更可靠的方法是在一个名为 **Podfile.properties.json** 的 JSON 文件中设置配置值。请查看以下如何使用 `podfile_properties` 自定义 **Podfile**：
```ruby Podfile
require 'json'
# @info 导入并解析 JSON 文件 #
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 [Auto-linking](/more/glossary-of-terms/#autolinking) 与 Podfile 交互，这提供了与项目文件的编程接口。
### 自定义基础修改器
Expo CLI `npx expo prebuild` 命令使用 [`@expo/prebuild-config`](https://github.com/expo/expo/tree/main/packages/%40expo/prebuild-config) 来获取默认基础修饰符。这些默认值仅管理一小部分常见文件，如果你想管理自定义文件，可以通过添加新的基础修饰符在本地实现。
例如，假设你想要增加对管理 `ios/*/AppDelegate.h` 文件的支持，你可以通过添加一个 `ios.appDelegateHeader` 修改器来完成。
> 这个示例使用 `tsx` 来便于简单的本地 TypeScript 支持，这并不是严格必要的。 [了解更多](/guides/typescript/#appconfigjs)。
```ts withAppDelegateHeaderBaseMod.ts
import { ConfigPlugin, IOSConfig, Mod, withMod, BaseMods } from 'expo/config-plugins';
import fs from 'fs';
/**
 * 一个插件，向预构建配置添加新的基础修改器。
 */
export function withAppDelegateHeaderBaseMod(config) {
  return BaseMods.withGeneratedBaseMods<'appDelegateHeader'>(config, {
    platform: 'ios',
    providers: {
      // 附加一个自定义规则，以向 `mods.ios.appDelegateHeader` 提供 AppDelegate 头文件数据
      appDelegateHeader: BaseMods.provider<IOSConfig.Paths.AppDelegateProjectFile>({
        // 获取应传递给 `read` 方法的本地文件路径。
        getFilePath({ modRequest: { projectRoot } }) {
          const filePath = IOSConfig.Paths.getAppDelegateFilePath(projectRoot);
          // 将 .m 替换为 .h
          if (filePath.endsWith('.m')) {
            return filePath.substr(0, filePath.lastIndexOf('.')) + '.h';
          }
          // 可能是一个 Swift 项目...
          throw new Error(`Could not locate a valid AppDelegate.h at root: "${projectRoot}"`);
        },
        // 从文件系统读取输入文件。
        async read(filePath) {
          return IOSConfig.Paths.getFileInfo(filePath);
        },
        // 将结果输出到文件系统。
        async write(filePath: string, { modResults: { contents } }) {
          await fs.promises.writeFile(filePath, contents);
        },
      }),
    },
  });
}
/**
 * （工具）提供用于修改的 AppDelegate 头文件。
 */
export const withAppDelegateHeader: ConfigPlugin<Mod<IOSConfig.Paths.AppDelegateProjectFile>> = (
  config,
  action
) => {
  return withMod(config, {
    platform: 'ios',
    mod: 'appDelegateHeader',
    action,
  });
};
// （示例）记录修改器的内容。
export const withSimpleAppDelegateHeaderMod = config => {
  return withAppDelegateHeader(config, config => {
    console.log('modify header:', config.modResults);
    return config;
  });
};
```
要使用这个新的基础 mod，请将其添加到插件数组中。基础 mod **MUST** 最后添加在所有使用该 mod 的其他插件之后，原因是它必须在过程结束时将结果写入磁盘。
```js app.config.js
// 用于使用 TS 的外部文件
require('tsx/cjs');
import {
  withAppDelegateHeaderBaseMod,
  withSimpleAppDelegateHeaderMod,
} from './withAppDelegateHeaderBaseMod.ts';
export default ({ config }) => {
  if (!config.plugins) config.plugins = [];
  config.plugins.push(
    withSimpleAppDelegateHeaderMod,
    // 基础 mods 必须最后
    withAppDelegateHeaderBaseMod
  );
  return config;
};
```
有关更多信息，请参见 [添加支持的 PR](https://github.com/expo/expo-cli/pull/3852)。
## expo install
当使用 `npx expo install` 命令安装节点模块时，如果它包含配置插件，它将自动添加到项目的应用配置中。这简化了设置并帮助防止用户忘记添加插件。然而，这确实带来了一些注意事项：
1. `npx expo install` 仅将使用根 **app.config.js** 文件的配置插件自动添加到应用清单中。此规则是为了防止像 `lodash` 这样的流行包被误认为是配置插件而导致预构建失败。
2. 当前没有检测配置插件是否具有强制属性的机制。因此，`expo install` 将仅添加插件，而不尝试添加任何额外的属性。例如，`expo-camera` 具有可选的额外属性，因此 `plugins: ['expo-camera']` 是有效的，但如果它有强制属性，那么 `expo-camera` 将引发错误。
3. 只有当用户的项目使用静态应用配置（**app.json** 和 **app.config.json**）时，插件才可以自动添加。如果用户在使用 **app.config.js** 的项目中运行 `expo install expo-camera`，他们将看到如下警告：
```sh
无法自动写入动态配置：app.config.js
请将以下内容添加到你的应用配置中
{
  "plugins": [
    "expo-camera"
  ]
}
```


## 使用 patch-project

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

> **important** **注意**: `patch-project` 是一个实验性功能。
`patch-project` 是一个 Expo 配置插件和命令行界面 (CLI) 工具，用于生成和应用补丁，以在运行 `npx expo prebuild` 后保留原生更改。该工具对希望保留自定义的原生应用开发者非常有用，而不需要了解如何编写配置插件，有效地生成与 [持续原生生成 (CNG)](/workflow/continuous-native-generation/) 兼容的自动解决方案。
本指南解释了如何使用 `patch-project`、什么时候使用它及其限制。
## patch-project 的工作原理
`patch-project` 采用了一种生成并自动应用补丁的方法，灵感来自 Git。使用该命令行工具需要在您的项目中执行以下步骤：
### 安装
要开始使用，您需要在您的项目中安装该工具：
```sh
$ npx expo install patch-project
```
此命令将自动将 `patch-project` 配置插件添加到您的 [app config](/workflow/configuration/) 中：
```json app.json
{
  "expo": {
    "plugins": [
      "patch-project"
    ]
  }
}
```
### 从现有自定义生成补丁
假设您手动修改了项目中的原生目录 (**android** 和 **ios**)。要为这些原生目录生成补丁，您可以运行以下命令：
```sh
$ npx patch-project
```
> **info** **注意**: 在您想为特定平台生成补丁的情况下，可以使用 `--platform` 选项并运行 `npx patch-project --platform android` 或 `npx patch-project --platform ios`。
生成的补丁将保存在 **cng-patches** 目录中。
```
./
    ├── app.json  # 带 patch-project 插件
    ├── cng-patches/
    │   ├── android+eee880ad7b07965271d2323f7057a2b4.patch  # android 目录的补丁
    │   └── ios+eee880ad7b07965271d2323f7057a2b4.patch  # ios 目录的补丁
    ├── package.json
    └── ...  # 其他项目文件
```
每个文件将以平台的名称前缀，并加上校验和值。例如：
```bash
ios+eee880ad7b07965271d2323f7057a2b4.patch
```
### 在预构建期间应用补丁
一旦您生成了补丁，它们将在随后的 `npx expo prebuild` 命令运行时自动应用。`patch-project` 配置插件会检测现有补丁并将其应用，以恢复您的自定义设置。
## 何时使用 patch-project
您可以在以下情况下使用 `patch-project`：
- **迁移现有的 React Native 应用**，因为它们包含大量原生自定义，重新创建这些原生自定义作为配置插件将非常耗时。
- **保留手动更改**，这些更改是在转向采用持续原生生成 (CNG) 的 Expo 项目中进行的 **android** 和/或 **ios** 目录中。
- **快速原型制作**，当您需要在编写配置插件之前测试原生更改时。
- **补丁将在随后的 `npx expo prebuild` 命令运行时自动应用**。与 `patch-package` 等工具相比，这是一个优势（常用于为 npm 库生成补丁），后者在预构建过程中并不会保留和自动应用补丁。
## 限制和注意事项
在升级 Expo SDK 版本时，补丁可能会失效，因为：
- **模板和/或文件结构更改**：预构建模板在 SDK 版本之间演进，带有新的更改和原生目录中的文件更新。这将影响已生成的 **cng-patches** 目录中的差异，可能不再适用。
- **插件冲突**：CNG 补丁可能会很危险，并且当其他插件修改同一文件时可能会出现问题。例如，如果您添加一个新的插件更新 **MainApplication.kt** 并与现有补丁冲突，则补丁可能无法正确应用。在这种情况下，您可能需要重新生成补丁。
- **iOS .pbxproj 更改**：在 iOS 项目中，将补丁应用于 **.pbxproj** 文件可能会很脆弱，因为该文件包含 UUID，运行命令如 `npx expo prebuild --clean` 可能会更改这些 ID。例如，如果您正在添加小部件扩展或进行其他项目配置更改，基于补丁的方法可能无法可靠工作。您可以查看生成的 **cng-patches/ios-\*** 并仅保留必要的补丁。将补丁保持尽可能小将减少应用补丁时失败的风险。
建议在每次 SDK 升级后重新生成补丁。


# 调试

## 错误和警告

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

在使用 Expo 开发应用程序时，您将遇到 **Redbox** 错误或 **Yellowbox** 警告。这些日志体验是由 [React Native 中的 LogBox](https://reactnative.dev/blog/2020/07/06/version-0.63) 提供的。
## Redbox 错误和 Yellowbox 警告
当致命错误阻止您的应用程序运行时，将显示 Redbox 错误。当有可能存在问题时，将显示 Yellowbox 警告，以通知您在发布应用程序之前应该解决它。
您还可以通过 `console.warn("Warning message")` 和 `console.error("Error message")` 自己创建警告和错误。触发 redbox 的另一种方法是抛出错误而不捕获它：`throw Error("Error message")`。
> 这是使用 Expo CLI 调试 React Native 应用程序的简要介绍。有关深入信息，请参见 [调试](/debugging/runtime-issues/)。
## 堆栈跟踪
当您在开发过程中遇到错误时，您将看到错误消息和 **堆栈跟踪**，这是一份您的应用程序崩溃时所做最近调用的报告。此堆栈跟踪同时显示在您的终端和 Expo Go 应用中，或者如果您创建了开发构建。
此堆栈跟踪是 **极其有价值** 的，因为它为您提供了错误发生的位置。例如，在下图中，错误发生在文件 **HomeScreen.js** 中，并且是在该文件的第 7 行引起的。
当您查看该文件时，在第 7 行，您将看到一个名为 `renderDescription` 的变量被引用。错误消息描述该变量未找到，因为该变量未在 **HomeScreen.js** 中声明。这是如何利用错误消息和堆栈跟踪的典型示例，如果您花时间去解读它们。
调试错误是开发过程中最令人沮丧但又最令人满意的部分之一。请记住，您从不是孤单的。**Expo 社区**以及 React 和 React Native 社区都是您遇到困难时的良好资源。很有可能还有其他人遇到了您的确切错误。确保阅读文档，搜索 [论坛](https://chat.expo.dev/)、[GitHub 问题](https://github.com/expo/expo/issues/) 和 [Stack Overflow](https://stackoverflow.com/)。


## 调试运行时问题

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

无论您是在本地开发应用、将其发送给选定的测试者，还是将应用上线到应用商店，您总会遇到调试问题。将错误分为两类是很有用的：
- 在开发过程中遇到的错误
- 您（或您的用户）在生产环境中遇到的错误
让我们看看在处理上述每种情况时的推荐做法。
## 开发错误
这些是您在开发应用时常见的错误。深入研究它们并不总是直接的。通常，在使用 [Expo CLI](/more/expo-cli/) 运行应用时调试就足够了。
调试这些问题的一种方法是查看 [堆栈跟踪](/debugging/errors-and-warnings/#stack-traces)。但是，在某些情况下，查看堆栈跟踪并不足够，因为跟踪的错误消息可能有些模糊。对于此类错误，请按以下步骤操作：
- 在 Google 和 [Stack Overflow](https://stackoverflow.com/questions) 中搜索错误消息，您很可能不是第一个遇到此问题的人。
- **隔离抛出错误的代码**。这一步是 _至关重要的_，用以修复模糊错误。为此：
  - 恢复到工作版本的代码。这甚至可以是一个完全空白的 `npx create-expo-app` 项目。
  - 一步一步应用您最近的更改，直到它崩溃。
  - 如果您在每一“片段”中添加的代码很复杂，您可能想简化您的操作。例如，如果您使用状态管理库如 Redux，您可以尝试完全移除它来查看问题是否出在您的状态管理上（这是 React 应用中常见的问题）。
  - 这样可以缩小错误的可能来源，并为您提供更多信息，以便在互联网上搜索其他遇到同样问题的人。
- 使用断点（或 `console.log`）检查并确保某段代码在运行，或者某个变量具有特定值。使用 `console.log` 进行调试并不被视为最佳实践，然而，它快速、简单，且往往提供一些有启发性的信息。
尽可能简化代码以追踪错误源是一种很好的调试应用的方法，而且这个过程会变得越来越容易。这就是为什么许多开源代码库要求在您提交问题时提供 [最小可重现示例](https://stackoverflow.com/help/minimal-reproducible-example)。这确保您已经隔离了问题并确切找到了问题发生的位置。如果您的应用过于庞大和复杂无法做到这一点，尝试在一个空白的 `npx create-expo-app` 项目中提取您尝试添加的功能，然后从那里开始。
### 原生调试
您可以通过在本地生成源代码并从该源构建来使用 Android Studio 和 Xcode 进行完整的原生调试。
#### Android Studio
Step 1: 
通过运行以下命令生成您的项目的原生代码：
```sh
$ npx expo prebuild -p android
```
这将在您的项目根目录添加一个 **android** 目录。
Step 2: 
通过运行命令在 Android Studio 中打开项目：
```sh
$ open -a "/Applications/Android Studio.app" ./android
```
Step 3: 
从 Android Studio 构建应用并连接调试器。有关更多信息，请参见 [Google 的文档](https://developer.android.com/studio/debug#startdebug)。
> 完成此过程后，您可以删除 **android** 目录。这确保您的项目仍由 Expo CLI 管理。保留该目录并在 `npx expo prebuild` 之外手动修改它，意味着您需要手动升级和配置原生库。
#### Xcode
> 此功能仅适用于 macOS 用户，并要求安装 Xcode。
Step 1: 
通过运行以下命令生成您的项目的原生代码：
```sh
$ npx expo prebuild -p ios
```
这将在您的项目根目录添加一个 **ios** 目录。
Step 2: 
通过运行命令打开 Xcode 中的项目，这是打开您项目的 **ios** 目录下 `.xcworkspace` 文件的快捷方式。
```sh
$ xed ios
```
Step 3: 
使用 <kbd>Cmd ⌘</kbd> + <kbd>r</kbd> 或按下 Xcode 左上角的播放按钮来构建应用。
Step 4: 
您现在可以利用 [**低级调试器 (LLDB)**](https://developer.apple.com/library/archive/documentation/IDEs/Conceptual/gdb_to_lldb_transition_guide/document/Introduction.html) 及所有其他 [Xcode 调试工具](https://developer.apple.com/documentation/metal/debugging_tools) 来检查原生运行时。
> 完成此过程后，您可以删除 **ios** 目录。这确保您的项目仍由 Expo CLI 管理。保留该目录并在 `npx expo prebuild` 之外手动修改它，意味着您需要手动升级和配置原生库。
## 生产错误
您在生产应用中遇到的错误或漏洞可能更难解决，主要由于您对错误的上下文了解较少（即，错误发生的地点、方式和原因是什么？）。
**解决生产错误的最佳第一步是本地重现它。** 一旦您在本地重现了错误，您可以按照 [开发调试过程](#development-errors) 隔离并解决根本原因。
> **info** **提示**：有时，在本地以 **生产模式** 运行应用会显示通常不会抛出的错误。您可以通过运行 `npx expo start --no-dev --minify` 在本地按生产模式运行应用。
> `--no-dev` 告诉服务器不要以开发模式运行，而 `--minify` 用于以与生产 JavaScript 包相同的方式压缩您的代码。
### 生产应用崩溃
当生产应用崩溃时，这可能是一个令人沮丧的情况。当发生崩溃时，几乎没有信息可以查看。重现这个问题很重要，即使您无法做到这一点，也要找到相关的崩溃报告。
首先使用您的生产应用重现崩溃，然后 **找到相关的崩溃报告**。对于 Android，您可以使用 `adb logcat`，对于 iOS，您可以使用 Xcode 中的控制台应用。
Video Tutorial: [如何使用 Logcat 和 macOS 控制台进行调试](https://www.youtube.com/watch?v=LvCci4Bwmpc)
#### 使用 adb logcat 查看崩溃报告
如果您的 Android 应用在 Google Play 上，请查看 [Google Play 控制台](https://play.google.com/console/about/) 的崩溃部分，或将 Android 设备连接到计算机并运行以下命令：
```sh
$ adb logcat
```
Android 调试桥 (`adb`) 程序是 Android SDK 的一部分，允许您查看实时日志。避免安装 Android SDK 的替代方法是在 Chrome 中使用 [WebADB](https://webadb.com/)。
#### 使用控制台应用查看崩溃报告
如果您的 iOS 应用在 TestFlight 或 App Store 上，您可以在 Xcode 中使用 [崩溃组织者](https://developer.apple.com/news/?id=nra79npr)。
如果没有，您可以通过将设备连接到您的 Mac，使用 Xcode 中的 **控制台** 应用。请按照以下步骤访问控制台应用：
Step 1: 
打开 Xcode 应用，然后通过按 <kbd>Shift</kbd> + <kbd>Cmd ⌘</kbd> + <kbd>2</kbd> 打开 **设备和模拟器** 窗口。
Step 2: 
如果您已连接实际设备，请在 **设备** 下选择它。否则，如果您使用的是模拟器，请在 **模拟器** 下选择它。
Step 3: 
单击窗口中显示的 **Open Console** 按钮以打开控制台应用。
这将打开控制台应用，供您查看来自设备或模拟器的日志。
有关更多信息，请参见苹果的 [使用崩溃报告和设备日志诊断问题](https://developer.apple.com/documentation/xcode/diagnosing-issues-using-crash-reports-and-device-logs) 指南。
### 应用在特定（旧款）设备上崩溃
这可能表明存在性能问题。您可能需要通过分析器运行应用，以更好地了解哪些进程正在导致应用崩溃，且 [React Native 为此提供了一些很好的文档](https://reactnative.dev/docs/profiling)。我们还建议使用 [React Native 开发工具](/debugging/tools/#debugging-with-react-native-devtools) 和随附的 [分析器](/debugging/tools/#profiling-javascript-performance)，这使得识别应用中 JavaScript 性能瓶颈变得超级简单。
### 使用错误报告服务
在您的生产应用中实现崩溃和错误报告服务提供了若干好处，例如：
- 提供有关生产部署的实时洞察，包括重现崩溃和错误的信息。
- 设置警报系统，以便在发生致命 JavaScript 错误或您配置的任何其他事件时获得通知。
- 使用网页仪表板查看关于异常的详细信息，例如堆栈跟踪、设备信息等。
使用 Expo，您可以集成像 [Sentry](/guides/using-sentry/) 或 [BugSnag](/guides/using-bugsnag/) 这样的报告服务，以实时获取更多洞察。
## 卡住了？
Expo 社区和 React 及 React Native 社区是您在遇到困难时寻求帮助的良好资源。很有可能其他人也遇到过与您相同的错误，所以请务必阅读文档，搜索 [论坛](https://chat.expo.dev/)、[GitHub 问题](https://github.com/expo/expo/issues/) 和 [Stack Overflow](https://stackoverflow.com/)。


## 调试和分析工具

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

React Native 由 JavaScript 和原生代码组成。在调试时区分这两者非常重要。如果 JavaScript 代码抛出了错误，您可能无法使用原生代码的调试工具找到它。此页面列出了一些可以帮助您调试 Expo 项目的工具。
## 开发者菜单
**开发者菜单** 提供访问有用的调试功能。它内置于开发客户端和 Expo Go 中。如果您正在使用仿真器、模拟器或通过 USB 连接设备，可以通过在启动开发服务器的终端中按 <kbd>m</kbd> 打开此菜单。
Note: 打开开发者菜单的其他选项
---
- Android 设备（没有 USB）：垂直摇晃设备。
- Android 模拟器或设备（带 USB）：
  - 按 <kbd>Cmd ⌘</kbd> + <kbd>m</kbd> 或 <kbd>Ctrl</kbd> + <kbd>m</kbd>。
  - 在终端中运行以下命令模拟按下菜单按钮：
    ```sh
$ adb shell input keyevent 82
```
- iOS 设备（没有 USB）：
  - 摇晃设备。
  - 用三根手指触摸屏幕。
- iOS 模拟器或设备（带 USB）：
  - 按 <kbd>Ctrl</kbd> + <kbd>Cmd ⌘</kbd> + <kbd>z</kbd> 或 <kbd>Cmd ⌘</kbd> + <kbd>d</kbd>
---
一旦开发者菜单打开，菜单将如下所示：
开发者菜单提供以下选项：
- **Copy link**：复制开发客户端中的开发服务器地址或您应用中的 [`exp://`](/linking/into-your-app/#test-a-link-using-expo-go) 链接。
- **Reload**：重新加载您的应用。通常不需要，因为默认启用了快速刷新。
- **Go Home**：离开您的应用并导航回开发客户端或 Expo Go 应用的主页。
- **Toggle performance monitor**：查看有关您的应用的性能信息。
- **Toggle element inspector**：启用或禁用元素检查器叠加层。
- **Open JS debugger**：打开 React Native DevTools，可访问控制台、源、网络（**仅限 Expo**）、内存、组件和 Profiler 选项卡，适用于使用 Hermes 的应用。有关更多信息，请参见 [使用 React Native DevTools 调试](#debugging-with-react-native-devtools) 部分。
- **Fast Refresh**：在您使用文本编辑器更改项目中的文件时切换自动刷新 JS 包。
现在，让我们详细探讨这些选项中的一些。
### 切换性能监视器
打开一个小叠加层，提供有关您的应用的以下性能信息：
- 项目的 RAM 使用情况。
- JavaScript 堆（这是查看应用内存泄漏的简单方法）。
- 两个视图。顶部指示屏幕的视图数，底部指示组件的视图数。
- UI 和 JS 线程的每秒帧数。UI 线程用于原生 Android 或 iOS UI 渲染。JS 线程是大多数逻辑运行的地方，包括 API 调用、触摸事件等。
### 切换元素检查器
打开元素检查器叠加层：
此叠加层具有以下功能：
- 检查：检查元素
- 性能：显示性能叠加层
- 网络：显示网络详细信息
- 可触控元素：高亮显示可触控元素
## 使用 React Native DevTools 调试
> **info** **从 React Native 0.76 开始**，React Native DevTools 替代了 Chrome DevTools。
**React Native DevTools** 是用于 Expo 和 React Native 应用的现代调试工具。它使您能够通过访问 [控制台](#interacting-with-the-console)、[源](#pausing-on-breakpoints)、[网络](#inspecting-network-requests)（**仅限 Expo**）和 [内存](#insepcting-memory) 选项卡来深入了解您应用的 JavaScript 代码。它还内置支持 React DevTools，如 [组件](#inspecting-components) 和 [Profiler](#profiling-javascript-performance) 选项卡。所有这些检查器均可通过 [开发客户端](/more/glossary-of-terms/#dev-clients) 或 Expo Go 访问。
您可以在任何使用 [Hermes](/guides/using-hermes/) 的应用上使用 React Native DevTools。**要打开它，请启动您的应用并在启动 Expo 的终端中按 <kbd>j</kbd>**。一旦您打开了 React Native DevTools，它将如下所示：
### 在断点处暂停
您可以在代码的特定部分暂停应用。要做到这一点，请在源选项卡下通过单击行号设置断点或在代码中添加 `debugger` 语句。
一旦您的应用正在执行具有断点的代码，它将完全暂停您的应用。这使您能够检查该范围内的所有变量和函数。您还可以在您的应用的一部分 [控制台](#interacting-with-the-console) 选项卡中执行代码。
### 在异常处暂停
如果应用抛出意外错误，找到错误来源可能很难。您可以使用 React Native DevTools 在应用暂停时检查堆栈跟踪和变量，错误抛出的那一刻。
> **info** 某些错误可能会被您应用中的其他组件捕获，例如 Expo Router。在这些情况下，您可以开启 **在捕获异常时暂停**。这样可以使您能够检查任何抛出的错误，即使这些错误已经被正确处理。
### 与控制台交互
**Console** 选项卡使您能够访问一个交互式终端，直接连接到您的应用。您可以在此终端内写入任何 JavaScript，以执行代码片段，就像它是您应用的一部分一样。默认情况下，代码在全局范围内执行。但是，当使用来自 [源](#pausing-on-breakpoints) 选项卡的断点时，它将在达到的断点范围内执行。这样可以让您在整个应用中调用方法并访问变量。
### 检查网络请求（仅限 Expo）
> **info** React Native DevTools 中的网络选项卡仅在您的项目中安装了 `expo` 时可用。
**Network** 选项卡使您能够深入了解应用发出的网络请求。您可以通过单击它们来检查每个请求和响应。这包括 `fetch` 请求、外部加载的媒体，在某些情况下，甚至包括由原生模块发出的请求。
> **info** 请参阅 [检查网络流量](#inspecting-network-traffic) 以获得检查网络请求的替代方法。
### 检查内存
**Memory** 选项卡可让您检查内存使用情况并获取应用 JavaScript 代码的堆快照。
### 检查组件
**Components** 选项卡允许您检查应用中的 React 组件。您可以在 React Native DevTools 中悬停组件，查看每个组件的属性和样式。这是调试应用 UI 和理解组件结构的好方法。
### 分析 JavaScript 性能
> **warning** 分析的配置尚未符号化为源映射，并且 [只能在调试构建中使用](https://github.com/facebook/hermes/issues/760)。这些限制将在即将发布的版本中解决。
**Profiler** 选项卡允许您记录并分析应用 JavaScript 的性能。您可以开始记录，与应用交互，然后停止记录以分析性能。
> **info** 要分析本机运行时，请使用 Android Studio 或 Xcode 中包含的工具。
## 使用 VS Code 调试
> **warning** VS Code 调试器集成是实验性的。为了获得最稳定的调试体验，[使用 React Native DevTools](#debugging-with-react-native-devtools)。
VS Code 是一个流行的代码编辑器，内置调试器。此调试器使用与 React Native DevTools 相同的系统——检查器协议。
您可以使用 [Expo Tools](https://github.com/expo/vscode-expo#readme) VS Code 扩展配合此调试器。此调试器允许您设置断点、检查变量并通过调试控制台执行代码。
要开始调试：
- 连接您的应用
- 打开 VS Code 命令面板（根据您的计算机，按 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> 或 <kbd>Cmd ⌘</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd>）
- 运行 **Expo: Debug ...** VS Code 命令。
这将将 VS Code 附加到正在运行的应用。
此外，如果您想在 VS Code 中获得全面功能的 IDE 设置，您可能想查看 [Radon IDE](https://ide.swmansion.com/) 扩展（收费，并提供 30 天免费试用）。它将您的编辑器转变为一个强大的环境，专为 React Native 和 Expo 项目设计，具备高级调试、网络检查器、路由器集成和其他内置工具。
## React Native 调试器
> **warning** React Native 调试器需要远程 JS 调试，自 [React Native 0.73](https://reactnative.dev/docs/other-debugging-methods#remote-javascript-debugging-deprecated) 开始已被弃用。
React Native 调试器是一个独立的应用，包裹了 React DevTools、Redux DevTools 和 React Native DevTools。不幸的是，它需要 [已弃用的远程 JS 调试工作流](https://github.com/jhen0409/react-native-debugger/discussions/774)，并与 Hermes 不兼容。
如果您使用的是 Expo **SDK 50** 或 **更高版本**，您可以使用 [Expo 开发工具插件](/debugging/devtools-plugins) 来替代 React Native 调试器：
- [React Native DevTools](#debugging-with-react-native-devtools)
- [Redux DevTools](/debugging/devtools-plugins/#redux)
如果您使用的是 Expo SDK 49 或更早版本，则可以使用 React Native 调试器。本部分提供快速入门说明。有关详细信息，请查看其 [文档](https://github.com/jhen0409/react-native-debugger#documentation)。
您可以通过 [发布页面](https://github.com/jhen0409/react-native-debugger/releases) 安装它，或者如果您在 macOS 上，可以运行：
```sh
$ brew install react-native-debugger
```
### 启动
启动 React Native 调试器后，您需要将端口指定为 `8081`（快捷方式：在 macOS 上按 <kbd>Cmd ⌘</kbd> + <kbd>t</kbd>，在 Linux/Windows 上按 <kbd>Ctrl</kbd> + <kbd>t</kbd>）。然后，运行您的项目并使用 `npx expo start`，在开发者菜单中选择 `调试远程 JS`。调试器应自动连接。
在调试控制台中，您可以看到元素树，以及所选元素的属性、状态和子元素。右侧还有 Chrome 控制台，如果您在控制台中输入 `$r`，您将看到所选元素的详细信息。
如果您在 React Native 调试器的任何位置右键单击，您将获得一些便利的快捷方式，可以重新加载 JS、启用/禁用元素检查器、网络检查器，以及记录和清除您的 `AsyncStorage` 内容。
### 检查网络流量
在 React Native 调试器中调试网络请求非常简单：在 React Native 调试器的任何位置右键单击并选择 `启用网络检查`。这将启用网络选项卡，并允许您检查 `fetch` 和 `XMLHttpRequest` 的请求。
不过，也存在 [一些限制](https://github.com/jhen0409/react-native-debugger/blob/master/docs/network-inspect-of-chrome-devtools.md#limitations)，因此有一些其他替代方法，所有这些都需要使用代理：
- [Charles Proxy](https://www.charlesproxy.com/documentation/configuration/browser-and-system-configuration/) (~$50 美元，我们推荐的工具)
- [Proxyman](https://proxyman.io)（提供免费版本，或 $49 到 $59 美元）
- [mitmproxy](https://medium.com/@rotxed/how-to-debug-http-s-traffic-on-android-7fbe5d2a34#.hnhanhyoz)
- [Fiddler](http://www.telerik.com/fiddler)
## 调试生产应用
实际上，应用通常会带着错误发布。实施崩溃和错误报告系统可以帮助您获得生产应用的实时洞察。有关更多详细信息，请参阅 [使用错误报告服务](/debugging/runtime-issues/#using-error-reporting-services)。


## 开发工具插件

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

开发工具插件在您的本地开发环境中可用，以帮助您调试应用程序。它们由一小部分代码组成，您将其添加到项目中，从而使应用程序与外部 Chrome 窗口之间能够双向通信。这种设置提供了显示工具，以检查应用程序，触发某些行为进行测试等。
开发工具插件类似于在开发构建和 Expo Go 中可用的 Flipper 插件，不需要将本机模块或配置插件添加到您的项目中。
## 将开发工具插件添加到项目
要将开发工具插件添加到应用程序中，将其作为包安装，然后添加一个小代码片段来连接代码与您的应用程序。该代码从应用程序的根组件调用，以在您的应用程序和插件之间建立双向通信。然后，插件可以在您的应用程序以开发模式运行的整个时间内检查应用程序的各个方面。
所有 [Expo 开发工具插件](#expo-dev-tools-plugins) 和使用 [我们的创建工具](/debugging/create-devtools-plugins) 创建的插件都导出一个钩子，您可以使用它将插件连接到您的应用程序。钩子和从中返回的任何函数在应用程序未在开发模式下运行时将无操作。
某些插件钩子需要与插件如何检查应用程序相关的参数。例如，用于检查 React Navigation 状态的插件可能需要对导航根的引用。
要开始使用插件，请在应用程序的根组件中使用该钩子：
```jsx App.js
import { useMyDevToolsPlugin } from 'my-devtools-plugin';
export default App() {
  useMyDevToolsPlugin();
  return (/* rest of your app */)
}
```
在某些情况下，您可能需要直接与插件交互。所有插件通过 `expo/devtools` 导出的内容进行通信，您可以通过 `useDevToolsPluginClient` 发送和监听消息。确保将与插件的 Web 用户界面相同的插件名称传递给 `useDevToolsPluginClient`：
```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 */)
}
```
### 与 Expo Go 和开发构建的兼容性
开发工具插件应仅包含 JavaScript 代码。它们通常与 Expo Go 和 [开发构建](/develop/development-builds/introduction/) 兼容，并且不应需要创建新的开发构建来添加插件。如果一个包的底层模块包含本机代码且不属于 Expo Go，则创建一个新的开发构建以使用该组件和来自该包的插件。
例如，检查 [React Native Firebase](/guides/using-firebase/#using-react-native-firebase) 的开发工具插件将不适用于 Expo Go。React Native Firebase 包含不是 Expo Go 一部分的本机代码。要使用开发工具插件和 React Native Firebase，请创建一个开发构建。
## 使用开发工具插件
在安装开发工具插件并将所需的连接代码添加到项目后，您可以使用 `npx expo start` 启动开发服务器。然后按 <kbd>shift</kbd> + <kbd>m</kbd> 打开可用开发工具插件的列表。选择您想使用的插件，它将在新的 Chrome 窗口中打开。
> 使用 Expo CLI 启动开发服务器时，可以按 <kbd>?</kbd> 以 **显示所有命令**。这将显示额外命令，包括打开 **更多工具** 的快捷方式。在此菜单中也可以选择开发工具插件。
## Expo 开发工具插件
Expo 提供一些开发工具插件用于常见的调试任务。按照以下说明在您的应用程序中开始使用它们。
> **注意**：以下每个开发工具插件钩子仅在开发模式下启用插件。它不会影响您的生产包。
### React Navigation
受到 [`@react-navigation/devtools`](https://github.com/react-navigation/react-navigation/tree/main/packages/devtools) 启发，React Navigation 开发工具插件允许查看 [React Navigation](https://reactnavigation.org/) 动作和状态的历史。您还可以倒回导航历史中的先前点，并向您的应用程序发送深度链接。由于 Expo Router 是基于 React Navigation 构建的，因此此插件与 [Expo Router](/router/introduction) 完全兼容。
要使用该插件，请首先安装包：
```sh
$ npx expo install @dev-plugins/react-navigation
```
在应用程序的条目点中将导航根传递给插件：
```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 插件。这将打开插件的 Web 界面，显示您在应用程序中导航时的导航历史。
### Apollo Client
受到 [`react-native-apollo-devtools`](https://github.com/razorpay/react-native-apollo-devtools) 启发，Apollo Client 开发工具插件允许检查 Apollo Client 的缓存、查询和变更。
要使用该插件，请首先安装包：
```sh
$ npx expo install @dev-plugins/apollo-client
```
然后在应用程序的根组件中或在用 `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 Client 操作时的查询历史、缓存和变更。
### React Query
受到 [`react-query-native-devtools`](https://github.com/bgaleotti/react-query-native-devtools) 启发，React Query 开发工具插件允许您浏览数据和查询、缓存状态，以及从 [TanStack Query](https://tanstack.com/query/latest/) 中重新获取和移除缓存中的查询。
要使用该插件，请首先安装包：
```sh
$ npx expo install @dev-plugins/react-query
```
然后在应用程序的根组件中或在用 `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 界面，显示在您的应用程序中使用查询时的查询。
### Redux
`redux-devtools-expo-dev-plugin` 基于 [Redux DevTools](https://github.com/reduxjs/redux-devtools/)（来自 Chrome 扩展）。它提供了一个活动的动作列表，以及它们如何影响状态，以及从 DevTools 回滚、重放和调度动作的能力。
要使用该插件，请首先安装包：
```sh
$ npx expo install redux-devtools-expo-dev-plugin
```
如果您使用的是 `@reduxjs/toolkit`，请修改 `configureStore` 调用，通过传递 `devTools: false` 来禁用内置的开发工具。然后，通过连接 `devToolsEnhancer()` 来添加 Expo DevTools 插件增强器。`configureStore` 调用将如下所示：
```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 界面，显示当动作被调度时您的动作和商店内容。
有关完整的安装和使用说明，包括如果您直接使用 `redux` 而不是 `@reduxjs/toolkit`，[请查看项目的 README](https://github.com/matt-oakes/redux-devtools-expo-dev-plugin)。
### TinyBase
TinyBase 开发工具插件将 TinyBase Store Inspector 连接到您的应用程序，允许您查看和更新应用程序商店的内容。
要使用该插件，请首先安装包：
```sh
$ npx expo install @dev-plugins/tinybase
```
然后在应用程序的根组件中或在用商店的 `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 插件。这将打开插件的 Web 界面，显示在修改商店内容时的商店内容。


## 创建开发工具插件

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

> **提示**：查看 [Expo DevTools Plugins](https://github.com/expo/dev-plugins) 获取完整例子。
您可以创建一个开发工具插件，无论是用于检查常见框架或库的某些方面，还是用于您自定义代码的特定内容。本指南将指导您创建一个开发工具插件。
## 什么是开发工具插件？
开发工具插件在您的网页浏览器中运行于本地开发环境，并连接到您的 Expo 应用。
一个插件包含三个关键元素：
- 一个 Expo 应用，用于显示开发工具网页用户界面。
- 一个 **expo-module.config.json** 以供 Expo CLI 识别。
- 调用 `expo/devtools` API 以便应用能与开发工具的网页界面进行双向通信。
插件可以在 npm 上分发或包含在您应用的单一代码库中。它们通常导出一个可以在您应用的根组件中使用的钩子，以便在应用以调试模式运行时与网页界面进行双向通信。
Step 1: 
## 创建插件
### 创建一个新的插件项目
`create-dev-plugin` 将为您设置一个新的插件项目。运行以下命令以创建新的插件项目：
```sh
$ npx create-dev-plugin@latest
```
`create-dev-plugin` 将提示您输入插件的名称、描述以及将被插件使用者使用的钩子的名称。
插件项目将包含以下目录：
- **src** - 这是导出将被消费应用用于连接插件的钩子。
- **webui** - 这包含插件的网页用户界面。
### 自定义插件的功能
模板包含一个简单的示例，演示了插件与应用之间发送和接收消息。`useDevToolsPluginClient`，从 `expo/devtools` 导入，提供插件与应用之间发送和接收消息的功能。
`useDevToolsPluginClient` 返回的客户端对象包括：
#### addMessageListener
监听与输入字符串匹配的消息，并使用消息数据调用回调。
```jsx
const client = useDevToolsPluginClient('my-devtools-plugin');
client.addMessageListener('ping', data => {
  alert(`Received ping from ${data.from}`);
});
```
#### sendMessage
监听与输入字符串匹配的消息，并使用消息数据调用回调。
```jsx
const client = useDevToolsPluginClient('my-devtools-plugin');
client?.sendMessage('ping', { from: 'web' });
```
编辑 **webui** 目录中的 Expo 应用，以自定义显示来自您应用的诊断信息或触发测试场景的用户界面：
```tsx webui/App.tsx
import { useDevToolsPluginClient, type EventSubscription } from 'expo/devtools';
import { useEffect } from 'react';
export default function App() {
  const client = useDevToolsPluginClient('my-devtools-plugin');
  useEffect(() => {
    const subscriptions: EventSubscription[] = [];
    subscriptions.push(
      client?.addMessageListener('ping', data => {
        alert(`Received ping from ${data.from}`);
      })
    );
    return () => {
      for (const subscription of subscriptions) {
        subscription?.remove();
      }
    };
  }, [client]);
}
```
编辑 **src** 目录中的钩子，以自定义发送到插件的诊断信息或应用如何应对来自网页用户界面的任何消息：
```tsx src/useMyDevToolsPlugin.ts
import { useDevToolsPluginClient } from 'expo/devtools';
export function useMyDevToolsPlugin() {
  const client = useDevToolsPluginClient('my-devtools-plugin');
  const sendPing = () => {
    client?.sendMessage('ping', { from: 'app' });
  };
  return {
    sendPing,
  };
}
```
如果您更新钩子以返回将在应用中调用的函数，您还需要更新 **src/index.ts** 以便在应用未在调试模式下运行时，它将导出无操作函数：
```diff src/index.ts
if (process.env.NODE_ENV !== 'production') {
  useMyDevToolsPlugin = require('./useMyDevToolsPlugin').useMyDevToolsPlugin;
} else {
  useMyDevToolsPlugin = () => ({
+    sendPing: () => {},
  });
}
```
Step 2: 
## 测试插件
由于插件网页用户界面是一个 Expo 应用，您可以像测试任何其他 Expo 应用一样进行测试，使用 `npx expo start`，不同的是您将仅在浏览器中运行它。模板包含了一个便利命令，以在本地开发模式下运行插件：
```sh
$ npm run web:dev
```
Step 3: 
## 构建插件以供分发
为了准备您的插件以供分发或在您的单一代码库中使用，您需要使用以下命令构建插件：
```sh
$ npm run build:all
```
此命令将在 **build** 目录中构建钩子代码，并在 **dist** 目录中构建网页用户界面。
Step 4: 
## 使用插件
将插件的钩子导入到您应用的根组件中，并调用它以连接您的应用与插件：
```jsx App.js
import { useMyDevToolsPlugin } from 'my-devtools-plugin';
import { Button } from 'react-native';
export default function App() {
  const { sendPing } = useMyDevToolsPlugin();
  return (
    <View style={styles.container}>
      <Button
        title="Ping"
        onPress={() => {
          sendPing();
        }}
      />
    </View>
  );
}
```


# 评审

## 审核分发应用概览

了解如何通过应用商店、内部分发和 EAS Update 将您的应用分发以供审核。

本页概述了三种与团队共享应用预览版本以进行 QA 和审阅的方式：应用商店测试轨道、内部分发，以及使用 EAS Update 的开发构建。
Note: 我可以使用 Expo Go 来查看发行版吗？
---
尽管 Expo Go 是一个开源的沙箱，适合在 Android 和 iOS 上预览单个原型，但它并非用于生产应用。在应用预览过程中应避免使用它。
---
## App store 测试轨道
在应用商店测试轨道分发应用时，只能使用发布版本构建。您不能使用此方法来分发开发版本构建。一种替代方法是使用 ["内部分发"](#internal-distribution-with-eas-build)，它可以在发布版本和开发版本构建上工作。
Note: Android: Google Play Beta
---
在正式公开发布之前，[Google Play beta](https://support.google.com/googleplay/android-developer/answer/9845334?visit_id=638740965629093187-3840249980&rd=1) 是将应用分发给测试人员的另一种选择。您可以设置内部、封闭或公开测试轨道，并控制谁可以访问该应用。
每个测试轨道都有其自身的要求。对于内部轨道，你最多只能邀请 100 名测试人员。闭环轨道和公开轨道都支持更大规模的测试人员组。在闭环轨道中，你需要邀请测试人员；在公开轨道中，任何人都可以加入你的项目。
要使用 Google Play 测试版，需将应用上传为 AAB（Android App Bundle）到 Google Play Console，设置测试轨道，并通过电子邮件或可分享链接邀请用户。测试人员可以通过 Play 商店安装应用，并且可直接从 Google Play Console 收集反馈和崩溃报告。
---
Note: iOS: TestFlight
---
TestFlight 是分发 iOS 设备应用的另一种选择。TestFlight 也需要付费的 Apple Developer 账户。TestFlight 的内部测试选项允许你创建测试组，最多包含你 Apple Developer 账户团队的 100 名成员，然后通过 TestFlight 应用下载应用。一些团队偏好 TestFlight，因为添加新测试人员不需要重新构建，应用会自动保持更新。
TestFlight 还包括外部测试选项，允许你通过电子邮件或公开链接与多达 10,000 名用户分享你的应用。
在 TestFlight 中，内部测试和外部测试分发都需要你在 App Store Connect 中上传你的应用并等待自动审查，随后才可以分享构建。然而，外部测试的构建在分发前需要经过更正式的 App Store 审查（与应用在生产发布前必须经过的审查不同）。
---
## 与 EAS Build 一起的内部分发
[内部分发](/build/internal-distribution/) 是 EAS 提供的一个功能，允许开发者创建构建并通过一个 URL 轻松分享。该 URL 可以在设备上打开以安装应用。应用以可安装的 Android APK 形式提供，或以 iOS 的临时 Provisioning 应用形式提供。
一旦创建了内部分发构建，它就可以下载和安装——无需填写表格或等待审批/处理。你可以使用内部分发来分享发布版和开发版。
## 开发构建与 EAS Update
你可以使用 [开发构建](/develop/development-builds/introduction/) 在评审阶段加载应用预览，通过发布一个带有 [EAS Update](/eas-update/introduction/) 的更新来实现。在通过内部分发分享开发构建并安装后，只要更新与你已安装的构建兼容，你就可以启动任何你通过 EAS Update 发布的更新。了解更多关于 [运行时版本与更新](/eas-update/runtime-versions/) 。
Note: 您可以使用 EAS 仪表板来启动更新并分享特定更新的链接。
---
---
Note: 您可以直接从开发构建中探索和启动更新。
---
---
Note: 您可以配置 GitHub Actions 以在 PR 和提交时自动发布更新。
---
---
这种方法具有独特的强大功能，因为它让你在尽可能快速地运行 `eas update` 时对反馈作出回应。与团队分享应用新版本可能只需几秒钟，而且你可以在不需要重新构建应用或将其上传到商店测试通道的情况下完成。
  }
  description={
    <>
      了解如何在项目中使用  启动不同的应用版本
      并在开发构建中预览已发布的更新。
    </>


## 与团队共享预览

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

一旦您在分支上进行了更改，您可以通过发布更新与团队共享这些更改。这使您能够在审查期间获得对更改的反馈。
以下步骤将概述发布更改预览的基本流程，然后与团队共享。有关更全面的资源，请参见 [预览更新](/eas-update/preview/) 指南。
## 发布更改的预览
您可以通过运行以下 [EAS CLI](/develop/tools/#eas-cli) 命令发布当前更改的预览：
```sh
$ eas update --auto
```
此命令将在当前分支名称下发布更新。
## 与团队共享
一旦预览发布，您将在终端窗口看到如下输出：
```sh
✔ Published!
...
EAS Dashboard      https://expo.dev/accounts/your-account/projects/your-project/updates/708b05d8-9bcf-4212-a052-ce40583b04fd
```
将 **EAS Dashboard** 链接与审阅者共享。打开链接后，他们可以点击 **预览** 按钮。然后，他们会看到一个二维码，可以扫描该二维码以在其设备上打开预览。
## 自动创建预览
您可以使用 [EAS Workflows](/eas/workflows/get-started/) 在每次提交时自动创建预览。首先，您需要 [配置您的项目](/eas/workflows/get-started/#configure-your-project)，在项目根目录下添加一个名为 **.eas/workflows/publish-preview-update.yml** 的文件，然后添加以下工作流配置：
```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 命令手动运行此工作流：
```sh
$ eas workflow:run publish-preview-update.yml
```
了解更多常见模式，请参见 [工作流示例指南](/eas/workflows/examples)。
## 了解更多


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

了解如何将更新与 Expo Orbit 一起作为审核工作流程的一部分打开。

[Expo Orbit](https://expo.dev/orbit) 是一款专为 macOS 和 Windows 设计的应用程序，旨在加快从 EAS 安装和运行构建的速度。它使运行构建和更新变得像按下 **在 Orbit 中打开** 一样简单。
Note: 自动安装和启动更新是如何工作的？
---
当您启动更新时，Orbit 将查找与更新的运行时版本和目标平台匹配的最新开发构建。如果找到兼容的构建，更新将自动安装在目标设备上，并使用指向该更新的深度链接启动。
如果您没有可用的开发构建，可能是因为它们都已过期，您还没有创建一个，您不使用 EAS Build，或者您正在 [本地构建您的应用](/guides/local-app-development/)，那么 Orbit 将提示您如何继续。如果您已经在目标设备上安装了兼容的开发构建，请在提示中点击 **使用深度链接启动** 以打开更新。
---
## 先决条件
- **在按照本指南的步骤操作之前，安装 Orbit 应用程序。** 您可以直接从 [GitHub releases](https://github.com/expo/orbit/releases) 下载，或者参见 [替代方法](/build/orbit/#installation) 进行安装。
- 安装应用后，从 **设置** 登录到您的 Expo 账户。
## 使用 Expo Orbit 预览更新
使用 Expo Orbit 预览需要您已经发布了更新。如果您还没有发布更新，请在执行下一节中的步骤之前查看 [发布更新](/eas-update/getting-started/#publish-an-update)。
### 安装并启动更新
> **注意**：使用 Expo Orbit 启动更新在真实的 iOS 设备上不受支持。它在 Android 设备/模拟器或 iOS 模拟器上受支持。
在更新发布后，按照以下步骤在 Android 模拟器或 iOS 模拟器上打开它：
- 导航到您项目的 **Updates** 标签。
- 选择您想要预览的更新。
- 点击 **Preview**。这将打开 **Preview** 对话框。
- 在 **Open with Orbit** 下，选择一个平台来启动更新。
- Orbit 将在所选的 Android 模拟器或 iOS 模拟器上安装并启动更新。
您现在可以使用 Expo Orbit 无缝地启动和审核更新。


# 部署

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

了解如何使用 EAS Build 从命令行创建一个准备提交到应用商店的生产构建。

无论您是使用[EAS](/build/setup/)还是[本地](/guides/local-app-development/)构建了本机应用程序二进制文件，您应用开发旅程中的下一步是将应用提交至商店。为此，您需要创建一个**生产构建**。
生产构建是提交给应用商店供公众发布或作为商店协助的测试过程（如 TestFlight）的一部分。本指南说明了如何使用[EAS](#production-builds-using-eas)和[本地](#production-builds-locally)创建生产构建。您还可以使用任何能够编译 Android 和 iOS 应用的 CI 服务为 Expo 应用创建生产构建。
## 使用 EAS 创建生产构建
生产构建必须通过各自的应用商店进行安装。您不能直接在 Android 模拟器、iOS 模拟器或设备上安装它们。唯一的例外是，如果您在构建配置文件中明确设置了`"buildType": "apk"`用于 Android。不过，提交到商店时建议使用**aab**，这是默认配置。
### `eas.json` 配置
**eas.json**中的生产构建的最小配置在您创建第一次构建时已生成：
```json eas.json
{
  "build": {
    "production": {}
  }
}
```
### 创建生产构建
要创建生产构建，请为平台运行以下命令：
    ```sh
$ eas build --platform android
```
    ```sh
$ eas build --platform ios
```
您可以通过将`--message`附加到构建命令中来添加消息，例如，`eas build --platform ios --message "Some message"`。消息将出现在 EAS 仪表板上。当您想为团队指定构建的目的时，它会很有用。
或者，您可以使用`--platform all`选项同时为 Android 和 iOS 构建：
```sh
$ eas build --platform all
```
## 开发者账户
您需要拥有一个开发者账户，以便将应用提交到您想要的应用商店。
Note: 需要拥有 Google Play 开发者会员才能分发到 Google Play 商店。
---
您可以使用 EAS Build 构建和签名您的应用，但除非您拥有会员资格（一次性 25 美元），否则无法将其上传到 Google Play 商店。
---
Note: 需要拥有 Apple 开发者计划会员才能为 Apple App Store 构建应用。
---
如果您打算使用 EAS Build 为 Apple App Store 创建生产构建，您需要访问具有 99 美元 [Apple 开发者计划](https://developer.apple.com/programs) 会员资格的账户。
---
## 应用签名凭据
在开始为应用商店构建之前，您需要一个商店开发者账户并生成或提供应用签名凭据。
无论您是否有生成应用签名凭据的经验，EAS CLI 都可以完成繁重的工作。您可以选择让 EAS CLI 处理应用签名凭据的过程。
### Android 应用签名凭据
- 如果您尚未为应用生成密钥库，请通过选择`生成新的密钥库`来使用 EAS CLI，然后即可完成。密钥库会安全地存储在 EAS 服务器上。
- 如果您想手动生成密钥库，请参见[手动 Android 凭据指南](/app-signing/local-credentials#android-credentials)以获取更多信息。
### iOS 应用签名凭据
- 如果您尚未生成配置文件和/或分发证书，请通过登录到您的 Apple 开发者计划账户并按照提示使用 EAS CLI。
- 如果您想手动生成凭据，请参见[手动 iOS 凭据指南](/app-signing/local-credentials#ios-credentials)以获取更多信息。
## 等待构建完成
默认情况下，`eas build`命令会等待您的构建完成，但如果您不想等待，可以中断它。相反，请使用 EAS CLI 提示的构建详情页面链接来监控构建进度并阅读构建日志。您也可以通过访问[您的构建仪表板](https://expo.dev/builds)或运行以下命令找到此页面：
```sh
$ eas build:list
```
如果您是某个组织的成员且您的构建是以该组织的名义进行的，您将找到[该账户的构建仪表板](https://expo.dev/accounts/[account]/builds)上的构建详情。
## 自动创建构建
您可以通过[EAS Workflows](/eas/workflows/get-started/)在特定分支的提交上自动创建构建。首先，您需要[配置您的项目](/eas/workflows/get-started/#configure-your-project)，在项目根目录中添加一个名为**.eas/workflows/create-builds.yml**的文件，然后添加以下工作流配置：
```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
```
上述工作流将在每次提交到项目的`main`分支时创建 Android 和 iOS 构建。您还可以通过以下 EAS CLI 命令手动运行此工作流：
```sh
$ eas workflow:run create-builds.yml
```
了解更多关于常见模式的信息，请参见[工作流示例指南](/eas/workflows/examples)。
## 本地发布构建
要在本地创建发布（也称为生产）构建，请参阅以下 React Native 指南，以获取有关 Android 和 iOS 所需步骤的更多信息。
这些指南假设您的项目包含**android**和/或**ios**目录，其中包含相应的本机项目。如果您使用[持续本机生成](/workflow/continuous-native-generation)，则需要运行[预构建](/workflow/prebuild)以在遵循指南之前生成目录。
> **注意**：遵循下面的指南，在第四步中，当您为 Android 构建发布的**.aab**时，请在**android**目录中运行`./gradlew app:bundleRelease`，而不是`npx react-native build-android --mode=release`。
## 下一步


## 提交到应用商店

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

**EAS Submit** 是一个托管服务，可以使用 EAS CLI 上传并提交应用二进制文件到应用商店。 本指南描述了如何使用 EAS Submit 将您的应用提交到 Google Play 商店和 Apple App Store。
Video Tutorial: [如何快速将应用发布到 App Store 和 Play Store 与 EAS Submit](https://www.youtube.com/watch?v=-KZjr576tuE)
## Apple App Store
<Prerequisites numberOfRequirements={4}>
  <Requirement number={1} title="注册 Apple 开发者账户">
    提交应用到 Apple App Store 需要一个 Apple 开发者账户。 您可以在 [Apple 开发者门户](https://developer.apple.com/account/) 上注册 Apple 开发者账户。
  </Requirement>
  <Requirement number={2} title="在 app.json 中包含包标识符">
    在 **app.json** 中包含您应用的包标识符：
    ```json app.json
    {
      "ios": {
        "bundleIdentifier": "com.yourcompany.yourapp"
      }
    }
    ```
  </Requirement>
  <Requirement number={3} title="安装 EAS CLI 并使用您的 Expo 账户进行身份验证">
    安装 EAS CLI 并使用您的 Expo 账户登录：
    ```sh
$ npm install -g eas-cli && eas login
```
  </Requirement>
  <Requirement number={4} title="构建生产应用">
    您需要一个准备好提交商店的生产版本。 您可以使用 [EAS Build](/build/introduction/) 创造一个：
    ```sh
$ eas build --platform ios --profile production
```
    或者，您可以使用 `eas build --platform ios --profile production --local` 或 Xcode 在自己计算机上构建应用。
  </Requirement>
</Prerequisites>
一旦完成所有先决条件，您可以开始提交流程。
运行以下命令将构建提交到 Apple App Store：
```sh
$ eas submit --platform ios
```
该命令将引导您逐步完成提交应用的过程。
## Google Play Store
<Prerequisites numberOfRequirements={7}>
  <Requirement number={1} title="注册 Google Play 开发者账户">
    提交应用到 Google Play 商店需要一个 Google Play 开发者账户。 您可以在 [Google Play 控制台注册页面](https://play.google.com/apps/publish/signup/) 注册 Google Play 开发者账户。
  </Requirement>
  <Requirement number={2} title="创建 Google 服务账户">
    EAS 需要您上传和配置 Google 服务账户密钥，以便将 Android 应用提交到 Google Play 商店。 您可以通过 [使用 EAS 上传 Google 服务账户密钥进行 Play Store 提交](https://github.com/expo/fyi/blob/main/creating-google-service-account.md) 指南创建一个。
  </Requirement>
  <Requirement number={3} title="在 Google Play 控制台上创建应用">
    通过点击 [Google Play 控制台](https://play.google.com/apps/publish/) 中的 **Create app** 创建一个应用。
  </Requirement>
  <Requirement number={4} title="安装 EAS CLI 并使用您的 Expo 账户进行身份验证">
    安装 EAS CLI 并使用您的 Expo 账户登录：
    ```sh
$ npm install -g eas-cli && eas login
```
  </Requirement>
  <Requirement number={5} title="在 app.json 中包含包名">
    在 **app.json** 中包含您应用的包名：
    ```json app.json
    {
      "android": {
        "package": "com.yourcompany.yourapp"
      }
    }
    ```
  </Requirement>
  <Requirement number={6} title="构建生产应用">
    您需要一个准备好提交商店的生产版本。 您可以使用 [EAS Build](/build/introduction/) 创建一个：
    ```sh
$ eas build --platform android --profile production
```
    或者，您可以使用 `eas build --platform android --profile production --local` 或 Android Studio 在自己计算机上构建应用。
  </Requirement>
  <Requirement number={7} title="至少手动上传一次应用">
    您必须至少手动上传一次应用。 这是 Google Play 商店 API 的限制。
    通过 [首次提交 Android 应用](https://expo.fyi/first-android-submission) 指南学习如何操作。
  </Requirement>
</Prerequisites>
一旦完成所有先决条件，您可以开始提交流程。
运行以下命令将构建提交到 Google Play 商店：
```sh
$ eas submit --platform android
```
该命令将引导您逐步完成提交应用的过程。
## 自动构建和提交
您可以使用 [EAS Workflows](/eas/workflows/get-started/) 自动创建构建并提交到应用商店。 首先，您需要 [配置您的项目](/eas/workflows/get-started/#configure-your-project)，在项目根目录添加名为 **.eas/workflows/build-and-submit.yml** 的文件，然后添加以下工作流配置：
```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 命令手动运行此工作流：
```sh
$ eas workflow:run build-and-submit.yml
```
了解更多关于常见模式的信息，请参见 [工作流示例指南](/eas/workflows/examples)。
## 手动提交到应用商店
您也可以将应用手动提交到 Google Play 商店和 Apple App Store。
## 下一步


## 应用商店元数据

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

> **important** **EAS 元数据** 处于预览状态，可能会发生重大更改。
在将您的应用提交到应用商店时，您需要提供元数据。这个过程是漫长的，通常涉及与您的应用无关的复杂主题。您提供的信息经过审查后，如果存在任何问题，您需要重新开始这个过程。
[**EAS 元数据**](/eas/metadata/) 使您能够通过命令行自动化和维护这些信息，而不必在应用商店仪表板中填写多个表单。它还可以即时识别可能在漫长的审查队列后触发拒绝的知名应用商店限制。本指南显示如何使用 EAS 元数据自动化和维护您的应用商店存在。
## 先决条件
EAS 元数据目前 **仅支持 Apple App Store**。
> 使用 VS Code？安装 [Expo Tools 扩展](https://github.com/expo/vscode-expo#readme) 获取 **store.config.json** 文件的自动完成、建议和警告。
## 创建商店配置
EAS 元数据使用 [store.config.json](/eas/metadata/config/) 文件来保存您想要上传到应用商店的所有信息。此文件位于您的 Expo 项目的根目录下。
在项目目录的根目录下创建一个新的 **store.config.json** 文件，如下例所示：
```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` 等。
**从上述示例中需要记住的一件重要事情是 `configVersion` 属性。** 它有助于版本变更，这些变更不向后兼容。
> 有关 **store.config.json** 中可以定义的属性的更多信息，请参见 [EAS 元数据架构](/eas/metadata/schema/#config-schema)。
## 上传商店配置
> 在将 **store.config.json** 推送到应用商店之前，您必须上传应用的新二进制文件。有关更多信息，请参见 [应用商店提交](/deploy/submit-to-app-stores/)。二进制文件提交并处理后，您可以继续进行以下步骤。
在您创建了 **store.config.json** 文件并添加了与您的应用相关的必要信息后，您可以通过运行以下命令将商店配置推送到应用商店：
```sh
$ eas metadata:push
```
如果 EAS 元数据在处理您的商店配置时遇到任何问题，它将在运行此命令时给您警告。当没有错误，或您确认推送可能存在的问题时，它将尝试尽可能多地上传。
您还可以在修改 **store.config.json** 文件并希望将最新更改推送到应用商店时重用此命令。
## 下一步


## 发送空中更新

了解如何发送空中更新，以将关键的错误修复和改进推送给您的用户。

您可以发送包含关键错误修复和改进的空中更新给您的用户。
## 开始
> 如果您之前发布过 [预览](/review/share-previews-with-your-team/) 或创建过 [构建](/deploy/build-project/)，您可能已经设置了更新，可以跳过此部分。
要设置更新，请运行以下 [EAS CLI](/develop/tools/#eas-cli) 命令：
```sh
$ eas update:configure
```
命令完成后，您需要进行新的构建，然后才能继续到下一部分。
## 发送更新
要发送更新，请运行以下 [EAS CLI](/develop/tools/#eas-cli) 命令：
```sh
$ eas update --channel production
```
此命令将创建一个更新，并使其可用于配置为接收 `production` 通道更新的应用构建。该通道在 [**eas.json**](/eas/json/#channel) 中定义。
您可以通过强制关闭应用并重新打开两次来验证更新是否有效。更新应在第二次启动时应用。
## 自动发送更新
您可以使用 [EAS Workflows](/eas/workflows/get-started/) 自动发送更新。首先，您需要 [配置项目](/eas/workflows/get-started/#configure-your-project)，在项目根目录添加名为 **.eas/workflows/send-updates.yml** 的文件，然后添加以下工作流配置：
```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 命令手动运行此工作流：
```sh
$ eas workflow:run send-updates.yml
```
了解更多常见模式，请查看 [工作流示例指南](/eas/workflows/examples)。
## 了解更多
您可以通过我们的 [更新指南](/eas-update/introduction/) 学习如何 [推出更新](/eas-update/rollouts/)、[优化资产](/eas-update/optimize-assets/) 等。


## 发布您的网络应用

学习如何使用 EAS Hosting 部署您的网络应用。

> **important** **EAS Hosting** 处于预览阶段，可能会发生变化。
如果您正在构建一个通用应用，可以快速使用 [EAS Hosting](/eas/hosting/introduction/) 部署您的网络应用。它是一个用于部署使用 Expo Router 和 React 构建的网络应用的服务。
## 先决条件
在您开始之前，请确保在项目的 **app.json** 文件中，[`expo.web.output`](/versions/latest/config/app/#output) 属性是 `static` 或 `server`。
## 导出您的网络项目
要部署您的网络应用，您需要创建网络项目的静态构建。通过运行以下命令将您的网络项目导出到 **dist** 目录：
```sh
$ npx expo export --platform web
```
> 请记住，在您对网络应用进行更改后，每次部署之前都要重新运行此命令。
## 初始部署
要发布您的网络应用，请运行以下 [EAS CLI](/develop/tools/#eas-cli) 命令：
```sh
$ eas deploy
```
首次运行此命令后，您将被提示选择项目的预览子域名。此子域名是用于创建预览 URL 的前缀，并用于生产部署。例如，在 `https://test-app--1234.expo.app` 中，`test-app` 是预览子域名。
部署完成后，EAS CLI 将输出访问您已部署应用的预览 URL。
## 生产部署
要创建生产部署，请运行以下 [EAS CLI](/develop/tools/#eas-cli) 命令：
```sh
$ eas deploy --prod
```
部署完成后，EAS CLI 将输出访问您已部署应用的生产 URL。
## 自动部署
您可以使用 [EAS Workflows](/eas/workflows/get-started/) 自动将应用部署到网络上。首先，您需要 [配置您的项目](/eas/workflows/get-started/#configure-your-project)，在项目根目录下添加名为 **.eas/workflows/deploy-web.yml** 的文件，然后添加以下工作流程配置：
```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` 分支时创建一个网络部署。您还可以使用以下 EAS CLI 命令手动运行此工作流：
```sh
$ eas workflow:run deploy-web.yml
```
了解有关常见模式的更多信息，请参考 [工作流示例指南](/eas/workflows/examples)。
## 了解更多
您可以了解有关设置 [部署别名](/eas/hosting/deployments-and-aliases/)、使用 [自定义域名](/eas/hosting/custom-domain/) 或 [部署 API 路由](/router/reference/api-routes/#deployment) 的更多信息。


# 监控

## 监控服务

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

一旦您的应用发布，您可以跟踪匿名使用数据，以便了解用户如何使用您的应用。这些数据包括正在使用的更新、用户遇到错误的时间等。
## EAS Insights
Expo 提供了 [`expo-insights`](/eas-insights/introduction/) 库，用于跟踪与 [EAS 更新](/deploy/send-over-the-air-updates/) 相关的信息。此数据包括应用版本、平台、操作系统版本和更新采纳情况。在您安装它并在应用商店发布生产版本后，您将能够在项目仪表板上看到更多数据：
可以通过以下指南开始：
## LogRocket
您可以通过 [LogRocket](https://logrocket.com) 获取更多见解。LogRocket 记录用户会话，并在用户使用应用时识别错误。您可以通过更新 ID 来过滤会话，也可以在 EAS 仪表板上连接到您的 LogRocket 账户，以便快速访问应用的会话数据。
可以通过以下指南开始：
## Sentry
[Sentry](http://getsentry.com/) 是一个崩溃报告平台，提供生产部署的实时洞察信息，帮助重现和修复崩溃。
它会提醒您用户在使用应用时遇到的异常或错误，并在网页仪表板上为您整理这些信息。报告的异常包括堆栈跟踪、设备信息、版本和其他相关上下文。您还可以提供与您的应用特定相关的额外上下文，如当前路由和用户 ID。
可以通过以下指南开始：
## Vexo
[Vexo](https://www.vexo.co/) 帮助您了解用户如何与您的 Expo 应用互动，识别摩擦点，并改善用户参与。它提供实时用户分析，只需简单的两行集成，并提供一个完整的仪表板，深入了解用户活动、应用性能和采纳趋势，配合热图、会话重放等功能。
可以通过以下指南开始：
## BugSnag
[BugSnag](https://www.bugsnag.com/) 是一个稳定性监控解决方案，提供丰富的端到端错误报告和分析，以快速而准确地重现和修复错误。BugSnag 支持全栈，提供超过 50 个平台的开源库，包括 React Native。
可以通过以下指南开始：


# 更多

## 核心概念

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

Expo 是一个[开源框架](https://github.com/expo/expo/) ，用于在 Android、iOS 和网页上原生运行的应用程序。Expo 将移动和网页的最佳功能结合在一起，使构建和扩展应用程序的许多重要功能成为可能。
`expo` npm 软件包为 React Native 应用程序提供了一套令人惊叹的功能。`expo` 软件包几乎可以安装在 **任何 React Native 项目** 中。
## 工具和功能
> **info** 所有功能都是免费的、可选的，并且可以相互独立使用。未使用的功能不会给您的应用程序增加额外的负担。
| 功能                                                                 | 使用 `expo` | 不使用 `expo` （简单 React Native） |
| -------------------------------------------------------------------- | ----------- | ----------------------------------- |
| 完全用 JavaScript 开发复杂应用。                                     | <YesIcon /> | <NoIcon />                          |
| 使用 Swift 和 Kotlin 编写 JSI 原生模块。                             | <YesIcon /> | <NoIcon />                          |
| 无需 Xcode 或 Android Studio 开发应用。                              | <YesIcon /> | <NoIcon />                          |
| 使用 [Snack](https://snack.expo.dev/) 在浏览器中创建和共享示例应用。 | <YesIcon /> | <NoIcon />                          |
| 进行大规模升级而无须进行原生更改。                                   | <YesIcon /> | <NoIcon />                          |
| 一流的 TypeScript 支持。                                             | <YesIcon /> | <NoIcon />                          |
| 从命令行安装与原生兼容的库。                                         | <YesIcon /> | <NoIcon />                          |
| 使用相同的代码库开发高性能的网站。                                   | <YesIcon /> | <NoIcon />                          |
| 将您的开发服务器 [隧道](/more/expo-cli/#tunneling) 到任何设备。      | <YesIcon /> | <NoIcon />                          |
## 服务
Expo 背后的团队还提供 **Expo 应用服务（EAS）**，深度集成的云服务，用于构建、提交和更新您的 React Native 应用。EAS 可以与 **任何 React Native 应用** 一起使用，无论它是否使用 `expo`。


## 常见问题解答

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

此页面列出了一些有关 Expo 及相关服务的常见问题和答复。如果您有未在此处回答的问题，请参阅 [论坛](https://chat.expo.dev/) 以获取更多常见问题。
## Expo 用于什么？
Expo 是一个 [开源框架](https://github.com/expo/expo)，用于在 Android、iOS 和 Web 上本地运行的应用。Expo 将移动和 Web 的最佳结合在一起，并为构建和扩展应用提供许多重要功能，例如实时更新、即时共享您的应用和 Web 支持。`expo` npm 包为 React Native 应用启用了一套令人惊叹的功能。`expo` 包几乎可以安装在任何 React Native 项目中。有关更多信息，请参阅 [Expo 提供的内容](/core-concepts)。
## 公司使用 Expo 吗？
是的，Expo 被全世界的顶级公司使用，服务数亿终端用户。请查看我们的[展示](https://expo.dev/customers)。
## 为什么 Expo 有自己的 SDK？
当 Expo 首次创建时，React Native 尚未公开发布。这意味着没有第三方包。为了使 React Native 的开发体验合理，我们创建了[几个库以实现常见功能](/versions/latest)。这些库许多已经被分叉和修改以满足各种需求。我们欢迎用户根据需要混合和匹配任何 [自定义原生代码](/workflow/customizing)，以使他们的应用变得出色。
Expo SDK 经过充分测试，使用 TypeScript 编写，具有文档记录，并为 Android、iOS 和 Web 构建。Expo SDK 中的每个模块都协同工作，以确保版本始终匹配。这创造了良好的升级体验。
Expo SDK 还使用 [Expo Modules API](/modules) 编写，以使贡献、维护和理解更容易。
## Expo 和 React Native 之间有什么区别？
`expo` 包提供了一套简化复杂 React Native 应用开发和扩展的功能。您可以在几乎所有的 React Native 应用中安装 `expo`。不过，使用 [Expo 应用服务 (EAS)](/eas) 或 React Native 并不需要 `expo` 包，但我们强烈推荐使用。有关更多信息，请参阅 [Expo 提供的内容](/core-concepts)。
## 我需要从 React Native 切换到 Expo 吗？
不，`expo` npm 包和 CLI 适用于任何 React Native 应用。[Expo 应用服务 (EAS)](/eas) 也适用于所有 React Native 应用，提供构建、更新、应用商店提交等一流支持。
## Expo 的费用是多少？
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 应用是开始的最简单方法，也可以在应用商店免费获得。
[Expo 应用服务 (EAS)](/eas) 是 Expo 团队为 React Native 应用提供的一套可选云服务。EAS 使构建应用、提交到应用商店、保持更新、发送推送通知等变得更容易。如果 [免费计划](https://expo.dev/pricing) 的配额足够满足您的应用需求，则可以免费使用 EAS。更多信息请查看 [定价页面](https://expo.dev/pricing)。
## 如何将自定义原生代码添加到我的 Expo 项目？
Expo 支持添加自定义原生代码并自定义该代码（Android/Xcode 项目）。要使用任何自定义原生代码，您可以创建一个 [开发构建](/develop/development-builds/introduction/) 和 [配置插件](/config-plugins/introduction)。我们确实推荐在可能的情况下使用 [Expo SDK](/versions/latest) 中的模块，以便更轻松地进行升级并改善开发者体验。
## 我可以在使用 React Native CLI 创建的应用中使用 Expo 吗？
可以！所有 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) 的信息。
## 我如何分享我的 Expo 项目？我可以将其提交到应用商店吗？
分享您项目的最快方法是通过 [EAS 更新](/eas-update/introduction) 发布，并在 [开发构建](/develop/development-builds/introduction/) 中启动。这会为您的应用提供一个 URL；您可以与任何拥有 Android 或 iOS 的 [开发构建](/develop/development-builds/introduction/) 的人共享该 URL。URL 也可以在 Android 的 Expo Go 中打开。
准备好后，您可以创建一个生产构建 (**.aab** 和 **.ipa**) 以提交到应用商店。您可以通过 [EAS 构建](/build/introduction) 使用单个命令构建应用，并通过 [EAS 提交](/submit/introduction) 将其提交到商店。
您还可以使用 [内部分发](/build/internal-distribution) 通过 APK 在 Android 上共享应用，并在 iOS 上使用 Ad-hoc 或企业配置。
## 我可以在 Windows 电脑上开发 iOS 应用吗？
传统上，您需要 macOS 才能开发 iOS 应用，但是，您可以使用 [EAS 构建](/build/introduction) 在云中构建应用。您还可以使用 [EAS 提交](/submit/introduction) 将您的应用提交到商店。可以使用 [Expo Go](https://expo.dev/go) 或 [开发构建](/develop/development-builds/introduction/) 在物理 iOS 设备上进行测试。
## Expo SDK 支持哪些版本的 Android 和 iOS？
目前，Expo SDK 支持 Android {latestSdkVersionValues.android} 和 iOS {latestSdkVersionValues.ios}。欲了解更多信息，请参见 [对 Android 和 iOS 版本的支持](/versions/latest/#support-for-android-and-ios-versions)。
## “hello world” expo 应用的最小大小是多少？
使用纯 Expo 创建的最低生产应用小于 3 MB。对于 iOS，Expo 目标是较新最低 iOS 版本，以便能够进行应用商店优化。
如果您的应用中包含 `expo` 包，它在应用商店的最终应用大小中只一次增加 1 MB。`expo` 包的大小开销很小（例如，Android 上为 150 Kib）。其余大小来自语言运行时（如 Android 上的 Kotlin）。
## 我可以将 Expo 与我的原生库一起使用吗？
您可以通过使用 Swift 和 Kotlin 创建 [自定义原生模块](/modules) 来将原生 Android 和 iOS 库与 Expo 一起使用。许多流行的库已经具有自定义原生模块。查看我们的 [React Native 目录](https://reactnative.directory)，以查找适合您用例的流行库。
## 我可以将 Expo 与这个 Web 库一起使用吗？
许多流行的 Web 包，如 three.js，可以与 Expo 和 React Native 一起使用。有关更多信息，请参见 [Expo 示例](https://github.com/expo/examples)。
## Expo 是否类似于用于 Web 开发的 React？
Expo 是一个 [开源框架](https://github.com/expo/expo)，用于在 Android、iOS 和 Web 上本地运行的应用。React Native 类似于 Web 开发中的 `react-dom`，使您能够在特定平台上运行 React，然而，它有一些关键的区别：
- React Native 不支持 HTML 或 CSS。
- React Native 使用原生组件，而不是使用 DOM。例如，使用 `<View />` 代替 `<div />`。原生组件比 DOM 更高效，并提供更佳的用户体验。
- 与访问浏览器 API 的 React.js 不同，React Native 使用自定义原生 API。例如，使用 `expo-location` 代替 `navigator.geolocation` 访问用户位置。自定义原生 API 类似于浏览器 API，但您可以对其进行完全控制。这意味着您可以在这些功能在浏览器中可用之前访问新特性。
与 React.js 框架帮助用户轻松创建更大的网站类似，Expo 帮助用户轻松创建更大的应用。Expo 提供了一套经过充分测试的 React Native 模块，能够在 Android、iOS 和 Web 上运行。Expo 还提供了一套工具 [工具](/eas) 用于构建、部署和更新您的应用。
## 关于解释性代码的商店政策是什么？
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) 以获取最新政策信息。
_以下是截至 2024 年 4 月 25 日的相关政策摘录。_
### Google Play 商店
```text
...应用可能无法从 Google Play 以外的来源下载可执行代码（例如 dex、JAR、.so 文件）。此限制不适用于在虚拟机或解释器中运行的代码，这两者都提供间接访问 Android API 的权限（例如，Webview 或浏览器中的 JavaScript）。
应用或第三方代码（如 SDK），使用解释性语言（JavaScript、Python、Lua 等）在运行时加载（例如，未与应用打包）必须不允许对 Google Play 政策的潜在违反。
```
来源： [Google Play 政策中心](https://support.google.com/googleplay/android-developer/answer/9888379?hl=en).
### Apple 应用商店
```text
...解释性代码可以下载到应用程序中，但前提是该代码：
(a) 不通过提供与应用程序作为提交到应用商店的意图和广告目的不一致的特性或功能改变应用程序的主要目的，
(b) 不为其他代码或应用程序创建商店或销售点，以及
(c) 不绕过操作系统的签名、沙盒或其他安全功能。
```
来源： [3.3.1 APIs 和功能 - B. 可执行代码](https://developer.apple.com/support/terms/apple-developer-program-license-agreement#b331).
## 我应该使用 Expo CLI 还是 React Native Community CLI？
Expo CLI 提供与 React Native Community CLI（也称为 “React Native CLI”）相同的核心功能，并具有额外的功能，例如自动 [TypeScript 设置](/guides/typescript)、[Web 支持](/workflow/web)、[自动安装兼容库](/more/expo-cli/#install)、[改进的原生构建命令](/more/expo-cli#compiling)、[隧道功能](/more/expo-cli#tunneling)、[预构建](/workflow/prebuild) 等。
它可以与 React Native Community 同时使用。无论您使用哪个 CLI，您都可以在项目中使用 [Expo SDK](/versions/latest/) 和 [Expo 应用服务](/eas) 的任何部分。有关更多信息，请查看：
- 了解如何在 [现有 React Native 项目](/bare/using-expo-cli/) 中迁移到使用 Expo CLI。
- 了解 [使用框架构建 React Native 应用](https://reactnative.dev/blog/2024/06/25/use-a-framework-to-build-react-native-apps) 的好处。
- 了解迁移到 Expo CLI 的好处，如提高应用性能、加快发布速度并促进团队间更强协作，在 [这篇博客文章](https://expo.dev/blog/from-rnc-cli-to-expo) 中。
> **注意：** EAS Build 与现有的 React Native 项目兼容（原生目录已检查到版本控制中）。当这些目录存在时，EAS Build 不会运行预构建步骤，因为这可能会覆盖您对原生项目文件所做的任何手动自定义。您需要使用 Android Studio 或 Xcode 等原生工具自行配置原生目录。
## Expo Go 是开源的吗？
是的，Expo Go 的源代码可以在 [expo/expo GitHub 仓库](https://github.com/expo/expo) 的 **apps/expo-go** 目录中找到。Expo Go 应用也是使用 Expo 和 React Native 构建的。
## 我可以用 Expo Go 做什么或不能做什么？
[Expo Go](/get-started/set-up-your-environment/?redirected=#how-would-you-like-to-develop) 是一个沙盒，可以帮助您快速开始 React Native 开发，以便学习、原型设计或实验。它允许您使用包含在 Expo SDK 中的库和不需要自定义原生代码的库。
Expo Go 不能使用需要自定义原生代码的第三方库，您也无法在 Expo Go 中直接编辑原生代码。它不能用于生产应用。
**我们强烈建议任何需要具有原生代码的附加库的项目迁移到 [开发构建](/develop/development-builds/introduction/)。这就像创建一个特别定制为您应用需求的 Expo Go 版本。**
## 弹出是否被弃用？
是的，弹出是一个被弃用的术语，不再是必需的。当 Expo 首次发布时，应用的原生二进制文件大小较大，并且不支持自定义原生代码而不“弹出”。这一点在 2020 年 12 月随着 [EAS Build](/build/introduction) 的发布而改变，EAS Build 支持任何 React Native 应用。“弹出”的概念在 SDK 41（2021 年 4 月）中被 [`npx expo prebuild`](/workflow/prebuild) 命令取代，该命令根据项目和应用配置（**app.json**）中的库不断生成原生项目。`expo eject` 命令在 SDK 46（2022 年 8 月）中完全被弃用。
与之前的弹出工作流程不同，作者可以通过创建 [配置插件](/config-plugins/introduction/) 将其库配置为与 Expo Prebuild 兼容。这意味着您可以使用任何库与 Expo Prebuild。您还可以通过创建 [开发构建](/develop/development-builds/introduction/) 使用任何自定义原生代码与 Expo Prebuild。了解更多信息，请参阅 [Expo Prebuild 文档](/workflow/prebuild)。


## LLMs 文档

可供大型语言模型 (LLMs) 及其应用程序使用的 Expo 和 EAS 文档文件列表。

在 Expo，我们支持 [llms.txt](https://llmstxt.org/) 计划，为大型语言模型 (LLMs) 及其应用程序提供文档。以下是可用的文档文件列表：
- [/llms.txt](/llms.txt): 所有可用文档文件的列表
- [/llms-full.txt](/llms-full.txt): Expo 的完整文档，包括 Expo Router、Expo Modules API、开发过程等
- [/llms-eas.txt](/llms-eas.txt): Expo 应用服务 (EAS) 的完整文档
- [/llms-sdk.txt](/llms-sdk.txt): 最新 Expo SDK 的完整文档
Note: 寻找已弃用的 Expo SDK 版本？
---
- [/llms-sdk-v53.0.0.txt](/llms-sdk-v53.0.0.txt): Expo SDK v53.0.0 的文档
- [/llms-sdk-v52.0.0.txt](/llms-sdk-v52.0.0.txt): Expo SDK v52.0.0 的文档
- [/llms-sdk-v51.0.0.txt](/llms-sdk-v51.0.0.txt): Expo SDK v51.0.0 的文档
---


## 教程和用户界面的概述

**学习**部分是一个教程和其他指南的集合，帮助您了解 Expo 和 EAS。它涵盖以下内容：


# Expo 教程

## 教程：使用 React Native 和 Expo

这是一个关于如何使用 Expo 构建适用于 Android、iOS 和 web 的通用应用程序的 React Native 教程介绍。

我们即将开始构建通用应用程序的旅程。在本教程中，我们将创建一个在 Android、iOS 和 web 上运行的 Expo 应用；所有这些都使用单一的代码库。让我们开始吧！
## 关于 React Native 和 Expo 教程
本教程的目标是开始使用 Expo，并熟悉 Expo SDK。它将涵盖以下主题：
- 使用启用 TypeScript 的默认模板创建应用
- 使用 Expo Router 实现一个两屏底部标签布局
- 拆分应用布局并使用 flexbox 实现它
- 使用每个平台的系统 UI 从媒体库选择图像
- 使用来自 React Native 的 `<Modal>` 和 `<FlatList>` 组件创建一个贴纸模态
- 添加触摸手势与贴纸进行交互
- 使用第三方库捕捉屏幕截图并保存到磁盘
- 处理 Android、iOS 和 web 之间的平台差异
- 最后，配置状态栏、启动屏幕和图标以完成应用
这些主题为学习构建 Expo 应用的基础提供了支撑。该教程是自定进度的，完成可能需要长达两小时。
为了保持对初学者友好，我们将教程分为九个章节，这样您可以随时跟随或放下然后再回来。每个章节都包含完成步骤所需的代码片段，因此您可以通过从头创建应用或复制粘贴来跟随。
在开始之前，先看看我们将要构建的内容。它是一个名为 **StickerSmash** 的应用，在 Android、iOS 和 web 上运行：
> **info** 本教程的完整源代码可在 [GitHub](https://github.com/expo/examples/tree/master/stickersmash) 上找到。
## 如何使用本教程
我们相信通过 [实践学习](https://en.wikipedia.org/wiki/Learning-by-doing)，因此本教程强调实践而非解释。您可以通过从头创建应用的过程来跟随构建应用的旅程。
在整个教程中，任何重要的代码或在示例之间发生变化的代码将被 <span className="tutorial-code-annotation">高亮显示为绿色</span>。您可以将鼠标悬停在高亮部分（在桌面上）或在移动设备上点击它们以了解更多更改信息。比如，下面代码片段中高亮的代码解释了它的功能：
```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',
  },
});
```
## 下一步
我们准备开始构建我们的应用。


## 创建你的第一个应用

在本章中，学习如何创建一个新的 Expo 项目。

在本章中，让我们学习如何创建一个新的 Expo 项目以及如何使其运行。
Video Tutorial: [观看：创建你的第一个通用 Expo 应用](https://www.youtube.com/watch?v=m1-bc53EGh8)
---
## 前提条件
我们需要以下内容来开始：
- 在物理设备上安装 [Expo Go](https://expo.dev/go)
- 安装 [Node.js (LTS 版本)](https://nodejs.org/en)
- 安装 [VS Code](https://code.visualstudio.com/) 或其他首选的代码编辑器或 IDE
- 拥有一个打开终端窗口的 macOS、Linux 或 Windows（PowerShell 和 [WSL2](https://expo.fyi/wsl)）
本教程假设你对 TypeScript 和 React 有一定的了解。如果你不熟悉它们，可以查看 [TypeScript 手册](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html) 和 [React 的官方教程](https://react.dev/learn)。
Step 1: 
## 初始化一个新的 Expo 应用
我们将使用 [`create-expo-app`](/more/create-expo/) 来初始化一个新的 Expo 应用。它是一个用于创建新的 React Native 项目的命令行工具。在你的终端中运行以下命令：
```sh
$ npx create-expo-app@latest StickerSmash
$ cd StickerSmash
```
该命令将创建一个名为 StickerSmash 的新项目目录，使用 [默认](/more/create-expo/#--template) 模板。该模板具有构建我们的应用所需的基本样板代码和库，包括 Expo Router。我们将继续根据需要在本教程中添加更多库。
Note: 使用默认模板的好处
---
- 创建一个安装了 `expo` 包的新 React Native 项目
- 包含推荐的工具，如 Expo CLI
- 包含来自 Expo Router 的标签导航器，以提供基本导航系统
- 自动配置为在多个平台上运行：Android、iOS 和 web
- 默认配置为使用 TypeScript
---
Step 2: 
## 下载资产
下载归档后：
1. 解压归档并用新资产替换 **your-project-name/assets/images** 目录中的默认资产。
2. 在代码编辑器或 IDE 中打开项目目录。
Step 3: 
## 运行 reset-project 脚本
在本教程中，我们将从头开始构建我们的应用并理解添加基于文件的导航的基本概念。让我们运行 `reset-project` 脚本以移除样板代码：
```sh
$ npm run reset-project
```
运行上述命令后，**app** 目录中将只剩下两个文件（**index.tsx** 和 **\_layout.tsx**）。脚本将 **app** 和其他目录（**components**、**constants** 和 **hooks** 中的样板代码）中的先前文件移动到名为 **app-example** 的子目录中。我们将随着进度创建自己的目录和组件文件。
Note:   脚本做了什么？
---
`reset-project` 脚本重置项目中的 **app** 目录结构，并将项目根目录中的以前样板文件复制到名为 **app-example** 的其他子目录中。我们可以删除它，因为它不属于我们主应用的结构。
---
Step 4: 
## 在移动设备和网页上运行应用
在项目目录中，运行以下命令以从终端启动[开发服务器](/more/glossary-of-terms/#development-server)：
```sh
$ npx expo start
```
运行上述命令后：
1. 开发服务器将启动，你将在终端窗口中看到一个二维码。
2. 扫描该二维码以在设备上打开应用。在 Android 上，使用 Expo Go > **Scan QR code** 选项。在 iOS 上，使用默认的相机应用。
3. 要运行网页应用，请在终端中按 <kbd>w</kbd>。这将在默认网页浏览器中打开网页应用。
一旦在所有平台上运行，应用应如下所示：
Step 5: 
## 编辑首页屏幕
**app/index.tsx** 文件定义了在应用屏幕上显示的文本。它是我们应用的入口点，并在开发服务器启动时执行。它使用核心 React Native 组件，如 `<View>` 和 `<Text>` 来显示背景和文本。
应用于这些组件的样式使用 JavaScript 对象，而不是在网络上使用的 CSS。然而，如果你之前在网络上使用过 CSS，许多属性将是你所熟悉的。大多数 React Native 组件接受 `style` 属性，该属性将 JavaScript 对象作为其值。有关更多详细信息，请参见 [React Native 中的样式](https://reactnative.dev/docs/style)。
让我们修改 **app/index.tsx** 屏幕：
1. 从 `react-native` 中导入 `StyleSheet` 并创建一个 `styles` 对象以定义我们的自定义样式。
2. 将 `styles.container.backgroundColor` 属性添加到 `<View>` 中，值为 `#25292e`。这会改变背景颜色。
3. 将 `<Text>` 的默认值替换为 "首页"。
4. 为 `<Text>` 添加 `styles.text.color` 属性，值为 `#fff`（白色），以改变文本颜色。
```tsx app/index.tsx|collapseHeight=340
export default function Index() {
  return (
    <View style={styles.container}>
      <Text style={styles.text}>首页</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
    justifyContent: 'center',
  },
  text: {
    color: '#fff',
  },
});
```
> React Native 使用与 web 相同的颜色格式。它支持十六进制三位数（这就是 `#fff`），`rgba`，`hsl` 和命名颜色，例如 `red`、`green`、`blue`、`peru` 和 `papayawhip`。有关更多信息，请参见 [React Native 中的颜色](https://reactnative.dev/docs/colors)。
一旦你保存你的更改，它们会被发送并应用到连接到开发服务器的运行中的应用：
## 总结
<ProgressTracker
  currentChapterIndex={0}
  name="GET_STARTED"
  summary="我们成功创建了一个新的 Expo 项目，使用了 React Native 核心组件，并准备开发我们的 StickerSmash 应用。"
  nextChapterDescription="在下一章中，我们将学习如何在我们的应用中添加堆栈和标签导航。"
  nextChapterTitle="添加导航"
  nextChapterLink="/tutorial/add-navigation/"
/>


## 添加导航

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

在本章中，我们将学习 Expo Router 的基本知识，以创建堆栈导航和带有两个选项卡的底部选项卡栏。
Video Tutorial: [观看：在您的通用 Expo 应用中添加导航](https://www.youtube.com/watch?v=8336fcFV_T4)
## Expo Router 基础知识
Expo Router 是一个基于文件的路由框架，用于 React Native 和 Web 应用。它管理屏幕之间的导航，并在多个平台上使用相同的组件。要开始，我们需要了解以下约定：
- **app 目录**：一个特殊目录，仅包含路由及其布局。添加到此目录的任何文件都会成为我们本地应用中的一个屏幕和网页上的一个页面。
- **根布局**：**app/\_layout.tsx** 文件。它定义了共享的 UI 元素，例如标题和选项卡栏，以便在不同的路由之间保持一致。
- **文件名约定**：_Index_ 文件名，如 **index.tsx**，与其父目录匹配，并且不添加路径段。例如，**app** 目录中的 **index.tsx** 文件匹配 `/` 路由。
- 一个 **路由** 文件将一个 React 组件作为其默认值导出。它可以使用 `.js`、`.jsx`、`.ts` 或 `.tsx` 扩展名。
- Android、iOS 和 Web 共享统一的导航结构。
> 上述列表足够我们开始。有关功能的完整列表，请参见 [Introduction to Expo Router](/router/introduction/)。
Step 1: 
## 将新屏幕添加到堆栈中
让我们在 **app** 目录中创建一个名为 **about.tsx** 的新文件。当用户导航到 `/about` 路由时，它会显示屏幕名称。
```tsx app/about.tsx|collapseHeight=300
import { Text, View, StyleSheet } from 'react-native';
export default function AboutScreen() {
  return (
    <View style={styles.container}>
      <Text style={styles.text}>About screen</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    justifyContent: 'center',
    alignItems: 'center',
  },
  text: {
    color: '#fff',
  },
});
```
在 **\_layout.tsx** 中：
1. 添加一个 `<Stack.Screen />` 组件和一个 `options` 属性，以更新 `/about` 路由的标题。
2. 通过添加 `options` 属性，将 `/index` 路由的标题更新为 `首页`。
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: 'Home' }} />
      <Stack.Screen name="about" options={{ title: 'About' }} />
    </Stack>
  );
}
```
Note: 什么是 ?
---
堆栈导航器是应用程序中不同屏幕之间导航的基础。在 Android 上，堆叠路由在当前屏幕上方动画。在 iOS 上，堆叠路由从右侧动画。Expo Router 提供了一个 `Stack` 组件，用于创建导航堆栈以添加新路由。
---
Step 2: 
## 在屏幕之间导航
我们将使用 Expo Router 的 `Link` 组件从 `/index` 路由导航到 `/about` 路由。它是一个 React 组件，渲染具有给定 `href` 属性的 `<Text>`。
1. 在 **index.tsx** 中从 `expo-router` 导入 `Link` 组件。
2. 在 `<Text>` 组件之后添加一个 `Link` 组件，并传递 `href` 属性与 `/about` 路由。
3. 为 `Link` 组件添加 `fontSize`、`textDecorationLine` 和 `color` 的样式。它接受与 `<Text>` 组件相同的属性。
```tsx app/index.tsx|collapseHeight=300
import { Text, View, StyleSheet } from 'react-native';
export default function Index() {
  return (
    <View style={styles.container}>
      <Text style={styles.text}>Home screen</Text>
      <Link href="/about" style={styles.button}>
        Go to About screen
      </Link>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
    justifyContent: 'center',
  },
  text: {
    color: '#fff',
  },
  button: {
    fontSize: 20,
    textDecorationLine: 'underline',
    color: '#fff',
  },
});
```
让我们来看看我们应用中的变化。单击 `Link` 导航到 `/about` 路由：
Step 3: 
## 添加未找到路由
当路由不存在时，我们可以使用 `+not-found` 路由来显示备用屏幕。当我们希望在移动设备上导航到无效路由时显示自定义屏幕，而不是崩溃应用程序或在网页上显示 _404_ 错误时，这非常有用。Expo Router 使用一个特殊的 **+not-found.tsx** 文件来处理这种情况。
1. 在 app 目录中创建一个名为 **+not-found.tsx** 的新文件，以添加 `NotFoundScreen` 组件。
2. 从 `Stack.Screen` 添加 `options` 属性，以显示此路由的自定义屏幕标题。
3. 添加一个 `Link` 组件以导航到 `/` 路由，这是我们的备用路由。
```tsx app/+not-found.tsx
import { View, StyleSheet } from 'react-native';
import { Link, Stack } from 'expo-router';
export default function NotFoundScreen() {
  return (
    <>
      <Stack.Screen options={{ title: 'Oops! Not Found' }} />
      <View style={styles.container}>
        <Link href="/" style={styles.button}>
          Go back to Home screen!
        </Link>
      </View>
    </>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    justifyContent: 'center',
    alignItems: 'center',
  },
  button: {
    fontSize: 20,
    textDecorationLine: 'underline',
    color: '#fff',
  },
});
```
要测试此功能，请在Web浏览器中导航到 `http:localhost:8081/123` URL，因为在这里更改 URL 路径很简单。应用程序应显示 `NotFoundScreen` 组件：
Step 4: 
## 添加底部选项卡导航器
此时，我们的 **app** 目录的文件结构如下所示：
```
app/
    ├── _layout.tsx  # 根布局
    ├── index.tsx  # 匹配路由 '/'
    ├── about.tsx  # 匹配路由 '/about'
    └── +not-found.tsx  # 匹配任何 404 路由
```
我们将在应用中添加一个底部选项卡导航器，并重用现有的首页和关于屏幕以创建选项卡布局（这是许多社交媒体应用（如 X 或 BlueSky）中常见的导航模式）。我们还将在根布局中使用堆栈导航器，因此 `+not-found` 路由会在任何其他嵌套路由上方显示。
1. 在 **app** 目录中，添加一个 **(tabs)** 子目录。这个特殊目录用于将路由组合在一起，并在底部选项卡栏中显示它们。
2. 在目录中创建一个 **(tabs)/\_layout.tsx** 文件。它将用于定义选项卡布局，与根布局分开。
3. 将现有的 **index.tsx** 和 **about.tsx** 文件移动到 **(tabs)** 目录中。**app** 目录的结构将如下所示：
```
app/
    ├── _layout.tsx  # 根布局
    ├── +not-found.tsx  # 匹配任何 404 路由
    └── (tabs)/
        ├── _layout.tsx  # 选项卡布局
        ├── index.tsx  # 匹配路由 '/'
        └── about.tsx  # 匹配路由 '/about'
```
更新根布局文件以添加 `(tabs)` 路由：
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
    </Stack>
  );
}
```
在 **(tabs)/\_layout.tsx** 中，添加一个 `Tabs` 组件以定义底部选项卡布局：
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs>
      <Tabs.Screen name="index" options={{ title: 'Home' }} />
      <Tabs.Screen name="about" options={{ title: 'About' }} />
    </Tabs>
  );
}
```
让我们现在看看我们的应用，以查看新的底部选项卡：
Step 5: 
## 更新底部选项卡导航器外观
现在，底部选项卡导航器在所有平台上的外观相同，但与我们应用的样式不匹配。例如，选项卡栏或标题不显示自定义图标，并且底部选项卡的背景颜色与应用的背景颜色不匹配。
修改 **(tabs)/\_layout.tsx** 文件以添加选项卡栏图标：
1. 从 [`@expo/vector-icons`](/guides/icons/#expovector-icons) 导入 `Ionicons` 图标集 &mdash; 一个包含流行图标集的库。
2. 为 `index` 和 `about` 路由添加 `tabBarIcon`。此函数接受 `focused` 和 `color` 作为参数，并渲染图标组件。从图标集中，我们可以提供自定义图标名称。
3. 为 `Tabs` 组件添加 `screenOptions.tabBarActiveTintColor` 并将其值设置为 `#ffd33d`。这将更改选项卡栏图标和标签在激活时的颜色。
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
import Ionicons from '@expo/vector-icons/Ionicons';
export default function TabLayout() {
  return (
    <Tabs
      screenOptions={{
        tabBarActiveTintColor: '#ffd33d',
      }}
    >
      <Tabs.Screen
        name="index"
        options={{
          title: 'Home',
          tabBarIcon: ({ color, focused }) => (
            <Ionicons name={focused ? 'home-sharp' : 'home-outline'} color={color} size={24} />
          ),
        }}
      />
      <Tabs.Screen
        name="about"
        options={{
          title: 'About',
          tabBarIcon: ({ color, focused }) => (
            <Ionicons name={focused ? 'information-circle' : 'information-circle-outline'} color={color} size={24}/>
          ),
        }}
      />
    </Tabs>
  );
}
```
让我们也使用 `screenOptions` 属性更改选项卡栏和标题的背景颜色：
```tsx app/(tabs)/_layout.tsx
<Tabs
  screenOptions={{
    tabBarActiveTintColor: '#ffd33d',
    headerStyle: {
      backgroundColor: '#25292e',
    },
    headerShadowVisible: false,
    headerTintColor: '#fff',
    tabBarStyle: {
      backgroundColor: '#25292e',
    },
  }}
>
```
在上面的代码中：
- 使用 `headerStyle` 属性将标题的背景设置为 `#25292e`。我们还禁用了标题的阴影，使用 `headerShadowVisible`。
- `headerTintColor` 将标题标签应用为 `#fff`
- `tabBarStyle.backgroundColor` 将 `#25292e` 应用为选项卡栏
我们的应用现在有一个自定义的底部选项卡导航器：
## 总结
<ProgressTracker
  currentChapterIndex={1}
  name="GET_STARTED"
  summary="我们成功地向应用添加了堆栈和选项卡导航器。"
  nextChapterDescription="在下一章中，我们将学习如何构建应用的第一个屏幕。"
  nextChapterTitle="构建您的应用的第一个屏幕"
  nextChapterLink="/tutorial/build-a-screen"
/>


## 创建一个屏幕

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

在本章中，我们将创建 StickerSmash 应用的第一个屏幕。
上面的屏幕显示了一张图片和两个按钮。应用用户可以通过两个按钮中的一个选择一张图片。第一个按钮允许用户从他们的设备中选择一张图片。第二个按钮允许用户继续使用应用提供的默认图片。
一旦用户选择了一张图片，他们可以在其上添加贴纸。所以，让我们开始创建这个屏幕。
Video Tutorial: [观看：在您的通用 Expo 应用中构建一个屏幕](https://www.youtube.com/watch?v=3rcOP8xDwTQ)
---
Step 1: 
## 拆分屏幕
在通过编写代码构建这个屏幕之前，让我们将其拆分为一些基本元素。
有两个基本元素：
- 在屏幕中间显示一张大图
- 屏幕下半部分有两个按钮
第一个按钮包含多个组件。父元素提供了一个黄色边框，并在一行中包含了一个图标和文本组件。
现在我们已经将 UI 拆分为较小的部分，我们准备开始编码。
Step 2: 
## 显示图片
我们将使用 `expo-image` 库在应用中显示图片。它提供了一个跨平台的 `<Image>` 组件来加载和渲染一张图片。
通过在终端中按 <kbd>Ctrl</kbd> + <kbd>c</kbd> 停止开发服务器。然后，安装 `expo-image` 库：
```sh
$ npx expo install expo-image
```
[`npx expo install`](/more/expo-cli/#installation) 命令将安装该库并将其添加到 **package.json** 的项目依赖中。
> **info** **提示：** 每当我们在项目中安装新库时，通过在终端中按 <kbd>Ctrl</kbd> + <kbd>c</kbd> 停止开发服务器，然后运行安装命令。在安装完成后，我们可以通过在同一个终端窗口中运行 `npx expo start` 来再次启动开发服务器。
Image 组件将图片的来源作为其值。来源可以是 [静态资产](https://reactnative.dev/docs/images#static-image-resources) 或一个 URL。例如，来自 **assets/images** 目录的来源是静态的。它也可以来自 [网络](https://reactnative.dev/docs/images#network-images) 作为 `uri` 属性。
要在 **app/(tabs)/index.tsx** 文件中使用 Image 组件：
1. 从 `expo-image` 库中导入 `Image`。
2. 创建一个 `PlaceholderImage` 变量以便在 `Image` 组件中使用 **assets/images/background-image.png** 文件作为 `source` 属性。
```tsx app/(tabs)/index.tsx|collapseHeight=380
import { View, StyleSheet } from 'react-native';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <Image source={PlaceholderImage} style={styles.image} />
      </View>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  image: {
    width: 320,
    height: 440,
    borderRadius: 18,
  },
});
```
Step 3: 
## 将组件分割到文件中
随着我们向这个屏幕添加更多组件，让我们将代码分割到多个文件中。在本教程中，我们将使用组件目录来创建自定义组件。
1. 创建一个顶级 **components** 目录，并在其中创建 **ImageViewer.tsx** 文件。
2. 将显示该图像的代码与 `image` 样式一起移动到该文件中。
```tsx components/ImageViewer.tsx|collapseHeight=280
import { ImageSourcePropType, StyleSheet } from 'react-native';
import { Image } from 'expo-image';
type Props = {
  imgSource: ImageSourcePropType;
};
export default function ImageViewer({ imgSource }: Props) {
  return <Image source={imgSource} style={styles.image} />;
}
const styles = StyleSheet.create({
  image: {
    width: 320,
    height: 440,
    borderRadius: 18,
  },
});
```
> **info** 因为 **ImageViewer** 是一个自定义组件，我们将其放在一个独立的目录中，而不是 **app** 目录中。每个文件都在 **app** 目录中，要么是布局文件，要么是路由文件。更多信息，请参见 [非导航组件位于 app 目录之外](/router/basics/core-concepts/#5-non-navigation-components-live-outside-of-app-directory)。
导入 `ImageViewer` 并在 **app/(tabs)/index.tsx** 中使用它：
```tsx app/(tabs)/index.tsx|collapseHeight=320
import { StyleSheet, View } from 'react-native';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} />
      </View>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
});
```
Note: 什么是导入语句中的 ?
---
`@` 符号是一个自定义 [路径别名](/guides/typescript/#path-aliases-optional)，用来导入自定义组件和其他模块，而不是相对路径。Expo CLI 会自动在 **tsconfig.json** 中配置它。
---
Step 4: 
## 使用 Pressable 创建按钮
React Native 包含几个不同的组件来处理触摸事件，但推荐使用 [`<Pressable>`](https://reactnative.dev/docs/pressable)，因为它的灵活性。它可以检测单击、长按，在按钮按下和释放时触发不同事件，等等。
在设计中，我们需要创建两个按钮。每个按钮都有不同的样式和标签。让我们首先为这些按钮创建一个可重用的组件。在 **components** 目录中创建一个 **Button.tsx** 文件，内容如下：
```tsx components/Button.tsx|collapseHeight=280
import { StyleSheet, View, Pressable, Text } from 'react-native';
type Props = {
  label: string;
};
export default function Button({ label }: Props) {
  return (
    <View style={styles.buttonContainer}>
      <Pressable style={styles.button} onPress={() => alert('You pressed a button.')}>
        <Text style={styles.buttonLabel}>{label}</Text>
      </Pressable>
    </View>
  );
}
const styles = StyleSheet.create({
  buttonContainer: {
    width: 320,
    height: 68,
    marginHorizontal: 20,
    alignItems: 'center',
    justifyContent: 'center',
    padding: 3,
  },
  button: {
    borderRadius: 10,
    width: '100%',
    height: '100%',
    alignItems: 'center',
    justifyContent: 'center',
    flexDirection: 'row',
  },
  buttonLabel: {
    color: '#fff',
    fontSize: 16,
  },
});
```
当用户点击屏幕上的任何按钮时，应用会显示一个警告。这是因为 `<Pressable>` 在其 `onPress` 属性中调用了 `alert()`。让我们将这个组件导入到 **app/(tabs)/index.tsx** 文件中，并为包含这些按钮的 `<View>` 添加样式：
```tsx app/(tabs)/index.tsx
import { View, StyleSheet } from 'react-native';
import ImageViewer from '@/components/ImageViewer';
const PlaceholderImage = require("@/assets/images/background-image.png");
export default function Index() {
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} />
      </View>
      <View style={styles.footerContainer}>
        <Button label="Choose a photo" />
        <Button label="Use this photo" />
      </View>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
    paddingTop: 28,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
});
```
让我们看看我们的应用在 Android、iOS 和网页上的效果：
标签为 "使用这张照片" 的第二个按钮类似于设计中的实际按钮。然而，第一个按钮需要更多的样式来匹配设计。
Step 5: 
## 增强可重用的按钮组件
"选择照片" 按钮需要与 "使用这张照片" 按钮不同的样式，所以我们将添加一个新的按钮主题属性，使其能够应用 `primary` 主题。这个按钮在标签前面还有一个图标。我们将使用来自 `@expo/vector-icons` 库的图标。
为了加载并显示按钮上的图标，让我们使用库中的 `FontAwesome`。修改 **components/Button.tsx** 文件以添加以下代码片段：
```tsx components/Button.tsx
import { StyleSheet, View, Pressable, Text } from 'react-native';
type Props = {
  label: string;
};
  if (theme === 'primary') {
    return (
      <View
        style={[
          styles.buttonContainer,
          { borderWidth: 4, borderColor: '#ffd33d', borderRadius: 18 },
        ]}>
        <Pressable
          style={[styles.button, { backgroundColor: '#fff' }]}
          onPress={() => alert('You pressed a button.')}>
          <FontAwesome name="picture-o" size={18} color="#25292e" style={styles.buttonIcon} />
          <Text style={[styles.buttonLabel, { color: '#25292e' }]}>{label}</Text>
        </Pressable>
      </View>
    );
  }
  return (
    <View style={styles.buttonContainer}>
      <Pressable style={styles.button} onPress={() => alert('You pressed a button.')}>
        <Text style={styles.buttonLabel}>{label}</Text>
      </Pressable>
    </View>
  );
}
const styles = StyleSheet.create({
  buttonContainer: {
    width: 320,
    height: 68,
    marginHorizontal: 20,
    alignItems: 'center',
    justifyContent: 'center',
    padding: 3,
  },
  button: {
    borderRadius: 10,
    width: '100%',
    height: '100%',
    alignItems: 'center',
    justifyContent: 'center',
    flexDirection: 'row',
  },
  buttonIcon: {
    paddingRight: 8,
  },
  buttonLabel: {
    color: '#fff',
    fontSize: 16,
  },
});
```
让我们了解一下上述代码的作用：
- 主要主题按钮使用 **内联样式**，这会覆盖使用 `StyleSheet.create()` 定义的样式，并直接将对象传递给 `style` 属性。
- 主要主题中的 `<Pressable>` 组件使用 `backgroundColor` 属性，其值为 `#fff` 来将按钮的背景设置为白色。如果我们将此属性添加到 `styles.button`，则背景颜色值将同时应用于主要主题和未样式化的按钮。
- 内联样式使用 JavaScript，并为特定值覆盖默认样式。
现在，修改 **app/(tabs)/index.tsx** 文件，以便在第一个按钮上使用 `theme="primary"` 属性。
```tsx app/(tabs)/index.tsx
import { View, StyleSheet } from 'react-native';
import Button from '@/components/Button';
import ImageViewer from '@/components/ImageViewer';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} />
      </View>
      <View style={styles.footerContainer}>
        <Button theme="primary" label="Choose a photo" />
        <Button label="Use this photo" />
      </View>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
});
```
让我们看看我们的应用在 Android、iOS 和网页上的效果：
## 小结
<ProgressTracker
  currentChapterIndex={2}
  name="GET_STARTED"
  summary="我们已经成功实现了初始设计，以开始构建我们应用的第一个屏幕。"
  nextChapterDescription="在下一章中，我们将添加从设备媒体库中选择图像的功能。"
  nextChapterTitle="使用图像选择器"
  nextChapterLink="/tutorial/image-picker"
/>


## 使用图像选择器

在本教程中，学习如何使用 Expo 图像选择器。

React Native 提供内置组件作为标准构建块，例如 `<View>`、`<Text>` 和 `<Pressable>`。我们正在构建一个从设备媒体库中选择图像的功能。这在核心组件中无法实现，我们需要一个库来在我们的应用中添加此功能。
我们将使用 [`expo-image-picker`](/versions/latest/sdk/imagepicker)，这是一个来自 Expo SDK 的库。
> `expo-image-picker` 提供访问系统 UI，以便从手机的库中选择图像和视频。
Video Tutorial: [观看：在您的通用 Expo 应用中使用图像选择器](https://www.youtube.com/watch?v=iEQZU58naS8)
---
Step 1: 
## 安装 expo-image-picker
要安装该库，请运行以下命令：
```sh
$ npx expo install expo-image-picker
```
Step 2: 
## 从设备的媒体库中选择图像
`expo-image-picker` 提供 `launchImageLibraryAsync()` 方法，通过选择设备媒体库中的图像或视频来显示系统 UI。我们将使用上一章中创建的主要主题按钮来从设备的媒体库中选择图像，并创建一个函数以启动设备的图像库以实现此功能。
在 **app/(tabs)/index.tsx** 中，导入 `expo-image-picker` 库并在 `Index` 组件内创建 `pickImageAsync()` 函数：
```tsx app/(tabs)/index.tsx|collapseHeight=440
// ...其余的导入语句保持不变
export default function Index() {
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      console.log(result);
    } else {
      alert('You did not select any image.');
    }
  };
  // ...其余的代码保持不变
}
```
让我们了解上述代码的作用：
- `launchImageLibraryAsync()` 接收一个对象，以指定不同的选项。该对象是我们在调用该方法时传递的 [`ImagePickerOptions`](/versions/latest/sdk/imagepicker/#imagepickeroptions) 对象。
- 当 `allowsEditing` 设置为 `true` 时，用户可以在选择过程中裁剪图像，适用于 Android 和 iOS。
Step 3: 
## 更新按钮组件
按下主要按钮时，我们将在 `Button` 组件上调用 `pickImageAsync()` 函数。在 **components/Button.tsx** 中更新 `Button` 组件的 `onPress` 属性：
```tsx components/Button.tsx
import { StyleSheet, View, Pressable, Text } from 'react-native';
import FontAwesome from '@expo/vector-icons/FontAwesome';
type Props = {
  label: string;
  theme?: 'primary';
  onPress?: () => void;
};
  if (theme === 'primary') {
    return (
      <View
        style={[
          styles.buttonContainer,
          { borderWidth: 4, borderColor: '#ffd33d', borderRadius: 18 },
        ]}>
          <FontAwesome name="picture-o" size={18} color="#25292e" style={styles.buttonIcon} />
          <Text style={[styles.buttonLabel, { color: '#25292e' }]}>{label}</Text>
        </Pressable>
      </View>
    );
  }
  return (
    <View style={styles.buttonContainer}>
      <Pressable style={styles.button} onPress={() => alert('You pressed a button.')}>
        <Text style={styles.buttonLabel}>{label}</Text>
      </Pressable>
    </View>
  );
}
const styles = StyleSheet.create({
  buttonContainer: {
    width: 320,
    height: 68,
    marginHorizontal: 20,
    alignItems: 'center',
    justifyContent: 'center',
    padding: 3,
  },
  button: {
    borderRadius: 10,
    width: '100%',
    height: '100%',
    alignItems: 'center',
    justifyContent: 'center',
    flexDirection: 'row',
  },
  buttonIcon: {
    paddingRight: 8,
  },
  buttonLabel: {
    color: '#fff',
    fontSize: 16,
  },
});
```
在 **app/(tabs)/index.tsx** 中，将 `pickImageAsync()` 函数添加到第一个 `<Button>` 的 `onPress` 属性中。
```tsx app/(tabs)/index.tsx
import { View, StyleSheet } from 'react-native';
import * as ImagePicker from 'expo-image-picker';
import Button from '@/components/Button';
import ImageViewer from '@/components/ImageViewer';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      console.log(result);
    } else {
      alert('You did not select any image.');
    }
  };
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} />
      </View>
      <View style={styles.footerContainer}>
        <Button label="Use this photo" />
      </View>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
});
```
`pickImageAsync()` 函数调用 `ImagePicker.launchImageLibraryAsync()`，然后处理结果。`launchImageLibraryAsync()` 方法返回一个包含所选图像信息的对象。
以下是 `result` 对象及其包含的属性的示例：
For Android: 
```json collapseHeight=280
{
  "assets": [
    {
      "assetId": null,
      "base64": null,
      "duration": null,
      "exif": null,
      "fileName": "ea574eaa-f332-44a7-85b7-99704c22b402.jpeg",
      "fileSize": 4513577,
      "height": 4570,
      "mimeType": "image/jpeg",
      "rotation": null,
      "type": "image",
      "uri": "file:///data/user/0/host.exp.exponent/cache/ExperienceData/%2540anonymous%252FStickerSmash-13f21121-fc9d-4ec6-bf89-bf7d6165eb69/ImagePicker/ea574eaa-f332-44a7-85b7-99704c22b402.jpeg",
      "width": 2854
    }
  ],
  "canceled": false
}
```
For iOS: 
```json collapseHeight=280
{
  "assets": [
    {
      "assetId": "99D53A1F-FEEF-40E1-8BB3-7DD55A43C8B7/L0/001",
      "base64": null,
      "duration": null,
      "exif": null,
      "fileName": "IMG_0004.JPG",
      "fileSize": 2548364,
      "height": 1669,
      "mimeType": "image/jpeg",
      "type": "image",
      "uri": "file:///data/user/0/host.exp.exponent/cache/ExperienceData/%2540anonymous%252FStickerSmash-13f21121-fc9d-4ec6-bf89-bf7d6165eb69/ImagePicker/ea574eaa-f332-44a7-85b7-99704c22b402.jpeg",
      "width": 1668
    }
  ],
  "canceled": false
}
```
For web: 
```json
{
  "assets": [
    {
      "fileName": "some-image.png",
      "height": 720,
      "mimeType": "image/png",
      "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABQAA"
    }
  ],
  "canceled": false
}
```
Step 4: 
## 使用所选图像
`result` 对象提供 `assets` 数组，其中包含所选图像的 `uri`。让我们从图像选择器中获取该值，并使用它在应用中显示所选图像。
修改 **app/(tabs)/index.tsx** 文件：
1. 使用 React 的 [`useState`](https://react.dev/learn/state-a-components-memory#adding-a-state-variable) 钩子声明一个名为 `selectedImage` 的状态变量。我们将使用此状态变量来保存所选图像的 URI。
2. 更新 `pickImageAsync()` 函数以将图像 URI 保存到 `selectedImage` 状态变量中。
3. 将 `selectedImage` 作为道具传递给 `ImageViewer` 组件。
```tsx app/(tabs)/index.tsx
import { View, StyleSheet } from 'react-native';
import * as ImagePicker from 'expo-image-picker';
import { useState } from 'react';
import Button from '@/components/Button';
import ImageViewer from '@/components/ImageViewer';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  const [selectedImage, setSelectedImage] = useState<string | undefined>(undefined);
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      setSelectedImage(result.assets[0].uri);
    } else {
      alert('You did not select any image.');
    }
  };
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} selectedImage={selectedImage} />
      </View>
      <View style={styles.footerContainer}>
        <Button theme="primary" label="Choose a photo" onPress={pickImageAsync} />
        <Button label="Use this photo" />
      </View>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
});
```
将 `selectedImage` 属性传递给 `ImageViewer` 组件，以显示所选图像，而不是占位图像。
1. 修改 **components/ImageViewer.tsx** 文件以接受 `selectedImage` 属性。
2. 图像的来源变得冗长，因此让我们还将其移到名为 `imageSource` 的单独变量中。
3. 将 `imageSource` 作为 `source` 属性的值传递给 `Image` 组件。
```tsx components/ImageViewer.tsx
import { ImageSourcePropType, StyleSheet } from 'react-native';
import { Image } from 'expo-image';
type Props = {
  imgSource: ImageSourcePropType;
  selectedImage?: string;
};
  const imageSource = selectedImage ? { uri: selectedImage } : imgSource;
  return <Image source={imageSource} style={styles.image} />;
}
const styles = StyleSheet.create({
  image: {
    width: 320,
    height: 440,
    borderRadius: 18,
  },
});
```
在上述代码片段中，Image 组件使用条件运算符加载图像的来源。所选图像是一个 [`uri` 字符串](https://reactnative.dev/docs/images#network-images)，而不是占位图像那样的本地资产。
现在让我们看看我们的应用：
> 本教程中示例应用使用的图像来自 [Unsplash](https://unsplash.com)。
## 总结
<ProgressTracker
  currentChapterIndex={3}
  name="GET_STARTED"
  summary="我们成功添加了从设备媒体库中选择图像的功能。"
  nextChapterDescription="在下一章中，我们将学习如何创建一个表情符号选择器模态组件。"
  nextChapterTitle="创建一个表情符号选择器模态"
  nextChapterLink="/tutorial/create-a-modal"
/>


## 创建模态框

在本教程中，学习如何创建一个 React Native 模态框以选择图像。

React Native 提供了一个 [`<Modal>` 组件](https://reactnative.dev/docs/modal)，可以在应用程序的其余部分上显示内容。一般来说，模态框用于吸引用户注意关键的信息或引导他们采取行动。例如，在 [第三章](/tutorial/build-a-screen/#step-7-enhance-the-reusable-button-component) 中，按下按钮后，我们使用 `alert()` 显示了一些占位符文本。这就是模态组件显示覆盖层的方式。
在本章中，我们将创建一个显示表情符号选择器列表的模态框。
Video Tutorial: [观看：在您的通用 Expo 应用中创建模态框](https://www.youtube.com/watch?v=HRAMzrBwVeo)
---
Step 1: 
## 声明一个状态变量以显示按钮
在实现模态框之前，我们将添加三个新按钮。这些按钮在用户从媒体库中选择图像或使用占位符图像后可见。其中一个按钮将触发表情符号选择器模态框。
在 **app/(tabs)/index.tsx** 中：
1. 声明一个布尔状态变量 `showAppOptions`，用于显示或隐藏打开模态的按钮，以及一些其他选项。当应用程序屏幕加载时，我们将其设置为 `false`，这样在选择图像之前不会显示选项。当用户选择图像或使用占位符图像时，我们将其设置为 `true`。
2. 更新 `pickImageAsync()` 函数，在用户选择图像后将 `showAppOptions` 的值设置为 `true`。
3. 更新没有主题的按钮，添加一个 `onPress` 属性，值如下。
```tsx app/(tabs)/index.tsx
import { View, StyleSheet } from 'react-native';
import * as ImagePicker from 'expo-image-picker';
import { useState } from 'react';
import Button from '@/components/Button';
import ImageViewer from '@/components/ImageViewer';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  const [selectedImage, setSelectedImage] = useState<string | undefined>(undefined);
  const [showAppOptions, setShowAppOptions] = useState<boolean>(false);
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      setSelectedImage(result.assets[0].uri);
      setShowAppOptions(true);
    } else {
      alert('You did not select any image.');
    }
  };
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} selectedImage={selectedImage} />
      </View>
      {showAppOptions ? (
        <View />
      ) : (
        <View style={styles.footerContainer}>
          <Button theme="primary" label="Choose a photo" onPress={pickImageAsync} />
          <Button label="Use this photo" onPress={() => setShowAppOptions(true)} />
        </View>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
});
```
在上述代码片段中，我们根据 `showAppOptions` 的值渲染 `Button` 组件，并将按钮移到三元运算符块中。当 `showAppOptions` 的值为 `true` 时，渲染一个空的 `<View>` 组件。我们将在下一步中处理此状态。
现在，我们可以移除 `Button` 组件上的 `alert`，并在 **components/Button.tsx** 中更新第二个按钮的 `onPress` 属性：
```tsx components/Button.tsx
```
Step 2: 
## 添加按钮
让我们分解本章将实现的选项按钮的布局。设计如下：
它包含一个父 `<View>`，其中有三个按钮并排对齐。中间的按钮带有加号图标 (+)，将打开模态框，并且样式与其他两个按钮不同。
在 **components** 目录下，创建一个新的 **CircleButton.tsx** 文件，添加以下代码：
```tsx components/CircleButton.tsx
import { View, Pressable, StyleSheet } from 'react-native';
import MaterialIcons from '@expo/vector-icons/MaterialIcons';
type Props = {
  onPress: () => void;
};
export default function CircleButton({ onPress }: Props) {
  return (
    <View style={styles.circleButtonContainer}>
      <Pressable style={styles.circleButton} onPress={onPress}>
        <MaterialIcons name="add" size={38} color="#25292e" />
      </Pressable>
    </View>
  );
}
const styles = StyleSheet.create({
  circleButtonContainer: {
    width: 84,
    height: 84,
    marginHorizontal: 60,
    borderWidth: 4,
    borderColor: '#ffd33d',
    borderRadius: 42,
    padding: 3,
  },
  circleButton: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    borderRadius: 42,
    backgroundColor: '#fff',
  },
});
```
为了渲染加号图标，此按钮使用 `@expo/vector-icons` 库中的 `<MaterialIcons>` 图标集。
其他两个按钮也使用 `<MaterialIcons>` 来显示垂直对齐的文本标签和图标。在 **components** 目录中创建一个名为 **IconButton.tsx** 的文件。这个组件接受三个属性：
- `icon`: 对应于 `MaterialIcons` 库图标的名称。
- `label`: 显示在按钮上的文本标签。
- `onPress`: 当用户按下按钮时调用的函数。
```tsx components/IconButton.tsx
import { Pressable, StyleSheet, Text } from 'react-native';
import MaterialIcons from '@expo/vector-icons/MaterialIcons';
type Props = {
  icon: keyof typeof MaterialIcons.glyphMap;
  label: string;
  onPress: () => void;
};
export default function IconButton({ icon, label, onPress }: Props) {
  return (
    <Pressable style={styles.iconButton} onPress={onPress}>
      <MaterialIcons name={icon} size={24} color="#fff" />
      <Text style={styles.iconButtonLabel}>{label}</Text>
    </Pressable>
  );
}
const styles = StyleSheet.create({
  iconButton: {
    justifyContent: 'center',
    alignItems: 'center',
  },
  iconButtonLabel: {
    color: '#fff',
    marginTop: 12,
  },
});
```
在 **app/(tabs)/index.tsx** 中：
1. 导入 `CircleButton` 和 `IconButton` 组件以显示它们。
2. 为这些按钮添加三个占位符函数。`onReset()` 函数在用户按下重置按钮时调用，使图像选择按钮再次出现。我们稍后将为其他两个函数添加功能。
```tsx app/(tabs)/index.tsx
import { View, StyleSheet } from 'react-native';
import * as ImagePicker from 'expo-image-picker';
import { useState } from 'react';
import Button from '@/components/Button';
import ImageViewer from '@/components/ImageViewer';
import IconButton from '@/components/IconButton';
import CircleButton from '@/components/CircleButton';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  const [selectedImage, setSelectedImage] = useState<string | undefined>(undefined);
  const [showAppOptions, setShowAppOptions] = useState<boolean>(false);
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      setSelectedImage(result.assets[0].uri);
      setShowAppOptions(true);
    } else {
      alert('You did not select any image.');
    }
  };
  const onReset = () => {
    setShowAppOptions(false);
  };
  const onAddSticker = () => {
    // 我们稍后将实现这一点
  };
  const onSaveImageAsync = async () => {
    // 我们稍后将实现这一点
  };
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} selectedImage={selectedImage} />
      </View>
      {showAppOptions ? (
        <View style={styles.optionsContainer}>
          <View style={styles.optionsRow}>
            <IconButton icon="refresh" label="Reset" onPress={onReset} />
            <CircleButton onPress={onAddSticker} />
            <IconButton icon="save-alt" label="Save" onPress={onSaveImageAsync} />
          </View>
        </View>
      ) : (
        <View style={styles.footerContainer}>
          <Button theme="primary" label="Choose a photo" onPress={pickImageAsync} />
          <Button label="Use this photo" onPress={() => setShowAppOptions(true)} />
        </View>
      )}
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
  optionsContainer: {
    position: 'absolute',
    bottom: 80,
  },
  optionsRow: {
    alignItems: 'center',
    flexDirection: 'row',
  },
});
```
让我们看看我们的应用程序在 Android、iOS 和网络上的表现：
Step 3: 
## 创建表情符号选择器模态框
模态框允许用户从可用表情符号列表中选择一个表情符号。在 **components** 目录中创建一个 **EmojiPicker.tsx** 文件。这个组件接受三个属性：
- `isVisible`: 一个布尔值，用于确定模态框的可见状态。
- `onClose`: 关闭模态框的函数。
- `children`: 稍后用于显示表情符号列表。
```tsx components/EmojiPicker.tsx|collapseHeight=430
import { Modal, View, Text, Pressable, StyleSheet } from 'react-native';
import { PropsWithChildren } from 'react';
import MaterialIcons from '@expo/vector-icons/MaterialIcons';
type Props = PropsWithChildren<{
  isVisible: boolean;
  onClose: () => void;
}>;
export default function EmojiPicker({ isVisible, children, onClose }: Props) {
  return (
    <View>
    <Modal animationType="slide" transparent={true} visible={isVisible}>
      <View style={styles.modalContent}>
        <View style={styles.titleContainer}>
          <Text style={styles.title}>Choose a sticker</Text>
          <Pressable onPress={onClose}>
            <MaterialIcons name="close" color="#fff" size={22} />
          </Pressable>
        </View>
        {children}
      </View>
    </Modal>
    </View>
  );
}
const styles = StyleSheet.create({
  modalContent: {
    height: '25%',
    width: '100%',
    backgroundColor: '#25292e',
    borderTopRightRadius: 18,
    borderTopLeftRadius: 18,
    position: 'absolute',
    bottom: 0,
  },
  titleContainer: {
    height: '16%',
    backgroundColor: '#464C55',
    borderTopRightRadius: 10,
    borderTopLeftRadius: 10,
    paddingHorizontal: 20,
    flexDirection: 'row',
    alignItems: 'center',
    justifyContent: 'space-between',
  },
  title: {
    color: '#fff',
    fontSize: 16,
  },
});
```
让我们了解上述代码的作用：
- `<Modal>` 组件显示一个标题和一个关闭按钮。
- 它的 `visible` 属性取 `isVisible` 的值，并控制模态框是打开还是关闭。
- 它的 `transparent` 属性是一个布尔值，用于确定模态框是否填充整个视图。
- 它的 `animationType` 属性确定它如何进入和离开屏幕。在这种情况下，它是从屏幕底部滑动。
- 最后，当用户按下关闭的 `<Pressable>` 时，`<EmojiPicker>` 调用 `onClose` 属性。
现在，让我们修改 **app/(tabs)/index.tsx**：
1. 导入 `<EmojiPicker>` 组件。
2. 创建一个 `isModalVisible` 状态变量，使用 `useState` 钩子，其默认值为 `false`，在用户按下按钮以打开它之前隐藏模态框。
3. 在 `onAddSticker()` 函数中替换备注，更新 `isModalVisible` 变量为 `true`，当用户按下按钮时。这将打开表情符号选择器。
4. 创建 `onModalClose()` 函数以更新 `isModalVisible` 状态变量。
5. 将 `<EmojiPicker>` 组件放置在 `Index` 组件的底部。
```tsx app/(tabs)/index.tsx
import { View, StyleSheet } from 'react-native';
import * as ImagePicker from 'expo-image-picker';
import { useState } from 'react';
import Button from '@/components/Button';
import ImageViewer from '@/components/ImageViewer';
import IconButton from '@/components/IconButton';
import CircleButton from '@/components/CircleButton';
import EmojiPicker from '@/components/EmojiPicker';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  const [selectedImage, setSelectedImage] = useState<string | undefined>(undefined);
  const [showAppOptions, setShowAppOptions] = useState<boolean>(false);
  const [isModalVisible, setIsModalVisible] = useState<boolean>(false);
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      setSelectedImage(result.assets[0].uri);
      setShowAppOptions(true);
    } else {
      alert('You did not select any image.');
    }
  };
  const onReset = () => {
    setShowAppOptions(false);
  };
  const onAddSticker = () => {
    setIsModalVisible(true);
  };
  const onModalClose = () => {
    setIsModalVisible(false);
  };
  const onSaveImageAsync = async () => {
    // 我们稍后将实现这一点
  };
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} selectedImage={selectedImage} />
      </View>
      {showAppOptions ? (
        <View style={styles.optionsContainer}>
          <View style={styles.optionsRow}>
            <IconButton icon="refresh" label="Reset" onPress={onReset} />
            <CircleButton onPress={onAddSticker} />
            <IconButton icon="save-alt" label="Save" onPress={onSaveImageAsync} />
          </View>
        </View>
      ) : (
        <View style={styles.footerContainer}>
          <Button theme="primary" label="Choose a photo" onPress={pickImageAsync} />
          <Button label="Use this photo" onPress={() => setShowAppOptions(true)} />
        </View>
      )}
      <EmojiPicker isVisible={isModalVisible} onClose={onModalClose}>
        {/* Emoji list component will go here */}
      </EmojiPicker>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
  optionsContainer: {
    position: 'absolute',
    bottom: 80,
  },
  optionsRow: {
    alignItems: 'center',
    flexDirection: 'row',
  },
});
```
这是此步骤后的结果：
Step 4: 
## 显示表情符号列表
让我们在模态框的内容中添加一个水平的表情符号列表。我们将使用 [`<FlatList>`](https://reactnative.dev/docs/flatlist) 组件来实现它。
在 **components** 目录中创建一个 **EmojiList.tsx** 文件，并添加以下代码：
```tsx components/EmojiList.tsx
import { useState } from 'react';
import { ImageSourcePropType, StyleSheet, FlatList, Platform, Pressable } from 'react-native';
import { Image } from 'expo-image';
type Props = {
  onSelect: (image: ImageSourcePropType) => void;
  onCloseModal: () => void;
};
export default function EmojiList({ onSelect, onCloseModal }: Props) {
  const [emoji] = useState<ImageSourcePropType[]>([
    require("../assets/images/emoji1.png"),
    require("../assets/images/emoji2.png"),
    require("../assets/images/emoji3.png"),
    require("../assets/images/emoji4.png"),
    require("../assets/images/emoji5.png"),
    require("../assets/images/emoji6.png"),
  ]);
  return (
    <FlatList
      horizontal
      showsHorizontalScrollIndicator={Platform.OS === 'web'}
      data={emoji}
      contentContainerStyle={styles.listContainer}
      renderItem={({ item, index }) => (
        <Pressable
          onPress={() => {
            onSelect(item);
            onCloseModal();
          }}>
          <Image source={item} key={index} style={styles.image} />
        </Pressable>
      )}
    />
  );
}
const styles = StyleSheet.create({
  listContainer: {
    borderTopRightRadius: 10,
    borderTopLeftRadius: 10,
    paddingHorizontal: 20,
    flexDirection: 'row',
    alignItems: 'center',
    justifyContent: 'space-between',
  },
  image: {
    width: 100,
    height: 100,
    marginRight: 20,
  },
});
```
让我们了解上述代码的作用：
- 上述 `<FlatList>` 组件使用 `Image` 组件渲染所有表情符号图像，并包裹在一个 `<Pressable>` 中。稍后，我们将改进它，以便用户可以点击屏幕上的表情符号，使其作为贴纸出现在图像上。
- 它还使用 `emoji` 数组变量提供的项数组作为 `data` 属性的值。`renderItem` 属性从 `data` 中获取项，并返回列表中的项。最后，我们添加 `Image` 和 `<Pressable>` 组件以显示此项。
- `horizontal` 属性使列表水平渲染，而不是垂直渲染。`showsHorizontalScrollIndicator` 使用 React Native 的 `Platform` 模块检查值并在网络上显示水平滚动条。
现在，更新 **app/(tabs)/index.tsx** 以导入 `<EmojiList>` 组件，并用以下代码片段替换 `<EmojiPicker>` 组件内的注释：
```tsx app/(tabs)/index.tsx|collapseHeight=440
import { ImageSourcePropType, View, StyleSheet } from 'react-native';
import * as ImagePicker from 'expo-image-picker';
import { useState } from 'react';
import Button from '@/components/Button';
import ImageViewer from '@/components/ImageViewer';
import IconButton from '@/components/IconButton';
import CircleButton from '@/components/CircleButton';
import EmojiPicker from '@/components/EmojiPicker';
import EmojiList from '@/components/EmojiList';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  const [selectedImage, setSelectedImage] = useState<string | undefined>(undefined);
  const [showAppOptions, setShowAppOptions] = useState<boolean>(false);
  const [isModalVisible, setIsModalVisible] = useState<boolean>(false);
  const [pickedEmoji, setPickedEmoji] = useState<ImageSourcePropType | undefined>(undefined);
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      setSelectedImage(result.assets[0].uri);
      setShowAppOptions(true);
    } else {
      alert('You did not select any image.');
    }
  };
  const onReset = () => {
    setShowAppOptions(false);
  };
  const onAddSticker = () => {
    setIsModalVisible(true);
  };
  const onModalClose = () => {
    setIsModalVisible(false);
  };
  const onSaveImageAsync = async () => {
    // 我们稍后将实现这一点
  };
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} selectedImage={selectedImage} />
      </View>
      {showAppOptions ? (
        <View style={styles.optionsContainer}>
          <View style={styles.optionsRow}>
            <IconButton icon="refresh" label="Reset" onPress={onReset} />
            <CircleButton onPress={onAddSticker} />
            <IconButton icon="save-alt" label="Save" onPress={onSaveImageAsync} />
          </View>
        </View>
      ) : (
        <View style={styles.footerContainer}>
          <Button theme="primary" label="Choose a photo" onPress={pickImageAsync} />
          <Button label="Use this photo" onPress={() => setShowAppOptions(true)} />
        </View>
      )}
      <EmojiPicker isVisible={isModalVisible} onClose={onModalClose}>
        <EmojiList onSelect={setPickedEmoji} onCloseModal={onModalClose} />
      </EmojiPicker>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
  optionsContainer: {
    position: 'absolute',
    bottom: 80,
  },
  optionsRow: {
    alignItems: 'center',
    flexDirection: 'row',
  },
});
```
在 `EmojiList` 组件中，`onSelect` 属性选择表情符号，选择后，`onCloseModal` 关闭模态框。
让我们看看我们的应用程序在 Android、iOS 和网络上的表现：
Step 5: 
## 显示选定的表情符号
现在，我们将表情符号贴纸放置在图像上。在 **components** 目录中创建一个新文件，并调用它 **EmojiSticker.tsx**。然后，添加以下代码：
```tsx components/EmojiSticker.tsx|collapseHeight=300
import { ImageSourcePropType, View } from 'react-native';
import { Image } from 'expo-image';
type Props = {
  imageSize: number;
  stickerSource: ImageSourcePropType;
};
export default function EmojiSticker({ imageSize, stickerSource }: Props) {
  return (
    <View style={{ top: -350 }}>
      <Image source={stickerSource} style={{ width: imageSize, height: imageSize }} />
    </View>
  );
}
```
此组件接收两个属性：
- `imageSize`: 在 `Index` 组件内部定义的值。我们将在下一章中使用该值当用户点击时缩放图像大小。
- `stickerSource`: 选定表情符号图像的源。
在 **app/(tabs)/index.tsx** 文件中导入该组件，并更新 `Index` 组件以在图像上显示表情符号贴纸。我们将检查 `pickedEmoji` 状态是否不为 `undefined`：
```tsx app/(tabs)/index.tsx
import { ImageSourcePropType, View, StyleSheet } from 'react-native';
import * as ImagePicker from 'expo-image-picker';
import { useState } from 'react';
import Button from '@/components/Button';
import ImageViewer from '@/components/ImageViewer';
import IconButton from '@/components/IconButton';
import CircleButton from '@/components/CircleButton';
import EmojiPicker from '@/components/EmojiPicker';
import EmojiList from '@/components/EmojiList';
import EmojiSticker from '@/components/EmojiSticker';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  const [selectedImage, setSelectedImage] = useState<string | undefined>(undefined);
  const [showAppOptions, setShowAppOptions] = useState<boolean>(false);
  const [isModalVisible, setIsModalVisible] = useState<boolean>(false);
  const [pickedEmoji, setPickedEmoji] = useState<ImageSourcePropType | undefined>(undefined);
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      setSelectedImage(result.assets[0].uri);
      setShowAppOptions(true);
    } else {
      alert('You did not select any image.');
    }
  };
  const onReset = () => {
    setShowAppOptions(false);
  };
  const onAddSticker = () => {
    setIsModalVisible(true);
  };
  const onModalClose = () => {
    setIsModalVisible(false);
  };
  const onSaveImageAsync = async () => {
    // 我们稍后将实现这一点
  };
  return (
    <View style={styles.container}>
      <View style={styles.imageContainer}>
        <ImageViewer imgSource={PlaceholderImage} selectedImage={selectedImage} />
        {pickedEmoji && <EmojiSticker imageSize={40} stickerSource={pickedEmoji} />}
      </View>
      {showAppOptions ? (
        <View style={styles.optionsContainer}>
          <View style={styles.optionsRow}>
            <IconButton icon="refresh" label="Reset" onPress={onReset} />
            <CircleButton onPress={onAddSticker} />
            <IconButton icon="save-alt" label="Save" onPress={onSaveImageAsync} />
          </View>
        </View>
      ) : (
        <View style={styles.footerContainer}>
          <Button theme="primary" label="Choose a photo" onPress={pickImageAsync} />
          <Button label="Use this photo" onPress={() => setShowAppOptions(true)} />
        </View>
      )}
      <EmojiPicker isVisible={isModalVisible} onClose={onModalClose}>
        <EmojiList onSelect={setPickedEmoji} onCloseModal={onModalClose} />
      </EmojiPicker>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
  optionsContainer: {
    position: 'absolute',
    bottom: 80,
  },
  optionsRow: {
    alignItems: 'center',
    flexDirection: 'row',
  },
});
```
让我们看看我们的应用程序在 Android、iOS 和网络上的表现：
## 总结
<ProgressTracker
  currentChapterIndex={4}
  name="GET_STARTED"
  summary="我们成功创建了表情符号选择器模态框，并实现了选择表情符号和在图像上显示它的逻辑。"
  nextChapterDescription="在下一章中，添加用户与手势的交互，以拖动表情符号并通过点击缩放其大小。"
  nextChapterTitle="添加手势"
  nextChapterLink="/tutorial/gestures"
/>


## 添加手势

在本教程中，学习如何实现来自 React Native Gesture Handler 和 Reanimated 库的手势。

手势是为应用程序提供直观用户体验的绝佳方式。[React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/) 库提供内置的原生组件，可处理手势。它使用平台的原生触摸处理系统识别平移、轻拍、旋转和其他手势。在本章中，我们将使用此库添加两种不同的手势：
- 双击放大表情符号贴纸的大小，再次双击时减小比例。
- 拖动以在屏幕上移动表情符号贴纸，以便用户可以将贴纸放置在图像的任意位置。
我们还将使用 [Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/handling-gestures/) 库在手势状态之间进行动画。
Video Tutorial: [观看：为您的通用 Expo 应用添加手势](https://www.youtube.com/watch?v=0q48LLvTGDU)
---
Step 1: 
## 添加 GestureHandlerRootView
为了让手势交互在应用中工作，我们将在 `Index` 组件的顶部渲染来自 `react-native-gesture-handler` 的 `<GestureHandlerRootView>`。用 `<GestureHandlerRootView>` 替换 **app/(tabs)/index.tsx** 中根级的 `<View>` 组件。
```tsx app/(tabs)/index.tsx
// ... 其余的导入语句保持不变
export default function Index() {
  return (
    <GestureHandlerRootView style={styles.container}>
      {/* ...其余的代码保持不变 */}
    </GestureHandlerRootView>
  )
}
```
Step 2: 
## 使用动画组件
`Animated` 组件查看组件的 `style` 属性，并确定哪些值需要动画以及应用更新以创建动画。Reanimated 导出动画组件，如 `<Animated.View>`、`<Animated.Text>` 或 `<Animated.ScrollView>`。我们将对 `<Animated.Image>` 组件应用动画，以使双击手势工作。
1. 打开 **components/EmojiSticker.tsx** 文件。在其中，导入 `Animated` 来自 `react-native-reanimated` 库以使用动画组件。
2. 用 `<Animated.Image>` 替换 `Image` 组件。
```tsx components/EmojiSticker.tsx
import { ImageSourcePropType, View } from 'react-native';
type Props = {
  imageSize: number;
  stickerSource: ImageSourcePropType;
};
export default function EmojiSticker({ imageSize, stickerSource }: Props) {
  return (
    <View style={{ top: -350 }}>
      <Animated.Image
        source={stickerSource}
        resizeMode="contain"
        style={{ width: imageSize, height: imageSize }}
      />
    </View>
  );
}
```
> 有关动画组件 API 的完整参考，参见 [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/core/createAnimatedComponent) 文档。
Step 3: 
## 添加轻拍手势
React Native Gesture Handler 允许我们在检测到触摸输入时添加行为，像双击事件。
在 **EmojiSticker.tsx** 文件中：
1. 从 `react-native-gesture-handler` 导入 `Gesture` 和 `GestureDetector`。
2. 为了识别贴纸上的轻拍，导入 `useAnimatedStyle`、`useSharedValue` 和 `withSpring` 来自 `react-native-reanimated`，以对 `<Animated.Image>` 的样式进行动画处理。
3. 在 `EmojiSticker` 组件内部，使用 `useSharedValue()` 钩子创建一个名为 `scaleImage` 的引用。它的初始值将为 `imageSize`。
```tsx components/EmojiSticker.tsx
// ...其余的导入语句保持不变
import { Gesture, GestureDetector } from 'react-native-gesture-handler';
import Animated, { useAnimatedStyle, useSharedValue, withSpring } from 'react-native-reanimated';
export default function EmojiSticker({ imageSize, stickerSource }: Props) {
  const scaleImage = useSharedValue(imageSize);
  return (
    // ...其余的代码保持不变
  )
}
```
使用 `useSharedValue()` 钩子创建共享值有很多优点。它有助于更改数据，并根据当前值运行动画。我们可以使用 `.value` 属性访问和修改共享值。我们将创建一个 `doubleTap` 对象来缩放初始值，并使用 `Gesture.Tap()` 在缩放贴纸图像时进行动画过渡。为了确定所需的点击次数，我们将添加 `numberOfTaps()`。
在 `EmojiSticker` 组件中创建以下对象：
```tsx components/EmojiSticker.tsx
const doubleTap = Gesture.Tap()
  .numberOfTaps(2)
  .onStart(() => {
    if (scaleImage.value !== imageSize * 2) {
      scaleImage.value = scaleImage.value * 2;
    } else {
      scaleImage.value = Math.round(scaleImage.value / 2);
    }
  });
```
为了使过渡动画化，让我们使用基于弹簧的动画。这将使它感觉更生动，因为它基于现实世界弹簧的物理特性。我们将使用 `react-native-reanimated` 提供的 `withSpring()` 函数。
在贴纸图像上，我们将使用 `useAnimatedStyle()` 钩子创建样式对象。当动画发生时，这将帮助我们使用共享值更新样式。我们还将通过操作 `width` 和 `height` 属性来缩放图像的大小。这些属性的初始值设为 `imageSize`。
创建一个 `imageStyle` 变量并将其添加到 `EmojiSticker` 组件：
```tsx components/EmojiSticker.tsx
const imageStyle = useAnimatedStyle(() => {
  return {
    width: withSpring(scaleImage.value),
    height: withSpring(scaleImage.value),
  };
});
```
接下来，用 `<GestureDetector>` 包裹 `<Animated.Image>` 组件，并在 `<Animated.Image>` 上修改 `style` 属性以传递 `imageStyle`。
```tsx components/EmojiSticker.tsx
import { ImageSourcePropType, View } from 'react-native';
import { Gesture, GestureDetector } from 'react-native-gesture-handler';
import Animated, { useAnimatedStyle, useSharedValue, withSpring } from 'react-native-reanimated';
type Props = {
  imageSize: number;
  stickerSource: ImageSourcePropType;
};
export default function EmojiSticker({ imageSize, stickerSource }: Props) {
  const scaleImage = useSharedValue(imageSize);
  const doubleTap = Gesture.Tap()
    .numberOfTaps(2)
    .onStart(() => {
      if (scaleImage.value !== imageSize * 2) {
        scaleImage.value = scaleImage.value * 2;
      } else {
        scaleImage.value = Math.round(scaleImage.value / 2);
      }
    });
  const imageStyle = useAnimatedStyle(() => {
    return {
      width: withSpring(scaleImage.value),
      height: withSpring(scaleImage.value),
    };
  });
  return (
    <View style={{ top: -350 }}>
        <Animated.Image
          source={stickerSource}
          resizeMode="contain"
        />
      </GestureDetector>
    </View>
  );
}
```
在上面的代码片段中，`gesture` 属性的值为 `doubleTap`，以便在用户双击贴纸图像时触发手势。
让我们在 Android、iOS 和网页上查看我们的应用：
> 有关轻拍手势 API 的完整参考，请参见 [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture) 文档。
Step 4: 
## 添加拖动手势
为了识别贴纸上的拖动手势并跟踪其移动，我们将使用拖动手势。在 **components/EmojiSticker.tsx** 中：
1. 创建两个新的共享值：`translateX` 和 `translateY`。
2. 用 `<Animated.View>` 组件替换 `<View>`。
```tsx components/EmojiSticker.tsx
export default function EmojiSticker({ imageSize, stickerSource }: Props) {
  const scaleImage = useSharedValue(imageSize);
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);
  // ...其余的代码保持不变
  return (
      <GestureDetector gesture={doubleTap}>
        {/* ...其余的代码保持不变 */}
      </GestureDetector>
  );
}
```
让我们学习上述代码的作用：
- 定义的平移值将移动贴纸在屏幕上。由于贴纸沿两个轴移动，我们需要跟踪 X 和 Y 值。
- 在 `useSharedValue()` 钩子中，我们将两个平移变量的初始位置设置为 `0`。这是贴纸的初始位置和起始点。当手势开始时，此值设置贴纸的初始位置。
在上一步中，我们触发了与 `Gesture.Tap()` 方法链的轻拍手势的 `onStart()` 回调。对于拖动手势，请指定一个 `onChange()` 回调，它在手势处于活动状态并移动时运行。
1. 创建一个 `drag` 对象来处理拖动手势。`onChange()` 回调接受 `event` 作为参数。`changeX` 和 `changeY` 属性保存自上一个事件以来位置的变化，并更新存储在 `translateX` 和 `translateY` 中的值。
2. 使用 `useAnimatedStyle()` 钩子定义 `containerStyle` 对象。它将返回一个包含变换的数组。对于 `<Animated.View>` 组件，我们需要将 `transform` 属性设置为 `translateX` 和 `translateY` 值。这将改变贴纸的位置，当手势处于活动状态。
```tsx components/EmojiSticker.tsx
const drag = Gesture.Pan().onChange(event => {
  translateX.value += event.changeX;
  translateY.value += event.changeY;
});
const containerStyle = useAnimatedStyle(() => {
  return {
    transform: [
      {
        translateX: translateX.value,
      },
      {
        translateY: translateY.value,
      },
    ],
  };
});
```
接下来，在 JSX 代码内部：
1. 更新 `<EmojiSticker>` 组件，使 `<GestureDetector>` 组件成为顶级组件。
2. 将 `containerStyle` 添加到 `<Animated.View>` 组件的样式中，以应用变换样式。
```tsx components/EmojiSticker.tsx
import { Gesture, GestureDetector } from 'react-native-gesture-handler';
import Animated, { useAnimatedStyle, useSharedValue, withSpring } from 'react-native-reanimated';
import { ImageSourcePropType } from 'react-native';
type Props = {
  imageSize: number;
  stickerSource: ImageSourcePropType;
};
export default function EmojiSticker({ imageSize, stickerSource }: Props) {
  const scaleImage = useSharedValue(imageSize);
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);
  const doubleTap = Gesture.Tap()
    .numberOfTaps(2)
    .onStart(() => {
      if (scaleImage.value !== imageSize * 2) {
        scaleImage.value = scaleImage.value * 2;
      } else {
        scaleImage.value = Math.round(scaleImage.value / 2);
      }
    });
  const imageStyle = useAnimatedStyle(() => {
    return {
      width: withSpring(scaleImage.value),
      height: withSpring(scaleImage.value),
    };
  });
  const drag = Gesture.Pan().onChange(event => {
    translateX.value += event.changeX;
    translateY.value += event.changeY;
  });
  const containerStyle = useAnimatedStyle(() => {
    return {
      transform: [
        {
          translateX: translateX.value,
        },
        {
          translateY: translateY.value,
        },
      ],
    };
  });
  return (
        <GestureDetector gesture={doubleTap}>
          <Animated.Image
            source={stickerSource}
            resizeMode="contain"
            style={[imageStyle, { width: imageSize, height: imageSize }]}
          />
        </GestureDetector>
      </Animated.View>
  );
}
```
让我们在 Android、iOS 和网页上查看我们的应用：
## 总结
<ProgressTracker
  currentChapterIndex={5}
  name="GET_STARTED"
  summary="我们成功实现了平移和轻拍手势。"
  nextChapterDescription="在下一章中，我们将学习如何截取图像和贴纸的屏幕快照，并将其保存到设备的库中。"
  nextChapterTitle="截取屏幕快照"
  nextChapterLink="/tutorial/screenshot"
/>


## 拍摄屏幕截图

在本教程中，学习如何使用第三方库和 Expo 媒体库来捕获屏幕截图。

在本章中，我们将学习如何使用第三方库拍摄屏幕截图并将其保存在设备的媒体库中。我们将使用 [`react-native-view-shot`](https://github.com/gre/react-native-view-shot) 来拍摄屏幕截图，并使用 [`expo-media-library`](/versions/latest/sdk/media-library/) 将图像保存在设备的媒体库中。
> **info** 到目前为止，我们已经使用了第三方库，如 `react-native-gesture-handler`，`react-native-reanimated`。我们可以根据用例在 [React Native Directory](https://reactnative.directory/) 找到数百个其他第三方库。
Video Tutorial: [观看：在你的通用 Expo 应用中拍摄屏幕截图](https://www.youtube.com/watch?v=Jft3_Yfr-p4)
---
Step 1: 
## 安装库
要安装 `react-native-view-shot` 和 `expo-media-library`，请运行以下命令：
```sh
$ npx expo install react-native-view-shot expo-media-library
```
Step 2: 
## 请求权限
需要敏感信息的应用程序，如访问设备的媒体库，必须提示用户授权以允许或拒绝访问。使用来自 `expo-media-library` 的 `usePermissions()` 钩子，我们可以使用权限 `permissionResponse` 和 `requestPermission()` 方法请求访问权限。
当应用第一次加载且权限状态既未授予也未拒绝时，`permissionResponse` 的值为 `null`。当请求权限时，用户可以选择授予或拒绝权限。我们可以添加一个条件来检查是否未授予。如果未授予，则触发 `requestPermission()` 方法。在获得访问权限后，`permissionResponse` 的值更改为 `granted`。
在 **app/(tabs)/index.tsx** 中添加以下代码片段：
```tsx app/(tabs)/index.tsx
// ...其余代码保持不变
export default function Index() {
  // ...其余代码保持不变
  useEffect(() => {
    if (!permissionResponse?.granted) {
      requestPermission();
    }
  }, []);
  // ...其余代码保持不变
}
```
Step 3: 
## 创建引用以保存当前视图
我们将使用 `react-native-view-shot` 允许用户在应用中拍摄屏幕截图。此库使用 `captureRef()` 方法捕获 `<View>` 的屏幕截图作为图像。它返回捕获的屏幕截图图像文件的 URI。
1. 从 `react-native-view-shot` 导入 `captureRef` 和从 React 导入 `useRef`。
2. 创建一个 `imageRef` 引用变量来存储所捕获屏幕截图的引用。
3. 将 `<ImageViewer>` 和 `<EmojiSticker>` 组件包裹在一个 `<View>` 中，然后将引用变量传递给它。
```tsx app/(tabs)/index.tsx|collapseHeight=440
export default function Index() {
  // ...其余代码保持不变
  return (
    <GestureHandlerRootView style={styles.container}>
      <View style={styles.imageContainer}>
          <ImageViewer imgSource={PlaceholderImage} selectedImage={selectedImage} />
          {pickedEmoji && <EmojiSticker imageSize={40} stickerSource={pickedEmoji} />}
      </View>
      {/* ...其余代码保持不变 */}
    </GestureHandlerRootView>
  );
}
```
在上面的代码片段中，`collapsable` 属性设置为 `false`。这允许 `<View>` 组件仅捕获背景图像和表情贴纸的屏幕截图。
Step 4: 
## 捕获屏幕截图并保存
我们可以通过在 `onSaveImageAsync()` 函数中调用来自 `react-native-view-shot` 的 `captureRef()` 方法来捕获视图的屏幕截图。它接受一个可选参数，我们可以在其中传递捕获区域的 `width` 和 `height`。我们可以在 [库的文档](https://github.com/gre/react-native-view-shot#capturerefview-options-lower-level-imperative-api) 中阅读更多可用选项。
`captureRef()` 方法还返回一个承诺，承诺以屏幕截图的 URI 兑现。我们将这个 URI 作为参数传递给 [`MediaLibrary.saveToLibraryAsync()`](/versions/latest/sdk/media-library/#medialibrarysavetolibraryasynclocaluri)，并将屏幕截图保存到设备的媒体库中。
在 **app/(tabs)/index.tsx** 中，用以下代码更新 `onSaveImageAsync()` 函数：
```tsx app/(tabs)/index.tsx|collapseHeight=440
import * as ImagePicker from 'expo-image-picker';
import * as MediaLibrary from 'expo-media-library';
import { useEffect, useRef, useState } from 'react';
import { ImageSourcePropType, StyleSheet, View } from 'react-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { captureRef } from 'react-native-view-shot';
import Button from '@/components/Button';
import CircleButton from '@/components/CircleButton';
import EmojiList from '@/components/EmojiList';
import EmojiPicker from '@/components/EmojiPicker';
import IconButton from '@/components/IconButton';
import ImageViewer from '@/components/ImageViewer';
import EmojiSticker from '@/components/EmojiSticker';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  const [selectedImage, setSelectedImage] = useState<string | undefined>(
    undefined
  );
  const [showAppOptions, setShowAppOptions] = useState<boolean>(false);
  const [isModalVisible, setIsModalVisible] = useState<boolean>(false);
  const [pickedEmoji, setPickedEmoji] = useState<
    ImageSourcePropType | undefined
  >(undefined);
  const [permissionResponse, requestPermission] = MediaLibrary.usePermissions();
  const imageRef = useRef<View>(null);
  useEffect(() => {
    if (!permissionResponse?.granted) {
      requestPermission();
    }
  }, []);
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      setSelectedImage(result.assets[0].uri);
      setShowAppOptions(true);
    } else {
      alert('You did not select any image.');
    }
  };
  const onReset = () => {
    setShowAppOptions(false);
  };
  const onAddSticker = () => {
    setIsModalVisible(true);
  };
  const onModalClose = () => {
    setIsModalVisible(false);
  };
  const onSaveImageAsync = async () => {
    try {
      const localUri = await captureRef(imageRef, {
        height: 440,
        quality: 1,
      });
      await MediaLibrary.saveToLibraryAsync(localUri);
      if (localUri) {
        alert('Saved!');
      }
    } catch (e) {
      console.log(e);
    }
  };
  return (
    <GestureHandlerRootView style={styles.container}>
      <View style={styles.imageContainer}>
        <View ref={imageRef} collapsable={false}>
          <ImageViewer imgSource={PlaceholderImage} selectedImage={selectedImage} />
          {pickedEmoji && <EmojiSticker imageSize={40} stickerSource={pickedEmoji} />}
        </View>
      </View>
      {showAppOptions ? (
        <View style={styles.optionsContainer}>
          <View style={styles.optionsRow}>
            <IconButton icon="refresh" label="Reset" onPress={onReset} />
            <CircleButton onPress={onAddSticker} />
            <IconButton icon="save-alt" label="Save" onPress={onSaveImageAsync} />
          </View>
        </View>
      ) : (
        <View style={styles.footerContainer}>
          <Button theme="primary" label="Choose a photo" onPress={pickImageAsync} />
          <Button label="Use this photo" onPress={() => setShowAppOptions(true)} />
        </View>
      )}
      <EmojiPicker isVisible={isModalVisible} onClose={onModalClose}>
        <EmojiList onSelect={setPickedEmoji} onCloseModal={onModalClose} />
      </EmojiPicker>
    </GestureHandlerRootView>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
  optionsContainer: {
    position: 'absolute',
    bottom: 80,
  },
  optionsRow: {
    alignItems: 'center',
    flexDirection: 'row',
  },
});
```
现在，选择一张照片并在应用中添加一个贴纸。然后点击“保存”按钮。我们应该在 Android 和 iOS 上看到以下结果：
## 摘要
<ProgressTracker
  currentChapterIndex={6}
  name="GET_STARTED"
  summary={
    <>
        我们成功使用  和  捕获了
        屏幕截图并将其保存到设备的库中。
    </>
}
nextChapterDescription="在下一章中，让我们学习如何处理移动平台和网页之间的差异，以在网页上实现相同功能。"
nextChapterTitle="处理平台差异"
nextChapterLink="/tutorial/platform-differences"
/>


## 处理平台差异

在本教程中，学习在创建通用应用时如何处理本地和网页之间的平台差异。

Android、iOS 和网页具有不同的功能。在我们的案例中，Android 和 iOS 都可以使用`react-native-view-shot`库捕获屏幕截图。然而，网页浏览器不可以。
在本章中，我们将学习如何处理网页浏览器的截图，以便我们的应用在所有平台上都有相同的功能。
Video Tutorial: [观看：在您的通用Expo应用中处理平台差异](https://www.youtube.com/watch?v=mEKQvF4irBM)
---
Step 1: 
## 安装并导入 dom-to-image
要在网页上捕获屏幕截图并将其保存为图像，我们将使用一个名为 [`dom-to-image`](https://github.com/tsayen/dom-to-image#readme) 的第三方库。它可以捕获任何 DOM 节点的屏幕截图并将其转换为矢量（SVG）或光栅（PNG 或 JPEG）图像。
停止开发服务器并运行以下命令以安装该库：
```sh
$ npm install dom-to-image
```
安装后，确保重启开发服务器，并在终端中按 <kbd>w</kbd>。
Step 2: 
## 添加平台特定代码
使用 React Native 的 `Platform` 模块，我们可以实现平台特定的行为。在 **app/(tabs)/index.tsx** 中：
1. 从 `react-native` 导入 `Platform` 模块。
2. 从 `dom-to-image` 导入 `domtoimage` 库。
3. 更新 `onSaveImageAsync()` 函数，以使用 `Platform.OS` 属性检查当前平台是否为 `'web'`。如果是 `'web'`，我们将使用 `domtoimage.toJpeg()` 方法将当前的 `<View>` 转换并捕获为 JPEG 图像。否则，我们将继续使用为本地平台添加的相同逻辑。
```tsx app/(tabs)/index.tsx
import * as ImagePicker from 'expo-image-picker';
import * as MediaLibrary from 'expo-media-library';
import { useEffect, useRef, useState } from 'react';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { captureRef } from 'react-native-view-shot';
import Button from '@/components/Button';
import ImageViewer from '@/components/ImageViewer';
import IconButton from '@/components/IconButton';
import CircleButton from '@/components/CircleButton';
import EmojiPicker from '@/components/EmojiPicker';
import EmojiList from '@/components/EmojiList';
import EmojiSticker from '@/components/EmojiSticker';
const PlaceholderImage = require('@/assets/images/background-image.png');
export default function Index() {
  const [selectedImage, setSelectedImage] = useState<string | undefined>(undefined);
  const [showAppOptions, setShowAppOptions] = useState<boolean>(false);
  const [isModalVisible, setIsModalVisible] = useState<boolean>(false);
  const [pickedEmoji, setPickedEmoji] = useState<ImageSourcePropType | undefined>(undefined);
  const [permissionResponse, requestPermission] = MediaLibrary.usePermissions();
  const imageRef = useRef<View>(null);
  useEffect(() => {
    if (!permissionResponse?.granted) {
      requestPermission();
    }
  }, []);
  const pickImageAsync = async () => {
    let result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });
    if (!result.canceled) {
      setSelectedImage(result.assets[0].uri);
      setShowAppOptions(true);
    } else {
      alert('You did not select any image.');
    }
  };
  const onReset = () => {
    setShowAppOptions(false);
  };
  const onAddSticker = () => {
    setIsModalVisible(true);
  };
  const onModalClose = () => {
    setIsModalVisible(false);
  };
  const onSaveImageAsync = async () => {
    if (Platform.OS !== 'web') {
      try {
        const localUri = await captureRef(imageRef, {
          height: 440,
          quality: 1,
        });
        await MediaLibrary.saveToLibraryAsync(localUri);
        if (localUri) {
          alert('Saved!');
        }
      } catch (e) {
        console.log(e);
      }
    } else {
      try {
        const dataUrl = await domtoimage.toJpeg(imageRef.current, {
          quality: 0.95,
          width: 320,
          height: 440,
        });
        let link = document.createElement('a');
        link.download = 'sticker-smash.jpeg';
        link.href = dataUrl;
        link.click();
      } catch (e) {
        console.log(e);
      }
    }
  };
  return (
    <GestureHandlerRootView style={styles.container}>
      <View style={styles.imageContainer}>
        <View ref={imageRef} collapsable={false}>
          <ImageViewer imgSource={PlaceholderImage} selectedImage={selectedImage} />
          {pickedEmoji && <EmojiSticker imageSize={40} stickerSource={pickedEmoji} />}
        </View>
      </View>
      {showAppOptions ? (
        <View style={styles.optionsContainer}>
          <View style={styles.optionsRow}>
            <IconButton icon="refresh" label="Reset" onPress={onReset} />
            <CircleButton onPress={onAddSticker} />
            <IconButton icon="save-alt" label="Save" onPress={onSaveImageAsync} />
          </View>
        </View>
      ) : (
        <View style={styles.footerContainer}>
          <Button theme="primary" label="Choose a photo" onPress={pickImageAsync} />
          <Button label="Use this photo" onPress={() => setShowAppOptions(true)} />
        </View>
      )}
      <EmojiPicker isVisible={isModalVisible} onClose={onModalClose}>
        <EmojiList onSelect={setPickedEmoji} onCloseModal={onModalClose} />
      </EmojiPicker>
    </GestureHandlerRootView>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#25292e',
    alignItems: 'center',
  },
  imageContainer: {
    flex: 1,
  },
  footerContainer: {
    flex: 1 / 3,
    alignItems: 'center',
  },
  optionsContainer: {
    position: 'absolute',
    bottom: 80,
  },
  optionsRow: {
    alignItems: 'center',
    flexDirection: 'row',
  },
});
```
Note: 修复  TypeScript 模块错误
---
我们需要在导入 `domtoimage` 库后添加一个类型定义，因为我们使用的是 TypeScript。我们可以通过在项目目录的根目录创建一个 **types.d.ts** 文件并添加声明语句来做到这一点：
```tsx types.d.ts
declare module 'dom-to-image';
```
---
在网页浏览器中运行应用时，我们现在可以保存屏幕截图：
## 总结
<ProgressTracker
  currentChapterIndex={7}
  name="GET_STARTED"
  summary="该应用程序完成了我们设定的所有目标，现在是时候将我们的注意力转向纯粹的美学了。"
  nextChapterDescription="在下一章中，我们将自定义应用的状态栏、启动画面和应用图标。"
  nextChapterTitle="配置状态栏、启动画面和应用图标"
  nextChapterLink="/tutorial/configuration"
/>


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

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

在本章中，我们将在将应用部署到应用商店之前，处理一些应用细节，例如主题状态栏、自定义应用图标和启动屏幕。
Video Tutorial: [观看：为您的通用 Expo 应用添加最后的修饰](https://www.youtube.com/watch?v=OgGCYdElcZo)
---
Step 1: 
## 配置状态栏
[`expo-status-bar`](/versions/latest/sdk/status-bar/) 库在使用 `create-expo-app` 创建的每个项目中都已预安装。该库提供了一个 `StatusBar` 组件来配置应用的状态栏样式。
在 **app/\_layout.tsx** 中：
1. 从 `expo-status-bar` 导入 `StatusBar`。
2. 将 `StatusBar` 和现有的 `Stack` 组件分组，使用 [React 的 Fragment 组件](https://react.dev/reference/react/Fragment)。
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
import { StatusBar } from 'expo-status-bar';
export default function RootLayout() {
  return (
    <>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      </Stack>
    </>
  );
}
```
现在让我们在 Android 和 iOS 上查看我们的应用：
Step 2: 
## 应用图标
在项目中，**assets/images** 目录下有一个 **icon.png** 文件。这就是我们的应用图标。它是一个 1024px x 1024px 的图像，外观如下：
与启动屏幕图像一样，**app.json** 文件中的 `"icon"` 属性配置了应用图标的路径。默认情况下，新的 Expo 项目定义了正确的路径为 `"./assets/images/icon.png"`。我们不需要更改任何内容。
> 最终，当您为应用商店构建应用时，[Expo 应用服务 (EAS)](/eas/) 将获取此图像并为每个设备创建优化的图标。
您可以在 Expo Go 的各个地方看到图标。以下是 Expo Go 开发者菜单中显示的应用图标的示例：
Step 3: 
## 启动屏幕
启动屏幕在应用内容加载之前可见。它使用较小的图像，例如应用的图标，并使其居中。当应用的内容准备好显示时，它会隐藏。
[`expo-splash-screen`](/versions/latest/sdk/splash-screen/) 插件在使用 `create-expo-app` 创建的每个项目中都已预安装。该库提供了一个配置插件来配置启动屏幕。
在 **app.json** 中，`expo-splash-screen` 插件已配置为使用应用的图标作为启动屏幕图像（在 [可下载资产](/tutorial/create-your-first-app/#download-assets) 中提供），使用以下片段，因此我们不需要更改任何内容：
```json app.json
{
  "plugins": [
    [
      "expo-splash-screen",
      {
        "image": "./assets/images/splash-icon.png"
      }
    ]
  ]
}
```
但是，**要测试启动屏幕，我们不能使用 Expo Go 或 [开发构建](/develop/development-builds/introduction/)**。要测试它，我们需要创建应用的预览或生产构建。我们建议您查看以下资源，以了解有关启动屏幕配置和如何测试更多信息：
- [创建启动屏幕图标](/develop/user-interface/splash-screen-and-app-icon/#splash-screen) 指南，以了解如何配置启动屏幕图标。
- 要了解如何创建预览构建，请参见 EAS 教程中的 [内部分发](/tutorial/eas/internal-distribution-builds/) 指南，或要创建生产构建，请参见 [Android](/tutorial/eas/android-production-build/) 和 [iOS](/tutorial/eas/ios-production-build/) 的指南。
## 总结
<ProgressTracker
  currentChapterIndex={8}
  name="GET_STARTED"
  summary="干得好！我们构建了一个可以在 Android、iOS 和 Web 上运行的应用，使用相同的代码库。"
  nextChapterDescription="本教程的下一部分将引导您了解更多我们在这里讨论的概念及其他我们简要提到的概念的资源。"
  nextChapterTitle="学习资源"
  nextChapterLink="/tutorial/follow-up"
/>


## 学习资源

探索一个策划的资源列表，以了解 Expo 和 React Native。

现在示例应用完成了，让我们深入了解我们用来构建它的技术。
## 将你的项目构建成应用
要开始在你的机器上创建一个新应用，你可以使用 `npx create-expo-app@latest` 并按顺序 [设置你的开发环境](/get-started/set-up-your-environment/)。
### 推荐资源
创建新项目后，你可以了解更多不同的工具和概念，帮助你在应用开发旅程中：
- [开发工具](/develop/tools/): Expo 工具的参考，可以帮助你在应用构建旅程的各个方面。
- [开发构建](/develop/development-builds/introduction/): 使用开发构建可以让你完全控制应用的构建过程，并在设备或模拟器上测试你的应用。
- [开发概述](/workflow/overview/): 这是一个高层次概述，提供有关使用 Expo 开发应用的关键概念和核心开发循环的流程的详细信息。
- [Expo 路由](/router/introduction/): 我们了解了 Expo 路由的基础知识，并实现了一个标签导航器。请查看其文档以了解更多关于该库的信息。
- [应用图标](/develop/user-interface/splash-screen-and-app-icon/#app-icon)和 [启动屏幕](/develop/user-interface/splash-screen-and-app-icon/#splash-screen): 你可以了解更多关于自定义应用图标和启动屏幕的指南。此外，查看 [应用配置参考](/workflow/configuration) 以获取可以在 **app.json** 文件中配置的属性。
- [应用分发](/deploy/build-project/) 和 [提交](/deploy/submit-to-app-stores/) 到应用商店: 阅读这些资源，以了解如何在应用准备好发布后将其发布和提交到应用商店。
- [调试](/debugging/runtime-issues/): 有时事情会出错，当出错时，你可以使用调试工具来查找和修复错误。
## 学习
### React
我们使用了 React 组件和 API。对 React 有扎实的理解对于使用 Expo 构建应用是必不可少的。我们建议阅读 React 文档中的 [快速入门部分](https://react.dev/learn) 和 [Hooks 部分](https://react.dev/reference/react/hooks)。
### React Native
在开发教程应用时，我们广泛使用了 React Native。你可以从 [React Native 基础指南](https://reactnative.dev/docs/getting-started) 开始了解更多。此外，请查看以下文档：
- [视图 API 参考](https://reactnative.dev/docs/view)
- [文本 API 参考](https://reactnative.dev/docs/text)
- [平台特定代码](https://reactnative.dev/docs/platform-specific-code)
- [在列表中展示数据](https://reactnative.dev/docs/using-a-listview)
我们使用 Flexbox 布局我们的组件。查看以下推荐以了解更多关于它的信息：
- [高度和宽度](https://reactnative.dev/docs/height-and-width)
- [使用 Flexbox 布局](https://reactnative.dev/docs/flexbox)
### 手势和动画
要了解更多关于实现不同类型的手势和动画的信息，我们推荐以下文档：
- [React Native 手势处理](https://docs.swmansion.com/react-native-gesture-handler/docs/)
- [React Native 动画](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started)
## 加入社区
加入我们的社区，在 <A href="https://chat.expo.dev/" shouldLeakReferrer>Discord</A> 与其他 Expo 用户聊天或提问。


# EAS 教程

## EAS 教程：介绍

本教程介绍如何使用 Expo 应用服务 (EAS) 为 Android 和 iOS 构建应用程序，涵盖构建、更新和提交工作流程。

## 关于本教程
本教程将使您熟悉 [Expo 应用服务 (EAS)](https://expo.dev/eas) 的核心服务：[构建](/build/introduction/)、[提交](/submit/introduction/) 和 [更新](/eas-update/introduction/)。完成本教程后，您将了解如何为个人和团队项目设置专业的移动持续集成 (CI)/持续开发 (CD) 流水线。
本教程涵盖以下主题：
- 使用 EAS Build 创建和安装开发构建，然后在设备、模拟器或仿真器上运行。
- 体验使用开发构建而不是 Expo Go 的好处。
- 实现与团队或外部利益相关者共享开发构建的工作流程。
- 自动增加应用构建版本。
- 在一个设备上同时安装不同的应用变体，例如开发版和预览版。
- 利用 EAS Update 在开发阶段快速创建和部署更新。
- 通过与 GitHub 存储库集成来自动化构建过程。
这些主题将为我们有效使用 EAS 提供所需的基础，并在需要时接触更高级的主题。
## 前提条件
本教程是实践操作，设计为大约两小时内完成。您需要一个现有的 Expo 项目来跟随并在本地设置它。选项包括：
- 继续使用我们上一教程中的 Sticker Smash 应用。如果是新手，请从 [GitHub](https://github.com/expo/examples/tree/master/stickersmash) 下载。
- 使用 [`npx create-expo-app`](/get-started/create-a-project/) 创建一个新项目。
- 使用原生 React Native 项目。确保安装了 `expo` 包，您可以 [自动](/bare/installing-expo-modules/) 或 [手动](/bare/installing-expo-modules/#manual-installation) 安装。
## 工具
[Expo Orbit](https://expo.dev/orbit) 用于在 macOS 和 Windows 上一键管理和启动构建。
如果您想同时在本地机器上安装和运行构建，可以使用 Android 模拟器或 iOS 模拟器。要设置它们，请参见以下内容：
- [Android 模拟器](/workflow/android-studio-emulator/)
- [iOS 模拟器](/workflow/ios-simulator/)（仅适用于 macOS）
## 下一步
在本地设置 Expo 项目后，我们准备好开始这段旅程。在下一章中，让我们学习如何使用 EAS Build 创建您的第一次构建。


## 在云端配置开发构建

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

在本章中，我们将为我们的示例应用设置并配置 EAS 的开发构建。
Video Tutorial: [观看：如何配置开发构建](https://www.youtube.com/watch?v=uQCE9zl3dXU)
---
## 理解开发构建
让我们先了解什么是开发构建，以及为什么我们需要它们。
[开发构建](/develop/development-builds/introduction/) 是我们项目的调试版本。它已优化以便在创建应用时快速迭代。它包含 [`expo-dev-client`](/versions/latest/sdk/dev-client/) 库，提供了一个强大而完整的开发环境。该设置允许我们根据需要集成任何本地库或更改 [本地目录](/workflow/overview/#android-and-ios-native-projects) 内的代码。
### 关键亮点
> **注意：** 如果您熟悉 [Expo Go](/get-started/expo-go/)，可以将开发构建视为根据项目要求定制的 Expo Go 版本。
| 特性             | 开发构建                                                                                                | Expo Go                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **开发阶段**     | 为移动应用开发提供类似 Web 的快速迭代速度。                                                             | 允许通过客户端应用快速迭代和测试 Expo SDK 项目。           |
| **协作**         | 促进团队测试，具有共享的本地运行时。                                                                    | 通过设备二维码轻松共享项目。                               |
| **第三方库支持** | 完全支持任何 [第三方库](/workflow/using-libraries/#third-party-libraries)，包括需要自定义本地代码的库。 | 限于 Expo SDK 内的库，不适合自定义本地依赖项。             |
| **定制化**       | 通过 [配置插件](/config-plugins/introduction/) 进行广泛定制，并可直接访问本地代码。                     | 定制化有限，专注于 Expo SDK 能力，而无直接的本地代码修改。 |
| **预期用途**     | 适用于面向商店部署的完整应用开发，提供完整的开发环境和工具。                                            | 适合学习、原型设计和实验。不推荐用于生产应用。             |
Step 1: 
## 安装 expo-dev-client 库
要为开发构建初始化我们的项目，让我们在项目目录中 [`cd`](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line#basic_built-in_terminal_commands) 并运行以下命令来安装库：
```sh
$ npx expo install expo-dev-client
```
### 启动开发服务器
运行 `npx expo start` 来启动 [开发服务器](/get-started/start-developing/#start-a-development-server):
```sh
$ npx expo start
```
该命令启动 metro 打包器。在终端窗口中，我们看到二维码，后面跟着 `Metro waiting on...` 和一个清单 URL：
我们来注意安装 `expo-dev-client` 库的变化：
- 清单 URL 包含了 `expo-development-client` 以及应用程序方案
- 开发服务器现在针对开发构建（而不是 Expo Go）运行。
由于我们没有在其中一个设备或模拟器/仿真器上安装开发构建，因此我们还不能运行我们的项目。
Step 2: 
## 初始化开发构建
### 安装 EAS CLI
我们需要在本地机器上作为全局依赖项安装 EAS 命令行界面（CLI）工具。运行以下命令：
```sh
$ npm install -g eas-cli
```
### 登录或注册 Expo 账户
> 如果您有 Expo 账户并通过 Expo CLI 登录，请跳过此步骤。如果您没有 Expo 账户，请 [在这里注册](https://expo.dev/signup) 并继续执行下面的登录命令。
要登录，请运行以下命令：
```sh
$ eas login
```
该命令要求输入我们 Expo 账户的邮箱或用户名和密码以完成登录。
### 初始化并链接项目到 EAS
对于任何新项目，第一步是初始化并将其链接到 EAS 服务器。运行以下命令：
```sh
$ eas init
```
运行此命令时：
- 请求通过输入我们的 Expo 账户凭据验证账户所有者，并询问我们是否想要为 @your-username/sticker-smash 创建一个新 EAS 项目：
```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)
```
- 创建 EAS 项目，并提供我们可以在 EAS 仪表板中打开的项目链接：
- 生成唯一的 `projectId` 并将该 EAS 项目链接到我们开发机器上的示例应用。
- 修改 **app.json** 以包含 [`extra.eas.projectId`](/versions/latest/sdk/constants/#easconfig) 并用创建的唯一 ID 更新其值。
Note: 在 app.json 中  是什么？
---
当 `eas init` 运行时，它在 **app.json** 中的 `extra.eas.projectId` 下关联了一个唯一标识符。该属性的值用于识别我们在 EAS 服务器上的项目。
```json
{
  "extra": {
    "eas": {
      "projectId": "0cd3da2d-xxx-xxx-xxx-xxxxxxxxxx"
    }
  }
}
```
---
Step 3: 
## 为 EAS Build 配置项目
要为 EAS Build 设置我们的项目，运行以下命令：
```sh
$ eas build:configure
```
运行该命令时：
- 提示选择一个平台：**Android**，**iOS** 或 **全部**。由于我们正在创建 Android 和 iOS 应用，所以选择 **全部**。
- 在项目目录的根部创建 **eas.json**，并进行以下配置：
```json eas.json
{
  "cli": {
    "version": ">= 16.18.0",
    "appVersionSource": "remote"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {
      "autoIncrement": true
    }
  },
  "submit": {
    "production": {}
  }
}
```
这是新项目中 **eas.json** 的默认配置。它完成两个任务：
- 定义当前的 EAS CLI 版本。
- 添加三个 [构建配置文件](/build/eas-json/#build-profiles)：`development`、`preview` 和 `production`。
Note: 进一步探索开发配置文件
---
**eas.json** 是不同构建配置文件的集合。每个配置文件均具有独特的配置，以生成特定的构建类型。这些配置文件还可以包括 Android 或 iOS 的平台特定设置。
目前，我们的重点是 `development` 配置文件，其中包括以下配置：
- [`developmentClient`](/eas/json/#developmentclient)：启用 (`true`) 以创建调试构建。它使用 `expo-dev-client` 库加载应用，提供开发工具并生成用于设备或模拟器/仿真器安装的构建工件，并允许在本地开发中使用该应用，因为它支持即时更新 JavaScript。
- [`distribution`](/eas/json/#distribution)：配置为 `internal`，以表明我们希望内部共享构建（而不是将其上传到应用商店）。
---
> **注意**：构建提供广泛的自定义选项，包括平台特定设置，以及能够在不同的构建配置文件之间扩展配置。了解更多关于 [自定义构建配置文件](/build/eas-json/#build-profiles)。
## 总结
<ProgressTracker
  currentChapterIndex={0}
  name="EAS_TUTORIAL"
  summary="
我们成功地使用 EAS CLI 初始化并配置了我们的项目，将其链接到 EAS 服务器，并准备了一个开发构建。"
  nextChapterDescription="在下一章中，我们将为 Android 创建一个开发构建，在设备和模拟器上安装，并通过开发服务器运行它。"
  nextChapterTitle="为 Android 创建并运行云构建"
  nextChapterLink="/tutorial/eas/android-development-build/"
/>


## 创建并运行 Android 的云构建

学习如何使用 EAS Build 配置适用于 Android 设备和模拟器的开发构建。

在本章中，我们将创建一个可以在 Android 上运行的开发构建，使用 EAS Build。
在 Android 设备或模拟器上创建和运行构建的过程是相同的，唯一的区别是在开发构建的安装上。
Video Tutorial: [观看：如何创建并运行 Android 的云构建](https://www.youtube.com/watch?v=D612BUtvvl8)
---
## 为开发配置文件创建构建
对于 Android，开发构建必须是 **.apk** 格式。虽然默认的 Android 格式是 **.aab**，这对于 Google Play 商店分发是理想的，但不能安装在设备或模拟器上。
要创建 **.apk**：
- 在 **eas.json** 中，确保 `developmentClient` 在 `build.development` 配置下设置为 `true`。
- 然后，运行 `eas build` 命令，将 `android` 作为平台，将 `development` 作为构建配置：
  ```sh
$ eas build --platform android --profile development
```
  > **info** **提示**：下次运行 `eas build` 命令时，您还可以使用 `-p` 来指定平台。它是 `--platform` 的简写。
该命令提示我们以下问题：
- **您希望 Android 应用程序 ID 是什么？** 按 <kbd>return</kbd> 以选择此提示中提供的默认值。这将在 **app.json** 中添加 [`android.package`](/versions/latest/config/app/#package)。
- **生成新的 Android Keystore**？按 <kbd>Y</kbd>。
在回答后，构建将排队，我们可以通过 EAS CLI 提供的链接在 EAS 仪表板中跟踪其进度：
Note: 构建详细信息页面包含什么信息？
---
构建详细信息页面显示构建类型、配置文件、Expo SDK 版本、应用版本、版本代码、最后的提交哈希，以及发起构建的开发者或账户拥有者的身份。
---
Note: 什么是 Android 应用程序 ID？
---
在上面的图像中，**构建工件** 的当前状态显示构建正在进行中。完成后，此部分将提供下载构建的选项。**日志** 概述了在 EAS Build 上进行 Android 构建过程中的每一步。为了简洁起见，我们不在这里详细探索每一步。要了解更多，请参见 [Android 构建过程](/build-reference/android-builds/)。
也称为我们 Android 应用的包名，它以 DNS 反向表示法格式存储值（`com.owner.appname`）。此表示法的每个组件应以小写字母开头。
例如，我们的示例应用有 `com.owner.stickersmash`，其中 `com.owner` 是域名，`stickersmash` 是我们的应用名称。
---
## Android 设备
Step 1: 
### 安装开发构建
一旦构建完成，**构建工件** 部分会更新，指示构建已完成：
此部分提供在 Android 设备上运行开发构建的可用方法：Expo Orbit 和安装按钮。
[Expo Orbit](https://expo.dev/orbit) 允许在 Android 设备上无缝安装开发构建。要使用此方法：
- 使用 USB 将 Android 设备连接到本地计算机。
- 打开 Orbit 菜单栏应用。
- 在 Orbit 应用中选择 **设备**。
- 在 EAS 仪表板上，在 **构建工件** 下单击 **使用 Orbit 打开**。
构建安装后，Orbit 应用将在设备上启动开发构建。
Note: 备用：使用安装按钮和二维码
---
**安装** 按钮在 **构建工件** 中生成二维码进行安装：
- 单击 **安装** 以显示带有二维码的弹出窗口。
- 使用 Android 设备的相机扫描二维码，以在默认的网页浏览器中打开构建链接。
- 点击网页上的 **安装** 按钮以下载 **.apk** 文件。
- 下载完成后，打开 **.apk** 以开始安装过程。
- 如果出现 **不安全的应用被阻止消息**，请选择 **仍然安装**。这个警告可以放心忽略，因为 **.apk** 的来源（我们生成的）是可信的。
---
Step 2: 
### 运行开发构建
通过在项目目录中运行 `npx expo start` 启动开发服务器。一旦服务器运行，按 <kbd>a</kbd> 在终端窗口中打开项目：
```sh
$ npx expo start
```
## Android 模拟器
Step 1: 
### 安装开发构建
在终端中，一旦构建完成，EAS CLI 会提示我们是否想在 Android 模拟器上运行该构建。按 <kbd>Y</kbd>。
Note: 备用：使用 Expo Orbit
---
此外，可以使用 [Expo Orbit](/build/orbit/) 进行安装。请在 EAS 仪表板上的 **构建工件** 中单击 **使用 Expo Orbit 打开** 以在 Android 模拟器上安装开发构建。
---
Step 2: 
### 运行开发构建
通过在项目目录中运行 `npx expo start` 启动开发服务器。一旦服务器运行，按 <kbd>a</kbd> 在终端窗口中打开项目：
```sh
$ npx expo start
```
## 总结
<ProgressTracker
  currentChapterIndex={1}
  name="EAS_TUTORIAL"
  summary={
    <>
      我们成功地使用 EAS Build 在 Android 设备和模拟器上创建并运行了开发构建，并了解了{' '}
      <strong>.apk</strong> 和 <strong>.aab</strong> 文件格式。
    </>
  }
  nextChapterDescription="在下一章中，学习如何使用 EAS Build 配置 iOS 模拟器的开发构建并使其运行。"
  nextChapterTitle="为 iOS 模拟器创建并运行云构建"
  nextChapterLink="/tutorial/eas/ios-development-build-for-simulators/"
/>


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

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

在本章中，我们将创建一个可以在 iOS 模拟器上运行的开发构建，使用 EAS Build。
iOS 模拟器的开发构建以 **.app** 格式生成，这与 iOS 设备不同。
Video Tutorial: [观看：为 iOS 模拟器创建开发构建](https://www.youtube.com/watch?v=SgL97PFZctg)
---
## 在 eas.json 中创建模拟器构建配置
在 **eas.json** 中，添加一个名为 `ios-simulator` 的新构建配置，并设置 [`ios.simulator`](/eas/json/#simulator) 属性。将其值设置为 `true`：
```json eas.json
{
  "build": {
    "development": {
    },
    "ios-simulator": {
      "ios": {
        "simulator": true
      }
    }
  }
}
```
对于开发构建，必须在配置中定义 `developmentClient` 和 `distribution` 属性。为了避免冗余，我们可以扩展 `development` 配置属性：
```json eas.json
{
  "ios-simulator": {
    "extends": "development",
    "ios": {
      "simulator": true
    }
  }
}
```
## iOS 模拟器的开发构建
Step 1: 
### 创建
运行 `eas build` 命令，将 `ios` 作为平台，`ios-simulator` 作为构建配置：
```sh
$ eas build --platform ios --profile ios-simulator
```
此命令在我们第一次创建构建时，会提示我们以下问题：
- **您希望您的 iOS 包标识符是什么？** 按 <kbd>return</kbd> 以选择此提示提供的默认值。这将添加 [`ios.bundleIdentifier`](/versions/latest/config/app/#package) 到 **app.json**。
- **iOS 应用是否只使用标准/豁免加密？** 按 <kbd>Y</kbd> 选择此提示提供的默认值。由于我们的应用未使用加密，它将 `ITSAppUsesNonExemptEncryption` 在 **Info.plist** 文件中设置为 `NO`，并在您将应用发布到 TestFlight/Apple App Store 时管理相应的合规性检查。当您发布自己的应用，并且它使用加密时，您可以选择 `N` 下次跳过此提示。
在回应提示后，我们的 EAS Build 被排队，EAS CLI 提供了一个链接来查看构建详情并跟踪 EAS 仪表板上的进度：
Note: 构建详情页面包含什么？
---
构建详情页面显示构建类型、配置、Expo SDK 版本、应用版本、构建编号、最后提交哈希和发起构建的开发者或账户所有者的身份。
在上图中，**构建产物** 的当前状态显示构建正在进行中。完成后，此部分将提供下载构建的选项。**日志**概述了在 EAS Build 中执行 iOS 构建过程的每个步骤。为了简洁起见，我们在这里不会详细探讨每一步。如需了解更多，请参阅 [iOS 构建过程](/build-reference/ios-builds/)。
---
Note: 什么是 iOS 包标识符？
---
`ios.bundleIdentifier` 是我们应用的唯一名称。如果我们现在发布我们的应用，Apple App Store 将使用此属性及其值来识别我们在商店中的应用。
该表示法定义为 `host.owner.app-name`。例如，我们的示例应用有 `com.owner.stickersmash`，其中 `com.owner` 是域名，`stickersmash` 是我们的应用名称。
---
Step 2: 
### 安装
在终端中，构建完成后，EAS CLI 提示我们是否要在 iOS 模拟器上运行构建。按 <kbd>Y</kbd>。
Note: 备用：使用 Expo Orbit
---
您可以使用 [Expo Orbit](https://expo.dev/orbit) 来安装开发构建。在 EAS 仪表板上的 **构建产物** 中，单击 **使用 Expo Orbit 打开**，以便在 iOS 模拟器上安装开发构建。
---
Step 3: 
### 运行
通过从项目目录运行 `npx expo start` 命令来启动开发服务器：
```sh
$ npx expo start
```
在终端窗口中按 <kbd>i</kbd> 以在 iOS 模拟器上打开项目。
## 总结
<ProgressTracker
  currentChapterIndex={2}
  name="EAS_TUTORIAL"
  summary="我们成功使用 EAS Build 在 iOS 模拟器上创建和运行开发构建。"
  nextChapterDescription="在下一个章节中，让我们为 iOS 创建开发构建，在设备上安装它并使其运行。"
  nextChapterTitle="创建并运行 iOS 设备的云构建"
  nextChapterLink="/tutorial/eas/ios-development-build-for-devices/"
/>


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

了解如何使用 EAS Build 配置针对 iOS 设备的开发构建。

在本章中，我们将创建一个可以在 iOS 设备上运行的开发构建，使用 EAS Build。
针对 iOS 设备的开发构建以 **.ipa** 格式生成，这是 iOS 应用程序安装的标准格式。
Video Tutorial: [观看：为 iOS 实体设备创建开发构建](https://www.youtube.com/watch?v=HbfWU7_o4cU)
---
## 先决条件
在我们开始之前，请确保您已具备以下条件：
- **Apple 开发者账号：** 这对于访问[必要的凭证](/app-signing/app-credentials/#ios) 以签名我们的应用是必需的，因为每个构建都需要进行签名，以验证该应用来自受信任的来源。EAS Build 帮助管理这些凭证。
- **在 iOS 16 及更高版本上激活开发者模式：** 在您的设备上安装开发构建需要启用开发者模式。如果这是您第一次操作或当前未启用，请查看这些说明以 [激活开发者模式](/guides/ios-developer-mode/)。
## 配置文件
要在 iOS 设备上开始开发，我们必须：
- 通过创建新的 [配置文件](/app-signing/app-credentials/#provisioning-profiles) 来注册设备。
- 将此配置文件下载并安装到设备上。
Step 1: 
### 注册 iOS 设备
使用 EAS CLI，运行命令以注册新 Apple 设备：
```sh
$ eas device:create
```
该命令会提示我们以下问题：
- **您在项目目录中。您希望使用** **your-account-name** **账号吗？** 按 <kbd>Y</kbd>。
- **Apple ID。** 对于此步骤，输入您的 Apple ID。然后将登录到我们的 Apple 开发者账号。在终端窗口中按照步骤操作。
- **您希望如何注册设备？** 选择 **网站**，会生成一个可以在 iOS 设备上打开的注册 URL。
> **info** **提示**：如果您或您的团队拥有多台设备，可以将配置文件链接分享给那些设备以进行下载和安装。
Step 2: 
### 下载并安装配置文件
在设备的网络浏览器中，打开上一步提供的链接并点击 **下载配置文件按钮**。
打开 **设置** 应用，提示我们注册设备。
点击 **安装** 来注册 iOS 设备。
配置文件安装后，我们的设备将重定向回网络浏览器，显示一条成功消息以指示过程完成。
## 针对 iOS 设备的开发构建
Step 1: 
### 创建
要在 iOS 设备上创建开发构建，请确保在 `build.development` 配置文件下：
- **eas.json** 中的 `developmentClient` 设置为 `true`，这是默认配置。
- 然后，运行 `eas build` 命令，指定 `ios` 为平台，`development` 为构建配置：
```sh
$ eas build --platform ios --profile development
```
> **info** **提示**：下次运行 `eas build` 命令时，您也可以使用 `-p` 指定平台。它是 `--platform` 的缩写。
该命令在我们第一次创建构建时会提示我们以下问题：
- **您希望您的 iOS 包标识符是什么？** 按 <kbd>return</kbd> 以选择此提示提供的默认值。如果尚未定义，将在 **app.json** 中添加 [`ios.bundleIdentifier`](/versions/latest/config/app/#package)。
- **您想登录到您的 Apple 账号吗？** 由于我们第一次创建开发构建，它会询问我们 **生成新的 Apple 分发证书**。请按两次 <kbd>Y</kbd>。
- **选择一个设备进行临时构建**。这是关键部分，因此我们之前必须注册配置文件。我们可以在这里选择一个或所有已注册的设备，然后按回车以稍后在这些设备上安装该构建。
> **info** **仅在您跳过 [iOS 模拟器章节](/tutorial/eas/ios-development-build-for-simulators/) 时：** 系统会提示 **iOS 应用程序是否仅使用标准/豁免加密？** 按 <kbd>Y</kbd> 以选择此提示提供的默认值。由于我们的应用未使用加密，它将在 **Info.plist** 文件中将 `ITSAppUsesNonExemptEncryption` 设置为 `NO` 并在您将应用发布到 TestFlight/Apple App Store 时管理合规检查。当您发布自己的应用并且它使用加密时，您可以选择 `N` 以在下次跳过此提示。
在做出回应后，构建将排队，我们可以通过 EAS CLI 在 EAS 仪表板提供的链接跟踪其进度：
Note: 构建详细信息页面包含什么？
---
构建详细信息页面显示构建类型、配置文件、Expo SDK 版本、应用版本、构建编号、上次提交哈希及发起构建的开发者或账号所有者的身份。
在上述图像中，**构建工件**的当前状态显示构建正在进行中。完成后，此部分将提供下载构建的选项。**日志**概述了在 EAS Build 上进行 iOS 构建过程中采取的每一步。为了简洁起见，我们在这里不会详细探讨每一个步骤。要了解更多，请参见 [iOS 构建过程](/build-reference/ios-builds/)。
---
Note: 什么是 iOS 包标识符？
---
`ios.bundleIdentifier` 是我们应用程序的唯一名称。如果我们现在发布我们的应用，Apple App Store 将使用此属性及其值来识别我们在商店中的应用。
这种表示法定义为 `host.owner.app-name`。例如，我们的示例应用具有 `com.owner.stickersmash`，其中 `com.owner` 是域，`stickersmash` 是我们的应用名称。
---
Step 2: 
### 安装
一旦构建完成，构建工件部分将更新，指示构建已完成：
此部分提供在 iOS 设备上运行开发构建的方法：Expo Orbit 和安装按钮。
[Expo Orbit](https://expo.dev/orbit) 允许在 iOS 设备上无缝安装开发构建。要使用此方法：
- 使用 USB 将我们的 iOS 设备连接到开发机器。
- 打开 Orbit 菜单栏应用。
- 在 Orbit 应用中选择 **设备**。
- 在 EAS 仪表板中，在 **构建工件** 下，点击 **用 Orbit 打开**。
构建安装后，Orbit 应用将在设备上启动开发构建。
Note: 替代方案：使用安装按钮和二维码
---
**构建工件**部分中的 **安装** 按钮生成二维码以便于安装：
- 点击 **安装** 显示带二维码的弹出窗口。
- 使用我们 iOS 设备的相机扫描二维码以打开并点击链接，在设备上下载开发构建。
---
Step 3: 
### 运行
从项目目录运行 `npx expo start` 命令以启动开发服务器：
```sh
$ npx expo start
```
- 在设备上，点击应用图标以打开开发构建。
- 通过确保我们在 EAS CLI 和开发构建中都已登录来使用账号同步功能。由于我们已登录 EAS CLI，下一步是通过开发构建的 UI 登录。
- 点击 **获取开发服务器** 并从开发服务器列表中选择正在运行的服务器。
## 总结
<ProgressTracker
  currentChapterIndex={3}
  name="EAS_TUTORIAL"
  summary="我们成功利用 EAS Build 创建并在 iOS 设备上运行开发构建。"
  nextChapterDescription="在下一章，了解如何配置我们的应用配置以在单个设备上安装多个应用变体。"
  nextChapterTitle="配置多个应用变体"
  nextChapterLink="/tutorial/eas/multiple-app-variants/"
/>


## 配置多个应用变体

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

在本章中，我们将配置我们的项目，以便在单个设备上同时运行多个构建类型（开发、预览、生产）。此设置将允许我们测试应用开发的各个阶段，而无需卸载和重新安装不同版本。
Video Tutorial: [观看: 如何配置多个应用变体](https://www.youtube.com/watch?v=UtJJCAfrjIg)
---
每个变体需要一个唯一的 Android 应用程序 ID 和 iOS Bundle 标识符，以便在一台设备上进行同时安装。以下是我们在 **app.json** 文件中设置的 ID：
```json app.json
{
  "ios": {
    "bundleIdentifier": "com.yourname.stickersmash"
  },
  "android": {
    "package": "com.yourname.stickersmash"
  }
}
```
Step 1: 
## 添加 app.config.js 以实现动态配置
**app.json** 包含应用相关的配置，采用 JSON 文件。它是静态的，如果我们想为某些属性使用 [动态值](/workflow/configuration/#dynamic-configuration) 则并不理想。我们将根据 [环境变量](/workflow/configuration/#switching-configuration-based-on-the-environment) 为所有构建配置添加不同的 Android 应用程序 ID 和 iOS Bundle 标识符。
- 在项目的根目录中创建一个名为 **app.config.js** 的新文件。
- 在 **app.config.js** 中，导出一个默认函数，该函数接受 `config` 作为参数。然后，我们将解构 `config` 以复制来自 **app.json** 的所有现有属性。
```js app.config.js
export default ({ config }) => ({
  ...config,
});
```
Step 2: 
## 根据环境更新动态值
为了识别构建类型，我们在 **app.config.js** 中添加两个名为 `IS_DEV` 和 `IS_PREVIEW` 的环境变量，分别用于 `development` 和 `preview` 构建配置：
```js app.config.js
const IS_DEV = process.env.APP_VARIANT === 'development';
const IS_PREVIEW = process.env.APP_VARIANT === 'preview';
```
接着，添加两个函数以动态更改应用名称、Android 应用程序 ID 和 iOS Bundle 标识符：
```js app.config.js
const getUniqueIdentifier = () => {
  if (IS_DEV) {
    return 'com.yourname.stickersmash.dev';
  }
  if (IS_PREVIEW) {
    return 'com.yourname.stickersmash.preview';
  }
  return 'com.yourname.stickersmash';
};
const getAppName = () => {
  if (IS_DEV) {
    return 'StickerSmash (Dev)';
  }
  if (IS_PREVIEW) {
    return 'StickerSmash (Preview)';
  }
  return 'StickerSmash: Emoji Stickers';
};
```
我们将使用 `getAppName()` 为应用分配动态 `name` 值，并使用 `getUniqueIdentifier()` 来区分开发和预览构建的 `android.package` 和 `ios.bundleIdentifier`：
```js app.config.js
export default ({ config }) => ({
  ...config,
  name: getAppName(),
  ios: {
    ...config.ios,
    bundleIdentifier: getUniqueIdentifier(),
  },
  android: {
    ...config.android,
    package: getUniqueIdentifier(),
  },
});
```
Step 3: 
## 配置 eas.json
在 **eas.json** 中，添加 `APP_VARIANT` 环境变量：
```json eas.json|collapseHeight=440
{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "env": {
        "APP_VARIANT": "development"
      }
    },
    "preview": {
      "distribution": "internal",
      "env": {
        "APP_VARIANT": "preview"
      }
    }
  }
}
```
运行 `eas build --profile development` 现在将把 `APP_VARIANT` 设置为 `development`。
> **注意：** 由于我们更改了 Android 应用程序 ID 和 iOS Bundle 标识符，EAS CLI 将提示我们为 Android 生成新的 Keystore 和为 iOS 生成新的配置文件。要了解更多有关这些步骤的信息，请查阅前一章。
由于我们的 `ios-simulator` 构建配置扩展了 `development`，因此此配置自动应用于 iOS 模拟器。
Step 4: 
## 运行开发服务器
> 在构建完成后，遵循前几章中的相同程序，将它们安装到设备或模拟器上。
由于我们通过 `APP_VARIANT` 环境变量识别我们的开发构建，因此在启动开发服务器时需要将其传递到命令中。为此，在我们项目的 **package.json** 的 [`"scripts"`](https://docs.npmjs.com/cli/v10/using-npm/scripts) 字段中添加一个 `dev` 脚本：
```json package.json
{
  "scripts": {
    "dev": "APP_VARIANT=development npx expo start"
  }
}
```
运行 `npm run dev` 命令以启动开发服务器：
```sh
$ npm run dev
```
此脚本将在本地评估 **app.config.js** 并加载开发配置文件的环境变量。
现在，我们的开发构建将在 Android 和 iOS 上运行，显示来自 **app.config.js** 的修改后的应用名称。例如，下面的开发构建在 iOS 模拟器上运行。请注意，应用名称为 **StickerSmash (Dev)**：
您现在可以继续使用 **app.json** 进行静态值的配置，并使用 **app.config.js** 进行动态配置。
## 摘要
<ProgressTracker
  currentChapterIndex={4}
  name="EAS_TUTORIAL"
  summary={
    <>
      我们成功创建了 <strong>app.config.js</strong> 以便进行动态配置，同时保持 **app.json**
      中的静态配置不变，添加了环境变量到 <strong>eas.json</strong>{' '}
      以配置特定的构建配置，并学习了如何使用自定义 <strong>package.json</strong>{' '}
      脚本启动开发服务器。
    </>
  }
  nextChapterDescription="在下一章中，了解什么是内部分发构建，为什么我们需要它们，以及如何创建它们。"
  nextChapterTitle="创建和分享内部分发构建"
  nextChapterLink="/tutorial/eas/internal-distribution-builds/"
/>


## 创建和分享内部分发构建

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

在本章中，我们将学习如何设置 [内部分发构建](/build/internal-distribution/#internal-distribution)。
Video Tutorial: [观看：如何创建和分享内部分发构建](https://www.youtube.com/watch?v=1fQuGLHxWks)
---
## 内部分发构建
内部分发构建非常适合与团队成员分享更新，使技术和非技术利益相关者能够直接提供反馈。与开发构建不同，这些构建不需要运行开发服务器，从而简化了测试过程。
### 内部分发应用的方法
谷歌和苹果都提供内置机制来内部分享应用：
- **Android**：使用 Google Play beta
- **iOS**：使用 TestFlight
不过，这两种传统方法都有其局限性。例如，TestFlight 每次只能有一个活动构建。
### EAS Build 以更快分发
EAS Build 加快了这一过程。它为我们的构建创建可分享链接，并提供使用说明。它有一个默认配置，旨在促进内部分发，提供比传统方法更高效的替代方案。
## 创建内部分发构建
要使用 EAS Build 创建和分发构建，我们需要遵循以下步骤：
Step 1: 
### 配置预览构建配置文件
从我们在 **eas.json** 中的初始设置，我们已经拥有包含 `preview` 构建配置文件的默认配置，旨在用于内部分发：
```json eas.json
{
  "build": {
    "preview": {
      "distribution": "internal"
    }
  }
}
```
这就是我们创建首个内部分发构建所需的全部。上面代码片段中的 `preview` 构建配置文件有一个 `distribution` 属性，其值设置为 `internal`。此值允许我们将构建 URL 分享给任何人，以便他们可以在其设备上安装，并且不需要运行开发服务器来使用该应用。
如前几章所述，对于非应用商店构建，Android 需要 **.apk** 格式，而 iOS 则需要 **.ipa** 格式。这同样适用于内部分发构建。当 `distribution` 设置为 `internal` 时，会自动为设备创建这些文件格式的应用二进制文件。
Step 2: 
### 创建
创建内部分发构建需要 [应用签名凭证](/app-signing/app-credentials/)。
Android 应用签名没有限制，允许安装任何兼容的 **.apk** 文件。当创建开发构建时，会新生成一个 Android Keystore。因此，无需为预览构建生成新 Keystore。
另一方面，苹果对 iOS 设备的应用分发有更严格的规定。我们需要一个明确列出允许运行该应用的设备的临时配置文件。一些符合特定要求的组织可能能够使用 [Apple Developer Enterprise Program](https://developer.apple.com/programs/enterprise/) 在更大范围内内部分发应用。
For Android: 
- 使用 `preview` 配置文件启动 Android 构建：
```sh
$ eas build --platform android --profile preview
```
- 此命令触发 EAS Build，且在 EAS 仪表板上，我们可以看到构建进度：
For iOS: 
使用临时配置文件签名的应用可以被其 UDID 注册在配置文件中的 iOS 设备安装。
- 要注册更多设备，请使用 `eas device:create`。此命令注册一个 iOS 设备，并给我们一个可以分享的用于设备注册的 URL 或二维码：
```sh
$ eas device:create
```
- 此命令为应用安装注册一个 iOS 设备，生成一个可分享的 URL（或二维码）用于设备注册。
  > **info** **提示**：此命令允许随时进行设备注册。然而，仅会在注册后创建的构建能在新添加的设备上工作。
- 要创建预览构建，我们需要使用 `eas build` 命令与 `preview` 配置文件：
```sh
$ eas build --platform ios --profile preview
```
- 此命令触发 EAS Build，且在 EAS 仪表板上，我们可以看到构建进度：
Note: 使用  注册设备的替代方法
---
[`eas build:resign`](/app-signing/app-credentials/#re-signing-new-credentials) 命令可用于使用新的临时配置文件重新签名现有的 iOS **.ipa**，避免了完全重建的需求。
---
Note: 您是在设置企业配置吗？
---
苹果企业计划会员费用为每年299美元，并且 [并非所有组织都有资格](https://developer.apple.com/programs/enterprise/)，因此您可能会使用临时配置，这适用于任何正常的付费苹果开发者账户。
如果您拥有 [Apple Developer Enterprise Program 会员](https://developer.apple.com/programs/enterprise/)，用户可以将您的应用安装到他们的设备上，而无需事先注册其 UDID。只需在其设备上安装配置文件，就可以访问现有的构建。在 `eas build` 过程中，您需使用您的苹果开发者企业账户登录，以设置正确的配置。
如果您通过企业配置和应用商店分发应用，则每种情况都需要有不同的包标识符。我们建议您选择：
- 在使用 Expo CLI 生成的项目中，使用 [**app.config.js** 动态切换标识符](/tutorial/eas/multiple-app-variants/)。
- 在 [现有的 React Native 项目](/bare/overview/) 中，为每个包标识符创建一个单独的 `scheme`，并在单独的构建配置文件中指定方案名称。
---
Note: 您在使用手动本地凭证吗？
---
如果是，请确保将您的 **credentials.json** 指向通过苹果开发者门户生成的临时或企业配置文件（可以更新用于其他分发类型的现有 **credentials.json**，或将其替换为指向适当配置文件的新文件）。注意，EAS CLI 对您的本地凭证只进行有限的验证，您需要手动处理设备 UDID 注册。了解更多关于 [使用本地凭证](/app-signing/local-credentials)。
---
Step 3: 
### 安装
一旦构建完成，构建工件部分会更新，指示构建已完成。该部分提供在 iOS 设备上运行开发构建的方法：Expo Orbit 和安装按钮。
- 打开构建的详细页面。如果您与他人分享构建，可以将链接发送给他们。他们将能够打开构建的详细页面或构建工件细节，其中包括 Expo Orbit。
- 使用 USB 将 Android 或 iOS 设备连接到您的机器。
- 打开 Orbit 菜单栏应用。
- 在 Orbit 应用中选择 **设备**。
- 在 **构建工件** 下，单击 **用 Orbit 打开**。
Note: 备用：使用安装和二维码
---
- 打开构建的详细页面。如果您与他人分享构建，可以将链接发送给他们。他们将能够打开它并查看构建工件细节，其中包括 Expo Orbit。
- 在构建工件部分点击 **安装**，以显示 **在测试设备上安装** 弹出窗口。
- 从 **发送链接到设备** 部分复制链接，并发送到测试设备。
---
Step 4: 
### 运行
轻触您的设备上的应用图标以启动预览构建。无需开发服务器。
由于我们已经设置了多个应用变体，我们可以看到开发和预览变体在设备上分别安装。例如：
- 在 Android 上：
- 在 iOS 上：
## 总结
<ProgressTracker
  currentChapterIndex={5}
  name="EAS_TUTORIAL"
  summary="我们成功地为 Android 和 iOS 创建了内部分发构建，对 iOS 使用了临时配置，并在同一设备上安装了多个应用变体。"
  nextChapterDescription="在下一章中，了解面向开发者和面向用户的应用版本，以及如何自动管理它们。"
  nextChapterTitle="管理不同的应用版本"
  nextChapterLink="/tutorial/eas/manage-app-versions/"
/>


## 管理不同的应用版本

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

在本章中，我们将学习 EAS Build 如何自动管理 Android 和 iOS 的面向开发者的应用版本。在我们深入下两章的生产构建之前，了解这一点将是有用的。
Video Tutorial: [观看：自动化应用版本代码](https://www.youtube.com/watch?v=C8x4N9UmzS8)
---
## 理解面向开发者和面向用户的应用版本
应用版本由两个值组成：
- 面向开发者的值：对于 Android，由 [`versionCode`](/versions/latest/config/app/#versioncode) 表示，对于 iOS，由 [`buildNumber`](/versions/latest/config/app/#buildnumber) 表示。
- 面向用户的值：由 [`version`](/versions/latest/config/app/#version) **app.config.js** 表示。
Google Play 商店和 Apple App Store 依赖面向开发者的值来识别每个唯一构建。例如，如果我们上传一个应用版本为 `1.0.0 (1)` 的应用（这是面向用户和面向开发者值的组合），我们不能提交另一个具有相同应用版本的构建到应用商店。提交具有重复应用版本号的构建会导致提交失败。
下面通过 **app.config.js** 中的 `android.versionCode` 和 `ios.buildNumber` 展示手动管理面向开发者值的示例。**我们不需要手动添加或管理这些值，因为 EAS Build 为我们自动化了这一过程**。
```js app.config.js
{
  ios: {
    buildNumber: 1
  },
  android: {
    versionCode: 1
  }
}
```
> **注意：** [面向用户的版本号](/build-reference/app-versions/#user-facing-version) 不由 EAS 处理。相反，我们在提交生产应用进行审核之前，在应用商店开发者门户中定义该版本。
## 使用 EAS Build 进行自动化应用版本管理
默认情况下，EAS Build 有助于自动化面向开发者的值。它利用 [远程版本来源](/build-reference/app-versions/#remote-version-source) 在每次进行新的生产发布时自动递增面向开发者的值。
当我们用 `eas init` 命令初始化项目时，EAS CLI 自动在 **eas.json** 中添加了以下属性：
- `cli.appVersionSource` 设置为 `remote`
- [`build.production.autoIncrement`](/eas/json/#autoincrement-1) 设置为 `true`
你可以在项目的 **eas.json** 中查看它们：
```json eas.json
{
  "cli": {
    "appVersionSource": "remote"
  },
  "build": {
    "production": {
      "autoIncrement": true
    }
  }
}
```
当我们在接下来的两章中创建一个新的生产构建时，Android 的 `versionCode` 和 iOS 的 `buildNumber` 将自动递增。
Note: 将已发布应用的面向开发者版本同步到 EAS
---
如果你的应用已在应用商店中发布，则面向开发者的应用版本已设置。当将此应用迁移到使用 EAS Build 时，请按照以下步骤同步这些应用版本：
- 在终端窗口中运行 `eas build:version:set` 命令：
```sh
$ eas build:version:set
```
- 在提示时选择平台（Android 或 iOS）。
- 当提示 **你是否想现在将应用版本源设置为远程？** 时，选择 **是**。这将在 **eas.json** 中将 `cli.appVersionSource` 设置为 `remote`。
- 当提示 **你想用什么版本初始化？** 时，输入你在应用商店中设置的最后版本号。
完成这些步骤后，应用版本将远程同步到 EAS Build。你可以在 **eas.json** 中将 `build.production.autoIncrement` 设置为 `true`。当你创建一个新的生产构建时，从现在开始 `versionCode` 和 `buildNumber` 将自动递增。
---
## 总结
<ProgressTracker
  currentChapterIndex={6}
  name="EAS_TUTORIAL"
  summary={
    <>
      我们成功探讨了应用版本差异，强调了独特应用版本对于防止商店拒绝的重要性，并在{' '}
      <strong>eas.json</strong> 中启用了生产构建的自动版本更新。
    </>
  }
  nextChapterDescription="在下一章中，了解如何为 Android 创建生产构建。"
  nextChapterTitle="为 Android 创建生产构建"
  nextChapterLink="/tutorial/eas/android-production-build/"
/>


## 为 Android 创建生产构建

了解创建 Android 生产构建和自动化发布过程的流程。

在本章中，我们将创建我们的示例应用程序的生产版本并将其提交到 Google Play 商店。我们还将探讨如何自动化创建和发布新版本的应用程序。
Video Tutorial: [观看：为 Android 创建和发布生产构建](https://www.youtube.com/watch?v=nxlt8uwqhpE)
---
## 先决条件
要在 Google Play 商店发布和分发应用程序，我们需要：
- **Google Play 开发者账户：** 必须拥有一个付费开发者账户。有关设置的详细信息，请访问 [Google Play 注册页面](https://play.google.com/apps/publish/signup/)。
- **Google 服务账户密钥：** 我们需要一个 Google 服务账户邮箱和 JSON 密钥以自动化应用程序提交过程。**遵循我们关于 [创建 Google 服务账户密钥或从现有账户下载的详细说明](https://expo.fyi/creating-google-service-account)，然后返回本指南。** 这是可选的，但在 [自动化发布过程](#automated-release) 中是必需的。
- **生产构建配置文件：** 确保在您的 **eas.json** 中存在一个 `production` 构建配置文件，该文件是默认添加的。
## Android 生产构建
一个 [生产 Android 构建](/build/eas-json/#production-builds) 具有 **.aab** 格式，针对 Google Play 商店的分发进行了优化。与 **.apk** 构建不同，**.aab** 文件只能通过 Google Play 商店进行分发和安装。
Step 1: 
## 创建生产构建
要使用默认 `production` 配置文件创建 Android 生产构建，请打开终端并执行以下命令。由于 `production` 被设置为 EAS 配置中的默认配置文件，因此无需通过 `--profile` 标志显式指定它。
```sh
$ eas build --platform android
```
上述命令将排队构建。在 EAS 仪表板中，注意 **版本代码** 是自动递增的。
Step 2: 
## 在 Google Play 控制台上创建应用
要首次上传应用到 Google Play 商店，我们需要：
- 前往 Google Play 仪表板。
- 在 **主页** 上，点击 **创建应用** 以创建一个新的应用。
- 填写我们的应用信息并点击 **创建应用** 按钮。
Step 3: 
## 发布内部测试版本
在 Google Play 控制台上创建应用后，它会将我们重定向到应用的仪表板屏幕。我们需要准备一个应用的内部测试版本。
- 在 **Dashboard** 上点击 **Start testing now**。
- 在 **Internal Testing** > **Testers for the internal testing release** 下创建一个用户电子邮件列表。
- Google Play Console 提示我们创建一个 **Release** 。
- 要创建新的发布，请转到 **Releases** 并点击 **Create new release** 。
- 要存储签名密钥，请转到 **App integrity** > **App bundles** 并点击 **Choose signing key** > **Use Google-generated key** 。
Step 4: 
## 上传应用二进制文件
在 EAS 创建生产构建后：
- 打开 EAS 仪表板并点击 **Download** 以获取 **.aab** 文件。
- 返回 Google Play 控制台并转到 **App bundles** 。点击 **Upload** 以添加 **.aab**。
- 提供我们应用的发布详情并点击 **Next** 。
- 在下一个屏幕上，点击 **Save and publish** 。
Step 5: 
## 分享内部发布版本
在 **Track Summary** 下，我们看到最新的发布显示了一个临时应用名称。这是因为我们的应用尚未审核。
在 **Releases** 下，我们看到该应用已对内部测试人员可用。要与测试团队分享该应用：
- 打开内部测试仪表板，然后点击 **View release details** 。
- 在 **How testers join your test** 下点击 **copy link** 。
- 在设备上，打开测试电子邮件并按照步骤下载应用。
- 测试邮件持有者需要接受邀请，接受后，应用可以在设备上安装。
> **info** **提示**：要在 Play 商店上发布应用，在 Google 仪表板中，完成 **设置您的应用** 下的步骤。这些步骤是在第一次在 Play 商店上发布应用之前所需的。您将需要提供隐私政策链接、目标受众、数据安全等详细信息。
> **完整的应用商店列表**：要准备应用进行商店列表，请参见 [创建应用商店资产](/guides/store-assets/) 以了解如何创建屏幕截图和预览。
Note: 提升测试发布
---
要将我们的内部测试发布版本提升为 **alpha**，在 Google Play 商店控制台中：
- 转到内部测试并点击 **Promote release** 。
- 打开下拉菜单并点击 **Closes testing** > **Closed testing - Alpha**。
---
Step 6: 
## 添加 Google 服务账户权限密钥
> **info** **提示**：在遵循本节中的步骤之前，请查看关于 [创建 Google 服务账户密钥或从现有账户下载](https://expo.fyi/creating-google-service-account) 的指南中的说明。
从现在开始，我们可以使用 [EAS Submit](/submit/introduction/) 来自动化发布，避免手动流程。为了做到这一点，我们需要将服务账户密钥添加到我们项目的 **eas.json** 中。
在遵循 Google 服务账户指南步骤后，我们可以使用下载的 JSON 密钥：
- 打开我们的项目，将 Google 服务账户的 JSON 文件复制到项目的根目录。
- 为了保护敏感数据，请确保通过在我们的 **.gitignore** 中列出它将该文件排除在版本控制之外。
Step 7: 
## 内部发布
让我们将 Google 服务账户文件路径添加到 **eas.json** 中。
- 在 `submit.production` 配置文件下，添加 `android.serviceAccountKeyPath` 和相对文件路径作为其值：
```json
{
  "submit": {
    "production": {
      "android": {
        "serviceAccountKeyPath": "./service-account-file.json",
        "track": "internal"
      }
    }
  }
}
```
在上述代码段中，我们还添加了 [`track`](/eas/json/#track) 属性，并将其值设置为 `internal`。这将使 `eas submit` 命令能够上传我们的生产构建，并将其发布为 Google Play 商店上的内部测试。
- 现在运行 `eas submit` 命令以发布新的内部测试版本：
```sh
$ eas submit --platform android
```
- 此命令将自动在 Google Play Console 中创建一个新的内部发布版本：
Step 8: 
## 生产发布
要为生产发布应用：
- 在 **eas.json** 中将 `track` 的值更改为 `production`：
```json
{
  "submit": {
    "production": {
      "android": {
        "serviceAccountKeyPath": "./service-account-file.json",
        "track": "production"
      }
    }
  }
}
```
- 我们还可以使用我们为内部测试发布执行的相同 EAS 构建。运行 `eas submit` 命令以发布到 Play 商店：
```sh
$ eas submit --platform android
```
- 要创建跟踪并将我们的应用提交到 Google Play 商店的审核过程，我们需要 **发布** > **生产**，在 **发布** 下选择我们要发送审核的构建。
Step 9: 
## 自动化发布
对于未来的后续发布，我们可以通过将构建创建和 Play 商店提交合并为一个步骤来简化流程，使用 `eas build` 的 [`--auto-submit`](/build/automate-submissions/) 标志：
```sh
$ eas build --platform android --auto-submit
```
## 总结
<ProgressTracker
  currentChapterIndex={7}
  name="EAS_TUTORIAL"
  summary={
    <>
      我们成功创建了一份准备好生产的 Android 构建，讨论了使用 {' '}
      手动和自动上传到 Google Play 商店的方法，并使用  自动化了发布过程。
    </>
  }
  nextChapterDescription="
在下一章中，了解为 iOS 创建生产构建的过程。"
  nextChapterTitle="为 iOS 创建生产构建"
  nextChapterLink="/tutorial/eas/ios-production-build/"
/>


## 为iOS创建生产构建

了解创建iOS生产构建及自动化发布流程的过程。

在本章中，我们将创建示例应用程序的生产版本，并通过TestFlight提交进行测试。之后，我们将提交应用程序进行App Store审核，以便在App Store上发布。
Video Tutorial: [观看：为iOS创建和发布生产构建](https://www.youtube.com/watch?v=VZL_e0cEwo8)
---
## 先决条件
要在苹果应用商店发布和分发应用程序，我们需要：
- **苹果开发者账户：** 要创建一个，请参见 [Apple Developer Portal](https://developer.apple.com/account/)。
- **生产构建配置文件：** 确保在您的**eas.json**中存在一个`production`构建配置文件，默认情况下会添加。
## iOS的生产构建
[生产 iOS 构建](/build/eas-json/#production-builds) 针对苹果的App Store Connect进行了优化，允许通过TestFlight分发构建给测试者，并通过App Store分发给公众最终用户。这种构建类型无法在模拟器或设备上侧载，且仅能通过App Store Connect进行分发。
Step 1: 
## 创建分发凭证配置文件
在终端中运行 `eas credentials` 命令，然后根据EAS CLI的提示回答以下问题：
- **选择平台** iOS。
- **您想要配置哪个构建配置文件？** 选择生产。
- **您是否希望登录到您的苹果账户？** 按<kbd>Y</kbd>。这将登录到我们的苹果开发者账户。
- **您想要做什么？** 选择**构建凭证**并选择**全部：设置构建项目所需的所有凭证**。
- 现在，会提示您是否希望重新使用先前的分发证书。按<kbd>Y</kbd>。
- **生成新的苹果配置文件？** 按<kbd>Y</kbd>。这将是生产应用程序的配置文件。
- 配置文件创建完成后，按任意<kbd>ctrl</kbd> + <kbd>c</kbd>以退出EAS CLI。
Step 2: 
## 创建生产构建
要使用默认的`production`配置文件创建iOS生产构建，请打开终端并执行以下命令。由于在EAS配置中设置了`production`为默认配置文件，因此无需使用`--profile`标志显式指定。
```sh
$ eas build --platform ios
```
命令将排队构建。请注意EAS仪表板上的**构建编号**是自动递增的。
Step 3: 
## 向App Store提交应用程序二进制文件
要提交从最新的EAS构建生成的应用程序二进制文件，请运行[`eas submit`](/submit/introduction/)命令：
```sh
$ eas submit --platform ios
```
运行此命令后，我们需要：
- **从EAS中选择一个构建。** 让我们选择最新的构建ID。
- **按照提示登录到我们的苹果账户。** 当询问**是否重用此App Store Connect API密钥？**时，按<kbd>Y</kbd>。
这将触发提交过程。
Step 4: 
## 发布内部测试版本
提交过程完成后，我们需要从网络浏览器登录到苹果开发者账户。
- 点击 **[Apps](https://appstoreconnect.apple.com/apps)**，查看应用程序图标。
- 点击应用程序名称，在导航选项卡菜单中点击**TestFlight**。如果构建刚刚提交，可能需要几分钟才能让苹果处理构建，然后可以通过TestFlight进行分发。
> **info** **仅在您跳过了[iOS设备的开发构建章节](/tutorial/eas/ios-development-build-for-devices/)时：**您将被提示**iOS应用程序是否仅使用标准/豁免加密？** 按<kbd>Y</kbd>以选择此提示提供的默认值。由于我们的应用程序不使用加密，因此在**Info.plist**文件中将`ITSAppUsesNonExemptEncryption`设置为`NO`，并在您将应用程序发布到TestFlight/Apple App Store时管理合规性检查。当您发布自己的应用程序时，若使用加密，可以选择`N`以跳过下次的提示。
- 在App Store Connect中，导航到**内部测试**，创建一个测试组。这将允许我们邀请测试用户。
- 一旦组创建成功，将向所有测试用户发送电子邮件。
- 在电子邮件中，点击**在 TestFlight 中查看**，接受邀请，然后点击 **安装**。
之后，应用程序将下载到我们的设备，以便我们进行测试。
> **注意**：与内部测试类似，我们还可以创建一个组，以利用TestFlight邀请外部测试人员。内部测试限制为100名用户，而TestFlight允许将测试发布版外部分享给多达10,000名测试人员，并提供可公开分享的链接。为了简洁起见，本教程中不涵盖这些步骤。
Step 5: 
## 向Apple App Store提交应用程序
要准备我们的应用程序进行 App Store 提交，请转到 **App Store** 选项卡：
- 提供元数据详细信息，根据苹果的指南提供屏幕截图，并填写 **常规** 下的详细信息。
- 然后，手动选择构建。
> **完整 App Store 列表**：要准备应用程序进行商店列表，请参见[创建应用商店资产](/guides/store-assets/)以了解如何创建屏幕截图和预览。
- 一旦我们的应用程序准备就绪，点击**提交申请审查**。之后，苹果将审查我们的应用程序，如果获得批准，应用程序将在App Store上发布。
Step 6: 
## 自动提交
对于未来的发布，我们可以通过使用`eas build`命令的[`--auto-submit`](/build/automate-submissions/)标志，将构建创建和App Store提交的过程合并为一个步骤，从而简化流程。
```sh
$ eas build --platform ios --auto-submit
```
> **注意：** 此命令将自动将您的构建上传到TestFlight进行内部测试，但不会自动提交您的应用程序进行App Store审核。当您准备好公开发布时，您仍需手动将构建从TestFlight推广到App Store。有关更多信息，请参见[应用商店的默认提交行为](/build/automate-submissions/#default-submission-behavior-for-app-stores)。
## 总结
<ProgressTracker
  currentChapterIndex={8}
  name="EAS_TUTORIAL"
  summary={
    <>
      我们成功创建了一个生产就绪的iOS构建，讨论了使用TestFlight和苹果App Store通过
      进行分发，并通过自动化发布流程。
    </>
  }
  nextChapterDescription="在下一章中，了解如何使用EAS更新发送OTA更新并与我们的团队分享预览。"
  nextChapterTitle="与您的团队分享预览"
  nextChapterLink="/tutorial/eas/team-development/"
/>


## 与团队分享预览

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

更新通常修复小错误，并在应用商店发布之间推送小改动。它们允许更新我们示例应用的非原生部分，例如 JavaScript 代码、样式和图像。
在这一章中，我们将使用 [EAS Update](/eas-update/introduction/) 与我们的团队分享更改。这将帮助 [我们和我们的团队快速分享预览](/review/overview/) 更改。
Video Tutorial: [观看：如何与团队分享预览](https://www.youtube.com/watch?v=vPKh-tNm-yI)
---
Step 1: 
## 安装 expo-updates 库
要初始化我们的项目并发送更新，我们需要使用 [`expo-updates`](/versions/latest/sdk/updates/) 库。运行以下命令安装它：
```sh
$ npx expo install expo-updates
```
Step 2: 
## 配置 EAS Update
要使用 EAS Update 初始化我们的项目，我们需要遵循以下步骤：
- 由于我们为应用的配置使用动态 **app.config.js**，因此必须添加 [`updates`](/versions/latest/config/app/#updates) 和 [`runtimeVersion`](/eas-update/runtime-versions/#setting-runtimeversion) 属性，以使我们的项目与 EAS Update 兼容。运行以下命令从 EAS 获取这些属性及其值，并手动复制到 **app.config.js**：
```sh
$ eas update:configure
```
Note: 非动态（app.json）项目怎么办？
---
如果一个项目不使用动态应用配置（使用 **app.json** 而不是 **app.config.js**），上述命令将配置我们的应用以与 EAS Update 兼容，并将正确的属性添加到 **app.json** 和 **eas.json**。
---
- 重新运行 `eas update:configure` 以继续设置过程。每个构建配置文件中都应添加 [`channel`](/eas/json/#channel) 到 **eas.json**：
```json eas.json
{
  "build": {
    "development": {
      "channel": "development"
    },
    "ios-simulator": {
    },
    "preview": {
      "channel": "preview"
    },
    "production": {
      "channel": "production"
    }
  }
}
```
> **info** 请注意，`eas update:configure` 命令将 `channel` 添加到 **eas.json** 中的每个构建配置文件中。然而，我们的 `ios-simulator` 配置文件扩展了 `development` 配置文件，拥有一个单独的 `channel` 是没有意义的。我们可以安全地从上述配置中删除 `ios-simulator.channel`。
Note: 什么是 channel？
---
[Channel](/eas-update/how-it-works/#conceptual-overview) 用于将构建分组在一起。如果我们有一个 Android 和一个 iOS 构建，两个都在应用商店中，我们可以将它们都给予生产 channel。稍后，我们可以告诉 EAS Update 以目标生产 channel，因此我们的更新将影响所有具有生产 channel 的构建。
---
Step 3: 
## 创建开发构建
我们需要创建一个新的开发构建，因为我们最后的构建不包含 `expo-updates` 库。运行以下命令：
```sh
$ eas build --platform android --profile development
```
> 我们使用开发构建来演示 Android 设备的更新。然而，我们可以使用 `--platform all` 或 `--platform ios` 来创建适用于两个平台或仅 iOS 的构建。
在新版本的开发构建创建后，请确保在设备上安装它。
Step 4: 
## 修改应用的 JavaScript 代码
让我们修改示例应用的 JavaScript 代码。如果您没有使用 [Sticker Smash 应用](/tutorial/eas/introduction/#prerequisites)，您可以修改代码的任何部分，以查看应用中的更改。
我们将修改示例应用中第一个按钮的文本，将 **选择照片** 更改为 **选择照片**。
```tsx app/(tabs)/index.tsx
<Button theme="primary" label="Select a photo" onPress={pickImageAsync} />
```
Step 5: 
## 发布更新
我们不想要创建一个新构建与团队分享此更改进行测试，而是让我们发布一个更新：
```sh
$ eas update --channel development --message "Change first button label"
```
在上述命令中，我们使用了 `development` channel。每次更新都与 [channel 名称](/eas-update/how-it-works/#publishing-an-update) 相关联。这类似于我们用 git 进行的每次提交，与一个 git 分支相关联。
因此，通过在我们的构建配置文件中使用 `development` channel，然后发布更新，我们要求 EAS 将此更新发送到具有 `development` channel 的构建。当我们创建 EAS Update channel 时，它自动与同名的分支映射。
更新发布后，CLI 将提示我们有关它的信息。
点击 **Website link** ，在 EAS 仪表盘的 **Over-the-air updates** > **Update groups** 下查看更新：
Step 6: 
## 在开发构建中实时预览更新
要在开发构建中预览实时更新：
- 在开发构建中登录你的 Expo 账号。
- 打开 **Extensions** 标签页。
- 在 **EAS Update** 下查找 **Branch: development**。
- 点击 **Open** 以访问更新。
Step 7: 
## 使用预览或生产构建共享更改
非开发构建（预览或生产）的更新会在应用启动并请求任何新更新时自动下载到设备。
任何运行预览或生产构建的团队成员将收到我们推送到这些特定分支的更新。
例如，对于 `preview` 构建，我们可以运行：
```sh
$ eas update --channel preview --message "Change first button label"
```
这是我们已为 `preview` 构建发布更新的示例。要测试更新，请强制关闭并重新打开应用两次，以下载并查看更改：
## 总结
<ProgressTracker
  currentChapterIndex={9}
  name="EAS_TUTORIAL"
  summary="我们成功配置了 EAS Update，以便跨平台管理和发布无线更新，并探索了获取更新以进行审核的方法。"
  nextChapterDescription="在下一章中，了解如何从 GitHub 存储库触发构建。"
  nextChapterTitle="从 GitHub 存储库触发构建"
  nextChapterLink="/tutorial/eas/using-github/"
/>


## 从 GitHub 存储库触发构建

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

[Expo GitHub App](/build/building-from-github/) 自动从我们的 GitHub 项目中与 EAS 触发构建。我们可以根据开发团队的偏好为任何构建配置触发构建。它还允许为直接提交到存储库或拉取请求的 `git` 推送触发构建。
在本章中，我们将配置此功能。我们已经有一个 GitHub 存储库用于演示我们的示例应用。
Video Tutorial: [观看：如何从 GitHub 存储库触发构建](https://www.youtube.com/watch?v=fBLFEFC0ip0)
---
Step 1: 
## 配置 Expo GitHub 应用
要使用此功能，我们需要连接我们的 GitHub 账户：
- 在 EAS 仪表板中，转到 [expo.dev/settings](https://expo.dev/settings#connections)，在 **Connections** > **GitHub** 下，单击 **Connect**。这将打开 **Connect GitHub** 账户页面。
- 单击 **Get started** 按钮，这将打开授权 Expo GitHub 应用的弹出窗口。单击 **Install and Authorize**。
- 一旦该应用安装在我们的 GitHub 账户上，我们需要将其链接到我们的 Expo 账户。在下一个弹出窗口中，单击 **Link installation**。
- 一旦账户链接，它将在 **GitHub** 下显示。
Step 2: 
## 连接 GitHub 存储库
要启用从 GitHub 存储库触发构建，我们需要将其连接到 EAS 仪表板中的项目：
- 在 EAS 仪表板中，转到 **Projects** > 选择您的项目 > **Project settings** > **GitHub**。
- 在 **连接 GitHub 存储库** 下，我们将看到我们的 GitHub 存储库列表。我们需要连接正确的一个。在示例中，我们正在寻找我们的存储库 **sticker-smash**。
- 单击项目存储库的 **Connect**。
Step 3: 
## 使用默认存储库设置
Expo GitHub 应用需要知道在哪里找到我们项目的源代码。默认情况下，它使用 `/` 选择根目录。在我们的示例项目中，源代码也可在根存储库中找到。我们可以将其保留为默认设置。
Step 4: 
## 使用 GitHub PR 标签触发构建
Expo GitHub 应用为我们提供了[多种选项](/build/building-from-github/#trigger-a-build-from-github) 来触发构建，例如：
- 从特定平台的构建页面手动触发
- 当新代码推送到存储库时自动触发
- 使用 GitHub PR 标签自动触发
要使用 GitHub PR 标签自动触发构建，我们将利用上面列表中的第三个选项：
- 我们需要指定将要使用的构建映像。打开 **eas.json**，在 `development` 配置下，添加 [`android.image`](/eas/json/#image) 和 [`ios.image`](/eas/json/#image-1) 属性，并将它们的值设置为 [`latest`](/build-reference/infrastructure/#configuring-build-environment)。
  ```json eas.json
  {
    "build": {
      "development": {
        "android": {
          "image": "latest"
        },
        "ios": {
          "image": "latest"
        }
      }
    }
  }
  ```
- 接下来，让我们创建一个名为 `dev` 的新分支，并更改应用的 JavaScript 代码。然后，提交更改，推送分支，并从该分支创建 PR。
- 在 PR 链接下的 **Labels** 中，创建一个名为 `eas-build-all:development` 的标签。
- 单击 **Create pull request** 按钮以创建 PR。Expo GitHub 应用将开始创建开发构建的过程。
- 在 EAS 仪表板的 **Builds** 页面上，我们可以验证 Android 和 iOS 的构建是否被触发。
- 如果我们查看单个构建的详细信息，我们可以在 **Created by** 下看到该构建是由 GitHub 应用创建的。
## 小结
<ProgressTracker
  currentChapterIndex={10}
  name="EAS_TUTORIAL"
  summary="我们成功将 GitHub 账户与 Expo 连接，将存储库连接到我们的 EAS 项目，并了解了如何使用 GitHub PR 标签自动创建开发构建。"
  nextChapterDescription="了解使用 EAS 的下一步步骤。"
  nextChapterTitle="您与 EAS 的旅程中的下一步"
  nextChapterLink="/tutorial/eas/next-steps/"
/>


## 下一步

了解您在 EAS 旅程中的下一步。

恭喜您！您已完成 EAS 教程，并了解了主要功能。现在，您有一个正在运行的 [EAS 项目](https://expo.dev/eas)。
## EAS
但这仅仅是个开始。以下是一些下一步，以继续您的 EAS 旅程：
  }
  href="/eas-insights/introduction/"
/>
## eas.json 参考
## 自定义构建
## 相关指南
我们希望您喜欢本课程。如果您有任何问题或反馈，请随时通过 [Discord](https://chat.expo.dev/) 联系我们，或在 [X](https://x.com/expo) 上分享您的经验。


# 更多

## 额外资源

## 指南：概述

本节包含有关使用 Expo 和 Expo 应用服务 (EAS) 的开发信息：
### <span className="inline-flex items-center gap-2"><CodeSquare01Icon />开发过程</span
了解 [使用 Expo 构建应用程序](/workflow/overview/) 的过程，以帮助理解核心开发循环的思维模型。本节还深入探讨了您在开发过程中可能需要的其他配置和工作流程，以帮助您开发、部署和维护应用程序。它包含有关 [应用配置](/workflow/configuration/) 、 [权限](/guides/permissions/) 、 [通用链接](/linking/into-your-app/) 、 [自定义原生代码](/workflow/continuous-native-generation/) 、 [网页](/workflow/web/) 等的深入信息。
### <span className="inline-flex items-center gap-2"><RouterLogo />Expo Router</span
了解如何使用 [Expo Router](/router/basics/layout/#root-layout) 库中的不同导航功能。它还涵盖了该库提供的全面 [Hooks API](/router/reference/hooks/) 以及导航的其他方面，如[身份验证](/router/reference/authentication/) 、 [重定向](/router/reference/redirects/) 、 [测试](/router/reference/testing/)等。
### <span className="inline-flex items-center gap-2"><CpuChip01Icon />Expo Modules API</span
了解如何使用 [Expo Modules API](/modules/overview/) 在您的应用中添加和使用原生模块。
### <span className="inline-flex items-center gap-2"><GraduationHat02DuotoneIcon />教程</span
如果您正在寻找 Expo 和 EAS 的逐步教程，请查看 [教程部分](/tutorial/overview/) ，其中包括有关 [使用 Expo 构建应用程序](/tutorial/introduction/) 和 [使用 EAS 服务](/tutorial/eas/introduction/) 的全面教程。
### 其他内容
除了上述基本内容，还有许多其他功能可供探索，例如 [推送通知](/push-notifications/overview/) 。我们在 **杂项** 和第三方 **集成** 部分也有一系列指南。


# 开发流程

## 使用Expo开发应用程序

构建 Expo 应用程序的开发流程概述，旨在帮助建立核心开发循环的思维模型。

如果你是 Expo 和 React Native 的新手，或者你在这个生态系统中待了一段时间，这份文档将对你理解构建 Expo 应用的开发过程非常有帮助。它将帮助你建立核心开发循环的思维模型，以及 Expo 工具如何融入其中。
## 关键概念
以下概念非常重要，我们建议在阅读本指南的其余部分以及使用 Expo 工具时，参考这些定义。
Note: 什么是 Expo 应用?
---
这是我们用来描述*使用 Expo 工具的 React Native 应用*的简写术语。“Expo 应用”可以使用 Expo SDK 中的单个包，或 Expo Router，或 Expo CLI，或 Continuous Native Generation，或它们的组合，或任何其他 Expo 工具。
我们称之为“Expo 应用”，因为*使用 Expo 工具的 React Native 应用*频繁输入和大声说出非常不方便。
<Collapsible summary={<>“Expo 应用”和“<span><i>不</i></span>使用 Expo 工具的 React Native 应用”的开发过程是否不同？</>}>
Expo 提供了多种可以独立使用的工具和服务，因此答案取决于您选择使用哪些工具。对于 Expo 提供的大多数功能，Meta 并没有提供可比的 React Native 工具。
---
---
Note: Expo 和 Expo 应用服务 (EAS) 之间有什么区别？
---
Expo 是一个开源项目，为开发者提供强大的工具，以帮助构建和维护任何规模的 React Native 应用。例如，Expo CLI、Expo Router 和 Expo SDK 包。所有 Expo 开源工具都是完全免费的，并且采用 MIT 许可证。
Expo 应用服务 (EAS) 是一套托管服务，您可以在 Expo 和 React Native 项目中使用它来：
- 构建、提交和更新您的应用
- 围绕所有这些流程设置自动化
- 与您的团队协作
EAS 解决了一系列需要物理资源的问题，例如应用服务器和 CDN 用于提供空中更新，以及用于运行构建的物理服务器。EAS 提供了一个慷慨的 [免费计划](https://expo.dev/pricing#get-started) ，适合许多学生和爱好项目。
您不必使用 GitHub 来使用 git，但在许多情况下这确实有帮助。EAS 和 Expo 也是如此。
不！您的 Expo 项目只是一个 React Native 应用程序，它只是一个原生应用程序。您可以使用 Fastlane 或任何您喜欢的原生构建、更新等工具。
大多数 EAS 服务还允许您在自己的基础设施上运行它们，我们提供了如何实现这一点的说明。例如， [自托管更新](/versions/latest/sdk/updates/) （而不是使用 EAS Update），或 [在本地运行构建](/guides/local-app-development/) 或在 [您自己的 CI](build/building-on-ci/) 上运行（而不是使用我们的 EAS Build 工作队列）。
对于大多数团队来说，使用 EAS 比花费工程时间和资源在其他基础设施上获取、设置和维护服务更有意义。此外，EAS 提供了服务之间的深度集成，例如用于监控应用版本采用情况的部署页面，将更新分配给特定构建，并逐步推出这些更新——这与 [EAS Insights](/eas-insights/introduction/) 的监控相结合。
是的！我们认为 EAS 非常适合任何 React Native 项目。
没有比 [Expo Go](https://expo.dev/go) 更快的方法来启动一个 React Native 项目并在您的设备或模拟器上运行它，尤其是与 [Snack](https://snack.expo.dev/) 结合使用时。
然而，**Expo Go 和 Snack 并不适合构建生产应用** 。它们在您开始一个项目或制作原型时非常好。 **如果您计划将应用部署到商店，那么 [开发构建](#development-builds) 将提供更灵活、可靠和完整的开发环境。** 本指南没有详细介绍 Expo Go，这也是唯一提到它的部分。
开发构建是您应用的调试构建，包含 `expo-dev-client` 库。它帮助您尽可能快速地迭代，并提供比 Expo Go 更灵活、可靠和完整的开发环境。您可以安装任何原生库，并使用 [应用配置](/workflow/configuration/) 或通过创建 [配置插件](/config-plugins/introduction/) 来配置或应用更改到 [原生项目](#android-and-ios-native-projects) 。您可以 [本地](/guides/local-app-development/#local-builds-with-expo-dev-client) 创建开发构建，或使用 [EAS Build](/develop/development-builds/create-a-build/) 在云中创建构建。
移动平台的 React Native 应用由两个相互关联的部分组成：
这部分包含您的 React 组件和您应用的大部分（如果不是全部的话）逻辑。它在 React 网站上与应用 JavaScript 的角色大致相同。
Android 和 Xcode 项目将 JavaScript 应用程序打包，作为每个平台上 JavaScript 应用程序的启动平台。它们还处理本地组件的渲染，并提供访问特定平台功能和与任何已安装的本地库集成的手段。应用程序配置，例如名称（在主屏幕上显示的名称）、图标、所需权限、关联域、支持的方向等，均在本地项目中配置。
与任何移动应用程序一样，分发给用户的应用程序是通过编译（“构建”）Android Studio 或 Xcode 项目创建的。
当您使用 `npx create-expo-app` 初始化一个新应用时，您将看不到任何 **android** 或 **ios** 目录。您可以通过运行 [`npx expo prebuild` 来生成本地项目](/workflow/prebuild/) ，这将初始化本地项目，然后将项目 Expo 应用配置（**app.json/app.config.js**）应用于它们。
如果您使用基于云的开发工作流程，您可能永远不需要在自己的机器上运行预构建或安装 Android Studio 或 Xcode（尽管您可能会发现这很有用）。这在[本地和基于云的开发工作流程](#cloud-based-and-local-development-workflows)中有详细说明。
Note: 为什么在使用 create-expo-app 初始化项目时默认不会创建本地项目？
---
默认行为鼓励使用[持续本地生成](/workflow/continuous-native-generation/) （CNG）在需要时生成本地项目，这可以使升级和项目维护变得更加容易。以下三个命令产生的项目大致相同：
```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)
---
连续原生生成（CNG）是构建 Expo 应用的一个过程，在该过程中，您的 [原生项目](#android-and-ios-native-projects) 是根据您的 **app.json** 和 **package.json** 按需生成的，类似于您的 **node_modules** 是如何从 **package.json** 生成的。
当您创建新项目时， [原生项目](#android-and-ios-native-projects) 目录（**android** 和 **ios**）会自动添加到您的 **.gitignore** 中，您可以随时删除它们，然后在需要时通过 `npx expo prebuild` 从 Expo 应用配置中重新生成它们。如果您使用基于云的开发工作流程，您甚至可能从未在自己的开发机器上运行过 prebuild。
Note: What if I want to edit the native project configuration in Android Studio or Xcode rather than generating the projects with prebuild?
---
使用 CNG 可以使升级到新版本的 React Native 变得更加容易。它可以简化项目维护，并促进设置复杂功能，例如 [App Clips](https://github.com/bndkt/react-native-app-clip)、 [分享扩展](https://github.com/timedtext/expo-config-plugin-ios-share-extension) 和 [推送通知](https://github.com/OneSignal/onesignal-expo-plugin) 。这一切都得益于 [配置插件](/config-plugins/introduction/) 。了解更多关于 [CNG](/workflow/continuous-native-generation/) 的信息。
CNG 已被证明对许多团队有帮助。然而，它可能并不适合您的项目，在许多情况下，使用 Expo 工具是完全合理的方式。
您可以在项目中运行 `npx expo prebuild`，然后直接对 **android** 和 **ios** 目录进行更改，而不是使用 Expo 应用配置。如果您决定这样做，请记住，您将无法再使用 prebuild 重新生成您的项目——在直接进行本地更改后运行 prebuild 将覆盖所有这些修改。
请注意，您可以使用 [配置插件](/config-plugins/introduction/) 来修改本地项目配置，而无需直接修改本地项目，如果您决定在某个时候回到 CNG。
如果您向项目添加了新的本地依赖项或在 Expo 应用配置中更改了项目配置 (**app.json/app.config.js**)，您可以运行 `npx expo prebuild --clean` 来重新生成本地项目目录。
有关如何确定新依赖项是否需要本机代码更改的更多信息，请参见[确定第三方库兼容性](/workflow/using-libraries/#determining-third-party-library-compatibility) 。
---
---
Note: Cloud-based and local development workflows
---
无论您选择基于云的还是本地的，都不会显著改变您的开发循环。关键在于您如何生成和分发您的应用程序二进制文件，以便您的 JavaScript 代码可以运行。选择基于云的或本地的开发是您每次运行新的本机构建时可以做出的选择。
在云中使用 EAS Build 编译您的应用程序就像运行一个命令一样简单，无需安装 Android Studio 或 Xcode。云构建使得与其他团队成员或利益相关者共享您的应用程序变得更加容易， [还有其他好处](/build/introduction/) 。
要在本地编译您的应用程序，您需要在您的机器上安装 Android Studio 和 Xcode，然后您可以从这些工具中运行构建，或者使用 `npx expo run:[android|ios]`。当您想要使用本机调试工具在物理设备或模拟器/仿真器上调试您的应用程序时，这最为有用。
了解更多关于[基于云的工作流程与 EAS Build](/build/introduction/) 和[本地开发](/guides/local-app-development/)的信息。
---
## 初始化并运行一个项目
创建新项目的最简单方法是[使用 `create-expo-app`](/get-started/create-a-project/)。创建项目后，您可以立即在物理设备上的 Expo Go 中直接启动它，或者在模拟器/仿真器中启动，如果您想进行实验或构建快速原型。
在大多数情况下，您将创建并使用项目的开发版本。您将安装 [`expo-dev-client`](/develop/development-builds/introduction/#what-is-expo-dev-client) 库。开发版本可以通过 EAS Build 创建，也可以在您的机器上本地创建：
## 核心开发循环
上面图中描述的核心开发循环是一个包含四个主要活动的周期，这些活动是您在开发应用时通常会经历的。
- #### 编写并运行 JavaScript 代码
  这涉及到创建组件、编写业务逻辑或从 npm 安装不需要本地代码更改的库。您在这里所做的更改会在您的应用中反映出来，而无需与应用的本地部分进行任何交互。
- #### 更新应用配置
  这涉及使用应用配置文件（**app.json** 或 **app.config.js**）修改您的应用配置。它包括更新应用的名称、图标、启动画面和其他属性。这些更改并不都直接影响原生项目。然而，如果您进行的更改影响原生项目，您可以使用[应用配置](/workflow/configuration/)来修改原生项目配置，或创建或使用[配置插件](/config-plugins/introduction/) 。有关应用配置文件中可用属性的完整列表，请参见[应用配置参考](/versions/latest/config/app/) 。
- #### 编写原生代码或修改原生项目配置
  这包括直接编写原生代码或修改原生代码配置。您需要访问原生代码项目目录以进行这些更改，或者您可以使用[本地 Expo 模块](/modules/get-started/#adding-a-new-module-to-an-existing-application)编写原生代码。
- #### 安装需要本地代码修改的库
  这意味着一个库需要对本地代码项目配置进行更改。要么库提供配置插件，要么提供更新应用配置的步骤。与之前的活动一样，这也要求您创建一个开发构建。
在创建[开发构建](#development-builds)时，您有两个选项。您可以使用 [EAS Build](/build/setup/) 创建基于云的构建，或者在本地进行。如果您选择在本地进行，您可以使用 [CNG](#continuous-native-generation-cng)，然后 [`npx expo prebuild --clean`](#how-do-i-know-when-i-need)，或者您可以使用 [`npx expo run android|ios`](/guides/local-app-development/#local-app-compilation)或 Android Studio 和 Xcode 创建开发构建。
> **注意** : 在本地创建开发构建时，`npx expo run` 命令将在构建应用之前生成本地目录。如果在第一次构建后修改了项目的配置或本地代码，则需要重新构建项目。再次运行 `npx expo prebuild` 会将更改叠加在现有文件之上。构建后可能会产生不同的结果。为避免这种情况，请将本地目录添加到项目的 **.gitignore** 中，并使用 `npx expo prebuild --clean` 命令。
在应用的开发循环中，您还可以在同一设备上 [安装不同版本（开发、预览或生产）](/build-reference/variants/) 的应用。
开发循环的另一个关键部分是调试。有关调试应用的更多信息，请参见 [调试运行时问题](/debugging/runtime-issues/) ，并了解不同的 [调试工具](/debugging/tools/) 。
## 与测试人员共享应用
开发应用程序的下一步是与团队、测试人员共享您的应用程序，或在多个测试设备上运行它。传统的方法是将应用程序的二进制文件上传到 Google Play Beta（Android）或 TestFlight（iOS）。这可能是一个耗时的工作，并且一次只能有一个活动构建（例如，在 TestFlight 的情况下）。
如果您使用 EAS Build，我们建议您查看 [内部分发](/build/internal-distribution/) 以了解更多关于共享您的应用程序进行测试的信息。
如果您在本地编译应用程序，可以创建 [本地生产构建](/guides/local-app-production/) 。
## 将应用程序发布到商店
要在应用商店发布您的应用，您可以使用 [EAS Submit](/submit/introduction/)。有关使用 EAS Submit 的更多信息，请参见 [提交到 Google Play 商店](/submit/android/) 和 [提交到 Apple App Store](/submit/ios/)。
要在本地创建生产构建，请参阅 [指南](/guides/local-app-production/) ，然后按照应用商店指南提交您的应用。
## 监控生产中的应用
监控您的生产应用有两种方式：崩溃报告和分析。崩溃报告帮助您了解用户在使用您的应用时遇到的异常或错误。您可以使用 [Sentry](/guides/using-sentry/) 或 [BugSnag](https://docs.bugsnag.com/platforms/react-native/expo/) 来启用崩溃报告。
分析功能允许您跟踪用户与您的应用程序的互动。请参阅[分析概述](/guides/using-analytics/)以了解有关 Expo 和 React Native 生态系统中可用服务的更多信息。
## 更新应用程序
`expo-updates` 库允许您以编程方式将应用程序的 JavaScript 的即时更新提供给您的生产应用程序。
您可以使用 [EAS Update](/eas-update/introduction/)，它为 React Native 应用程序提供一流的即时更新支持。它从全球 CDN 的边缘提供更新，并使用现代网络协议，如 HTTP/3，供支持的客户端使用。它还[专为使用 EAS Build 的开发者量身定制](/eas-update/develop-faster/) 。您也可以将其用于您[本地](/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 Prebuild](/workflow/prebuild) 生成、项目在 [Expo Go](/get-started/expo-go/) 中的加载方式，以及 OTA 更新清单。
它必须位于项目的根目录，与 **package.json** 在同一目录下。以下是一个最小示例：
```json app.json
{
  "name": "My app",
  "slug": "my-app"
}
```
如果您的 Expo 配置有一个顶层 `expo: {}` 对象，则将使用此对象替代根对象，所有其他键将被忽略。
## 属性
应用程序配置配置了许多内容，例如应用程序名称、图标、启动画面、深度链接方案、用于某些服务的 API 密钥等。有关可用属性的完整列表，请参见 [app.json/app.config.js/app.config.ts 参考](/versions/latest/config/app/) 。
> **info** 您使用 Visual Studio Code 吗？如果是，我们建议您安装 [Expo Tools](https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools) 扩展，以便在 **app.json** 文件中获得属性的自动补全。
## 在您的应用程序中读取配置值
应用配置中的大多数配置可以在运行时通过您的 JavaScript 代码访问，使用 [`Constants.expoConfig`](/versions/latest/sdk/constants/#nativeconstants--properties)。您**不应**在应用配置中包含任何敏感信息（有一些例外，具体字段将在下面说明）。
您可以通过运行 `npx expo config --type public` 来验证哪些配置将嵌入到您的构建/更新中并在运行时可用。
Note: 哪些字段会被过滤出公共应用程序配置？
---
以下字段已从公共应用配置中过滤（并且无法通过 `Constants.expoConfig` 对象访问）：
- [`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** 您还应该避免在 JavaScript 代码中直接导入 **app.json** 或 **app.config.js**，因为这将导入整个文件，而不是其处理后的版本。相反，请使用 [`Constants.expoConfig`](/versions/latest/sdk/constants/#nativeconstants--properties) 来访问配置。
## 扩展配置
库作者可以通过使用 [Expo 配置插件](/config-plugins/introduction/) 来扩展应用程序配置。
> **info** 配置插件主要用于配置 [`npx expo prebuild`](/workflow/prebuild) 命令。
## 动态配置
为了更好的自定义，您可以使用 JavaScript (**app.config.js**) 或 [TypeScript](#using-typescript-for-configuration-appconfigts-instead-of-appconfigjs) (**app.config.ts**)。这些配置具有以下属性：
- 注释、变量和单引号。
- 不支持 ESM 导入语法（`import` 关键字），除非使用 [TypeScript 和 `tsx`](/guides/typescript/#appconfigjs)。与您当前版本的 Node.js 兼容的 JS 文件可以使用 `require()` 导入。
- TypeScript 支持空值合并和可选链。
- 每当 Metro 打包器重新加载时更新。
- 向您的应用提供环境信息。
- 不支持 Promises。
例如，您可以导出一个对象来定义您的自定义配置：
```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',
  },
};
```
键 `"extra"` 允许将任意配置数据传递给您的应用。此键的值可以使用 [`expo-constants`](/versions/latest/sdk/constants/) 访问：
```js App.js
import Constants from 'expo-constants';
Constants.expoConfig.extra.fact === 'kittens are cool';
```
您可以通过导出一个返回对象的函数来访问和修改传入的配置值。如果您的项目还有一个 **app.json**，这将非常有用。默认情况下，Expo CLI 将首先读取 **app.json** 并将标准化的结果发送到 **app.config.js**。
例如，您的 **app.json** 可能看起来像这样：
```json app.json
{
  "name": "My App"
}
```
在你的 **app.config.js** 中，你可以在导出函数的参数中找到该配置：
```js app.config.js
module.exports = ({ config }) => {
  console.log(config.name); // prints 'My App'
  return {
    ...config,
  };
};
```
### 基于环境切换配置
在开发、预发布和生产环境中，通常会有一些不同的配置，或者完全更换配置以进行应用的白标化。为此，您可以使用 **app.config.js** 以及环境变量。
```js app.config.js
module.exports = () => {
  if (process.env.MY_ENVIRONMENT === 'production') {
    return {
      /* your production config */
    };
  } else {
    return {
      /* your development config */
    };
  }
};
```
要使用此配置与 Expo CLI 命令，请为特定命令或在您的 shell 配置文件中设置环境变量。要为特定命令设置环境变量，请在命令前加上变量和值，如下例所示：
```sh
$ MY_ENVIRONMENT=production eas update
```
这并不是 Expo CLI 独有的。在 Windows 上，你可以用以下命令近似实现：
```sh
$ npx cross-env MY_ENVIRONMENT=production eas update
```
或者你可以使用任何你熟悉的环境变量机制。
### 使用 TypeScript 进行配置：app.config.ts 而不是 app.config.js
您可以在 TypeScript 中使用 Expo 配置的自动完成功能和文档块。创建一个 **app.config.ts**，内容如下：
```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/) 。
### 配置解析规则
有两种不同类型的配置：静态（**app.config.json**，**app.json**）和动态（**app.config.js**，**app.config.ts**）。静态配置可以通过 CLI 工具自动更新，而动态配置必须由开发者手动更新。
1.  如果存在 **app.config.json**，则读取静态配置（回退到 **app.json**）。如果没有静态配置，则从 **package.json** 和你的依赖项中推断默认值。
2.  如果存在 **app.config.ts** 或 **app.config.js**，则读取动态配置。如果两者都存在，则使用 TypeScript 配置。
3.  如果动态配置返回一个函数，则静态配置将通过 `({ config }) => ({})` 传递给该函数。这个函数可以修改静态配置的值。可以将其视为静态配置的中间件。
4.  动态配置的返回值用作最终配置。它不能包含任何 Promise。
5.  在 Expo 生态系统中的任何工具使用配置之前，所有配置中的函数都会被评估和序列化。配置在托管时必须是 JSON 清单。
6.  如果最终配置对象具有顶层 `expo: {}` 对象，则将使用该对象替代根对象，所有其他键将被忽略。
运行 `npx expo config` 将显示在解析完成后将在 Expo CLI 中使用的最终配置。


## 连续原生生成 (CNG)

了解如何使用连续原生生成 (CNG) 和 Prebuild 管理您的原生项目。

单个原生项目本身在维护、扩展和更新方面是复杂的。在跨平台应用中，您有多个原生项目，必须保持它们的维护，并与最新的操作系统发布保持同步，以避免在任何第三方依赖项上落后太多。
随着您的原生项目的增长，来自第三方依赖项的复杂性增加，升级变得复杂，并减缓了开发人员的进展。这会阻碍高级原生功能的添加，导致应用程序的功能下降。在跨平台应用中，这种复杂性在每个平台上都被乘以。
为了应对这一点，我们引入了**连续原生生成**的概念。与其一次性创建原生项目并在整个代码库生命周期内维护这些原生项目的自定义，短期的原生项目仅在需要时生成，例如在调试或构建时。这些项目是从标准模板以及定义如何自定义模板的配置或自定义代码生成的。结果是一个可以编译成原生应用的原生项目，开发人员可以根据需要进行任何自定义。然而，开发人员仅需维护其自定义的定义，而不是所有原生项目代码。
## CNG 在 React Native 应用中的应用
React Native 应用可以通过使用 [Prebuild](#usage) 来自动化升级、安装或卸载库、应用白标自定义、在多个应用之间共享配置、减少 [孤立代码](#how-does-prebuild-help-with-orphaned-code) 等来使用 **CNG**。
**Expo 作为框架** 通过结合以下工具启用 CNG：
1. [app config](/workflow/configuration/) 文件。
2. 传递给 `npx expo prebuild` 命令的参数。
3. 项目中安装的 `expo` 版本及其对应的 [prebuild 模板](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)。
5. 原生订阅者，用于减少入口点文件（如 **MainApplication** 或 **AppDelegate**）中的原生代码副作用。
6. EAS 凭据，用于对额外目标和授权进行代码签名。
最终结果是一个工作流程，开发人员可以使用应用配置表达任何原生应用，并通过运行 `npx expo prebuild` 进行持续生成。
## 用法
Prebuild 可以通过运行以下命令来使用：
```sh
$ npx expo prebuild
```
这会创建用于运行您的 React 代码的 **android** 和 **ios** 目录。如果您手动修改生成的目录，则在下次运行 `npx expo prebuild --clean` 时您可能会丢失更改。相反，使用 [config plugins](/config-plugins/introduction/)，这些函数在预构建期间对原生项目执行修改。
我们强烈建议出于 [常见问题](#prebuild) 部分列出的理由使用 Prebuild，但该系统是 [完全可选的](#optionality)，您可以随时停止使用它。
### 与 EAS Build 的用法
如果您的项目不包含 **android** 和 **ios** 目录，EAS Build 将运行 Prebuild 以在编译之前生成这些原生目录。这是使用 `npx create-expo-app` 创建的任何项目的默认行为。
对于具有 **android** 和 **ios** 目录的项目，EAS Build 不会运行 Prebuild，以避免覆盖您对原生目录所做的任何更改。
如果通过 [本地编译](/guides/local-app-development/#local-app-compilation) （运行 `npx expo prebuild`，或 `npx expo run:android` 或 `npx expo run:ios`）来排除您的应用故障，您仍然可以使用 Prebuild 与 EAS Build 在构建过程中生成新的原生目录。创建新项目时，**android** 和 **ios** 目录会自动添加到 **.gitignore** 中，但如果您需要手动添加它们，您可以将它们添加到 **.gitignore** 或 [**.easignore**](/build-reference/easignore/) 文件中：
```diff
diff --git a/.gitignore b/.gitignore
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,2 @@
+/android
+/ios
```
### 与 Expo CLI 运行命令的用法
您可以通过运行以下命令在本地执行原生构建：
```sh
$ npx expo run:android
$ npx expo run:ios
```
如果原生目录缺失，`npx expo prebuild` 将为特定平台运行一次。在后续使用这些 `run` 命令时，手动运行 `npx expo prebuild --clean` 以确保原生代码与您的本地配置保持新鲜同步。
## 平台支持
Prebuild 目前支持 Android 和 iOS。因为网页无需为网页生成原生项目，所以不需要 Web 支持，并且 Web 应用程序在浏览器中运行。使用 `--platform` 选项为单个平台运行预构建：
```sh
$ npx expo prebuild --platform ios
```
## 依赖项
Prebuild 首先通过与每个 Expo SDK 版本相对应的模板初始化新的原生项目。这还与特定的 React 和 React Native 版本保持一致。当您的项目的 React 和 React Native 版本与指定在 [模板的 **package.json**](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum) 中的预期版本不同时，运行 `npx expo prebuild` 时会看到警告。
您可以使用 `--skip-dependency-update` 选项跳过更改 npm 包版本：
```sh
$ npx expo prebuild --skip-dependency-update react-native
react
```
## 包管理器
当 [依赖项](#dependencies) 更改时，Prebuild 将使用当前项目中使用的包管理器重新安装库（这是从锁文件中推断的）。您可以通过提供 `--npm`、`--yarn`、`--pnpm` 中的一个来强制使用特定的包管理器。
通过传递 `--no-install` 命令，可以跳过所有安装，这对于快速测试生成非常有用。
## 清理
`--clean` 选项会在生成之前删除任何现有的原生目录。在没有 `--clean` 选项的情况下重新运行 `npx expo prebuild` 将在现有文件上叠加更改，这样更快，但在某些情况下可能不会产生相同的结果。
例如，一些配置插件不是幂等的。当一个项目利用多个“危险修改器”向应用程序的代码添加正则表达式更改时，可能会导致意外行为。这就是为什么使用 `--clean` 选项是使用预构建命令最安全的方法，并且在大多数情况下通常推荐。
#### 使用 `--clean` 选项
当使用 `--clean` 选项时，如果您的 git 代码库中有任何未提交的更改，您将会收到警告，因为此选项将删除并重新创建您所有的原生项目文件。在 CI 中遇到时，这个提示是可选的，并将被跳过。您可以通过启用环境变量 `EXPO_NO_GIT_STATUS=1` 来禁用此检查。
在某些情况下，开发人员可能希望经常在工作流程之间切换。例如，您可能想在 Android Studio 和 Xcode 中原生构建自定义功能，然后将该功能移入本地配置插件。
## 模板
您可以通过 [config plugins](/config-plugins/introduction) 自定义生成原生目录的方式。许多配置插件已经存在，以进行很多修改，社区库通常会自己提供插件。您可以 [查看一些流行插件的列表](https://github.com/expo/config-plugins) 以获取更多信息。
Prebuild 从模板文件开始，随后通过配置插件进行修改。模板文件基于 Expo SDK 版本，并来自 npm 包 [`expo-template-bare-minimum`](https://github.com/expo/expo/tree/main/templates/expo-template-bare-minimum)。您可以通过向 `npx expo prebuild` 命令传递 `--template /path/to/template.tgz` 来更改使用的模板。这通常并不推荐，因为 `@expo/prebuild-config` 中的基本修改器对模板文件做了某些不记录的假设，因此维护您的自定义模板可能会很棘手。
> **注意：** 在所有包都从私有注册表下载且阻止对 npm 公共注册表访问的网络环境中，必须将本地可用的模板传递给预构建命令。[了解有关使用默认模板的本地版本的更多信息](https://expo.fyi/prebuild-without-npm-access)。
## 副作用
`npx expo prebuild` 在生成 **android** 和 **ios** 目录之外会执行几个副作用。正在进行工作以消除这些副作用 — 理想情况下，运行 `npx expo prebuild` 将生成 Android 和 iOS 项目，并保持项目的其余部分不变。
除了生成原生目录外，prebuild 还会进行以下修改：
- 修改 **package.json** 中的 `scripts` 字段，替代 `expo start --android` 和 `expo start --ios`，使用 `expo run:android` 和 `expo run:ios`
- 修改 **package.json** 中的 `dependencies` 字段
对 `scripts` 字段的便利更改是唯一改变开发人员在预构建前后工作的副作用。所有其他更改可以保留并提交到 git，以最小化运行预构建时的差异。
## 可选性
Prebuild 是可选的，并与所有 Expo 工具和服务无缝集成。对于那些手动管理原生项目的现有 React Native 项目，请不要使用 `npx expo prebuild`，因为这可能会覆盖任何手动自定义。开发人员可以继续对他们的原生项目进行（直接修改）(/more/glossary-of-terms/#bare-workflow)，同时采用其他 Expo 工具和工作流程。后来，他们可以将他们的手动自定义迁移到应用配置和/或配置插件中，然后采用 CNG。
Expo 提供的一切，包括 [EAS](/eas/)、Expo CLI 和 Expo SDK 中的库，都是为了**完全支持**裸 React Native 项目，因为这是使用 `npx expo prebuild` 的项目支持的最低要求。唯一的例外是 [Expo Go](https://expo.dev/go) 应用，该应用只能加载任意的 React Native 项目，前提是它们包含 Expo Go 运行时中缺失的原生代码的 JavaScript 回退。
## 常见问题
### CNG
Note: CNG 如何帮助项目升级？
---
未使用 **连续原生生成** 的 React Native 开发人员报告称，将他们的应用程序升级到最新版本的 React Native 是库的主要弱点，正如 [React Native 调查 (2022)](https://results.2022.stateofreactnative.com/opinions/#opinions_pain_points) 所示。
使用 CNG 时，升级过程仅涉及升级 npm 依赖项、应用配置，并重新运行 `npx expo prebuild --clean`。
---
Note: React Native 库作者如何采用 CNG？
---
React Native 库作者可以通过几种方式采用 CNG。这取决于他们库的复杂性。以下是几种情况：
- **没有原生代码或配置副作用**：如 `react-native-blurhash` 这样的库没有原生代码或配置副作用，可以无缝集成到 `npx expo prebuild` 中。它们可以依赖 Node 模块解析，无需任何额外配置。
- **有原生代码且安装后无需额外设置**：具有原生代码的库通常可以通过 [Expo 自动链接](/more/glossary-of-terms#autolinking) 自动安装和链接，该链接在构建原生应用之前运行。
- **额外的配置副作用和设置**：需要额外配置副作用的库可以通过为其库创建 [Expo 配置插件](/config-plugins/introduction/) 来采用 CNG。这种方法使库作者能够自动添加权限消息等值到 **Info.plist**，或在 Xcode 项目中注入目标。
- **依赖于原生运行时钩子的库**：依赖于特定原生运行时钩子的库，例如通过 `AppDelegate`、`MainActivity`、`MainApplication` 等拦截初始启动 URL，可以利用 [**生命周期监听器**](/modules/android-lifecycle-listeners/) 在 Expo 模块 API 中。这些生命周期监听器允许通过 Expo 自动链接应用这些运行时钩子，而不是通过修改这些标准原生项目文件，从而消除对配置插件的需求。
许多复杂的库和服务已经通过 Expo Prebuild 支持 CNG，例如 [MapBox](https://github.com/rnmapbox/maps)、[OneSignal](https://github.com/OneSignal/onesignal-expo-plugin)、[Stripe](https://github.com/stripe/stripe-react-native) 和 [React Native Firebase](https://rnfirebase.io/#expo)。
库作者采用 CNG 并不是使用 `npx expo prebuild` 的先决条件。如果库作者尚未采用 CNG，开发人员仍然可以通过创建本地 [配置插件](https://github.com/expo/config-plugins/) 来修改原生生成管道，从而使用 `npx expo prebuild`。这种灵活性使得 CNG 对 React Native 社区内所有开发人员都可及且有利。
---
Note: CNG 限于 React Native 项目吗？
---
不，CNG 是一个多功能模式，可以应用于任何原生项目。虽然 Expo Prebuild 是一个专门为 React Native 项目实现 CNG 的工具，但这个概念本身并不限于此框架。
---
Note: 社区如何使用 CNG？
---
以下是一些将困难的原生功能转换为简单配置文件的社区示例，这使开发人员能够构建更强大的应用，而不妨碍迭代速度：
- [iOS Safari 扩展](https://github.com/andrew-levy/react-native-safari-extension)：在这里，为 iOS 创建 Safari 扩展的过程，这是一项著名的难以实现的功能，简化为几行 JSON。
- [iMessage 贴纸应用](https://github.com/expo/config-plugins/tree/main/packages/ios-stickers)：这个 Expo 配置插件可以从一个 JSON 对象生成整个 iMessage 贴纸应用。
- [跨平台端到端测试](https://github.com/expo/config-plugins/tree/main/packages/detox)：配置原生应用以支持 Detox 的 E2E 测试只需一行。
- [整个 Firebase 套件](https://rnfirebase.io/)：在这里可以看到整个原生 Firebase 套件，从多个 IDE 的多步骤原生配置过程减少到基础的 JSON 配置。
- [跨平台主屏幕小部件](https://github.com/gaishimo/eas-widget-example)：这个 Expo 配置插件可以为 Android 和 iOS 生成主屏幕小部件。
- [通知扩展和代码签名](https://github.com/OneSignal/onesignal-expo-plugin)：这个 Expo 配置插件在 iOS 上生成通知扩展目标，并增强 EAS 凭据服务以保持零配置代码签名正常工作。
- [Apple App Clips](https://github.com/bndkt/react-native-app-clip)：这个 Expo 配置插件将生成 Apple App Clip 的过程从多步骤的过程（涵盖多个目标）缩减为一行 `["react-native-app-clip", { "name": "My App Clip" }]`。
在任何时候，这些功能都可以轻松添加和移除，而没有任何副作用。CNG 使开发人员能够快速实验复杂功能并对其进行迭代，而无需担心项目的长期维护成本或潜在的孤立代码。
---
Note: CNG 是否可以用于 Android 和 iOS 以外的操作系统？
---
绝对可以！CNG 是一个可以应用于任何操作系统的抽象概念。尽管 Expo Prebuild 正式为 Android 和 iOS 实现了 CNG，但它也为开发人员提供了抽象平台支持，以创建对此其他平台的实现。
---
Note: 使用 Expo 是 CNG 的要求吗？
---
根本不是。CNG 是一个开放模式，任何社区都可以采用。我们将这一模式抽象定义，以帮助其他社区了解如何将 CNG 采纳到他们自己的项目中。
---
Note: CNG 与静态站点生成（SSG）等 Web 开发模式相比如何？
---
CNG 与 SSG 共享相似之处，因为它是从一组输入生成项目。然而，CNG 与 SSG 的输出不同。它生成原生运行时代码，而不是静态网站代码。这意味着原生项目是按需生成的，一旦原生项目编译成原生应用，生成的源代码和配置就会被丢弃。
---
Note: 是否可以在现有的棕地项目中使用 CNG？
---
CNG 旨在持续管理原生项目的整个状态。因此，它不适用于现有棕地项目。但是，您可以使用 CNG 生成一个新的原生项目，然后将其集成到现有的棕地项目中。
---
### Prebuild
Expo Prebuild 简化了 CNG 处理。以下是 Prebuild 解决的 React Native 开发周期中的一些问题：
Note: Prebuild 如何帮助实现合理的项目升级？
---
构建原生代码需要熟悉平台的工具，这使得学习曲线陡峭。在跨平台开发中，由于多平台的存在，这种挑战加剧。如果必须在特定平台的原生代码中实现许多功能，那么跨平台工具就没有帮助。
在引导原生应用时，有一些您可能不理解的初始代码和配置。尽管您不负责维护它们，但最终您需要了解这些代码，以安全地升级您的应用。这个挑战往往使开发人员错误地升级或者开始一个新应用，复制现有源代码。
**通过 Prebuild**，升级过程更接近于升级纯 JavaScript 应用。提升 **package.json** 中的版本，重新生成原生项目，您应该准备好继续开发。
---
Note: Prebuild 如何简化跨平台配置？
---
跨平台配置，如应用图标、名称、启动画面等，必须在原生代码中手动实施。这些实现通常在每个平台上相差甚远。
**通过 Prebuild**，跨平台配置在配置插件层面处理，开发人员只需设置一个值，如 `"icon": "./icon.png"`，即可处理所有图标生成。
---
Note: 我该如何管理 Prebuild 的依赖副作用？
---
许多复杂的原生包在安装和 [自动链接](/more/glossary-of-terms#autolinking) 之外需要额外的设置。例如，摄像头库需要将权限设置添加到 **AndroidManifest.xml** 中（用于 Android）和 **Info.plist** 中（用于 iOS）。这种额外的设置可以视为包的配置副作用。将所需副作用代码粘贴到您的项目的原生文件中可能导致难以解决的原生编译错误，而且这也是您现在擅自拥有并维护的代码。
**通过 Prebuild**，库作者比任何人都更了解如何配置他们的库，可以创建一个可测试和版本化的脚本，称为 [配置插件](/config-plugins/introduction/)，以自动添加其库所需的配置副作用。这意味着库的副作用可以更具有表现力、强大和稳定。对于原生代码副作用，我们还提供了默认 [prebuild 模板](#templates) 中标准的 [Android 生命周期监听器](/modules/android-lifecycle-listeners) 和 [AppDelegate 订阅者](/modules/appdelegate-subscribers)。
---
Note: Prebuild 如何帮助解决孤立代码问题？
---
当您卸载一个包时，您必须确保完全删除使该包工作所需的所有副作用。如果您遗漏了任何内容，则会导致孤立代码，您无法追踪到任何特定包，代码会堆积，让您的项目更难理解和维护。
**通过 Prebuild**，唯一的副作用是项目的 Expo 配置中的 [配置插件](/config-plugins/introduction) (**app.json**)，当相应的节点模块已被卸载时，它将抛出错误，这意味着许多孤立配置会大大减少。
---
Note: 何时 Prebuild 可能不适合某个项目
---
以下是 Expo Prebuild 可能**不**适合某个特定项目的一些原因：
#### 平台兼容性
Prebuild 仅可用于 Expo SDK 支持的原生平台。目前仅支持 Android 和 iOS。除了 Web，该平台不需要 `npx expo prebuild`，因为它使用浏览器而不是自定义的原生运行时。
#### 直接更改比模块化和自动化更快
所有原生更改必须与原生模块一起添加（使用 React Native 的内置原生模块 API 或 Expo 模块 API）和配置插件。这意味着如果您想快速向项目中添加原生文件以进行实验，那么您可能会更好地运行预构建，然后手动添加文件，然后逐步找到与 [monorepo](/guides/monorepos) 的系统集成。我们计划通过向 [Expo 自动链接](/more/glossary-of-terms#expo-autolinking) 添加功能，以便在构建之前找到原生项目文件并链接它们，加速此过程。
如果您想修改配置，例如 **gradle.properties** 文件，您需要编写一个插件（[示例](https://github.com/expo/expo/blob/1c994bb042ad47fbf6878e3b5793d4545f2d1208/apps/native-component-list/app.config.js#L21-L28)）。这可以通过帮助插件库轻松实现自动化，但如果您频繁需要执行这项操作，速度会稍慢。
#### 社区对配置插件的支持
并非所有包都已支持 _Expo Prebuild_。如果您发现某个库在安装后需要额外设置但还没有配置插件，我们建议您打开一个 Pull Request 或问题，以便维护者了解此功能请求。
许多包，例如 [`react-native-blurhash`](https://github.com/mrousavy/react-native-blurhash)，不需要超过由 [自动链接](/more/glossary-of-terms#autolinking) 处理的任何其他原生配置，因此不需要配置插件。
其他包，例如 [`react-native-ble-plx`](https://github.com/Polidea/react-native-ble-plx)，确实需要额外设置，因此需要与 `npx expo prebuild` 一起使用配置插件（在这种情况下，有一个外部插件 [`@config-plugins/react-native-ble-plx`](https://github.com/expo/config-plugins/tree/main/packages/react-native-ble-plx)）。
另外，我们还拥有一个 [非树配置插件](https://github.com/expo/config-plugins) 的库，提供尚未采用该系统的流行包的插件。可以将其视为 TypeScript 的 [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped)。我们更倾向于包本身提供它们的配置插件，但如果它们尚未采用该系统，社区仍然可以使用该库中列出的包。
---


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

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

每个应用程序都不可避免地会使用第三方库，因此了解如何判断库是否与项目兼容至关重要。
## React Native 核心库
React Native 提供了一组内置基础组件，这些组件是大多数开发者在应用中必不可少的。其中包括 `<ActivityIndicator>`、`<TextInput>`、`<Text>`、`<ScrollView>` 和 `<View>` 等组件。这些组件在 React Native 文档的 [核心组件与 API](https://reactnative.dev/docs/components-and-apis) 中有详细列举。您也可查看[与 Expo SDK 版本对应的 React Native 版本](/versions/latest)。
要在项目中使用 React Native 组件或 API，请在代码中从`react-native`包导入：
<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>
  );
}
```
## Expo SDK 库
Expo SDK 在 React Native 核心库的基础上进一步扩展，提供了对大量设备和系统功能的访问，例如音频、条码扫描、相机、日历、联系人、视频等。它还集成了其他强大的库，如更新管理、地图服务、OAuth 认证工具等。更多详情请参阅我们如何决定[Expo SDK 的收录内容](https://expo.fyi/whats-in-the-sdk)。
使用 Expo SDK 库时，请在[API 参考文档](/versions/latest/)中查找所需库，或使用文档搜索功能。
<ConfigReactNative>
若您通过 `npx @react-native-community/cli@latest init` 初始化应用且尚未安装 `expo` 包，请参阅[安装 Expo 模块指南](/bare/installing-expo-modules)获取详细说明。
</ConfigReactNative>
每个 API 参考文档顶部均标注平台兼容性标签，用于说明库支持的平台与环境。例如 [`expo-device`](/versions/latest/sdk/device/) 库的平台标签如下所示：
在平台兼容性表格之后，包含库的描述以及安装库的说明部分。例如：
<InstallSection packageName="expo-device" hideBareInstructions />
`npx expo install` 命令会选择与您的项目兼容的库版本，然后使用您的 JavaScript 包管理器（如 npm）进行安装。
接下来，典型的 API 参考包含：
- 若库需要配置插件，则提供配置插件的使用说明。
- 展示库使用方式的代码示例。
- API 章节：列出库的导入方式，随后罗列库提供的钩子、属性、类型、方法及类。
> **注意**：若使用 TypeScript，您可在 TypeScript 兼容的代码编辑器（如 VS Code）中通过自动补全功能查看 API 章节包含的信息。
## 第三方库
### 查找第三方库
[React Native Directory](https://reactnative.directory) 是专为 React Native 构建的可搜索库数据库。若您所需的库未由 React Native 或 Expo SDK 提供，这将是为应用寻找库的首选之地。
在 React Native Directory 之后，[npm 注册库](https://www.npmjs.com/) 是次优选择。npm 注册库是 JavaScript 库的权威来源，但其中列出的库未必都兼容 React Native。React Native 只是众多 JavaScript 编程环境之一（包括 Node.js、网页浏览器、Electron 等），而 npm 收录的库适用于所有这些环境。任何兼容 React Native 的库，在创建[开发构建](/workflow/overview/#development-builds)时均可用于 Expo 项目。但需注意，这些库未必兼容[Expo Go](https://expo.dev/go)应用。
### 第三方库兼容性判断
请使用 Expo [开发构建](/workflow/overview/#开发构建) 构建生产级应用。该构建包含项目运行所需的所有原生代码，是应用发布至 App Store 或 Google Play 前的理想测试方案。您还可包含需要原生项目（**android** 和 **ios** 目录）配置的库。
Expo Go 应用是迈向开发构建的可选过渡方案。开发过程中可快速测试应用，但其未包含支持所有库所需的完整原生代码。访问 **React Native Directory** 网站，通过“✔️ Expo Go”标记可验证库是否兼容 Expo Go。您也可启用[Expo Go 筛选功能](https://reactnative.directory/?expoGo=true)。
判断新依赖项是否会改变原生项目目录时，请检查以下事项：
- 库文件是否包含 **android** 或 **ios** 目录？
- 库的 README 文件是否提及链接操作？
- 库是否要求修改 **android/app/src/main/AndroidManifest.xml** 或 **ios/Podfile** 或 **ios/Info.plist** 以变更项目配置？
- 库是否提供[配置插件](/config-plugins/introduction/)？
**若上述任一问题答案为肯定**，则需[创建开发构建](/develop/development-builds/introduction/)才能在项目中使用该库。
**未在目录中列出？** 您可在 GitHub 上查找项目。简便操作方式为执行 `npx npm-home --github <package-name>`。例如要打开 `react-native-localize` 的 GitHub 页面，请运行：
```sh
$ npx npm-home --github react-native-localize
```
> 若需协助判断库的兼容性，请在 React Native Directory 仓库中创建问题报告，告知我们具体情况。这不仅能帮助您解决当前问题，还能为其他开发者提供便捷的解决方案！
### 安装第三方库
> 我们建议始终使用 `npx expo install` 替代直接执行 `npm install` 或 `yarn add`，因为它能让 [Expo CLI](/more/expo-cli/) 在可能的情况下自动选择兼容的库版本，并提醒您已知的兼容性问题。
确认库与 React Native 兼容后，请使用 [Expo CLI](/more/expo-cli/) 安装该包：
```sh
$ npx expo install @react-navigation/native
```
请务必关注项目官网或 README 文件，获取任何额外的配置和使用说明。您可通过以下命令快速访问 README 文件：
```sh
$ npx npm-home @react-navigation/native
```
如果模块需要额外的原生配置，可通过[配置插件](/config-plugins/introduction/)实现。部分包虽需配置插件但尚未提供，可参考[树外配置插件列表](https://github.com/expo/config-plugins/)。
<ConfigReactNative>
若您的项目不支持[Expo 预构建](/workflow/prebuild)，则无法使用[配置插件](/config-plugins/introduction/)。您可选择[采用 Expo 预构建](/guides/adopting-prebuild)，或通过各模块官网或 README 中的补充配置指南手动设置每个库。
</ConfigReactNative>
若模块未在[Expo Go](https://expo.dev/go)中支持，可创建[开发构建](/develop/development-builds/introduction/)：
### 排除第三方库的版本检查
若您已安装特定版本的第三方库，并希望将其从 `npx expo install`、`npx expo-doctor` 或 `npx expo start` 执行的版本检查中排除，请在 **package.json** 文件中使用 [`expo.install.exclude`](/versions/latest/config/package-json/#exclude) 属性。


## 隐私声明

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

若您使用的原生 iOS 库调用了“受限原因”API，则需配置 iOS 隐私清单文件，声明包含原生代码调用这些 API 的具体原因。
更多详情及“必需原因”API 列表请参阅[Apple 开发者文档](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files)。
> **info** 本指南中的信息和步骤仍在开发中，可能因相关新工具的推出或苹果公司新增要求而变更。
## 什么是隐私清单？
隐私清单是名为 **PrivacyInfo.xcprivacy** 的文件，需包含在 iOS 原生项目中。该文件用于声明应用程序包含调用苹果公司视为敏感的特定 API 的原生代码的原因。
当前涉及的 API 包括访问 UserDefaults、文件时间戳、系统启动时间、磁盘空间及活动键盘。苹果将此视为开放列表，未来可能持续扩展。
## 应用配置中的设置
您可在应用配置的 `expo.ios` 节点下添加 `privacyManifests` 字段，即可包含 iOS 隐私清单文件。
```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 版本对应的最新版本。
<ConfigReactNative>
您可以在基础 Expo 应用中包含 iOS 隐私清单文件，方法是使用 Xcode 创建一个 **PrivacyInfo.xcprivacy** 文件，并将其添加到 iOS 应用目标中。
请遵循[Apple 隐私清单文件指南](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files)创建 **PrivacyInfo.xcprivacy** 文件。
</ConfigReactNative>
您可通过查阅[Apple 开发者文档](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api)来确定`NSPrivacyAccessedAPITypes`和`NSPrivacyAccessedAPITypeReasons`的具体值。
### 为 Expo SDK 包及其他第三方库添加必需的权限理由
目前苹果无法正确解析静态 CocoaPods 依赖项（如 Expo SDK 包及其他生态库）包含的所有 **PrivacyInfo** 文件。您可能需要在应用的 **PrivacyInfo.xcprivacy** 文件或 **app.json** 配置中，为这些依赖项使用的 API 添加必需理由。
所有使用“必需理由”API 的 Expo SDK 包均在包目录中包含 **PrivacyInfo** 文件。以下是`expo-application`库附带的[示例文件](https://github.com/expo/expo/blob/main/packages/expo-application/ios/PrivacyInfo.xcprivacy)。
通常可通过检查目标库在 **node_modules/package_name/ios** 目录下是否存在 **PrivacyInfo.xcprivacy** 文件，来确认第三方库所用 API 的必要性依据。若存在该文件，可查阅其中的 `NSPrivacyAccessedAPITypes` 和 `NSPrivacyAccessedAPITypeReasons` 值，并将这些值复制到你的配置文件中。
另一种方式是：当开发者提交缺少隐私清单文件或特定理由的构建版本后，苹果会向其发送通知。您可等待苹果发送通知邮件，随后将邮件中列出的必要理由添加至应用的 **PrivacyInfo.xcprivacy** 文件（若未使用[CNG](/workflow/continuous-native-generation/)），或添加至 **app.json** 文件的配置中。
## 隐私清单测试
您可通过构建应用并提交至 App Store 审核流程或 TestFlight 外部审核来测试隐私清单。若应用缺少所用 API 的必要理由说明，苹果将在提交后数分钟内发送邮件通知。


## 权限

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

在开发需要访问用户设备上潜在敏感信息的原生应用时，例如用户的位置或联系人，应用必须首先请求用户的权限。例如，要访问用户的媒体库，应用需要运行 [`MediaLibrary.requestPermissionsAsync()`](/versions/latest/sdk/media-library#medialibraryrequestpermissionsasync)。
独立和[开发构建](/develop/development-builds/introduction/)中的权限在请求之前需要进行原生构建时配置，才能使用运行时 JavaScript 代码进行请求。在 [Expo Go](https://expo.dev/go) 应用中测试项目时不需要此配置。
> 如果您没有正确配置或解释原生权限，**可能会导致您的应用被拒绝或从商店下架**。
## 安卓
权限通过 [`android.permissions`](/versions/latest/config/app/#permissions) 和 [`android.blockedPermissions`](/versions/latest/config/app/#blockedpermissions) 键在您的 [应用配置](/workflow/configuration/) 中进行配置。
大多数权限是由您在应用中使用的库自动添加的，使用 [配置插件](/config-plugins/plugins-and-mods/#create-a-plugin) 或包级 **AndroidManifest.xml**。您只需使用 `android.permissions` 来添加库中默认未包含的额外权限。
```json app.json
{
  "android": {
    "permissions": ["android.permission.SCHEDULE_EXACT_ALARM"]
  }
}
```
移除由包级 **AndroidManifest.xml** 文件添加的权限的唯一方法是通过 [`android.blockedPermissions`](/versions/latest/config/app/#blockedpermissions) 属性来阻止它们。为此，请指定 **完整权限名称**。例如，如果您想要移除 `expo-av` 添加的音频录制权限：
```json app.json
{
  "android": {
    "blockedPermissions": ["android.permission.RECORD_AUDIO"]
  }
}
```
- 请参阅 [`android.permissions`](/versions/latest/config/app/#permissions) 了解默认 [预构建模板](/workflow/prebuild#templates) 中包含哪些权限。
- 使用 _dangerous_ 或 _signature_ 权限而没有有效理由的应用 **可能会被 Google 拒绝**。在提交应用时，请确保遵循 [Android 权限最佳实践](https://developer.android.com/training/permissions/usage-notes)。
- [所有可用的 Android `Manifest.permissions`](https://developer.android.com/reference/android/Manifest.permission)。
<ConfigReactNative>
修改 **AndroidManifest.xml** 以排除特定权限：在 `<use-permission>` 标签中添加 `tools:node="remove"` 属性，以确保即使它包含在库的 **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` 属性。
</ConfigReactNative>
## iOS
你的 iOS 应用可以向用户请求系统权限。例如，使用设备的相机或访问照片，Apple 需要对应用如何使用这些数据进行解释。大多数包会自动为给定权限提供一个模板化的原因，使用 [config plugins](/config-plugins/introduction/)。这些默认消息很可能需要根据你应用的具体使用场景进行定制，才能被 App Store 接受。
要设置权限提示信息，请在你在 [app config](/workflow/configuration/) 中使用 [`ios.infoPlist`](/versions/latest/config/app/#infoplist) 键，例如：
```json app.json
{
  "ios": {
    "infoPlist": {
      "NSCameraUsageDescription": "此应用使用相机扫描活动门票上的条形码。"
    }
  }
}
```
这些属性中的许多也可以直接通过与之相关的库的 [config plugin](/config-plugins/introduction/) 的属性来进行配置。 例如，使用 [`expo-media-library`](/versions/latest/sdk/media-library) 时，您可以这样配置照片权限信息：
```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)。
- Apple 官方的[权限消息推荐](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).
<ConfigReactNative>
直接在 **Info.plist** 文件中添加并修改权限值。我们建议直接在 Xcode 中进行，以获得自动补全。
</ConfigReactNative>
## Web
在网页端，像 `Camera` 和 `Location` 这样的权限只能从 [安全上下文](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts#When_is_a_context_considered_secure) 请求。例如，使用 `https://` 或 `http://localhost`。这一限制类似于 Android 的清单权限以及 iOS 的 **Info.plist** 使用提示，并且是为了提升隐私保护而强制执行的。
## 重置权限
通常你希望能够测试当用户拒绝权限时会发生什么，以确保你的应用能优雅地做出反应。Android 和 iOS 的操作系统级别权限限制都禁止应用程序对同一权限请求超过一次（你可以想象在用户拒绝权限后被反复提示权限会有多烦人）。在开发中测试涉及权限的不同流程时，可能需要卸载并重新安装原生应用。
在测试 [Expo Go](https://expo.dev/go) 时，你可以删除应用并通过运行 `npx expo start` 并在 [Expo CLI](/more/expo-cli/) 终端界面中按 <kbd>i</kbd> 或 <kbd>a</kbd> 重新安装。


## Expo 中的环境变量

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

环境变量是在源代码之外配置的键值对，允许你的应用根据环境的不同而表现不同。例如，在构建应用的测试版本时，可以启用或禁用某些功能，或在为生产环境构建时切换到不同的 API 端点。
Expo CLI 将自动从 .env 文件中加载带有 EXPO*PUBLIC* 前缀的环境变量，以在您的 JavaScript 代码中使用，当您使用 Expo CLI 时，例如在本地开发模式下通过 npx expo start 启动应用程序。
## 读取 .env 文件中的环境变量
在项目根目录创建一个 **.env** 文件，并在新行以 `EXPO_PUBLIC_[NAME]=VALUE` 的形式添加环境特定变量：
```bash .env
EXPO_PUBLIC_API_URL=https://staging.example.com
EXPO_PUBLIC_API_KEY=abc123
```
现在你可以在源代码中直接使用环境变量：
```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 或开发构建中点击 Reload）以查看更新后的值。
> **warning** 不要在 `EXPO_PUBLIC_` 变量中存储敏感信息，例如私钥。这些变量将在编译后的应用程序中以明文形式显示。
### 变量加载方式
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** 里的代码不会被影响。
### 如何读取环境变量
- <YesIcon small /> **每个环境变量必须作为属性的静态引用使用 JavaScript 的点记法来对 `process.env`
  进行内联。** 例如，表达式 `process.env.EXPO_PUBLIC_KEY` 是有效的并且会被内联。
- <NoIcon small /> **不支持该表达式的其他版本**。例如， `process.env['EXPO_PUBLIC_KEY']` 或 `const
  {EXPO_PUBLIC_X} = process.env` 无效且将不会 可以内联。
### 使用多个 .env 文件定义不同环境
你可以定义任何 [标准的 .env 文件](https://github.com/bkeepers/dotenv/blob/c6e583a/README.md#what-other-env-files-can-i-use)，因此可以拥有单独的 **.env** 和 **.env.local** 文件，并且它们将按照标准优先级加载。
你可以选择提交默认的 **.env** 文件或其他标准配置，但通常 **.env.local** 文件应添加到你的 **.gitignore**，因为它们用于指定与你的本地机器相关的环境配置（例如，当你需要向本地服务器发出请求时，可能需要的网络 IP 地址等）。
```bash .gitignore
.env*.local
```
#### 环境变量与 `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` 的情况下运行该命令。
在 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 项目，最好不要为此用例再额外重载它。
如果你使用 EAS，考虑改用 `eas env:pull`。这会把你的 **.env.local** 与你选择的环境进行替换，而不是依赖 `NODE_ENV`。你也可以在不使用 EAS 的情况下，通过编写脚本覆盖 **.env.local** 或 **.env**，以获得与你希望工作的环境相匹配的内容，从而实现类似的行为。
### 禁用环境变量
Expo CLI 的环境变量有两个部分，且两者都可以被禁用：
1. Expo CLI 会自动将 **.env** 文件加载到全局进程中。要禁用此行为，请在运行任意 Expo CLI 命令之前将环境变量 `EXPO_NO_DOTENV` 设置为 `1`：`EXPO_NO_DOTENV=1`。
2. Expo 的 Metro 配置在客户端 JavaScript 包中包含环境变量的内联序列化。要禁用此行为，可以使用 `EXPO_NO_CLIENT_ENV_VARS=1`。
如果你在环境变量方面遇到问题，你可以尝试禁用其中一个或这两个功能中的一个或两个。
## Expo 应用服务中的环境变量
### EAS Build
[EAS Build](/build/introduction/) 使用 Metro Bundler 来构建嵌入在应用程序二进制中的 JavaScript bundle，因此它会使用与您的构建作业一起上传的 .env 文件，将 **EXPO*PUBLIC*** 变量内联到您的代码中。EAS Build 还允许在 **eas.json** 的构建配置文件和通过 EAS Secrets 定义环境变量。有关更多信息，请查看 EAS Build 文档中的[环境变量与构建机密](/build-reference/variables/)。
### EAS Update
[EAS Update](/eas-update/introduction) 在本地环境或 CI 中使用 Metro Bundler 来构建应用包，因此它将使用可用的 **.env** 文件将 `EXPO_PUBLIC_` 变量内联到代码中。有关更多信息，请查看 EAS Update 文档中的 [环境变量](/eas-update/environment-variables/)。
## 迁移到 Expo 环境变量
### 来自 react-native-config
将你的 **.env** 文件更新为在 JavaScript 代码中使用的变量前缀为 `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)。
然后更新你的代码以使用 `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;
```
### 来自 babel-plugin-transform-inline-environment-variables
使用 Babel 插件将代码中的环境变量引用进行转换，类似于 Expo 的环境变量工作方式。将变量放入一个 **.env** 文件中，并将变量名更新为以 `EXPO_PUBLIC_` 前缀：
```diff
- const apiUrl = process.env.API_URL;
+ const apiUrl = process.env.EXPO_PUBLIC_API_URL;
```
然后你可以从你的 [Babel 配置](/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` 清除缓存。
### 来自 direnv
将 JavaScript 中使用的任何环境变量从它们的 **.envrc** 文件移动到一个 **.env** 文件，并在前缀前加上 `EXPO_PUBLIC_`。
以前使用 `direnv` 时，你需要使用一个 [dynamic app config](/versions/latest/config/app/#app-config) 来读取 [`process.env`](https://nodejs.org/dist/latest/docs/api/process.html#process_process_env) 以在 `extra` 字段中设置环境变量，这样它们就可以通过 [`expo-constants`](/versions/latest/sdk/constants) 在你的 JavaScript 代码中使用。请将这些引用直接移动到你的代码中，并添加 `EXPO_PUBLIC_` 前缀：
```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。你很可能希望继续为在你的 JavaScript 代码中不使用的其他环境变量继续使用 `direnv`。
## 安全注意事项
切勿将前缀为 `EXPO_PUBLIC_` 的环境变量中的敏感秘密存储起来。当最终用户运行你的应用时，他们可以访问应用中的所有代码和嵌入的环境变量。有关存储敏感信息的更多信息，请阅读 [存放敏感信息](https://reactnative.dev/docs/security#storing-sensitive-info)。


# 链接

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

概览可用于在你的 Expo 应用中实现 Linking 和 Deep Links 的资源。

## 链接
链接使你的应用能够与进入和离开的 URL 进行交互。在此过程中新用户不仅被引导打开你的应用，还会被带到应用内的特定屏幕（路由）。
Video Tutorial: [观看：设置与 Expo 的链接](https://www.youtube.com/watch?v=kNbEEYlFIPs)
### 链接策略
在你的 Expo 应用中，你需要处理不同的链接策略：
- 使用你的网页域名链接到你的应用程序（[通用链接](#universal-linking) 使用 `https` 或 `http` 方案）
- 通过自定义方案（深层链接）将应用链接到其他应用或网站
  从你的应用链接到其他应用（外部链接）
> **info** **提示：** Expo Go 对入站链接的支持有限。我们建议使用 [Development builds](/develop/development-builds/introduction/) 来测试应用的链接策略。
## 通用链接
Android 和 iOS 都实现了自己的系统，将网页 URL 路由到应用（若应用已安装）。在 Android 上，这个系统被称为 App Links，在 iOS 上则被称为通用链接。两者的先决条件都是你拥有一个网页域名，你可以在该域名下托管一个验证你对该域名拥有控制权的文件。
### Android 应用链接
Android 应用链接与[从其他应用或网站链接到你应用的标准深度链接](#linking-to-your-app-from-other-apps-or-websites) 不同，因为它们使用常规的 HTTP 和 HTTPS 方案，并且仅限于 Android 设备。
此链接类型允许您的应用在用户点击链接时始终打开，而不是在设备显示的对话框中在浏览器或其他处理程序之间进行选择。如果用户未安装您的应用，该链接会将他们引导到应用关联的网站。
### iOS 通用链接
iOS 通用链接与 [标准深度链接](#linking-to-your-app-from-other-apps-or-websites) 不同，因为它们使用常规的 HTTP 和 HTTPS 方案，并且仅限于 iOS 设备。
此链接类型允许当用户点击指向您网站域名的 HTTP(S) 链接时，您的应用程序被打开。如果用户尚未安装您的应用程序，链接会将他们带到应用程序关联的网站。您还可以通过显示一个横幅，让用户打开您的应用程序来进一步配置网站，使用 [Apple Smart Banner](/linking/ios-universal-links/#apple-smart-banner)。
## 从其他应用或网站链接到你的应用
[Deep Links](https://en.wikipedia.org/wiki/Deep_linking) 是指向应用或网站中基于 URL 的特定内容的链接。
例如，通过点击某个产品广告，你的应用将在用户的设备上打开，用户可以查看该产品的详情。用户点击的该产品链接可能看起来像以下内容（或者也可以通过 JavaScript 设置 `window.location.href` 来调用）：
```html
<a href="myapp://web-app.com/product">查看产品</a>
```
这个链接由三部分构成：
- **方案**：标识应打开此 URL 的应用程序的 URL 方案（例如：`myapp://`）。对于非标准的深层链接也可以是 `https` 或 `http`。我们建议对基于 http(s) 的深层链接使用 [通用链接](#universal-linking)。
- **主机**：应打开该 URL 的应用域名（示例：`web-app.com`）。
- **路径**：应打开的屏幕路径（示例：`/product`）。如果未指定路径，系统将带用户进入应用的主屏幕。


## 链接到其他应用

了解如何根据其他应用的 URL scheme，在你的应用中处理并打开一个 URL。

通过使用目标应用的 URL，可以实现从你的应用跳转到其他应用。你可以使用两种方法在你的应用中打开这些 URL：
- 使用 [`expo-linking`](/versions/latest/sdk/linking) API
- 使用 Expo Router 的 [`Link`](/develop/file-based-routing/#how-does-link-work) 组件
## 使用 expo-linking API
[`expo-linking`](/versions/latest/sdk/linking) API 提供对原生 linking API（例如 Web 上的 `window.history`）的通用抽象，并为你的应用与其他已安装应用交互提供实用工具。
下面的示例使用 [通用 URL 方案](#common-url-schemes)在操作系统的默认浏览器中打开，并使用 [`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',
  },
});
```
## 使用 Expo Router 的 `Link` 组件
如果你的项目使用 [Expo Router](/router/introduction/)，请使用 `Link` 组件来打开 URL。它在本地平台上包装一个 `<Text>` 组件，在网页上则是一个 `<a>` 元素。它还使用 `expo-linking` API 来处理 URL 方案。
下面的示例在操作系统的默认浏览器中打开一个 [常见的 URL 方案](#common-url-schemes) （HTTPS）：
```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',
  },
});
```
## 常用的 URL 方案
在所有平台上都内置了提供核心功能访问的 URL 方案。以下是常用的一些方案列表：
| 方案             | 描述                 | 示例                      |
| ---------------- | -------------------- | ------------------------- |
| `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
---
对于 Android 11（API 30）及更高版本，您必须在 **AndroidManifest.xml** 文件中指定应用将要处理的 intents。您可以通过 [创建一个配置插件](/config-plugins/plugins-and-mods/#create-a-plugin) 来实现。
以下的配置插件示例通过定义 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;
```
在创建配置插件之后，在 [导入自定义配置插件](/config-plugins/plugins-and-mods/#import-a-plugin) ，并将其放在 `plugins` 属性下：
```json app.json
{
  "expo": {
    "plugins": [
      "./my-plugin.ts"
    ]
  }
}
```
> **info** **提示**：在 Android 上，你可以使用 `expo-intent-launcher` 打开设备上的**特定设置屏幕**。请参阅 [`expo-intent-launcher` API reference](/versions/latest/sdk/intent-launcher/#enums) 以查看可用 intents 的列表。
---
## Custom URL schemes
> 如果你知道要打开的应用的自定义 scheme，可以通过以下任一方法链接到它： [使用 `expo-linking` API](#using-expo-linking-api) 或 [使用 Expo Router 的 `Link`](#using-expo-routers-link-component)。
一些服务提供有关如何使用其应用自定义 URL 方案的文档。例如，[Uber 的深度链接文档](https://developer.uber.com/docs/riders/ride-requests/tutorials/deep-links/introduction#standard-deep-links) 描述了如何直接链接到特定的取车地点和目的地：
```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
```
在上面的示例中，如果用户的设备上没有安装 Uber 应用，你的应用可以引导他们前往 Google Play 商店或 Apple App Store 进行安装。我们建议使用 [`react-native-app-link`](https://github.com/FiberJW/react-native-app-link) 库来处理这些场景。
Note: Specify custom schemes for iOS
---
在 iOS 上，使用 [`Linking.canOpenURL`](/versions/latest/sdk/linking/#linkingcanopenurlurl) 来查询其他应用的 linking scheme 需要在 **InfoPlist** 中进行额外配置。你可以在应用配置中使用 [`ios.infoPlist`](/versions/latest/config/app/#infoplist) 属性来指定允许查询的 scheme 列表。例如：
```json app.json
{
  "expo": {
    "ios": {
      "infoPlist": {
        "LSApplicationQueriesSchemes": ["uber"]
      }
    }
  }
}
```
如果你没有指定这份列表，`Linking.canOpenURL` 可能在设备已安装目标应用时返回 `false`。
> **info** **提示** ：要在 iOS 设备上测试上述配置，请 [使用开发构建](/develop/development-builds/introduction/) 。不能使用 Expo Go 进行测试。
---
## 创建 URL
你可以使用 [`Linking.createURL`](/versions/latest/sdk/linking/#linkingcreateurlurl) 来创建一个可用于打开或重定向回你的应用的 URL。此方法解析为以下内容：
- **生产与开发版本** ：`myapp://`，其中 `myapp` 是在应用配置中定义的 [自定义 scheme](/linking/into-your-app/#add-a-scheme-in-app-config)
- **在 Expo Go 中开发** ：`exp://127.0.0.1:8081`
使用 `Linking.createURL` 可以帮助你避免硬编码 URL。通过向该方法传递可选参数，可以修改返回的 URL。
要将数据传递给应用程序，可以将数据作为路径或查询字符串追加到 URL。`Linking.createURL` 将自动构建一个可工作的 URL。例如：
```tsx Example
const redirectUrl = Linking.createURL('path/into/app', {
  queryParams: { hello: 'world' },
});
```
这将根据环境解析为以下内容：
- **生产和开发构建** ：`myapp://path/into/app?hello=world`
- **在 Expo Go 中开发** ：`exp://127.0.0.1:8081/--/path/into/app?hello=world`
Note: Using Expo Go for testing?
---
对于需要稳定 URL 的应用（例如认证提供商重定向），请使用自定义方案的开发构建，而不是使用 Expo Go。有关如何创建和测试自定义方案的更多详细信息，请参见 [Linking into your app](/linking/into-your-app/)。
---
## 应用内浏览器
`expo-linking` API 允许你使用操作系统默认的网页浏览器应用打开一个 URL。你可以使用 [`expo-web-browser`](/versions/latest/sdk/webbrowser) 库在应用内浏览器中打开 URL。例如，应用内浏览器对于安全的 [认证](/guides/authentication) 很有用。
Note: Example of opening a URL in an in-app browser
---
下面的示例通过 `expo-web-browser` 模拟在应用内浏览器中打开 URL 的行为，并使用 `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,
  },
});
```
---
## 在网页上提供更多链接功能
要在网页上提供更多链接功能，例如右键复制或悬停预览，您可以使用来自 [`expo-router`](/router/introduction/) 库的 `Link` 组件。
```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>` 元素：
```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>`。


## 将链接引入您的应用

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

本指南提供通过添加自定义方案在您的项目中配置标准 **深度链接** 的步骤。
> **info** 对于大多数应用，您可能希望设置 [Android 应用/iOS 通用链接](/linking/overview/#universal-linking)，而不是本指南中描述的深度链接，或者同时设置两者。
## 在应用配置中添加自定义方案
要提供链接到您的应用，需在 [应用配置](/workflow/configuration/) 中向 [`scheme`](/versions/latest/config/app/#scheme) 属性添加自定义字符串：
```json app.json
{
  "expo": {
    "scheme": "myapp"
  }
}
```
在您的应用中添加自定义方案后，您需要 [创建新的开发构建](/develop/development-builds/create-a-build/)。一旦应用安装在设备上，您可以使用 `myapp://` 在您的应用中打开链接。
如果 **未定义自定义方案**，则应用将在开发和生产构建中使用 `android.package` 和 `ios.bundleIdentifier` 作为默认方案。这是因为 [Expo Prebuild](/workflow/prebuild/) 会自动将这些属性添加为 Android 和 iOS 的自定义方案。
## 测试深度链接
您可以使用 [`npx uri-scheme`](https://github.com/expo/expo/tree/main/packages/uri-scheme#readme) 测试打开您应用的链接，它是一个用于交互和测试 URI 方案的命令行工具。
例如，如果您的应用有一个 `/details` 屏幕，您希望在用户点击链接时打开（无论是通过另一个应用还是网页浏览器），您可以通过运行以下命令来测试此行为：
```sh
$ npx uri-scheme open com.example.app://somepath/details --android
$ npx uri-scheme open myapp://somepath/details --ios
```
运行上述命令：
- 打开您应用的 `/details` 屏幕
- `android` 或 `ios` 选项指定链接应在 Android 或 iOS 上打开
- 或者，您可以尝试通过点击设备网页浏览器中的链接，例如 `<a href="scheme://">点击我</a>` 打开链接。请注意，在地址栏中输入链接可能无法按预期工作，您可以使用 [通用链接](/linking/overview/#universal-linking) 来实现此功能。
Note: 使用 Expo Go 测试链接
---
默认情况下，[Expo Go](https://expo.dev/go) 使用 `exp://` 方案。如果您链接到 `exp://` 而不指定后面的 URL 地址，它将打开应用的主页。在开发期间，您应用的完整 URL 看起来像 `exp://127.0.0.1:8081`。
要在 Expo Go 上测试时打开 `/details` 屏幕，您可以使用 `npx uri-scheme`：
```sh
$ npx uri-scheme open exp://127.0.0.1:8081/--/somepath/into/app?hello=world --ios
```
在 Expo Go 中，当指定路径时，`/--/` 会添加到 URL 中。这表明 Expo Go 中的子字符串对应于深度链接路径，而不是指向应用本身的路径的一部分。
默认情况下，当在 Expo Go 中打开 URL 时，`exp://` 会被替换为 `http://`。您还可以使用 `exps://` 来打开 `https://` URLs。然而，目前 `exps://` 不支持加载具有不安全 TLS 证书的网站。
---
## 处理 URLs
> **info** 如果您使用 [Expo Router](/linking/overview/#use-expo-router-to-handle-deep-linking)，您可以忽略此部分。
您可以使用 [`Linking.useURL()`](/versions/latest/sdk/linking/#useurl) 钩子观察启动您应用的链接，来源于 [`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()` 钩子通过以下命令性方法在后台工作：
- 启动应用的链接最初使用 [`Linking.getInitialURL()`](/versions/latest/sdk/linking/#linkinggetinitialurl) 返回
- 应用已经打开时触发的任何新链接都由 [`Linking.addEventListener('url', callback)`](/versions/latest/sdk/linking/#linkingaddeventlistenertype-handler) 观察
## 解析 URLs
您可以使用 [`Linking.parse()`](/versions/latest/sdk/linking/#linkingparseurl) 方法从 URL 中解析 **路径**、**主机名**和 **查询参数**。该方法提取深度链接信息并考虑非标准实现。
```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 (
  )
}
```
## 限制
如果用户没有安装您的应用，深度链接将无法工作。像 [Branch](https://www.branch.io/deep-linking/) 这样的归因服务提供条件性链接到您的应用或网页的解决方案。
Android 应用/iOS 通用链接是您可以用来处理这种情况的另一种解决方案。这种链接方式允许您的应用在用户点击指向您网站域的 HTTP(S) 链接时打开。如果用户没有安装您的应用，链接将带他们到您的网站。有关更多详细信息，请参见 [通用链接](/linking/overview/#universal-linking)。


## Android 应用链接

学习如何配置 Android 应用链接以从标准网页 URL 打开您的 Expo 应用。

要为您的应用配置 Android 应用链接，您需要：
- 在您项目的应用配置中添加 `intentFilters` 并将 `autoVerify` 设置为 true
- 设置双向关联以验证您的网站和本地应用程序
<VideoBoxLink videoId="kNbEEYlFIPs" time={399} title="观看：使用 Expo 路由设置 Android 应用链接" />
## 将 `intentFilters` 添加到应用配置
通过添加 `android.intentFilters` 属性并将 `autoVerify` 属性设置为 `true` 来配置您的应用配置。指定 `autoVerify` 是 Android 应用链接正常工作所必需的。
以下示例显示了基本配置，使您的应用能够在标准 Android 对话框中作为处理任何链接到 `webapp.io` 域的选项出现。它还使用常规的 `https` 协议，因为 [Android 应用链接](/linking/overview/#android-app-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"]
        }
      ]
    }
  }
}
```
## 设置双向关联
要设置网站和 Android 应用之间的 **双向关联**，您需要以下内容：
- **网站验证：** 这需要在 **/.well-known** 目录下创建一个 **assetlinks.json** 文件并将其托管在目标网站上。此文件用于验证从给定链接打开的应用是否是正确的应用。
- **本地应用验证：** 这需要某种形式的代码签名，引用目标网站域（URL）。
### 创建 assetlinks.json 文件
Step 1: 
为网站验证创建一个 **assetlinks.json** 文件（也称为 [数字资产链接](https://developers.google.com/digital-asset-links/v1/getting-started) 文件），文件路径为 **/.well-known/assetlinks.json**。此文件用于验证为给定链接打开的应用。
如果您使用 Expo 路由来构建您的网站（或其他任何现代 React 框架，如 Remix、Next.js 等），请在 **public/.well-known/assetlinks.json** 中创建 **assetlinks.json**。对于旧版的 Expo webpack 项目，请在 **web/.well-known/assetlinks.json** 中创建该文件。
Step 2: 
从应用配置中获取 `package_name` 的值，在 `android.package` 下。
Step 3: 
从您应用的签名证书中获取 `sha256_cert_fingerprints` 的值。如果您使用 [EAS Build](/build/setup/) 来构建您的 Android 应用，请在创建构建后：
- 运行 `eas credentials -p android` 命令，并选择构建配置以获取其指纹值。
- 复制 `SHA256 Fingerprint` 下列出的指纹值。
Note: 从 Google Play 控制台获取 SHA256 证书指纹的替代方法
---
如果您不使用 EAS 来管理代码签名，您可以通过手动构建并提交应用到 [Google Play 控制台](https://play.google.com/console/) 来找到 **sha256_cert_fingerprints**：
- 在 Google Play 控制台的仪表板中，转到 **Release > Setup > App Signing**。
- 找到适用于您的应用的正确 **Digital Asset Links JSON** 片段。
- 复制看起来像 `14:6D:E9:83...` 的值并将其粘贴到 **public/.well-known/assetlinks.json** 文件中的 `sha256_cert_fingerprints` 下。
---
Step 4: 
将 `package_name` 和 `sha256_cert_fingerprints` 添加到 **assetlinks.json** 文件中：
```json public/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example",
      "sha256_cert_fingerprints": [
        // 支持不同应用和密钥的多个指纹
        "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** 您可以在 `sha256_cert_fingerprints` 数组中添加多个指纹，以支持不同变体的应用。有关更多信息，请参阅 [Android 文档中关于如何声明网站关联的信息](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc)。
### 托管 assetlinks.json 文件
使用您的域通过 Web 服务器托管 **assetlinks.json** 文件。此文件必须以 `application/json` 的内容类型进行提供，并且可以通过 HTTPS 连接进行访问。通过在地址栏中输入完整 URL 验证您的浏览器可以访问此文件。
### 本地应用验证
在 Android 设备上安装应用以触发 [Android 应用验证](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc) 过程。
打开应用后，请参阅 [处理进入您应用的链接](/linking/into-your-app/#handle-urls) 以获取有关如何处理入站链接并向用户显示他们请求的内容的更多信息。
## 调试
Expo CLI 使您能够在不部署网站的情况下测试 Android 应用链接。利用 [`--tunnel`](/more/expo-cli/#tunneling) 功能，您可以将开发服务器转发到一个公共可用的 HTTPS URL。
Step 1: 
设置环境变量 `EXPO_TUNNEL_SUBDOMAIN=my-custom-domain`，其中 `my-custom-domain` 是您在开发过程中使用的唯一字符串。这确保您的隧道 URL 在开发服务器重启时保持一致。
Step 2: 
根据 [上述描述](#add-intentfilters-to-the-app-config) 向您的应用配置中添加 `intentFilters`。将 `host` 值替换为 Ngrok URL：`my-custom-domain.ngrok.io`。
Step 3: 
使用 `--tunnel` 标志启动您的开发服务器：
```sh
$ npx expo start --tunnel
```
Step 4: 
在您的设备上编译开发构建：
```sh
$ npx expo run:android
```
Step 5: 
使用以下 `adb` 命令启动意图活动并在您的应用中打开链接，或在设备的 Web 浏览器中输入自定义域链接。
```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>
```
## 故障排除
以下是一些常见提示，帮助您在实现 Android 应用链接时进行故障排除：
- 确保您的网站通过 HTTPS 提供，并且内容类型为 `application/json`
- [验证 Android 应用链接](https://developer.android.com/training/app-links/verify-android-applinks)
- Android 验证可能需要 20 秒或更长时间才能生效，因此请确保等到其完成。
- 如果您更新了 Web 文件，请重新构建本地应用以触发供应商端的服务器更新（Google）


## iOS 通用链接

学习如何配置 iOS 通用链接以通过标准 Web URL 打开您的 Expo 应用。

要为您的应用配置 iOS 通用链接，您需要设置 **双向关联** 以验证您的网站和本地应用。
<VideoBoxLink videoId="kNbEEYlFIPs" time={68} title="观看：使用 Expo Router 设置 iOS 通用链接" />
## 设置双向关联
要在网站和应用之间建立 **双向关联**，您需要执行以下步骤：
- **网站验证：** 这需要在 **/.well-known** 目录中创建一个 **apple-app-site-association (AASA)** 文件，并将其托管在目标网站上。该文件用于验证从给定链接打开的应用是否是正确的应用。
- **本地应用验证：** 这需要某种形式的代码签名，引用目标网站域（URL）。
### 创建 AASA 文件
在 **/.well-known** 目录中为网站验证创建一个 **apple-app-site-association** 文件。该文件指定您的 Apple 开发者团队 ID、包标识符和支持路径的列表，以重定向到本地应用。
> **info** 您可以在项目中运行 **实验性** CLI 命令 `npx setup-safari`，自动将包标识符注册到您的 Apple 账户，分配权利给该 ID，并在商店中创建 iTunes 应用条目。本地设置将被打印，您可以跳过大部分后续步骤。这是开始使用 iOS 通用链接的最简单方法。
如果您使用 Expo Router 构建网站（或任何其他现代 React 框架，如 Remix、Next.js 等），请在 **public/.well-known/apple-app-site-association** 中创建 AASA 文件。对于旧版 Expo webpack 项目，请在 **web/.well-known/apple-app-site-association** 中创建文件。
```json public/.well-known/apple-app-site-association
{
  // 本部分启用通用链接
  "applinks": {
    "apps": [],
    "details": [
      {
        // 语法: "<APPLE_TEAM_ID>.<BUNDLE_ID>"
        "appID": "QQ57RJ5UTD.com.example.myapp",
        // 所有应该支持重定向的路径。
        "paths": ["/records/*"]
      }
    ]
  },
  // 本部分启用 Apple Handoff
  "activitycontinuation": {
    "apps": ["<APPLE_TEAM_ID>.<BUNDLE_ID>"]
  },
  // 本部分启用共享 Web 凭据
  "webcredentials": {
    "apps": ["<APPLE_TEAM_ID>.<BUNDLE_ID>"]
  }
}
```
在上述示例中：
- 对 `https://www.myapp.io/records/*` 的任何链接（与记录 ID 的通配符匹配）应直接由在 iOS 设备上具有匹配包标识符的应用打开。这是 [Apple 团队 ID](https://expo.fyi/apple-team) 和包标识符的组合。
- `*` 通配符 **不** 匹配域名或路径分隔符（句点和斜杠）。
- `activitycontinuation` 和 `webcredentials` 对象是可选的，但建议使用。
> 请参阅 [Apple 的文档](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html) 获取 AASA 格式的更多详细信息。Branch 提供了一个 [AASA 验证器](https://branch.io/resources/aasa-validator/)，可以帮助您确认 AASA 是否已正确部署并具有有效格式。
### 支持 `details` 格式
[`details` 格式在 iOS 13 中得到支持](https://developer.apple.com/documentation/xcode/supporting-associated-domains)，允许您指定：
- `appIDs` 而不是 `appID`：使多个应用与相同配置关联更容易
- `components` 数组：允许您指定片段、排除特定路径，并添加注释
Note: 来自 Apple 文档的示例 AASA JSON
---
```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"
          }
        ]
      }
    ]
  }
}
```
---
为了支持所有 iOS 版本，您可以在 `details` 键中同时提供以上两种格式，但我们建议将较新 iOS 版本的配置放在前面。
### 托管 AASA 文件
使用您的域名通过 Web 服务器托管 **apple-app-site-association** 文件。该文件必须通过 HTTPS 连接提供。验证您的浏览器可以访问该文件。
在您设置好 AASA 文件后，将网站部署到支持 HTTPS 的服务器（大多数现代 Web 主机）。
### 本地应用配置
在部署您的 **apple-app-site-association**（AASA）文件后，通过将 [`ios.associatedDomains`](/versions/latest/config/app/#associateddomains) 添加到您的 [app config](/workflow/configuration/) 来配置您的应用以使用关联域。确保遵循 [Apple 指定的格式](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_associated-domains) 并 **不** 在 URL 中包括协议（`https`）。这是一个常见错误，会导致通用链接无法正常工作。
例如，如果一个关联网站是 `https://expo.dev/`，则 `applinks` 为：
```json app.json
{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:expo.dev"]
    }
  }
}
```
使用 [EAS Build](/build/setup/) 构建您的 iOS 应用，确保权利自动注册到 Apple。
Note: 手动本地配置
---
如果您不使用 EAS 或 [连续本地生成](/workflow/continuous-native-generation) (`npx expo prebuild`)，则必须 [手动配置](/build-reference/ios-capabilities#manual-setup) 您的包标识符的 **关联域** 功能。
如果通过 [Apple 开发者控制台](/build-reference/ios-capabilities#apple-developer-console) 启用，则确保在您的 **ios/[app]/[app].entitlements** 文件中添加以下权利：
```xml
<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:expo.dev</string>
</array>
```
---
### 本地应用验证
在您的 iOS 设备上安装应用以触发验证过程。移动设备上指向您网站的链接应打开您的应用。如果没有，请重新检查先前步骤，以确保您的 AASA 有效、AASA 中指定的路径，以及您在 [Apple 开发者控制台](https://developer.apple.com/account/resources/identifiers/list) 中正确配置了应用 ID。
一旦您的应用打开，请参阅 [处理链接到您的应用](/linking/into-your-app/#handle-urls) 获取有关如何处理传入链接并向用户显示他们请求的内容的更多信息。
> iOS 在首次安装应用或从 App Store 安装更新时下载您的 AASA。之后，操作系统不会频繁刷新。如果您想更改生产应用中 AASA 的路径，则需要通过 App Store 发布完整更新，以便所有用户的应用重新获取您的 AASA 并识别新路径。
## Apple 智能横幅
如果用户未安装您的应用，他们将被引导至网站。您可以使用 [Apple 智能横幅](https://developer.apple.com/documentation/webkit/promoting_apps_with_smart_app_banners) 在页面顶部显示一个横幅，提示用户安装应用。只有当用户在移动设备上并且没有安装应用时，横幅才会显示。
要启用横幅，请将以下元标记添加到网站的 `<head>` 中，将 `<ITUNES_ID>` 替换为您应用的 iTunes ID：
```html
<meta name="apple-itunes-app" content="app-id=<ITUNES_ID>" />
```
如果您在设置横幅时遇到问题，请运行以下命令以自动生成您的项目的元标记：
```sh
$ npx setup-safari
```
### 将元标记添加到您的静态渲染网站
如果您正在使用 Expo Router 构建 [静态渲染网站](/router/reference/static-rendering)，请将 HTML 标记添加到您的 [**app/+html.js** 文件](/router/reference/static-rendering#root-html) 的 `<head>` 组件中。
```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>" />
        {/* 其他头部元素... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
```
## 调试
Expo CLI 使您可以在不部署网站的情况下测试 iOS 通用链接。利用 [`--tunnel`](/more/expo-cli/#tunneling) 功能，您可以将开发服务器转发到公开可用的 HTTPS URL。
Step 1: 
设置环境变量 `EXPO_TUNNEL_SUBDOMAIN=my-custom-domain`，其中 `my-custom-domain` 是您在开发过程中使用的唯一字符串。这确保您的隧道 URL 在开发服务器重启时保持一致。
Step 2: 
将 `associatedDomains` 添加到您的应用配置中，如 [上述描述](#native-app-configuration) 中所示。将域值替换为 Ngrok URL：`my-custom-domain.ngrok.io`。
Step 3: 
使用 `--tunnel` 标志启动您的开发服务器：
```sh
$ npx expo start --tunnel
```
Step 4: 
在您的设备上编译开发构建：
```sh
$ npx expo run:ios
```
现在，您可以在设备的 Web 浏览器中输入自定义域链接以打开您的应用。
## 故障排除
以下是一些帮助您在实现 iOS 通用链接时进行故障排除的常见提示：
- 阅读 Apple 官方文档以了解 [调试通用链接](https://developer.apple.com/documentation/technotes/tn3155-debugging-universal-links)
- 确保您的 apple-app-site-association 文件有效，使用 [验证工具](https://branch.io/resources/aasa-validator/) 进行检查。
- 未压缩的 `apple-app-site-association` 文件不能 [大于 128kb](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html)。
- 确保您的网站通过 HTTPS 提供。
- 如果您更新了 Web 文件，请重新构建本地应用以触发供应商端（Apple）的服务器更新。


# 编写原生代码

## 添加自定义原生代码

学习如何向您的 Expo 项目添加自定义原生代码。

您可以通过以下一种或两种方法添加自定义原生代码：
- [使用包含原生代码的库](#using-libraries-that-include-native-code)
- [编写原生代码](#writing-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 的绑定）。
Note: 使用 Expo Go？
---
如果您正在使用沙箱应用 [Expo Go](http://expo.dev/go)，[您只能访问 Expo SDK 中包含的原生库](/versions/latest/sdk/third-party-overview/)，或不包含任何自定义原生代码的库（[了解更多](/workflow/using-libraries/#third-party-libraries)）。[创建开发构建](/develop/development-builds/introduction/)允许您像在其他原生应用中一样更改原生代码或配置。
---
### 在开发构建中安装具有自定义原生代码的库
使用 [开发构建](/develop/development-builds/introduction/) 时，使用带有自定义原生代码的库非常简单：
- 使用 npm 安装库，例如：`npx expo install react-native-localize`
- 如果库包含 [配置插件](/config-plugins/introduction/)，您可以在应用配置中指定您首选的配置。
- 创建一个新的开发构建（可以[本地](/guides/local-app-development/)或使用 [EAS](/develop/development-builds/create-a-build/)）。
现在您可以在应用代码中使用该库。
Note: 关键概念和开发工作流程
---
[开发概述](/workflow/overview/)提供了有关使用 Expo 开发应用程序的关键概念和核心开发循环的流程的详细信息。
---
## 编写原生代码
使用 [Expo Modules API](/modules/overview/) 编写 Swift 和 Kotlin 代码，并通过原生模块和视图向您的应用添加新功能。虽然您可以使用其他工具构建原生模块，但我们认为使用 Expo Modules API 使构建和维护几乎所有类型的 React Native 模块变得尽可能简单。我们认为，Expo Modules API 是大多数开发者为其应用构建原生模块的最佳选择。
Note: 我什么时候应该考虑编写原生代码？
---
常常会遇到库不能完全满足您需求的情况。例如，库可能无法访问特定平台功能，或者第三方服务可能没有为 React Native 提供绑定。
---
Note: 您是否考虑主要使用 C++ 编写模块？
---
如果您打算主要使用 C++ 编写一个原生模块，您可能想探索 React Native 提供的 [Turbo Modules API](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/turbo-modules.md)。
---
### 使用 Expo Modules API
### 创建本地模块
如果您打算在单个应用中使用您的原生模块（您可以稍后更改主意），我们建议 [使用 "本地" Expo 模块](/modules/get-started/#creating-the-local-expo-module) 来编写自定义原生代码。本地 Expo 模块的功能类似于库开发人员和 Expo SDK 中使用的 [Expo Modules](/modules/overview)，如 `expo-camera`，但它们不会发布到 npm。相反，您可以在项目中直接创建它们。
创建本地模块将在项目的 `modules` 目录中搭建一个 Swift 和 Kotlin 模块，这些模块会自动链接到您的应用。
```sh
$ npx create-expo-module@latest --local
$ npx expo run
```
### 在多个应用中共享模块
如果您打算在多个应用中使用您的原生模块，则使用 `npx create-expo-module@latest`，不需要添加 `--local` 标志，并[创建一个独立模块](/modules/use-standalone-expo-module-in-your-project/)。您可以将您的包发布到 npm，或者您可以将其放在您的 [monorepo](/guides/monorepos/) 的 packages 目录中（如果有的话），以 [类似于本地模块的方式使用它](/modules/use-standalone-expo-module-in-your-project/)。
## 使用连续原生生成（CNG）时的考虑事项
在使用 [CNG](/workflow/continuous-native-generation/) 时，以下建议最为重要，但即使您不使用它也非常好。
Note: 在本地构建以获得最佳调试体验和快速反馈
---
默认情况下，使用 `create-expo-app` 创建的 Expo 项目使用 CNG，并且在您运行 `npx expo prebuild` 命令前不包含 **android** 或 **ios** 原生目录。使用 CNG 时，开发人员通常不会将 **android** 和 **ios** 目录提交到源代码控制中，也不会在本地生成它们，因为 EAS Build 会在构建过程中自动完成。也就是说，在编写自定义原生代码时，生成原生目录并使用 `npx expo run` 在本地构建是很常见的，以便快速反馈循环和完全访问 Android Studio / Xcode 中的原生调试工具。
---
Note: 使用配置插件进行原生项目配置
---
如果您的原生代码需要您对项目配置进行更改，例如修改项目的 **AndroidManifest.xml** 或 **Info.plist**，[您应通过配置插件应用这些更改](/modules/config-plugin-and-native-module-tutorial/)，而不是直接修改 **android** 和 **ios** 目录中的文件。请记住，直接对原生项目目录所做的更改将在您使用 CNG 时的下次运行 prebuild 时丢失。
---
Note: 使用事件订阅器挂接到应用生命周期事件
---
如果您需要挂接到 Android 生命周期事件或 `AppDelegate` 方法，请使用 Expo Modules 提供的 [Android](/modules/android-lifecycle-listeners/) 和 [iOS](/modules/appdelegate-subscribers/) 的 API 来实现，而不是直接修改原生项目目录中的源文件或使用配置插件添加代码，这与其他插件的兼容性较差。
---


## 采用 Prebuild

学习如何在使用 React Native CLI 启动的项目中采用 Expo Prebuild。

使用 [Expo Prebuild][prebuild] 以 [持续生成您的本地项目](/workflow/continuous-native-generation) 有 [许多优势](/workflow/prebuild#pitch)。本指南将向您展示如何在使用 `npx @react-native-community/cli@latest init` 启动的项目中采用 Expo Prebuild。转换项目所需的时间取决于您对 Android 和 iOS 本地项目所做的自定义本地更改的数量。对于一个全新的项目，这可能需要一两分钟，而对于大型项目，这将花费更长时间。
采用 prebuild 将通过本地链接 `expo-modules-core` 自动添加对使用 [Expo 本地模块 API][expo-modules-core] 开发模块的支持。您还可以在项目中使用 [Expo CLI][cli] 的任何命令。
> **warning** [并非所有版本的 `react-native` 都被明确支持](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version)。确保使用与之对应的 Expo SDK 版本的 `react-native` 版本。
## 安装 `expo` 包
`expo` 包包含 [`npx expo prebuild`](/more/expo-cli/#prebuild) 命令，并指示使用哪个 [prebuild 模板](/workflow/prebuild#templates)：
```sh
$ npm install expo
```
确保安装适合您当前安装的 [版本的 `react-native`](/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version) 的 `expo` 版本。
## 更新入口文件
修改入口文件以使用 [`registerRootComponent`](/versions/latest/sdk/expo/#registerrootcomponentcomponent) 而不是 `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)。
## Prebuild
> **warning** 确保您已提交更改，以防您想要恢复，命令也会警告您这一点！
如果您正在迁移现有项目，则可能想先参考 [**迁移本地自定义**](#migrate-native-customizations)。
运行以下命令，根据应用配置 (**app.json/app.config.js**) 重新生成 **android** 和 **ios** 目录：
```sh
$ npx expo prebuild --clean
```
您可以通过本地构建项目来测试一切是否正常：
```sh
$ npx expo run:android
$ npx expo run:ios
```
> 了解更多关于 [编译本地应用](/more/expo-cli/#compiling)。
## 额外更改
以下更改是可选但推荐的。
**.gitignore**
您可以将 **.expo** 添加到您的 **.gitignore** 中，以防止 Expo CLI 生成的值被提交。这些 [值是您项目的唯一标识](/more/expo-cli/#expo-directory) 在您的本地计算机上。
在您创建新项目时，**android** 和 **ios** 目录会自动添加到 **.gitignore** 中，确保它们在 prebuild 之间不会被提交。
**app.json**
删除所有在顶级 `expo` 对象之外的字段，因为这些在 `npx expo prebuild` 中不会被使用。
```diff
{
-  "name": "myapp",
-  "displayName": "myapp"
+  "expo": {
+    "name": "myapp"
+  }
}
```
**metro.config.js**
请参阅 [自定义 Metro](/guides/customizing-metro/)。
**package.json**
您可能想要更改脚本以使用 [Expo CLI](/more/expo-cli/#compiling) 运行命令：
```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` 来服务文件。
## 迁移本地自定义
如果您的项目有任何本地修改（对 **android** 或 **ios** 目录的更改，例如应用程序图标配置或启动画面），那么您需要配置您的应用配置 (**app.json**) 以反映这些本地更改。
- 检查您的更改是否与内置的 [应用配置字段](/versions/latest/config/app/) 重叠。例如，如果您有应用程序图标，请确保在 **app.json** 中将其定义为 `expo.icon`，然后重新运行 `npx expo prebuild`。
- 查找您使用的任何包是否需要 [Expo 配置插件][config-plugins]。如果项目中的某个包需要在 **android** 或 **ios** 目录中进行额外更改，则您可能需要配置插件。当您运行 `npx expo install` 并使用 **package.json** 依赖关系中的所有包时，某些插件可以被自动添加。如果某个包需要插件但未提供，则可以尝试检查社区插件 [expo/config-plugins](https://github.com/expo/config-plugins) 来查看是否已经存在。
- 您可以使用 [VS Code Expo 扩展][vs-code-expo] 检查您的更改并调试 prebuild 是否生成您期望的本地代码。只需按 <kbd>Cmd ⌘</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd>，输入 "Expo: Preview Modifier"，然后选择您希望检查的本地文件。
- 此外，您可以开发本地配置插件以满足您的需求。 [了解更多](/config-plugins/development-and-debugging/#develop-a-plugin)。
## 添加更多功能
Prebuild 是自动化冰山的一角，您可以接下来采用以下一些功能：
- [EAS Build](/build/setup): 代码签名和云构建。
- [EAS Update](/build/updates): 立即发送空中更新。
- [Expo for web](/workflow/web): 在浏览器中运行您的应用。
- [Expo Dev Client][dev-client]: 围绕您的本地运行时创建您自己的个人 "Expo Go" 类型的应用程序。
- [Expo 本地模块 API][expo-modules-core]: 使用 Swift 和 Kotlin 编写模块。在使用 `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 应用程序的本地应用编译过程的概述。

您可以利用本地开发环境，通过使用 Android Studio 和 Xcode 来本地编译您的应用程序。此编译过程可用于调试版本和发布版本。本页提供本地应用编译过程的概述，并引用可能在此工作流程中所需的其他指南。
## 何时本地编译您的应用程序
有不同的场景您可能希望在开发机器上编译应用程序。这包括：
- 您希望快速迭代本地代码更改或测试调试版本中的平台特定更改
- 您希望手动生成本地代码以测试调试版本
- 在网络访问受限的环境中创建构建的任何场景
- 您希望本地管理自己的凭据（例如上传密钥等）
- 您希望测试或集成自己的自定义构建缓存提供者
- 您希望选择退出 Android 的预构建 Expo 模块，并从源代码本地编译一次
> **注意**：本地编译您的应用程序可以补充 EAS Build。您可以继续使用云自动化的构建服务，并回退到本地构建进行开发。
## 前提条件
您需要安装和设置 Android Studio 和 Xcode，以在本地机器上编译和运行 Android 和 iOS 项目。请参阅以下指南以了解如何设置这些工具：
- [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)
## 编译您的调试版本
要快速构建和迭代调试版本，您可以使用 Expo CLI 的 `npx expo run:[android|ios]` 命令。这些命令使用您本地安装的 Android SDK 或 Xcode 将项目编译为您的应用的调试版本。
## 编译您的发布版本
要创建应用的发布版本（也称为生产版本），您需要使用 Android Studio 和 Xcode 提供的工具生成签名凭据。然后，您可以生成发布版本并手动提交您的应用到 Google Play 商店或苹果应用商店。
## 重用提供者的先前构建
您可以通过缓存和重用提供者的构建来加速本地开发。您可以使用 EAS 作为构建提供者或创建自己的自定义提供者。
## Android 的预构建 Expo 模块
SDK 53 及更高版本配备预构建的 Android Expo 模块，减少了 Gradle 在每次构建时的工作量。您可以继续使用默认值，或在需要修改模块的源代码时选择性地退出。


## 本地应用开发

学习如何在本地编译和构建您的 Expo 应用。

要在本地使用您的机器将项目构建为应用，您必须在测试调试版本或创建用于提交到应用商店的生产版本之前手动生成原生代码。有两种方法可以在本地构建您的应用。此指南提供了两种方法的简要介绍以及必要的其他指南的参考，以创建此工作流程。
## 先决条件
您需要安装并设置 Android Studio 和 Xcode，以便在本地机器上编译和运行 Android 和 iOS 项目。有关如何设置这些工具，请参见以下内容：
- [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)
## 本地应用编译
要在本地构建项目，您可以使用 Expo CLI 的编译命令来生成 **android** 和 **ios** 目录：
```sh
$ npx expo run:android
$ npx expo run:ios
```
上述命令使用您本地安装的 Android SDK 或 Xcode 编译您的项目，生成应用的调试版本。
- 这些编译命令最初会运行 `npx expo prebuild` 来生成原生目录（**android** 和 **ios**），如果它们尚不存在。如果它们已经存在，则会跳过此步骤。
- 您还可以添加 `--device` 标志以选择要在其上运行应用的设备——您可以选择物理连接的设备或模拟器/仿真器。
- 您可以传入 `--variant release`（Android）或 `--configuration Release`（iOS）来构建 [应用的生产版本](/deploy/build-project/#production-builds-locally)。请注意，这些构建没有签名，您不能将其提交到应用商店。要签署您的生产版本，请参见 [本地应用生产](/guides/local-app-production/)。
- **仅限 Android**：从 SDK 54 开始，您可以传入 `--variant debugOptimized` 变体，以加快开发迭代速度。有关更多信息，请参见 [在 Expo CLI 中编译 Android](/more/expo-cli/#compiling-android)。
要在第一次构建后修改项目的配置或原生代码，您必须重新构建项目。再次运行 `npx expo prebuild` 会将更改叠加在现有文件之上。构建后，这可能会产生不同的结果。
为避免这种情况，创建新项目时，原生目录会自动添加到项目的 **.gitignore** 中，您可以使用 `npx expo prebuild --clean` 命令。这确保项目始终得到管理，而 [`--clean` 标志](/workflow/prebuild/#clean) 将在重新生成之前删除现有目录。您可以使用 [应用配置](/workflow/configuration/) 或创建一个 [配置插件](/config-plugins/introduction/) 来修改项目的配置或原生目录中的代码。
要了解编译和预构建的工作原理，请参见以下指南：
## 使用 `expo-dev-client` 的本地构建
如果您将 [`expo-dev-client`](/develop/development-builds/introduction/#what-is-expo-dev-client) 安装到项目中，则项目的调试构建将包括 `expo-dev-client` 用户界面和工具，我们称这些为开发构建。
```sh
$ npx expo install expo-dev-client
```
要创建开发构建，您可以使用 [本地应用编译](#local-app-compilation) 命令（`npx expo run:[android|ios]`），这将创建一个调试构建并启动开发服务器。
## 使用 Android 产品风味的本地构建
> **warning** 仅在 SDK 52 及更高版本中可用。
如果您有一个具有多个产品风味的自定义 Android 项目，使用不同的应用 ID，您可以配置 `npx expo run:android` 以使用正确的风味和构建类型。Expo 支持 `--variant` 和 `--app-id` 来自定义构建和启动行为。
`--variant` 标志可以将 Android 构建类型从 **debug** 切换为 **release**。当以 camelCase 格式配置时，此标志还可以配置产品风味和构建类型。例如，如果您有 [**免费** 和 **付费** 产品风味](https://developer.android.com/build/build-variants#change-app-id)，您可以使用以下命令构建应用的开发版本：
```sh
$ npx expo run:android --variant freeDebug
$ npx expo run:android --variant paidDebug
```
`--app-id` 标志可用于使用自定义应用程序 ID 构建后启动应用。例如，如果您的产品风味 **free** 使用 `applicationIdSuffix ".free"` 或 `applicationId "dev.expo.myapp.free"`，则可以运行构建并启动应用：
```sh
$ npx expo run:android --variant freeDebug --app-id dev.expo.myapp.free
```
> **info** 自定义 Android 构建类型也是可能的，但这将打破 Expo 假设 **release** 的构建类型用于生产。您可能会使用不同的构建类型构建未优化的代码。
## 使用 EAS 的本地构建


## 在本地创建发布构建

了解如何在本地为您的 Expo 应用创建发布（生产）构建。

要在本地创建您应用的发布版本（也称为生产版本），您需要在计算机上遵循不同的步骤，并使用创建任何原生应用所需的工具。本指南提供了 Android 和 iOS 所需的步骤。
## Android
在本地为 Android 创建发布版本需要使用 [上传密钥](https://developer.android.com/studio/publish/app-signing#certificates-keystores) 对其进行签名，并生成 Android 应用程序包 (**.aab**)。请按照以下步骤操作：
### 先决条件
- 已安装 [OpenJDK 发行版](/get-started/set-up-your-environment/?mode=development-build&buildEnv=local#install-watchman-and-jdk) 以访问 `keytool` 命令
- 生成 **android** 目录。如果您正在使用 [CNG](/workflow/continuous-native-generation/)，请运行 `npx expo prebuild` 以生成它。
Step 1: 
### 创建上传密钥
Note: 已经使用 EAS Build 创建了构建？下载您的凭证并跳到下一步。
---
如果您已经使用 EAS Build 创建了构建，请遵循以下步骤下载凭证，其中包含上传密钥及其密码、密钥别名和密钥密码：
1. 在终端中运行 `eas credentials -p android` 并选择构建配置。
2. 选择 **credentials.json** > **从 EAS 下载凭证到 credentials.json**。
3. 将下载的 **keystore.jks** 文件移动到 **android/app** 目录。
4. 从 **credentials.json** 中复制上传密钥库密码、密钥别名和密钥密码的值，因为您将在下一步中需要它们。
---
在您的 Expo 项目目录中，运行以下 `keytool` 命令以创建上传密钥：
```sh
$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000
```
运行此命令后，系统会提示您输入密钥库的密码。此密码将保护上传密钥。请记住您在此处输入的密码，因为您将在下一步中需要它。
此命令还会在您的项目目录中生成名为 **my-upload-key.keystore** 的密钥库文件。将其移动到 **android/app** 目录。
> **warning** 如果您将 **android** 目录提交到像 Git 这样的版本控制系统，请不要提交此密钥库文件。它包含您的上传密钥，应保持私密。
Step 2: 
### 更新 gradle 变量
打开 **android/gradle.properties** 文件，并在文件末尾添加以下 gradle 变量。用您在上一步中提供的正确密钥库和密钥密码替换 `*****`。
这些变量包含有关您上传密钥的信息：
```ruby android/gradle.properties
# 如果您已从 `eas credentials` 命令下载凭证，请查看下方每个值的注释。
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore     # "keystore" 文件的路径
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias                # 用 credentials.json 文件中 `keystore.keyAlias` 字段的值替换
MYAPP_UPLOAD_STORE_PASSWORD=*****                  # 用 credentials.json 文件中 `keystore.password` 字段的值替换
MYAPP_UPLOAD_KEY_PASSWORD=*****                    # 用 credentials.json 文件中 `keystore.keyPassword` 字段的值替换
```
> **warning** 如果您将 **android** 目录提交到像 Git 这样的版本控制系统，请不要提交上述信息。相反，请在您的计算机上创建一个 **~/.gradle/gradle.properties** 文件，并将上述变量添加到此文件中。
Step 3: 
### 将签名配置添加到 build.gradle
打开 **android/app/build.gradle** 文件并添加以下配置：
<DiffBlock source="/static/diffs/android-release-build.diff" />
Step 4: 
### 生成发布 Android 应用程序包 (aab)
导航到 **android** 目录并通过运行 Gradle 的 `bundleRelease` 命令创建 **.aab** 格式的发布构建：
```sh
$ cd android
$ ./gradlew app:bundleRelease
```
此命令将在 **android/app/build/outputs/bundle/release** 目录中生成 app-release.aab。
Step 5: 
### 手动将应用提交到 Google Play 控制台
当第一次提交 **.aab** 文件时，Google Play 商店需要手动提交应用。
## iOS
要在本地为 Apple App Store 创建 iOS 发布版本，您需要使用 Xcode，它通过 App Store Connect 处理签名和提交过程。
### 先决条件
- 付费的 Apple 开发者会员
- 已在计算机上安装 [Xcode](/get-started/set-up-your-environment/?platform=ios&device=physical&mode=development-build&buildEnv=local#set-up-xcode-and-watchman)
- 生成 **ios** 目录。如果您正在使用 [CNG](/workflow/continuous-native-generation/)，请运行 `npx expo prebuild` 以生成它。
Step 1: 
### 在 Xcode 中打开 iOS 工作区
在您的 Expo 项目目录中，运行以下命令在 Xcode 中打开 `your-project.xcworkspace`：
```sh
$ xed ios
```
打开 Xcode 中的 iOS 项目后：
1. 从左侧的侧边栏中选择您的应用工作区。
2. 转到 **Signing & Capabilities** 并选择 **All** 或 **Release**。
3. 在 **Signing** > **Team** 下，确保选择了您的 Apple 开发团队。Xcode 将生成一个自动管理的配置文件和签名证书。
Step 2: 
### 配置发布方案
要配置您应用的发布方案：
1. 从菜单栏中，打开 **Product** > **Scheme** > **Edit Scheme**。
2. 从侧边栏中选择 **Run**，然后使用下拉菜单将 **Build configuration** 设置为 **Release**。
Step 3: 
### 生成发布应用
要为发布生成应用，从菜单栏中，打开 **Product** > **Build**。此步骤将构建您的应用二进制文件以供发布。
Step 4: 
### 使用 App Store Connect 提交应用
构建完成后，您可以通过 App Store Connect 将应用分发到 TestFlight 或提交到 App Store：
1. 从菜单栏中，打开 **Product** > **Archive**。
2. 在 **Archives** 下，点击右侧边栏中的 **Distribute App**。
3. 点击 **App Store Connect** 并按照窗口中显示的提示进行操作。此步骤将创建一个应用商店记录并将您的应用上传到 App Store。
4. 现在，您可以进入您的 App Store Connect 账户，在应用列表下选择您的应用，并使用 TestFlight 提交以进行测试，或按照 App Store Connect 仪表板中的步骤为最终发布做准备。


## 使用构建缓存提供者

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

构建缓存是一项通过远程缓存构建来加速 `npx expo run:[android|ios]` 的功能，基于项目的 [fingerprint](/versions/latest/sdk/fingerprint/)。当你运行 `npx expo run:[android|ios]` 时，它会检查是否存在具有匹配指纹的构建，然后下载并启动它，而不是再次编译。否则，项目会像往常一样编译，然后生成的二进制文件会上传到远程缓存，以供将来运行使用。
## 使用 EAS 作为构建提供者
要使用 EAS Build 提供者插件，首先安装 `eas-build-cache-provider` 包作为开发依赖：
```sh
$ npx expo install eas-build-cache-provider
```
然后，更新你的 **app.json** 以包含 `buildCacheProvider` 属性及其提供者：
```json app.json
{
  "expo": {
    "buildCacheProvider": "eas"
  }
}
```
你可以通过导出一个实现以下方法的插件来创建自己的缓存提供者：
```ts
type BuildCacheProviderPlugin<T = any> = {
  /**
   * 尝试获取现有的构建。如果缺失，返回其 URL 或 null。
   */
  resolveBuildCache(props: ResolveBuildCacheProps, options: T): Promise<string | null>;
  /**
   * 上传新的构建二进制文件。如果失败，返回其 URL 或 null。
   */
  uploadBuildCache(props: UploadBuildCacheProps, options: T): Promise<string | null>;
  /**
   * （可选）自定义指纹哈希算法。
   */
  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;
};
```
使用 GitHub Releases 缓存构建的参考实现可以在 [Build Cache Provider Example](https://github.com/expo/examples/tree/master/with-github-remote-build-cache-provider) 中找到。
## 创建自定义构建提供者
首先创建一个 **provider** 目录以编写 TypeScript 的提供者插件，并在项目根目录中添加一个 **provider.plugin.js** 文件，这将是插件的入口点。
Step 1: 
### 创建一个 `provider/tsconfig.json` 文件
```json provider/tsconfig.json
{
  "extends": "expo-module-scripts/tsconfig.plugin",
  "compilerOptions": {
    "outDir": "build",
    "rootDir": "src"
  },
  "include": ["./src"],
  "exclude": ["**/__mocks__/*", "**/__tests__/*"]
}
```
Step 2: 
### 为你的插件创建一个 `provider/src/index.ts` 文件
```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: 
### 在根目录中创建一个 `provider.plugin.js` 文件
```js provider.plugin.js
// 此文件配置插件的入口文件。
module.exports = require('./provider/build');
```
Step 4: 
### 构建你的提供者插件
在你的项目根目录中运行 `npm run build provider` 以启动 TypeScript 编译器的监视模式。
Step 5: 
### 通过将以下行添加到 `example/app.json` 文件中，将你的示例项目配置为使用你的插件：
```json example/app.json
{
  "expo": {
    "buildCacheProvider": {
      "plugin": "./provider.plugin.js"
    }
  }
}
```
Step 6: 
### 测试你的提供者
当你在 **example** 目录中运行 `npx expo run` 命令时，你应该在日志中看到插件的控制台语句。
```sh
$ cd example
$ npx expo run:ios
```
就这样！你现在有一个远程构建缓存提供者来加速构建。
### 传递自定义选项
要向你的插件注入自定义选项，可以使用 `options` 字段，它将作为自定义函数的第二个参数传递。为此，请按下面所示修改 **example/app.json** 中的 `buildCacheProvider` 字段：
```json example/app.json
{
  "expo": {
    "buildCacheProvider": {
      "plugin": "./provider.plugin.js",
      "options": {
        "myCustomKey": "XXX-XXX-XXX"
      }
    }
  }
}
```


## 预构建 Expo 模块用于 Android

了解预构建 Expo 模块如何在您的机器上将 Android 构建时间减少多达 25%。

在构建 React Native 应用时，较长的构建时间会减慢您的开发工作流程并降低生产力。每次您对代码进行更改时，都可能需要等待构建过程完成，这可能会导致显著的延迟。
**从 SDK 53 开始**，Expo 引入了用于 Android 的预构建 Expo 模块以解决这一痛点。您的项目现在可以使用这些模块的预编译版本，而无需在每次构建时从头编译 Expo 模块源代码。最终，这将导致更快的构建时间。
## 优势
- **更快的本地开发**：在本地机器上将 Android 构建时间减少多达 25%
- **改善的开发者体验**：在开发迭代期间等待时间更短
- **自动优化**：与 SDK 53 及更高版本的新项目开箱即用
## 预构建的 Android Expo 模块如何工作
在项目的 Android 构建过程中，请查找构建输出中包名称旁的 `[📦]` 表情符号前缀。这表明这些包使用的是预构建版本，而不是从源代码编译而成。
例如，在使用 SDK 53 的默认模板创建项目并运行 `npx expo run:android` 命令后，您会注意到在预编译的包旁边有 `[📦 package-name` 前缀：
## 配置
**对于 SDK 53 及更高版本，创建使用可用 [Expo 模板](/more/create-expo/#--template) 的项目时无需配置步骤**。
### 放弃预构建的 Expo 模块
您可以选择放弃预构建模块。当您自己修改模块源代码时，可能需要这样做。在这种情况下，您可以通过将 `buildFromSource` 添加到 **package.json** 文件中来配置 Expo 自动链接配置：
```json package.json
{
  "name": "your-app-name",
  "expo": {
    "autolinking": {
      "android": {
        "buildFromSource": [
          ".*"
        ]
      }
    }
  }
}
```
### 有选择地放弃
您也可以通过指定单个包名称而不是通配符 `".*"` 来选择放弃特定模块，同时保留其他模块为预构建：
```json package.json
{
  "name": "your-app-name",
  "expo": {
    "autolinking": {
      "android": {
        "buildFromSource": [
          "expo-camera",
          "expo-web-browser",
          "expo-linking",
        ]
      }
    }
  }
}
```
## 注意事项
- 现有项目在升级到 SDK 53 及更高版本时可以受益于此功能
- 性能改进可能会根据您的硬件配置而有所不同
- 目前 EAS 构建的改进相对温和，但为未来的缓存机制奠定了基础


# Web

## 使用 Expo 开发网站

学习如何为网络开发您的应用程序，以便构建通用应用程序。

Expo 在使用 React 构建全栈网站方面提供了卓越的支持。Expo 网站可以进行 [静态渲染](/router/reference/static-rendering)，以便提高 SEO 和性能，或者进行客户端渲染，以便在浏览器中获得更类似应用程序的体验。
For 通用: 
    使用来自 [React Native for web](https://github.com/necolas/react-native-web) 的 `<Text>` 组件在任何平台上呈现文本。
    ```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>`。在进行网络开发时，使用 RNW 是可选的，因为您可以直接使用 React DOM，但我们通常推荐在跨平台构建时使用它，因为它最大化了代码重用。
    > React Native for web 用于支持整个 [X](https://x.com/) 网站。
For 仅适用于 Web: 
    或者，您可以编写仅适用于网页的 React DOM 组件，例如 `<div>`、`<p>` 等，但是这些组件将无法在原生平台上呈现。
    ```jsx app/index.js
    export default function Page() {
      return <p>Home page</p>;
    }
    ```
    Expo 完全支持构建仅适用于 Web 的组件，然而，您可能希望组织您的代码，以更好地支持同时为 Web 和原生平台构建。有关更多信息，请参阅 [平台特定模块](/router/advanced/platform-specific-modules)。
Expo SDK 中的所有库都构建支持浏览器和服务器渲染环境（如适用）。库也针对它们所针对的各个平台进行了优化。
快速刷新、调试、环境变量和 [打包](/guides/customizing-metro) 等开发功能也完全通用，使开发者体验统一。Expo CLI **会自动优化代码**，以针对单个平台构建生产版本，使用 [平台摇动](/guides/tree-shaking#platform-shaking) 等技术。
## 入门
### 安装 Web 依赖
```sh
$ npx expo install react-dom react-native-web @expo/metro-runtime
```
Note: 还没有在您的应用中使用  包吗？
---
如果您还没有将 Expo 添加到您的 React Native 应用中，您可以选择 [安装 Expo 模块](/bare/installing-expo-modules/)（推荐）或仅安装 `expo` 包并配置应用入口文件。这将允许您面向 Web，但不会包含对 Expo SDK 的支持。
1. 在您的项目中安装 [Expo CLI](/more/expo-cli/)：
```sh
$ npm install expo
```
2. 修改入口文件以使用 [`registerRootComponent`](/versions/latest/sdk/expo/#registerrootcomponentcomponent) 而不是 `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);
```
---
### 启动开发服务器
您现在可以启动开发服务器并在浏览器中进行开发：
```sh
$ npx expo start --web
```
应用可以导出为生产网站：
```sh
$ npx expo export --platform web
```
## 下一步


## 发布网站

学习如何将 Expo 网站部署为生产环境。

Expo 网络应用可以在本地进行测试以验证生产行为，并部署到托管服务。我们建议将其部署到 [EAS Hosting](/eas/hosting) 以获得最佳功能支持。您还可以选择自托管或使用第三方服务。
> 对于 SDK 49 及更早版本，您可能需要查看 [发布 `webpack` 构建的指南](/archive/publishing-websites-webpack/)。
## 输出目标
[`web.output`](/versions/latest/config/app/#output) 目标可以在 [应用配置](/workflow/configuration/) 中进行配置，以设置网络应用的导出方法：
```json app.json
{
  "expo": {
    "web": {
      "output": "server",
      "bundler": "metro"
    }
  }
}
```
Expo Router 支持网络应用的三种输出目标。
| 输出            | Expo Router | API 路由    | 描述                                                                                                                                          |
| --------------- | ----------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `single` (默认) | <YesIcon /> | <NoIcon />  | 输出单页应用（SPA），在输出目录中只有一个 **index.html**，没有静态可索引的 HTML。                                                             |
| `server`        | <YesIcon /> | <YesIcon /> | 创建 **client** 和 **server** 目录。客户端文件作为单独的 HTML 文件输出。API 路由作为单独的 JavaScript 文件，用于自定义 Node.js 服务器的托管。 |
| `static`        | <YesIcon /> | <NoIcon />  | 为 **app** 目录中的每个路由输出单独的 HTML 文件。                                                                                             |
## 创建构建
创建项目的构建是发布网络应用的第一步。无论您想在本地提供服务还是部署到托管服务，您都需要导出项目的所有 JavaScript 和资产。这被称为静态打包。可以通过运行以下命令导出：
运行通用导出命令以编译项目以适应网络：
```sh
$ npx expo export -p web
```
生成的项目文件位于 **dist** 目录中。任何在 **public** 目录中的文件也会复制到 **dist** 目录中。
## 本地服务
使用 `npx expo serve` 快速测试您的网站在生产中将如何托管。运行以下命令以提供静态打包服务：
```sh
$ npx expo serve
```
打开 [`http://localhost:8081`](http://localhost:8081) 查看您的项目运行情况。此为 **仅 HTTP**，因此权限、相机、位置和许多其他安全功能可能无法按预期工作。
## 使用 EAS 托管
当您准备好投入生产时，可以使用 EAS CLI 立即部署您的网站。
## 在第三方服务上托管
### Netlify
[Netlify](https://www.netlify.com/) 是一个几乎不干预的平台，用于部署网络应用。它对 Expo 网络应用的兼容性最高，因为它对框架几乎没有假设。
#### 使用 Netlify CDN 手动部署
Step 1: 
通过运行以下命令安装 Netlify CLI：
```sh
$ npm install -g netlify-cli
```
Step 2: 
为单页应用配置重定向。
> 如果您的应用使用 [静态渲染](/router/reference/static-rendering)，则可以跳过此步骤。
`expo.web.output: 'single'` 生成单页应用。这意味着只有一个 **dist/index.html** 文件需要重定向所有请求。这可以在 Netlify 中通过创建一个 **./public/\_redirects** 文件并将所有请求重定向到 **/index.html** 来完成。
```sh public/_redirects
/*    /index.html   200
```
如果您修改了此文件，则必须通过 `npx expo export -p web` 重新构建项目，以确保它被安全复制到 **dist** 目录中。
Step 3: 
通过运行以下命令部署网络构建目录：
```sh
$ netlify deploy --dir dist
```
您将看到一个可用于在线查看项目的 URL。
#### 持续交付
Netlify 还可以在您推送到 Git 或打开新的拉取请求时进行构建和部署：
- [开始一个新的 Netlify 项目](https://app.netlify.com/signup)。
- 选择您的 Git 托管服务并选择您的存储库。
- 点击 **Build your site**。
### Vercel
[Vercel](https://vercel.com/) 具有单命令部署流程。
Step 1: 
安装 [Vercel CLI](https://vercel.com/docs/cli)。
```sh
$ npm install -g vercel@latest
```
Step 2: 
  为单页应用配置重定向。
在应用的根目录下创建一个 **vercel.json** 文件，并添加以下配置：
```json vercel.json
{
  "buildCommand": "expo export -p web",
  "outputDirectory": "dist",
  "devCommand": "expo",
  "cleanUrls": true,
  "framework": null,
  "rewrites": [
    {
      "source": "/:path*",
      "destination": "/"
    }
  ]
}
```
如果您的应用使用 [静态渲染](/router/reference/static-rendering)，则可能需要添加其他 [动态路由配置](/router/reference/static-rendering#dynamic-routes)。
Step 3: 
  部署网站。
{' '}
```sh
$ vercel
```
现在您将看到一个可用于在线查看项目的 URL。当构建完成后，将该 URL 粘贴到浏览器中，您将看到已部署的应用。
### AWS Amplify 控制台
[AWS Amplify 控制台](https://console.amplify.aws) 提供了基于 Git 的工作流，用于持续部署和托管全栈无服务器网络应用。Amplify 从存储库而不是从您的计算机部署您的 PWA。在本指南中，我们将使用 GitHub 存储库。在开始之前，[在 GitHub 上创建一个新仓库](https://github.com/new)。
Step 1: 
将 [**amplify-explicit.yml**](https://github.com/expo/amplify-demo/blob/master/amplify-explicit.yml) 文件添加到您存储库的根目录。确保您已从 **.gitignore** 文件中删除生成的 **dist** 目录并提交了这些更改。
Step 2: 
将您的本地 Expo 项目推送到 GitHub 存储库。如果您尚未推送到 GitHub，请遵循 [GitHub 的指南将现有项目添加到 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: 
登录到 [Amplify 控制台](https://console.aws.amazon.com/amplify/home)，选择一个现有的应用或创建一个新应用。授予 Amplify 读取您 GitHub 账户或拥有您存储库的组织的权限。
Step 4: 
添加您的存储库，选择分支，并在 **Connecting a monorepo?** 中输入您的应用 **dist** 目录的路径，然后选择 **Next**。
Amplify 控制台将检测到您项目中的 **amplify.yml** 文件。选择 **Allow AWS Amplify to automatically deploy all files hosted in your project root directory** 并选择 **Next**。
Step 5: 
检查您的设置并选择 **Save and deploy**。您的应用现在将部署到 `https://branchname.xxxxxx.amplifyapp.com` URL。您现在可以访问您的网络应用，部署另一个分支，或在您的 Expo 移动和网络应用之间添加统一的后端环境。
按照 **Learn how to get the most out of Amplify Hosting** 下拉列表中的步骤 **Add a custom domain with a free SSL certificate** 及更多信息。
### Firebase 托管
[Firebase Hosting](https://console.firebase.google.com/) 是用于网络项目的生产级内容托管。
Step 1: 
通过 [Firebase 控制台](https://console.firebase.google.com) 创建一个 Firebase 项目，并按照这些 [说明](https://firebase.google.com/docs/hosting) 安装 Firebase CLI。
Step 2: 
使用 CLI 登录到您的 Firebase 账户，运行命令：
```sh
$ firebase login
```
Step 3: 
然后，通过运行命令初始化您的 Firebase 项目以进行托管：
```sh
$ firebase init
```
设置将取决于您如何构建 Expo 网站：
1. 当询问公共路径时，请确保指定 **dist** 目录。
2. 当提示 **Configure as a single-page app (rewrite all urls to /index.html)** 时，仅当您使用 `web.output: "single"`（默认）时才选择 **Yes**。否则，选择 **No**。
Step 4: 
在 **package.json** 的现有 `scripts` 属性中，添加 `predeploy` 和 `deploy` 属性。每个属性具有以下值：
```json package.json
"scripts": {
  "predeploy": "expo export -p web",
  "deploy-hosting": "npm run predeploy && firebase deploy --only hosting",
}
```
Step 5: 
要部署，请运行以下命令：
```sh
$ npm run deploy-hosting
```
打开控制台输出中的 URL 检查您的部署，例如：`https://project-name.firebaseapp.com`。
如果您想更改托管的标题，请在 **firebase.json** 的 `hosting` 部分添加以下配置：
```json firebase.json
  "hosting": [
    {
      "headers": [
        {
          "source": "/**",
          "headers": [
            {
              "key": "Cache-Control",
              "value": "no-cache, no-store, must-revalidate"
            }
          ]
        },
        {
          "source": "**/*.@(jpg|jpeg|gif|png|svg|webp|js|css|eot|otf|ttf|ttc|woff|woff2|font.css)",
          "headers": [
            {
              "key": "Cache-Control",
              "value": "max-age=604800"
            }
          ]
        }
      ],
    }
  ]
```
### GitHub Pages
[GitHub Pages](https://pages.github.com/) 允许您直接从 GitHub 存储库发布网站。
> **warning** GitHub Pages 部署使用实验性 `baseUrl` 功能，可能无法按预期工作。
Step 1: 
首先在您的项目中初始化一个新的 git 存储库，并将其配置为推送到 GitHub 存储库。如果您已经在与 GitHub 存储库同步您的更改，请跳过此步骤。
在 GitHub 网站上创建一个存储库。然后，在项目的根目录中运行以下命令：
```sh
$ git init
$ git remote add origin https://github.com/username/expo-gh-pages.git
```
上述命令初始化了一个新的 Git 存储库，并将其配置为将您的源代码推送到指定的 GitHub 存储库。
Step 2: 
将在项目中安装 `gh-pages` 包作为开发依赖：
For npm: 
```sh
$ npm install --save-dev gh-pages
```
For Yarn: 
```sh
$ yarn add -D gh-pages
```
Step 3: 
要部署该项目，请在 [应用配置](/workflow/configuration/) 中将其配置为子域，在 [`baseUrl`](/versions/latest/config/app/#baseurl) 属性中设置其值为字符串 `/repo-name`。
例如，如果 GitHub 存储库是 `expo-gh-pages`，则 [实验性 `baseUrl` 属性](/more/expo-cli/#hosting-with-sub-paths) 的值将如下：
```json app.json
{
  "expo": {
    "experiments": {
      "baseUrl": "/expo-gh-pages"
    }
  }
}
```
Step 4: 
通过在 **package.json** 文件中修改 `scripts`，添加 `predeploy` 和 `deploy` 脚本。每个脚本都有自己的值：
```json package.json
"scripts": {
  "deploy": "gh-pages --nojekyll -d dist",
  "predeploy": "expo export -p web"
}
```
因为 Expo 在生成的文件中使用下划线，所以您需要使用 `--nojekyll` 标志禁用 Jekyll。
Step 5: 
要生成网络应用的生产构建并将其部署到 GitHub Pages，运行以下命令：
For npm: 
```sh
$ npm run deploy
```
For Yarn: 
```sh
$ yarn deploy
```
这将在您 GitHub 存储库的 `gh-pages` 分支上发布网络应用的构建。此分支只包含来自 **dist** 目录的构建构件，以及 `gh-pages` 生成的 **.nojekyll** 文件。它不包括开发源代码。
Step 6: 
现在网络应用已发布到 `gh-pages` 分支，配置 GitHub Pages 从该分支提供应用。
- 导航到 GitHub 存储库的 **Settings** 选项卡。
- 向下滚动到 **Pages** 部分。
- 确保 **Source** 设置为 **Deploy from a branch**。
- 在 **Branch** 部分，选择 **gh-pages** 和 **root** 目录。
- 点击 **Save**。
Step 7: 
一旦网络应用发布并设置了 GitHub Pages 配置，GitHub Action 将部署您的网站。您可以通过导航到存储库的 **Actions** 选项卡来监控其进度。完成后，您的网络应用将可在 URL `http://username-on-github.github.io/repo-name` 上访问。
对于后续的部署和更新，运行 `deploy` 命令，GitHub Action 将自动开始更新您的网络应用。


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

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

> **info** 可用于 **SDK 52 及更高版本**。
Expo 提供了一种新颖的方法，可以通过 `'use dom'` 指令直接在原生应用中使用现代网页代码。这使得可以通过逐个组件的方式将整个网站逐步迁移到通用应用程序中。
虽然 Expo 原生运行时通常不支持像 `<div>` 或 `<img>` 这样的元素，但可能会有需要快速整合网页组件的情况。在这种情况下，DOM 组件提供了一种有用的解决方案。
## 前提条件
Note: 您的项目必须使用 Expo CLI 并扩展 Expo Metro Config
---
如果您已经使用 `npx expo [command]` 运行项目（例如，如果您是通过 `npx create-expo-app` 创建的），那么您已经准备就绪，可以跳过此步骤。
如果您的项目中还没有 `expo` 包，请通过运行下面的命令安装它，并 [选择使用 Expo CLI 和 Metro Config](/bare/installing-expo-modules/#configure-expo-cli-for-bundling-on-android-and-ios):
```sh
$ npx install-expo-modules@latest
```
如果命令失败，请参阅 [安装 Expo 模块](/bare/installing-expo-modules/#manual-installation) 指南。
---
Note: Expo Metro Runtime, React DOM, 和 React Native Web
---
如果您正在使用 Expo Router 和 Expo Web，您可以跳过此步骤。否则，请安装以下软件包：
```sh
$ npx expo install @expo/metro-runtime react-dom react-native-web
```
---
## 使用方法
在您的项目中安装 `react-native-webview`：
```sh
$ npx expo install react-native-webview
```
要将 React 组件渲染到 DOM，请在网页组件文件的顶部添加 `'use dom'` 指令：
```tsx my-component.tsx (web)
'use dom';
export default function DOMComponent({ name }: { name: string }) {
  return (
    <div>
      <h1>Hello, {name}</h1>
    </div>
  );
}
```
在原生组件文件中，导入网页组件以使用它：
```tsx App.tsx (native)
import DOMComponent from './my-component.tsx';
export default function App() {
  return (
    // 这是一个 DOM 组件。它在后台重新导出一个被包裹的 `react-native-webview`。
    <DOMComponent name="Europa" />
  );
}
```
## 特征
- 跨网页、原生和 DOM 组件的共享捆绑器配置。
- DOM 组件中启用 React、TypeScript、CSS 和所有其他 Metro 特性。
- 在终端和 Safari/Chrome 调试中日志记录。
- 快速刷新和 HMR。
- 用于离线支持的嵌入式导出。
- 资产在网页和原生之间统一。
- DOM 组件捆绑可以在 [Expo Atlas](/guides/analyzing-bundles/#analyzing-bundle-size-with-atlas) 中进行检查以进行调试。
- 访问所有网页功能而无需进行原生重建。
- 开发中的运行时错误覆盖。
- 支持 Expo Go。
## WebView 属性
要将属性传递给底层原生 **WebView**，请在组件上使用 `dom` 属性。这个属性内置于每个 DOM 组件中，并接受一个包含任意 [`WebView` 属性](https://github.com/react-native-webview/react-native-webview/blob/master/docs/Reference.md) 的对象，以便您进行更改。
```tsx App.tsx (native)
import DOMComponent from './my-component';
export default function App() {
  return (
    <DOMComponent
      dom={{
        scrollEnabled: false,
      }}
    />
  );
}
```
在您的 DOM 组件中，添加 `dom` 属性以在 TypeScript 中识别：
```tsx my-component.tsx (web)
'use dom';
export default function DOMComponent({}: { dom: import('expo/dom').DOMProps }) {
  return (
    <div>
      <h1>Hello, world!</h1>
    </div>
  );
}
```
## 可序列化的属性
您可以通过可序列化的属性（`number`，`string`，`boolean`，`null`，`undefined`，`Array`，`Object`）将数据发送到 DOM 组件。例如，在原生组件文件中，您可以将属性传递给 DOM 组件：
```tsx App.tsx (native)
import DOMComponent from './my-component';
export default function App() {
  return <DOMComponent hello={'world'} />;
}
```
在网页组件文件中，您可以如下接收属性：
```tsx my-component.tsx (web)
'use dom';
export default function DOMComponent({ hello }: { hello: string }) {
  return <p>Hello, {hello}</p>;
}
```
属性通过异步桥传送，因此不会同步更新。它们作为属性传递给 React 根组件，这意味着它们会重新渲染整个 React 树。
## 原生操作
您可以通过将异步函数作为顶层属性传递给 DOM 组件，将类型安全的原生函数发送到 DOM 组件：
```tsx App.tsx (native)
import DomComponent from './my-component';
export default function App() {
  return (
    <DomComponent
      hello={(data: string) => {
        console.log('Hello', data);
      }}
    />
  );
}
```
```tsx my-component.tsx (web)
'use dom';
export default function MyComponent({ hello }: { hello: (data: string) => Promise<void> }) {
  return <p onClick={() => hello('world')}>Click me</p>;
}
```
> 您不能将函数作为嵌套属性传递给 DOM 组件。它们必须是顶层属性。
原生操作始终是异步的，并且只接受可序列化的参数（意思是没有函数），因为数据通过桥发送到 DOM 组件的 JavaScript 引擎。
原生操作可以将可序列化的数据返回给 DOM 组件，这对于从原生侧获取数据非常有用。
```tsx
getDeviceName(): Promise<string> {
  return DeviceInfo.getDeviceName();
}
```
可以将这些函数视为 React 服务器函数，但它们不是驻留在服务器上，而是本地存在于原生应用中，并与 DOM 组件进行通信。这种方法提供了一种将真正原生功能添加到您的 DOM 组件的强大方式。
## 传递 refs
> **important** 这是实验性的，未来可能会更改。
您可以在 DOM 组件中使用 `useDOMImperativeHandle` 钩子，以接受来自原生侧的 ref 调用。这个钩子类似于 React 的 [`useImperativeHandle`](https://react.dev/reference/react/useImperativeHandle) 钩子，但不需要传递 ref 对象。
```tsx App.tsx (native)
import { useRef } from 'react';
import { Button, View } from 'react-native';
import MyComponent, { type DOMRef } from './my-component';
export default function App() {
  const ref = useRef<DOMRef>(null);
  return (
    <View style={{ flex: 1 }}>
      <MyComponent ref={ref} />
      <Button
        title="focus"
        onPress={() => {
          ref.current?.focus();
        }}
      />
    </View>
  );
}
```
For SDK 53 及更高版本: 
Expo SDK 53 及更高版本使用 React 19。这意味着 `ref` 属性作为属性传递给组件，您可以直接在组件中使用它。
```tsx my-component.tsx (web)
'use dom';
import { useDOMImperativeHandle, type DOMImperativeFactory } from 'expo/dom';
import { Ref, useRef } from 'react';
export interface DOMRef extends DOMImperativeFactory {
  focus: () => void;
}
export default function MyComponent(props: {
  ref: Ref<DOMRef>;
  dom?: import('expo/dom').DOMProps;
}) {
  const inputRef = useRef<HTMLInputElement>(null);
  useDOMImperativeHandle(
    props.ref,
    () => ({
      focus: () => {
        inputRef.current?.focus();
      },
    }),
    []
  );
  return <input ref={inputRef} />;
}
```
For SDK 52 及更早版本: 
在 Expo SDK 52 及更早版本（React 18）中，使用传统的 `forwardRef` 函数来访问 `ref` 句柄。
```tsx my-component.tsx (web)
'use dom';
import { useDOMImperativeHandle, type DOMImperativeFactory } from 'expo/dom';
import { forwardRef, useRef } from 'react';
export interface MyRef extends DOMImperativeFactory {
  focus: () => void;
}
export default forwardRef<MyRef, object>(function MyComponent(props, ref) {
  const inputRef = useRef<HTMLInputElement>(null);
  useDOMImperativeHandle(
    ref,
    () => ({
      focus: () => {
        inputRef.current?.focus();
      },
    }),
    []
  );
  return <input ref={inputRef} />;
});
```
React 的数据流是单向的，因此使用回调向上树返回的概念不是符合惯例的。预计行为可能不稳定，并可能在将来的新版本的 React 中逐步淘汰。向上发送数据的首选方式是使用原生操作，它们更新状态，然后将状态传递回 DOM 组件。
## 功能检测
由于 DOM 组件用于运行网站，您可能需要额外的限定符以更好地支持某些库。您可以用以下代码检测组件是否在 DOM 组件中运行：
```ts
import { IS_DOM } from 'expo/dom';
```
虽然 `process.env.EXPO_OS` 在 DOM 组件中始终为 web，但您可以通过 `process.env.EXPO_DOM_HOST_OS` 检测 _顶层_ 平台。它将是 `ios`、`android`，具体取决于最顶层的原生平台的操作系统，而在 web 上为 `undefined`。
## 公共资产
> **important** **警告：** 这是实验性的，将来可能会更改。公共资产在 EAS 更新中不受支持。请使用 `require()` 加载本地资产。
根 **public** 目录的内容复制到原生应用的二进制文件中，以支持在 DOM 组件中使用公共资产。由于这些公共资产将从本地文件系统提供，使用 `process.env.EXPO_BASE_URL` 前缀引用正确的路径。例如：
```tsx
<img src={`${process.env.EXPO_BASE_URL}img.png`} />
```
## 调试
默认情况下，所有 `console.log` 方法在 WebView 中被扩展，以将日志转发到终端。这使得快速查看您的 DOM 组件中发生了什么变得简单且方便。
Expo 还在开发模式下捆绑时启用 WebView 检查和调试。您可以打开 **Safari** > **Develop** > **Simulator** > **MyComponent.tsx** 来查看 WebView 的控制台并检查元素。
## 手动 WebViews
您可以使用来自 `react-native-webview` 的 `WebView` 组件创建手动 WebView。这对于从远程服务器渲染网站可能很有用。
```tsx App.tsx (native)
import { WebView } from 'react-native-webview';
export default function App() {
  return <WebView source={{ html: '<h1>Hello, world!</h1>' }} />;
}
```
## 路由
Expo Router API，如 `<Link />` 和 `useRouter` 可以在 DOM 组件中用于在路由之间导航。
```tsx my-component.tsx (web)
'use dom';
import Link from 'expo-router/link';
export default function DOMComponent() {
  return (
    <div>
      <h1>Hello, world!</h1>
      <Link href="/about">About</Link>
    </div>
  );
}
```
像 `useLocalSearchParams()`、`useGlobalSearchParams()`、`usePathname()`、`useSegments()`、`useRootNavigation()` 和 `useRootNavigationState()` 等同步返回路由信息的 API 不会自动支持。相反，您需要在 DOM 组件外部读取这些值并将其作为属性提供。
```tsx App.tsx (native)
import DOMComponent from './my-component';
import { usePathname } from 'expo-router';
export default function App() {
  const pathname = usePathname();
  return <DOMComponent pathname={pathname} />;
}
```
`router.canGoBack()` 和 `router.canDismiss()` 函数也不受支持，需要手动序列化，这样可以确保不会触发多余的渲染周期。
避免使用标准网页 `<a />` 锚元素进行导航，因为这将以用户可能无法返回的方式更改 DOM 组件的源。如果您想呈现外部网站，建议直接启动 `WebBrowser`。
由于 DOM 组件无法呈现原生子组件，因此布局路由 (`_layout`) 永远不能是 DOM 组件。您可以从布局路由中渲染 DOM 组件，以创建标题、背景等，但是布局路由本身应该始终是原生的。
## 测量 DOM 组件
您可能希望测量 DOM 组件的大小并报告回原生侧（例如，原生滚动）。可以使用 `matchContents` 属性或手动原生操作来实现这一点：
### 自动使用 `matchContents` 属性
您可以使用 `dom={{ matchContents: true }}` 属性自动测量 DOM 组件的大小并调整原生视图的大小。这在某些布局中特别有用，在这些布局中，DOM 组件必须具有内在大小才能显示，例如当组件在父视图中居中时：
```tsx App.tsx (native)
import DOMComponent from './my-component';
export default function Route() {
  return <DOMComponent dom={{ matchContents: true }} />;
}
```
### 手动指定大小
您还可以通过将大小传递给 `WebView` 的 `style` 属性，手动提供大小：
```tsx App.tsx (native)
import DOMComponent from './my-component';
export default function Route() {
  return (
    <DOMComponent
      dom={{
        style: { width, height },
      }}
    />
  );
}
```
### 观察大小变化
如果您希望将 DOM 组件的大小变化报告回原生侧，您可以在 DOM 组件中添加一个原生操作，该操作在大小发生变化时调用：
```tsx my-component.tsx (web)
'use dom';
import { useEffect } from 'react';
function useSize(callback: (size: { width: number; height: number }) => void) {
  useEffect(() => {
    // 观察窗口大小变化
    const observer = new ResizeObserver(entries => {
      for (const entry of entries) {
        const { width, height } = entry.contentRect;
        callback({ width, height });
      }
    });
    observer.observe(document.body);
    callback({
      width: document.body.clientWidth,
      height: document.body.clientHeight,
    });
    return () => {
      observer.disconnect();
    };
  }, [callback]);
}
export default function DOMComponent({
  onDOMLayout,
}: {
  dom?: import('expo/dom').DOMProps;
  onDOMLayout: (size: { width: number; height: number }) => void;
}) {
  useSize(onDOMLayout);
  return <div style={{ width: 500, height: 500, background: 'blue' }} />;
}
```
然后更新您的原生代码，以便在 DOM 组件报告大小变化时在状态中设置大小：
```tsx App.tsx (native)
import DOMComponent from '@/components/my-component';
import { useState } from 'react';
import { View, ScrollView } from 'react-native';
export default function App() {
  const [containerSize, setContainerSize] = useState<{
    width: number;
    height: number;
  } | null>(null);
  return (
    <View style={{ flex: 1 }}>
      <ScrollView>
        <DOMComponent
          onDOMLayout={async ({ width, height }) => {
            if (containerSize?.width !== width || containerSize?.height !== height) {
              setContainerSize({ width, height });
            }
          }}
          dom={{
            containerStyle:
              containerSize != null
                ? { width: containerSize.width, height: containerSize.height }
                : null,
          }}
        />
      </ScrollView>
    </View>
  );
}
```
## 体系结构
内置的 DOM 支持仅以单页面应用程序的形式呈现网站（不支持 SSR 或 SSG）。这是因为搜索引擎优化和索引对嵌入的 JS 代码来说是不必要的。
当一个模块标记为 `'use dom'` 时，它将被在运行时导入的代理引用所替代。此功能主要是通过一系列捆绑和 CLI 技术来实现的。
如果需要，您仍然可以通过将原始 HTML 传递给 `WebView` 组件来使用标准方法使用 WebView。
在网站或其他 DOM 组件中渲染的 DOM 组件将如常规组件一样运行，并且 `dom` 属性将被忽略。这是因为网页内容直接通过传递，而不是包裹在 `iframe` 中。
总体而言，这个系统与 Expo 的 React 服务器组件实现有许多相似之处。
## 注意事项
我们建议使用通用原语（如 `View`、`Image` 和 `Text`）来构建真正的原生应用。DOM 组件仅支持标准 JavaScript，这比优化后的 Hermes 字节码解析和启动速度慢。
可以通过异步 JSON 传输系统在 DOM 组件和原生组件之间发送数据。避免依赖于跨 JS 引擎和对 DOM 组件中嵌套 URL 的深度链接，因为它们当前不支持与 Expo Router 的完整协调。
虽然 DOM 组件并非仅限于 Expo Router，但它们是在 Expo Router 应用程序中开发和测试的，以提供在与 Expo Router 一起使用时的最佳体验。
如果您有一个共享数据的全局状态，它将无法跨 JS 引擎访问。
虽然 Expo SDK 中的原生模块可以被优化以支持 DOM 组件，但该优化尚未实施。使用原生操作和属性将原生功能与 DOM 组件共享。
DOM 组件和网站通常不如原生视图优化，但它们有一些合理的用法。例如，网络在渲染富文本和 markdown 方面在概念上是最好的方式。网络还具有非常好的 WebGL 支持，前提是低功耗模式下的设备通常会限制网页帧率以节省电池。
许多大型应用程序还使用一些网页内容作为辅助路由，例如博客文章、富文本（例如，长篇 X 帖子）、设置页面、帮助页面以及应用程序中其他不太常访问的部分。
## 服务器组件
当前，DOM 组件仅以单页面应用程序形式渲染，不支持静态渲染或 React 服务器组件（RSC）。当项目使用 React 服务器组件时，`'use dom'` 将与 `'use client'` 一样工作，无论平台如何。RSC 负载可以作为属性传递给 DOM 组件。但在原生平台上无法正确水合，因为它们将被渲染为原生运行时。
## 限制
- 与服务器组件不同，您无法将 `children` 传递给 DOM 组件。
- DOM 组件是独立的，不能在不同实例之间自动共享数据。
- 您不能将原生视图添加到 DOM 组件。虽然您可以尝试将原生视图漂浮在 DOM 组件上，但这种方法会导致用户体验不佳。
- 函数属性不能同步返回值。它们必须是异步的。
- 当前，DOM 组件只能被嵌入，不支持 OTA 更新。此功能可能在将来的 React 服务器组件中添加。
最终，通用架构是最令人兴奋的类型。Expo CLI 的广泛通用工具是我们能够提供如此复杂且有价值的功能的唯一原因。
虽然 DOM 组件有助于迁移和快速移动，但我们建议尽可能使用真正的原生视图。
## 常见问题
### 如何在 DOM 组件中获取安全上下文？
一些 Web API 需要 [安全上下文](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) 才能正常工作。例如，只有在安全上下文中才能使用 [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API)。安全上下文意味着远程资源必须通过 HTTPS 提供。[了解更多有关限制在安全上下文中的特性](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts)。
为了确保您的 DOM 组件在安全上下文中运行，请遵循以下指南：
- **发布构建**：使用 `file://` 方案提供的 DOM 组件默认具有安全上下文。
- **调试构建**：当使用开发服务器（默认使用 `http://` 协议）时，您可以使用 [隧道](/more/expo-cli/#tunneling) 通过 HTTPS 提供 DOM 组件。
Note: 通过 HTTPS 隧道 DOM 组件的示例命令
---
```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 网站添加渐进式网页应用支持。

渐进式网页应用（简称 PWA）是可以安装在用户设备上并离线使用的网站。我们建议尽可能构建原生应用，因为它们具有最佳的离线支持，但 PWA 对桌面用户来说是一个很好的选择。
## 网站图标
Expo CLI 会根据 **app.json** 中的 `web.favicon` 字段自动生成 **favicon.ico** 文件。
```json
{
  "web": {
    "favicon": "./assets/favicon.png"
  }
}
```
或者，您可以在 **public** 目录中创建一个 **favicon.ico** 文件以手动指定图标。
## 清单文件
PWA 可以通过 [清单文件](https://developer.mozilla.org/en-US/docs/Web/Manifest) 进行配置，该文件描述了应用的名称、图标和其他元数据。
Step 1: 
在 **public/manifest.json** 中创建一个 PWA 清单：
```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: 
文件 **logo192.png** 和 **logo512.png** 是在用户设备上安装应用时使用的图标。这些文件也应添加到 **public** 目录中。
```
public/
    ├── manifest.json  # PWA 清单
    ├── logo192.png  # 192x192 图标
    └── logo512.png  # 512x512 图标
```
Step 3: 
现在在您的 HTML 文件中链接清单。方法取决于您网站的输出模式（在 **app.json** 中的 `web.output` 指定，默认为 `single`）。
For single: 
如果您正在使用单页面应用，可以通过在 **public/index.html** 中创建一个模板 HTML 来链接清单：
```sh
$ npx expo customize public/index.html
```
然后将清单添加到 `<head>` 标签中：
```html
<link rel="manifest" href="/manifest.json" />
```
For static & server: 
如果您正在使用静态或服务器渲染，可以在 **app/+html.tsx** 中动态创建 HTML 入口。在这里，我们将通过将 `<link>` 标签添加到 `<head>` 组件来链接清单：
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import type { PropsWithChildren } from 'react';
// 此文件仅限于 Web，用于配置每个
// 网页在静态渲染期间的根 HTML。
// 此函数的内容仅在 Node.js 环境中运行，
// 并且无法访问 DOM 或浏览器 API。
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" />
        {/* 链接 PWA 清单文件。 */}
        <link rel="manifest" href="/manifest.json" />
        {/*
          在 Web 上禁用主体滚动。这使得 ScrollView 组件的工作方式更接近于原生。
          然而，主体滚动在移动 Web 上通常是不错的选择。如果您想启用它，请删除此行。
        */}
        <ScrollViewStyleReset />
        {/* 添加任何您希望在 Web 上全局可用的额外 <head> 元素... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
```
## 服务工作者
服务工作者主要用于为网站添加离线支持。谷歌的 Workbox 是将服务工作者添加到网站的最佳方式。请遵循 [使用 Workbox CLI 的指南](https://developer.chrome.com/docs/workbox/modules/workbox-cli/)，在提到“构建脚本”的地方，将其替换为 `npx expo export -p web`。
> **warning** 添加服务工作者时请小心，因为它们已知会导致 Web 上的意外行为。如果您意外发布了一个强力缓存您网站的服务工作者，用户将无法轻松请求更新。为了获得最佳的离线移动体验，请使用 Expo 创建原生应用。与有服务工作者的网站不同，原生应用可以通过应用商店进行更新，以清除缓存的体验。这类似于重置用户的原生浏览器（如果服务工作者足够强力，他们可能不得不这样做）。有关更多信息，请参见 [为什么服务工作者是次优的](https://github.com/facebook/create-react-app/issues/2398)。
例如，以下是设置 Workbox 的可能流程：
Step 1: 
使用以下命令创建一个新项目：
```sh
$ npm create expo -t tabs my-app
$ cd my-app
```
Step 2: 
现在在 HTML 文件中注册服务工作者。方法取决于您网站的输出模式（在 **app.json** 中的 `web.output` 指定，默认为 `single`）。
For single: 
接下来，在根 **index.html** 中添加服务工作者注册脚本。
如果尚未存在，则首先在 **public/index.html** 中创建一个模板 HTML：
```sh
$ npx expo customize public/index.html
```
然后在 `<head>` 标签中创建服务工作者注册脚本：
```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: 
接下来，为应用创建一个根 HTML 文件，并添加服务工作者注册脚本：
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import type { PropsWithChildren } from 'react';
// 此文件仅限于 Web，用于配置每个
// 网页在静态渲染期间的根 HTML。
// 此函数的内容仅在 Node.js 环境中运行，
// 并且无法访问 DOM 或浏览器 API。
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" />
        {/* 启动服务工作者。 */}
        <script dangerouslySetInnerHTML={{ __html: sw }} />
        {/*
          在 Web 上禁用主体滚动。这使得 ScrollView 组件的工作方式更接近于原生。
          然而，主体滚动在移动 Web 上通常是不错的选择。如果您想启用它，请删除此行。
        */}
        <ScrollViewStyleReset />
        {/* 添加任何您希望在 Web 上全局可用的额外 <head> 元素... */}
      </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: 
现在在运行向导之前构建网站：
```sh
$ npx expo export -p web
```
Step 4: 
运行向导命令，选择 `dist` 作为应用的根目录，并选择其他所有项的默认值：
```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: 
最后，运行 `npx workbox-cli generateSW workbox-config.js` 以生成服务工作者配置。
今后，您可以在 **package.json** 中添加构建脚本，以按正确顺序运行这两个脚本：
```json package.json
{
  "scripts": {
    "build:web": "expo export -p web && npx workbox-cli generateSW workbox-config.js"
  }
}
```
Step 6: 
如果您托管网站并使用 Chrome 访问，可以通过前往 Chrome DevTools 中的 **Application > Service Workers** 来检查服务工作者。


## Tailwind CSS

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

> **info** 标准的 Tailwind CSS 仅支持网页平台。要实现通用支持，请使用像 [NativeWind](https://www.nativewind.dev/) 这样的库，它支持使用 Tailwind CSS 创建样式化的 React Native 组件。
[Tailwind CSS](https://tailwindcss.com/) 是一个实用优先的 CSS 框架，可以与 Metro 一起用于网页项目。本指南解释了如何配置你的 Expo 项目以使用该框架。
## 前提条件
以下文件将被修改以设置 Tailwind CSS 配置：
```
app.json
package.json
global.css
index.js
```
确保你的项目使用 Metro 来进行网页开发。你可以通过检查 **app.json** 文件中设置为 `metro` 的 `web.bundler` 字段来验证这一点。
```json app.json
{
  "expo": {
    "web": {
      "bundler": "metro"
    }
  }
}
```
## 配置
根据 [Tailwind PostCSS 文档](https://tailwindcss.com/docs/installation/using-postcss) 在你的 Expo 项目中配置 Tailwind CSS。
For v3: 
Step 1: 
安装 `tailwindcss` 及其必要的对等依赖。然后，运行初始化命令以在项目根目录中创建 **tailwind.config.js** 和 **post.config.js** 文件。
```sh
$ npx expo install tailwindcss@3 postcss autoprefixer --dev
$ npx tailwindcss init -p
```
Step 2: 
在 **tailwind.config.js** 中添加所有模板文件的路径。
```js tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // 确保这指向你的源代码
    './app/**/*.{js,tsx,ts,jsx}',
    // 如果你使用一个 `src` 目录，请添加: './src/**/*.{js,tsx,ts,jsx}'
    // 对 `components`、`hooks`、`styles` 或其他任何顶层目录做同样的事
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```
> 如果你使用 Expo Router，可以考虑使用根 **src** 目录来简化此步骤。了解更多关于 [顶级 src 目录](/router/reference/src-directory/) 的信息。
Step 3: 
在你的项目根目录中创建一个 **global.css** 文件，并为 Tailwind 的每一层添加指令：
```css global.css
/* 此文件添加了 Tailwind 正常工作的所需实用类。 */
@tailwind base;
@tailwind components;
@tailwind utilities;
```
Step 4: 
在你的 **app/\_layout.tsx**（如果使用 Expo Router）或 **index.js** 文件中导入 **global.css** 文件：
```tsx
import '../global.css';
```
```tsx
// 在 index.js 文件中导入 global.css 文件：
import './global.css';
```
> **info** 如果你使用 [DOM 组件](/guides/dom-components)，请在每个模块中添加此文件导入，并使用 `"use dom"` 指令，因为它们不共享全局变量。
Step 5: 
现在你可以启动项目，并在你的组件中使用 Tailwind CSS 类。
```sh
$ npx expo start
```
For v4: 
Step 1: 
安装 `tailwindcss` 及其必要的对等依赖：
```sh
$ npx expo install tailwindcss @tailwindcss/postcss postcss --dev
```
Step 2: 
将 Tailwind 添加到你的 PostCSS 配置中
```js postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
```
Step 3: 
创建一个导入 Tailwind CSS 的全局 CSS 文件。
你可以为此文件选择任何名称。使用 **global.css** 是一种常见做法。
```css global.css
@import 'tailwindcss';
```
Step 4: 
在你的 **app/\_layout.tsx**（如果使用 Expo Router）或 **index.js** 文件中导入你的 CSS 文件：
```tsx
// 如果使用 Expo Router，请在 app/_layout.tsx 文件中导入你的 CSS 文件
import '../global.css';
```
```tsx
// 否则在 index.js 文件中导入你的 CSS 文件：
import './global.css';
```
> **info** 如果你使用 [DOM 组件](/guides/dom-components)，请在每个模块中添加此文件导入，并使用 `"use dom"` 指令，因为它们不共享全局变量。
Step 5: 
现在你可以启动项目，并在你的组件中使用 Tailwind CSS 类。
```sh
$ npx expo start
```
## 用法
你可以直接使用 Tailwind 与 React DOM 元素：
```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 网页元素结合使用：
```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>
  );
}
```
## 针对 Android 和 iOS 的 Tailwind
Tailwind 不支持 Android 和 iOS 平台。你可以使用类似 [NativeWind](https://www.nativewind.dev/) 的兼容性库以实现通用支持。
## 针对 Android 和 iOS 的替代方案
或者，你也可以使用 [DOM 组件](/guides/dom-components) 在本地的 `WebView` 中渲染你的 Tailwind 网页代码。
```tsx app/index.tsx
'use dom';
// 别忘了在每个 DOM 组件中导入 global.css 文件。
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>
  );
}
```
## 故障排除
如果你的 **metro.config.js** 中有自定义 `config.cacheStores`，你需要扩展 Expo 超类 `FileStore`：
```js metro.config.js
// 导入支持 PostCSS 的 Expo 超类。
const { FileStore } = require('@expo/metro-config/file-store');
config.cacheStores = [
  new FileStore({
    root: '/path/to/custom/cache',
  }),
];
module.exports = config;
```
确保你的 **metro.config.js** 中没有禁用 CSS：
```js metro.config.js
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname, {
  // 使用 Tailwind 时请勿禁用 CSS 支持。
  isCSSEnabled: true,
});
```


## 使用本地 HTTPS 开发

学习如何为 Expo Web 应用程序设置本地 HTTPS。

在本地开发 Expo Web 应用程序时，您可能需要在本地开发环境中使用 HTTPS 来测试安全的浏览器 API。本指南将向您展示如何为 Expo Web 应用程序设置本地 HTTPS。
## 前提条件
本指南要求您的机器上安装以下工具：
- `mkcert`：用于创建开发证书的工具。有关安装说明，请参见 [`mkcert` GitHub 仓库](https://github.com/FiloSottile/mkcert#installation)。
## 优势
- **团队可扩展性**：相同的设置适用于每个人
- **身份验证支持**：仅限 HTTP 的 Cookie 和安全上下文
- **生产环境一致性**：与您的生产 HTTPS 环境匹配
- **易于共享**：团队中一致的开发 URL
## 设置您的项目
Step 1: 
创建或导航到您的 Expo 项目：
```sh
$ npx create-expo-app@latest example-app
$ cd example-app
$ cd your-expo-project
```
Step 2: 
启动您的 Expo 开发服务器：
```sh
$ npx expo start --web
```
您的应用程序将在 `http://localhost:8081` 上运行。请保持此终端窗口打开。
Step 3: 
使用 `mkcert` 为 localhost 生成证书。在新的终端窗口中从项目的根目录运行以下命令：
```sh
$ mkcert localhost
```
> **info** **提示**：确保在安装 `mkcert` 后运行 `mkcert -install` 以安装本地证书颁发机构（CA）。
这将在项目的根目录中生成两个签名证书文件：`localhost.pem`（证书）和 `localhost-key.pem`（私钥）。
Step 4: 
在项目的根目录中，运行以下命令以启动代理：
```sh
$ npx local-ssl-proxy --source 443 --target 8081 --cert localhost.pem --key localhost-key.pem
```
> **info** **提示**：[`local-ssl-proxy`](https://github.com/cameronhunter/local-ssl-proxy) 是一个创建代理服务器的工具，它将来自 443 端口的 HTTPS 流量转发到您在 8081 端口上的 Expo 开发服务器。
这将创建一个将 HTTPS 流量从 443 端口转发到您在 8081 端口上的 Expo 开发服务器的代理。
Step 5: 
在您的浏览器中打开 `https://localhost` 以访问您的应用程序。您的Expo 应用程序现在正在使用 HTTPS 运行。


# 打包

## 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 等大型应用程序。
## 自定义
你可以通过在项目根目录创建 **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` 以确保版本一致性。
运行以下命令以生成模板文件：
```sh
$ npx expo customize metro.config.js
```
**metro.config.js** 文件如下所示：
```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/)。
## 资产
Metro 将文件解析为源代码或资产。源代码是 JavaScript、TypeScript、JSON 和其他应用程序使用的文件。[资产](/develop/user-interface/assets/) 是图像、字体和其他不应由 Metro 转换的文件。为了适应大规模代码库，Metro 要求所有源代码和资产的扩展必须在启动打包工具之前明确定义。这是通过将 `resolver.sourceExts` 和 `resolver.assetExts` 选项添加到 Metro 配置中来完成的。默认情况下，包含以下扩展：
- [`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)
### 向 `assetExts` 添加更多文件扩展名
最常见的自定义是向 Metro 添加额外的资产扩展名。
在 **metro.config.js** 文件中，将文件扩展名（不带前导 `.`）添加到 `resolver.assetExts` 数组：
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.resolver.assetExts.push(
  // 为 SQLite 数据库添加对 `.db` 文件的支持
  'db'
);
module.exports = config;
```
## 别名
有时你希望将一个导入重定向到另一个模块或文件。这称为别名。由于 Metro 同时为多个平台打包，我们建议使用自定义解析器来处理别名。
在以下示例中，我们将为 `old-module` 添加一个别名指向 `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) => {
  // 确保你调用默认解析器。
  return context.resolveRequest(
    context,
    // 如果存在别名则使用别名。
    ALIASES[moduleName] ?? moduleName,
    platform
  );
};
module.exports = config;
```
如果你只想在某个平台上应用别名，可以检查 `platform` 参数：
```js metro.config.js
config.resolver.resolveRequest = (context, moduleName, platform) => {
  if (platform === 'web') {
    // 仅在为 Web 打包时使用别名。
    return context.resolveRequest(context, ALIASES[moduleName] ?? moduleName, platform);
  }
  // 确保你调用默认解析器。
  return context.resolveRequest(context, moduleName, platform);
};
```
下次重启开发服务器时你会看到这些更改。解析不会被缓存，并且不需要 `--clear` 标志进行更新。如果你使用基于转换的系统，如 `babel-plugin-module-resolver`，你需要清除缓存以查看已应用的更改。
## 包分割
Expo CLI 会根据异步导入自动分割包（仅限Web）。
此技术可以与 Expo Router 一起使用，以根据 **app** 目录中的路由文件自动分割包。它将只加载当前路由所需的代码，并在用户导航到不同页面时延迟加载额外的 JavaScript。有关更多信息，请参见 [异步路由](/router/reference/async-routes)。
## 树摇
## 代码压缩
## Web 支持
Expo CLI 支持使用 Metro 打包网站。这是用于原生应用程序的相同打包工具，并且设计为跨平台通用。它是 Web 项目的推荐打包工具。
### Expo webpack 与 Expo Metro
如果你之前使用已弃用的 `@expo/webpack-adapter` 编写了网站，请查看 [迁移指南](/router/migrate/from-expo-webpack) 和 [对比图表](/router/migrate/from-expo-webpack#expo-cli)。
### 向 Metro 添加 Web 支持
修改你的 [app 配置](/workflow/configuration) 以使用 `expo.web.bundler` 字段启用该功能：
```json app.json
{
  "expo": {
    "web": {
      "bundler": "metro"
    }
  }
}
```
#### 开发
要启动开发服务器，运行以下命令：
```sh
$ npx expo start --web
```
或者，在 Expo CLI 终端 UI 中按 <kbd>W</kbd>。
#### 静态文件
Expo 的 Metro 实现支持通过将静态文件放置在根 **public/** 目录中，从开发服务器托管静态文件。这与许多其他 Web 框架类似。
当使用 `npx expo export` 导出时，**public** 目录的内容将被复制到 **dist/** 目录。这意味着你的应用可以期望相对于主机 URL 获取这些资产。最常见的例子是 **public/favicon.ico**，这通常用于网站渲染标签图标。
你可以通过在项目中创建 **public/index.html** 文件来覆盖 Metro Web 的默认 **index.html**。
未来，这将能够在所有平台上通用，支持 EAS 更新托管。目前，此功能仅基于用于原生应用的静态主机，旧版 Expo 服务更新不支持此功能。
## TypeScript
Expo 的 Metro 配置支持项目的 **tsconfig.json**（或 **jsconfig.json**）文件中的 `compilerOptions.paths` 和 `compilerOptions.baseUrl` 字段。这使项目中的绝对导入和别名成为可能。有关更多信息，请参见 [TypeScript](/guides/typescript) 指南。
此功能在裸项目中需要额外设置。有关更多信息，请参见 [Metro 设置指南](/versions/latest/config/metro#bare-workflow-setup)。
## CSS


## 使用 Expo Atlas 和 Lighthouse 分析 JavaScript 包

了解如何使用 Expo Atlas 和 Lighthouse 改善 Expo 应用和网站的生产 JavaScript 包大小。

包的性能在不同的平台上有所不同。例如，网络浏览器不支持预编译的字节码，因此 JavaScript 包的大小对于改善启动时间和性能是至关重要的。包越小，下载和解析的速度就越快。
## 使用 Expo Atlas 分析包大小
项目中使用的库会影响生产 JavaScript 包的大小。您可以使用 [Expo Atlas](https://github.com/expo/expo-atlas#readme) 来可视化生产包并识别哪些库对包大小产生影响。
### 使用 `npx expo start` 运行Atlas
您可以使用本地开发服务器与Expo Atlas。此方法允许Atlas在您更改项目中的任何代码时更新。
一旦您的应用在Android、iOS和/或Web上通过本地开发服务器运行，您可以通过 [dev tools插件菜单](/debugging/devtools-plugins/#using-a-dev-tools-plugin) 使用 <kbd>shift</kbd> + <kbd>m</kbd> 打开Atlas。
```sh
$ EXPO_ATLAS=true npx expo start
```
#### 将开发模式更改为生产模式
默认情况下，Expo在 [开发模式](/workflow/development-mode/#development-mode) 下启动本地开发服务器。开发模式禁用一些在 [生产模式](/workflow/development-mode/#production-mode) 下启用的优化。您也可以在生产模式下启动本地开发服务器，以获得更准确的生产包大小表示：
```sh
$ EXPO_ATLAS=true npx expo start --no-dev
```
### 使用 `npx expo export` 的Expo Atlas
在为您的应用或EAS更新生成生产包时，您也可以使用Expo Atlas。在导出时，Atlas会生成一个**.expo/atlas.jsonl** 文件，您可以分享和打开该文件，而无需访问项目。
```sh
$ EXPO_ATLAS=true npx expo export
$ npx expo-atlas .expo/atlas.jsonl
```
您还可以使用 `--platform` 选项指定您希望分析的平台。Expo Atlas只会收集导出平台的数据。
### 分析变换模块
在 Atlas 中，您可以按住 <kbd>⌘ Cmd</kbd> 并单击图形节点以查看变换模块的详细信息。此功能帮助您了解模块如何通过 Babel 进行变换，它导入了哪些模块，以及哪些模块导入了它。这可以用于追踪模块在依赖图中的来源。
## 使用 source-map-explorer 分析包大小
> **SDK 50及之前版本**的替代方法。
如果您使用的是 SDK 50 或更早版本，可以使用 [`source-map-explorer`](https://www.npmjs.com/package/source-map-explorer) 库来可视化和分析生产 JavaScript 包。
Step 1: 
要使用 source map explorer，请运行以下命令进行安装：
```sh
$ npm i --save-dev source-map-explorer
```
Step 2: 
在 **package.json** 中添加一个脚本以运行它。您可能需要根据您使用的平台或SDK调整输入路径。为简便起见，以下示例假设项目是Expo SDK 50，并且不使用Expo Router的 `server` 输出。
```json package.json
{
  "scripts": {
    "analyze:web": "source-map-explorer 'dist/_expo/static/js/web/*.js' 'dist/_expo/static/js/web/*.js.map'",
    "analyze:ios": "source-map-explorer 'dist/_expo/static/js/ios/*.js' 'dist/_expo/static/js/ios/*.js.map'",
    "analyze:android": "source-map-explorer 'dist/_expo/static/js/android/*.js' 'dist/_expo/static/js/android/*.js.map'"
  }
}
```
如果您使用 SDK 50 的 `server` 输出用于Web，则使用以下命令映射Web包：
```sh
$ npx source-map-explorer 'dist/client/_expo/static/js/web/*.js' 'dist/client/_expo/static/js/web/*.js.map'
```
Web 包输出到 **dist/client** 子目录，以防止将服务器代码暴露给客户端。
Step 3: 
导出您的生产 JavaScript 包，并包含 `--source-maps` 标志，以便源映射浏览器可以读取源映射。对于使用 Hermes 的本地应用，您可以使用 `--no-bytecode` 选项禁用字节码生成。
```sh
$ npx expo export --source-maps --platform web
$ npx expo export --source-maps --platform ios --no-bytecode
```
此命令在输出中显示JavaScript包和源映射路径。在下一步中，您将这些路径传递给源映射浏览器。
> 请避免将源映射发布到生产环境，因为它们可能引发安全和性能问题（浏览器将下载大型映射）。
Step 4: 
运行脚本以分析您的包：
```sh
$ npm run analyze:web
```
运行此命令时，您可能会看到以下错误：
```text
You must provide the URL of lib/mappings.wasm by calling SourceMapConsumer.initialize({ 'lib/mappings.wasm': ... }) before using SourceMapConsumer
```
这可能是由于在 Node.js 18及以上版本中的 `source-map-explorer` 存在 [已知问题](https://github.com/danvk/source-map-explorer/issues/247)。要解决此问题，请在运行分析脚本之前设置环境变量 `NODE_OPTIONS=--no-experimental-fetch`。
您可能会遇到警告，如 `Unable to map 809/13787 bytes (5.87%)`。这是因为源映射通常会排除打包器运行时定义（例如，`__d(() => {}, [])`）。此值是一致的，不必担心。
## Lighthouse
Lighthouse 是检查您的网站速度、可访问性和性能的好方法。您可以通过 Chrome 中的 **审计** 选项卡或使用 [Lighthouse CLI](https://github.com/GoogleChrome/lighthouse#using-the-node-cli) 测试您的项目。
在通过 `npx expo export -p web` 创建生产构建并提供服务（使用 `npx serve dist`、生产部署或自定义服务器）后，使用您网站托管的 URL 运行 Lighthouse。
```sh
$ npm install -g lighthouse
$ npx lighthouse <url> --view
```


## 树摇与代码移除

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

树摇（也称为 _死代码移除_）是一种从生产包中移除未使用代码的技术。 Expo CLI 采用不同的技术，包括 [minification](/guides/minify)，通过移除未使用的代码来提高启动时间。
## 平台摇动
Expo CLI 采用称为 **平台摇动** 的过程进行应用打包，为每个平台（Android、iOS、web）创建单独的包。它确保代码仅在一个平台上使用，并从其他平台中移除。
任何基于 `react-native` 的 `Platform` 模块条件使用的代码都将从其他平台中移除。然而，这种排除特别适用于直接从 react-native 中导入的 `Platform.select` 和 `Platform.OS` 实例。如果这些通过不同的模块重新导出，则它们在打包过程中不会被移除。
例如，考虑以下变换输入：
```js Input
import { Platform } from 'react-native';
if (Platform.OS === 'ios') {
  console.log('Hello on iOS');
}
```
生产包将移除基于平台的条件：
```js Output (Android)
```
```js Output (iOS)
console.log('Hello on iOS');
```
此优化仅适用于生产，并逐文件运行。如果从不同的模块重新导出 `Platform.OS`，则不会从生产包中移除。
`process.env.EXPO_OS` 可用于检测 JavaScript 为哪个平台打包（运行时无法改变）。由于 Metro 在依赖解析后压缩代码，此值不支持平台摇动导入。
## 移除仅开发使用的代码
在您的项目中，可能有代码是为了帮助开发过程而设计的。它应该从生产包中排除。要处理这些情况，请使用 `process.env.NODE_ENV ` 环境变量或非标准的 `__DEV__` 全局布尔值。
Step 1: 
例如，以下代码片段将从生产包中删除：
```js Input
if (process.env.NODE_ENV === 'development') {
  console.log('Hello in development');
}
if (__DEV__) {
  console.log('Another development-only conditional...');
}
```
Step 2: 
在 _常量折叠_ 发生后，可以静态评估条件：
```js Post constants folding
if ('production' === 'development') {
  console.log('Hello in development');
}
if (false) {
  console.log('Another development-only conditional...');
}
```
Step 3: 
在 [minification](/guides/minify) 期间，无法访问的条件被移除：
```js Output (production)
```
为了提高速度，Expo CLI 仅在生产构建中执行代码消除。上述代码片段中的条件在开发构建中保留。
## 自定义代码移除
`EXPO_PUBLIC_` 环境变量在压缩过程之前被内联。这意味着它们可以用于从生产包中移除代码。例如：
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: 
上述输入代码片段在 `babel-preset-expo` 之后被转换为以下内容：
```js Post babel-preset-expo
if (!'true') {
  console.log('Hello from the feature!');
}
```
Step 3: 
上述代码片段随后被压缩，从而移除未使用的条件：
```js Post minifier
// Empty file
```
- 此系统不适用于服务器代码，因为环境变量不会在服务器包中内联。
- 为了安全原因，库作者不应使用 `EXPO_PUBLIC_` 环境变量，因为它们只在应用代码中运行。
## 移除服务器代码
通常使用 `typeof window === 'undefined'` 有条件地启用或禁用服务器和客户端环境的代码。
`babel-preset-expo` 在打包服务器环境时会将 `typeof window === 'undefined'` 转换为 `true`。默认情况下，此检查在打包 Web 客户端环境时保持不变。此变换在开发和生产中都运行，但仅在生产中删除条件需要。
您可以通过传递 `{ minifyTypeofWindow: true }` 来配置 `babel-preset-expo` 以启用此变换。
默认情况下，此变换在 Web 环境中保持禁用，因为 Web Worker 不会有 `window` 全局。
Step 1: 
```js Input
if (typeof window === 'undefined') {
  console.log('Hello on the server!');
}
```
Step 2: 
上一步的输入代码在针对服务器环境（API 路由、服务器渲染）打包时被 `babel-preset-expo` 转换为以下代码片段：
```js Post babel-preset-expo (bundling for server)
if (true) {
  console.log('Hello on the server!');
}
```
为 Web 或本地应用打包客户端代码时，不会替换 `typeof window`，除非设置了 `minifyTypeOfWindow: true`：
```js Post babel-preset-expo
if (typeof window === 'undefined') {
  console.log('Hello on the server!');
}
```
Step 3: 
对于服务器环境，上述代码片段随后被压缩，移除未使用的条件：
```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 导入
`babel-preset-expo` 为 `react-native-web` 批量文件提供内置优化。如果您使用 ESM 直接导入 `react-native`，则批量文件将从生产包中移除。
For ESM: 
如果使用静态 `import` 语法导入 `react-native`，则批量文件将被移除。
```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: 
如果使用 `require()` 导入 `react-native`，则批量文件将在生产包中保持不变。
```js Input
const { View, Image } = require('react-native');
```
```js Output (web)
const { View, Image } = require('react-native-web');
```
## 移除未使用的导入和导出
> 在 SDK 52 及更高版本中试验性可用。
您可以试验性地启用自动移除未使用的导入和导出跨模块的支持。这对于加速本地 OTA 下载和优化必须使用标准 JavaScript 引擎解析和执行的 Web 性能非常有用。
考虑以下示例代码：
```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() {
  /* ... */
}
```
由于 `index.js` 中仅使用 `ArrowUp`，生产包将移除 `icons.js` 中的所有其他组件。
```js icons.js (Output)
export function ArrowUp() {
  /* ... */
}
```
此系统可扩展到自动优化应用中所有 `import` 和 `export` 语法，跨所有平台。虽然这会导致更小的包，但处理 JS 仍然需要时间和计算机内存，因此避免导入数以百万计的模块。
- 树摇仅在生产包中运行，并且只能在使用 `import` 和 `export` 语法的模块上运行。使用 `module.exports` 和 `require` 的文件将不会被树摇。
- 避免添加将 `import`/`export` 语法转换为 CJS 的 Babel 插件，例如 `@babel/plugin-transform-modules-commonjs`。这将破坏整个项目的树摇。
- 被标记为副作用的模块将不会从图中移除。
- `export * from "..."` 将被扩展和优化，除非导出使用 `module.exports` 或 `exports`。
- Expo SDK 中的所有模块都作为 ESM 打包并可以彻底树摇。
## 启用树摇
> 在 SDK 52 及更高版本中试验性可用。
Step 1: 
确保 `experimentalImportSupport` 并确保您的应用可以按预期构建和运行。
> **info** **注意**：在 SDK 54 及更高版本中默认启用。
Note: 如何在旧 SDK 版本中启用导入支持？
---
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.getTransformOptions = async () => ({
  transform: {
    experimentalImportSupport: true,
  },
});
module.exports = config;
```
实验性导入支持使用自定义版本的 `@babel/plugin-transform-modules-commonjs` 插件。它大大减少了解析的数量并简化输出包。此功能可以与 `inlineRequires` 一起使用，以进一步实验性地优化您的包。
---
Step 2: 
打开环境变量 `EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1`，以在整个图创建之前保留模块。确保您的应用在启用此功能时的生产模式下按预期构建和运行，然后再继续。
```sh .env
EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1
```
这将仅在生产模式下使用。
Step 3: 
打开环境变量 `EXPO_UNSTABLE_TREE_SHAKING=1` 以启用该功能。
```sh .env
EXPO_UNSTABLE_TREE_SHAKING=1
```
这将仅在生产模式下使用。
Step 4: 
在生产模式下捆绑您的应用，以查看树摇的效果。
```sh
$ npx expo export
```
此功能是非常实验性的，因为它改变了 Metro 打包代码的基本结构。默认情况下，Metro 会按需和延迟打包一切，以确保最快的开发时间。相反，树摇需要在整个包创建后延迟某些转换。这意味着更少的代码可以被缓存，这通常是可以的，因为树摇是仅在生产中使用的特性，而生产包通常不使用转换缓存。
## 批量文件
> 在 SDK 52 及更高版本中试验性可用。
通过 Expo 树摇，星形导出将根据使用情况自动展开并摇动。例如，考虑以下代码片段：
```js Input
export * from './icons';
```
优化通道将爬行 `./icons` 并将导出添加到当前模块。如果导出未使用，它们将从生产包中移除。
```js Expanded
export { ArrowRight, ArrowLeft } from './icons';
```
这将根据标准树摇规则进行摇动。如果您只导入 `ArrowRight`，则 `ArrowLeft` 将从生产包中移除。
如果星形导出拉入模糊的导出，例如 `module.exports.ArrowUp` 或 `exports.ArrowDown`，那么优化通道将不会扩展星形导出，并且不会从批量文件中移除任何导出。您可以使用 [Expo Atlas](/guides/analyzing-bundles/#analyzing-bundle-size-with-atlas) 来检查扩展的导出。
您可以使用此策略与如 `lucide-react` 等库结合，移除您应用中未使用的所有图标。
## 递归优化
> 在 SDK 52 及更高版本中试验性可用。
Expo 通过在整个图中递归以寻找未使用的导入来优化模块。考虑以下代码片段：
```js Input
export function foo() {
  // 因为这里使用了 bar，所以不能被移除。
  bar();
}
export function bar() {}
```
在这种情况下，`bar` 在 `foo` 中使用，因此不能被移除。然而，如果 `foo` 在应用中没有被使用，那么将移除 `foo`，并将模块重新扫描以查看 `bar` 是否可以被移除。这个过程会针对给定模块递归执行 5 次，然后由于性能原因退出。
## 副作用
Expo CLI 根据 [Webpack 系统](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free) 遵循模块副作用。副作用通常用于定义全局变量（`console.log`）或修改原型（避免这样做）。
您可以在 **package.json** 中标记您的模块是否有副作用：
```json package.json
{
  "name": "library",
  "sideEffects": ["./src/*.js"]
}
```
副作用将防止未使用模块的移除，并禁用模块内联，以确保 JS 代码按预期顺序运行。如果副作用为空或仅包含注释和指令（`"use strict"`、`"use client"` 等），则将被移除。
当启用 Expo 树摇时，您可以安全地在 **metro.config.js** 中为生产包启用 `inlineRequires`。这将在评估时延迟加载模块，从而导致更快的启动时间。避免在没有 Expo 树摇的情况下使用此功能，因为它将以可能改变副作用执行顺序的方式移动模块。
```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;
```
## 针对树摇的优化
在 Expo 树摇之前，React Native 库会通过将导入包装在条件块中来移除导入，如下所示：
```js
if (process.env.NODE_ENV === 'development') {
  require('./dev-only').doSomething();
}
```
这很成问题，因为您没有准确的 TypeScript 支持，且这使图变得模糊，因为您无法静态分析代码。启用 Expo 树摇后，您可以重构此代码以使用 ESM 导入：
```js Input
import { doSomething } from './dev-only';
if (process.env.NODE_ENV === 'development') {
  doSomething();
}
```
在这两种情况下，整个模块在生产包中将是空的。


## 压缩 JavaScript

了解如何在 Expo CLI 中使用 Metro bundler 自定义 JavaScript 压缩过程。

压缩是一个优化构建步骤。它会从源代码中移除多余的字符，例如压缩空白、去除注释，以及缩短静态操作。此过程减少了最终文件大小并改善了加载时间。
## Expo CLI 中的压缩
在 Expo CLI 中，压缩会在生产导出期间对 JavaScript 文件进行（即在执行 `npx expo export`、`npx expo export:embed`、`eas build` 等命令时）。
例如，考虑项目中的以下代码片段：
```js Input
// 此注释将被去除
console.log('a' + ' ' + 'long' + ' string' + ' to ' + 'collapse');
```
这将在 Expo CLI 中被压缩为：
```js Output
console.log('a long string to collapse');
```
> **提示**: 可以通过使用 `/** @preserve */` 指令来保留注释。
Expo CLI 的默认压缩对大多数项目而言是足够的。然而，您可以自定义压缩器以优化速度或去除额外的功能，如日志。
## 移除控制台日志
您可以从生产构建中移除控制台日志。在 Terser 压缩器配置中使用 `drop_console` 选项。
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.minifierConfig = {
  compress: {
    // 以下选项将在生产中移除所有控制台日志语句。
    drop_console: true,
  },
};
module.exports = config;
```
如果您希望保留某些日志，也可以传递要删除的控制台类型数组。例如：`drop_console: ['log', 'info']` 将移除 `console.log` 和 `console.info`，但保留 `console.warn` 和 `console.error`。
## 自定义压缩器
不同的压缩器在速度和压缩之间有权衡。您可以通过修改项目中的 **metro.config.js** 文件来自定义 Expo CLI 使用的压缩器。
### Terser
> [`terser`](https://github.com/terser/terser) 是默认的压缩器（[Metro@0.73.0 更新日志](https://github.com/facebook/metro/releases/tag/v0.73.0)）。
Step 1: 
要在项目中安装 Terser，请运行命令：
```sh
$ yarn add --dev metro-minify-terser
```
Step 2: 
将 Terser 设置为压缩器，使用 `transformer.minifierPath`，并将 [`terser` 选项](https://github.com/terser/terser#compress-options) 传递给 `transformer.minifierConfig`。
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.minifierPath = 'metro-minify-terser';
config.transformer.minifierConfig = {
  // Terser 选项...
};
module.exports = config;
```
### 不安全的 Terser 选项
对于可能在所有 JavaScript 引擎中无法正常工作的附加压缩，请启用 [`unsafe` `compress` 选项](https://terser.org/docs/miscellaneous/#the-unsafe-compress-option)：
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.minifierPath = 'metro-minify-terser';
config.transformer.minifierConfig = {
  compress: {
    // 启用所有不安全的优化。
    unsafe: true,
    unsafe_arrows: true,
    unsafe_comps: true,
    unsafe_Function: true,
    unsafe_math: true,
    unsafe_symbols: true,
    unsafe_methods: true,
    unsafe_proto: true,
    unsafe_regexp: true,
    unsafe_undefined: true,
    unused: true,
  },
};
module.exports = config;
```
### esbuild
[`esbuild`](https://esbuild.github.io/) 用于以指数级速度比 `uglify-es` 和 `terser` 更快地进行压缩。有关更多信息，请参阅 [`metro-minify-esbuild`](https://github.com/EvanBacon/metro-minify-esbuild#usage) 的使用。
### Uglify
您可以通过以下步骤使用 [`uglify-es`](https://github.com/mishoo/UglifyJS)：
Step 1: 
在项目中安装 Uglify，请运行命令：
```sh
$ yarn add --dev metro-minify-uglify
```
> 确保 `metro-minify-uglify` 的版本与项目中的 `metro` 版本匹配。
Step 2: 
将 Uglify 设置为压缩器，使用 `transformer.minifierPath`，并将 [选项](https://github.com/mishoo/UglifyJS#compress-options) 传递给 `transformer.minifierConfig`。
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.minifierPath = 'metro-minify-uglify';
config.transformer.minifierConfig = {
  // 选项: https://github.com/mishoo/UglifyJS#compress-options
};
module.exports = config;
```


## 为什么选择 Metro？

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

[Metro](https://metrobundler.dev/) 是 Expo 和 React Native 的官方打包工具。它是 Expo 框架中的一个核心构建工具。打包工具包含成千上万的意见和权衡。本文档概述了 Expo 为什么围绕 Metro 开发的主要原因以及它如何惠及开发者。
## 官方 Meta 打包工具
Metro 由 Meta 维护，Meta 是 React、React Native、Yoga 和 Hermes 的维护者。它被用于开发一些全球最大的应用程序，涵盖了应用商店中的所有类别。
Meta 工程师积极开发 Metro，明确要求将他们所有的应用程序打包，涵盖超过 40 万个源文件，同时保持快速和可靠。
通过提供一流的 Metro 支持，我们确保 Expo 开发者在 Meta 的工具之间保持连续性，并立即访问新兴功能。这包括：
- React Fast Refresh 于 2019 年作为 Metro 的一项功能首次推出。React 网页社区在第二年通过 Webpack 采用了它。
- 将 JavaScript 转换为 Hermes 字节码，以实现即时原生启动。
- React Native DevTools，包括对 [网络和 JS 调试](/debugging/tools/#debugging-with-react-native-devtools) 的一流支持，专门与 Metro 和 Hermes 一起使用。
- React Compiler 最初作为与 Metro 兼容的 Babel 插件发布。
计划在 Metro 中推出的新功能包括：
- 使用 Static Hermes 将 Flow 代码编译为原生机器代码。有关更多信息，请查看 Tzvetan Mikov 的 [Static Hermes](https://www.youtube.com/watch?v=GUM64b-gAGg) 讲座。
- 数据获取、流处理、React Suspense、服务器渲染，以及使用通用 React 服务器组件的构建时静态渲染，适用于所有平台。有关更多信息，请查看 React Conf 2024 的 [Universal React Server Components](https://www.youtube.com/watch?v=djhEgxQf3Kw) 讲座。
Expo 团队与 Meta 合作开发旨在为 Expo Router 提供 Metro，增加了 [基于文件的路由](/develop/file-based-routing/)、[Web 支持](/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/) 等功能。
## 大规模实战检验
几乎世界上每个 React Native 应用程序都在使用 Metro，这使其成为一个经过实战检验的解决方案，优化了大规模项目的使用。这使其适用于从业余爱好者到大型公司的所有规模开发者。Metro 专门设计用来处理大规模 Meta 应用程序，这就是为什么它具有如 Watchman 的原生文件监视和 [共享远程缓存](https://metrobundler.dev/docs/caching) 这样的功能。
## 按需处理
在开发过程中，Metro 直到请求时才执行任何特定于平台的工作。这使开发者能够在不为所支持平台数量支付性能成本的情况下，进行大型项目的开发。结合激进的缓存和 [异步路由](/router/reference/async-routes/)，开发者可以增量打包他们正在积极处理的应用程序部分。
## 多维度
与传统的打包工具不同，这些工具创建多个实例以捆绑服务器和客户端代码，而 Metro 最大化了跨平台和环境（服务器、客户端、DOM 组件）之间的资源重用。这种架构非常适合多平台和服务器开发。
## 可重用的转换记忆化
Metro 是增量式的，可以创建可在多台机器上使用的缓存转换工件。这使大型团队能够重用来自远程构建器的工作，这是 Meta 在所有大型项目中使用的一种技术。
## 针对自定义运行时优化
尽管其他打包工具围绕Web浏览器的静态规范而设计，Metro则针对React Native的灵活性进行了优化。这使得生成所需的特定语言特性集成为可能，以进行 Hermes 字节码编译，从而在生产中实现更快的应用程序启动。这也将扩展到 Static Hermes，它将静态类型信息编译为原生应用程序的机器代码。
## 跨技术支持
Expo 利用 Metro 的技术来创建新颖的功能，如 [DOM 组件](/guides/dom-components/)。这使得在原生应用程序中的 React 组件能够动态捆绑为整个网站，并与父应用程序共用所有相同的默认设置，按需进行。
## 原生资产导出
与传统打包工具的最终结果是完全托管的应用程序不同，Metro 的配置选项支持将捆绑导出为嵌入到独立应用程序二进制文件中的原生工件。这利用了 Apple 平台上诸如 `xcassets` 的操作系统特定优化。
## 并发处理
Metro 中的所有 AST 转换都是在所有可用线程上并发执行，最大化硬件的使用。
## 与其他方法的比较
虽然 Metro 是为通用应用程序开发而设计的，但它常常与其他仅限于 Web 的打包工具进行比较。以下是一些关键区别：
### 浏览器 ESM 与打包
虽然像 Vite 这样的打包工具利用浏览器内置的 ESM 支持，但这种方法在中到大规模时可能会导致较慢的实际开发时间，因为存在数千个级联的网络请求。Metro 在本地开发中执行打包，这使得开发结果与生产结果更接近，并且更适合 React Native 的更大模块数量。
### JavaScript 与原生语言
一些打包工具选择用 Rust 编写其核心以提高性能，但这也带来了一些权衡，例如更具挑战性的贡献、补丁和开发。Metro 根据操作使用一系列技术：
- 核心打包工具和实用程序用 JS/Flow 编写。
- 文件监视通过 Watchman 用 C++ 编写，并具有 JS 备份。Watchman 随后在计算机上的各个项目中使用。
- AST 使用 Hermes 解析器（WebAssembly）解析为 Babel 兼容格式。
- AST 转换使用 Babel 执行。这最大化了开发者的自定义。
- 在原生平台上使用 Hermes 进行压缩，而在 Web 上使用 Terser（可选的 ESBuild 支持）。
- CSS 解析和压缩使用 [LightningCSS](https://lightningcss.dev/)（Rust）执行。
这种方法与 Meta 和社区工具保持一致，同时使开发者更容易进行调试、分析和修补。


# 参考

## 与单体仓库合作

了解如何在使用工作区的单体仓库中设置 Expo 项目。

单体仓库，或称 _“单体代码库”_，是一个包含多个应用程序或包的单一代码库。它们可以加快大型项目的开发速度，更容易共享代码，并作为单一事实来源。本指南将设置一个简单的单体仓库，并包含一个 Expo 项目。Expo 对于管理工作区的包管理器（如：[Bun](https://bun.sh/docs/install/workspaces)，[npm](https://docs.npmjs.com/cli/using-npm/workspaces)，[pnpm](https://pnpm.io/workspaces) 和 [Yarn](https://yarnpkg.com/features/workspaces)（经典版v1和Berry版））的单体仓库提供了一流的支持。Expo 会自动检测单体仓库，并为添加到单体仓库的新应用项目进行配置。该检测基于项目中的工作区配置。
> **info** 并不是所有项目都适合使用单体仓库。如果多个应用程序位于一个代码库中并共享代码，或者有助于将原生模块与您的应用程序共同定位，那么它们是有用的。其权衡是在设置和配置工具时复杂性增加。在设置单体仓库之前，请检查您的工具和库是否能够很好地使用单体仓库。
Note: 自动配置（迁移到 SDK 52+）
---
<a id="automatic-configuration" />
自 SDK 52 起，Expo 会自动为单体仓库配置 Metro。如果您使用 [`expo/metro-config`](/guides/customizing-metro/) ，则在使用单体仓库时无需手动配置 Metro。
如果您正在迁移到 SDK 52 之后的 Expo 版本，并且拥有一个手动修改以下属性之一的 **metro.config.js**，请将其从配置中删除：
- `watchFolders`
- `resolver.nodeModulesPath`
- `resolver.extraNodeModules`
- `resolver.disableHierarchicalLookup`
删除这些选项后，您需要运行 Expo 以 `npx expo start --clear` 一次，以清除过时的 Metro 缓存。如果您的应用在之后继续按预期运行，那么它就是一个常规的 Node 单体仓库，今后将不需要任何特殊配置。
---
Note: 手动配置（在 SDK 52 之前）
---
<a id="manual-configuration" />
自 SDK 52 起，Expo 的 Metro 配置支持 Bun、npm、pnpm 和 Yarn 的单体仓库，且会自动配置。如果您使用 [`expo/metro-config`](/guides/customizing-metro/) 的配置，则无需手动配置单体仓库支持。
在 SDK 52 之前，手动使用 Metro 配置单体仓库需要进行两个手动更改：
1. 必须手动配置 Metro 以监视单体仓库中的代码（例如，不只是 **apps/cool-app**）。
2. 必须调整 Metro 的解析以找到其他工作区和多个 `node_modules` 目录中的包（例如，**apps/cool-app/node_modules** 或 **node_modules**）。
通过创建一个 [**metro.config.js**](/guides/customizing-metro/#customizing)，其内容如下，进行了配置调整：
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const path = require('path');
// 这可以替换为 `find-yarn-workspace-root`
const monorepoRoot = path.resolve(__dirname, '../..');
const config = getDefaultConfig(__dirname);
// 1. 监视单体仓库中的所有文件
config.watchFolders = [monorepoRoot];
// 2. 让 Metro 知道在哪里解析包以及顺序
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(monorepoRoot, 'node_modules'),
];
module.exports = config;
```
> 了解更多关于 [自定义 Metro](/guides/customizing-metro)。
---
## 设置单体仓库
在单体仓库中，您的应用程序通常会是您代码库下的一个子目录，并且您的包管理器被配置为允许您从单体仓库中添加对其他包的依赖项。例如，包含 Expo 应用的单体仓库的基本结构可能如下所示：
- **apps**：包含多个项目，包括 Expo 应用。
- **packages**：包含应用使用的不同包。
- **package.json**：根包文件。
所有单体仓库都应该有一个“根” **package.json** 文件。它是单体仓库的主要配置，可能包含为代码库中的所有项目安装的工具。根据您使用的包管理器，设置工作区的步骤可能会有所不同，但对于 [Bun](https://bun.sh/docs/install/workspaces)，[npm](https://docs.npmjs.com/cli/using-npm/workspaces)，和 [Yarn](https://yarnpkg.com/features/workspaces)，应将 `workspaces` 属性添加到根 **package.json** 文件中，以指定单体仓库中所有工作区的 [glob 模式](https://classic.yarnpkg.com/lang/en/docs/workspaces/#toc-tips-tricks)：
```json package.json
{
  "name": "monorepo",
  "private": true,
  "version": "0.0.0",
  "workspaces": ["apps/*", "packages/*"]
}
```
对于 [pnpm](https://pnpm.io/workspaces)，您需要创建一个 [**pnpm-workspace.yaml**](https://pnpm.io/pnpm-workspace_yaml)：
```yaml pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
```
### 创建您的第一个应用
现在您已经设置了基本的单体仓库结构，可以添加您的第一个应用。
在创建应用之前，您必须创建 **apps** 目录。此目录包含属于此单体仓库的所有独立应用或网站。在这个 **apps** 目录内，您可以创建一个包含 Expo 应用的子目录。
  For npm: 
    ```sh
$ npx create-expo-app@latest apps/cool-app
```
  For Yarn: 
    ```sh
$ yarn create expo-app apps/cool-app
```
  For pnpm: 
    ```sh
$ pnpm create expo-app apps/cool-app
```
  For Bun: 
    ```sh
$ bun create expo apps/cool-app
```
> 如果您有现有应用，可以将所有这些文件复制到 **apps** 中的一个目录。
在复制或创建第一个应用后，从单体仓库的根目录使用包管理器安装依赖项，以检查常见的警告。
### 创建一个包
单体仓库可以帮助我们在一个代码库中分组代码。这包括应用程序，但也包括独立的包。它们也不需要发布。[Expo 仓库](https://github.com/expo/expo) 也使用这一点。所有的 Expo SDK 包都位于我们代码库中的 [**packages**](https://github.com/expo/expo/tree/main/packages) 目录下。这有助于我们在发布之前在我们 [**apps**](https://github.com/expo/expo/tree/main/apps/native-component-list) 目录中测试代码。
让我们回到根目录并创建 **packages** 目录。此目录可以包含您想要创建的所有独立包。一旦进入此目录，我们需要添加一个新的子目录。子目录是我们可以在应用中使用的独立包。在下面的示例中，我们将其命名为 **cool-package**。
  For npm: 
    ```sh
$ mkdir -p packages/cool-package
$ cd packages/cool-package
$ npm init
```
  For Yarn: 
    ```sh
$ mkdir -p packages/cool-package
$ cd packages/cool-package
$ yarn init
```
  For pnpm: 
    ```sh
$ mkdir -p packages/cool-package
$ cd packages/cool-package
$ pnpm init
```
  For Bun: 
    ```sh
$ mkdir -p packages/cool-package
$ cd packages/cool-package
$ bun init --minimal
```
我们不会对创建包展开过多细节。如果您对此不熟悉，请考虑使用一个不带单体仓库的简单应用。不过，为了使示例完整，我们添加一个 **index.js** 文件，其内容如下：
```js index.js
export const greeting = 'Hello!';
```
### 使用该包
像标准包一样，我们需要将我们的 **cool-package** 添加为我们的 **cool-app** 的依赖项。标准包与单体仓库中的包之间的主要区别在于，您总是希望使用 _“当前状态的包”_，而不是某个版本。让我们通过将 `"cool-package": "*"` 添加到我们的应用 **package.json** 文件中，来将 **cool-package** 添加到我们的应用程序：
```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": "~54.0.0",
    "expo-status-bar": "~3.0.6",
    "react": "19.1.0",
    "react-native": "0.81.1"
  }
}
```
Bun、npm 和 pnpm 支持使用 `"workspace:*"` 指定工作区依赖关系，而不是 `"*"`。这将确保工作区包永远不会从 npm 注册表解析同名的已发布包，但这是可选的。
添加包之后，再次从单体仓库的根目录使用包管理器安装依赖项，以检查常见警告。
现在您应该能够在应用中使用该包！为了测试这一点，让我们编辑您的应用中的 **App.js**，并渲染我们 **cool-package** 中的 `greeting` 文本。
```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>
  );
}
```
## 常见问题
单体仓库可能会导致常规项目不会出现的解析和依赖问题。它们需要更深入的知识，并需要特定的工具配置。您会承受更高的复杂性，并需要解决您在没有工作区的情况下不会遇到的问题。以下是您可能遇到的一些常见问题。
### 具有孤立依赖项的包管理器
> **info** 从 **SDK 54** 开始，Expo 支持孤立依赖项和孤立安装。
> 对于 **SDK 53**，建议禁用孤立依赖项，否则您可能会遇到原生构建错误和依赖冲突。
[Bun](https://bun.com/docs/install/isolated) 和 [pnpm](https://pnpm.io/settings#nodelinker) 对孤立安装提供了原生支持。对于 pnpm，这也是默认的安装策略，除非禁用。
使用孤立依赖项时，包管理器不会将嵌套的 `node_modules` 目录中的包提升到更高的目录中。相反，它们会创建一个中心目录来包含您的 Node 模块，并创建指向该目录的链接。这种依赖结构强制包只能访问其显式声明的依赖项。这是一种比传统 **hoisted** 安装策略更严格的安装策略，后者是 npm 和 Yarn 的默认方式，通过扁平结构安装依赖项。
**hoisted** 安装的一个副作用是，您可能会无意中依赖于在自己 **package.json** 的 `dependencies` 或 `peerDependencies` 中未指定的 Node 模块。相反，其他包依赖的许多更多依赖项被提升并变得可访问。这可能导致非确定性行为，并允许您拥有破损的依赖关系链，这些链更加脆弱，并且在更新或升级包时可能会导致解析错误。这在单体仓库中尤其常见。
**从 SDK 54 开始**，Expo 支持孤立依赖项。不幸的是，并非所有您安装的包都能正常工作，某些 React Native 库在与孤立依赖项一起使用时可能会导致构建或解析错误。如果您在使用 [pnpm](https://pnpm.io/settings#nodelinker) 时遇到孤立安装问题，请通过在代码库根目录中的 **.npmrc** 文件中更改 `node-linker` 设置切换到 **hoisted** 安装策略：
```plain .npmrc
node-linker=hoisted
```
### 单体仓库内重复的原生包
Expo 改进了对更完整的 **node_modules** 模式（例如孤立模块）的支持。不幸的是，如果您的应用包含重复的依赖项，仍可能会发生问题：
- 在单个单体仓库中不支持重复的 React Native 版本
- 在单个应用中重复的 React 版本将导致运行时错误
- 重复版本的 Turbo 和 Expo 模块可能导致运行时或构建错误
您可以检查您的单体仓库是否有多个同一包的版本，例如 `react-native`，以及它们为何被您使用的包管理器安装。
  For npm: 
    ```sh
$ npm why react-native
```
  For Yarn: 
    ```sh
$ yarn why react-native
```
  For pnpm: 
    ```sh
$ pnpm why --depth=10 react-native
```
  For Bun: 
    ```sh
$ bun pm why react-native
```
这些命令的输出在不同的包管理器之间会非常不同，但您可以通过查看同一包的多个版本（例如 `react-native@0.79.5` 和 `react-native@0.81.0`）在它们的任意输出中找到重复的包。
**npm**，
#### 为同伴依赖项添加依赖解析
如果重复的依赖项无法通过更改您的依赖项进行解决，则可能需要添加解析。例如，并非所有包都已更新其 **peerDependencies** 以支持 React 19。为了解决此问题，您可以创建一个解析，强制安装单个版本的 `react`。
```json package.json
{
  "name": "monorepo",
  "private": true,
  "version": "0.0.0",
  "workspaces": ["apps/*", "packages/*"],
  "resolutions": {
    "react": "^19.1.0"
  }
}
```
对于 [npm](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides)，您必须使用名为 `overrides` 的属性，而不是 `resolutions`。
#### 去重自动链接的原生模块
> **important** 这是从 SDK 54 及以后版本开始的实验性功能。该过程将在未来版本中自动化并提供更好的支持。
通常，重复的依赖项不会引起任何问题。然而，原生模块绝不应重复，因为一次只能为应用构建编译一个版本的原生模块。与 JavaScript 依赖项不同，原生构建不能包含单个原生模块的两个冲突版本。
从 **SDK 54** 开始，您可以在 **app.json** 中将 `experiments.autolinkingModuleResolution` 设置为 `true`，以自动将自动链接应用于 Expo CLI 和 Metro 打包工具。这将强制 Metro 解析的依赖项与 [自动链接](/modules/autolinking/) 为您的原生构建链接的原生模块匹配。
### 脚本 '...' 不存在
React Native 使用包来发布 JavaScript 和原生文件。这些原生文件也需要链接，就像 **android/app/build.Gradle** 中的 [**react-native/react.Gradle**](https://github.com/facebook/react-native/blob/v0.70.6/react.gradle) 文件一样。通常，此路径是硬编码为类似于：
**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'
```
不幸的是，由于 [提升](https://classic.yarnpkg.com/blog/2018/02/15/nohoist/)，在单体仓库中此路径可能会有所不同。它也不使用 [Node 模块解析](https://nodejs.org/api/modules.html#all-together)。您可以通过使用 Node 找到包的位置，而不是硬编码路径来避免此问题：
**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.org/api/modules.html#requireresolverequest-options) 方法查找包的位置。我们明确引用 `package.json` 是因为我们想找到包的根位置，而不是入口点的位置。通过该根位置，我们可以解析到包内的预期相对路径。[了解更多关于这些引用的信息](https://github.com/expo/expo/blob/4633ab2364e30ea87ca2da968f3adaf5cdde9d8b/packages/expo-modules-core/README.mdx#importing-native-dependencies---autolinking)。
所有 Expo SDK 模块和模板都有这些动态引用，并且在单体仓库中工作。然而，有时您可能会遇到仍使用硬编码路径的包。您可以使用 [`patch-package`](https://github.com/ds300/patch-package#readme) 手动编辑它，或向包维护者提及此问题。


## 查看日志

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

在 React Native 应用中记录信息的方式与在网页浏览器中相似。您可以使用 `console.log`、`console.warn` 和 `console.error`。然而，有时您可能希望深入了解应用中发生的事情，以获得更有用的信息。为此，您可以使用 **本机日志** 和 **系统日志**。
## 控制台日志
当您运行 `npx expo start` 并连接设备时，控制台日志将在终端进程中显示。这些日志从运行时通过 WebSocket 发送到 Expo CLI，这意味着结果的质量低于直接将开发工具连接到引擎。
您可以通过创建一个带有 [Hermes](/guides/using-hermes) 的开发构建，并 [连接检查器](/guides/using-hermes#javascript-inspector-for-hermes) 来查看 **高保真** 日志并使用高级日志功能，如 `console.table`。
## 本机日志
您可以通过在 Android Studio 和 Xcode 中本地编译应用程序来查看本机运行时日志。有关更多信息，请参见 [本机调试](/debugging/runtime-issues/#native-debugging)。
## 系统日志
虽然通常不必要，但如果您想查看设备上发生的所有日志，例如，甚至包括其他应用和操作系统的日志，您可以使用以下命令：
```sh
$ npx react-native log-android
$ npx react-native log-ios
```


## 开发和生产模式

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

您的项目将始终以 **development** 或 **production** 模式运行。默认情况下，本地运行项目时使用 `npx expo start` 会以开发模式运行，而已发布的项目（使用 `eas update`）或任何独立应用将以生产模式运行。
**开发模式** 包括有用的警告，并为您提供可以使开发和调试更轻松的工具。**生产模式** [压缩你的代码](/guides/customizing-metro/#minification)，更好地代表您的应用在最终用户设备上的性能。让我们更详细地查看这两种模式，并了解如何在它们之间切换。
## 开发模式
React Native 提供了一些非常有用的开发工具：Chrome 中的远程 JavaScript 调试、实时重新加载、热重载，以及类似于您在 Chrome 中使用的受欢迎的元素检查器。如果您想了解如何使用这些工具，请参见 [调试](/debugging/runtime-issues/)。
开发模式还在您的应用运行时执行验证，以便给您警告。例如，如果您正在使用已弃用的属性，或者如果您忘记将必需的属性传递给组件。下面的视频展示了元素检查器和性能监视器在 Android 模拟器和 iOS 模拟器上的实际情况：
> **warning** **这带来了代价。您的应用在开发模式下运行更慢。**  您可以使用 Expo CLI 开启和关闭它，请参见 [生产模式](#production-mode)。当您切换时，关闭并重新打开应用以使更改生效。**每当您测试应用的性能时，请确保禁用开发模式**。
### 查看开发者菜单
该菜单提供访问许多功能，使开发和调试变得更加容易。有关如何在 Android 和 iOS 上打开它的更多信息，请参见 [开发者菜单](/debugging/tools/#developer-menu)。
## 生产模式
生产模式最有用于两件事：
- 测试应用的性能，开发模式会显著降低应用速度。
- 捕捉仅在生产环境中才会出现的错误。
模拟项目如何在最终用户设备上运行的最简单方法是使用以下命令：
```sh
$ npx expo start --no-dev --minify
```
它以生产模式运行您的应用的 JavaScript（这让 Metro 打包器将 `__DEV__` 环境变量设置为 `false`，以及其他一些事情）。`--minify` 标志会压缩您的应用。该标志还会消除不必要的数据，如注释、格式和未使用的代码。如果您在独立应用中遇到错误或崩溃，使用此命令运行您的项目可以节省您找出根本原因的许多时间。
要完全编译您的应用以进行生产，请参见 [编译 Android](/more/expo-cli/#compiling-android) 和 [编译 iOS](/more/expo-cli/#compiling-ios)。


## 常见开发错误

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

本页面列出了开发者在使用 Expo 时常遇到的一些错误。对于每个错误，第一个项目符号提供关于出现该错误的解释，第二个项目符号包含调试建议。如果您认为还有其他错误应当列在此处，我们欢迎并鼓励您 [创建一个 PR](https://github.com/expo/expo/pulls)。
### Metro bundler ECONNREFUSED 127.0.0.1:19001
- 一个错误阻止了与本地开发服务器的连接。
- 运行 `rm -rf .expo` 来清除您的本地状态。检查防火墙或 [代理](/troubleshooting/proxies/) 是否影响您当前连接的网络。
### 模块 AppRegistry 不是一个已注册的可调用模块（调用 runApplication）
- 您的代码中出现错误，阻止 JavaScript bundle 在启动时执行。
- 尝试运行 `npx expo start --no-dev --minify` 在本地重现生产 JavaScript bundle。如果可能，请连接您的设备并通过 Android Studio 或 Xcode 访问设备日志。设备日志包含更详细的堆栈信息和信息。检查您的 Babel 配置中是否有更改或错误。在一些罕见情况下，这个问题可能是由于 Metro JavaScript 压缩器与您应用中的某些代码不兼容引起的 ([更多信息](https://forums.expo.dev/t/change-minifierconfig-for-minify-uglify/36460/2))。
### npm ERR! 未在 \$PATH 中找到 git 二进制文件
- 您可能没有安装 git，或者它在您的 `$PATH` 中未正确配置。
- 如果您尚未安装 [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)，请安装它。否则，请根据您的操作系统检查如何在 `$PATH` 中设置它。
### XX.X.X 不是有效的 SDK 版本
- 您正在运行的 SDK 版本已被弃用且不再受支持。
- [升级您的项目](/workflow/upgrading-expo-sdk-walkthrough) 到受支持的 SDK 版本。如果您使用的是受支持的版本且仍然看到此消息，则需要更新您的 Expo Go 应用。
### React Native 版本不匹配
- 您终端中运行的开发服务器正在打包与您设备或模拟器中的应用不同版本的 React Native。
- 通过检查 **app.json** 和 **package.json** 中的版本来 [对齐您的 react-native 版本](/troubleshooting/react-native-version-mismatch)。
### 应用程序未注册
- 您的应用中原生部分和 JS 部分注册的 AppKey 不匹配。
- [对齐您的 AppKey](/troubleshooting/application-has-not-been-registered/) 与项目的原生部分。
### 应用程序行为与预期不符
- 可能缓存正在阻止您看到应用程序的当前状态。
- 清除与您的项目相关的所有缓存，具体是 [Unix 类](/troubleshooting/clear-cache-macos-linux/) 或 [Windows](/troubleshooting/clear-cache-windows/) 系统。


## Android Studio 模拟器

学习如何设置 Android 模拟器以在虚拟 Android 设备上测试您的应用。

如果您没有可用于测试的 Android 设备，我们建议使用随 Android Studio 附带的默认模拟器。如果您在设置过程中遇到任何问题，请按照本指南中的步骤进行操作。
<AndroidStudioEnvironmentInstructions />
<AndroidStudioInstructions />
<AndroidEmulatorInstructions />
## 故障排除
### 多个 `adb` 版本
系统中存在多个 `adb` 版本可能会导致以下错误：
```sh
$ adb server version (xx) doesn't match this client (xx); killing...
```
这是因为您系统中的 `adb` 版本与 Android SDK 平台工具中的 `adb` 版本不匹配。
Step 1: 
打开终端并检查系统上的 `adb` 版本：
```sh
$ adb version
```
Step 2: 
从 Android SDK 平台工具目录中检查：
```sh
$ cd ~/Library/Android/sdk/platform-tools
$ ./adb version
```
Step 3: 
将 `adb` 从 Android SDK 目录复制到 `usr/bin` 目录：
```sh
$ sudo cp ~/Library/Android/sdk/platform-tools/adb /usr/bin
```


## iOS 模拟器

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

直接在计算机上开发应用程序可能比不断与 iPhone 或 iPad 交互更方便，尤其是在网络条件较慢或由于 LAN 限制需要 [隧道连接](/more/expo-cli/#tunneling) 的情况下。
本指南说明如何在您的 Mac 上安装 iOS 模拟器以进行应用开发。请注意，iOS 模拟器只能安装在 macOS 上。如果您使用 Windows 或 Linux 计算机开发 iOS 应用程序，您将需要一个物理 iOS 设备。
## 设置 Xcode 和 Watchman
<XcodeInstructions />
Step 4: 
### 尝试一下
使用 `npx expo start` 运行您的应用，并从命令行按 <kbd>i</kbd>。
您可能会收到一个有关需要接受 Xcode 许可证的警告。运行它所建议的命令。再次打开您的应用以查看是否成功。如果没有，请查看下面的 [故障排除](#troubleshooting) 提示。
您还可以在 Expo CLI 中按 <kbd>shift</kbd> + <kbd>i</kbd> 互动选择要打开的模拟器。
## Expo Orbit
您可以使用 Expo Orbit 应用，它允许从 macOS 菜单栏一键启动构建和模拟器管理。
## 限制
尽管 iOS 模拟器适合快速开发，但它确实有一些限制。我们将在下面列出一些影响 Expo API 的主要区别。不过，请查看 [Apple 的文档](https://help.apple.com/simulator/mac/current/#/devb0244142d) 获取更多详细信息。
在模拟器中无法使用以下硬件：
- 音频输入
- 气压计
- 相机
- 运动支持（加速度计和陀螺仪）
模拟器还会暂停 iOS 11 及后续版本上的后台应用程序和进程。
## 故障排除
### 当打开模拟器时 CLI 似乎卡住了
有时 iOS 模拟器对打开命令没有响应。如果它似乎卡在此提示上，您可以手动打开 iOS 模拟器 (`open -a Simulator`)，然后在 macOS 工具栏中选择 **文件** &gt; **打开模拟器**，并选择您希望打开的 iOS 版本和设备。
您可以使用此菜单打开任何版本的模拟器。您也可以同时打开多个模拟器，但是 Expo CLI 将始终针对最近打开的模拟器。
### 模拟器已打开但 Expo Go 应用未在其中打开
首次在模拟器中安装应用时，iOS 会询问您是否希望打开 Expo Go 应用。您可能需要与模拟器交互（点击周围，拖动某些东西）以显示此提示，然后按 **确定**。
### 如何强制更新到最新版本？
创建一个具有所需 SDK 版本的项目，并在模拟器中打开以安装特定版本的 Expo Go。
```sh
$ npx create-expo-app --template blank@53
$ npx expo start --ios
```
### Expo CLI 打印了关于 `xcrun` 的错误消息，我该怎么办？
对于杂项错误，尝试以下操作：
- 手动卸载模拟器上的 Expo Go，并在 Expo CLI 终端 UI 中按 <kbd>shift</kbd> + <kbd>i</kbd> 并选择所需的模拟器重新安装。
- 如果这没有帮助，聚焦模拟器窗口，在 Mac 工具栏中选择 **设备** &gt; **抹掉所有内容和设置...**
  这将从空白镜像重新初始化您的模拟器。这在计算机内存不足且模拟器无法存储某些内部文件时有时很有用，这会导致设备处于损坏状态。


## React Native 的新架构

了解 React Native 的“新架构”以及如何和为什么迁移到它。

> **info** 我们建议使用最新的 Expo 版本，以获得最佳的新架构体验。
新架构是一个用来描述 React Native 内部完全重构的名称。它还用于解决在 Meta 和其他公司多年使用中发现的原始 React Native 架构的局限性。
在本指南中，我们将讨论如何在今天的 Expo 项目中使用新架构。
Note: 为什么迁移到新架构？
---
**新架构是 React Native 的未来** &mdash; 然而，对于许多应用程序来说，今天迁移可能没有太多即时好处。您可能想把迁移到新架构视为对您的应用未来的投资，而不是立即改善应用的一种方式。
话虽如此，**新的 React 和 React Native 特性仅在新架构中出现**。例如，新架构包括 [对 Suspense 的全面支持](https://reactnative.dev/blog/2024/10/23/the-new-architecture-is-here#full-support-for-suspense)，而 [新的样式功能](https://reactnative.dev/blog/2025/01/21/version-0.77#new-css-features-for-better-layouts-sizing-and-blending) 在传统架构中并未实现。像 [@shopify/flash-list](https://github.com/Shopify/flash-list) 和 [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated) 这样的库将发布新的主要版本，以充分利用新特性，从而提供比之前更好的性能，并将不再支持传统架构。
**传统架构不会永远存在** &mdash; 传统架构可能会在 2025 年晚期的发布中被移除。当它被移除时，您将无法在不迁移到新架构的情况下升级 React Native 或 Expo SDK。
---
## Expo 工具和新架构
从 SDK 53 开始，[Expo SDK](/versions/latest/) 中所有的 `expo-*` 包支持新架构（包括 [无桥接](https://github.com/reactwg/react-native-new-architecture/discussions/154)）。[了解已知问题](#known-issues-in-expo-sdk-libraries)。
此外，所有使用 [Expo 模块 API](/modules/overview/) 编写的模块默认支持新架构！因此，如果您使用此 API 构建了自己的本地模块，则无需额外工作即可与新架构一起使用。
**截至 2025 年 4 月，约 75% 的使用 [EAS Build](/build/introduction/) 构建的 SDK 52+ 项目采用新架构**。
## 第三方库和新架构
许多最流行的库的兼容性状态在 [React Native 目录](https://reactnative.directory/) 上进行了跟踪 （[了解有关第三方库的已知问题](#known-issues-in-third-party-libraries)）。我们已经将工具集成到 Expo Doctor 中，以与 React Native 目录集成，帮助您验证依赖项，这样您就可以快速了解哪些库没有维护，哪些与新架构不兼容或未经测试。
### 使用 React Native 目录验证您的依赖项
运行 `npx expo-doctor` 来检查您的依赖项与 React Native 目录中的数据是否一致。
```sh
$ npx expo-doctor@latest
```
您可以在 **package.json** 文件中配置 React Native 目录检查。例如，如果您想在验证中排除一个包：
```json package.json
{
  "expo": {
    "doctor": {
      "reactNativeDirectoryCheck": {
        "exclude": ["react-redux"]
      }
    }
  }
}
```
Note: 查看所有可用选项
---
- **enabled**: 如果为 `true`，检查会对任何缺失的 React Native 目录中的包发出警告。设置为 `false` 将禁用此行为。在 SDK 52 及更高版本中，默认设置为 `true`，否则默认为 `false`。您还可以使用环境变量 `EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK` 来覆盖此设置（0 为 `false`，1 为 `true`）。
- **exclude**: 列出您希望从检查中排除的包。支持精确包名和正则表达式。例如，`["exact-package", "/or-a-regex-.*/"]`。
- **listUnknownPackages**: 默认情况下，检查会警告如果 React Native 目录中缺失任何包。将此设置为 false 以禁用此行为。
---
## 使用新架构初始化新项目
**从 SDK 52 开始**，所有新项目将默认启用新架构。
```sh
$ npx create-expo-app@latest
```
## 在现有项目中启用新架构
  For SDK 53 及更高版本: 
    **新架构默认在 SDK 53 及更高版本中启用**。如果您明确禁用了它，请移除该配置以启用它。
  For SDK 52: 
    我们建议升级到 SDK 53，以确保您的应用能够利用所有最新的新架构相关修复和改进，无论是库还是 React Native 本身。如果您想先在 SDK 52 上试用，请遵循以下说明。
    Step 1: 
    要在 Android 和 iOS 上启用它，请使用在应用配置的 `expo` 对象根部的 `newArchEnabled`。您可以通过设置，例如， `"android": { "newArchEnabled": true }` 来选择性地为单个平台启用它。
    ```json app.json
    {
      "expo": {
        "newArchEnabled": true
      }
    }
    ```
    Step 2: 
      创建新构建：
          ```sh
$ npx expo prebuild --clean && npx expo run:android
$ eas build -p android
```
          ```sh
$ npx expo prebuild --clean && npx expo run:ios
$ eas build -p ios
```
      如果构建成功，您现在可以使用新架构运行您的应用！根据您使用的本地模块，您的应用可能会立即正常工作。
      现在，您可以在应用中进行点击并进行测试。对于大多数非简单应用，您可能会遇到一些问题，例如尚未为新架构实现的缺失本地视图。您遇到的许多问题都是可操作的，可以通过一些配置或代码更改来解决。我们建议您阅读以下的 [故障排除](#troubleshooting) 部分以获取更多信息。
  For SDK 51 及更早版本: 
    我们建议至少升级到 SDK 52，最好是 SDK 53。您可以在 SDK 51 中启用新架构，但您很可能会遇到各种在较新版本中已解决的问题。要启用它，您需要 [安装 `expo-build-properties` 插件](/versions/latest/sdk/build-properties/#installation) 并在目标平台上设置 `newArchEnabled`。
Note: 您是在一个裸 React Native 应用中启用新架构吗？
---
如果您使用的是 Expo SDK 53 或更高版本，新架构将默认启用。以下说明适用于旧项目。
- **Android**: 在 **gradle.properties** 文件中设置 `newArchEnabled=true`。
- **iOS**: 如果您的项目有 **Podfile.properties.json** 文件（由 `npx create-expo-app` 或 `npx expo prebuild` 创建），您可以通过在 **Podfile.properties.json** 文件中将 `newArchEnabled` 属性设置为 `"true"` 来启用新架构。否则，请参阅 React Native 新架构工作组的 ["为应用启用新架构"](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/enable-apps.md) 部分。
---
## 在现有项目中禁用新架构
> **info**: Expo Go 仅支持新架构。
如果您想选择退出使用新架构，请在应用配置中将 `newArchEnabled` 属性设置为 `false` 并创建一个 [开发构建](/develop/development-builds/introduction/)。
```json app.json
{
  "expo": {
    "newArchEnabled": false
  }
}
```
Note: 您是在一个裸 React Native 应用中禁用新架构吗？
---
- **Android**: 在 **gradle.properties** 文件中设置 `newArchEnabled=false`。
- **iOS**: 如果您的项目有 **Podfile.properties.json** 文件（由 `npx create-expo-app` 或 `npx expo prebuild` 创建），您可以通过在 **Podfile.properties.json** 文件中将 `newArchEnabled` 属性设置为 `"false"` 来禁用新架构。否则，请参阅 React Native 新架构工作组的 ["为应用启用新架构"](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/enable-apps.md) 部分。
---
## 故障排除
Meta 和 Expo 正在努力使新架构成为所有新应用的默认架构，并确保迁移现有应用的过程尽可能简单。然而，新架构不仅仅是一个名称 &mdash; React Native 的许多内部结构已经从头开始重构和重建。因此，在您的应用中启用新架构时，您可能会遇到问题。以下是一些故障排除这些问题的建议。
Note: 即使我使用的一些库不受支持，我仍然可以尝试新架构吗？
---
即使我使用的一些库不受支持，您仍然可以尝试在您的应用中使用新架构，但这需要暂时移除那些库。在您的代码库中创建一个新分支，并移除所有不兼容的库，直到您的应用可以正常运行。这将使您对哪些库需要在完全迁移到新架构之前进行改进有良好的了解。我们建议您在这些库的代码库中创建问题或拉取请求，以帮助它们与新架构兼容。或者，您可以切换到与新架构兼容的其他库。请参考 [React Native 目录](https://reactnative.directory/) 以查找兼容的库。
---
Note: React Native 中的已知问题
---
请参考 [React Native GitHub 存储库中标记为“类型：新架构”的问题](https://github.com/facebook/react-native/issues?q=is%3Aopen+is%3Aissue+label%3A%22Type%3A+New+Architecture%22)。
---
Note: Expo 库中的已知问题
---
在 Expo 库中没有与新架构相关的已知问题。
---
Note: 第三方库中的已知问题
---
自 React Native 0.74 以来，默认启用了各种互操作层。这使得为旧架构构建的许多库能够在新架构中无须任何更改即可工作。然而，互操作并不完美，某些库需要更新。最可能需要更新的库是那些发货或依赖于第三方本地代码的库。 [了解新架构中库的支持](https://github.com/reactwg/react-native-new-architecture/discussions/167)。
请参考 [React Native 目录](https://reactnative.directory/) 来获得更完整的库及其与新架构兼容性列表。以下库在 Expo 应用中被发现是流行的，并且已知不兼容：
以下是与 Expo 应用中流行库相关的已知问题。
- **react-native-maps**: 版本 1.20.x 是 SDK 53 的默认版本，支持新架构与互操作层，并且在大多数特性中运行良好。新架构优先版本在 1.21.0 中可用，仍在稳定中。我们鼓励您在您的应用中测试它，报告您发现的问题，并 [随时关注 GitHub 上的讨论](https://github.com/react-native-maps/react-native-maps/discussions/5355)。我们还在调查另一种方法，它可能会提供更顺畅的迁移路径，即依靠 [互操作层](https://github.com/reactwg/react-native-new-architecture/discussions/175) 而不是重写模块。值得一提的是，如果您的应用可以强制最低版本为 iOS 17，或者不需要在 iOS 上支持地图，则可以考虑使用 [`expo-maps`](/versions/latest/sdk/maps/)。
- **@stripe/react-native**: 从版本 0.45.0 开始支持新架构，该版本为 SDK 53 的默认版本。
- **@react-native-community/masked-view**: 使用 `@react-native-masked-view/masked-view` 代替。
- **@react-native-community/clipboard**: 使用 `@react-native-clipboard/clipboard` 代替。
- **rn-fetch-blob**: 使用 `react-native-blob-util` 代替。
- **react-native-fs**: 使用 `expo-file-system` 或 [react-native-fs 的一个分叉](https://github.com/birdofpreyru/react-native-fs) 代替。
- **react-native-geolocation-service**: 使用 `expo-location` 代替。
- **react-native-datepicker**: 使用 `react-native-date-picker` 或 `@react-native-community/datetimepicker` 代替。
---
Note: 在启用新架构后我的构建失败了
---
这并不完全令人惊讶！并非所有库都兼容，而且在某些情况下，兼容性仅在最近才添加，因此您将希望确保更新库到其最新版本。查看日志以确定哪些库不兼容。此外，运行 `npx expo-doctor@latest` 检查您的依赖项与 React Native 目录中的数据是否一致。
当您使用最新版本的库且其不兼容时，请向相应的 GitHub 存储库报告任何遇到的问题。创建一个 [最小可复现示例](https://stackoverflow.com/help/minimal-reproducible-example) 并向库的作者报告该问题。如果您认为问题源于 React Native 本身而不是某个库，请向 React Native 团队报告（同样，提供一个最小可复现示例）。
---


## React 编译器

学习如何在 Expo 应用中启用和使用 React 编译器。

新的 [React 编译器](https://react.dev/learn/react-compiler) 自动记忆组件和钩子，以实现细粒度的反应性。这可以显著提高您应用的性能。您可以通过以下说明在您的应用中启用它。
## 启用 React 编译器
Step 1: 
[检查您的项目与 React 编译器的兼容性](https://react.dev/learn/react-compiler#checking-compatibility)。
```sh
$ npx react-compiler-healthcheck@latest
```
这通常会验证您的应用是否遵循 [**React 规则**](https://react.dev/reference/rules)。
Step 2: 
在您的项目中安装 `babel-plugin-react-compiler` 和 React 编译器运行时：
    Babel 在 Expo SDK 54 及更高版本中自动配置。
    ```sh
$ npx expo install babel-plugin-react-compiler@beta
```
    ```sh
$ npx expo install babel-plugin-react-compiler@beta react-compiler-runtime@beta
```
Step 3: 
在您的应用配置文件中启用 React 编译器实验：
```json app.json
{
  "expo": {
    "experiments": {
      "reactCompiler": true
    }
  }
}
```
### 启用 linter
> 将来，以下所有步骤将由 Expo CLI 自动化。
此外，您还应使用 ESLint 插件持续强制执行您项目中的 React 规则。
Step 1: 
运行 [`npx expo lint`](/guides/using-eslint/#eslint) 以确保 ESLint 在您的应用中设置正确，然后安装 React 编译器的 ESLint 插件：
```sh
$ npx expo install eslint-plugin-react-compiler -D
```
Step 2: 
更新您的 [ESLint 配置](/guides/using-eslint/) 以包括该插件：
```js .eslintrc.js
// https://docs.expo.dev/guides/using-eslint/
const { defineConfig } = require('eslint/config');
const expoConfig = require('eslint-config-expo/flat');
const reactCompiler = require('eslint-plugin-react-compiler');
module.exports = defineConfig([
  expoConfig,
  reactCompiler.configs.recommended,
  {
    ignores: ['dist/*'],
  },
]);
```
## 渐进采用
您可以通过一些策略逐步在应用中采用 React 编译器：
Step 1: 
配置 Babel 插件，仅在特定文件或组件上运行。要做到这一点：
1. 如果您的项目没有 [**babel.config.js**](/versions/latest/config/babel/)，通过运行 `npx expo customize babel.config.js` 创建一个。
2. 将以下配置添加到 **babel.config.js**：
```js babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      [
        'babel-preset-expo',
        {
          'react-compiler': {
            sources: filename => {
              // 匹配要包括在 React 编译器中的文件名。
              return filename.includes('src/path/to/dir');
            },
          },
        },
      ],
    ],
  };
};
```
每当您更改 **babel.config.js** 文件时，您需要重新启动 Metro 打包器以应用更改：
```sh
$ npx expo start --clear
```
Step 2: 
使用 `"use no memo"` 指令选择不使用特定组件或文件的 React 编译器。
```jsx
function MyComponent() {
  'use no memo';
  return <Text>Will not be optimized</Text>;
}
```
## 使用
> 要更好地理解 React 编译器的工作原理，请查看 [React Playground](https://playground.react.dev/)。
改进主要是自动的。您可以删除 `useCallback`，`useMemo` 和 `React.memo` 的实例，转而使用自动记忆。类组件不会被优化。相反，请迁移到函数组件。
Expo 的 React 编译器实现仅在应用代码上运行（不包括节点模块），并且只在为客户端打包时运行（在服务器渲染中禁用）。
## 配置
您可以通过使用 Babel 配置中的 `react-compiler` 对象向 React 编译器 Babel 插件传递附加设置：
```js babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      [
        'babel-preset-expo',
        {
          'react-compiler': {
            // 直接传递给 React 编译器 Babel 插件。
            compilationMode: 'all',
            panicThreshold: 'all_errors',
          },
          web: {
            'react-compiler': {
              // 仅限 Web 的设置...
            },
          },
        },
      ],
    ],
  };
};
```


# 现有的 React Native 应用

## 在现有 React Native 应用中使用 Expo 概述

学习如何在现有的 React Native 应用中使用 Expo 工具和服务。

如果您有一个不使用任何 Expo 工具的 React Native 应用，您可能会想知道 Expo 能为您提供什么，您为什么可能希望使用 Expo 工具和服务，以及如何开始。
**Expo 提供的所有工具和服务在任何 React Native 应用中都表现良好**。
您可以使用 [EAS](/eas) 快速设置专业 CI/CD 工作流，以构建、审查、部署和更新您的应用。 [Expo CLI](/more/expo-cli/) 为 React Native 提供了最佳的命令行体验。 [Expo SDK](/versions/latest/) 是 React Native 的扩展标准库。它为开发者提供了高质量、维护良好的原生库，使用一致的 API 约定使其更易于学习和使用。
如果您曾经为 React Native 编写过原生模块，您会惊讶于使用 [Expo Modules API](/modules/overview/) 提供的标准 Swift 和 Kotlin DSL 构建和维护模块是多么容易。
还有很多内容可以探索，下面的链接将帮助您了解可用的选项。
## 渐进式采用步骤
以下是四个建议的渐进式采用阶段。这些阶段通常从快速更改以改善开发者体验开始，逐渐过渡到更重要的工作流和代码库优化。
只有第一阶段 &mdash; 前提条件 &mdash; 是其他阶段所必需的。遵循其指示后，您可以跳过到与您采用 Expo 目标最相关的工具和服务。
### 前提条件
这些第一步是后来采用 Expo 工具和服务所必需的：
  }
  href="/bare/installing-expo-modules"
/>
  }
  href="/bare/using-expo-cli/"
/>
### 快速成功
以下内容帮助改善开发体验并需要配置：
  }
  Icon={BookOpen02Icon}
  href="/bare/install-dev-builds-in-bare/"
/>
### 新工作流
一旦您的应用安装了 `expo` 包，您可以通过单个命令将您的应用提交到应用商店，或更新配置 `expo-updates` 库来管理应用代码的远程更新：
  }
  href="/bare/installing-updates/"
/>
### 新思维方式
以下有助于您项目的长期可维护性、原生代码维护和更轻松的升级：
## 常见问题
Note: 在我的现有 React Native 项目中采用 Expo 需要多长时间？
---
采用 Expo 不必一步到位。您可以从 _快速成功_ 开始，然后再转向更复杂的部分。您还可以根据项目的实际需要选择和选择希望采用的功能。
---
Note: 使用 Expo 在我的 React Native 应用中我将获得什么？
---
在您现有的 React Native 应用中采纳 Expo 工具可以帮助您通过 [Expo SDK](/versions/latest/) 加速开发，通过 [CNG](/workflow/continuous-native-generation/) 精简原生代码维护和升级，通过 [EAS Update](/eas-update/introduction/) 实现更快的部署等等。
---
Note: 谁在使用 Expo？
---
顶级公司在全球范围内使用 Expo，服务数百万终端用户。有关更多信息，请查看我们的 [Expo 展示](https://expo.dev/customers)。
---
Note: 采用 Expo 会对我的应用大小产生什么影响？
---
`expo` 包占用的空间很小，因为它仅包括每个应用中所需的一小部分模块，以及内置的自动链接基础设施和其他 Expo SDK 库。有关如何确定应用实际大小的更多信息，请参见 [了解应用大小](/distribution/app-size/)。
---
Note: 为什么 React Native 推荐使用 Expo？
---
大多数 React Native 开发者在构建应用时会解决一些常见问题，例如实现导航、访问原生 API、升级到新版本等。这需要使用一组特定的工具和库来构建和维护您的应用 &mdash; 这意味着您正在创建自己的框架。
Expo 通过提供一组原语来解决这些问题，帮助您（开发者）专注于构建应用。它还提供工具以在开发中更快迭代。有关更多信息，请参见 [为什么 React Native 推荐使用框架](https://reactnative.dev/blog/2024/06/25/use-a-framework-to-build-react-native-apps)。
---
Note: 我必须放弃我的原生项目才能使用 Expo 吗？
---
默认情况下，使用 `create-expo-app` 创建的 Expo 项目使用 [连续原生生成 (CNG)](/workflow/continuous-native-generation/) 并且不包含 **android** 和 **ios** 原生目录。如果您在现有的 React Native 应用中逐步采用 Expo，您不必删除这些目录。您可以使用 `npx expo run:[android|ios]` 作为 `@react-native-community/cli` 提供的命令的替代方案，以本地编译您的应用，并保留原生项目的配置。
---
Note: 我在使用 CodePush。我可以继续在 Expo 中使用它吗？
---
CodePush 将在 2025 年 3 月被退休，并与 React Native 的新架构不兼容，因此，从长远来看，我们推荐切换到 EAS 更新以管理您应用代码的远程更新。不过，您可以今天在启用 CodePush 的应用中开始使用 Expo 工具，包括 Expo SDK、Expo CLI、EAS Build 等。
---
Note: 我必须使用 EAS 构建吗？
---
[Expo 应用服务 (EAS)](/eas/) 是深入集成的云服务，提供构建、测试和部署应用的工具。
虽然我们建议使用 EAS 以便与团队成员进行顺畅协作和快速分发，但您可以通过本地编译您的应用、在 CI 上编译，或以任何您喜欢的方式进行编译。
---
Note: 我可以在我的代码中安装第三方原生库吗？
---
是的，您可以安装和使用需要原生项目（**android** 和 **ios**）配置的第三方库，或提供与 [开发构建](/workflow/overview/#development-builds) 兼容的 [配置插件](/config-plugins/introduction/)。有关更多信息，请参见 [使用第三方库](/workflow/using-libraries/#third-party-libraries)。
---
Note: 我在使用 React Navigation。我必须使用 Expo Router 吗？
---
您可以继续在项目中使用任何导航库。不过，我们建议使用 Expo Router 以获得所有 [在此描述的好处](/router/introduction)。
---


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

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

要在您的应用中使用 Expo 模块，您需要安装并配置 `expo` 包。
`expo` 包的体积较小；它仅包括几乎每个应用所需的最小包以及构建其他 Expo SDK 包的模块和自动链接基础设施。一旦在您的项目中安装和配置了 `expo` 包，您可以使用 `npx expo install` 来添加 SDK 中的任何其他 Expo 模块。
根据您[初始化项目](/bare/overview/)的方式，您可以通过两种方式安装 Expo 模块：[自动](#automatic-installation)或[手动](#manual-installation)。
## 自动安装
要安装和使用 Expo 模块，最简单的方式是使用 `install-expo-modules` 命令。
<InstallSection
  packageName="expo"
  cmd={['# 自动安装和配置 expo 包', '$ npx install-expo-modules@latest']}
  hideBareInstructions
/>
- <YesIcon small /> **当命令成功时**，您将能够在您的应用中添加任何 Expo
  模块！继续查看[使用](#usage)以获取更多信息。
- <NoIcon small /> **如果命令失败**，请遵循手动安装说明。
  以编程方式更新代码可能比较棘手，如果您的项目与默认的 React Native
  项目有显著不同，那么您需要执行手动安装并根据这里的说明调整您的代码库。
## 手动安装
以下说明适用于在 React Native 0.81 中安装最新版本的 Expo 模块。对于以前的版本，请查看[本地升级助手](/bare/upgrade)以了解这些文件是如何自定义的。
<InstallSection packageName="expo" cmd={['$ npm install expo']} hideBareInstructions />
安装完成后，从以下差异中应用更改以配置项目中的 Expo 模块。预计这将花费大约五分钟，您可能需要根据项目的定制程度稍作调整。
### Android 的配置
<DiffBlock source="/static/diffs/expo-android.diff" />
### iOS 的配置
<DiffBlock source="/static/diffs/expo-ios.diff" />
可选地，您还可以向您的 **AppDelegate.swift** 添加其他委托方法。一些库可能需要这些方法，因此除非您有充分的理由不添加，建议您添加它们。[查看 AppDelegate.swift 中的委托方法](https://github.com/expo/expo/blob/sdk-54/templates/expo-template-bare-minimum/ios/HelloWorld/AppDelegate.swift#L24-L42)。
保存所有更改并在 Xcode 中将您的 iOS 部署目标更新为 `iOS 15.1`：
- 在 Xcode 中打开 **your-project-name.xcworkspace**，在左侧边栏中选择您的项目。
- 选择 **Targets** > **your-project-name** > **Build Settings** > **iOS Deployment Target** 并将其设置为 `iOS 15.1`。
最后一步是再次安装项目的 CocoaPods，以拉取 `use_expo_modules!` 指令检测到的 Expo 模块，该指令已添加到 **Podfile** 中：
<InstallSection
  packageName="expo"
  cmd={['# 安装 pods', '$ npx pod-install', '', '# 或者，运行命令将为您安装', '$ npx expo run:ios']}
  hideBareInstructions
/>
### 配置 Expo CLI 以在 Android 和 iOS 上打包
我们建议使用 Expo CLI 和相关工具配置来打包您的应用 JavaScript 代码和资产。这增加了在 **package.json** 中使用 `"main"` 字段以使用 [Expo Router](/router/introduction/) 库的支持。不使用 Expo CLI 进行打包可能会导致意外行为。[了解有关 Expo CLI 的更多信息](/bare/using-expo-cli/)。
Note: 在您的 babel.config.js 中使用 babel-preset-expo
---
  <DiffBlock source="/static/diffs/babel-config.diff" />
---
Note: 在您的 metro.config.js 中扩展 expo/metro-config
---
  <DiffBlock source="/static/diffs/metro-config.diff" />
---
Note: 配置 Android 项目以使用 Expo CLI 打包
---
  <DiffBlock source="/static/diffs/expo-cli-android.diff" />
---
Note: 配置 iOS 项目以使用 Expo CLI 打包
---
将 Xcode 中 **Build Phases** > **Bundle React Native code and images** 下的脚本替换为以下内容：
```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
# 默认情况下，项目根目录比 ios 目录高一级
export PROJECT_ROOT="$PROJECT_DIR"/..
if [[ "$CONFIGURATION" = *Debug* ]]; then
  export SKIP_BUNDLING=1
fi
if [[ -z "$ENTRY_FILE" ]]; then
  # 使用打包器的入口解析设置入口 JS 文件。
  export ENTRY_FILE="$("$NODE_BINARY" -e "require('expo/scripts/resolveAppEntry')" "$PROJECT_ROOT" ios relative | tail -n 1)"
fi
if [[ -z "$CLI_PATH" ]]; then
  # 使用 Expo CLI
  export CLI_PATH="$("$NODE_BINARY" --print "require.resolve('@expo/cli')")"
fi
if [[ -z "$BUNDLE_COMMAND" ]]; then
  # 默认的 Expo CLI 打包命令
  export BUNDLE_COMMAND="export:embed"
fi
`"$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'"`
```
并通过在 **AppDelegate.swift** 中进行以下更改来支持 **package.json** 中的 `"main"` 字段：
```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
```
---
## 使用方法
### 验证安装
您可以通过从 [`expo-constants`](/versions/latest/sdk/constants) 中记录一个值来验证安装是否成功。
- 运行 `npx expo install expo-constants`
- 然后，运行 `npx expo run` 并修改您的应用 JavaScript 代码以添加以下内容：
```js
import Constants from 'expo-constants';
console.log(Constants.systemFonts);
```
### 使用 Expo SDK 包
一旦 `expo` 包在您的项目中安装和配置，您可以使用 `npx expo install` 来添加 SDK 中的任何其他 Expo 模块。有关更多信息，请参见 [使用库](/workflow/using-libraries)。
### 包含在 `expo` 包中的 Expo 模块
以下 Expo 模块作为 `expo` 包的依赖引入：
- [`expo-asset`](/versions/latest/sdk/asset) - 一个仅 JavaScript 的包，围绕 `expo-file-system` 构建，并为所有 Expo 模块提供一个共同的基础。
- [`expo-constants`](/versions/latest/sdk/constants) - 提供访问清单的功能。
- [`expo-file-system`](/versions/latest/sdk/filesystem) - 与设备文件系统交互。被 `expo-asset` 和许多其他 Expo 模块使用。开发人员常常在应用程序代码中直接使用。
- [`expo-font`](/versions/latest/sdk/font) - 在运行时加载字体。此模块是可选的，可以安全地删除，但如果您使用 `expo-dev-client` 进行开发，则建议保留，并且 `@expo/vector-icons` 需要它。
- [`expo-keep-awake`](/versions/latest/sdk/keep-awake) - 防止您的设备在开发应用时进入睡眠模式。此模块是可选的，可以安全地删除。
要排除任何这些模块，请参考以下关于[排除特定模块的自动链接](#excluding-specific-modules-from-autolinking)的指南。
### 从自动链接中排除特定模块
如果您需要排除未使用的 Expo 模块的本地代码，但它们是由其他依赖项安装的，您可以在 **package.json** 中使用 [`expo.autolinking.exclude`](/modules/autolinking/#exclude) 属性：
```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 模块 API 和 Expo CLI。本指南涵盖安装步骤、使用 Expo CLI 的好处，以及迁移到 Expo CLI 后如何编译和运行您的项目。
强烈建议在使用其他 Expo 工具时使用 Expo CLI。许多工具（如 EAS 更新、Expo 路由器和 expo-dev-client）需要它，其他功能在没有它的情况下可能无法正常工作。
## 安装 `expo` 包
在大多数情况下，在项目目录中执行以下命令以安装包就足够了：
```sh
$ npx install-expo-modules@latest
```
有关详细的安装指南，请参见 [安装 Expo 模块](/bare/installing-expo-modules)。
> **info** 安装 `expo` 包后，您需要配置项目以使用 Expo CLI。这包括设置 Metro 配置、Babel 预设和本机项目配置。有关完整设置说明，请参见 [为 Android 和 iOS 打包配置 Expo CLI](/bare/installing-expo-modules/#configure-expo-cli-for-bundling-on-android-and-ios) 部分。
## 为什么选择 Expo CLI 而不是 React Native CLI
Expo CLI 命令相比于 `@react-native-community/cli` 中的类似命令提供了几个好处，包括：
- 通过 <kbd>j</kbd> 快捷键瞬时访问 Hermes 调试器。
- 调试器随附 [React Native DevTools](/debugging/tools/#debugging-with-react-native-devtools)。
- 支持 [持续原生生成 (CNG)](/workflow/continuous-native-generation/) 和 [`expo prebuild`](/workflow/prebuild/)，方便升级、白标、轻松设置第三方包以及更好的代码库可维护性（通过减少表面面积）。
- 支持使用 [`expo-router`](/router/introduction/) 的基于文件的路由。
  - [开发中的异步打包](/router/reference/async-routes)。
- 内置 [环境变量支持](/guides/environment-variables) 和 **.env** 文件集成。
- 在终端中直接查看原生日志 alongside JavaScript 日志。
- 使用 Expo CLI 的 `xcpretty` 风格工具改进原生构建日志格式，该工具专门为 React Native 应用构建。例如，在编译 Pod 时，您可以看到哪个 Node 模块包含了它。
- [一流的 TypeScript 支持](/guides/typescript)。
- 对 `tsconfig.json` 别名与 `paths` 和 `baseUrl` 的 [内置支持](/guides/typescript/#path-aliases-optional)。
- 使用 Metro 的 [Web 支持](/guides/customizing-metro/#adding-web-support-to-metro)。对于 React Native Web 完全类型化。
- 对现代 [CSS 支持](/versions/latest/config/metro#css)，支持 Tailwind、PostCSS、CSS Modules、SASS 等。
- 使用 Expo Router 和 Metro web 进行静态网站生成。
- 开箱即用的 [单一代码库支持](/guides/monorepos)。
- 支持 Expo 工具，如 [`expo-dev-client`](/develop/development-builds/introduction)、[Expo 更新协议](/technical-specs/expo-updates-1) 和 [EAS 更新](/eas-update/introduction)。
- 当使用 `npx expo run:ios` 时，自动执行 `pod install`。
- `npx expo install` 为知名包选择兼容的依赖版本。
- 在运行 `npx expo run:[android|ios]` 和 `npx expo start` 时自动检测端口。如果默认端口正在运行其他应用，则会使用不同的端口。
- 使用 <kbd>Shift</kbd> + <kbd>a</kbd> 或 <kbd>Shift</kbd> + <kbd>i</kbd> 从交互提示中选择启动 Android 或 iOS 设备的快捷方式。
- 内置支持通过 [ngrok 隧道](/develop/development-builds/development-workflows/#tunnel-urls) 来服务您的应用。
- 在任何端口开发，使用任何入口 JavaScript 文件。
我们建议对于目标 Android、iOS 和/或 web 的大多数 React Native 项目使用 Expo CLI。它尚未对最流行的非树平台（如 Windows 和 macOS）提供内置支持。如果要为这些平台构建，您可以利用支持的 Expo CLI 平台和 `@react-native-community/cli` 进行其他平台的构建。
## 编译并运行您的应用
安装 `expo` 包后，您可以使用以下命令作为 `npx react-native run-android` 和 `npx react-native run-ios` 的替代：
```sh
$ npx expo run:android
$ npx expo run:ios
```
在构建项目时，您可以使用 `--device` 标志选择设备或模拟器。这也适用于连接到您计算机的任何 iOS 设备。
## 独立启动打包器
`npx expo run:[android|ios]` 自动启动打包器/开发服务器。如果您想用 `npx expo start` 命令独立启动打包器，请将 `--no-bundler` 参数传递给 `npx expo run:[android|ios]` 命令。
## 常见问题
Note: 我可以在不安装 Expo 模块 API 的情况下使用 Expo CLI 吗？
---
Expo 模块 API 在您使用 `npx install-expo-modules` 安装 `expo` 包时也会被安装。如果您想现在尝试 Expo CLI 而不安装 Expo 模块 API，请使用 `npm install` 安装 `expo` 包，然后配置 **react-native.config.js** 以将该包排除在自动链接之外：
```js react-native.config.js
module.exports = {
  dependencies: {
    expo: {
      platforms: {
        android: null,
        ios: null,
        macos: null,
      },
    },
  },
};
```
> **注意：** 在未安装 Expo API 模块的情况下，某些功能（例如 `expo-dev-client` 或 `expo-router`）不可用。
---
Note: 我可以对非树平台（如 macOS 或 Windows）使用 prebuild 吗？
---
可以！有关更多信息，请参阅 [自定义 Prebuild 示例仓库](https://github.com/byCedric/custom-prebuild-example)。
---
## 下一步
现在，您已在项目中安装并配置了 `expo` 包，可以开始使用 Expo CLI 和 SDK 的所有功能。以下是一些推荐的下一步，以深入了解：


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

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

`expo-updates` 是一个库，可以让您的应用管理应用代码的远程更新。它与配置的远程更新服务通信，以获取可用更新的信息。本指南解释了如何设置一个裸 React Native 项目，以便与 [EAS Update](/eas-update/introduction) 一起使用，这是一个托管的远程更新服务，包含简化安装和配置 `expo-updates` 库的工具。
Note: 您在项目中使用持续原生生成（CNG）吗？
---
您可能阅读了错误的指南。要在使用 [CNG](/workflow/continuous-native-generation/) 的项目中使用 `expo-updates`，请参见 [EAS Update "开始使用"](/eas-update/getting-started/)。
---
## 先决条件
**必须安装并配置 `expo` 包。** 如果您通过 `npx @react-native-community/cli@latest init` 创建了项目，并且没有安装其他任何 Expo 库，则在继续之前需要 [安装 Expo 模块](/bare/installing-expo-modules)。
## 安装
要开始，请安装 `expo-updates`：
```sh
$ npx expo install expo-updates
```
然后，为 iOS 安装 pods：
```sh
$ npx pod-install
```
## 配置 expo-updates 库
应用以下部分的差异中的更改，以在您的项目中配置 `expo-updates`。
### JavaScript 和 JSON
运行 `eas update:configure` 以设置 **app.json** 中的 `updates` URL 和 `projectId`。
```sh
$ eas update:configure
```
修改 **app.json** 的 `expo` 部分。 如果您使用 `npx @react-native-community/cli@latest init` 创建了项目，则需要添加以下更改，包括 [`updates` URL](/versions/latest/config/app/#url)。
> 下面示例中的 `updates` URL 和 `projectId` 是与 EAS Update 一起使用的。当运行 `eas update:configure` 时，EAS CLI 会正确设置此 URL 以用于 EAS Update 服务。
<DiffBlock source="/static/diffs/expo-updates-app-json.diff" />
如果您想要设置一个 [自定义 `expo-updates` 服务器](https://github.com/expo/custom-expo-updates-server)，请将您的 URL 添加到 **app.json** 中的 `updates.url`。
```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
修改 **android/app/build.gradle** 以检查 Expo 文件中的 JS 引擎配置（JSC 或 Hermes）：
<DiffBlock source="/static/diffs/expo-updates-android-build-gradle.diff" />
修改 **android/app/src/main/AndroidManifest.xml** 以添加 `expo-updates` 配置 XML，以便与 **app.json** 的内容匹配：
<DiffBlock source="/static/diffs/expo-updates-android-manifest.diff" />
如果使用更新服务器 URL（运行在同一台机器上的自定义非 HTTPS 更新服务器），您需要修改 **android/app/src/main/AndroidManifest.xml** 以添加更新服务器 URL 并启用 `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>
```
将 Expo 运行时版本字符串密钥添加到 **android/app/src/main/res/values/strings.xml**：
<DiffBlock source="/static/diffs/expo-updates-strings-xml.diff" />
### iOS
将文件 **Podfile.properties.json** 添加到 **ios** 目录：
```json ios/Podfile.properties.json
{
  "expo.jsEngine": "hermes"
}
```
修改 **ios/Podfile** 以检查 Expo 文件中的 JS 引擎配置（JSC 或 Hermes）：
<DiffBlock source="/static/diffs/expo-updates-ios-podfile.diff" />
使用 Xcode，将 **Expo.plist** 文件添加到 **ios/your-project/Supporting**，内容如下，以匹配 **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>
```
## 下一步
- 要开始使用 EAS Update 和 EAS Build，请参见 EAS Update [开始使用](/eas-update/getting-started/)。
- 请参见 [`expo-updates` API 参考](/versions/latest/sdk/updates/) 以获取有关如何使用该库的更多信息。
- 请参见如何直接使用 [EAS Update 和本地构建](/eas-update/standalone-service/)。
- 也可以使用实现 [Expo 更新协议](/technical-specs/expo-updates-1/) 的自定义服务器来使用 `expo-updates`。请参见 [`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`。
Note: 您需要创建一个新项目吗？
---
如果您从新项目开始，请使用 `with-dev-client` 模板创建它：
```sh
$ npx create-expo-app -e with-dev-client
```
---
Note: 您的项目中使用了持续原生生成 (CNG) 吗？
---
要在使用 [CNG](/workflow/continuous-native-generation/) 的项目中使用 `expo-dev-client`，请参见 [创建开发构建](/develop/development-builds/create-a-build/)。
---
## 先决条件
**必须安装和配置 `expo` 包。** 如果您是通过 `npx @react-native-community/cli@latest init` 创建项目，并且没有安装任何其他 Expo 库，您需要在继续之前 [安装 Expo 模块](/bare/installing-expo-modules)。
Step 1: 
## 安装 expo-dev-client
将 `expo-dev-client` 库添加到您的 **package.json** 中：
```sh
$ npx expo install expo-dev-client
```
如果您的项目在磁盘上有 **ios** 目录，请运行以下命令以完全安装 `expo-dev-client` 的原生代码：
```sh
$ npx pod-install
```
如果您的项目没有 **ios** 目录，则可以跳过此步骤。
Step 2: 
## 配置深度链接
Expo CLI 使用深度链接来启动您的项目，如果您计划 [使用 `expo-dev-client` 启动预览更新](/eas-update/getting-started/)，并且已经向项目添加了自定义深度链接方案，这也很有用。
如果您尚未为您的应用配置 `scheme` 以支持深度链接，那么请使用 `uri-scheme` 库为您执行此操作。
```sh
$ npx uri-scheme list
$ npx uri-scheme add your-scheme
```
有关更多信息，请参见 [`uri-scheme` 库](https://www.npmjs.com/package/uri-scheme)。
Step 3: 
## 构建并安装应用
使用您选择的工具创建应用的调试构建。例如，您可以通过 [使用 Expo CLI 本地开发应用](/guides/local-app-development/) 或 [在云中使用 EAS Build](/develop/development-builds/create-a-build/) 来完成此操作。


## 原生项目升级助手

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

如果您管理您的原生项目（以前称为裸工作流），要 [升级到最新的 Expo SDK](/workflow/upgrading-expo-sdk-walkthrough/)，您必须对您的原生项目进行更改。找到哪些原生文件需要更改以及需要在文件中更新什么可能是一个复杂的过程。
以下指南提供比较您的项目当前 SDK 版本与您希望升级的目标 SDK 版本之间原生项目文件的差异。您可以根据项目使用的 `expo` 包版本对项目进行更改。此页面上的工具类似于 [React Native 升级助手](https://react-native-community.github.io/upgrade-helper/)。然而，它们是围绕使用 Expo 模块和相关工具的项目进行的。
> 想避免完全升级原生代码吗？请查看 [连续原生生成 (CNG)](/workflow/continuous-native-generation/)，了解 Expo Prebuild 如何在构建之前生成您的原生项目。
## 升级原生项目文件
一旦您 [升级了您的 Expo SDK 版本和相关依赖项](/workflow//upgrading-expo-sdk-walkthrough/#how-to-upgrade-to-the-latest-sdk-version)，请使用下面的差异工具了解您需要对原生项目进行的更改，并使其与当前 Expo SDK 版本保持同步。
选择您的 **from SDK version** 和 **to SDK version** 以查看生成的差异。然后，通过复制和粘贴或手动对项目文件进行更改来将这些更改应用到您的原生项目中。
<TemplateBareMinimumDiffViewer />


# 现有的原生应用

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

如何将 Expo 工具集成到现有原生应用（“棕地”应用）的概述。

一个使用其他技术构建的现有原生应用，其主要入口点*不是* React Native 视图，通常被称为“棕地”应用。例如，如果您的应用是使用 UIKit 和 Swift 构建的，并且您想在单个屏幕上使用 React Native，那么这被视为“现有原生应用”和“棕地”。
相对而言，“绿地”应用是从一开始就使用 Expo 或 React Native 创建的，或者 React Native 是入口点，并且所有其他 UI 都从这里分支出去。
根据这些定义，如果您有一个 Android 或 iOS 的“现有原生应用”，并且您想学习如何在您的项目中使用 Expo 和 React Native（可能是在单个屏幕上或甚至单个功能），那么本指南适合您。
## 与现有原生应用的兼容性
> **info** 支持将 Expo 模块集成到现有原生项目中仍处于实验阶段。如果您遇到问题，[在 GitHub 上创建问题](https://github.com/expo/expo/issues)。在现有原生应用的上下文中，并非所有工具和服务的功能都可用。
Expo 主要是针对绿地应用构建的，但我们正越来越多地投资于棕地场景。并非所有 Expo 工具和服务目前都与现有原生项目兼容。此外，棕地集成的全面文档可能还不可用，您可能需要将其他相关文档调整到您的上下文中。
| 工具/服务                                                                          | 支持棕地？ |
| ---------------------------------------------------------------------------------- | ---------- |
| [Expo SDK](/versions/latest/) - React Native 的扩展标准库                          | 是         |
| [Expo Modules API](/modules/overview/) - 使用地道的 Swift/Kotlin API 构建原生扩展  | 是         |
| [Expo Router](/router/introduction/) - 基于文件的路由和导航                        | 否         |
| [Expo CLI](/more/expo-cli/) - 从终端运行和开发应用的工具                           | 是         |
| [Expo Dev Client](/versions/latest/sdk/dev-client/) - 向调试构建添加应用内开发工具 | 否         |
| [EAS Build](/build/introduction/) - 专为 Expo/React Native 构建的 CI/CD 服务       | 是         |
| [EAS Submit](/submit/introduction/) - 将您的应用上传到商店的托管服务               | 是         |
| [EAS Update](/eas-update/introduction/) - 应用 JavaScript 和资产的即时更新         | 是         |
## 下一步


## 如何将 Expo 添加到现有的原生（棕地）应用

添加 Expo 和 React Native 到现有原生应用以及添加第一个视图组件的指南。

React Native 和 Expo 是灵活的，可以逐步采用，一次一个屏幕（甚至一个视图）。您甚至可能会发现，以这种方式使用 Expo 是最适合您特定应用程序的，或者您最终可能会在应用程序的更多表面上慢慢采用它。无论哪种方式，这种灵活性使开发者能够立即在他们的原生应用中采用现代跨平台工具，而不是冒着完全重写的风险。
本指南将引导您完成将 React Native 视图添加到现有原生应用中的步骤。这里介绍的方法被称为“集成”方法，因为 React Native 和 Expo 的集成方式与您使用的其他库相同。
另一种流行的技术是我们所称的“孤立”方法，在这种方法中，您的 Expo 应用被打包为一个库，并被主现有应用视为一个黑箱。孤立方法的指南将很快提供。现在，回到在您的现有原生应用中使用“集成”方法。
## 前提条件
要将 React Native 集成到您的现有应用中，您需要设置一个 JavaScript 开发环境。这包括安装 Node.js 来运行 Expo CLI 和 Yarn 来管理项目的 JavaScript 依赖关系。
- [Node.js (LTS)](https://nodejs.org/en/): 执行 JavaScript 代码和 Expo CLI 的运行时。
- [Yarn](https://yarnpkg.com/): 用于安装和管理 JavaScript 依赖关系的包管理器。
- <PlatformTag platform="ios" /> [CocoaPods](https://cocoapods.org/): iOS
  可用的依赖管理系统之一。CocoaPods 是一个 Ruby
  [gem](https://en.wikipedia.org/wiki/RubyGems)。您可以使用随最新版本的 macOS 附带的 Ruby 版本安装
  CocoaPods。
Learn more from the [设置环境指南](/get-started/set-up-your-environment/)。
## 创建一个 Expo 项目
首先，在您现有的原生项目的根目录中创建一个 Expo 项目。
```sh
$ npx create-expo-app my-project
```
此命令创建一个名为 **my-project** 的新目录，其中包含您的新 Expo 项目。虽然您可以将项目命名为任何名称，但本指南使用 **my-project** 以保持一致。新项目包括一个示例 TypeScript 应用程序，以帮助您入门。
## 设置您的项目结构
标准的 React Native 项目将原生代码放在 **android** 和 **ios** 目录中。具体的实现方式取决于您的项目，但可以简单地创建目录并将项目移到那里。例如：
For Android: 
```sh
$ mkdir my-project/android
$ mv /path/to/your/android-project my-project/android/
```
For iOS: 
```sh
$ mkdir my-project/ios
$ mv /path/to/your/ios-project my-project/ios/
```
Note: 不能将您的原生项目移动到 android 和 ios 目录？
---
### 设置单体库
单体库，或称为“单一代码库”，是包含多个应用程序或包的单一代码库。[了解更多](/guides/monorepos/)。
设置单体库将确保 Android 和 iOS 脚本能够在自定义文件夹结构下调用 Node 库中的命令。要设置 Yarn 单体库，请在项目根目录创建一个 **package.json** 文件，并添加以下内容：
```json package.json
{
  "version": "1.0.0",
  "private": true,
  "workspaces": ["my-project"]
}
```
然后运行 `yarn install` 来安装依赖关系。这将确保 **node_modules** 被安装在项目的根目录，并且原生脚本可以与 React Native 代码交互。请确保将 `["my-project"]` 更改为您在前一步创建的 Expo 项目的名称。
> **info** 选择单体库需要您在 Gradle/CocoaPods 中配置自定义项目根目录。这将在接下来的部分中介绍。
---
## 配置您的原生项目
要在 Android 上集成 React Native，您需要修改以下文件来配置原生项目：
- **Gradle 文件**: **settings.gradle**，顶层 **build.gradle**，**app/build.gradle** 和 **gradle.properties** 来添加 React Native Gradle 插件（RNGP）和其他属性。
- **AndroidManifest.xml**: 添加必要的权限。 ([了解更多](#configuring-your-manifest))
- **MainActivity**: 加载您的 React Native 应用程序。
### 配置 Gradle
Step 1: 
首先，编辑您的 **settings.gradle** 文件并添加以下行（使用 [bare minimum template](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/settings.gradle) 作为参考）：
```groovy settings.gradle
// Configures the React Native Gradle Settings plugin used for autolinking
pluginManagement {
  def reactNativeGradlePlugin = new File(
    providers.exec {
      workingDir(rootDir)
      commandLine("node", "--print", "require.resolve('@react-native/gradle-plugin/package.json', { paths: [require.resolve('react-native/package.json')] })")
    }.standardOutput.asText.get().trim()
  ).getParentFile().absolutePath
  includeBuild(reactNativeGradlePlugin)
  def expoPluginsPath = new File(
    providers.exec {
      workingDir(rootDir)
      commandLine("node", "--print", "require.resolve('expo-modules-autolinking/package.json', { paths: [require.resolve('expo/package.json')] })")
    }.standardOutput.asText.get().trim(),
    "../android/expo-gradle-plugin"
  ).absolutePath
  includeBuild(expoPluginsPath)
}
plugins {
  id("com.facebook.react.settings")
  id("expo-autolinking-settings")
}
extensions.configure(com.facebook.react.ReactSettingsExtension) { ex ->
  ex.autolinkLibrariesFromCommand(expoAutolinking.rnConfigCommand)
}
expoAutolinking.useExpoModules()
// rootProject.name = 'HelloWorld'
expoAutolinking.useExpoVersionCatalog()
includeBuild(expoAutolinking.reactNativeGradlePlugin)
// Include your existing Gradle modules here.
// include(":app")
```
Note: 使用自定义文件夹结构？
---
如果您使用自定义文件夹结构，则需要在 **settings.gradle** 中明确设置项目根目录，以便自动链接工作。修改以下行：
<DiffBlock source="/static/diffs/brownfield/android/settings-gradle-custom-root.diff" />
---
Step 2: 
然后打开您的顶层 **build.gradle** 并添加此行（根据 [bare minimum template](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/build.gradle) 建议）：
<DiffBlock source="/static/diffs/brownfield/android/build-gradle.diff" />
这会确保 React Native Gradle 和 Expo 插件在您的项目中可用并已应用。
Step 3: 
在您应用的 **build.gradle** 文件中添加以下行（通常是 **app/build.gradle** &mdash; 您可以使用 [bare minimum template file as reference](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/app/build.gradle)）：
<DiffBlock source="/static/diffs/brownfield/android/app-build-gradle.diff" />
Note: 使用自定义文件夹结构？
---
如果您使用自定义文件夹结构，则需要将 `projectRoot` 值调整为指向 **app/build.gradle** 中Expo 项目的根目录。修改以下行：
<DiffBlock source="/static/diffs/brownfield/android/app-build-gradle-custom-root.diff" />
---
Step 4: 
最后，打开您应用的 **gradle.properties** 文件，并添加以下行（使用 [bare minimum template file as reference](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/gradle.properties)）：
```properties gradle.properties
reactNativeArchitectures=armeabi-v7a,arm64-v8a,x86,x86_64
newArchEnabled=true
hermesEnabled=true
```
### 配置您的清单
Step 1: 
首先，确保在您的 **AndroidManifest.xml** 中拥有 `INTERNET` 权限：
<DiffBlock source="/static/diffs/brownfield/android/android-manifest-internet-permission.diff" />
Step 2: 
现在在您的 **debug** **AndroidManifest.xml** 中，启用 [清晰文本流量](https://developer.android.com/training/articles/security-config#CleartextTrafficPermitted)：
<DiffBlock source="/static/diffs/brownfield/android/android-manifest-cleartext-traffic.diff" />
这是让您的应用通过 HTTP 与本地 [Metro bundler](https://metrobundler.dev/) 通信所必需的。您可以使用 bare minimum 模板中的 **AndroidManifest.xml** 文件作为参考：[main](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/app/src/main/AndroidManifest.xml) 和 [debug](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/app/src/debug/AndroidManifest.xml)
### 与您的代码集成
现在，您需要添加一些原生代码以启动 React Native 运行时，并告诉它渲染您的 React 组件。
#### 更新您的 `Application` 类
首先更新您的 `Application` 类以初始化 React Native。您可以使用来自 [bare minimum template](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/app/src/main/java/com/helloworld/MainApplication.kt) 的 **MainApplication.kt** 作为参考：
<DiffBlock source="/static/diffs/brownfield/android/main-application.diff" />
#### 创建一个 `ReactActivity`
创建一个新的 `Activity`，它将扩展 `ReactActivity` 并托管 React Native 代码。此活动将负责启动 React Native 运行时并渲染 React 组件。您可以使用 [bare minimum template file from **MainActivity.kt**](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/app/src/main/java/com/helloworld/MainActivity.kt) 作为参考：
```kotlin MyReactActivity.kt
// package <your-package-here>
import android.os.Build
import com.facebook.react.ReactActivity
import com.facebook.react.ReactActivityDelegate
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
import com.facebook.react.defaults.DefaultReactActivityDelegate
import expo.modules.ReactActivityDelegateWrapper
class MyReactActivity : ReactActivity() {
  /**
   * 返回从 JavaScript 注册的主组件的名称。这用于安排
   * 组件的渲染。
   */
  override fun getMainComponentName(): String = "main"
  /**
   * 返回 [ReactActivityDelegate] 的实例。我们使用 [DefaultReactActivityDelegate]
   * 这允许您通过一个布尔标志 [fabricEnabled] 来启用新架构
   */
  override fun createReactActivityDelegate(): ReactActivityDelegate {
    return ReactActivityDelegateWrapper(
          this,
          BuildConfig.IS_NEW_ARCHITECTURE_ENABLED,
          object : DefaultReactActivityDelegate(
              this,
              mainComponentName,
              fabricEnabled
          ){})
  }
}
```
将新 Activity 添加到您的 **AndroidManifest.xml** 文件中，确保将 `MyReactActivity` 的主题设置为 `Theme.AppCompat.Light.NoActionBar`（或任何非 ActionBar 主题），以避免您的应用在 React Native 屏幕上呈现 `ActionBar`：
<DiffBlock source="/static/diffs/brownfield/android/android-manifest-add-activity.diff" />
现在您的活动已准备好运行一些 JavaScript 代码。
要在 iOS 上集成 React Native，您需要通过修改以下文件来配置原生 iOS 项目：
- **Podfile**: 添加 React Native 依赖项。
- **Xcode project**: 添加用于捆绑 JavaScript 代码的构建阶段。
- **Info.plist**: 配置 React Native 所需的应用设置。
### 配置 CocoaPods
如果您的项目没有 **Podfile**，您可以使用 [bare minimum template](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/ios/Podfile) 作为参考创建一个：
```rb Podfile
require File.join(File.dirname(`node --print "require.resolve('expo/package.json')"`), "scripts/autolinking")
require File.join(File.dirname(`node --print "require.resolve('react-native/package.json')"`), "scripts/react_native_pods")
require 'json'
platform :ios, '15.1'
install! 'cocoapods',
  :deterministic_uuids => false
prepare_react_native_project!
target 'HelloWorld' do
  use_expo_modules!
  config_command = [
    'npx',
    'expo-modules-autolinking',
    'react-native-config',
    '--json',
    '--platform',
    'ios'
  ]
  config = use_native_modules!(config_command)
  use_frameworks! :linkage => ENV['USE_FRAMEWORKS'].to_sym if ENV['USE_FRAMEWORKS']
  use_react_native!(
    :path => config[:reactNativePath],
    :hermes_enabled => true,
    # 您应用根目录的绝对路径。
    :app_path => "#{Pod::Config.instance.installation_root}/..",
    :privacy_file_aggregation_enabled => true,
  )
  post_install do |installer|
    react_native_post_install(
      installer,
      config[:reactNativePath],
      :mac_catalyst_enabled => false,
    )
  end
end
```
如果您的项目已经有一个 **Podfile**，您需要手动将 React Native 依赖项合并到现有的 **Podfile** 中。
Note: 使用自定义文件夹结构？
---
如果您使用自定义文件夹结构，则需要在 **Podfile** 中明确设置项目根目录，以便自动链接工作。修改 **Podfile** 中的以下行：
<DiffBlock source="/static/diffs/brownfield/ios/podfile-custom-root.diff" />
---
现在，运行以下命令：
```sh
$ pod install
```
运行 `pod` 命令将把 React Native 代码集成到您的应用中，允许您的 iOS 文件导入 React Native 头文件。
### 配置您的 Xcode 项目
Step 1: 
在 `pod install` 命令之后，CocoaPods 将创建一个 Xcode 工作区 **\{Project\}.xcworkspace**，您需要打开 **xcworkspace** 项目而不是传统的 **xcodeproj** 项目。或者，您可以使用以下命令打开项目：
```sh
$ xed my-project/ios
```
在 Xcode 项目导航器中，选择您的项目，然后在 `TARGETS` 下选择您的应用目标。在 **Build Settings** 中，使用搜索栏搜索 `ENABLE_USER_SCRIPT_SANDBOXING`。如果尚未设置其值，请将其设置为 `No`。这是为了确保能够在 [Hermes
引擎](https://github.com/facebook/hermes/blob/main/README.md) 的调试和发布版本之间切换。
Step 2: 
现在切换到 **Build Phases** 标签，并在 `[CP] Embed Pods Frameworks` 阶段之前添加一个新的 `Run Script Phase`。此脚本将把 JavaScript 代码和资源打包到 iOS 应用程序中。
```sh Build React Native code and image
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
# 默认情况下，项目根目录位于 ios 目录上方一级
export PROJECT_ROOT="$PROJECT_DIR"/..
if [[ "$CONFIGURATION" = *Debug* ]]; then
  export SKIP_BUNDLING=1
fi
if [[ -z "$ENTRY_FILE" ]]; then
  # 根据捆绑器的入口解析设置入口 JS 文件。
  export ENTRY_FILE="$("$NODE_BINARY" -e "require('expo/scripts/resolveAppEntry')" "$PROJECT_ROOT" ios absolute | tail -n 1)"
fi
if [[ -z "$CLI_PATH" ]]; then
  # 使用 Expo CLI
  export CLI_PATH="$("$NODE_BINARY" --print "require.resolve('@expo/cli', { paths: [require.resolve('expo/package.json')] })")"
fi
if [[ -z "$BUNDLE_COMMAND" ]]; then
  # 默认的 Expo CLI 打包命令
  export BUNDLE_COMMAND="export:embed"
fi
# 如果存在，源 .xcode.env.updates 以允许
# 在需要时取消 SKIP_BUNDLING 的设置
if [[ -f "$PODS_ROOT/../.xcode.env.updates" ]]; then
  source "$PODS_ROOT/../.xcode.env.updates"
fi
# 源本地更改以允许覆盖
# 在需要时
if [[ -f "$PODS_ROOT/../.xcode.env.local" ]]; then
  source "$PODS_ROOT/../.xcode.env.local"
fi
`"$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'"`
```
下次当您为发布构建应用程序时，React Native 代码将使用 Expo CLI 打包并嵌入到应用中。
Step 3: 
编辑您的 **Info.plist** 文件，并确保添加 `UIViewControllerBasedStatusBarAppearance` 键，其值为 `NO`，这对于确保状态栏由 React Native 正确管理是必需的。
<DiffBlock source="/static/diffs/brownfield/ios/info-plist.diff" />
### 与您的代码集成
现在，您需要添加一些原生代码以启动 React Native 运行时，并告诉它渲染您的 React 组件。
#### 创建 ReactViewController
创建一个新文件 **ReactViewController.swift**，这将是加载 React Native 视图作为其 `view` 的 `ViewController`。
```swift ReactViewController.swift
import UIKit
import React
import React_RCTAppDelegate
import ReactAppDependencyProvider
class ReactNativeViewController: UIViewController {
  var reactNativeFactory: RCTReactNativeFactory?
  var reactNativeFactoryDelegate: RCTReactNativeFactoryDelegate?
  override func viewDidLoad() {
    super.viewDidLoad()
    reactNativeFactoryDelegate = ReactNativeDelegate()
    reactNativeFactoryDelegate!.dependencyProvider = RCTAppDependencyProvider()
    reactNativeFactory = RCTReactNativeFactory(delegate: reactNativeFactoryDelegate!)
    view = reactNativeFactory!.rootViewFactory.view(withModuleName: "HelloWorld")
  }
}
class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
    override func sourceURL(for bridge: RCTBridge) -> URL? {
      self.bundleURL()
    }
    override func bundleURL() -> URL? {
      #if DEBUG
      RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: ".expo/.virtual-metro-entry")
      #else
      Bundle.main.url(forResource: "main", withExtension: "jsbundle")
      #endif
    }
}
```
#### 在 rootViewController 中展示 React Native 视图
最后，您可以展示您的 React Native 视图。为此，您需要一个新的视图控制器，可以在其中加载 JS 内容。您已经有了初始的 `ViewController`，可以让它呈现 `ReactViewController`。根据您的应用，有多种方法可以做到这点。在这个例子中，我们假设您有一个按钮可以以模态方式打开 React Native。
```swift ViewController.swift
import UIKit
class ViewController: UIViewController {
  var reactViewController: ReactViewController?
  override func viewDidLoad() {
    super.viewDidLoad()
    // 在加载视图后进行任何其他设置。
    self.view.backgroundColor = .systemBackground
    let button = UIButton()
    button.setTitle("Open React Native", for: .normal)
    button.setTitleColor(.systemBlue, for: .normal)
    button.setTitleColor(.blue, for: .highlighted)
    button.addAction(UIAction { [weak self] _ in
      guard let self else { return }
      if reactViewController == nil {
       reactViewController = ReactViewController()
      }
      present(reactViewController!, animated: true)
    }, for: .touchUpInside)
    self.view.addSubview(button)
    button.translatesAutoresizingMaskIntoConstraints = false
    NSLayoutConstraint.activate([
      button.leadingAnchor.constraint(equalTo: self.view.leadingAnchor),
      button.trailingAnchor.constraint(equalTo: self.view.trailingAnchor),
      button.centerXAnchor.constraint(equalTo: self.view.centerXAnchor),
      button.centerYAnchor.constraint(equalTo: self.view.centerYAnchor),
    ])
  }
}
```
## 测试您的集成
您已经完成了将 React Native 与您的应用集成的所有基本步骤。现在在 React Native 目录中运行以下命令以启动 [Metro bundler](https://metrobundler.dev/)：
```sh
$ yarn start
```
Metro 将您的 TypeScript 应用程序代码构建为一个包，通过其 HTTP 服务器提供，并从您的开发环境的 `localhost` 共享包到模拟器或设备，从而实现 [热重载](https://reactnative.dev/blog/2016/03/24/introducing-hot-reloading)。现在您可以像往常一样构建和运行您的应用程序。一旦您到达应用中的 React 驱动活动，它应该从开发服务器加载 JavaScript 代码。


# Expo Router

## Expo Router 介绍

Expo Router 是一个用于使用 Expo 构建的通用 React Native 应用程序的开源路由库。

Expo Router 是一个基于文件的 React Native 和 Web 应用程序路由器。它使您能够管理应用程序中屏幕之间的导航，允许用户在应用程序的 UI 不同部分之间无缝移动，使用相同的组件在多个平台上（Android、iOS 和 Web）运行。
它将网络中的最佳文件系统路由概念带入通用应用程序 &mdash; 使您的路由可以跨越每个平台工作。当将文件添加到 **app** 目录时，该文件会自动成为导航中的一个路由。
您还可以查看以下播放列表以开始使用 Expo Router：
## 功能
- **原生**: 基于我们强大的 [React Navigation 套件](https://reactnavigation.org/) 构建，Expo Router 导航在默认情况下是真正的原生和平台优化。
- **可共享**: 您应用程序中的每个屏幕自动可深链接。使您应用程序中的任何路由都可以通过链接共享。
- **离线优先**: 应用程序被缓存并优先运行离线，在发布新版本时自动更新。处理所有传入的原生 URL，无需网络连接或服务器。
- **优化**: 路由在生产中通过懒加载自动优化，在开发中则延迟打包。
- **迭代**: 在 Android、iOS 和 Web 之间实现通用快速刷新，以及在打包器中实现工件记忆，以保持快速规模。
- **通用**: Android、iOS 和 Web 共享统一的导航结构，能够在路由级别下放到特定平台的 API。
- **可发现**: Expo Router 使 Web 上的构建时静态渲染和对原生的统一链接成为可能。这意味着您的应用内容可以被搜索引擎索引。
### 使用不同的导航库
您可以在您的 Expo 项目中使用任何其他导航库，例如 [React Navigation](https://reactnavigation.org/docs/getting-started#installation)。然而，如果您正在构建一个新应用程序，**我们建议您使用 Expo Router 以获得上述所有功能**。使用其他导航库，您可能需要为这些功能中的某些功能实施自己的策略，例如可共享链接或在同一项目中处理 Web 和原生导航。
如果您想使用 [Wix 的 React Native Navigation](https://github.com/wix/react-native-navigation)，它在 Expo Go 中不可用，并且尚未与 `expo-dev-client` 兼容。我们建议使用 [React Navigation 的 `createNativeStackNavigator`](https://reactnavigation.org/docs/native-stack-navigator) 来使用 Android 和 iOS 原生导航 API。
## 常见问题
Note: Expo Router 与 Expo 与 React Native CLI 的对比
---
历史上，React Native 并没有对应用程序的构建方式提供规范，这类似于在没有现代 Web 框架的情况下使用 React。Expo Router 是一个具有主张的 React Native 框架，类似于 Remix 和 Next.js 是仅限 Web 的 React 的主张框架。
Expo Router 的设计旨在为每个人带来最佳的架构模式，确保 React Native 被充分利用。例如，Expo Router 的 [Async Routes](/router/reference/async-routes) 功能使每个人都能实现懒加载打包。之前，懒加载打包仅在 Meta 用于构建 Facebook 应用。
---
Note: 我可以在现有的 React Native 应用中使用 Expo Router 吗？
---
是的，Expo Router 是用于通用 React Native 应用的框架。由于路由器与打包器之间的深层连接，Expo Router 仅在使用 Metro 的 Expo CLI 项目中可用。幸运的是，您也可以 [在任何 React Native 项目中使用 Expo CLI](/bare/using-expo-cli/)！
---
Note: 基于文件的路由有什么好处？
---
- 文件系统是一个众所周知且易于理解的概念。更简单的认知模型使得教育新团队成员和扩展应用程序变得更容易。
- 最快的方式使新用户入门是让他们打开一个通用链接，该链接根据他们是否安装了该应用或网站打开到正确的屏幕。这个技术如此先进，以至于通常只有大型公司才能承担创建和维护平台之间的相似性。但有了 Expo 的基于文件的路由，您可以开箱即用这一功能！
- 代码重构变得更容易，因为您可以移动文件而无需更新任何导入或路由组件。
- Expo Router 能够自动静态类型化路由。这确保您只能链接到有效的路由，而不能链接到不存在的路由。类型化路由还改善了重构，因为如果链接被破坏，您将得到类型错误。
- Async Routes（打包分割）提高了开发速度，尤其是在较大的项目中。由于错误被隔离到单一路由，这也使得升级变得更容易，意味着您可以逐页逐步更新或重构应用，而不是一次性全部更新（传统的 React Native）。
- 深链接始终有效，适用于每个页面。这使得能够共享应用中任何内容的链接，对于推广您的应用、收集错误报告、E2E 测试、自动截图等非常有用。
- Expo Head 使用自动链接启用深层原生集成。像快速笔记、接力、Siri 上下文和通用链接这样功能只需配置设置，无需代码更改。这实现了与用户拥有的整套智能设备生态系统的完美垂直整合，从而导致只有通用应用（web ⇄ native）才能提供的用户体验。
- Expo Router 具备在 Web 上自动静态渲染每一页的能力，使得真实 SEO 和您应用内容的完全可发现成为可能。这仅因为基于文件的约定才得以实现。
- **Expo CLI** 在遵循已知约定时能够推测出有关您应用的很多信息。例如，我们可以实现每条路由的自动打包分割，或自动为您的网站生成一个网站地图。当您的应用只有一个入口点时，这是不可能的。
- 像通知和主屏幕小部件等重新参与功能更容易集成，因为您可以简单地拦截启动和深链接，带查询参数，随处在应用中实现。
- 就像在 Web 上，分析和错误报告可以很容易配置为自动包含路由名称，这对调试和理解用户行为非常有用。
---
Note: 我为什么应该使用 Expo Router 而不是 React Navigation？
---
Expo Router 和 React Navigation 都是 Expo 团队的库。我们在 React Navigation 的基础上构建了 Expo Router，以便利用基于文件的路由的好处。Expo Router 是 React Navigation 的超集，这意味着您可以与 Expo Router 一起使用任何 React Navigation 组件和 API。
如果基于文件的路由不适合您的项目，您可以使用 React Navigation 手动设置路由、类型和链接。
---
Note: 我如何对我的 Expo Router 网站进行服务器渲染？
---
Expo Router 支持基本的静态渲染（SSG）。服务器端渲染当前需要定制基础设施来设置。
---
## 下一步


## 安装 Expo Router

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

请按照以下步骤创建一个使用 Expo Router 库的新项目或将其添加到现有项目中。
## 快速开始
Step 1: 
我们建议使用 `create-expo-app` 创建一个新的 Expo 应用程序，从而创建一个已经安装和配置了 Expo Router 库的项目：
```sh
$ npx create-expo-app@latest
```
Step 2: 
现在，您可以通过运行以下命令启动您的项目：
```sh
$ npx expo start
```
- 要在移动设备上查看您的应用程序，我们建议从 [Expo Go](/get-started/set-up-your-environment/#how-would-you-like-to-develop) 开始。随着您的应用程序复杂度的增加以及对更多控制的需求，您可以创建一个 [开发构建](/develop/development-builds/introduction/)。
- 在终端 UI 中按 <kbd>w</kbd> 以在网页浏览器中打开项目。按 <kbd>a</kbd> 以进行 Android（需要 Android Studio），或按 <kbd>i</kbd> 以进行 iOS（需要 macOS 和 Xcode）。
## 手动安装
如果您有一个之前使用 Expo 创建的项目，但没有安装 Expo Router 库，请按照以下步骤操作。
### 先决条件
确保您的计算机 [已设置为运行 Expo 应用程序](/get-started/create-a-project/)。
Step 1: 
### 安装依赖项
您需要安装以下依赖项：
```sh
$ npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar
```
上述命令将安装与您项目当前使用的 Expo SDK 版本兼容的这些库的版本。
Step 2: 
### 设置入口点
对于属性 `main`，在 **package.json** 中使用 `expo-router/entry` 作为其值。初始客户端文件是 [**app/\_layout.tsx**](/router/basics/layout/#root-layout)。
```json package.json
{
  "main": "expo-router/entry"
}
```
Note: 自定义入口点以初始化和加载副作用
---
您可以在 Expo Router 项目中创建一个自定义入口点，以在应用程序加载根布局（**app/\_layout.tsx**）之前初始化和加载副作用。以下是自定义入口点的一些常见用例：
- 初始化全局服务，如分析、错误报告等。
- 设置填充
- 使用来自 `react-native` 的 `LogBox` 忽略特定日志
1. 在项目的根目录中创建一个新文件，例如 **index.js**。创建此文件后，项目结构应如下所示：
   ```
app/
│   └── _layout.tsx
index.js
package.json
其他项目文件
```
2. 导入或添加您的自定义配置到该文件。然后，导入 `expo-router/entry` 以注册应用入口。请记得始终最后导入它，以确保在应用程序呈现之前，所有配置都已正确设置。
   ```js index.js
   // 首先导入副作用和服务
   // 初始化服务
   // 通过 Expo Router 注册应用入口
   import 'expo-router/entry';
   ```
3. 更新 **package.json** 中的 `main` 属性，以指向新的入口文件。
   ```json package.json
   {
     "main": "index.js"
   }
   ```
---
Step 3: 
### 修改项目配置
在您的 [应用配置](/workflow/configuration/) 中添加深度链接 `scheme`：
```json app.json
{
  "scheme": "your-app-scheme"
}
```
如果您正在为网页开发应用程序，请安装以下依赖项：
```sh
$ npx expo install react-native-web react-dom
```
然后，通过将以下内容添加到您的 [应用配置](/workflow/configuration/) 中来启用 [Metro web](/guides/customizing-metro/#adding-web-support-to-metro) 支持：
```json app.json
{
  "web": {
    "bundler": "metro"
  }
}
```
Step 4: 
### 修改 babel.config.js
确保在 **babel.config.js** 文件中使用 `babel-preset-expo` 作为 `preset`，或删除该文件：
```js babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
  };
};
```
Step 5: 
### 清除打包器缓存
更新 Babel 配置文件后，运行以下命令以清除打包器缓存：
```sh
$ npx expo start --clear
```
Step 6: 
### 更新解析
如果您是从旧版本的 Expo Router 升级，请确保移除 **package.json** 中所有已过时的 Yarn 解析或 npm 覆盖。具体来说，从 **package.json** 中删除 `metro`、`metro-resolver`、`react-refresh` 解析。


# Router 101

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

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

在深入了解如何使用 Expo Router 构建您的应用导航树之前，让我们首先理解构成 Expo Router 中基于文件路由基础的核心概念，以及 Expo Router 项目如何在结构上与其他 React Native 项目有所不同。
## Expo Router 的规则
### 1. 所有屏幕/页面都是应用目录中的文件
您应用中的所有导航路由都是由 **app** 目录中的文件和子目录定义的。**app** 目录中的每个文件都有一个默认导出，定义了您的应用中的一个独特页面（特殊的 **\_layout** 文件除外）。
因此，**app** 目录中的目录将相关屏幕组合在一起，定义为栈、选项卡或其他排列方式。
### 2. 所有页面都有 URL
所有页面都有与 **app** 目录中文件位置相匹配的 URL 路径，可以用于在网页地址栏中导航到该页面，或作为原生移动应用中的特定深层链接。这就是 Expo Router 支持“通用深层链接”的含义。您的应用中的所有页面都可以通过 URL 进行导航，无论平台如何。
### 3. 首先的 index.tsx 是初始路由
使用 Expo Router，您不需要在代码中定义初始路由或第一个屏幕。相反，当您打开应用时，Expo Router 将查找与 `/` URL 匹配的第一个 **index.tsx** 文件。这可以是 **app/index.tsx** 文件，但不一定是。如果用户应该默认从导航树的深层部分开始，您可以使用 [路由组](/router/basics/notation/#parentheses)（目录名称用括号括起来），这将不算作 URL 的一部分。如果您希望您的第一个屏幕是一个选项卡组，您可以将所有选项卡页面放入 **app/(tabs)** 目录，并将默认选项卡定义为 **index.tsx**。通过这种安排，`/` URL 将直接将用户带到 **app/(tabs)/index.tsx** 文件。
### 4. 根 \_layout.tsx 替代 App.jsx/tsx
每个项目应该在 **app** 目录中有一个 **\_layout.tsx** 文件。此文件在应用中的任何其他路由之前呈现，您可以将可能以前放在 **App.jsx** 文件中的初始化代码放在这里，例如加载字体或与启动屏幕交互。
### 5. 非导航组件放在应用目录外
在 Expo Router 中，**app** 目录专门用于定义您应用的路由。您应用的其他部分，如组件、钩子、实用工具等，应放在其他顶层目录中。如果您将非路由放入 **app** 目录，Expo Router 将尝试将其视为路由。
另外，您可以创建一个 [顶层 **src** 目录](/router/reference/src-directory/)，并将您的路由放在 **src/app** 目录中，非路由组件放在 **src/components**、**src/utils** 等文件夹中。这是唯一的其他目录结构，Expo Router 将识别。
### 6. 本质上仍然是 React Navigation
虽然这听起来与 React Navigation 有些不同，但 Expo Router 实际上是建立在 React Navigation 之上的。您可以将 Expo Router 视为一种 Expo CLI 优化，它将您的文件结构转换为您之前在自己的代码中定义的 React Navigation 组件。
这也意味着，您通常可以参考 React Navigation 文档，了解如何样式或配置导航，因为默认的堆栈和选项卡导航器使用完全相同的选项。
## Expo Router 规则的应用
让我们将这些 Expo Router 的基本规则应用于快速识别以下项目文件结构的关键元素：
```
app/
│   ├── index.tsx
│   ├── home.tsx
│   ├── _layout.tsx
│   └── profile/
│       └── friends.tsx
components/
    ├── TextField.tsx
    └── Toolbar.tsx
```
- **app/index.tsx** 是初始路由，打开应用或导航到您的网页应用根 URL 时将首先出现。
- **app/home.tsx** 是具有 `/home` 路由的页面，因此您可以在浏览器中通过 `yourapp.com/home` 的 URL 导航到它，或在原生应用中通过 `myapp://home` 导航。
- **app/\_layout.tsx** 是根布局。您可能以前放在 **App.jsx** 中的任何初始化代码都应该放在这里。
- **app/profile/friends.tsx** 是具有 `/profile/friends` 路由的页面。
- **TextField.tsx** 和 **Toolbar.tsx** 不在 **app** 目录中，因此它们将不会被视为页面。它们将没有 URL，且不能作为导航动作的目标。然而，它们可以作为 **app** 目录中页面的组件使用。


## Expo Router 符号

了解如何使用特殊的文件名和符号在项目的文件结构中富有表现力地定义应用程序的导航树。

当你查看一个典型的 Expo Router 项目中的 **app** 目录时，你会看到远比简单的文件和目录名称要多的东西。括号和方括号意味着什么？让我们学习基于文件的路由符号的意义，以及它如何允许你定义复杂的导航模式。
## 路由符号的类型
### 简单名称/无符号
```
app/
    ├── home.tsx
    └── feed/
        └── favorites.tsx
```
没有任何符号的常规文件和目录名称表示 _静态路由_。它们的 URL 完全与文件树中的显示方式相匹配。因此，位于 **feed** 目录中的名为 **favorites.tsx** 的文件将具有 `/feed/favorites` 的 URL。
### 方括号
```
app/
    ├── [userName].tsx
    └── products/
        └── [productId]/
            └── index.tsx
```
如果你在文件或目录名称中看到方括号，您正在查看 _动态路由_。路由的名称包含一个参数，可以在渲染页面时使用。该参数可以在目录名称或文件名称中。例如，名为 **[userName].tsx** 的文件将匹配 `/evanbacon`，`/expo` 或其他用户名。然后，你可以使用 `useLocalSearchParams` 钩子在页面中访问该参数，以加载该特定用户的数据。
### 括号
```
app/
    └── (tabs)/
        ├── index.tsx
        └── settings.tsx
```
其名称被括号包围的目录表示 _路由组_。这些目录用于将路由组合在一起，而不影响 URL。例如，名为 **app/(tabs)/settings.tsx** 的文件将具有 `/settings` 的 URL，即使它并不直接位于 **app** 目录中。
路由组对于简单的组织目的可能很有用，但通常在定义路由之间的复杂关系时变得更加重要。
### index.tsx 文件
```
app/
    ├── (tabs)/
    │   └── index.tsx
    └── profile/
        └── index.tsx
```
就像在网络上一样，**index.tsx** 文件表示目录的默认路由。例如，名为 **profile/index.tsx** 的文件将匹配 `/profile`。名为 **(tabs)/index.tsx** 的文件将匹配 `/`，有效地成为你整个应用的默认路由。
### \_layout.tsx 文件
```
app/
    ├── _layout.tsx
    ├── (tabs)/
    │   └── _layout.tsx
    └── feed/
        └── _layout.tsx
```
**\_layout.tsx** 文件是特殊文件，它们本身不是页面，但定义了目录中一组路由之间的关系。如果一组路由安排为堆栈或选项卡，布局路由就是你将使用堆栈导航器或选项卡导航器组件定义该关系的地方。
布局路由在其目录内的实际页面路由之前被渲染。这意味着直接位于 **app** 目录中的 **\_layout.tsx** 会在应用程序中的其他内容之前被渲染，并且是你放置之前可能放在 **App.jsx** 文件中的初始化代码的地方。
### 加号
```
app/
    ├── +not-found.tsx
    ├── +html.tsx
    ├── +native-intent.tsx
    └── +middleware.ts
```
包含 `+` 的路由对 Expo Router 有特殊意义，并用于特定用途。一些例子：
- [`+not-found`](/router/error-handling/#unmatched-routes)，捕获任何不匹配你应用中的路由的请求。
- [`+html`](/router/reference/static-rendering/#root-html) 用于定制你在 web 上使用的 HTML 模板。
- [`+native-intent`](/router/advanced/native-intent/) 用于处理深层链接到你应用的链接，这些链接不匹配特定路由，例如第三方服务生成的链接。
- [`+middleware`](/router/reference/middleware/) 用于在路由被渲染之前运行代码，使你能够对每个请求执行身份验证或重定向等任务。
## 路由符号的应用
考虑以下项目文件结构以识别不同类型的路由：
```
app/
    ├── (tabs)/
    │   ├── _layout.tsx
    │   ├── index.tsx
    │   ├── feed.tsx
    │   └── profile.tsx
    ├── _layout.tsx
    ├── users/
    │   └── [userId].tsx
    ├── +not-found.tsx
    └── about.tsx
```
- **app/about.tsx** 是一个静态路由，匹配 `/about`。
- **app/users/[userId].tsx** 是一个动态路由，匹配 `/users/123`，`/users/456` 等等。
- **app/(tabs)** 是一个路由组。它不会影响 URL，因此 `/feed` 将匹配 **app/(tabs)/feed.tsx**。
- **app/(tabs)/index.tsx** 是 **(tabs)** 目录的默认路由，因此它将是最初聚焦的选项卡，并将匹配 `/` URL。
- **app/(tabs)/\_layout.tsx** 是一个布局文件，定义了 **app/(tabs)/** 中的三页之间的关系。如果你在此文件中使用选项卡导航器组件，那么这些屏幕将被安排为选项卡。
- **app/\_layout.tsx** 是根布局文件，并且在应用中的任何其他路由之前被渲染。
- **+not-found.tsx** 是一个特殊路由，如果用户导航到你应用中不存在的路由，则会显示该路由。


## 在 Expo Router 中的导航布局

学习如何通过使用目录和布局文件构建不同页面之间的关系。

<VideoBoxLink
  videoId="Yh6Qlg2CYwQ"
  title="Expo Router 布局文件简介"
  description="什么是布局文件，如何在屏幕之间导航，以及如何使用重定向阻止访问。"
  className="mb-6"
/>
每个 **app** 目录中的目录（包括 **app** 本身）可以在该目录内定义一个 **\_layout.tsx** 文件作为布局。该文件定义了该目录内所有页面的排列方式。在这里，您可以定义堆栈导航器、选项卡导航器、抽屉导航器或您希望用于该目录中的页面的任何其他布局。布局文件导出一个默认组件，该组件在您导航到该目录内的任何页面之前呈现。
让我们看几个常见的布局场景。
## 根布局
几乎每个应用都将在 **app** 目录中直接包含一个 **\_layout.tsx** 文件。这是根布局，代表您导航的入口点。除了描述您应用的顶级导航器外，该文件是放置初始化代码的地方，这些代码可能之前放在 **App.jsx** 文件中，例如加载字体、与启动画面交互或添加上下文提供者。
以下是根布局的示例：
```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 />;
}
```
上述示例初始显示启动画面，然后在字体加载后呈现堆栈导航器，这将导致您的应用继续至初始路由。
## 堆栈
您可以在根布局中实现堆栈导航器，如上所示，或在目录中的任何其他布局文件中。假设您有一个文件结构，在目录中有一个堆栈：
```
app/
    └── products/
        ├── _layout.tsx
        ├── index.tsx
        ├── [productId].tsx
        └── accessories/
            └── index.tsx
```
如果您希望 **app/products** 目录中的所有内容以堆栈关系排列，请在 **\_layout.tsx** 文件中返回一个 `Stack` 组件：
```tsx app/products/_layout.tsx
import { Stack } from 'expo-router';
export default function StackLayout() {
  return <Stack />;
}
```
当您导航到 `/products` 时，它将首先转到默认路由，即 **products/index.tsx**。如果您导航到 `/products/123`，那么该页面将被推送到堆栈中。默认情况下，堆栈将在头部呈现一个返回按钮，该按钮将当前页面从堆栈中弹出，使用户返回到上一页。即使页面不可见，如果它仍然被推入堆栈，它仍然在呈现中。
`Stack` 组件实现了 [React Navigation 的原生堆栈](https://reactnavigation.org/docs/native-stack-navigator/)，并且可以使用相同的屏幕选项。不过，您无需在导航器内具体定义页面。目录中的文件将自动被视为堆栈中的合格路由。不过，如果您想定义屏幕选项，可以在 `Stack` 组件内添加一个 `Stack.Screen` 组件。`name` 属性应与路由名称匹配，但您无需提供 `component` 属性；Expo Router 会自动映射：
```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** 目录中拥有额外的 **\_layout.tsx** 和一个 `Stack` 导航器。那将定义一个嵌套在第一个堆栈内的另一个堆栈。添加仅影响 URL 的目录是可以的，否则，请使用与父目录相同的导航器。
## 选项卡
类似于堆栈，您可以在布局文件中实现选项卡导航器，目录中的所有路由将被视为选项卡。考虑以下文件结构：
```
app/
    └── (tabs)/
        ├── _layout.tsx
        ├── index.tsx
        ├── feed.tsx
        └── profile.tsx
```
在 **\_layout.tsx** 文件中，返回一个 `Tabs` 组件：
```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} />,
        }}
      />
      <!-- 在这里添加更多标签 -->
    </Tabs>
  );
}
```
这将使 **index.tsx**、**feed.tsx** 和 **profile.tsx** 文件在同一底部选项卡导航器中一起出现。该 `Tabs` 组件使用 [React Navigation 的原生底部选项卡](https://reactnavigation.org/docs/bottom-tab-navigator/) 并支持相同的选项。
在 `Tabs` 中，您可能希望在导航器中定义选项卡，因为这会影响选项卡的出现顺序、标题和选项卡内的图标。index 路由将是默认选中的选项卡。
## 插槽
在某些情况下，您可能希望没有导航器的布局。这对于在当前路由周围添加页眉或页脚，或在目录内部显示模态是很有帮助的。在这种情况下，您可以使用 `Slot` 组件，它作为当前子路由的占位符。
考虑以下文件结构：
```
app/
    └── social/
        ├── _layout.tsx
        ├── index.tsx
        ├── feed.tsx
        └── profile.tsx
```
例如，您可能希望用页眉和页脚包装 **social** 目录中的任何路由，但您希望在页面之间的导航仅替换当前页面，而不是将新页面推入堆栈，这样可以后续用“后退”导航操作将其弹出。在 **\_layout.tsx** 文件中，返回一个被页眉和页脚包围的 `Slot` 组件：
```tsx app/social/_layout.tsx
import { Slot } from 'expo-router';
export default function Layout() {
  return (
    <>
      <Header />
      <Slot />
      <Footer />
    </>
  );
}
```
## 其他布局
这只是一些常见布局的示例，让您了解它是如何工作的。您可以在布局中做更多事情：
- 实现一个 [抽屉导航器](/router/advanced/drawer)
- 将默认选项卡替换为 [完全自定义的选项卡](/router/advanced/custom-tabs)
- 使用 [模态](/router/advanced/modals) 显示具有透明度的页面，使父导航器仍然在下面可见
- [适应任何与 React Navigation 兼容的导航器](/versions/latest/sdk/router/#withlayoutcontextnav-processor)，包括顶部选项卡、底部表单等


## 在 Expo Router 中页面之间导航

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

一旦您在应用程序中设置了一些页面及其布局，就该开始在它们之间导航了。Expo Router 中的导航与 React Navigation 类似，但由于所有页面默认都具有 URL，我们可以创建链接并使用这些 URL 以熟悉的 Web 模式在我们的应用程序中移动。
## 使用 `useRouter` 的原生导航基础
与 React Navigation 一样，您可以从 `onPress` 处理程序中调用函数以导航到另一个页面。在 Expo Router 中，您可以使用 `useRouter` 钩子访问导航函数：
```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 中，您可以通过其 URL 或相对于 **app** 目录的位置来引用页面。查看以下文件结构以及您如何导航到每个页面：
```
app/
    ├── index.tsx  # router.navigate("/")
    ├── about.tsx  # router.navigate("/about")
    └── profile/
        ├── index.tsx  # router.navigate("/profile")
        └── friends.tsx  # router.navigate("/profile/friends")
```
## 链接和按钮
在 Expo Router 中链接到页面的典型方式是像 Web 应用程序一样使用链接。Expo Router 有一个 `Link` 组件用于在页面之间导航，`href` 就是您在 `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` 属性的组件：
```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>
  );
}
```
## 相对路由
您并不总是需要使用路由的绝对路径。使用以 `./`（当前目录）或 `../`（上级目录）开头的路径将相对于当前路由进行导航。
相对 URL 是带有 `./` 的 URL 前缀，例如 `./article`或 `./article/`。相对 URL 相对于当前渲染的屏幕解析。
```tsx
<Link href="./article">Go to article</Link>
```
```ts
router.navigate('./article');
```
## 动态路由和 URL 参数
<VideoBoxLink
  videoId="izZv6a99Roo"
  time={350}
  title="在 Expo Router 中使用动态路由"
  description="学习如何使路由的一个部分动态。"
  className="mb-6"
/>
动态路由可以通过完整 URL 链接，或通过传递 `params` 对象。
考虑以下文件结构：
```
app/
    └── user/
        └── [id].tsx
```
每个链接都将导航到相同的页面：
```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>
  );
}
```
> **info** 一些参数保留供 Expo Router 和 React Navigation 内部使用。您可以在 [使用 URL 参数指南](/router/reference/url-parameters/#reserved-parameters) 中找到它们。
### 传递查询参数
您可以在链接 URL 本身中指定查询参数，或作为 `params` 对象中的附加参数。任何与动态路由变量名称不匹配的参数都相当于查询参数。
```tsx
<Link href="/users?limit=20">查看用户</Link>
<Link
  href={{
    pathname: '/users',
    params: { limit: 20 }
  }}>
  View users
</Link>
```
### 在目标页面中使用动态路由变量和查询参数
链接 URL 中的所有变量都可以通过 `useLocalSearchParams` 钩子访问到接收页面。该钩子返回一个包含所有 URL 参数的对象，包括作为 `params` 传递的那些。
例如，如果您有这样的链接：
```tsx
<Link href="/users?limit=20">View users</Link>
```
那么您可以在另一端这样读取参数：
```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>
  );
}
```
### 无需导航即可更新查询参数
可以无需导航到新页面而更新查询参数。这可以通过使用与当前页面相同的 URL 的 `Link` 来实现，但更新了查询参数，或者以强制方式实现。
```tsx
<Link href="/users?limit=50">View more users</Link>
<Pressable onPress={() => router.setParams({ limit: 50 })}>
  <Text>View more users</Text>
</Pressable>
```
## 重定向
您可以使用 `Redirect` 组件从页面或布局立即重定向到另一个路由。这就像 `replace` 强制性导航函数一样。重定向将导航到新路由，而不会渲染当前页面。
```tsx
import { Redirect } from 'expo-router';
export default function Page() {
  return <Redirect href="/about" />;
}
```
## 预取
`<Link />` 组件上的 `prefetch` 属性在组件渲染时启用目标屏幕的预取。这通过提前准备屏幕来加快导航速度。
```tsx
import { Link } from 'expo-router';
export default function Page() {
  return <Link href="/about" prefetch />;
}
```
当设置了 `prefetch` 时，Expo Router 将尝试在屏幕外渲染目标屏幕。具体行为取决于使用的导航器类型：
- **Expo Router 导航器**：在屏幕外渲染目标屏幕以启用预加载。
- **自定义导航器**：可能以不同方式实现预取或根本不支持它。
当屏幕在堆栈导航器中预加载时，它将有一些限制：
- 它不能使用强制性的 `router` API。
- 它不能使用 `useNavigation().setOptions()` 更新选项。
- 它不能监听来自导航器的事件（例如焦点、tabPress 等）。
在您导航到屏幕时，导航对象将被更新。因此，如果您在 useEffect 钩子中有事件监听器并依赖于导航，它将在导航到屏幕时添加任何监听器：
```tsx
const navigation = useNavigation();
useEffect(() => {
  const unsubscribe = navigation.addListener('tabPress', () => {
    // 做点什么
  });
  return () => {
    unsubscribe();
  };
}, [navigation]);
```
同样，对于调度动作或更新选项，您可以在执行操作之前检查屏幕是否聚焦：
```tsx
const navigation = useNavigation();
if (navigation.isFocused()) {
  navigation.setOptions({ title: 'Updated title' });
}
```
有关更多信息，请参考 [React Navigation 预加载文档](https://reactnavigation.org/docs/navigation-object/#preload)
## 深度链接
深度链接是指通过 URL 打开应用程序中的特定页面。Expo Router 默认支持深度链接，因此您可以使用外部 URL 链接到应用程序中的任何页面，就像您在应用程序内部使用 `Link` 一样。这对于共享指向应用程序中特定页面的链接尤其有用。
在 Web 上，深度链接和在 Web 浏览器中导航到该特定 URL 一样简单。在移动设备上，您需要在 [应用配置](/workflow/configuration/) 文件中定义一个 `scheme`，该 `scheme` 成为深度链接进入您的应用程序的前缀。
假设您的 `scheme` 是 `myapp`，以下是一些示例，说明如何从网页或其他应用程序链接到您应用程序中的页面：
```
app/
    ├── about.tsx  # myapp://about
    ├── profile/
    │   └── index.tsx  # myapp://profile
    └── users/
        └── [username].tsx  # myapp://users/evanbacon
```
使用应用链接和通用链接，您还可以使用 `https` URL 链接到您的应用程序。有关更多信息，请参见 [通用链接](/linking/overview/#universal-linking)。
## 初始路由
在打开深度链接到您应用程序中的页面时，您可能希望后退导航的表现与用户从您的主页导航到该页面时相同。要做到这一点，您可以指定一个 `initialRouteName` 配置，定义在深度链接页面之前应该加载的布局页面。
考虑以下文件结构：
```
app/
    ├── index.tsx
    └── stack/
        ├── index.tsx
        ├── second.tsx
        └── _layout.tsx
```
`stack` 是一个堆栈导航器，而 `/stack/index` 始终是堆栈中的第一个路由。
为确保即使用户深度链接到 `/stack/second`，`/stack/index` 也始终首先加载，您可以在 **app/stack/\_layout.tsx** 中设置 `initialRouteName`：
```tsx
export const unstable_settings = {
  // 确保任何路由都可以链接回 `/`
  initialRouteName: 'index',
};
```
默认情况下，仅在深度链接时考虑 `initialRouteName`，而在应用程序内部导航时不考虑。不过，您可以在 `Link` 上使用 `withAnchor` 属性，以强制在直接导航到应用程序中的另一个堆栈时加载初始路由。
因此，如果 **app/index.tsx** 中包含一个指向 `/stack/second` 的链接，请添加 `withAnchor` 属性，以确保首先加载 `/stack/index`，这将导致用户在从 `/stack/second` 按下后退按钮时返回 `/stack/index`：
```tsx
<Link href="/stack/second" withAnchor>
  Go to second
</Link>
```
> **info** 如果在测试深度链接时缺少后退按钮，通常可以通过设置 `initialRouteName` 来解决。


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

将 Expo Router 的基础知识应用于您可以在应用程序中使用的现实导航模式。

现在您已经知道了在 Expo Router 中如何命名和排列文件与目录的基础知识，让我们应用这些知识，看看您在应用程序中可能使用的一些现实导航模式。
## 标签页中的堆栈：嵌套导航器
如果您的应用程序的典型起始点是一组标签，但一个或多个标签可能与多个屏幕相关，则在标签中嵌套堆栈导航器通常是最佳选择。此模式通常会产生直观的 URL，并且在桌面 Web 应用程序上的可扩展性良好，因为主标签通常始终可见。
请考虑以下导航树：
```
app/
    └── (tabs)/
        ├── _layout.tsx
        ├── index.tsx  # 单页标签
        ├── feed/
        │   ├── _layout.tsx  # 带有堆栈的标签
        │   ├── index.tsx
        │   └── [postId].tsx
        └── settings.tsx  # 单页标签
```
在 **app/(tabs)/\_layout.tsx** 文件中，返回一个 `Tabs` 组件：
```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` 组件：
```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]` 路由推入堆栈，同时保持标签导航器可见。
您还可以使用相同的 URL 从任何其他标签导航到动态标签中的帖子。使用 `withAnchor` 配合 `initialRouteName`，确保 `feed/index` 路由始终是堆栈中的第一个屏幕：
```tsx app/(tabs)/feed/index.tsx
<Link href="/feed/123" withAnchor>
  Go to post
</Link>
```
您还可以在外部堆栈导航器中嵌套标签。这通常更有助于在标签上方显示模态。
## 一个屏幕，两个标签：共享路由
路由组可用于在两个不同的标签之间共享单个屏幕。考虑一下具有动态标签和搜索标签的导航树，它们都共享查看用户资料的页面：
```
app/
    └── (tabs)/
        ├── _layout.tsx
        ├── (feed)/
        │   └── index.tsx  # 默认路由
        ├── (search)/
        │   └── search.tsx
        └── (feed,search)/
            ├── _layout.tsx  # 两个标签共享的布局
            └── users/
                └── [username].tsx  # 共享用户资料页面
```
每个标签都被放入一个组中，因此您可以定义一个第三个目录以在两个组之间共享路由 (**app/(tabs)/(feed,search)/**)。即使有额外的层，**app/(tabs)/(feed)/index.tsx** 仍然是最近的索引，因此它将是默认路由。
```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)` 路由组都包含堆栈，因此它们也可以共享单个布局：
```tsx app/(tabs)/(feed,search)/_layout.tsx
import { Stack } from 'expo-router';
export default function SharedLayout() {
  return <Stack />;
}
```
共享组还可以只包含共享页面，每个不同的组都有自己的布局文件。
现在，两个标签都可以导航到 `/users/evanbacon` 并查看相同的用户资料页面。
当您已经专注于一个标签并导航到一个用户时，您将留在当前标签的组中。但是，当直接从应用程序外部深度链接到用户资料页面时，Expo Router 必须选择两个组中的一个，因此它将选择按字母顺序排列的第一个组。因此，深度链接到 `/users/evanbacon` 将会在动态标签中显示用户资料。
## 仅限经过身份验证的用户：受保护路由
对于需要身份验证的移动应用程序，您可能会有一组路由仅应对经过身份验证的用户进行访问。
例如，请考虑以下导航树，其中您有一个底部标签布局、一个登录页面、一个创建账户页面，以及一个仅应对经过身份验证的用户可见的模态：
当您的应用程序首次启动时，路由器将试图打开根索引， **app/(tabs)/index.tsx**。如果您将此屏幕包装在一个 `Stack.Protected` 中，并将 `guard={false}`，则该屏幕将变得不可访问，并且将打开下一个可用屏幕。在这个例子中，将打开 `sign-in` 屏幕，因为它是下一个可用路由。
```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)` 组的根。
受保护路由的另一个好处是，它们会在您直接深度链接到页面时进行检查。例如，如果未经过身份验证的用户深度链接到上面的模态屏幕，他们将被重定向到登录页面。
受保护的路由还可以用于有条件地显示底部标签。在这个例子中，`vip` 标签仅对身份验证用户显示：
```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>
  );
}
```
## 有时候最好的路由根本不是路由
将您的导航状态分离到不同的路由中是为了服务于您和您的应用程序。有时候，最佳模式根本不涉及导航到另一个路由。由于布局文件只是 React 组件，您可以使用它们来显示各种 UI，除了、旁边或代替导航器。
回想一下身份验证，如果用户在未登录的情况下根本不应该访问某些页面，受保护路由的设置效果很好。但是当未经过身份验证的用户可以以只读模式浏览应用程序时，该怎么办？在这种情况下，您可能希望在应用中显示一个登录模态，而不是将用户重定向到登录页面：
```tsx app/(logged-in)/_layout.tsx
import { Modal } from 'react-native';
import { SafeAreaView } from 'react-native-safe-area-context';
import { Stack } from 'expo-router';
export default function Layout() {
  const isAuthenticated = /* 检查有效的身份验证令牌 / 会话 */
  return (
    <SafeAreaView>
      <Stack />
      <Modal visible={!isAuthenticated}>{/* 登录 UX */}</Modal>
    </SafeAreaView>
  );
}
```


# 导航模式

## 堆栈

学习如何在 Expo Router 中使用堆栈导航器。

<VideoBoxLink
  videoId="izZv6a99Roo"
  title="使用 Expo Router 的堆栈导航器"
  description="在屏幕之间导航、在屏幕之间传递参数、创建动态路由，并配置屏幕标题和动画。"
  className="mb-6"
/>
堆栈导航器是应用程序中在路由之间导航的基础方式。在 Android 上，堆叠的路由在当前屏幕上方动画显示。在 iOS 上，堆叠的路由从右侧动画显示。Expo Router 提供了一个 `Stack` 导航组件，创建一个导航堆栈并允许您在应用中添加新路由。
本指南提供有关如何在项目中创建 `Stack` 导航器并自定义单个路由的选项和标题的信息。
## 开始使用
您可以使用基于文件的路由来创建堆栈导航器。下面是一个示例文件结构：
```
app/
    ├── _layout.tsx
    ├── index.tsx
    └── details.tsx
```
此文件结构生成一个布局，其中 `index` 路由是堆栈中的第一个路由，而 `details` 路由在导航时会堆叠在 `index` 路由之上。
您可以使用 **app/\_layout.tsx** 文件来定义您的应用的 `Stack` 导航器，并使用这两个路由：
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default function Layout() {
  return <Stack />;
}
```
## 屏幕选项和标题配置
### 静态配置路由选项
您可以在布局组件路由中使用 `<Stack.Screen name={routeName} />` 组件来静态配置路由的选项。这对于 [tabs](/router/advanced/tabs/) 或 [drawers](/router/advanced/drawer/) 也很有用，因为它们需要提前定义一个图标。
```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',
        },
      }}>
      {/* 可选地在路由外部配置静态选项。*/}
      <Stack.Screen name="home" options={{}} />
    </Stack>
  );
}
```
作为 `<Stack.Screen>` 组件的替代，您可以使用 [`navigation.setOptions()`](https://reactnavigation.org/docs/navigation-object/#setoptions) 从路由组件文件内部配置路由的选项。
```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>
  );
}
```
### 配置标题栏
您可以使用 `screenOptions` 属性为 `Stack` 导航器中的所有路由配置标题栏。这对于在所有路由之间设置共同的标题样式很有用。
```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 的交互非常有用。
```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://reactnative.dev/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,
  },
});
```
### 可用的标题选项
`Stack` 导航器支持全面的标题配置选项。以下是所有可用的与标题相关的选项：
<ReactNavigationOptions category="header" />
### 动态设置屏幕选项
要动态配置路由的选项，您可以在该路由的文件中始终使用 `<Stack.Screen>` 组件。
另外，您还可以使用 [命令式 API 的 `router.setParams()`](/versions/latest/sdk/router/#router) 函数来动态配置路由。
```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',
  },
});
```
### 标题按钮
您可以通过使用 `headerLeft` 和 `headerRight` 选项向标题添加按钮。这些选项接受一个 React 组件，该组件在标题中渲染。
```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://reactnative.dev/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,
  },
});
```
### 其他屏幕选项
有关包括动画、手势和其他配置的所有可用其他屏幕选项的完整列表：
<ReactNavigationOptions excludeCategories={['header']} />
## 自定义推送行为
默认情况下，`Stack` 导航器在推送已经在堆栈中的路由时会删除重复的屏幕。例如，如果您推送相同的屏幕两次，则第二个推送将被忽略。您可以通过为 `<Stack.Screen>` 提供自定义 `getId()` 函数来更改此推送行为。
例如，以下布局结构中的 `index` 路由显示了应用中不同用户资料的列表。让我们将 `[details]` 路由设置为 [动态路由](/router/basics/notation/#square-brackets)，以便应用用户可以浏览查看某个资料的详细信息。
```
app/
    ├── _layout.tsx
    ├── index.tsx
    └── [details].tsx  # 匹配动态路径，如 '/details1'
```
每次应用用户导航到不同的资料时，`Stack` 导航器将推送一个新屏幕，但会失败。如果您提供一个每次返回新 ID 的 `getId()` 函数，`Stack` 每次用户导航到一个资料时都会推送一个新屏幕。
您可以在布局组件路由中使用 `<Stack.Screen name="[profile]" getId={}>` 组件来修改推送行为：
```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>
  );
}
```
## 删除堆栈屏幕
您可以使用不同的操作来解除和删除堆栈中的一个或多个路由。
### `dismiss` 操作
解除最近堆栈中的最后一个屏幕。如果当前屏幕是堆栈中的唯一路由，它将解除整个堆栈。
您可以可选地传递一个正数，以解除到该指定数量的屏幕。
解除与 `back` 不同，因为它针对的是最近的堆栈，而不是当前导航器。如果您有嵌套导航器，调用 `dismiss` 将带您回到多个屏幕。
```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>
  );
}
```
### `dismissTo` 操作
> `dismissTo` 在 Expo Router `4.0.8` 中添加。它的操作类似于 Expo Router v3 中的 `navigation` 函数。
解除当前 `<Stack />` 中的屏幕，直到达到指定的 `Href`。如果历史中不存在 `Href`，则将执行 `push` 操作。
例如，考虑 `/one`、`/two`、`/three` 路由的历史，其中 `/three` 是当前路由。操作 `router.dismissTo('/one')` 将导致历史回退两次，而 `router.dismissTo('/four')` 将推送历史前进到 `/four` 路由。
```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>
  );
}
```
### `dismissAll` 操作
返回最近堆栈中的第一屏。这与 [`popToTop`](https://reactnavigation.org/docs/stack-actions/#poptotop) 堆栈操作类似。
例如，`home` 路由是第一屏，`settings` 是最后一屏。要从 `settings` 回到 `home` 路由，您必须先返回到 `details`。然而，使用 `dismissAll` 操作，您可以从 `settings` 直接跳转到 `home`，并解除中间的任何屏幕。
```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>
  );
}
```
### `canDismiss` 操作
检查是否可以解除当前屏幕。如果路由处于堆栈中，且堆栈历史中有超过一个屏幕，则返回 `true`。
```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>
  );
}
```
## 与原生堆栈导航器的关系
Expo Router 中的 `Stack` 导航器封装了来自 React Navigation 的 [Native Stack Navigator](https://reactnavigation.org/docs/native-stack-navigator)。Native Stack Navigator 中可用的选项在 Expo Router 的 `Stack` 导航器中都可用。
### 使用 @react-navigation/stack 的 JavaScript 堆栈
您还可以使用基于 JavaScript 的 `@react-navigation/stack` 库通过将此库包装在 `withLayoutContext` 中来创建自定义布局组件。
在以下示例中，`JsStack` 组件是使用 `@react-navigation/stack` 库定义的：
```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` 组件后，您可以在应用中使用它：
```tsx app/_layout.tsx
import { JsStack } from '../layouts/js-stack';
export default function Layout() {
  return (
    <JsStack
      screenOptions={
        {
        }
      }
    />
  );
}
```
有关可用选项的更多信息，请参见 [`@react-navigation/stack` 文档](https://reactnavigation.org/docs/stack-navigator)。
## iOS 26 液态玻璃标题
从 iOS 26 开始，导航标题默认采用系统的“液态玻璃”效果。无法按屏幕禁用，因此您需要使用全局配置选择退出。
### 方法 1：使用 `UIDesignRequiresCompatibility`
> **注意**：在 Expo Go 中不支持。此方法是临时解决方案。从 iOS 27 开始，此选项将被苹果公司移除，您无法选择退出液态玻璃效果。
创建一个 [开发构建](/develop/development-builds/create-a-build/#prerequisites)，并在 [应用配置](/workflow/configuration/) 中将 [`UIDesignRequiresCompatibility`](https://developer.apple.com/documentation/BundleResources/Information-Property-List/UIDesignRequiresCompatibility) 属性设置为 `true`：
```json app.json
{
  "ios": {
    "infoPlist": {
      "UIDesignRequiresCompatibility": true
    }
  }
}
```
### 方法 2：使用基于 JavaScript 的导航堆栈
从原生导航库 ([`@react-navigation/native`](https://reactnavigation.org/docs/native-stack-navigator/)) 切换到 JavaScript 基于的堆栈导航库，如 [`@react-navigation/stack`](https://reactnavigation.org/docs/stack-navigator/)，它让您完全控制标题 UI，但以牺牲使用高度优化的 iOS 导航视图/控制器的性能为代价。
有关更多信息，请参见 [使用 `@react-navigation/stack` 的 JavaScript 堆栈](#javascript-stack-with-react-navigationstack)。


## JavaScript 标签

了解如何在 Expo Router 中使用 JavaScript 标签布局（React Navigation 底部标签）。

<VideoBoxLink
  videoId="BElPB4Ai3j0"
  title="使用 JavaScript 标签导航器与 Expo Router"
  description="配置标签图标，嵌套导航器，并管理导航历史。"
  className="mb-6"
/>
标签是在应用不同部分之间导航的常见方式。Expo Router 提供一种标签布局，帮助您在应用底部创建标签栏。最快的入门方式是使用模板。请参见 [快速开始安装](/router/installation/#quick-start) 以开始。
## 多种标签布局
Expo Router 提供三种类型的标签导航器：
- **JavaScript 标签**：使用 React Navigation 的底部标签实现，如果您已经使用过 React Navigation，将提供熟悉的 API。
- **原生标签**：使用平台的原生标签栏，提供原生的外观和感觉。
- **自定义标签**：提供来自 `expo-router/ui` 的无头标签组件，以构建完全自定义的标签布局，以实现复杂的 UI 模式。
本指南涵盖 **JavaScript 标签** 布局。有关其他标签布局，请参见：
## 开始使用 JavaScript 标签
您可以使用基于文件的路由来创建标签布局。以下是示例文件结构：
```
app/
    ├── _layout.tsx
    └── (tabs)/
        ├── _layout.tsx
        ├── index.tsx
        └── settings.tsx
```
该文件结构在屏幕底部生成带有标签栏的布局。标签栏将有两个标签：**首页**和**设置**：
您可以使用 **app/\_layout.tsx** 文件来定义应用的根布局：
```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` 布局。
从文件结构来看，**(tabs)** 目录有三个文件。第一个是 **(tabs)/\_layout.tsx**。该文件是标签栏和每个标签的主要布局文件。在里面，您可以控制标签栏和每个标签按钮的外观和行为。
```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: '首页',
          tabBarIcon: ({ color }) => <FontAwesome size={28} name="home" color={color} />,
        }}
      />
      <Tabs.Screen
        name="settings"
        options={{
          title: '设置',
          tabBarIcon: ({ color }) => <FontAwesome size={28} name="cog" color={color} />,
        }}
      />
    </Tabs>
  );
}
```
最后，您有两个标签文件构成标签的内容：**app/(tabs)/index.tsx** 和 **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>标签 [首页|设置]</Text>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
```
名为 **index.tsx** 的标签文件是在应用加载时的默认标签。第二个标签文件 **settings.tsx** 显示了如何向标签栏添加更多标签。
## 屏幕选项
标签布局包装了 React Navigation 的 [Bottom Tabs Navigator](https://reactnavigation.org/docs/bottom-tab-navigator)。您可以使用 [React Navigation 文档中提供的选项](https://reactnavigation.org/docs/bottom-tab-navigator/#options) 来自定义标签栏或每个标签。
## 高级
### 隐藏标签
有时您希望路由存在但不在标签栏中显示。您可以传递 `href: null` 来禁用按钮：
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs>
      <Tabs.Screen
        name="index"
        options={{
          href: null,
        }}
      />
    </Tabs>
  );
}
```
### 动态路由
您可以在标签栏中使用动态路由。例如，您有一个 `[user]` 标签显示用户的个人资料。您可以使用 `href` 选项链接到特定用户的个人资料。
```tsx app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs>
      <Tabs.Screen
        // 动态路由的名称。
        name="[user]"
        options={{
          // 确保该标签始终链接到相同的 href。
          href: '/evanbacon',
          // 或者您可以使用 href 对象。
          href: {
            pathname: '/[user]',
            params: {
              user: 'evanbacon',
            },
          },
        }}
      />
    </Tabs>
  );
}
```
> **注意**：在标签布局中添加动态路由时，确保定义的动态路由是唯一的。您不能拥有两个相同动态路由的屏幕。例如，您不能有两个 `[user]` 标签。如果您需要多个动态路由，请创建自定义导航器。


## 原生标签

学习如何在 Expo Router 中使用原生标签布局。

<VideoBoxLink
  videoId="QqNZXdGFl44"
  title="使用 Expo Router 的液态玻璃标签"
  description="学习如何在 iOS 上使用原生标签创建液态玻璃标签，使用 Expo Router。"
  className="mb-6"
/>
> **important** 原生标签是 SDK 54 及更高版本中的实验性特性，其 API 可能会改变。
标签是一种常见的方式，用于在应用的不同部分之间导航。在 Expo Router 中，您可以根据需要使用不同的标签布局。本指南涵盖原生标签。与 [其他标签布局](/router/advanced/tabs/#multiple-tab-layouts) 不同，原生标签使用原生系统标签栏。
有关其他标签布局，请参见：
## 开始使用
您可以使用基于文件的路由创建标签布局。以下是一个示例文件结构：
```
app/
    ├── _layout.tsx
    ├── index.tsx
    └── settings.tsx
```
上述文件结构在屏幕底部生成一个带标签栏的布局。标签栏将有两个标签：**首页** 和 **设置**。
您可以使用 **app/\_layout.tsx** 文件定义应用的根布局，使用标签。这是标签栏和每个标签的主要布局文件。在其中，您可以控制标签栏和每个标签项的外观和行为。
```tsx app/_layout.tsx
import { NativeTabs, Icon, Label } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index">
        <Label>首页</Label>
        <Icon sf="house.fill" drawable="custom_android_drawable" />
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="settings">
        <Icon sf="gear" drawable="custom_settings_drawable" />
        <Label>设置</Label>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
最后，您有两个标签文件，构成标签的内容：**app/index.tsx** 和 **app/settings.tsx**。
```tsx app/index.tsx and app/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** 显示如何将更多标签添加到标签栏。
> **info** 与栈导航器相比，标签不会自动添加到标签栏。您需要在布局文件中使用 `NativeTabs.Trigger` 显式添加它们。
## 自定义标签栏项
当您想要自定义标签栏项时，我们建议使用为此目的设计的组件 API。目前，您可以自定义：
- **图标**：在标签栏项中显示的图标。
- **标签**：在标签栏项中显示的标签。
- **徽章**：在标签栏项中显示的徽章。
### 图标
您可以使用 `Icon` 组件自定义在标签栏项中显示的图标。`Icon` 组件接受用于 Android drawable 的 `drawable` 属性，用于 Apple 的 SF Symbols 图标的 `sf` 属性，或用于自定义图像的 `src` 属性。
另外，您可以将 `{default: ..., selected: ...}` 传递给 `sf` 或 `src` 属性，以指定默认和选定状态的不同图标。
> 要在 Android 上使用 `drawable` 属性，您可以使用 [内置 drawable](https://developer.android.com/reference/android/R.drawable) 或添加 [自定义 drawable](https://developer.android.com/studio/write/resource-manager)。
```tsx app/_layout.tsx
import { NativeTabs, Icon } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index">
        <Icon sf={{ default: 'house', selected: 'house.fill' }} drawable="custom_home_drawable" />
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="settings">
        <Icon src={require('../../../assets/setting_icon.png')} />
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
iOS 上的液态玻璃会自动根据背景色的亮度变化颜色。没有此类回调，因此您需要使用 `PlatformColor` 来设置图标的颜色。
```tsx app/_layout.tsx
import { DynamicColorIOS } from 'react-native';
import { NativeTabs, Icon } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs
      labelStyle={{
        // 文本颜色
        color: DynamicColorIOS({
          dark: 'white',
          light: 'black',
        }),
      }}
      // 选定图标颜色
      tintColor={DynamicColorIOS({
        dark: 'white',
        light: 'black',
      })}>
      <NativeTabs.Trigger name="index">
        <Icon sf={{ default: 'house', selected: 'house.fill' }} drawable="custom_home_drawable" />
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="settings">
        <Icon
          src={{
            default: require('../../../assets/setting_icon.png'),
            selected: require('../../../assets/selected_setting_icon.png'),
          }}
        />
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
### 标签
您可以使用 `Label` 组件自定义在标签栏项中显示的标签。`Label` 组件接受作为子项传递的字符串标签。如果未提供标签，标签栏项将使用路由名称作为标签。
如果您不想显示标签，可以使用 `hidden` 属性来隐藏标签。
```tsx app/_layout.tsx
import { NativeTabs, Label } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index">
        <Label>Home</Label>
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="settings">
        <Label hidden />
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
### 徽章
您可以使用 `Badge` 组件自定义标签栏项的徽章。徽章是标签上的附加标记，用于显示通知或未读消息计数。
```tsx app/_layout.tsx
import { NativeTabs, Badge } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="messages">
        <Badge>9+</Badge>
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="settings">
        <Badge />
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
## 自定义标签栏
由于原生标签布局的外观因平台而异，定制选项也不同。有关所有自定义选项，请参见 [`NativeTabs` 的 API 参考](/versions/latest/sdk/router-native-tabs/)。
## 高级
### 有条件地隐藏标签
如果您想根据条件隐藏标签，可以删除触发器或将 `hidden` 属性传递给 `NativeTabs.Trigger` 组件。
```tsx app/_layout.tsx
import { NativeTabs } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  const shouldHideMessagesTab = true; // 用您的条件替换
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="messages" hidden={shouldHideMessagesTab} />
    </NativeTabs>
  );
}
```
> **info** **注意**：将标签标记为 `hidden` 意味着无法以任何方式导航到它。
### 消失行为
> **info** 目前这是仅适用于 iOS 的特性，但我们计划在将来将其添加到 Android。
默认情况下，点击一个已经活跃的标签会关闭该标签的所有屏幕并返回到根屏幕。您可以通过在 `NativeTabs.Trigger` 组件上设置 `disablePopToTop` 属性来禁用此功能。
```tsx app/_layout.tsx
import { NativeTabs, Label } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index" disablePopToTop>
        <Label>Home</Label>
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="settings">
        <Label>Settings</Label>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
### 滚动到顶部
> **info** 目前这是仅适用于 iOS 的特性，但我们计划在将来将其添加到 Android。
默认情况下，点击一个已经活跃的标签并显示其根屏幕会将内容向上滚动回到顶部。您可以通过在 `NativeTabs.Trigger` 组件上设置 `disableScrollToTop` 属性来禁用此功能。
```tsx app/_layout.tsx
import { NativeTabs, Label } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index" disableScrollToTop>
        <Label>Home</Label>
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="settings">
        <Label>Settings</Label>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
### iOS 26 特性
> **info** 要使用此部分中描述的特性，请使用 Xcode 26 或更高版本编译您的应用。
#### 单独的搜索标签
要添加单独的搜索标签，将 `role` 的值设置为 `search` 的原生标签分配给要单独显示的标签。
```tsx app/_layout.tsx
import { NativeTabs, Label } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index">
        <Label>Home</Label>
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="search" role="search">
        <Label>Search</Label>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
#### 标签栏搜索输入
要在标签栏中添加搜索字段，将屏幕包装在栈导航器中并配置 `headerSearchBarOptions`。
```
app/
    ├── _layout.tsx
    ├── index.tsx
    └── search/
        ├── _layout.tsx
        └── index.tsx
```
```tsx app/_layout.tsx
import { NativeTabs, Label } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index">
        <Label>Home</Label>
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="search" role="search">
        <Label>Search</Label>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
```tsx app/search/_layout.tsx
import { Stack } from 'expo-router';
export default function SearchLayout() {
  return (
    <Stack>
      <Stack.Screen
        name="index"
        options={{
          title: 'Search',
          headerSearchBarOptions: {
            placement: 'automatic',
            placeholder: 'Search',
            onChangeText: () => {},
          },
        }}
      />
    </Stack>
  );
}
```
```tsx app/search/index.tsx
import { ScrollView } from 'react-native';
export default function SearchIndex() {
  return <ScrollView>{/* 屏幕内容 */}</ScrollView>;
}
```
#### 标签栏最小化行为
要实现标签栏的最小化行为，您可以使用 [`minimizeBehavior`](/versions/latest/sdk/router-native-tabs/#minimizebehavior) 属性在 `NativeTabs` 上。在下面的示例中，当向下滚动时，标签栏被最小化。
```tsx app/_layout.tsx
import { NativeTabs, Label } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs minimizeBehavior="onScrollDown">
      <NativeTabs.Trigger name="index">
        <Label>Home</Label>
      </NativeTabs.Trigger>
      <NativeTabs.Trigger name="tab-1">
        <Label>Tab 1</Label>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
### 与 `@expo/vector-icons` 的集成
> **info** **推荐**：使用 [iOS 上的 SF Symbols](#icon)。与矢量图标相比，它们提供了更原生的平台感觉。
要使用 `@expo/vector-icons` 中的图标，您可以使用 `VectorIcon` 组件。
```tsx app/_layout.tsx|collapseHeight=480
import MaterialIcons from '@expo/vector-icons/MaterialIcons';
import { NativeTabs, Icon, VectorIcon } from 'expo-router/unstable-native-tabs';
import { Platform } from 'react-native';
export default function TabLayout() {
  return (
    <NativeTabs minimizeBehavior="onScrollDown">
      <NativeTabs.Trigger name="index">
        <Label>Home</Label>
        {Platform.select({
          ios: <Icon sf="house.fill" />,
          android: <Icon src={<VectorIcon family={MaterialIcons} name="home" />} />,
        })}
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```
## 从 JavaScript 标签迁移
原生标签不是为 [JavaScript 标签](/router/advanced/tabs/) 设计的直接替代品。原生标签受限于原生平台行为，而 JavaScript 标签可以更自由地定制。如果您对原生平台行为不感兴趣，您可以继续使用 JavaScript 标签。
### 使用 `Trigger` 替代 `Screen`
`NativeTabs` 引入了 `Trigger` 的概念，用于向布局添加路由。与自动添加样式的 `Screen` 不同，`Trigger` 系统为隐藏和移除标签提供了更好的控制。
### 使用 React 组件而不是属性
`NativeTabs` 采用了以 React 为先的 API，选择使用组件定义 UI，而不是属性对象。
```diff
- options={{
-   tabBarIcon: ({ focused, color, size }) => (
-     <Icon name="home" color={color} size={size} />
-   ),
- }}
+ <Icon sf="house" drawable="home_drawable" />
```
### 在标签内使用栈
JavaScript `` 有一个伪栈头部，这在原生标签中不存在。相反，您应该在原生标签内部嵌套一个原生 `<Stack />` 布局，以支持头部和推送屏幕。
## 已知限制
### Android 上的标签限制为 5
在 Android 上，标签栏中最多只能有 5 个标签。这个限制来自该平台的 Material Tabs 组件。
### 不能测量标签栏的高度
标签会移动，有时在 iPad 上渲染时位于屏幕顶部，有时在 Apple Vision Pro 上运行时位于屏幕一侧，等等。我们正在努力提供更详细的布局信息的布局函数。
### 不支持嵌套原生标签
原生标签不能嵌套在其他原生标签中。您仍然可以在原生标签内部嵌套 [JavaScript 标签](/router/advanced/tabs/)。
### 对 FlatList 的支持有限
[FlatList](https://reactnative.dev/docs/flatlist) 与原生标签的集成存在限制。像滚动到顶部和滚动时最小化这样的功能不受支持。此外，检测滚动边缘可能失败，导致标签栏透明。为了解决这个问题，使用 [`disableTransparentOnScrollEdge`](/versions/latest/sdk/router-native-tabs/#disabletransparentonscrolledge) 属性。
```tsx app/_layout.tsx
import { NativeTabs, Label } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
  return (
    <NativeTabs disableTransparentOnScrollEdge>
      <NativeTabs.Trigger name="index">
        <Label>Home</Label>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}
```


## 抽屉

学习如何在 Expo Router 中使用抽屉布局。

导航抽屉是移动应用中的一种常见模式，它允许用户从屏幕的一侧滑出菜单以显示导航选项。这个菜单通常也可以通过应用程序的头部按钮进行切换。
For SDK 54 及更高版本: 
要使用 [抽屉导航器](https://reactnavigation.org/docs/drawer-based-navigation)，如果还没有安装某些额外的依赖项，则需要安装它们。在 Android 和 iOS 上，抽屉导航器需要 `react-native-reanimated` 和 `react-native-worklets` 来驱动其动画。在网页上，则由 CSS 动画处理。
## 安装
```sh
$ npx expo install @react-navigation/drawer react-native-reanimated react-native-worklets
```
## 用法
现在您可以使用 `Drawer` 布局来创建抽屉导航器
```tsx app/_layout.tsx
import { Drawer } from 'expo-router/drawer';
export default function Layout() {
  return <Drawer />;
}
```
要编辑抽屉导航菜单标签、标题和屏幕选项，以下是所需的特定屏幕：
```tsx app/_layout.tsx
import { Drawer } from 'expo-router/drawer';
export default function Layout() {
  return (
    <Drawer>
      <Drawer.Screen
        name="index" // 这是页面的名称，必须与根目录中的 URL 匹配
        options={{
          drawerLabel: 'Home',
          title: 'overview',
        }}
      />
      <Drawer.Screen
        name="user/[id]" // 这是页面的名称，必须与根目录中的 URL 匹配
        options={{
          drawerLabel: 'User',
          title: 'overview',
        }}
      />
    </Drawer>
  );
}
```
For SDK 53 及更早版本: 
## 安装
```sh
$ npx expo install @react-navigation/drawer react-native-reanimated react-native-gesture-handler
```
## 用法
现在您可以使用 `Drawer` 布局来创建抽屉导航器。
```tsx app/_layout.tsx
import { Drawer } from 'expo-router/drawer';
export default function Layout() {
  return <Drawer />;
}
```
要编辑抽屉导航菜单标签、标题和屏幕选项，以下是所需的特定屏幕：
```tsx app/_layout.tsx
import { Drawer } from 'expo-router/drawer';
export default function Layout() {
  return (
    <Drawer>
      <Drawer.Screen
        name="index" // 这是页面的名称，必须与根目录中的 URL 匹配
        options={{
          drawerLabel: 'Home',
          title: 'overview',
        }}
      />
      <Drawer.Screen
        name="user/[id]" // 这是页面的名称，必须与根目录中的 URL 匹配
        options={{
          drawerLabel: 'User',
          title: 'overview',
        }}
      />
    </Drawer>
  );
}
```


## Expo Router 的认证

如何在 Expo Router 中实现认证并保护路由。

> **info** **注意：** 本指南需要 SDK 53 及更高版本。有关该指南的先前版本，请参见 [身份验证（重定向）](/router/advanced/authentication-rewrites/)。
使用 Expo Router，所有路由始终被定义并可以访问。您可以使用运行时逻辑根据用户是否已认证将用户重定向到特定屏幕以外的地方。在路由内对用户进行认证有两种不同的技术。 本指南提供了一个示例，演示标准原生应用程序的功能。
## 使用受保护路由
[受保护路由](/router/advanced/protected/) 允许您通过客户端导航来防止用户访问某些路由。如果用户尝试导航到受保护的屏幕，或者如果屏幕在其活动时变为受保护的，他们将被重定向到锚路由（通常是索引屏幕）或堆栈中第一个可用屏幕。 考虑以下项目结构，其中有一个始终可访问的 `/sign-in` 路由和一个需要认证的 `(app)` 组：
Step 1: 
要遵循上述示例，设置一个 [React Context 提供者](https://react.dev/reference/react/createContext)，它可以将认证会话暴露给整个应用程序。你可以实现你自己的自定义认证会话提供者，或者使用下面的 **示例认证上下文**。
Note: 示例认证上下文
---
此提供者使用模拟实现。您可以用您自己的 [认证提供者](/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,
});
// 使用此钩子访问用户信息。
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.Provider
      value={{
        signIn: () => {
          // 在此处执行登录逻辑
          setSession('xxx');
        },
        signOut: () => {
          setSession(null);
        },
        session,
        isLoading,
      }}>
      {children}
    </AuthContext.Provider>
  );
}
```
以下代码片段是一个基本钩子，它通过 [`expo-secure-store`](/versions/latest/sdk/securestore) 在本地安全地持久化令牌，并在网络上存储在本地存储中。
```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> {
  // 公共
  const [state, setState] = useAsyncState<string>();
  // 获取
  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: string | null) => {
        setState(value);
      });
    }
  }, [key]);
  // 设置
  const setValue = useCallback(
    (value: string | null) => {
      setState(value);
      setStorageItemAsync(key, value);
    },
    [key]
  );
  return [state, setValue];
}
```
---
Step 2: 
创建一个 **SplashScreenController** 来管理启动屏幕。认证加载是异步的，因此要在认证加载完成之前保持启动屏幕可见。
```tsx splash.tsx
import { SplashScreen } from 'expo-router';
import { useSession } from './ctx';
SplashScreen.preventAutoHideAsync();
export function SplashScreenController() {
  const { isLoading } = useSession();
  if (!isLoading) {
    SplashScreen.hide();
  }
  return null;
}
```
Step 3: 
将 `SessionProvider` 添加到您的根布局。这使您的整个应用程序能够访问认证上下文。确保 `SplashScreenController` 在 `SessionProvider` 内部。
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
import { SessionProvider } from '../ctx';
import { SplashScreenController } from '../splash';
export default function Root() {
  // 设置认证上下文并在其中渲染布局。
  return (
    <SessionProvider>
      <SplashScreenController />
      <RootNavigator />
    </SessionProvider>
  );
}
// 创建一个可以在稍后访问 SessionProvider 上下文的新组件。
function RootNavigator() {
  return <Stack />;
}
```
Step 4: 
创建 `/sign-in` 屏幕。该屏幕使用 `signIn()` 切换认证。由于该屏幕在 `(app)` 组外，因此在渲染此屏幕时，该组的布局和认证检查不会运行。这允许未登录的用户访问该屏幕。
```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();
          // 登录后导航。您可能希望对此进行调整，以确保登录成功后再导航。
          router.replace('/');
        }}>
        Sign In
      </Text>
    </View>
  );
}
```
Step 5: 
现在修改 `RootNavigator` 以根据您的 `SessionProvider` 保护路由。
```tsx app/_layout.tsx|collapseHeight=400
// All import statements remain the same except you need to import `useSession` from your `ctx.tsx` file.
import { SessionProvider, useSession } from '../ctx';
// 以上所有代码保持不变。根据您的 `SessionProvider` 更新 `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: 
实现一个允许用户注销的认证屏幕。
```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={() => {
          // `RootNavigator` 中的守卫会重定向回登录屏幕。
          signOut();
        }}>
        Sign Out
      </Text>
    </View>
  );
}
```
Step 7: 
创建 **app/(app)/\_layout.tsx**：
```tsx app/(app)/_layout.tsx
import { Stack } from 'expo-router';
export default function AppLayout() {
  // 这将为所有经过认证的应用路由渲染导航堆栈。
  return <Stack />;
}
```
现在您有了一个应用程序，该应用将在初始认证状态加载完成之前显示启动屏幕，并且如果用户未经过认证，将重定向到登录屏幕。如果用户访问任何具有认证检查的路由的深链接，他们将被重定向到登录屏幕。
## 模态和每路由认证
另一个常见模式是渲染在应用上方的登录模态。这使您能够在认证完成后取消并部分保留深链接。然而，此模式要求在后台渲染路由，因为这些路由需要在没有认证的情况下处理数据加载。
```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>
  );
}
```
## 更多信息
有关更多信息，请阅读 [受保护路由文档](/router/advanced/protected/)，以了解更多模式。
Video Tutorial: [如何在 Expo Router 5 及更高版本中使用受保护的路由进行顺畅的身份验证](https://www.youtube.com/watch?v=XCTaMu0qnFY)
## 中间件
传统上，网站可能利用某种形式的服务器端重定向来保护路由。Expo Router 在网络上当前仅支持构建时静态生成，且不支持自定义中间件或服务。这将在将来添加，以提供更优化的网络体验。在此期间，可以通过使用客户端重定向和加载状态来实现认证。


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

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

> **info** SDK 53 引入了 [受保护的路由](/router/advanced/protected/)，这是一种更强大的身份验证处理方法。如果您使用的是 SDK 52 及更早版本，请遵循本指南。
<VideoBoxLink
  videoId="yNaOaR2kIa0"
  title="使用 Expo Router 构建身份验证流程"
  description="学习如何在您的 Expo Router 项目中实现身份验证流程。"
  className="mb-6"
/>
使用 Expo Router，所有路由始终定义并可访问。您可以使用运行时逻辑根据用户是否经过身份验证将其重定向离开特定屏幕。有两种不同的技术用于在路由中对用户进行身份验证。本指南提供了一个示例，演示标准原生应用的功能。
## 使用 React 上下文和路由组
通常会限制某些路由仅向未通过身份验证的用户开放。这可以通过使用 React 上下文和路由组以有序的方式实现。考虑以下项目结构，其中有一个始终可访问的 `/sign-in` 路由和一个需要身份验证的 `(app)` 组：
Step 1: 
要遵循上述示例，设置一个 [React 上下文提供者](https://react.dev/reference/react/createContext)，可以将身份验证会话暴露给整个应用程序。您可以实现自定义身份验证会话提供者或使用下面的 **示例身份验证上下文**。
Note: 示例身份验证上下文
---
此提供者使用模拟实现。您可以将其替换为自己的 [身份验证提供者](/guides/authentication/)。
```tsx ctx.tsx
import { useContext, 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,
});
// 此 hook 可用于访问用户信息。
export function useSession() {
  const value = useContext(AuthContext);
  if (!value) {
    throw new Error('useSession 必须被 <SessionProvider /> 包装');
  }
  return value;
}
export function SessionProvider({ children }: PropsWithChildren) {
  const [[isLoading, session], setSession] = useStorageState('session');
  return (
    <AuthContext.Provider
      value={{
        signIn: () => {
          // 在此处理登录逻辑
          setSession('xxx');
        },
        signOut: () => {
          setSession(null);
        },
        session,
        isLoading,
      }}>
      {children}
    </AuthContext.Provider>
  );
}
```
以下代码片段是一个基本的 hook，它在原生应用中安全地持久化令牌，使用 [`expo-secure-store`](/versions/latest/sdk/securestore) 并在网页本地存储中存储。
```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> {
  // 公共
  const [state, setState] = useAsyncState<string>();
  // 获取
  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: string | null) => {
        setState(value);
      });
    }
  }, [key]);
  // 设置
  const setValue = useCallback(
    (value: string | null) => {
      setState(value);
      setStorageItemAsync(key, value);
    },
    [key]
  );
  return [state, setValue];
}
```
---
Step 2: 
在根布局中使用 `SessionProvider`，将身份验证上下文提供给整个应用程序。必须确保在触发任何导航事件之前挂载 `<Slot />`。否则将抛出运行时错误。
```tsx app/_layout.tsx
import { Slot } from 'expo-router';
import { SessionProvider } from '../ctx';
export default function Root() {
  // 设置身份验证上下文并在其中渲染布局。
  return (
    <SessionProvider>
      <Slot />
    </SessionProvider>
  );
}
```
Step 3: 
创建一个嵌套的 [布局路由](/router/basics/layout/)，在渲染子路由组件之前检查用户是否经过身份验证。如果用户未通过身份验证，此布局路由将用户重定向到登录屏幕。
```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();
  // 您可以保持闪屏开放，或渲染一个加载屏幕，就像我们在这里所做的。
  if (isLoading) {
    return <Text>Loading...</Text>;
  }
  // 仅在 (app) 组的布局中需要身份验证，用户
  // 需要能够访问 (auth) 组并再次登录。
  if (!session) {
    // 在网页上，静态渲染将停在这里，因为用户未通过身份验证
    // 在执行页面渲染的无头 Node 进程中。
    return <Redirect href="/sign-in" />;
  }
  // 该布局可以延迟，因为它不是根布局。
  return <Stack />;
}
```
Step 4: 
创建 `/sign-in` 屏幕。它可以使用 `signIn()` 切换身份验证。由于此屏幕位于 `(app)` 组之外，因此在渲染此屏幕时，该组的布局和身份验证检查不会运行。这允许未登录的用户查看此屏幕。
```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();
          // 登录后导航。您可能希望调整此设置，以确保登录
          // 成功后再导航。
          router.replace('/');
        }}>
        Sign In
      </Text>
    </View>
  );
}
```
Step 5: 
实现一个经过身份验证的屏幕，让用户注销。
```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={() => {
          // `app/(app)/_layout.tsx` 将重定向到登录屏幕。
          signOut();
        }}>
        Sign Out
      </Text>
    </View>
  );
}
```
您现在有一个应用程序，可以在检查初始身份验证状态时呈现加载状态，并在用户未通过身份验证时重定向到登录屏幕。如果用户访问带有身份验证检查的任何路由的深层链接，他们将被重定向到登录屏幕。
## 替代加载状态
使用 Expo Router，加载初始身份验证状态时必须向屏幕呈现某些内容。在上面的示例中，应用布局呈现了一个加载消息。或者，您可以使 `index` 路由成为加载状态，并将初始路由移到 `/home`，这类似于 X 的工作方式。
## 模态和每路由身份验证
另一个常见模式是在应用程序顶部渲染一个登录模态。这使您能够在身份验证完成时解除并部分保留深层链接。然而，这种模式需要在后台渲染路由，因为这些路由需要在没有身份验证的情况下处理数据加载。
```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>
  );
}
```
## 无导航导航
当应用程序尝试在 [根布局](/router/basics/layout/#root-layout) 中没有挂载导航器时执行导航时，您可能会遇到以下错误。
```text
错误：尝试在挂载根布局组件之前进行导航。确保根布局组件在第一次渲染时正在渲染一个 Slot 或其他导航器。
```
要解决此问题，请添加一个组并将条件逻辑移动到下一级。
### 之前
```
app/
    ├── _layout.tsx
    └── about.tsx
```
```tsx app/_layout.tsx
export default function RootLayout() {
  React.useEffect(() => {
    // 此导航事件将触发上述错误。
    router.push('/about');
  }, []);
  // 此条件语句创建问题，因为根布局的
  // 内容（Slot）必须在发生任何导航事件之前挂载。
  if (isLoading) {
    return <Text>Loading...</Text>;
  }
  return <Slot />;
}
```
### 之后
```
app/
    ├── _layout.tsx
    └── (app)/
        ├── _layout.tsx  # 将条件逻辑移到下一级
        └── about.tsx
```
```tsx app/_layout.tsx
export default function RootLayout() {
  return <Slot />;
}
```
```tsx app/(app)/_layout.tsx
export default function RootLayout() {
  React.useEffect(() => {
    router.push('/about');
  }, []);
  // 延迟呈现此嵌套布局的内容是可以的。我们无法
  // 延迟呈现根布局的内容，因为导航事件（重定向）
  // 会在根布局的内容被挂载之前触发。
  if (isLoading) {
    return <Text>Loading...</Text>;
  }
  return <Slot />;
}
```
## 中间件
传统上，网站可能会利用某种形式的服务器端重定向来保护路由。Expo Router 在网页上目前仅支持构建时静态生成，并不支持自定义中间件或服务。这可以在未来添加，以提供更优化的网页体验。在此期间，可以通过使用客户端重定向和加载状态来实现身份验证。


## 嵌套导航

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

> **warning** 导航 UI 元素（链接、标签、堆栈）将来可能会从 Expo Router 库中移除。
<VideoBoxLink
  videoId="izZv6a99Roo"
  title="在 Expo Router 中使用堆栈导航器"
  description="在屏幕之间导航，传递参数，创建动态路由，并配置屏幕标题和动画。"
  className="mb-6"
/>
嵌套导航器允许在另一个导航器的屏幕内渲染一个导航器。本指南是对 [React Navigation: 嵌套导航器](https://reactnavigation.org/docs/nesting-navigators) 在 Expo Router 中的扩展。它提供了一个如何在使用 Expo Router 时嵌套导航器工作的示例。
## 示例
考虑以下用于示例的文件结构：
```
app/
    ├── _layout.tsx
    ├── index.tsx
    └── home/
        ├── _layout.tsx
        ├── feed.tsx
        └── messages.tsx
```
在上述示例中，**app/home/feed.tsx** 匹配 `/home/feed`，而 **app/home/messages.tsx** 匹配 `/home/messages`。
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export default Stack;
```
下面的 **app/home/\_layout.tsx** 和 **app/index.tsx** 都嵌套在 **app/\_layout.tsx** 布局中，因此它将作为堆栈渲染。
```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** 布局中，因此它将作为选项卡渲染。
```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>
  );
}
```
## 导航到嵌套导航器中的屏幕
在 React Navigation 中，导航到特定的嵌套屏幕可以通过在参数中传递屏幕名称来控制。这会呈现指定的嵌套屏幕，而不是该嵌套导航器的初始屏幕。
例如，从 `root` 导航器中的初始屏幕，您想导航到 `settings`（一个嵌套导航器）中的名为 `media` 的屏幕。在 React Navigation 中，可以如下所示完成：
```jsx React Navigation
navigation.navigate('root', {
  screen: 'settings',
  params: {
    screen: 'media',
  },
});
```
在 Expo Router 中，您可以使用 `router.push()` 来实现相同的结果。无需在参数中显式传递屏幕名称。
```jsx Expo Router
router.push('/root/settings/media');
```


## 模态

学习如何在 Expo Router 中使用模态。

<VideoBoxLink
  videoId="gNzuJVRmyDk"
  title="使用模态和 Expo Router"
  description="了解各种在您的应用中展示内容的方法。"
  className="mb-6"
/>
模态是在移动应用中常见的用户界面模式。它们用于在现有屏幕上展示内容，通常用于不同的目的，例如显示确认警报或独立表单。您可以使用以下方法在应用中创建模态：
- 使用 React Native 的 [`Modal`](https://reactnative.dev/docs/modal) 组件。
- 使用 Expo Router 的特殊文件语法在应用的导航系统中创建模态屏幕。
每种方法都有其特定的使用场景。理解何时使用每种方法对于创造积极的用户体验至关重要。
## React Native 的 Modal 组件
`Modal` 组件是 React Native 核心 API 的一部分。常见用例包括：
- 独立交互，例如不需要成为导航系统一部分的自包含任务。
- 临时警报或确认对话框，适合进行快速交互。
下面是一个自定义 `Modal` 组件的示例，在不同平台上覆盖当前屏幕：
对于大多数用例，您可以使用 `Modal` 组件并根据应用的用户界面需求进行自定义。有关如何使用 `Modal` 组件及其属性的详细信息，请参阅 [React Native 文档](https://reactnative.dev/docs/modal)。
## 使用 Expo Router 的模态屏幕
模态屏幕是一个创建在 **app** 目录中的文件，用作现有堆栈中的路由。它用于需要成为导航系统一部分的复杂交互，例如在多步骤表单中，您可以在过程完成后链接到特定屏幕。
下面是不同平台上模态屏幕工作的示例：
### 用法
要实现模态路由，请在 **app** 目录中创建一个名为 **modal.tsx** 的屏幕。以下是示例文件结构：
```
app/
    ├── _layout.tsx
    ├── index.tsx
    └── modal.tsx
```
上述文件结构生成的布局中，`index` 是堆栈中的第一个路由。在根布局文件 (**app/\_layout.tsx**) 中，您可以在堆栈中添加 `modal` 路由。要将其呈现为模态，请在路由上将 `presentation` 选项设置为 `modal`。
```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** 文件导航到模态屏幕。
```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** 展示模态的内容。
```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',
  },
});
```
### 模态展示和消失行为
当模态作为导航中的当前屏幕并呈现为独立屏幕时，将失去其先前的上下文。其展示和消失行为在每个平台上都不同：
- 在 Android 上，模态从当前屏幕上方滑入。要消失它，请使用返回按钮导航回前一个屏幕。
- 在 iOS 上，模态从当前屏幕底部滑入。要消失它，请从顶部向下滑动。
- 在网页上，模态作为单独的路由呈现，消失行为必须通过使用 [`router.canGoBack()`](/router/navigating-pages/#imperative-navigation) 手动提供。以下是如何消失模态的示例：
```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="../">关闭模态</Link>}
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
### 更改 iOS 上状态栏外观
在 iOS 上，模态默认有黑色背景，会隐藏状态栏。要更改状态栏外观，可以使用 `Platform` API 检查当前平台是否为 iOS，然后使用 [`StatusBar`](/versions/latest/sdk/status-bar/) 组件在 **modal.tsx** 文件中更改外观。
```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',
  },
});
```
### 处理深层链接的模态
在使用堆栈或嵌套堆栈导航器时，模态需要锚定以确保正确的导航行为。这在深层链接到模态路由时是必需的。如果不进行锚定，模态后面的屏幕将被擦除，从而没有导航上下文。
一个 _锚_ 作为模态的基础。在复杂的应用中，当您有嵌套堆栈时，锚必须为嵌套堆栈定义，其值成为堆栈的初始路由。
您可以通过从堆栈的布局文件导出 `unstable_settings` 来配置锚：
```tsx
export const unstable_settings = {
  anchor: 'index', // 锚定到索引路由
};
```
在上述示例中，`anchor: 'index'` 告诉 Expo Router 在呈现模态时应在后台保持指定的锚点路由。
## 其他信息
### 展示选项
通过在 Android 和 iOS 上使用 `presentation` 选项，有不同的选项可以展示模态屏幕。
| 选项                        | 描述                                                                                                                                                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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) 模态样式。                              |


## Web 模态框

学习如何在您的网络应用中使用 Expo Router 实现和自定义模态框的行为。

**important** 网页模态框是SDK 54及更高版本中的实验性功能。要使用此功能，您必须在项目中设置环境变量 `EXPO_UNSTABLE_WEB_MODAL=1`。
现代网络应用需要一种灵活的模态体验，以适应不同的内容大小和用户交互。Expo Router 提供了多种模态呈现模式，以满足现代网络体验的需求。这些模式利用 `presentation` 和 `modal`、`formSheet`、`transparentModal` 或 `containedTransparentModal` 在不同的屏幕宽度下呈现模态，并使用 `webModalStyle` 提供可自定义的样式属性。
## Get started
> **info** 要使用新的网页模态功能，您必须为开发和 [导出](/deploy/web/#export-your-web-project) 构建设置 `EXPO_UNSTABLE_WEB_MODAL=1` 环境变量。您可以通过将其添加到项目根目录的 **.env** 文件中，或通过在命令前加上前缀来实现，例如：`EXPO_UNSTABLE_WEB_MODAL=1 npx expo start`。
在 Expo Router 中，模态框是通过带有特定选项的 `Stack.Screen` 组件配置的。这要求模态屏幕被添加到您应用的 `Stack` 布局文件中。
考虑以下导航树，它包含在布局文件中定义的堆栈导航器、访问模态的主页和模态屏幕组件：
```
app/
    ├── _layout.tsx
    ├── index.tsx
    └── modal.tsx
```
在布局文件 (**app/\_layout.tsx**) 中，模态屏幕组件被添加到 Stack 导航器中：
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  anchor: 'index',
};
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'modal', // 启用模态行为
          sheetAllowedDetents: [0.5, 1], // 针对小于 786px 的屏幕的捕捉位置数组。
        }}
      />
    </Stack>
  );
}
```
**modal.tsx** 用于显示模态框的内容：
```tsx app/modal.tsx
import { Text, View } from 'react-native';
export default function Modal() {
  return <View style={{ flex: 1, padding: 16 }}>{/* 模态内容在这里 */}</View>;
}
```
现在，要从 **index.tsx** 打开模态框，您可以在您的索引路由中使用 `router.push('/modal')`：
```tsx app/index.tsx
import { router } from 'expo-router';
import { Pressable, Text, View, StyleSheet } from 'react-native';
export default function Home() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Home Screen</Text>
      <Pressable onPress={() => router.push('/modal')} style={styles.button}>
        <Text style={styles.buttonText}>Open Modal</Text>
      </Pressable>
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 20,
  },
  button: {
    backgroundColor: '#007AFF',
    padding: 16,
    borderRadius: 8,
  },
  buttonText: {
    color: 'white',
    fontSize: 16,
    fontWeight: '600',
  },
});
```
以下是上述示例的结果：
## 锚点和嵌套堆栈
在使用堆栈或嵌套堆栈导航器时，模态框需要正确锚定，以确保正确的导航行为，尤其是在深度链接到模态路由时。如果没有锚点，模态框背后的屏幕将被擦除，失去导航上下文。
锚点\_ 是模态框的基础。在复杂的应用中，当您有嵌套堆栈时，锚点必须为嵌套堆栈定义，其值成为堆栈的初始路由。
您可以通过从堆栈的布局文件导出 `unable_settings` 来配置锚点：
```tsx
export const unstable_settings = {
  anchor: 'index', // 锚定到索引路由
};
```
在上述示例中，`anchor: 'index'` 告诉 Expo Router 在呈现模态时应在后台保持指定的锚点路由。
## 模态框呈现样式
模态框在您的网络应用中如何出现的差异在于屏幕较大（例如，台式机）时的呈现与在移动设备上运行时保持表单行为的不同，具体取决于配置选项。以下是可用于配置网络模态外观的选项，可以传递给 `Stack.Screen` 的 `options` 对象。
| 选项                  | 类型                                                                          | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `presentation`        | `'modal'`、`'formSheet'`、`'transparentModal'`、`'containedTransparentModal'` | 模态呈现样式。在宽度超过 768px 的屏幕上，所有样式显示为居中覆盖（例如，灯箱）。  在宽度小于 `768px` 的屏幕上，`formSheet` 用于显示为底部表单。 当设置为 `transparentModal` 时，显示为没有完全遮挡背景内容的覆盖。捕捉位置和表单抓取器属性不会应用。该呈现方式在构建您自己的自定义模态时非常有用。  类似于 `transparentModal`，当设置为 `containedTransparentModal` 时，显示为没有完全遮挡背景内容的覆盖。捕捉位置和其他属性不会应用。该呈现方式在构建您自己的自定义模态时非常有用。 |
| `sheetAllowedDetents` | `number[]`、`'fitToContents'`                                                 | 捕捉位置的百分比（0.0-1.0）或自动适应。仅适用于宽度小于 `768px` 的屏幕。                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `sheetGrabberVisible` | `boolean`                                                                     | **在 iOS 上，**显示/隐藏表单顶部的拖动手柄。在 Android 和网络上不支持。我们建议使用自定义表单头组件，以便在所有平台上模仿抓取器。                                                                                                                                                                                                                                                                                                                                                                                       |
| `sheetCornerRadius`   | `number`                                                                      | 表单的角半径（以像素为单位）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `webModalStyle`       | `WebModalStyle`                                                               | 特殊属性，允许网络特定的样式选项，以微调模态外观。                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
## 使用 `webModalStyle` 自定义模态样式
> **info** **注意:** `webModalStyle` 属性仅适用于网络平台。在移动设备上，模态将自动适应以使用类似表单的行为以进行触摸交互。
您可以使用 `webModalStyle` 自定义网络上模态的尺寸和外观。它提供以下属性以供进一步自定义：
| 属性                | 类型              | 描述                                                                                                     | 默认               |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------- | ------------------ |
| `width`             | `number` `string` | 重写模态的宽度（像素或百分比）。仅适用于在桌面上的网络平台。                                             | `83vw`             |
| `height`            | `number` `string` | 重写模态的高度（像素或百分比）。仅适用于在桌面上的网络平台。                                             | `79vh`             |
| `minHeight`         | `number` `string` | 桌面模态的最小高度（像素或百分比）。覆盖默认的 iOS 26 尺寸。                                             | `min(586px, 79vh)` |
| `minWidth`          | `number` `string` | 桌面模态的最小宽度（像素或百分比）。覆盖默认的 iOS 26 尺寸。                                             | `min(936px, 83vw)` |
| `border`            | `string`          | 重写桌面模态的边框（任何有效的 CSS 边框值，例如 '1px solid #ccc' 或 'none'）。                           | 无                 |
| `overlayBackground` | `string`          | 重写覆盖背景颜色（任何有效的 CSS 颜色或 rgba/hsla 值）。                                                 | 半透明黑色         |
| `shadow`            | `string`          | 重写模态阴影过滤器（任何有效的 CSS 过滤器值，例如 'drop-shadow(0 4px 8px rgba(0,0,0,0.1))' 或 'none'）。 | 投影阴影过滤器     |
### 自定义 CSS 属性
Expo Router 使用自定义 CSS 属性为模态样式设置，您可以使用 `webModalStyle` 全局覆盖这些属性。这些变量提供了对模态外观的细粒度控制。
#### 宽度和高度尺寸变量
```css
/* 默认模态宽度（桌面上为 83vw，遵循 iOS 26 规格） */
--expo-router-modal-width: 83vw;
/* 最大模态宽度（最大 936px，默认 83vw，遵循 iOS 26） */
--expo-router-modal-max-width: min(936px, 83vw);
/* 最小模态宽度（默认自动） */
--expo-router-modal-min-width: auto;
/* 默认模态高度（79vh，遵循 iOS 26 规格） */
--expo-router-modal-height: 79vh;
/* 最小模态高度（最大 586px，默认 79vh，遵循 iOS 26） */
--expo-router-modal-min-height: min(586px, 79vh);
```
#### 边框和覆盖样式变量
```css
/* 模态边框（默认无） */
--expo-router-modal-border: none;
/* 模态角半径（默认 24px，遵循 iOS 26） */
--expo-router-modal-border-radius: 24px;
/* 模态阴影过滤器（默认投影阴影） */
--expo-router-modal-shadow: drop-shadow(0 10px 8px rgb(0 0 0 / 0.04))
  drop-shadow(0 4px 3px rgb(0 0 0 / 0.1));
/* 覆盖背景颜色（默认 25% 黑色） */
--expo-router-modal-overlay-background: rgba(0, 0, 0, 0.25);
```
#### 如何将 `webModalStyle` 映射到 CSS 变量
当您使用 `webModalStyle` 重写任何尺寸变量时，Expo Router 会自动将这些 CSS 变量设置为您提供的值：
```tsx
// 此 webModalStyle 配置
webModalStyle: {
  width: 800,
  height: 600,
  border: '2px solid blue',
  overlayBackground: 'rgba(0, 0, 0, 0.7)',
  shadow: 'drop-shadow(0 8px 16px rgba(0,0,0,0.2))',
}
// ...自动设置这些 CSS 变量：
// --expo-router-modal-width: 800px
// --expo-router-modal-height: 600px
// --expo-router-modal-border: 2px solid blue
// --expo-router-modal-overlay-background: rgba(0, 0, 0, 0.7)
// --expo-router-modal-shadow: drop-shadow(0 8px 16px rgba(0,0,0,0.2))
```
## 常见示例
Note: 全屏模态框示例
---
要创建一个覆盖最大空间的全屏模态框，您可以在模态路由的 `Stack.Screen` 选项中使用 `webModalStyle` 属性：
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  anchor: 'index',
};
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'modal',
          webModalStyle: {
            width: '95vw',
            height: '95vh',
            border: 'none',
          },
        }}
      />
    </Stack>
  );
}
```
以下是上述示例的结果：
在移动设备上运行您的网络应用时，您可以将 `sheetAllowedDetents` 设置为 `fitToContents` 或自定义值，以避免显示全屏模态框：
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  anchor: 'index',
};
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'modal',
          webModalStyle: {
            width: '95vw',
            height: '95vh',
            border: 'none',
          },
          sheetAllowedDetents: 'fitToContents',
        }}
      />
    </Stack>
  );
}
```
模态框在移动设备上显示为表单：
---
Note: 紧凑模态框示例
---
对于较小的交互，您可以创建一个适应其内容的紧凑模态框：
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  anchor: 'index',
};
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'modal',
          webModalStyle: {
            width: 400,
            height: 'auto',
            minHeight: 200,
            border: '1px solid #e5e7eb',
            overlayBackground: 'rgba(0, 0, 0, 0.3)',
          },
          sheetCornerRadius: 12,
          sheetAllowedDetents: 'fitToContents',
        }}
      />
    </Stack>
  );
}
```
以下是上述示例的结果：
---
Note: 透明模态框示例
---
当您想要显示一个应该保持底层屏幕可视上下文的覆盖时，可以将 `presentation` 选项设置为 `transparentModal`：
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  anchor: 'index',
};
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'transparentModal',
        }}
      />
    </Stack>
  );
}
```
以下是上述示例的结果：
---
Note: 角半径示例
---
您可以使用 `sheetCornerRadius` 自定义角半径：
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  anchor: 'index',
};
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'formSheet',
          sheetAllowedDetents: [0.4],
          sheetCornerRadius: 32,
        }}
      />
    </Stack>
  );
}
```
以下是上述示例的结果：
---
Note: 自定义捕捉位置示例
---
您可以使用 `sheetAllowedDetents` 定义模态框可以停靠的高度：
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  anchor: 'index',
};
export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'formSheet',
          sheetAllowedDetents: [0.2, 0.5, 0.8, 0.98],
        }}
      />
    </Stack>
  );
}
```
以下是上述示例的结果：
---
## 全球 CSS 自定义
对于您的网络应用，如果您在项目中使用 [global CSS](https://docs.expo.dev/versions/latest/config/metro/#global-css) 文件，您还可以覆盖宽度、高度、边框和覆盖变量。
您可以在全局 CSS 文件中使用 `--expo-router-*` 变量添加自定义值：
```css
/* 在全局重写默认模态样式 */
:root {
  --expo-router-modal-width: 700px;
  --expo-router-modal-min-width: auto;
  --expo-router-modal-max-width: 95vw;
  --expo-router-modal-height: 640px;
  --expo-router-modal-min-height: 640px;
  --expo-router-modal-border: none;
  --expo-router-modal-border-radius: 16px;
  --expo-router-modal-shadow: drop-shadow(0 8px 16px rgba(0, 0, 0, 0.2));
  --expo-router-modal-overlay-background: rgba(0, 0, 0, 0.5);
}
```
## 自定义模态路由实现
{/* TODO (@aman): 发布本指南时，从 modals.tsx 文件中移除 "Web 模态框实现"。 */}
上面的 video 演示了一个模态窗口，它出现在网页的主要内容上方。背景变暗以吸引用户的注意力到模态框，模态框包含用户信息。这是网络模态的典型行为，用户可以与模态框进行交互或关闭模态框以返回到主页面。
您可以通过使用 [`transparentModal`](https://reactnavigation.org/docs/stack-navigator/#transparent-modals) 呈现模式、样式化覆盖和模态内容以及利用 [`react-native-reanimated`](/versions/latest/sdk/reanimated/#installation) 动画模态的呈现，来实现上述网络模态行为。
修改您项目的根布局 (**app/\_layout.tsx**) 以向模态路由添加 `options` 对象：
```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` 导航器中工作。
上述示例将 `index` 屏幕设置为 [`initialRouteName`](/router/advanced/router-settings/#initialroutename)，使用 [`unstable_settings`](/router/advanced/router-settings)。这确保了透明模态总是在当前屏幕上呈现，即使用户通过直接链接导航到模态屏幕时也是如此。
在 **modal.tsx** 中样式化覆盖和模态内容，如下所示：
```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',
      }}
    >
      {/* 按下外部时关闭模态框 */}
      <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 }}>模态屏幕</Text>
        <Link href="/">
          <Text>← 返回</Text>
        </Link>
      </Animated.View>
    </Animated.View>
  );
}
```
您可以根据需要自定义模态的外观。


## 共享路由

了解如何定义共享路由或者使用数组在不同布局中多次使用相同路由，使用 Expo Router。

为了匹配相同的 URL 但使用不同的布局，请使用 [**组**](/router/basics/notation/#parentheses) 和重叠的子路由。这个模式在原生应用程序中非常常见。例如，在 X 应用中，个人资料可以在每个标签页中查看（如首页、搜索和个人资料）。然而，访问该路由仅需要一个 URL。
在下面的示例中，**app/\_layout.tsx** 是标签栏，每个路由都有自己的标题。**app/(profile)/[user].tsx** 路由在每个标签之间共享。
```
app/
    ├── _layout.tsx
    ├── (home)/
    │   ├── _layout.tsx
    │   └── [user].tsx
    ├── (search)/
    │   ├── _layout.tsx
    │   └── [user].tsx
    └── (profile)/
        ├── _layout.tsx
        └── [user].tsx
```
> 重新加载页面时，渲染第一个字母顺序匹配的路由。
共享路由可以通过在路由中包含组名来直接导航。例如， `/(search)/baconbrix` 将在“搜索”布局中导航到 `/baconbrix`。
## 数组
> 数组语法是一个独特于原生应用开发的高级概念。
使用数组语法 `(,)` 复制组的子路由，而不是为不同的布局多次定义相同的路由。例如，`app/(home,search)/[user].tsx` &mdash; 在内存中创建 `app/(home)/[user].tsx` 和 `app/(search)/[user].tsx`。
要区分这两个路由，请使用布局的 `segment` 属性：
```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)：
```tsx app/(home,search)/_layout.tsx
export const unstable_settings = {
  initialRouteName: 'home',
  search: {
    initialRouteName: 'search',
  },
};
export default function DynamicLayout({ segment }) {
}
```
在上面的示例中，`home` 路由是 `home` 组和应用的默认路由。`search` 路由是 `search` 组的默认路由。
## 关键点
- 只能为当前导航器提供组。
- 使用数组语法时，如果有两个组（例如，`(one)/(two)`），仅最后一个组的段用于匹配路由。
- 如果至少有两个组的 `initialRouteNames`，但没有提供默认的 `initialRouteName`，则使用第一个组的 `initialRouteName`。


## 受保护的路由

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

> **warning** 受保护的路由在 SDK 53 及更高版本中可用。
Video Tutorial: [观看：使用受保护的路由](https://www.youtube.com/watch?v=zHZjJDTTHJg)
## 概述
受保护的屏幕允许您防止用户通过客户端导航访问某些路由。如果用户尝试导航到受保护的屏幕，或者如果一个屏幕在活动时变为受保护状态，他们将被重定向到锚路由（通常是索引屏幕）或堆栈中的第一个可用屏幕。
```
app/
    ├── _layout.tsx
    ├── index.tsx
    ├── about.tsx
    ├── login.tsx  # 只有在未认证时可用
    └── private/
        ├── _layout.tsx  # 只有在认证时可用
        ├── index.tsx
        └── page.tsx
```
```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 默认包括所有路由。添加 Stack.Protected 为这些屏幕创建例外。 */}
    </Stack>
  );
}
```
在这个例子中，`/private` 路由无法访问，因为 `guard` 为 false。当用户尝试访问 `/private` 时，他们会被重定向到锚路由，即 **index** 屏幕。
此外，如果用户在 `/private/page` 上，而 `guard` 条件变为 **false**，他们将自动被重定向。
当屏幕的 **guard** 从 **true** 更改为 **false** 时，它的所有历史条目将从导航历史中删除。
## 多个受保护的屏幕
在 Expo Router 中，一个屏幕 **一次只能存在于一个活动路由组中**。
您应仅在最合适的组或堆栈中声明一个屏幕一次。如果一个屏幕的可用性依赖于逻辑，则应将其包装在条件组中，而不是重复屏幕。
```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" /> // ❌ 不允许：重复屏幕
    </Stack>
  );
}
```
## 嵌套受保护的屏幕
受保护的屏幕可以嵌套以定义分层访问控制逻辑。
```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>
  );
}
```
在这种情况下：
- `/private` 仅在用户已登录且为管理员时受保护。
- `/about` 对任何已登录用户受到保护。
## 回退到特定屏幕
您可以配置导航器，在拒绝访问时回退到特定屏幕。
```
app/
    ├── _layout.tsx
    ├── index.tsx
    ├── about.tsx
    ├── login.tsx
    └── private/
        ├── _layout.tsx
        ├── index.tsx
        └── page.tsx
```
```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>
  );
}
```
在这里，因为 **index** 屏幕是受保护的而 **protected** 为 **false**，路由器重定向到第一个可用屏幕 &mdash; **login**。
## 标签和抽屉
受保护的路由也适用于 [Tabs](/router/advanced/tabs/) 和 [Drawer](/router/advanced/drawer/) 导航器。
```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>
  );
}
```
## 自定义导航器
`Protected` 也适用于使用 `withLayoutContext` 钩子的 [自定义导航器](/router/migrate/from-react-navigation/#rewrite-custom-navigators)。
## 静态渲染考虑
受保护的屏幕仅在客户端进行评估。在静态网站生成过程中，受保护路由不创建任何 HTML 文件。然而，如果用户知道这些路由的 URL，他们仍然可以直接请求相应的 HTML 或 JavaScript 文件。受保护的屏幕不能替代服务器端的身份验证或访问控制。


# 进阶

## 平台特定扩展和模块

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

在构建应用时，您可能希望根据当前平台显示特定内容。平台特定扩展和 `Platform` 模块可以使体验更符合特定平台的原生感觉。以下部分描述了您如何在 Expo Router 中实现这一点。
## 平台特定扩展
> **警告** 平台特定扩展在 Expo Router `3.5.x` 中添加。如果您正在使用较旧版本的库，请遵循[平台特定模块](#platform-module)的说明。
有两种方法可以使用平台特定扩展：
### 在应用目录内
Metro 打包器的*PLATFORM*特定扩展（例如，**.android.tsx**，**.ios.tsx**，**.native.tsx**，或 **.web.tsx**）仅在存在 **非平台版本** 时才支持在 **app** 目录中。这确保了路由在各个平台之间对深度链接是通用的。
考虑以下项目结构：
```
app/
    ├── _layout.tsx
    ├── _layout.web.tsx
    ├── index.tsx
    ├── about.tsx
    └── about.web.tsx
```
在上述文件结构中：
- **\_layout.web.tsx** 文件在网页上作为布局使用，而 **\_layout.tsx** 在所有其他平台使用。
- **index.tsx** 文件作为所有平台的首页使用。
- **about.web.tsx** 文件作为网页的关于页面使用，而 **about.tsx** 文件在所有其他平台使用。
### 在应用目录外
您可以在 **app** 目录之外创建平台特定的文件，扩展名可为（例如，**.android.tsx**，**.ios.tsx**，**.native.tsx**，或 **.web.tsx**），并从 **app** 目录中使用它们。
考虑以下项目结构：
```
app/
│   ├── _layout.tsx
│   ├── index.tsx
│   └── about.tsx
components/
    ├── about.tsx
    ├── about.ios.tsx
    └── about.web.tsx
```
在上述文件结构中，设计要求您为每个平台构建不同的 `about` 屏幕。在这种情况下，您可以在 **components** 目录中为每个平台使用平台扩展创建一个组件。当导入时，Metro 将确保根据当前平台使用正确的组件版本。然后，您可以在 **app** 目录中将该组件重新导出为屏幕。
```tsx app/about.tsx
export { default } from '../components/about';
```
## 平台模块
您可以使用来自 React Native 的 [`Platform`](https://reactnative.dev/docs/platform-specific-code#platform-module) 模块来检测当前平台，并根据结果渲染适当的内容。例如，您可以在原生上渲染 `Tabs` 布局，而在网页上渲染自定义布局。
```tsx app/_layout.tsx
import { Platform } from 'react-native';
import { Link, Slot, Tabs } from 'expo-router';
export default function Layout() {
  if (Platform.OS === 'web') {
    // 在网页上使用基本的自定义布局。
    return (
      <div style={{ flex: 1 }}>
        <header>
          <Link href="/">首页</Link>
          <Link href="/settings">设置</Link>
        </header>
        <Slot />
      </div>
    );
  }
  // 在原生平台上使用原生底部标签布局。
  return (
    <Tabs>
      <Tabs.Screen name="index" options={{ title: '首页' }} />
      <Tabs.Screen name="settings" options={{ title: '设置' }} />
    </Tabs>
  );
}
```


## 自定义链接

学习如何在使用 Expo Router 时执行链接重定向并利用第三方深度链接与 +native-intent。

Expo Router 使用扩展版的网络标准在应用程序中导航。然而，原生应用并不总是符合基于服务器的路由。这可能导致在集成任何第三方服务时出现不匹配。例如，应用可以使用任意字符串或意图对象启动，而不是 URL。在以下两种常见场景中，您可能需要自定义链接：
- **应用关闭**：当应用未打开时，传入的深度链接 URL 可能需要重写以确保无缝导航。
- **应用打开**：当应用已打开时，可能需要根据特定的业务逻辑或用户交互进行 URL 自定义。此逻辑可以是全局适用于整个应用，或者局部适用于一组路由。
## 设置链接
请参阅 [将链接引入您的应用](/linking/into-your-app/) 指南，了解如何在您的应用中设置和测试链接。
## 重写传入的原生深度链接
Expo Router 将始终假设 URL 目标是应用中的特定页面。然而，实际上，这些 URL 的性质可以有所不同：
- **来自第三方提供商的唯一/推荐 URL**：这些 URL 通常遵循特定的模式，例如 `<my-scheme>://<provider-hostname>/<uuid>`，并由外部来源生成，以引导用户访问应用中的指定内容。
- **来自早期版本的过时 URL**：应用用户可能会遇到来自旧版本应用的 URL，这可能导致过时或不存在的内容。妥善处理此类场景至关重要，以确保用户体验的流畅。
在这样的场景中，需要重写 URL 以正确目标路由。
为此，请在项目的 **app** 目录的顶层创建一个名为 **+native-intent.tsx** 的特殊文件。此文件导出一个特殊的 [`redirectSystemPath`](/versions/latest/sdk/router/#nativeintent) 方法，旨在处理 URL/路径处理。当调用时，它接收一个 `options` 对象，包含两个属性：`path` 和 `initial`。
```
app/
    └── +native-intent.tsx
```
以下是一个应用实践的示例，说明如何在 **+native-intent.tsx** 文件中使用 `redirectSystemPath`。通过遵循此示例，您可以确保应用的 URL 处理功能的稳定性和可靠性，并降低意外错误和崩溃的风险。
```ts app/+native-intent.tsx
import ThirdPartyService from 'third-party-sdk';
export function redirectSystemPath({ path, initial }) {
  try {
    if (initial) {
      // 虽然参数被称为 `path`，但不能保证这是一个路径或有效的 URL
      const url = new URL(path, 'myapp://app.home');
      // 第三方 URL 的检测将根据提供商的不同而变化
      if (url.hostname === '<third-party-provider-hostname>') {
        return ThirdPartyService.processReferringUrl(url).catch(() => {
          // 发生了错误
          return '/unexpected-error';
        });
      }
      return path;
    }
    return path;
  } catch {
    // 在此函数内不要崩溃！相反，您应该将用户重定向
    // 到一个自定义路由以处理意外错误，让他们可以报告事件
    return '/unexpected-error';
  }
}
```
## 重写传入的网页深度链接
处理网页上的深度链接与原生平台有所不同，因为初始路由过程发生的方式不同。Expo Router 无法为网页提供与 `+native-intent` 的直接对应，因为网页路由在网站的 JavaScript 执行之前被解析，并且会根据部署输出和您选择的提供商而变化。
因此，您应实现以下模式之一，以最适合您的要求：
- **服务器重定向**：由于所有网站，包括静态页面，都托管在服务器上，请考虑利用您部署提供商提供的服务器端重定向或中间件选项。这种方法非常适合针对 **server** 或 **static** 输出的部署。
- **客户端重定向**：或者，您可以在应用根 `_layout` 中管理 URL 重定向。这种方法适合处理单一输出格式目标为客户端渲染的项目。
选择与您的部署策略和技术要求相符的模式，以确保无缝处理网页平台上的传入深度链接。
## 重写 URLs
当您的应用打开时，您可以使用 `usePathname()` 钩子在 `_layout` 文件中响应 URL 更改。`_layout` 的位置决定了订阅的范围。
- **全局**：将逻辑添加到根 `_layout` 文件
- **局部**：向现有目录添加 `_layout` 文件（或创建一个新的 [组目录](/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 />;
}
```
### 使用 `redirectSystemPath`
在原生应用中，重写 URL 的另一种方法是在 [`redirectSystemPath`](#redirectsystempath) 方法中处理它。这种方法对于某些用例可能更简单，但也有一些缺点：
- **仅限原生**：此方法在网页上无效，因为 `+native-intent` 仅适用于原生应用。
- **缺乏上下文**：`+native-intent` 在应用的上下文之外处理。这意味着您无法访问其他逻辑，例如用户身份验证状态或当前路由的状态。
## 向第三方服务发送导航事件
以下是如何向外部服务（例如分析或日志服务）发送导航事件的基本示例。请咨询您的提供商以获取具体说明。
```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();
  // 执行服务初始化逻辑
  useEffect(() => {
    thirdParty.register();
    return () => {
      thirdParty.deregister();
    };
  }, [thirdParty]);
  // 将路径名称更改发送给第三方
  useEffect(() => {
    thirdParty.sendEvent({ pathname });
  }, [pathname]);
  return <Slot />;
}
```
## Universal Links 和多个域名
Expo Router 不需要为 Universal Links 和多个域名进行额外配置。提供给您的应用的所有 URL 都将被评估。要自定义您的应用的 URL 方案，您应该 [自定义应用配置中的 `scheme` 值](/versions/latest/config/app/#scheme)。
## 强制网页链接
如果您希望 URL 被用户的浏览器初步评估，请将地址写为具有 `http`/`https` 方案的完全合格 URL (FQDN)。使用完整 URL 可确保链接被解释为网页 URL，默认在用户的浏览器中打开。
这种方法对于将用户引导至外部网站或其他应用的 Universal Links 非常有效。
```ts
<Link href="https://my-website.com/router/introduction" />
```
## `legacy_subscribe`
> `legacy_subscribe` 在 SDK 52 中实验性可用。
如果您使用的第三方提供商不支持 Expo Router，但通过 `Linking.subscribe` 函数支持 React Navigation（针对现有项目），您可以将 `legacy_subscribe` 用作替代 API。
不建议在新项目或集成中使用此 API。它的用法与服务器端路由和 [静态渲染](/router/reference/static-rendering/) 不兼容，并且在离线或网络连接不良的环境中难以管理。


## 路由设置

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

> **warning** **警告：** `unstable_settings` 目前不支持 [异步路由](/router/reference/async-routes/)（仅限于开发）。这就是为何该功能被指定为 _不稳定_。
#### initialRouteName
在深度链接到一个路由时，您可能希望为用户提供一个“返回”按钮。`initialRouteName` 设置堆栈的默认屏幕，应该匹配一个有效的文件名（不带扩展名）。
```
app/
    ├── _layout.tsx
    ├── index.tsx
    └── other.tsx
```
```tsx app/_layout.tsx
import { Stack } from 'expo-router';
export const unstable_settings = {
  // 确保任何路由可以链接回 `/`
  initialRouteName: 'index',
};
export default function Layout() {
  return <Stack />;
}
```
现在直接深度链接到 `/other` 或重新加载页面将继续显示返回箭头。
使用 [数组语法](/router/advanced/shared-routes/#arrays) `(foo,bar)` 时，您可以在 `unstable_settings` 对象中指定一个组的名称以目标特定段。
```tsx other.tsx
export const unstable_settings = {
  // 用于 `(foo)`
  initialRouteName: 'first',
  // 用于 `(bar)`
  bar: {
    initialRouteName: 'second',
  },
};
```
`initialRouteName` 仅在深度链接到一个路由时使用。在应用导航期间，您正在导航到的路由将是初始路由。您可以使用 `<Link />` 组件上的 `initial` 属性或通过将选项传递给命令式 API 来禁用此行为。
```js
// 如果此导航到一个新的 _layout，别覆盖初始路由
<Link href="/route" initial={false} />;
router.push('/route', { overrideInitialScreen: false });
```


## 苹果接力

了解如何通过 Expo Router 和苹果接力在 Apple 设备之间无缝继续应用导航。

苹果接力是一个功能，使用户能够在另一台设备上继续浏览您的应用或网站。Expo Router 自动化了此功能的所有运行时路由。但是，一次性配置必须手动设置。
在 Expo Router 中，底层 iOS API（`NSUserActivity`）需要一个 `webpageUrl`，操作系统建议将其作为切换到您的应用程序的当前 URL。`expo-router/head` 组件有一个可选的原生模块，可以自动将 `webpageUrl` 设置为 Expo Router 中当前聚焦的路由。
<PlatformsSection ios web />
## 设置
以下限制和考虑事项非常重要：
- 接力仅限苹果。
- 接力无法在 Expo Go 应用中使用，因为它需要构建时配置。
- 接力要求配置 [通用链接](/linking/into-your-app/)，至少在 iOS 上，并包含 `activitycontinuation` 对象。
- 接力要求在您希望支持的每个页面上使用 `expo-router/head` 组件，或者在根布局中以便所有页面都可以连续。
要确保 **public/.well-known/apple-app-site-association** 文件配置正确，必须包含 `activitycontinuation` 键，并具有包含您的应用程序的捆绑 ID 和团队 ID 格式为 `<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>` 的 `apps` 数组。例如，`QQ57RJ5UTD.app.expo.acme`，其中 `QQ57RJ5UTD` 是团队 ID，`app.expo.acme` 是捆绑标识符。
```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` 对象是可选的，但推荐使用。
您可以使用以下命令根据您的 [app config](/versions/latest/config/app/) 生成 **apple-app-site-association** 文件：
```sh
$ npx setup-safari
```
请参阅 [测试深层链接](/linking/into-your-app/#test-the-deep-link) 指南以测试开发中的接力。
### Expo Head 设置
确保您在 `app.config.tsx` 文件中使用 `expo-router` 配置插件设置接力源。这是用户切换到您的应用程序时将用于 `webpageUrl` 的 URL。
```tsx app.config.tsx
// 确保将此更改为独特的项目。
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}`,
      // 在此处添加其他生产 URL。
      // `applinks:example.com`,
      // `activitycontinuation:example.com`,
      // `webcredentials:example.com`,
    ],
  },
  plugins: [
    [
      'expo-router',
      {
        // 注意：在 "headOrigin" 中，URL 必须以 "https://" 开头
        headOrigin:
          process.env.NODE_ENV === 'development'
            ? `https://${ngrokUrl}`
            : 'https://my-website-example.com',
      },
    ],
  ],
};
```
> 测试接力到原生时，请不要使用仅限开发的 `?mode=developer` 后缀。
配置应用程序配置后，使用以下命令重新生成您的原生项目：
```sh
$ npx expo prebuild -p ios
```
在开发过程中，您必须在 **安装应用程序到您的设备之前** 启动网站。这是因为当您安装应用程序时，操作系统将触发苹果的服务器以对您的网站进行 ping 测试，以获取 **.well-known/apple-app-site-association** 文件。如果网站未运行，操作系统将无法找到该文件，接力将无法正常工作。如果发生这种情况，请使用 `npx expo run:ios -d` 重新构建原生应用程序。
## 使用
在您希望支持接力的任何路由中，使用 `expo-router/head` 中的 `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>
    </>
  );
}
```
### 元标记
`expo-router/head` 组件支持以下元标记：
| 元标记                  | 描述                                                                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expo:handoff`          | 设置为 `true` 以启用当前路由的接力。默认值为 `false`。（仅限 iOS）                                                                                                        |
| `og:title` 和 `<title>` | 设置 `NSUserActivity` 的标题，这在接力中未使用。                                                                                                                          |
| `og:description`        | 设置 `NSUserActivity` 的描述，这在接力中未使用。                                                                                                                          |
| `og:url`                | 设置用户切换到您的应用时应打开的 URL。默认值为应用内当前 URL，在 `expo-router` 配置插件中为 `headOrigin` 属性，作为 baseURL。传递相对路径将把 `headOrigin` 附加到该路径。 |
您可能希望在平台之间切换值，对于此您可以使用 **Platform.select**：
```tsx app/index.tsx
import Head from 'expo-router/head';
export default function App() {
  return (
    <Head>
      <meta
        property="og:url"
      />
    </Head>
  );
}
```
## 调试
确保您的苹果设备已 [启用接力](https://support.apple.com/en-us/HT209455)。您可以通过以下步骤测试，但用 Safari 代替您的应用程序。
1. 在您的设备上打开原生应用程序。
2. 导航到应用程序中支持接力的路由，该路由正在呈现 Expo Router 的 `<Head />` 元素。
3. 切换到您的 Mac，并在 Dock 中点击应用程序的接力图标。
4. 切换到您的 iPhone 或 iPad，打开应用程序切换器，并点击屏幕底部的应用程序横幅。
如果您在 iPhone 的应用程序切换器中只看到 Safari 图标，则表示接力无法工作。
## 故障排除
您可以使用验证器测试 Apple App Site Association 文件 (**public/.well-known/apple-app-site-association**)，例如 [AASA Validator](https://branch.io/resources/aasa-validator/)。
如果您遇到问题，最好的办法是启用应用程序中最激进的接力设置。这可确保任何可能的路由都是可链接的。您可以通过确保 **public/.well-known/apple-app-site-association** 文件与所有路由匹配来做到这一点：
```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) 组件中，以确保在调试时每个路由都是可链接的。
确保您可以访问 Ngrok URL（例如，通过浏览器），在将应用程序安装到您的设备之前。如果您无法访问该 URL，操作系统将无法找到该文件，接力将无法正常工作。
`npx expo run:ios` 和 Xcode 都会在设置关联域时对您的应用进行代码签名，这对于接力和通用链接的正常工作是必需的。
接力在您的 Mac 和 iPhone/iPad 之间在 Expo Go 应用中不受支持。您必须构建并安装应用程序到您的设备。
**如果您在 iPhone 的应用程序切换器中看到 Safari 图标**，则意味着接力无法正常工作。
- 确保在测试接力到原生时您没有使用 `?mode=developer` 后缀。
- 还要确保您没有使用本地开发服务器 URL。例如，`http://localhost:8081`，因为这不能用作有效的应用程序网站关联链接，请在浏览器中打开正在运行的 Ngrok URL 以进行测试。
- 确保您的 **public/.well-known/apple-app-site-association** 文件包含 `activitycontinuation` 字段。
- 我们观察到在 iOS 16.3.1 和 macOS 13.0（Ventura）中，以 `app.` 和 `io.` 开头的捆绑标识符有时不会触发原生应用在 iOS 任务切换器中显示。将 `com.` 作为捆绑标识符的第一个部分使用。
您的 **public/.well-known/apple-app-site-association** 必须从安全 URL（HTTPS）提供。如果您使用开发通道，必须使用 `EXPO_TUNNEL_SUBDOMAIN` 环境变量来配置开发通道的子域。此通道是开发中测试所必需的，因为您需要使用 SSL 来使用通用链接，Expo CLI 通过运行 `npx expo start --tunnel` 提供对此的内置支持。
检查您的 **ios&#x2f;project&#x2f;project.entitlements** 文件，查找 `com.apple.developer.associated-domains` 键。这应包含与您的 Web 服务器/网站相同的域。URL 不能包含协议（`https://`）或附加的路径名、查询参数或片段。
### 仍然困惑
> 这是一个重要但非常难以设置的功能。Expo Router 自动化了许多移动部分，Expo CLI 自动化了许多配置和托管。但是，硬件设置仍然可能配置错误。
如果一切都失败了，您可以尝试按照 [Apple Docs](https://developer.apple.com/documentation/foundation/task_management/implementing_handoff_in_your_app) 中的步骤进行调试。注意：
- “将用户活动表示为 `NSUserActivity` 的实例。” 是由 Expo Head 原生模块执行的。
- “在用户在应用程序中执行操作时更新活动实例。” 是通过将 `<Head />` 组件与元标签 `<meta property="expo:handoff" content="true" />` 一起挂载/呈现执行的。
- “在您的应用中的其他设备上接收来自接力的活动。” 是由 Expo Head 原生模块中的 [App Delegate Subscriber](/modules/appdelegate-subscribers) 执行的。它用于在您传递到原生应用程序时将您重定向到正确的路由。
## 已知问题
从 Web 到原生的接力不支持客户端路由。这意味着在应用程序切换器中呈现的 URL 将是您点击链接或重新加载页面时所处页面的 URL。这是 Web 平台的限制，而不是 Expo Router 可以解决的问题。


## 自定义选项卡布局

学习如何使用无头选项卡组件在 Expo Router 中创建自定义选项卡布局。

> **important** 在 SDK 52 及更高版本中实验性可用。
Expo Router 提供了一组组件，通过子模块 [`expo-router/ui`](/versions/latest/sdk/router-ui/) 创建自定义选项卡布局。与 React Navigation 风格的 `Tabs` 不同，这些组件是无样式和灵活的，旨在允许您从头开始在项目中构建复杂的 UI 模式。
有关其他选项卡布局，请参见：
## 自定义 Tabs 组件的构成
`expo-router/ui` 提供了四个组件来创建自定义选项卡布局：
| 组件         | 描述                                                                               |
| ------------ | ---------------------------------------------------------------------------------- |
| `Tabs`       | 包含选项卡的 `<View>` 的包装组件。                                                 |
| `TabList`    | 包含 `TabTrigger` 组件列表的 `<View>`。                                            |
| `TabTrigger` | 切换到指定选项卡的触发组件。它用于使用 `href` 属性和每个选项卡的 `name` 定义路由。 |
| `TabSlot`    | 用于渲染当前选中的选项卡的插槽。                                                   |
自定义选项卡布局的最低结构将包含一个 `TabList`（其中包含每个选项卡的 `TabTrigger` 组件）和一个 `TabSlot`，所有这些都在 `Tabs` 组件中，如下所示：
```tsx app/(tabs)/_layout.tsx|collapseHeight=440
import { Tabs, TabList, TabTrigger, TabSlot } from 'expo-router/ui';
import { Text } from 'react-native';
// 定义自定义选项卡导航器的布局
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>
  );
}
```
## 创建路由
`TabList` 包含选项卡导航器内所有可用的路由。它必须是 `Tabs` 的直接子项。每个路由由 `TabList` 中的 `TabTrigger` 定义。`TabList` 中的 `TabTrigger` 必须包含一个 `name` 和一个 `href` 属性。
通常，`TabList` 定义了可用的选项卡路由和选项卡的外观，每个 `TabTrigger` 的子项定义了每个选项卡按钮的外观。
> **注意:** `name` 可以是任何 `string`。这是用户定义的选项卡名称。
### 动态路由
允许动态路由，并可以通过 `href` 提供值。
```
_layout.tsx
[slug].tsx
```
触发器 `<TabTrigger name="dynamic page" href="/hello-world" />` 将为 **[slug].tsx** 创建一个选项卡，参数为 `{ slug: 'hello-world' }`。这种设置可以用于基于最终用户数据显示任意数量的选项卡，比如在应用中为每个用户配置文件显示一个单独的选项卡。
### 模糊路由
```
_layout.tsx
(one,two)/
    └── route.tsx  # 共享组中的路由
```
提供给 `TabTrigger` 的 `href` 值必须始终指向单一路由。在上述共享路由示例中，href `/route` 是不允许的，因为它可以引用 `/(one)/route` 或 `/(two)/route`。但是，指定路由组的 href 将有效（例如`href="/(one)/route"`）。
### 嵌套路由
```
_layout.tsx
(stack-one)/
    ├── _layout.tsx  # 一个 <Stack> 布局
    └── (stack-two)/
        ├── _layout.tsx  # 嵌套 <Stack> 布局
        └── route.tsx
```
`TabTrigger` 可以链接到嵌套很深的路由。`<TabTrigger name="route" href="/route" />` 将显示 **(stack-one)/(stack-two)/route.tsx** 路由。这个选项卡将由该路由的父导航器控制（即在 **stack-two_layout.tsx** 中的导航器）。这种导航与深层链接类似。
## 渲染路由
`TabSlot` 组件渲染当前路由。`TabSlot` 可以嵌套在 `Tabs` 中的其他组件内，但不能在 `TabList` 中。
```tsx app/_layout.tsx
<Tabs>
  <TabList>
    <TabTrigger name="home" href="/">
      <Text>Home</Text>
    </TabTrigger>
  </TabList>
  {/* 自定义 `<TabSlot />` 的渲染方式。 */}
  <View>
    <View>
      <TabSlot />
    </View>
  </View>
</Tabs>
```
## 切换选项卡
可以通过 `Link` 或使用命令式 API 切换选项卡。但是，这些 API 将始终执行导航操作（它们将切换选项卡并可能更改 URL）。要切换选项卡而不执行任何导航，应使用 `TabTrigger`。`TabTrigger` 是一个无样式的 `<View>`，当按下时会切换选项卡，就像文本和组件可以用 `Link` 包裹以使其成为可按压的导航元素一样。
### 重置导航
可以使用来自 `TabTrigger` 的 `reset` 属性控制选项卡何时重置其导航状态。选项有 `always`, `onLongPress` 和 `never`。这对于嵌套在选项卡内的堆栈导航器特别有用。例如，`<TabTrigger name="home" reset="always" />` 将使用户返回到选项卡嵌套堆栈导航器内的索引路由。
## TabTrigger
`TabTrigger` 用于切换选项卡，但也具有定义作为选项卡可用的路由的双重角色。
### 在 TabList 内
当 `TabTrigger` 作为 `TabList` 的子项使用时，定义了选项卡导航器内可用的路由。这些 `TabTrigger` 需要同时包含 `name` 和 `href` 属性，因为它们定义了该选项卡的 URL 和可用于引用该选项卡的自定义名称。如果 `TabTrigger` 组件还包含文本或其他组件作为子项，则这些也将作为选项卡按钮呈现。但是，您可以在 `TabList` 内定义没有任何 UI 的 `TabTrigger`，然后可以由在 `TabList` 外的 `TabTrigger` 调用。
### 在 TabList 外
可以在 `TabList` 外部定义额外的 `TabTrigger`，使您能够执行与在 `TabList` 定义的 `TabTrigger` 相同的操作。在这种情况下，`TabTrigger` 将没有 `href` 属性。相反，它将执行与主 `TabTrigger` 相同的操作，具有相同的 `name` 属性。这使您能够创建可以切换选项卡并与当前导航状态无关的组件。请注意所有 `TabTrigger` 至少需要是 `Tabs` 组件的后代，否则将被视为在选项卡导航器外并无法调用它。
## 自定义外观
除了 `TabTrigger` 以 `<Pressable>` 渲染外，所有组件都是作为无样式的 `<View>` 渲染。这使您可以提供自定义的 `style` 属性来美化其外观。给 `TabList` 样式设置类似于在 React Navigation 中自定义选项卡栏，给 `TabTrigger` 样式设置影响选项卡按钮的外观。
如果您需要改变组件的结构，您可以通过使用 `asChild` 属性重写其底层组件。该组件将充当插槽，并将其属性转发给其直接子项。
```tsx Custom TabList
<Tabs>
  <TabSlot />
  <TabList asChild>
    {/* 渲染自定义 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>
      {/* 渲染自定义按钮 */}
      <CustomButton>
        <Text>Home</Text>
      </CustomButton>
    </TabTrigger>
  </TabList>
</Tabs>
```
### 多个选项卡栏
`TabList` 是 `Tabs` 的配置和默认外观，但这不是渲染选项卡栏的唯一方式。通过隐藏 `TabList`，您可以使用 `TabTrigger` 构建自定义选项卡栏。
```tsx 多个选项卡栏示例
<Tabs>
  <TabSlot />
  {/* 自定义选项卡栏 */}
  <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` 将转发一个 `isFocused` 属性，因此您可以创建一个单独的选项卡按钮组件，该组件对聚焦状态做出反应。
```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 及更早版本
---
在 Expo SDK 52 及更早版本（React 18）中，使用遗留的 `forwardRef` 函数来访问 `ref` 句柄。
```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>) => {
```
---
### 钩子
所有组件也都有一个钩子版本，让您控制渲染树。有关可用钩子的完整列表，请参见 [Router UI Reference](/versions/latest/sdk/router-ui/)。
使用钩子被视为该库的高级用法。对于大多数用例，使用 `asChild` 的组件应该能给您提供足够的控制权。
如果您正在开发自定义 `<TabTrigger />`，您可能还需要开发自定义 `<TabList />`，因为 `<TabList />` 使用了 [`useTabsWithChildren()`](/versions/latest/sdk/router-ui/#usetabswithchildrenoptions)，这需要使用导出的 `<TabTrigger />` 组件。
### 自定义选项卡屏幕的渲染方式
`TabSlot` 接受一个 `renderFn` 属性。此函数可用于覆盖屏幕的渲染方式，允许您实现高级功能，例如动画或持久化/卸载屏幕。有关更多信息，请参见 [Router UI Reference](/versions/latest/sdk/router-ui/)。
## 常见问题
Note: 我如何为相同路由创建多个选项卡？
---
```
_layout.tsx  # 选项卡布局
(movie,tv)/
    └── [id].tsx
```
您应该将路由添加到共享组中并为每个组 `group` 创建单独的 `TabTrigger`。
---
Note: 我如何隐藏选项卡？
---
不渲染 `TabTrigger` 将从您的应用中移除该选项卡（及其导航状态）。
---
Note: 我如何创建动画选项卡？
---
您可以向 `TabSlot` 提供自定义呈现器，以自定义其渲染屏幕的方式。您可以使用此方法检测屏幕何时聚焦并相应地进行动画处理。
---
Note: 我可以使用相对 href 吗？
---
```
directory/
    ├── _layout.tsx  # 本地路径名是 /directory
    ├── page.tsx  # 路径名是 /directory/page
    └── profile.tsx  # 路径名是 /directory/profile
```
具有相对 href 的 `TabTrigger` 相对于 `Tabs` 渲染的本地路径名。与当前显示路由的正常相对 href 不同。例如，`<TabTrigger href="./profile" />` 将解析为 `/directory/profile`，即使当前显示的是 `/directory/page` 路由。Expo 不建议使用相对 href。
---


# 参考

## 错误处理

学习如何在使用 Expo Router 时处理未匹配的路由和错误。

本指南指定了在使用 Expo Router 时如何处理未匹配的路由和错误。
## 未匹配的路由
原生应用没有服务器，因此技术上没有 404。然而，如果你在全局实现路由，处理缺失的路由是有意义的。这对每个应用程序都是自动完成的，但你也可以自定义它。
```tsx app/+not-found.tsx
import { Unmatched } from 'expo-router';
export default Unmatched;
```
这将呈现默认的 `Unmatched`。你可以导出希望呈现的任何组件。我们建议添加一个指向 `/` 的链接，以便用户可以导航回主页。
### 路由优先级
在 Web 上，文件按以下顺序提供服务：
1. **public** 目录中的静态文件。
2. 应用目录中的标准和动态路由。
3. [API 路由](/router/reference/api-routes) 在应用目录中。
4. 未找到的路由将最后提供，并返回 404 状态码。
## 错误处理
Expo Router 启用精细化的错误处理，以便在未来实现更具主观的数据加载策略。
你可以从任何路由导出嵌套的 [`ErrorBoundary`](/versions/latest/sdk/router/#errorboundary) 组件，以使用 [React 错误边界](https://react.dev/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 错误边界包裹：
```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) 属性。
### 进行中的工作
React Native LogBox 需要以较少的侵略性呈现，以便在开发时处理错误。目前，它会对 `console.error` 和 `console.warn` 显示。然而，理想情况下，它应该只对于未捕获的错误显示。


## 使用 URL 参数

学习如何在应用中访问和修改路由参数和搜索参数。

URL 参数包括 **路由参数** 和 **搜索参数**。Expo Router 提供 hooks 用于访问和修改这些参数。
## 路由参数和搜索参数的区别
路由参数是定义在 URL 路径中的动态片段，如 `/profile/[user]`，其中 `user` 是路由参数。它们用于匹配路由。
搜索参数（也称为查询参数）是可以附加到 URL 上的可序列化字段，如 `/profile?extra=info`，其中 `extra` 是搜索参数。它们通常用于在页面之间传递数据。
## 本地与全局 URL 参数
在嵌套应用中，您常常会同时有 **多个页面挂载**。例如，当新的路由被推送时，堆栈中会同时保留前一页面和当前页面的内存。因此，Expo Router 提供了两种不同的 hooks 来访问 URL 参数：
- **useLocalSearchParams**：返回当前组件的 URL 参数。仅当全局 URL 符合路由时才会更新。
- **useGlobalSearchParams**：返回全局 URL，不考虑组件。它在每次 URL 参数更改时更新，并可能导致组件在后台非必要地更新。
hooks `useGlobalSearchParams` 和 `useLocalSearchParams` 允许您在组件内部访问这些参数，使您能够检索和利用这两种类型的 URL 参数。
这两个 hooks 的类型和访问方式相同。但唯一的区别是它们更新的频率。
下面的示例演示了 `useLocalSearchParams` 和 `useGlobalSearchParams` 之间的区别。它使用以下 **app** 目录结构：
```
app/
    ├── _layout.tsx
    ├── index.tsx
    └── [user].tsx
```
Step 1: 
    根布局是一个堆栈导航器：
    ```tsx app/_layout.tsx
    import { Stack } from 'expo-router';
    export default function Layout() {
      return <Stack />;
    }
    ```
Step 2: 
    初始路由重定向到动态路由 **app/[user].tsx**，其 **user=evanbacon**：
    ```tsx app/index.tsx
    import { Redirect } from 'expo-router';
    export default function Route() {
      return <Redirect href="/evanbacon" />;
    }
    ```
Step 3: 
    动态路由 **app/[user]** 打印全局和本地 URL 参数（在此情况下为路由参数）。它还允许通过不同的 **路由参数** 推送同一路由的新实例：
    ```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: 
当应用启动时，打印以下日志：
```sh
Local: evanbacon Global: evanbacon
```
按下“Visit charlie”会推送新的 `/[user]` 实例，**user=charlie**，并记录以下内容：
```sh
Local: charlie Global: charlie
Local: evanbacon Global: charlie
```
按下“Visit james”会有类似的效果：
```sh
Local: james Global: james
Local: evanbacon Global: james
Local: charlie Global: james
```
    **结果：**
    - `useGlobalSearchParams` 在 URL **路由参数** 更改时使后台屏幕重新渲染。如果过度使用，可能会导致性能问题。
    - 全局重新渲染按堆栈顺序执行，因此第一个屏幕首先重新渲染，然后是 **user=charlie** 屏幕。
    - `useLocalSearchParams` 在全局 URL **路由参数** 更改时保持不变。您可以利用这种行为进行数据获取，以确保在返回时先前屏幕的数据仍然可用。
## 静态类型的 URL 参数
`useLocalSearchParams` 和 `useGlobalSearchParams` 都可以使用泛型进行静态类型化。以下是 `user` 路由参数的示例：
```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>;
}
// 给定 URL： `/evanbacon`
// 返回： { user: "evanbacon" }
```
任何搜索参数（例如，`?query=...`）可以选择性地进行类型定义：
```tsx app/[user].tsx
const { user, query } = useLocalSearchParams<{ user: string; query?: string }>();
// 给定 URL： `/evanbacon?query=hello`
// 返回： { user: "evanbacon", query: "hello" }
```
与剩余语法（`...`）一起使用时，路由参数作为字符串数组返回：
```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>;
}
// 给定 URL： `/evanbacon/123`
// 返回： { everything: ["evanbacon", "123"] }
```
任何搜索参数将继续作为单独的字符串返回：
```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>;
}
// 给定 URL： `/evanbacon/123?query=hello&query2=world`
// 返回： { everything: ["evanbacon", "123"], query: "hello", query2: "world" }
```
## 更新 URL 参数
URL 参数可以使用 **router.setParams** 函数从命令式 API 更新。更新 URL 参数不会将任何内容推送到历史堆栈。
以下示例使用 `<TextInput>` 更新搜索参数 **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="搜索"
      style={{
        borderRadius: 12,
        backgroundColor: '#fff',
        fontSize: 24,
        color: '#000',
        margin: 12,
        padding: 16,
      }}
    />
  );
}
```
这里是一个使用 `onPress` 事件来更新路由参数 **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' })}>去 Evan</Text>
    </>
  );
}
```
## 路由参数与搜索参数
路由参数用于匹配路由，而搜索参数用于在路由之间传递数据。考虑以下结构，在其中使用一个路由参数来匹配 _user_ 路由：
当匹配 `app/[user]` 路由时，`user` 参数传递给组件，并且始终不是空值。搜索参数和路由参数可以一起使用，并且可以通过 `useLocalSearchParams` 和 `useGlobalSearchParams` hooks 访问：
```tsx app/[user].tsx
import { useLocalSearchParams } from 'expo-router';
export default function User() {
  const {
    // 路由参数
    user,
    // 可选搜索参数。
    tab,
  } = useLocalSearchParams<{ user: string; tab?: string }>();
  console.log({ user, tab });
  // 给定 URL: `/bacon?tab=projects`，打印如下：
  // { user: 'bacon', tab: 'projects' }
  // 给定 URL: `/expo`，打印如下：
  // { user: 'expo', tab: undefined }
}
```
每当路由参数更改时，组件将重新挂载。
```tsx app/[user].tsx
import { Text } from 'react-native';
import { router, useLocalSearchParams, Link } from 'expo-router';
export default function User() {
  // 下面三个都会更改路由参数 `user`，并添加一个新的用户页面。
  return (
    <>
      <Text onPress={() => router.setParams({ user: 'evan' })}>去 Evan</Text>
      <Text onPress={() => router.push('/mark')}>去 Mark</Text>
      <Link href="/charlie">去 Charlie</Link>
    </>
  );
}
```
{/*
TODO: REMOVE COMMENT WHEN https://github.com/expo/expo/pull/30268 IS PUBLISHED
## 数组支持
多个相同的 URL 参数将被组合为一个数组。
```tsx app/hash.tsx
import { router, useLocalSearchParams } from 'expo-router';
export default function Route() {
  // 如果当前 URL 是 `/route?myParam=1&myParam=2`
  const { myParam } = useLocalSearchParams();
  // myParam === ["1", "2"]
}
```
\*/}
## 哈希支持
URL [哈希](https://developer.mozilla.org/en-US/docs/Web/API/URL/hash) 是一个跟随在 URL 中 `#` 符号后面的字符串。它通常用于在网站上链接到页面的特定部分，但也可以用于存储数据。Expo Router 将哈希视为使用名称 `#` 的特殊搜索参数。可以使用与 [搜索参数](#local-versus-global-search-parameters) 相同的 hooks 和 API 访问和修改它。
```tsx app/hash.tsx
import { Text } from 'react-native';
import { router, useLocalSearchParams, Link } from 'expo-router';
export default function User() {
  // 访问哈希
  const { '#': hash } = useLocalSearchParams<{ '#': string }>();
  return (
    <>
      <Text onPress={() => router.setParams({ '#': 'my-hash' })}>设置新哈希</Text>
      <Text onPress={() => router.push('/#my-hash')}>推送新哈希</Text>
      <Link href="/#my-hash">指向哈希的链接</Link>
    </>
  );
}
```
## 保留参数
某些 URL 参数保留供 Expo Router 和 React Navigation 内部使用。避免使用以下名称作为您自己的参数，以防止冲突：
- `screen`
- `params`
- `initial`
- `state`


## 服务器中间件

学习如何在 Expo Router 中创建对服务器的每个请求都运行的中间件。

> **important** 服务器中间件是 SDK 54 及更高版本中的实验性功能，需要一个[已部署的服务器](/router/reference/api-routes/#deployment)才能在生产环境中使用。
Expo Router 中的服务器中间件允许您在请求到达路由之前运行代码，从而为每个请求启用强大的服务器端功能，如身份验证和日志记录。与处理特定端点的[API 路由](/router/reference/api-routes)不同，中间件适用于您的应用中的 **每个** 请求，因此应该尽可能快速运行，以避免降低应用的性能。在本地应用或在使用 [`<Link />`](/versions/latest/sdk/router/#link) 的 Web 应用中，客户端导航不会经过服务器中间件。
## 设置
Step 1: 
### 在应用配置中启用服务器中间件
首先，通过将服务器配置添加到您的[应用配置](/versions/latest/config/app/)中来配置您的应用以使用服务器输出：
```json app.json
{
  "expo": {
    "web": {
      "output": "server"
    },
    "plugins": [
      [
        "expo-router",
        {
          "unstable_useServerMiddleware": true
        }
      ]
    ]
  }
}
```
Step 2: 
### 创建中间件文件
在您的 **app** 目录中创建一个 **+middleware.ts** 文件，以定义您的服务器中间件函数：
```ts app/+middleware.ts
export default function middleware(request) {
  console.log(`Middleware executed for: ${request.url}`);
  // 您的中间件逻辑在这里
}
```
中间件函数必须是文件的默认导出。它接收一个[不可变请求](#request-immutability)，可以返回一个 [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)，或者返回空以让请求不被修改地通过。请求是不可变的，以防止副作用；您可以读取头部和属性，但无法修改头部或消费请求体。
Step 3: 
### 启动开发服务器
运行您的开发服务器以测试中间件：
```sh
$ npx expo start
```
您的中间件现在将针对应用的所有请求运行。
Step 4: 
### 测试中间件功能
在浏览器中访问您的应用或发出请求以测试您的中间件是否工作。检查控制台以查看来自中间件函数的日志消息。
Step 5: 
### 配置中间件匹配器（可选）
默认情况下，中间件在所有服务器请求上运行。您可以添加匹配器以控制中间件执行的时机，使用 `unstable_settings`：
```ts app/+middleware.ts
export const unstable_settings = {
  matcher: {
    // 仅在 GET 请求上运行
    methods: ['GET'],
    // 仅在 API 路由和特定路径上运行
    patterns: ['/api', '/admin/[...path]'],
  },
};
export default function middleware(request) {
  console.log(`Middleware executed for: ${request.url}`);
}
```
匹配器配置允许您：
- **按 HTTP 方法过滤**：指定哪些方法应触发中间件
- **按路径模式过滤**：定义哪些 URL 模式应使用精确路径、命名参数或正则表达式匹配
## 工作原理
中间件函数在任何路由处理程序之前执行，允许您执行日志记录、身份验证或修改响应等操作。它专门在服务器上运行，仅对实际的 HTTP 请求执行。
### 请求/响应流
当请求进入您的应用时，Expo Router 按以下顺序处理它：
1. 中间件函数首先运行，使用[不可变请求](#request-immutability)。
2. 如果中间件返回一个 `Response`，则该响应会立即发送
3. 如果中间件不返回任何内容，请求将继续到匹配的路由
4. 路由处理程序处理请求并返回其响应
### 模式匹配
匹配器支持不同的模式类型，以控制中间件的运行时机：
```ts
export const unstable_settings = {
  matcher: {
    patterns: [
      '/api', // 精确路径
      '/posts/[postId]', // 命名参数
      '/blog/[...slug]', // 捕获所有参数
      /^\/api\/v\d+\/users$/, // 正则表达式
    ],
  },
};
```
- **精确路径** 仅匹配指定路径。`/api` 匹配 `/api`，但不匹配 `/api/users`
- **命名参数** 例如 `[postId]` 捕获任何单个段。`/posts/[postId]` 匹配 `/posts/123` 或 `/posts/my-post`
- **捕获所有参数** 例如 `[...slug]` 捕获一个或多个段。`/blog/[...slug]` 匹配 `/blog/2024` 或 `/blog/2024/12/post`
- **正则表达式** 用于复杂模式。`/^\/api\/v\d+\/users$/` 匹配 `/api/v1/users`，但不匹配 `/api/users`
如果 **任何** 模式与请求 URL 匹配，则中间件会运行。当同时指定 `methods` 和 `patterns` 时，必须满足这两个条件，以便中间件运行。
### 中间件执行顺序
Expo Router 支持一个名为 **+middleware.ts** 的单一中间件文件，适用于所有服务器请求。当使用匹配器时，中间件仅在与指定模式和方法匹配的请求上执行，在发生任何路由匹配或呈现之前。
### 中间件运行时机
中间件仅在对您的服务器的实际 HTTP 请求中执行。这意味着它在以下情况下执行：
- 初始页面加载，例如用户首次访问您的网站时
- 完整页面刷新
- 直接 URL 导航
- 来自任何客户端的 API 路由调用（本地/Web 应用程序、外部服务）
- 服务器端渲染请求
中间件不在以下情况下运行：
- 使用 [`<Link />`](/versions/latest/sdk/router/#link) 或 [`router`](/versions/latest/sdk/router/#router) 的客户端导航
- 本地应用程序的屏幕过渡
- 预取的路由
- 静态资源请求，如图像和字体
## 示例
Note: 身份验证
---
中间件通常用于在路由加载之前执行授权检查。您可以检查头部、cookie 或查询参数，以确定用户是否可以访问特定路由：
```ts app/+middleware.ts
import { jwtVerify } from 'jose';
export default function middleware(request) {
  const token = request.headers.get('authorization');
  const decoded = jwtVerify(token, process.env.SECRET_KEY);
  if (!decoded.payload) {
    return new Response('Forbidden', { status: 403 });
  }
}
```
---
Note: 日志记录
---
您可以使用中间件来记录请求，以便调试或分析。这可以帮助您跟踪用户活动或诊断应用中的问题：
```ts app/+middleware.ts
export default function middleware(request) {
  console.log(`${request.method} ${request.url}`);
}
```
---
Note: 动态重定向
---
中间件还可以用来执行动态重定向。这使您能够根据特定条件控制用户导航：
```ts app/+middleware.ts
export default function middleware(request) {
  if (request.headers.has('specific-header')) {
    return Response.redirect('https://expo.dev');
  }
}
```
---
Note: 仅限 API 的中间件
---
使用匹配器仅对 API 路由运行中间件，保持其他路由不受影响：
```ts app/+middleware.ts
export const unstable_settings = {
  matcher: {
    patterns: ['/api'],
  },
};
export default function middleware(request) {
  // 记录所有 API 请求以便调试
  console.log(`API request: ${request.method} ${request.url}`);
  // 为 API 路由添加 CORS 头
  const response = new Response();
  response.headers.set('Access-Control-Allow-Origin', '*');
  return response;
}
```
---
Note: 特定方法身份验证
---
保护写操作（POST、PUT、DELETE），同时允许公共读取访问：
```ts app/+middleware.ts
export const unstable_settings = {
  matcher: {
    methods: ['POST', 'PUT', 'DELETE'],
    patterns: ['/api', '/admin/[...path]'],
  },
};
export default function middleware(request) {
  const token = request.headers.get('authorization');
  if (!token || !isValidToken(token)) {
    return new Response('Unauthorized', { status: 401 });
  }
}
function isValidToken(token: string): boolean {
  // 您的令牌验证逻辑
  return token.startsWith('Bearer ');
}
```
---
Note: 选择性日志记录
---
监控特定端点，而不记录每个请求：
```ts app/+middleware.ts
export const unstable_settings = {
  matcher: {
    patterns: ['/api/users/[userId]', '/admin', /^\/webhook/],
  },
};
export default function middleware(request) {
  const userAgent = request.headers.get('user-agent');
  const timestamp = new Date().toISOString();
  console.log(`[${timestamp}] ${request.method} ${request.url} - ${userAgent}`);
}
```
---
## 其他说明
### 最佳实践
- 使中间件轻量，因为它在每个服务器请求上同步运行，并直接影响响应时间。
- 使用匹配器通过避免在不需要它的路由上不必要的中间件执行来优化性能，尤其是对于流量大的应用程序。
- 优先使用精确路径和命名参数，而不是正则表达式，因为简单模式比复杂正则表达式更容易评估和维护。
- 组合方法和模式过滤，以精确控制中间件执行的时机。
- 对于本地应用，使用 API 路由进行安全的数据获取。当本地应用调用 API 路由时，这些请求将首先通过中间件。
### 类型化中间件
```ts app/+middleware.ts
import { MiddlewareFunction } from 'expo-router/server';
const middleware: MiddlewareFunction = request => {
  if (request.headers.has('specific-header')) {
    return Response.redirect('https://expo.dev');
  }
};
export default middleware;
```
### 限制
- 中间件仅在服务器上运行，并且仅对 HTTP 请求。它不会在客户端导航期间执行，例如使用 [`<Link />`](/versions/latest/sdk/router/#link) 或本地应用程序的屏幕过渡。
- 传递给中间件的请求对象是[不可变的](#request-immutability)，以防止副作用。您无法修改头部或消费请求体，确保它仍可用于路由处理程序。
- 您的应用中只能有一个根级 **+middleware.ts**。
- [适用于 API 路由](https://router/reference/api-routes/#known-limitations) 的相同限制也适用于中间件。
### 请求不可变性
为了防止意外副作用并确保请求体保持可用于路由处理程序，传递给中间件的 [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) 是不可变的。这意味着您可以：
- 读取所有请求属性，如 `url`、`method`、`headers` 等
- 使用 `request.headers.get()` 读取头部值
- 使用 `request.headers.has()` 检查头部的存在
- 访问 URL 参数和查询字符串
但您将无法：
- 使用 `set()`、`append()`、`delete()` 修改头部
- 使用 `text()`、`json()`、`formData()` 等消费请求体
- 直接访问 `body` 属性


## 重定向

学习如何在 Expo Router 中重定向 URL。

您可以根据某些应用内标准将请求重定向到不同的 URL。Expo Router 支持多种不同的重定向模式。
## 使用 `Redirect` 组件
您可以通过使用 `Redirect` 组件立即从某个特定屏幕重定向：
```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>
  );
}
```
## 使用 `useRouter` hook
您也可以通过 `useRouter` hook 进行命令式重定向：
```tsx
import { Text } from 'react-native';
import { useRouter, useFocusEffect } from 'expo-router';
function MyScreen() {
  const router = useRouter();
  useFocusEffect(() => {
    // 调用 replace 方法重定向到新路由，而不将其添加到历史记录中。
    // 我们在 useFocusEffect 中这样做，以确保每次屏幕聚焦时都发生重定向。
    router.replace('/profile/settings');
  });
  return <Text>My Screen</Text>;
}
```


## 静态渲染

学习如何使用 Expo Router 将路由渲染为静态 HTML 和 CSS 文件。

要在网页上启用搜索引擎优化（SEO），您必须静态渲染您的应用程序。本指南将引导您完成静态渲染您的 Expo Router 应用程序的过程。
## 设置
Step 1: 
在项目的 [app config](/versions/latest/config/app/) 中启用 metro 打包器和静态渲染：
```json app.json
{
  "expo": {
    "web": {
      "bundler": "metro",
      "output": "static"
    }
  }
}
```
Step 2: 
如果您的项目中有 **metro.config.js** 文件，请确保它扩展了 **expo/metro-config**，如下所示：
```js metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname, {
  // 其他功能...
});
module.exports = config;
```
您还可以了解更多关于 [自定义 Metro](/guides/customizing-metro/) 的信息。
Step 3: 
确保 Fast Refresh 已配置。Expo Router 至少需要 `react-refresh@0.14.0`。确保您在 **package.json** 中 **不** 有任何对 `react-refresh` 的覆盖或解析。
Step 4: 
启动开发服务器：
```sh
$ npx expo start
```
## 生产
要为生产打包您的静态网站，请运行通用导出命令：
```sh
$ npx expo export --platform web
```
这将创建一个包含您静态渲染网站的 **dist** 目录。如果您的本地 **public** 目录中有文件，这些也会被复制过来。
您可以通过运行以下命令并在浏览器中打开链接的 URL 来本地测试生产构建：
```sh
$ npx serve dist
```
此项目几乎可以部署到任何托管服务。请注意，这不是一个单页面应用程序，也不包含自定义服务器 API。这意味着动态路由 (**app/[id].tsx**) 不一定能正常工作。您可能需要构建无服务器功能来处理动态路由。
## 动态路由
`static` 输出将为每个路由生成 HTML 文件。这意味着动态路由 (**app/[id].tsx**) 将无法开箱即用。您可以使用 `generateStaticParams` 函数提前生成已知路由。
```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();
  // 返回一个用于生成静态 HTML 文件的参数数组。
  // 数组中的每个条目将是一个新页面。
  return posts.map(post => ({ id: post.id }));
}
export default function Page() {
  const { id } = useLocalSearchParams();
  return <Text>Post {id}</Text>;
}
```
这将在 **dist** 目录中为每个帖子输出一个文件。例如，如果 `generateStaticParams` 方法返回 `[{ id: "alpha" }, { id: "beta" }]`，则会生成以下文件：
```
dist/
    └── blog/
        ├── alpha.html
        └── beta.html
```
#### generateStaticParams
一个仅在构建时在 Node.js 环境中评估的服务器函数，由 Expo CLI 提供。这意味着它可以访问 `__dirname`、`process.cwd()`、`process.env` 等等。它还可以访问过程中的每个环境变量。然而，带有前缀 `EXPO_PUBLIC_.generateStaticParams` 的值不会在浏览器环境中运行，因此无法访问浏览器 API，如 `localStorage` 或 `document`。它也无法访问本机 Expo API，如 `expo-camera` 或 `expo-location`。
```tsx app/[id].tsx
export async function generateStaticParams(): Promise<Record<string, string>[]> {
  console.log(process.cwd());
  return [];
}
```
`generateStaticParams` 从嵌套父级向下流向子级。级联参数将传递给每个导出 **generateStaticParams** 的动态子路由。
```tsx app/[id]/_layout.tsx
export async function generateStaticParams(): Promise<Record<string, string>[]> {
  return [{ id: 'one' }, { id: 'two' }];
}
```
现在动态子路由将被调用两次，一次使用 `{ id: 'one' }`，一次使用 `{ id: 'two' }`。所有变体都必须被考虑。
```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,
  }));
}
```
### 使用 `process.cwd()` 读取文件
由于 Expo Router 将您的代码编译到一个单独的目录，您无法使用 `__dirname` 来形成路径，因为其值将与预期不同。
相反，使用 `process.cwd()`，它会给您提供项目正在编译的目录。
```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,
  };
}
```
## 根 HTML
默认情况下，每个页面都用一些小的 HTML 样板包裹，这被称为 **根 HTML**。
您可以通过在项目中创建一个 **app/+html.tsx** 文件来定制根 HTML 文件。该文件导出一个仅在 Node.js 中运行的 React 组件，这意味着无法在其中导入全局 CSS。该组件将包裹 **app** 目录中的所有路由。这对于添加全局 `<head>` 元素或禁用页面滚动非常有用。
> **注意**: 全局上下文提供程序应放在 [根布局](/router/basics/layout/#root-layout) 组件中，而不是根 HTML 组件中。
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import { type PropsWithChildren } from 'react';
// 此文件仅用于 web，配置每个网页的根 HTML。
// 此函数的内容仅在 Node.js 环境中运行，
// 并且无法访问 DOM 或浏览器 API。
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" />
        {/*
          禁用网页上的主体滚动。这使得 ScrollView 组件的工作方式更接近原生。
          然而，对于移动网页，主体滚动通常是很好的。如果您希望启用它，请删除这一行。
        */}
        <ScrollViewStyleReset />
        {/* 添加任何想在网页上全局可用的额外 <head> 元素... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
```
- `children` prop 包含根 `<div id="root" />` 标签。
- JavaScript 脚本在静态渲染后追加。
- React Native web 样式会自动静态注入。
- 不应将全局 CSS 导入到此文件中。相反，应使用 [根布局](/router/basics/layout/#root-layout) 组件。
- 像 `window.location` 这样的浏览器 API 在此组件中不可用，因为它仅在 Node.js 中的静态渲染期间运行。
### `expo-router/html`
来自 `expo-router/html` 的导出与根 HTML 组件相关。
- `ScrollViewStyleReset`: 用于全屏 [React Native web 应用程序](https://necolas.github.io/react-native-web/docs/setup/#root-element) 的根样式重置，使用以下样式以确保与原生的兼容性。
## 元标签
您可以使用来自 `expo-router` 的 `<Head />` 模块向您的页面添加元标签：
```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>
    </>
  );
}
```
头部元素可以使用相同的 API 动态更新。然而，提前渲染静态头部元素对于 SEO 是有用的。
## 静态文件
Expo CLI 支持一个根 **public** 目录，该目录在静态渲染期间会被复制到 **dist** 目录。这在添加静态文件如图像、字体和其他资产时非常有用。
```
public/
    ├── favicon.ico
    ├── logo.png
    └── .well-known/
        └── apple-app-site-association
```
这些文件将在静态渲染期间被复制到 **dist** 目录：
```
dist/
    ├── index.html
    ├── favicon.ico
    ├── logo.png
    ├── .well-known/
    │   └── apple-app-site-association
    └── _expo/
        └── static/
            ├── js/
            │   └── index-xxx.js
            └── css/
                └── index-xxx.css
```
> **info** **仅限网页**: 静态资产可以在运行时代码中使用相对路径访问。例如，**logo.png** 可以在 `/logo.png` 访问：
```tsx app/index.tsx
import { Image } from 'react-native';
export default function Page() {
  return <Image source={{ uri: '/logo.png' }} />;
}
```
## 字体
Expo Font 对 Expo Router 中的字体加载具有自动静态优化。当您使用 `expo-font` 加载字体时，Expo CLI 将自动提取字体资源并将其嵌入页面的 HTML 中，从而实现预加载、加快水合速度并减少布局位移。
以下代码片段将把 Inter 加载到命名空间中并在网页上进行静态优化：
```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>;
}
```
这将生成以下静态 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>
```
- 静态字体优化要求字体以同步方式加载。如果字体未被静态优化，可能是因为它在 `useEffect`、延迟组件或异步函数内部加载。
- 静态优化仅支持 `Font.loadAsync` 和 `Font.useFonts` 来自 `expo-font`。包装函数是被支持，只要包装器是同步的。
## 常见问题
### 如何添加自定义服务器？
没有单一的方式来添加自定义服务器。您可以使用任何服务器。然而，您需要自行处理动态路由。您可以使用 `generateStaticParams` 函数为已知路由生成静态 HTML 文件。
将来，会有一个服务器 API，以及一个新的 `web.output` 模式，这将生成一个项目，其中（除了其他事情）支持动态路由。
## 服务器端渲染
在请求时渲染（SSR）在 `web.output: 'static'` 中不支持。这可能会在将来的 Expo Router 版本中添加。
### 我可以将静态渲染的网站部署到哪里？
您可以将静态渲染的网站部署到任何静态托管服务。以下是一些流行的选项：
- [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 文件的集合。


## 异步路由

学习如何通过 Expo Router 中的异步打包加快开发速度。

> **important** 异步路由是一个实验性功能。
<ContentSpotlight file="expo-router/async-routes.mp4" loop={false} />
Expo Router 可以基于路由文件自动拆分你的 JavaScript 包，使用 [React Suspense](https://react.dev/reference/react/Suspense)。这使得开发更快，因为只有你导航到的路由会被打包或加载到内存中。这对于减少应用程序的初始包大小也很有用。
使用 Hermes Engine 的应用程序在包拆分方面的受益不大，因为字节码已经提前在内存中映射。不过，它会改善你的空中更新、React 服务器组件和网络支持。
> 在 **原生平台** 上进行生产打包时，所有 suspense 边界 **将被禁用**，并且将没有加载状态。
## 工作原理
所有路由都包装在一个 suspense 边界内并异步加载。这意味着第一次导航到一个路由时，加载时间会稍长。但是，一旦加载，它会被缓存，后续访问将是瞬时的。
{/* [Suspense fallback](https://react.dev/reference/react/Suspense#displaying-a-fallback-while-content-is-loading) 或加载状态 **目前无法自定义**。我们计划未来通过 **route+loading.js** 文件添加支持。 */}
加载错误在父路由中处理，通过 [`ErrorBoundary`](/router/error-handling/#errorboundary) 导出。
在开发过程中，异步路由无法静态分析，因此所有文件将被视为路由，即使它们不导出默认组件。组件打包并加载后，任何无效路由都将使用回退警告屏幕。
对于熟悉高级打包技术的人来说，异步路由功能由 [React Suspense](https://react.dev/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)（开发中）组成。
## 设置
通过在你的 [app config](/versions/latest/config/app/) 的 Expo Router 配置插件中设置 `asyncRoutes` 选项来启用此功能：
    > 设置 `asyncRoutes` 为 `true` 以启用生产包拆分。
    ```json app.json
    {
      "expo": {
        "plugins": [
          [
            "expo-router",
            {
              "origin": "https://acme.com",
              "asyncRoutes": {
                "web": true,
                "default": "development"
              }
            }
          ]
        ]
      }
    }
    ```
你可以使用对象为 `asyncRoutes` 设置平台特定的设置（`default`、`android`、`ios` 或 `web`）：
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-router",
        {
          "origin": "https://acme.com",
          "asyncRoutes": {
            "web": true,
            "android": false,
            "default": "development"
          }
        }
      ]
    ]
  }
}
```
然后，当你准备开始项目时，可以使用 `--clear` 标志来清除 Metro 缓存。这将确保路由异步加载：
```sh
$ npx expo start --clear
$ npx expo export --clear
```
## 静态渲染
静态渲染通过在 Node.js 中同步渲染所有 Suspense 边界，在生产 Web 应用中受到支持，然后根据给定 HTML 文件所选路由将所有异步块链接在一起。这确保你在服务器导航时不会遇到加载状态的瀑布流。后续导航将递归加载任何缺失的块。
为确保一致的首次渲染，所有指向 URL 的叶路由的布局路由将包含在初始服务器响应中。
所有初始路由，使用 `unstable_settings = { initialRouteName: '...' }` 定义，将包含在初始 HTML 文件中，因为它们是首次渲染所需的。例如，如果服务器请求的是一个模态，模态下渲染的屏幕也将包含在内，以确保模态正确渲染。
## 注意事项
异步路由代表了我们未来计划如何支持 [React 服务器组件](https://react.dev/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023#react-server-components) 的早期预览。因此，有一些注意事项需要了解：
- 异步路由尚不支持原生生产应用。
- 在开发中，运行时 JavaScript 是懒加载打包的，因此你可能会遇到 HTML 与可用 JavaScript 不匹配的情况。
- 此时加载状态无法自定义。


## API 路由

学习如何使用 Expo Router 创建服务器端点。

Expo Router 使您能够在您的 **app** 目录中为所有平台编写安全的服务器代码。
```ts app/hello+api.ts
export function GET(request: Request) {
  return Response.json({ hello: 'world' });
}
```
服务器功能需要一个自定义服务器，您可以将其部署到 EAS 或大多数 [其他托管服务提供商](#deployment)。
Video Tutorial: [观看：Expo Router API 路由处理请求和流数据](https://www.youtube.com/watch?v=2_UzR1wdimI)
## 什么是 API 路由
API 路由是在匹配路由时在服务器上执行的函数。它们可以用于安全处理敏感数据，例如 API 密钥，或实现自定义服务器逻辑，例如交换认证码以获取访问令牌。API 路由应在 [WinterCG](https://wintercg.org/)-合规环境中执行。
在 Expo 中，API 路由是通过在 **app** 目录中创建带有 `+api.ts` 扩展名的文件来定义的。例如，以下 API 路由在匹配 `/hello` 路由时执行。
```
app/
    ├── index.tsx
    └── hello+api.ts  # API Route
```
## 创建 API 路由
Step 1: 
确保您的项目使用服务器输出，这将配置导出和生产构建以生成服务器捆绑包以及客户端捆绑包。
```json app.json
{
  "web": {
    "output": "server"
  }
}
```
Step 2: 
在 **app** 目录中创建一个 API 路由。例如，添加以下路由处理程序。它是在匹配 `/hello` 路由时执行的。
```ts app/hello+api.ts
export function GET(request: Request) {
  return Response.json({ hello: 'world' });
}
```
您可以从服务器路由导出以下函数中的任何一个 `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, 和 `OPTIONS`。该函数在匹配相应的 HTTP 方法时执行。不支持的方法将自动返回 `405: Method not allowed`。
Step 3: 
使用 Expo CLI 启动开发服务器：
```sh
$ npx expo
```
Step 4: 
您可以对路由发出网络请求以访问数据。运行以下命令测试路由：
```sh
$ curl http://localhost:8081/hello
```
您还可以从客户端代码中发出请求：
```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" />;
}
```
相对获取请求会自动相对于开发服务器的源进行获取，并且可以使用 **app.json** 中的 `origin` 字段在生产环境中进行配置：
```json app.json
{
  "plugins": [
    [
      "expo-router",
      {
        "origin": "https://evanbacon.dev/"
      }
    ]
  ]
}
```
通过设置 `EXPO_UNSTABLE_DEPLOY_SERVER=1` 环境变量，可以在 EAS 构建期间自动配置此 URL。这将触发版本化的服务器部署，自动将 origin 设置为预览部署 URL。
Step 5: 
将网站和服务器部署到 [托管服务提供商](#deployment)，以便在生产环境中在原生和网页上访问路由。
> **warning** API 路由文件名不能有特定于平台的扩展名。例如，**hello+api.web.ts** 将无法工作。
## 请求
Requests use the global, standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/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.json()` 函数访问请求体。它会自动解析请求体并返回结果。
```ts app/validate+api.ts
export async function POST(request: Request) {
  const body = await request.json();
  return Response.json({ ... });
}
```
### 请求查询参数
可以通过解析请求 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`](https://fetch.spec.whatwg.org/#response) 对象。
```ts app/demo+api.ts
export function GET() {
  return Response.json({ hello: 'universe' });
}
```
## 错误
对于错误情况，您可以创建具有任何状态码和响应体的 `Response`。
```ts app/blog/[post]+api.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`.
## Runtime API
> **important** The server runtime API and `expo-server` are available in SDK 54 and later and require a deployed server for production use.
You can use the [`expo-server`](/versions/latest/sdk/server/) library to use several utilities and code patterns that work in any server-side Expo code. This includes utilities to get request metadata, for scheduling tasks, and for error handling.
```sh
$ npx expo install expo-server
```
Using `expo-server` is not limited to API routes and it can be used in any other server code as well, for example, in [server middleware](/router/reference/middleware/).
### Error handling
You can abort a request and instead return an error `Response` by throwing a [`StatusError`](/versions/latest/sdk/server/#statuserror). This is a special `Error` instance that will be replaced with an HTTP response replacing the error itself.
```ts app/blog/[post]+api.ts
import { StatusError } from 'expo-server';
export async function GET(request: Request, { post }: Record<string, string>) {
  if (!post) {
    throw new StatusError(404, 'No post found');
  }
  // ...
}
```
When composing your own server utilities and helpers, the `StatusError` is a more convenient way to handle exceptions, since throwing them interrupts any API functions and returns an error early.
`StatusError`s accept a status code and an error message, which can also optionally be passed as a JSON, or `Error` object, and will always return a `Response` with a JSON body with an `error` key set to their error message.
This can be restrictive, and isn't suitable for all cases. Sometimes it might be beneficial to instead `throw` a `Response` object, which interrupts your logic as well, but replaces the resolved `Response` from your API route directly, without a `StatusError` wrapper. For example, this can be used to create redirect responses.
```ts app/blog/[post]+api.ts
import { StatusError } from 'expo-server';
export async function GET(request: Request, { post }: Record<string, string>) {
  if (!post) {
    throw Response.redirect('https://expo.dev', 302);
  }
  // ...
}
```
### Request metadata
Requests typically carry most metadata you'll need in their headers. However, `expo-server` provides some helper functions to retrieve common values more easily.
Helper functions from `expo-server` return values that are scoped to the current `Request`. You can only call these functions in server-side code and only during ongoing requests.
A common value that you may need to access is the request's origin URL. The origin URL, typically transmitted on a request's `Origin` header, represents the URL that a user used to access your API route. This may differ from any internal deployment URL that your server sees when the request is being proxied. You can use `expo-server`'s [`origin()`](/versions/latest/sdk/server/#origin) helper method to access this value.
```ts app/help+api.ts
import { origin } from 'expo-server';
export async function GET(request: Request) {
  const target = new URL('/help', origin() ?? request.url);
  return Response.redirect('https://expo.dev', 302);
}
```
Most runtimes that you deploy your server code to have a concept of environments, to differentiate between production or staging deployments. You can use `expo-server`'s [`environment()`](/versions/latest/sdk/server/#environment) helper to get an environment name. This value will differ depending on how you're running your server code.
```ts app/env+api.ts
import { environment } from 'expo-server';
export async function GET(request: Request) {
  const env = environment();
  if (env === 'staging') {
    return Response.json({ isStaging: true });
  } else if (!env) {
    return Response.json({ isProduction: true });
  } else {
    return Response.json({ env });
  }
}
```
### Task scheduling
In your request handlers, you may need to run asynchronous tasks in parallel to your server logic.
```ts app/tasks+api.ts
export async function GET(request: Request) {
  // This will delay the response:
  await pingAnalytics(...);
  const data = await fetchExampleData(...);
  return Response.json({ data });
}
```
In the above example, an `await`-ed function call delays the rest of the API route's execution. If we don't want to delay a `Response`, then `await`-ing this call isn't suitable. However, calling the function without `await` wouldn't guarantee that this task keeps a serverless function running.
Instead, you can use `expo-server`'s [`runTask()`](/versions/latest/sdk/server/#runtaskfn) helper function to run concurrent tasks. This is equivalent to the [`waitUntil()`](https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent/waitUntil) method that you see in service worker code or other serverless runtimes.
```ts app/tasks+api.ts
import { runTask } from 'expo-server';
export async function GET(request: Request) {
  // This will NOT delay the response:
  runTask(async () => {
    await pingAnalytics(...);
  });
  const data = await fetchExampleData(...);
  return Response.json({ data });
}
```
With `runTask`, you have a compromise between `await`-ing and not `await`-ing asynchronous functions. They'll be run concurrently, and don't delay the API route's response or execution, but are also making sure the runtime is aware of them, and don't quit early.
However, sometimes you may want to delay a task until after the API route has returned a `Response`. In such cases, you might prefer not to execute the task if the API has rejected it. Additionally, you may want to run a function only after a time-sensitive task has been completed to prevent concurrent code from delaying computation-heavy tasks in your API route.
You can use `expo-server`'s [`deferTask()`](/versions/latest/sdk/server/#defertaskfn) helper function to schedule tasks to run after a `Response` has been resolved by your API route.
```ts app/tasks+api.ts
import { deferTask } from 'expo-server';
export async function GET(request: Request) {
  // This will run after this entire function resolves:
  deferTask(async () => {
    await pingAnalytics(...);
  });
  const data = await fetchExampleData(...);
  return Response.json({ data });
}
```
### Response headers
When structuring and splitting server logic into separate helper functions and files, it may be necessary to modify `Response` headers before a `Response` has been created.
For example, you may need to add metadata in [server middleware](/router/reference/middleware/) to a `Response` before your API route code is running.
```ts app/+middleware.ts
import { setResponseHeaders } from 'expo-server';
export default function middleware(request: Request) {
  // Rate limiters typically add a `Retry-After` header
  setResponseHeaders({ 'Retry-After': '3600' });
}
```
In the above example, a `Retry-After` header is added to a future `Response` that an API route may be creating. This can also be extended for authentication and cookies.
```ts app/+middleware.ts
import { setResponseHeaders } from 'expo-server';
export default function middleware(request: Request) {
  // Append cookie to future response
  setResponseHeaders(headers => {
    headers.append('Set-Cookie', 'token=123; Secure');
  });
}
```
## 打包
API 路由与 Expo CLI 和 [Metro bundler](/guides/customizing-metro) 一起打包。它们可以访问与您的客户端代码相同的所有语言特性：
- [TypeScript](/guides/typescript) &mdash; 类型和 [**tsconfig.json** 路径](/guides/typescript/#path-aliases-optional)。
- [环境变量](/guides/environment-variables) &mdash; 服务器路由可以访问所有环境变量，而不仅仅是以 `EXPO_PUBLIC_` 前缀的变量。
- Node.js 标准库 &mdash; 确保您在本地的服务器环境中使用正确版本的 Node.js。
- **babel.config.js** 和 **metro.config.js** 支持 &mdash; 设置在客户端和服务器代码中均有效。
## 安全性
路由处理程序在与客户端代码隔离的沙箱环境中执行。这意味着您可以安全地在路由处理程序中存储敏感数据，而无需将其暴露给客户端。
- 导入具有秘密的代码的客户端代码将包含在客户端捆绑包中。它适用于 **app 目录** 中的 **所有文件**，即使它们不是路由处理程序文件（例如带有 **+api.ts** 后缀的文件）。
- 如果秘密在 **&lt;...&gt;+api.ts** 文件中，它将不包含在客户端捆绑包中。这适用于路由处理程序中导入的所有文件。
- 秘密剥离发生在 `expo/metro-config` 中，并要求在 **metro.config.js** 中使用它。
## 部署
当您准备好部署到生产环境时，运行以下命令以在 **dist** 目录中创建服务器捆绑包（有关更多详细信息，请参见 [Expo CLI 文档](/more/expo-cli#exporting)）：
```sh
$ npx expo export --platform web
```
此服务器可以通过 `npx expo serve` （在 Expo SDK 52 及更高版本可用）进行本地测试，在网页浏览器中访问该 URL，或者使用 `origin` 设置为本地服务器 URL 创建本地构建。
您可以使用 [EAS Hosting](/eas/hosting/get-started) 或其他第三方服务将服务器部署到生产。
如果您想导出 API 路由并跳过生成应用程序的网站版本，可以使用以下命令，这将生成一个只包含您项目服务器代码的 **dist** 目录。
```sh
$ npx expo export --platform web --no-ssg
```
### 原生部署
> **important** 这是从 SDK 52 及更高版本开始的实验性功能。该过程将在未来的版本中更加自动化，并提供更好的支持。
Expo Router 中的服务器功能（API 路由和 React 服务器组件）集中在 `window.location` 和 `fetch` 的原生实现上，这些实现指向远程服务器。在开发中，我们自动指向使用 `npx expo start` 运行的开发服务器，但为了使原生构建在生产中工作，您需要将服务器部署到安全的主机，并设置 Expo Router 配置插件的 `origin` 属性。
配置后，像相对获取请求 `fetch('/my-endpoint')` 将自动指向服务器源。
这个部署过程可以实验性地自动化，以确保在原生构建期间的正确版本控制，方法是使用 `EXPO_UNSTABLE_DEPLOY_SERVER=1` 环境变量。
以下是如何配置您的原生应用以在构建时自动部署并链接一个版本化的生产服务器：
Step 1: 
确保 **app.json** 中的 `origin` 字段 **未** 设置，或者未在 `expo.extra.router.origin` 字段中设置。此外，确保不使用 **app.config.js**，因为这尚不支持自动链接的部署。
Step 2: 
通过先在本地部署一次来为项目设置 [EAS Hosting](/eas/hosting/get-started)。
```sh
$ npx expo export -p web
$ eas deploy
```
Step 3: 
在您的 `.env` 文件中设置 `EXPO_UNSTABLE_DEPLOY_SERVER` 环境变量。这将用于在 EAS Build 期间启用实验性服务器部署功能。
```sh .env
EXPO_UNSTABLE_DEPLOY_SERVER=1
```
Step 4: 
您现在准备使用自动服务器部署！运行构建命令以启动该过程。
```sh
$ eas build
```
您还可以使用以下命令在本地运行：
```sh
$ npx expo run:android --variant release
$ npx expo run:ios --configuration Release
```
关于原生应用自动服务器部署的备注：
- 如果某些设置不正确，可能会在 EAS Build 的 `Bundle JavaScript` 阶段发生服务器故障。
- 如果愿意，您可以在构建应用之前手动部署服务器并设置 `origin` URL。
- 可通过设置环境变量 `EXPO_NO_DEPLOY=1` 强制跳过自动部署。
- 自动部署尚不支持 [动态应用配置](/workflow/configuration/#dynamic-configuration)（**app.config.js** 和 **app.config.ts**）文件。
- 部署日志将写入 `.expo/logs/deploy.log`。
- 在 `EXPO_OFFLINE` 模式下不会运行部署。
### 在本地测试原生生产应用
在本地开发服务器上测试生产构建通常非常有用，以确保一切按预期工作。这可以显著加快调试过程。
Step 1: 
导出生产服务器：
```sh
$ npx expo export
```
Step 2: 
在本地托管生产服务器：
```sh
$ npx expo serve
```
Step 3: 
在 **app.json** 的 `origin` 字段中设置 origin。确保 `expo.extra.router.origin` 中没有生成的值。它应该是 `http://localhost:8081`（假设 `npx expo serve` 在默认端口上运行）。
```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-router",
        {
          "origin": "http://localhost:8081"
        }
      ]
    ]
  }
}
```
记得在生产部署时删除此 `origin` 值。
Step 4: 
在模拟器上以发布模式构建应用：
```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** The `expo-server` library was added in SDK 54. Use `@expo/server` for older SDKs instead.
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 a server-side runtime for exported Expo web and API route artifacts.
- `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.
The `expo-server` library contains adapters for various providers and runtimes. Before proceeding with any of the below sections, install the `expo-server` library.
```sh
$ npx expo install expo-server
```
### Bun
Step 1: 
导出网站以供生产：
```sh
$ bunx expo export -p web
```
Step 2: 
编写一个服务器入口文件，以提供静态文件并将请求委托给服务器路由：
```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: 
使用 `bun` 启动服务器：
```sh
$ bun run server.ts
```
### Express
Step 1: 
安装所需的依赖项：
```sh
$ npm i -D express compression morgan
```
Step 2: 
导出网站以供生产：
```sh
$ npx expo export -p web
```
Step 3: 
编写一个服务器入口文件，以提供静态文件并将请求委托给服务器路由：
```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://expressjs.com/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: 
使用 `node` 命令启动服务器：
```sh
$ node server.ts
```
### Netlify
> **important** Third-party adapters are subject to breaking changes. We have no continuous tests against them.
Step 1: 
创建一个服务器入口文件。所有请求将通过此中间件委托。确切的文件位置很重要。
```ts netlify/functions/server.ts
import path from 'node:path';
import { createRequestHandler } from 'expo-server/adapter/netlify';
export default createRequestHandler({
  build: path.join(__dirname, '../../dist/server'),
});
```
Step 2: 
在项目根目录中创建一个 Netlify 配置文件，以将所有请求重定向到服务器函数。
```yaml netlify.toml
[build]
  command = "expo export -p web"
  functions = "netlify/functions"
  publish = "dist/client"
[[redirects]]
  from = "/*"
  to = "/.netlify/functions/server"
  status = 404
[functions]
  # 包含所有内容，以确保可以使用动态路由。
  included_files = ["dist/server/**/*"]
[[headers]]
  for = "/dist/server/_expo/functions/*"
  [headers.values]
    # 将其设置为60秒作为示例。
    "Cache-Control" = "public, max-age=60, s-maxage=60"
```
Step 3: 
创建配置文件后，您可以使用 Expo CLI 构建网站和功能：
```sh
$ npx expo export -p web
```
Step 4: 
使用 [Netlify CLI](https://docs.netlify.com/cli/get-started/) 部署到 Netlify。
```sh
$ npm install netlify-cli -g
$ netlify deploy
```
您现在可以通过 Netlify CLI 提供的 URL 访问您的网站。运行 `netlify deploy --prod` 将发布到生产 URL。
Step 5: 
如果您使用任何环境变量或 **.env** 文件，请将它们添加到 Netlify。您可以通过访问 **站点设置** 并将它们添加到 **构建与部署** 部分来做到这一点。
### Vercel
> **important** Third-party adapters are subject to breaking changes. We have no continuous tests against them.
Step 1: 
创建一个服务器入口文件。所有请求将通过此中间件委托。确切的文件位置很重要。
```ts api/index.ts
const { createRequestHandler } = require('expo-server/adapter/vercel');
module.exports = createRequestHandler({
  build: require('path').join(__dirname, '../dist/server'),
});
```
Step 2: 
在项目根目录中创建一个 Vercel 配置文件 (**vercel.json**) 以将所有请求重定向到服务器函数。
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"
    }
  ]
}
```
新版本的 **vercel.json** 不再使用 `routes` 和 `builds` 配置选项，并自动从 **dist/client** 输出目录提供您的公共资产。
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"
    }
  ]
}
```
**旧版** 的 **vercel.json** 需要一个 `@vercel/static-build` 运行时，从 **dist/client** 输出目录提供您的资产。
Step 3: 
> **注意：** 此步骤仅适用于 **旧版** 的 **vercel.json** 用户。如果您使用的是 v3，可以跳过此步骤。
创建配置文件后，在您的 **package.json** 文件中添加一个 `vercel-build` 脚本，并将其设置为 `expo export -p web`。
Step 4: 
使用 [Vercel CLI](https://vercel.com/docs/cli) 部署到 Vercel。
```sh
$ npm install vercel -g
$ vercel build
$ vercel deploy --prebuilt
```
您现在可以通过 Vercel CLI 提供的 URL 访问您的网站。
## 已知限制
API 路由测试版中当前不支持几个已知功能。
### 不支持动态导入
API 路由当前通过将所有代码（减去 Node.js 内置的）捆绑到一个文件中来工作。这意味着您无法使用未与服务器捆绑在一起的任何外部依赖项。例如， `sharp` 这样的库，包含多个平台二进制文件，无法使用。这将在未来版本中得到解决。
### 不支持 ESM
当前的捆绑实现选择更统一而不是灵活。这意味着原生不支持 ESM 的限制被应用于 API 路由。所有代码将被转译为 Common JS（`require`/`module.exports`）。但是，我们建议您尽管如此还使用 ESM 编写 API 路由。这将在未来版本中得到解决。


## Sitemap

学习如何使用 Sitemap 来调试你的应用程序与 Expo Router。

在本地，你可以使用 [`uri-scheme`](https://www.npmjs.com/package/uri-scheme) CLI 在设备上测试打开本地链接。
例如，如果你想在 iOS 上启动 Expo Go 应用程序并访问 `/form-sheet` 路由，请运行：
```sh
$ npx uri-scheme open exp://192.168.87.39:19000/--/form-sheet --ios
```
> 使用 `192.168.87.39:19000` 替换在运行 `npx expo start` 时显示的 IP 地址。
你也可以直接在 Safari 或 Chrome 等浏览器中搜索链接来测试物理设备上的深度链接。了解更多关于 [测试深度链接](https://reactnavigation.org/docs/deep-linking)。
## Sitemap
Expo Router 目前会自动注入一个 **/\_sitemap**，提供应用程序中所有路由的列表。这对调试非常有用。
可以通过在应用配置中的 `expo-router` 配置插件中添加 `sitemap: false` 来移除网站地图：
```json app.json
{
  "plugins": [
    [
      "expo-router",
      {
        "sitemap": false
      }
    ]
  ]
}
```


## 链接预览

学习如何在使用 Expo Router 时，在 iOS 上为链接添加预览。

> **important** 链接预览是仅适用于 iOS 的功能，仅在 SDK 54 及更高版本中可用。
链接预览（也称为“窥视和弹出”）是 iOS 上常用的功能，用于向用户显示链接屏幕的预览弹出窗口。
本指南将向您展示如何为您的 iOS 应用添加和自定义链接预览。
如果您的应用中有链接，您可以通过用 [`Link.Trigger`](/versions/latest/sdk/router/#linktrigger) 替换链接的内容，并添加 [`Link.Preview`](/versions/latest/sdk/router/#linkpreview) 组件来为其添加链接预览。这将创建一个链接指向页面的预览。
```tsx
import { Link } from 'expo-router';
export default function Page() {
  return (
    <Link href="/about">
      <Link.Trigger>About</Link.Trigger>
      <Link.Preview />
    </Link>
  );
}
```
## 自定义链接预览
默认情况下，链接预览呈现为全尺寸页面快照。有几种方法可以自定义此行为。
### 自定义大小
您可以使用 `width` 和 `height` 来建议首选的预览大小。系统将考虑这些首选项，但可能会根据可用空间或平台行为进行覆盖。
```tsx
<Link href="...">
  <Link.Trigger>Content</Link.Trigger>
  <Link.Preview style={{ width: 300, height: 200 }} />
</Link>
```
以下示例展示了在 iOS 上自定义链接预览大小：
### 自定义预览
如果您不想显示默认预览，可以通过 children 向 `Link.Preview` 组件传递自定义内容。这些自定义内容将替代链接目标的默认预览。
```tsx
export default function Page() {
  const [imageSize, setImageSize] = useState({ width: 0, height: 0 });
  const { width } = useWindowDimensions();
  const previewHeight = (width / imageSize.width) * imageSize.height;
  return (
    <Link href="/about">
      <Link.Trigger>About</Link.Trigger>
      <Link.Trigger>Content</Link.Trigger>
      <Link.Preview style={{ width, height: previewHeight }}>
        <Image
          onLoad={e => setImageSize(e.nativeEvent.source)}
          source={source}
          style={{ width: '100%', height: '100%' }}
        />
      </Link.Preview>
    </Link>
  );
}
```
以下示例展示了在 iOS 上的自定义链接预览：
## 菜单
要在预览旁边渲染上下文菜单，请添加一个 [`Link.Menu`](/versions/latest/sdk/router/#linkmenu) 和 [`Link.MenuAction`](/versions/latest/sdk/router/#linkmenuaction) children。
```tsx
<Link href="/about">
  <Link.Trigger>About</Link.Trigger>
  <Link.Menu>
    <Link.MenuAction title="Share" icon="square.and.arrow.up" onPress={handleSharePress} />
    <Link.MenuAction title="Block" icon="nosign" destructive onPress={handleBlockPress} />
  </Link.Menu>
</Link>
```
以下示例展示了在 iOS 上的自定义链接预览：
### 图标
您可以为每个菜单操作指定一个图标，使用 [SF Symbols](https://developer.apple.com/sf-symbols/)。
```tsx
<Link href="/about">
  <Link.Trigger>About</Link.Trigger>
  <Link.Menu>
    <Link.MenuAction title="Share" icon="square.and.arrow.up" onPress={handleSharePress} />
    <Link.MenuAction title="Block" icon="nosign" onPress={handleBlockPress} />
    <Link.MenuAction
      title="Follow"
      icon="person.crop.circle.badge.plus"
      onPress={handleFollowPress}
    />
    <Link.MenuAction title="Copy" icon="doc.on.doc" onPress={handleCopyPress} />
  </Link.Menu>
</Link>
```
以下示例展示了具有四个元素的上下文菜单，每个元素使用不同的图标在 iOS 上：
### 嵌套菜单
您可以通过将一个 [`Link.Menu`](/versions/latest/sdk/router/#linkmenu) 放置在另一个菜单内来嵌套菜单：
```jsx
<Link href="...">
  <Link.Trigger>About</Link.Trigger>
  <Link.Menu>
    <Link.MenuAction title="Share" icon="square.and.arrow.up" onPress={() => {}} />
    <Link.Menu title="More" icon="ellipsis">
      <Link.MenuAction title="Copy" icon="doc.on.doc" onPress={() => {}} />
      <Link.MenuAction title="Delete" icon="trash" destructive onPress={() => {}} />
    </Link.Menu>
  </Link.Menu>
</Link>
```
以下示例展示了在 iOS 上的嵌套上下文菜单：
### 更多自定义选项
要查看更多可用的自定义选项，请参阅 [`Link.MenuAction`](/versions/latest/sdk/router/#linkmenuaction) 的 API 文档。
## 检测组件是否在预览中
如果您正在构建一个可能在预览中呈现的组件，您可以使用 [`useIsPreview()`](/versions/latest/sdk/router/#useispreview) hook 来相应调整其行为：
```jsx
function MyComponent() {
  // 如果组件/屏幕在预览中被渲染，则为 true
  const isInsidePreview = useIsPreview();
  return isInsidePreview ? <Text>From within preview</Text> : <Text>I am outside of preview</Text>;
}
```
## 已知限制
### 不支持 `replace`
使用链接预览与 [`replace`](/versions/latest/sdk/router/#replace) 模式当前 **不支持**。预览只能与默认 [`push`](/versions/latest/sdk/router/#push) 导航模式一起使用。
### JavaScript 标签和插槽
在 JavaScript 标签（而非原生标签）或 [`Slot`](/versions/latest/sdk/router/#slot) 中进行导航时，预览过渡动画可能会显得不够流畅。这是由于 React 的渲染延迟，而原生预览动画会立即开始。为避免此问题，请使用原生标签和堆栈导航器。
### 缺失 `Link.Trigger`
如果您渲染一个具有预览或上下文菜单的 `Link`，但没有 `Link.Trigger`，将抛出异常。如果在使用预览模式时，将任何非 `Link.*` 组件直接放置在 `Link` 内部，也会出现相同的情况。
### 多个带 `asChild` 属性的 `Link.Trigger` children
使用带 `asChild` 的 `Link` 时，您只能为 `Link.Trigger` 指定 **一个** child。`onPress` 事件将仅转发给那个 child。
### 在预览打开时更改 href
在预览打开时动态更改 `href` prop 的路径 **不支持**。您只能动态修改查询参数。


## 类型化路由

学习如何在 Expo Router 中使用静态类型链接和路由。

> 在项目中使用 TypeScript 时可用。Expo Router 支持标准 TypeScript 开箱即用。有关如何设置的更多信息，请参见 [TypeScript](/guides/typescript/) 指南。
Expo Router 支持通过 Expo CLI 自动生成 TypeScript 类型。这使得 `<Link>` 和 [hooks API](/router/reference/hooks) 能够静态类型化。此功能目前处于 beta 状态，默认情况下未启用。
## 开始
### 快速开始
如果您按照 [Expo Router 快速开始指南](/router/installation/#quick-start) 创建了项目，则您的项目已配置为使用类型化路由。Expo CLI 将在您第一次运行 `npx expo start` 时生成所需的类型文件。然后，每当您在 **.tsx** 文件中使用 Expo Router 的 `<Link>` 组件时，可以使用 `href` 属性的自动完成功能。
### 手动配置
在该功能处于 beta 状态时，您可以通过在 **app.json** 中将 `experiments.typedRoutes` 设置为 `true` 来启用它：
```json app.json
{
  "expo": {
    "experiments": {
      "typedRoutes": true
    }
  }
}
```
运行 `npx expo customize tsconfig.json` 来配置您的 **tsconfig.json** 以添加所需的 `includes` 字段。
然后，通过运行 `npx expo start` 启动开发服务器。现在，您可以在 Expo Router `<Link>` 组件的 `href` 属性中使用自动完成。
## 类型生成
在 Expo Router 中，当开发服务器启动时，类型化路由将自动生成。默认情况下，这些生成的类型配置为被 Git 忽略，并将添加到本地 **.gitignore** 文件中。这确保了自动生成的文件不会混乱您的版本控制系统。
如果您发现自己需要在不启动开发服务器的情况下生成这些类型，例如在连续集成（CI）服务器上进行类型检查。为此，在 CI 上运行命令 `npx expo customize tsconfig.json`。
## 静态类型化路由
使用 `Href<T>` 的组件和函数现在将被静态类型化，并具有更严格的定义。例如：
```tsx
✅ <Link href="/about" />
✅ <Link href="/user/1" />
✅ <Link href={`/user/${id}`} />
✅ <Link href={("/user" + id) as Href} />
// 如果 href 不是有效路由，则 TypeScript 会报错
❌ <Link href="/usser/1" />
```
> **注意**: `expo-router` 还提供了一个 [`Route` 类型](/versions/latest/sdk/router/#route)，它会自动匹配项目中的所有有效路由。
对于动态路由，Href 需要为对象，其参数被严格类型化：
```tsx
✅ <Link href={{ pathname: "/user/[id]", params: { id: 1 }}} />
// TypeScript 错误，因为 href 有效，但它应该是带有参数的 HrefObject
❌ <Link href="/user/[id]" />
// TypeScript 错误，因为参数包含无效键
❌ <Link href={{ pathname: "/user/[id]", params: { _id: 1 }}} />
// TypeScript 错误，因为参数包含未知键
❌ <Link href={{ pathname: "/user/[id]", params: { id: 1, id2: 2 }}} />
```
### 相对路径
静态类型化路由不支持相对路径。您需要对所有路由使用绝对路径：
```tsx
✅ <Link href="/about" />
// 不支持相对路径
❌ <Link href="./about" />
```
您可以利用来自 `expo-router` 的 `useSegments()` hooks 来创建复杂的相对路径。考虑以下结构：
```
app/
│   ├── (feed)/
│   │   ├── _layout.tsx
│   │   ├── feed.tsx
│   │   ├── search.tsx
│   │   └── profile.tsx
│   └── (search)/
│       └── profile.tsx
components/
    └── button.tsx
```
您可以确保使用 `useSegments()` hook 获取当前路由的第一个段落，以推送到相同的标签。
```tsx button.tsx
import { Link, useSegments } from 'expo-router';
export function Button() {
  const [
    // 根据当前标签，这将是 `(feed)` 或 `(search)`。
    first,
  ] = useSegments();
  return <Link href={`/${first}/profile`}>Push profile</Link>;
}
```
现在，您可以利用 **app/(feed)/feed.tsx** 和 **app/(search)/search.tsx** 中的 `<Button />` 来推送 `./profile`，同时保留当前标签。
如果您需要特定用途的段落，可以将完整路由传递给 `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;
}
```
## 命令式导航
您可以使用类型化的 `router` 对象进行命令式导航：
```tsx
import { router } from 'expo-router';
router.push('/about');
```
或使用类型化的 `useRouter()` hook：
```tsx
import { useRouter } from 'expo-router';
function Page() {
  const router = useRouter();
  router.push('/about');
  // ...
}
```
## 路由参数
对于强类型的路由参数，您可以将完整的 href 传递给 `useLocalSearchParams` 和 `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>
    </>
  );
}
```
## 查询参数
大多数查询参数不会在文件系统中表示，因此无法自动类型化。您可以通过将泛型传递给 `useLocalSearchParams` 和 `useGlobalSearchParams` hooks 手动类型化查询参数。例如：
```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>;
}
```
如果您需要路由和查询参数的组合，请将路由作为第一个泛型，然后是查询参数
```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>;
}
```
## 环境的变化
当启用类型化路由时，Expo CLI 将在您的项目根目录中生成一个被 git 忽略的 **expo-env.d.ts** 文件，更新 **.gitignore** 以忽略新的根 **expo-env.d.ts** 文件，并修改 **tsconfig.json** 以包含新的 **expo-env.d.ts** 文件。
您 **tsconfig.json** 中的 `includes` 字段会更新以包含 **expo-env.d.ts** 和一个隐藏的 **.expo** 目录。这些条目是必需的，不应从文件中删除。
生成的 **expo-env.d.ts** 绝对不应在任何时候删除或更改。它不应被提交，应被版本控制忽略。
### 全局类型
当启用类型化路由时，Expo CLI 将在您的项目中添加以下全局类型：
- 设置 `process.env.NODE_ENV = "development" | "production" | "test"`
- 允许导入 `.[css|sass|scss]` 文件
- 设置 `*.module.[css|sass|scss]` 的导出为 `Record<string, string>`
- 为 Metro 的 `require.context` 添加类型。这由 `expo/metro-config` 启用，用于静态路由生成。
### React Native Web
启用类型化路由后，Expo CLI 还增强了 `react-native` 类型以支持 React Native Web。以下更改已完成：
- 为 `ViewStyle`、`TextStyle`、`ImageStyle` 添加额外的仅 Web 样式
- 为 `TextProps` 添加 `tabIndex`、`aria-level`、`lang`
- 为 Pressable 的 `children` 和 `style` 状态回调函数添加 `hovered`
- 添加 `className` 元素


## 分析屏幕追踪

学习如何在使用 Expo Router 时启用分析的屏幕追踪。

与 React Navigation 不同，Expo Router 始终可以访问 URL。这意味着屏幕追踪和网页一样简单。
1. 创建一个高阶组件，观察当前选定的 URL
2. 在你的分析提供者中追踪 URL
```
app/
    └── _layout.tsx
```
```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();
  // 在你的分析提供者中追踪位置。
  useEffect(() => {
    analytics.track({ pathname, params });
  }, [pathname, params]);
  // 以最基本的方式导出所有子路由。
  return <Slot />;
}
```
现在，当用户更改路由时，分析提供者将收到通知。
## 从 React Navigation 迁移
React Navigation 的 [屏幕追踪指南](https://reactnavigation.org/docs/screen-tracking/) 不能进行与 Expo Router 相同的导航状态假设。因此，实施需要使用 `onReady` 和 `onStateChange` 回调。如果可能，避免使用这些方法，因为根 `<NavigationContainer />` 并未直接暴露，并允许在 Expo Router 中进行级联。


## 顶级 src 目录

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

随着项目的发展，将所有包含应用程序代码的目录移动到一个单一的 **src** 目录中可能会很有帮助。Expo Router 开箱即用地支持这一点。
```
src/
│   ├── app/
│   │   ├── _layout.tsx
│   │   └── index.tsx
│   └── components/
│       └── button.tsx
package.json
```
只需将您的 **app** 目录移动到 **src/app** 并重启开发服务器。
```sh
$ npx expo start
$ npx expo export
```
**注意**：
- 配置文件（**app.config.ts**，**app.json**，**package.json**，**metro.config.js**，**tsconfig.json**）应保留在根目录中。
- **src/app** 目录的优先级高于根 **app** 目录。如果您同时存在两者，则只会使用 **src/app** 目录。
- **public** 目录应保留在根目录中。
- 静态渲染将自动使用 **src/app** 目录（如果存在）。
- 您可能会考虑更新任何 [类型别名](/guides/typescript#path-aliases) 以指向 **src** 目录，而不是根目录。
## 自定义目录
> **warning** 不推荐更改默认根目录。我们将不接受关于自定义根目录项目的错误报告。
您可以使用 Expo Router 配置插件危险地自定义根目录。以下将根目录更改为相对于项目根目录的 **src/routes**。
```json app.json
{
  "plugins": [
    [
      "expo-router",
      {
        "root": "./src/routes"
      }
    ]
  ]
}
```
这可能会导致意外行为。许多工具假定根目录为 **app** 或 **src/app**。只有在 Expo CLI 的确切版本中的工具才会尊重配置插件。


## 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应用。
## 配置
在继续之前，请确保根据[使用 Jest 进行单元测试](/develop/unit-testing/)和[`@testing-library/react-native`](https://callstack.github.io/react-native-testing-library/docs/start/quick-start)在你的项目中设置了`jest-expo`。
> **注意**：使用 Expo Router 时，请勿将测试文件放在 **app** 目录中。所有 **app** 目录中的文件必须是路由或布局文件。相反，请使用 **\_\_tests\_\_** 目录或单独的目录。此方法在[使用 Jest 进行单元测试](/develop/unit-testing/#structure-your-tests)中进行了说明。
## `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)兼容，允许你使用标准的[查询API](https://callstack.github.io/react-native-testing-library/docs/api/queries)来定位组件。
`renderRouter`接受与`render`相同的[选项](https://callstack.github.io/react-native-testing-library/docs/api#render-options)，并引入了一个额外的选项`initialUrl`，用于设置深度链接的初始路由。
#### 内联文件系统
`renderRouter(mock: Record<string, ReactComponent>, options: RenderOptions)`
`renderRouter`可以通过将对象作为第一个参数传递给此函数来提供文件系统的内联模拟。对象的键是模拟的文件系统路径。**定义这些路径时不要使用前导相对(`./`)或绝对(`/`)表示法，并排除文件扩展名。**
```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');
});
```
#### 使用`null`组件的内联文件系统
`renderRouter(mock: string[], options: RenderOptions)`
向`renderRouter`提供一个字符串数组将创建一个内联模拟文件系统，其中包含`null`组件(`{ default: () => null }`)。这对于测试不需要测试路由输出的场景非常有用。
```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');
});
```
#### 高速缓存路径
`renderRouter(fixturePath: string, options: RenderOptions)`
`renderRouter`可以接受一个目录路径以模拟现有的高速缓存。确保提供的路径相对于当前测试文件。
```tsx app.test.js
it('my-test', async () => {
  const MockComponent = jest.fn(() => <View />);
  renderRouter('./my-test-fixture');
});
```
#### 带覆盖的高速缓存路径
`renderRouter({ appDir: string, overrides: Record<string, ReactComponent>}, options: RenderOptions)`
对于更复杂的测试场景，`renderRouter`可以同时利用目录路径和内联模拟方法。`appDir`参数接受一个表示目录路径的字符串。覆盖参数是一个内联模拟，可用于覆盖`appDir`中的特定路径。此组合允许对模拟环境进行精细控制。
```tsx app.test.js
it('my-test', async () => {
  const MockAuthLayout = jest.fn(() => <View />);
  renderRouter({
    appDir: './my-test-fixture',
    overrides: {
      'directory/(auth)/_layout': MockAuthLayout,
    },
  });
});
```
## Jest 匹配器
以下匹配器已添加到`expect`中，可以用于断言`screen`上的值。
#### toHavePathname()
断言当前路径名与给定字符串匹配。该匹配器使用当前`screen`上的[`usePathname`](/router/reference/hooks/#usepathname)钩子的值。
```tsx app.test.ts
expect(screen).toHavePathname('/my-router');
```
#### toHavePathnameWithParams()
断言当前路径名（包括URL参数）与给定字符串匹配。这对于断言URL在网页浏览器中的出现很有用。
```tsx app.test.ts
expect(screen).toHavePathnameWithParams('/my-router?hello=world');
```
#### toHaveSegments()
断言当前片段与字符串数组匹配。该匹配器使用当前`screen`上的[`useSegments`](/router/reference/hooks/#usesegments)钩子的值。
```tsx app.test.ts
expect(screen).toHaveSegments(['[id]']);
```
#### useLocalSearchParams()
断言当前本地URL参数与对象匹配。该匹配器使用当前`screen`上的[`useLocalSearchParams`](/router/reference/hooks/#uselocalsearchparams)钩子的值。
```tsx app.test.ts
expect(screen).useLocalSearchParams({ first: 'abc' });
```
#### useGlobalSearchParams()
断言当前屏幕的路径名与某个值匹配。使用[`useGlobalSearchParams`](/router/reference/hooks/#useglobalsearchparams)钩子的值进行比较。
断言当前全局URL参数与对象匹配。该匹配器使用当前`screen`上的[`useGlobalSearchParams`](/router/reference/hooks/#useglobalsearchparams)钩子的值。
```tsx app.test.ts
expect(screen).useGlobalSearchParams({ first: 'abc' });
```
#### toHaveRouterState()
一个先进的匹配器，断言当前路由器状态与对象匹配。
```tsx app.test.ts
expect(screen).toHaveRouterState({
  routes: [{ name: 'index', path: '/' }],
});
```


## 故障排除

修复 Expo Router 设置中的常见问题。

## React Native DevTools 中缺少文件或源映射
如果您的 Chrome DevTools 在其忽略列表中有排除项，则可能会发生此情况。要解决此问题，请使用 [React Native DevTools](https://reactnative.dev/docs/react-native-devtools):
1. 通过在终端窗口中运行的开发服务器按 <kbd>j</kbd> 启动 React Native DevTools
2. 点击齿轮图标打开 **设置**
3. 在 **扩展** 下，点击 **恢复默认设置并重新加载**
4. 再次打开 **设置**，转到 **忽略列表** 选项卡
5. 取消选中任何对 `/node_modules/` 的排除项
## `EXPO_ROUTER_APP_ROOT` 未定义
如果 `process.env.EXPO_ROUTER_APP_ROOT` 未定义，您将看到以下错误：
```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` 时，可能会发生此情况。您可以尝试通过以下命令清除缓存：
```sh
$ npx expo start --clear
```
或者，您可以通过在项目根目录中创建一个 **index.js** 文件，并包含以下内容，来绕过此问题：
```jsx index.js
import { registerRootComponent } from 'expo';
import { ExpoRoot } from 'expo-router';
// 必须导出，否则快速刷新不会更新上下文
export function App() {
  const ctx = require.context('./app');
  return <ExpoRoot context={ctx} />;
}
registerRootComponent(App);
```
然后，在 **package.json** 中更新您应用的主入口点：
```json package.json
{
  "main": "index.js"
}
```
> 请勿使用此方法更改根目录（**app**），因为它不会考虑在其他地方的使用。
## `require.context` 未启用
当使用未启用上下文模块的自定义版本 `@expo/metro-config` 时，可能会发生此情况。Expo Router 要求项目的 **metro.config.js** 使用 `expo-router/metro` 作为默认配置。删除 **metro.config.js** 或扩展 `expo/metro-config`。有关更多信息，请参见 [自定义 metro](/guides/customizing-metro/)。
## 缺少返回按钮
如果您设置了一个模态窗口或其他预期有返回按钮的屏幕，则需要将 [`unstable_settings`](/router/advanced/router-settings/) 添加到路由的布局中，以确保初始路由已配置。初始路由在移动应用中有些独特，并且在系统中适应不良 &mdash; 改进待定。
```tsx app/_layout.tsx
export const unstable_settings = {
  initialRouteName: 'index',
};
```


# 迁移

## 从 React Navigation 迁移

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

React Navigation 和 Expo Router 都是用于路由和导航的 Expo 框架。Expo Router 是 React Navigation 的一个包装，许多概念是相同的。
## 介绍
除了 React Navigation 的所有优点外，Expo Router 还支持自动深层链接、[类型安全](/router/reference/typed-routes)、[延迟打包](/router/reference/async-routes)、[Web 的静态渲染](/router/reference/static-rendering)以及更多功能。
## 反向介绍
如果您的应用使用自定义的 `getPathFromState` 或 `getStateFromPath` 组件，可能不适合 Expo Router。如果您使用这些函数来支持 [共享路由](/router/advanced/shared-routes)，那么您应该没问题，因为 Expo Router 内置了对这点的支持。
## 建议
我们建议在开始迁移之前，对您的代码库进行以下修改：
- 将 React Navigation 的 screen 组件拆分成单独的文件。例如，如果您有 `<Stack.Screen component={HomeScreen} />`，则确保 `HomeScreen` 组件位于自己的文件中。
- 将项目转换为 [TypeScript](/guides/typescript/#migrating-existing-javascript-project)。这将使您更容易发现迁移过程中可能出现的错误。
- 将相对导入转换为 [类型别名](/guides/typescript/#path-aliases-optional)。例如，在开始迁移之前，将 `../../components/button.tsx` 转换为 `@/components/button`。这使得在文件系统中移动屏幕时，无需更新相对路径。
- 避免使用 `resetRoot`。这用于在运行时“重启”应用程序。这通常被认为是一个不好的实践，您应该重构应用的导航，以便不再需要此操作。
- 将初始路由重命名为 `index`。Expo Router 将启动时打开的路由视为匹配 `/`，而 React Navigation 用户通常将初始路由称为“Home”。
### 重构搜索参数
将屏幕重构为 [使用可序列化的顶级查询参数](https://reactnavigation.org/docs/params/#what-should-be-in-params)。我们在 React Navigation 中也推荐这样做。
在 Expo Router 中，搜索参数只能序列化顶级值，例如 `number`、`boolean` 和 `string`。React Navigation 没有相同的限制，因此用户有时可能会传递无效的参数，比如函数、对象、地图等。
如果您的代码类似于以下内容：
```js
import { useNavigation } from '@react-navigation/native';
const navigation = useNavigation();
navigation.push('Followers', {
  onPress: profile => {
    navigation.push('User', { profile });
  },
});
```
请考虑重构，以便该函数可以从“关注者”屏幕访问。在这种情况下，您可以从“关注者”屏幕访问路由并直接推送。
### 急切加载 UI
在 React Native 应用中，从根组件 `return null` 在资产和字体加载时很常见。这是不好的做法，并且在 Expo Router 中通常不支持。如果您绝对必须延迟渲染，请确保您不会尝试导航到任何屏幕。
历史上，这种模式存在是因为如果您使用尚未加载的自定义字体，React Native 会抛出错误。我们在 React Native 0.72（SDK 49）中上游更改了这一点，因此默认行为是在自定义字体加载时交换默认字体。如果您希望在字体加载完成之前隐藏单个文本元素，请编写一个包装 `<Text>`，在字体加载完成之前返回 null。
在 Web 上，从根返回 `null` 将导致 [静态渲染](/router/reference/static-rendering) 跳过所有子元素，结果没有可搜索的内容。这可以通过在 Chrome 中使用“查看页面源”或禁用 JavaScript 并重新加载页面来测试。
## 迁移
### 删除未使用或管理的代码
Expo Router 自动添加对 `react-native-safe-area-context` 的支持。
```diff
- import { SafeAreaProvider } from 'react-native-safe-area-context';
export default function App() {
  return (
-    <SafeAreaProvider>
      <MyApp />
-    </SafeAreaProvider>
  )
}
```
Expo Router **不**添加 `react-native-gesture-handler`（自 v3 起），因此如果您使用 Gesture Handler 或 `<Drawer />` 布局，您需要自己添加此内容。在 Web 上避免使用此包，因为它添加的很多 JavaScript 经常未使用。
### 将屏幕复制到应用目录
在您的仓库根目录或根 **src** 目录创建一个 **app** 目录。
通过根据 [Expo Router 规则的应用](https://router/basics/core-concepts/#the-rules-of-expo-router-applied) 创建文件来布局您应用的结构。使用 kebab-case 和小写字母被认为是路由文件名的最佳实践。
用目录替换导航器，例如：
```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 由 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 Router:**
- 将“主”路由从 **Home** 重命名为 **index**，以确保其匹配 `/` 路径。
- 将名称转换为小写字母。
- 将所有屏幕移动到应用目录中的适当文件位置。这可能需要一些实验。
```
app/
    ├── _layout.js
    ├── (home)/
    │   ├── _layout.js
    │   ├── index.js
    │   └── feed.js
    ├── profile.js
    └── settings.js
```
```jsx app/_layout.js
import { Stack } from 'expo-router';
export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen
        name="(home)"
        options={
            title: 'Home Screen',
        }
      />
    </Stack>
  );
}
```
选项卡导航器将移动到子目录。
```jsx app/(home)/_layout.js
import { Tabs } from 'expo-router';
export default function HomeLayout() {
  return <Tabs />;
}
```
### 使用 Expo Router 钩子
React Navigation v6 及更低版本将 `{ navigation, route }` 属性传递给每个屏幕。这种模式在 React Navigation 中将逐步消失，并且我们从未将其引入到 Expo Router 中。
相反，将 `navigation` 迁移到 `useRouter` 钩子。
```diff
+ import { useRouter } from 'expo-router';
export default function Page({
-  navigation
}) {
-  navigation.push('User', { user: 'bacon' });
+  const router = useRouter();
+  router.push('/users/bacon');
}
```
同样，从 `route` 属性迁移到 [`useLocalSearchParams`](/router/reference/hooks/#uselocalsearchparams) 钩子。
```diff
+ import { useLocalSearchParams } from 'expo-router';
export default function Page({
-  route
}) {
-  const user = route?.params?.user;
+  const { user } = useLocalSearchParams();
}
```
要访问 [`navigation.navigate`](https://reactnavigation.org/docs/navigation-object/#navigate)，从 [`useNavigation`](/router/reference/hooks/#usenavigation) 钩子导入 `navigation` 属性。
```diff
+ import { useNavigation } from 'expo-router';
export default function Page({
+  const navigation = useNavigation();
  return (
    <Button onPress={navigation.navigate('screenName')}>
  )
})
```
### 迁移 Link 组件
React Navigation 和 Expo Router 都提供 Link 组件。然而，Expo 的 Link 组件使用 `href` 而不是 [`to`](https://reactnavigation.org/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 应用中，通常会在多个导航器之间重用一组路由。这通常与标签一起使用，以确保每个标签都可以推送任意屏幕。
在 Expo Router 中，您可以迁移到 [共享路由](/router/advanced/shared-routes) 或创建多个文件并从中重新导出相同的组件。
当您使用组或共享路由时，您可以通过使用完全合格的路由名称导航到特定标签，例如 `/(home)/settings` 而不是 `/settings`。
### 迁移屏幕跟踪事件
您可能根据我们的 [React Navigation 屏幕跟踪指南](https://reactnavigation.org/docs/screen-tracking/) 设置了屏幕跟踪，请根据 [Expo Router 屏幕跟踪指南](/router/reference/screen-tracking) 更新。
### 根据平台使用特定组件来显示屏幕
有关根据平台切换 UI 的信息，请参阅 [平台特定模块](/router/advanced/platform-specific-modules) 指南。
### 替换 `NavigationContainer`
全局的 React Navigation [`<NavigationContainer />`](https://reactnavigation.org/docs/navigation-container/) 在 Expo Router 中完全由其管理。Expo Router 提供系统，以实现与 `NavigationContainer` 相同的功能，而无需直接使用它。
Note: API 替代
---
### Ref
`NavigationContainer` 引用不应直接访问。请使用以下方法。
#### `resetRoot​`
导航到应用程序的初始路由。例如，如果您的应用从 `/` 开始（推荐），那么您可以使用此方法将当前路由替换为 `/`。
```jsx
import { useRouter } from 'expo-router';
function Example() {
  const router = useRouter();
  return (
    <Text
      onPress={() => {
        // 转到应用程序的初始路由。
        router.replace('/');
      }}>
      Reset App
    </Text>
  );
}
```
#### `getRootState`
使用 `useRootNavigationState()`。
#### `getCurrentRoute`
与 React Navigation 不同，Expo Router 可以可靠地区分任何路由字符串。使用 [`usePathname()`](/router/reference/hooks/#usepathname) 或 [`useSegments()`](/router/reference/hooks/#usesegments) 钩子来识别当前路由。
#### `getCurrentOptions`
使用 [`useLocalSearchParams()`](/router/reference/hooks/#uselocalsearchparams) 钩子获取当前路由的查询参数。
#### `addListener`
可以迁移以下事件：
#### `state`
使用 [`usePathname()`](/router/reference/hooks/#usepathname) 或 [`useSegments()`](/router/reference/hooks/#usesegments) 钩子来识别当前路由。与 `useEffect(() => {}, [...])` 结合使用，以观察变化。
#### `options`
使用 [`useLocalSearchParams()`](/router/reference/hooks/#uselocalsearchparams) 钩子获取当前路由的查询参数。与 `useEffect(() => {}, [...])` 结合使用，以观察变化。
### 属性
迁移以下 `<NavigationContainer />` 属性：
#### `initialState`
在 Expo Router 中，您可以从路由字符串（例如 `/user/evanbacon`）重新水合应用程序状态。使用 [重定向](/router/reference/redirects/) 处理初始状态。有关高级重定向，请参阅 [共享路由](/router/advanced/shared-routes/)。
避免使用此模式，优先使用深层链接（例如，用户打开您的应用到 `/profile` 而不是从主屏幕），因为这最类似于 Web。如果应用因特定屏幕崩溃，最好避免在应用启动时自动导航回确切的屏幕，因为这可能需要重新安装应用以修复。
#### `onStateChange`
使用 [`usePathname()`](/router/reference/hooks/#usepathname)、[`useSegments()`](/router/reference/hooks/#usesegments) 和 [`useGlobalSearchParams()`](/router/reference/hooks/#useglobalseearchparams) 钩子来识别当前路由状态。与 `useEffect(() => {}, [...])` 结合使用，以观察变化。
- 如果您尝试跟踪屏幕更改，请遵循 [屏幕跟踪指南](/router/reference/screen-tracking/)。
- React Navigation 建议避免 [`onStateChange`](https://reactnavigation.org/docs/navigation-container/#onstatechange)。
#### `onReady`
在 React Navigation 中，[`onReady`](https://reactnavigation.org/docs/navigation-container/#onready) 最常用于确定何时隐藏启动屏幕或何时通过分析跟踪屏幕。Expo Router 对这两种用例都有特殊处理。假设在 Expo Router 中，导航始终为导航事件做好准备。
- 有关从 React Navigation 迁移分析信息，请参见 [屏幕跟踪指南](/router/reference/screen-tracking/)。
- 有关处理启动屏幕的信息，请参见 [启动屏幕功能](/develop/user-interface/splash-screen-and-app-icon/)。
#### `onUnhandledAction`
在 Expo Router 中，操作始终被处理。使用 [动态路由](/router/basics/notation/#square-brackets) 和 [404 屏幕](/router/error-handling/#unmatched-routes) 替代 [`onUnhandledAction`](https://reactnavigation.org/docs/navigation-container/#onunhandledaction)。
#### `linking`
[`linking`](https://reactnavigation.org/docs/navigation-container/#linking) 属性是基于 **app** 目录中的文件自动构建的。
#### `fallback`
[`fallback`](https://reactnavigation.org/docs/navigation-container/#fallback) 属性由 Expo Router 自动处理。更多信息请参见 [启动屏幕](/versions/latest/sdk/splash-screen/) 参考。
#### `theme`
在 React Navigation 中，您使用 [`<NavigationContainer />`](https://reactnavigation.org/docs/navigation-container/#theme) 组件为整个应用设置主题。Expo Router 为您管理根容器，因此相反，您应该直接使用 `ThemeProvider` 设置主题。
```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>
  );
}
```
您可以在应用的任何层使用此技术设置特定布局的主题。当前主题可以通过 `@react-navigation/native` 中的 `useTheme` 钩子访问。
#### `children`
`children` 属性根据 **app** 目录中的文件和当前打开的 URL 自动填充。
#### `independent`
Expo Router 不支持 [`independent`](https://reactnavigation.org/docs/navigation-container/#independent) 容器。这是因为路由器负责管理单个 `<NavigationContainer />`。任何其他容器将不会由 Expo Router 自动管理。
#### `documentTitle`
使用 [Head 组件](/router/reference/static-rendering#meta-tags) 设置网页标题。
#### `ref`
请改用 `useNavigationContainerRef()` 钩子。
---
### 重写自定义导航器
如果您的项目有自定义导航器，您可以重写它或将其移植到 Expo Router。
要移植，只需使用 `withLayoutContext` 函数：
```js
import { createCustomNavigator } from './my-navigator';
export const CustomNavigator = withLayoutContext(createCustomNavigator().Navigator);
```
要重写，请使用 `Navigator` 组件，该组件将包装来自 React Navigation 的 [`useNavigationBuilder`](https://reactnavigation.org/docs/custom-navigators#usenavigationbuilder) 钩子。
`useNavigationBuilder` 的返回值可以通过 `<Navigator />` 组件内部的 `Navigator.useContext()` 钩子访问。可以通过 `<Navigator />` 组件的属性传递属性给 `useNavigationBuilder`，包括 `initialRouteName`、`screenOptions` 和 `router`。
`<Navigator />` 组件的所有 `children` 将按原样渲染。
- `Navigator.useContext`：访问 React Navigation 的 `state`、`navigation`、`descriptors` 和 `router` 用于自定义导航器。
- `Navigator.Slot`：用于呈现当前所选路由的 React 组件。此组件只能在 `<Navigator />` 组件内部渲染。
#### 示例
自定义布局具有一个内部上下文，在没有 `<Navigator />` 组件将其包装时，使用 `<Slot />` 组件将被忽略。
```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>
  );
}
```
### 使用 Expo Router 的启动屏幕包装器
Expo Router 包装了 `expo-splash-screen` 并添加了特殊处理，以确保在导航挂载后以及每当捕获到意外错误时隐藏它。只需将导入 `expo-splash-screen` 迁移到导入来自 `expo-router` 的 `SplashScreen`。
### 观察导航状态
如果您直接观察导航状态，请迁移到 [`usePathname`](/router/reference/hooks/#usepathname)、[`useSegments`](/router/reference/hooks/#usesegments) 和 [`useGlobalSearchParams`](/router/reference/hooks/#useglobalsearchparams) 钩子。
### 将参数传递给嵌套屏幕
而不是使用 [嵌套屏幕导航事件](https://reactnavigation.org/docs/params/#passing-params-to-nested-navigators)，请使用合格的 href：
```js
// React Navigation
navigation.navigate('Account', {
  screen: 'Settings',
  params: { user: 'jane' },
});
// Expo Router
router.push({ pathname: '/account/settings', params: { user: 'jane' } });
```
### 为深层链接和服务器导航设置初始路由
在 React Navigation 中，您可以使用链接配置的 `initialRouteName` 属性。在 Expo Router 中，请使用 [布局设置](/router/advanced/router-settings)。
### 重置导航状态
您可以使用来自 React Navigation 库的 [`reset`](https://reactnavigation.org/docs/navigation-actions/#reset) 操作来重置导航状态。它是通过从 Expo Router 访问的 [`useNavigation`](/router/reference/hooks/#usenavigation) 钩子派发的 `navigation` 属性。
在以下示例中，`navigation` 属性可以从 `useNavigation` 钩子和来自 `@react-navigation/native` 的 `CommonActions.reset` 操作访问。`reset` 操作中指定的对象将用新对象替换现有的导航状态。
```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} />
    </>
  );
}
```
### 迁移 TypeScript 类型
Expo Router 可以自动生成 [静态类型路由](/router/reference/typed-routes)，这将确保您只能导航到有效的路由。
## 附加信息
### React Navigation 主题
React Navigation 的导航器 `<Stack>`、`<Drawer>` 和 `` 使用共享外观提供程序。在 React Navigation 中，您使用 `<NavigationContainer />` 组件为整个应用设置主题。Expo Router 管理根容器，因此您可以直接使用 `ThemeProvider` 设置主题。
```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>
  );
}
```
您可以在应用的任何层使用此技术设置特定布局的主题。当前主题可以通过 `useTheme` 钩子访问。
### React Navigation 元素
[`@react-navigation/elements`](https://reactnavigation.org/docs/elements/) 库提供了一组 UI 元素和帮助程序，可以用来构建导航 UI。这些组件旨在可组合和可定制。您可以重用库中的默认功能或在其基础上构建您自己的导航器 UI。
要与 Expo Router 一起使用，您需要安装该库：
For npm: 
```sh
$ npm install @react-navigation/elements
```
For Yarn: 
```sh
$ yarn add @react-navigation/elements
```
要了解有关该库提供的组件和工具的更多信息，请参见 [Elements library](https://reactnavigation.org/docs/elements/) 文档。


## 从 Expo Webpack 迁移

学习如何将使用 Expo Webpack 的网站迁移到 Expo Router。

原始的 **Expo for web** 版本基于 Webpack 4，主要集中于构建单页面应用程序（SPAs）。这种方法基于 [Create React App](https://create-react-app.dev/)，使得使用 Expo SDK 和 React Native for web 构建简单的 web 应用程序成为可能。
Expo Router 是构建能够在 web 和原生上运行的强大通用应用的新方法。此指南将帮助您将现有网站迁移到 Expo Router。
React Navigation 和 Expo Router 都是 Expo 的路由和导航框架。Expo Router 是 React Navigation 的一个包装器，并且有许多共享的概念。
## 提示
> **warning** `@expo/webpack-config` 已被废弃，不会再接收任何新特性更新。
Expo Router 支持 [静态渲染在 web 上](/router/reference/static-rendering)，这使得搜索引擎优化（SEO）、社交媒体预览和更快的加载时间成为可能，不同于 Expo Webpack。除了 React Navigation 的优势，它还支持自动深度链接、[类型安全](/router/reference/typed-routes)、[延迟打包](/router/reference/async-routes)、[模块化 HTML 模板](/router/reference/static-rendering#root-html)、[静态渲染在 web 上](/router/reference/static-rendering) 等等。
Expo Router 还旨在解决 Expo Webpack 的主要跨平台问题，通过在 web 和原生之间共享导航，而不影响功能或性能。
## 反提示
Expo Router 使用基于 [Metro](https://metrobundler.dev/) 的自定义打包器堆栈。这是 React Native 使用的相同打包器。这确保了最大代码重用，并解决了由于跨平台使用不同打包器而导致的许多分叉行为问题。这也意味着某些打包功能可能尚未在 Expo Router 中可用。
最终，作为一个完整的通用框架，Expo Router 是一种比 `@expo/webpack-config` 更强大的解决方案，后者只是一个打包器集成。它应该用于所有新的 Expo web 项目。
## Expo CLI
与 `@expo/webpack-config` 不同，Expo Router 在 web 和原生中使用相同的 CLI 命令和功能。有关 Expo Router 和 `@expo/webpack-config` 之间差异的更多信息，请参阅下表。
| 特性                 | Expo Router                                | `@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` |
| 打包拆分             | <YesIcon /> (SDK 50 • web)                 | <YesIcon />            |
| 全局 CSS             | <YesIcon /> (SDK 50 • web)                 | <YesIcon />            |
| CSS 模块             | <YesIcon /> (SDK 50 • web)                 | <NoIcon />             |
| 静态字体优化         | <YesIcon /> (SDK 50 • web)                 | <NoIcon />             |
| API 路由             | <YesIcon /> (SDK 50)                       | <NoIcon />             |
| 多平台               | <YesIcon />                                | <NoIcon />             |
| 快速刷新             | <YesIcon />                                | <NoIcon />             |
| 错误覆盖             | <YesIcon />                                | <NoIcon />             |
| 延迟打包             | <YesIcon />                                | <NoIcon />             |
| 静态生成             | <YesIcon />                                | <NoIcon />             |
| 环境变量             | <YesIcon />                                | <NoIcon />             |
| `tsconfig.json` 路径 | <YesIcon />                                | <NoIcon />             |
| 树摇晃               | <PendingIcon /> ([部分支持][tree-shaking]) | <YesIcon />            |
## HTML 模板
在 `@expo/webpack-config` 中，所有路由共享一个单一的 HTML 文件。该文件基于 `web/index.html` 中的模板，然后由 `@expo/webpack-config` 修改以包含必要的脚本和样式表。
在 Expo Router 中，有两种不同的渲染模式：
- **推荐**: `web.output: "static"`，为应用中的每个路由输出一个新的 HTML 文件。这种方法允许您使用 **app/+html.js** 文件 [动态生成整个 HTML 模板](/router/reference/static-rendering#root-html)。
- **不推荐**: `web.output: "single"`，输出一个单页面应用程序。这种方法让您使用 `public/index.html` 作为模板 HTML 文件。
## 静态资源
在 `@expo/webpack-config` 中，您可以在 `web` 目录中托管静态文件，这些文件将从网站的根目录提供服务。例如，`web/favicon.ico` 是从 `https://example.com/favicon.ico` 提供的。
在 Expo Router 中，您可以使用 **public** 目录来托管静态文件。例如，**public/favicon.ico** 是从 `https://example.com/favicon.ico` 提供的。与 Webpack 不同，Expo Router 的托管在原生上也有效。在生产中使用前，请确保从服务器托管文件。
## 生产打包
在 `@expo/webpack-config` 中，您可以使用 `npx expo export:web` 来将网站打包为生产版本。这会将包输出到 **web-build** 目录。
在 Expo Router 中，使用 `npx expo export --platform web` 命令导出到 **dist** 目录。您可以使用 `--dump-sourcemap` 标志生成源映射。在构建时，**public** 目录的内容将被复制到 **dist** 目录。
## Babel 配置
与之前一样，根 [**babel.config.js**](/versions/latest/config/babel/) 文件用于 web 和原生。您可以通过在 API 调用者中使用 `platform` 属性来更改预设：
```js babel.config.js
module.exports = api => {
  // 从 API 调用者获取平台...
  const platform = api.caller(caller => caller && caller.platform);
  return {
    presets: ['babel-preset-expo'],
    plugins: [
      // 添加一个仅限 Web 的插件...
      platform === 'web' && 'custom-web-only-plugin',
    ].filter(Boolean),
  };
};
```
## 开发服务器
在 Expo Router 中，所有平台都从同一开发服务器在同一端口托管。这方便了模拟应用的生产行为。所有日志和热更新也通过同一端口进行。
由于原生的限制，目前不支持使用假 HTTPS 托管。这个功能现在的重要性低于 2018 年，因为您可以使用 Chrome 等网络浏览器在 localhost 上测试摄像头和位置等安全特性。
## Expo 常量
[`expo-constants`](/versions/latest/sdk/constants/) 库可以用于访问应用内的 **app.json**。在幕后，这通过将 `process.env.APP_MANIFEST` 设置为 **app.json** 文件的字符串内容来实现。
在 Expo Router 中，通过使用 Babel 和 `babel-preset-expo` 来完成。如果您修改了 **app.json**，请使用 `npx expo start --clear` 重新启动 Babel 缓存以查看更新。
## 基路径和子路径托管
> **important** 实验性功能。
在 `@expo/webpack-config` 中，您可以使用 `PUBLIC_URL` 环境变量或项目 **package.json** 中的 `homepage` 字段将网站打包为从子路径托管：
```json package.json
{
  "homepage": "/evanbacon/my-website"
}
```
在 Expo Router 中，您可以使用项目 **app.json** 中的实验性 `baseUrl` 字段：
```json app.json
{
  "expo": {
    "experiments": {
      "baseUrl": "/evanbacon/my-website"
    }
  }
}
```
与之前的系统不同，这还会更新路由以考虑基路径。例如，如果您有一个路由 `/profile`，并将基路径设置为 `/evanbacon/my-website`，则该路由将是 `/evanbacon/my-website/profile`。
有关更多信息，请参见 [使用子路径托管](/more/expo-cli#hosting-with-sub-paths)。
## 快速刷新
在 `@expo/webpack-config` 中，您可以安装 `@pmmmwh/react-refresh-webpack-plugin` 并在 **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);
  // 在开发模式中使用 React 刷新插件
  if (env.mode === 'development') {
    config.plugins.push(new ReactRefreshWebpackPlugin({ disableRefreshCheck: true }));
  }
  return config;
};
```
在 Expo Router 中，**快速刷新默认启用**，使用 Meta 的官方快速刷新实现。
## 网站图标
与 `@expo/webpack-config` 一样，Expo Router 支持根据 **app.json** 中的 `web.favicon` 字段生成 **favicon.ico** 文件。
## Service Workers
> **warning** 添加 service workers 时要小心，因为它们可能导致网络上出现意外行为。如果您不小心发布了一个过于激进缓存您网站的 service worker，则用户无法轻松请求更新。为了获得最佳的离线移动体验，请使用 Expo 创建一个原生应用。与带有 service workers 的网站不同，原生应用可以通过应用商店更新以清除缓存的体验。这类似于重置用户的原生浏览器（如果 service worker 过于激进的话，他们可能需要这样做）。有关更多信息，请参见 [为什么 service workers 不理想](https://github.com/facebook/create-react-app/issues/2398)。
Expo Webpack 没有内置的 service worker 支持。但是，您可以通过使用 `workbox-webpack-plugin` 并将其添加到 **webpack.config.js** 中来自行添加。
Workbox 没有 Metro 集成，但因为 Workbox 不需要打包器的核心功能之一（转换、解析、序列化），它可以很容易地作为构建后的步骤使用。请遵循 [使用 Workbox CLI](https://developer.chrome.com/docs/workbox/modules/workbox-cli/) 的指南，所有提到“构建脚本”的地方，使用 `npx expo export -p web`。
例如，这是设置 Workbox 的可能流程。用以下命令创建新项目：
```sh
$ npm create expo -t tabs my-app
$ cd my-app
```
接下来，为应用创建一个根 HTML 文件，并添加 service worker 注册脚本：
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import type { PropsWithChildren } from 'react';
// 此文件仅限于 Web，用于配置每个
// 在静态渲染期间的 web 页面的根 HTML。
// 此函数的内容仅在 Node.js 环境中运行，
// 不访问 DOM 或浏览器 API。
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" />
        {/* 启动 service worker。 */}
        <script dangerouslySetInnerHTML={{ __html: sw }} />
        {/*
          在 web 上禁用 body 滚动。这使 ScrollView 组件的工作方式更接近于它们在原生中的工作方式。
          然而，body 滚动通常在移动 Web 上是可以有的。如果您想启用它，请删除此行。
        */}
        <ScrollViewStyleReset />
        {/* 添加任何您希望在 web 上全局可用的额外 <head> 元素... */}
      </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);
        });
    });
}
`;
```
现在在运行向导之前构建应用：
```sh
$ npx expo export -p web
```
运行向导命令，选择 `dist` 作为应用的根目录，其他所有默认值：
```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** 中添加一个构建脚本，以正确的顺序运行这两个脚本：
```json package.json
{
  "scripts": {
    "build:web": "expo export -p web && npx workbox-cli generateSW workbox-config.js"
  }
}
```
## PWA 清单
与 `@expo/webpack-config` 不同，Expo Router 不会自动尝试生成 PWA 清单配置。您可以在 **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 文件中链接此文件：
```tsx app/+html.tsx
import { ScrollViewStyleReset } from 'expo-router/html';
import type { PropsWithChildren } from 'react';
// 此文件仅限于 Web，用于配置每个
// 在静态渲染期间的 web 页面的根 HTML。
// 此函数的内容仅在 Node.js 环境中运行，
// 不访问 DOM 或浏览器 API。
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" />
        {/* 链接 PWA 清单文件。 */}
        <link rel="manifest" href="/manifest.json" />
        {/*
          在 web 上禁用 body 滚动。这使 ScrollView 组件的工作方式更接近于它们在原生中的工作方式。
          然而，body 滚动通常在移动 Web 上是可以有的。如果您想启用它，请删除此行。
        */}
        <ScrollViewStyleReset />
        {/* 添加任何您希望在 web 上全局可用的额外 <head> 元素... */}
      </head>
      <body>{children}</body>
    </html>
  );
}
```
## 打包器插件
如果您使用了自定义打包器插件，请参见 [Expo Metro 配置](/versions/latest/config/metro) 以向您的打包管道添加自定义功能。
## 导航
如果您在 `@expo/webpack-config` 中使用 React Navigation 在屏幕之间导航，请参见 [React Navigation 的迁移指南](/router/migrate/from-react-navigation)。
## 部署
查看 [发布网站](/guides/publishing-websites) 了解如何将 Expo Router 网站部署到各种托管提供商。
[tree-shaking]: /guides/tree-shaking


# Expo 模块 API

## Expo 模块 API：概述

Expo 提供的用于开发原生模块的 API 和工具的概述。

## 什么是 Expo 模块 API
Expo 模块 API 允许您使用 Swift 和 Kotlin 编写代码，为您的应用程序添加原生模块和视图的新功能。该 API 旨在利用现代语言特性，尽可能在两个平台上保持一致，要求最少的样板代码，并提供与 React Native 的 Turbo Modules API 相当的性能特性。所有 Expo 模块都支持新架构，并自动向后兼容使用旧架构的现有 React Native 应用。
我们相信，使用 Expo 模块 API 使构建和维护几乎所有类型的 React Native 模块变得尽可能简单，我们认为 Expo 模块 API 是绝大多数开发人员为其应用构建原生模块的最佳选择。
### 常见问题
Note: 我需要了解 Expo 模块 API 才能构建 Expo / React Native 应用吗？
---
大多数情况下，Expo 和 React Native 开发人员不需要编写任何原生代码 &mdash; 库已经针对广泛的用例提供了支持，从相机到视频、到地图、到触觉等应有尽有。
但有时，没有任何东西能够完全满足您的需求。也许您想集成您公司所要求的分析服务，但该服务尚未拥有 React Native 库，因此您需要围绕他们的 SDK 构建一个模块。或者，也许您想访问您的应用所需，但并不常用的系统特性，因此没有人维护相应的库。
---
Note: 我什么时候应该使用 Turbo 模块，什么时候应该使用 Expo 模块 API？
---
总结并改述 [React Native 团队的建议](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):
- 如果您打算在原生模块中使用 C++，请使用 Turbo 模块，因为它提供了更方便的低级机制访问。
- 如果您希望更好的开发体验，并且愿意在模块中依赖 `expo` 包，则使用 Expo 模块 API。
---
Note: 我在哪里可以找到开源的 Expo 模块以供学习？
---
如果您想学习我们如何实现库，[Expo SDK](https://github.com/expo/expo/tree/main/packages) 是一个很好的地方。另一个极好的资源是开源应用，例如 [Bluesky](https://github.com/bluesky-social/social-app/tree/main/modules)。
以下库是我们社区中的一些最爱：
- [`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: 使用 Expo 模块 API 会对我的应用大小产生什么影响？
---
将 Expo 模块 API 添加到您的应用对应用大小的影响微乎其微，可能会增加几百千字节的大小。[在这篇博客文章中了解更多](https://blog.expo.dev/embracing-expo-modules-in-your-react-native-projects-cd8ed4cbec3)。
---
Note: 使用 Expo 模块 API 会对我的应用性能产生什么影响？
---
Expo 模块 API 的性能特性与 React Native 的 Turbo 模块 API 类似。两个 API 都利用 React Native 的 JavaScript 接口（JSI），而不是使用过时的 JSON 消息队列（“桥”）的方法 ([了解更多关于 JSI 的内容](https://reactnative.dev/docs/the-new-architecture/landing-page#fast-javascriptnative-interfacing))。
无论是 Expo 模块还是 Turbo 模块，并不是为了追求技术上最快的速度，而是在重要的地方提供快速。例如，Expo 模块 API 可能会利用代码生成和新的原生 Swift / C++ 互操作性，来减少单个方法调用的开销。然而，这会带来一些开发体验挑战和开销，我们尚未遇到任何这样的优化能提供实质性现实世界性能改进的用例。实际上，执行原生方法主体所花费的时间往往比方法调用的开销大几个数量级。Expo 模块和 Turbo 模块可以轻松地每秒执行数十万次原生方法调用，这远远超过您可能在任何应用中发现的，并且方法调用的开销不太可能成为瓶颈。
如果您在使用 Expo 模块 API 时遇到任何性能瓶颈，[提交问题](https://github.com/expo/expo/issues/new/choose)，我们很乐意与您讨论。
---
Note: Expo 模块 API 是否支持 Android、iOS 和 Web 以外的平台？
---
Expo 模块 API 对 macOS 和 tvOS 有实验性支持。有关更多信息，请参见 [额外平台支持](/modules/additional-platform-support/) 教程。
---
Note: 我如何使用 Expo 模块 API 将第三方 SDK 提供给我的 Expo 应用？
---
在 [集成现有库](/modules/existing-library/) 教程中了解更多。
---
## 下一步


## Expo 模块 API：开始入门

了解如何开始使用 Expo 模块 API。

**有两种方法可以开始使用 Expo 模块 API**：您可以从头开始初始化一个新模块或将 Expo 模块 API 添加到现有模块中。本指南将指导您从头开始创建一个新模块，而 [集成到现有库中](/modules/existing-library) 则涵盖后者。
创建新模块的两种推荐流程：
- [将新模块添加到现有 Expo 应用程序](#add-a-new-module-to-an-existing-application)，并使用它来测试和开发您的模块。
- [在隔离中创建一个新模块并生成示例项目](#create-a-new-module-with-an-example-project)，如果您想在多个项目中重用它或将其发布到 npm。
这两个流程将在接下来的部分中进行介绍。
## 将新模块添加到现有应用程序
Step 1: 
### 创建本地 Expo 模块
导航到您的项目目录（即包含 **package.json** 文件的目录），然后运行以下命令。这是创建本地 Expo 模块的推荐方法。
```sh
$ npx create-expo-module@latest --local
```
您可以在 CLI 提示中提供一个有意义的模块名称。对于其余的提示，您也可以接受默认建议。
运行命令后，您将看到在项目中创建了一个名为 **modules** 的新目录。目录结构应如下所示：
```
modules/
    └── my-module/
        ├── android/
        │   └── 
        ├── ios/
        │   └── 
        ├── src/
        │   └── 
        ├── expo-module.config.json
        └── index.ts
```
然后，如果您的项目没有生成本地项目（**android** 和 **ios** 目录），请运行以下命令，否则跳过此命令：
```sh
$ npx expo prebuild --clean
```
> **注意**：如果您的项目根目录中存在使用 `npx expo prebuild` 创建的预先存在的 **ios** 目录，则必须重新安装 pods：
>
> 
> ```sh
$ npx pod-install
```
Step 2: 
### 使用本地模块
在您的应用程序中导入本地模块，例如在 **App.js** 或 **App.tsx** 或 **app/(tabs)/index.tsx** 中：
```tsx app/(tabs)/index.tsx
import MyModule from '@/modules/my-module';
export default function HomeScreen() {
  return (
    <View style={styles.container}>
      <Text>{MyModule.hello()}</Text>
    </View>
  );
}
```
在终端中启动开发服务器，以便在您编辑原生模块并在下一步构建应用程序时，所做的更改将反映在应用中：
```sh
$ npx expo start
```
恭喜！您已创建一个本地 Expo 模块。您现在可以开始对其进行开发。
> **info** **提示**：您还可以通过 [应用以下配置更改](https://expo.fyi/absolute-path-expo-modules.md) 来使用绝对导入路径。
Step 3: 
### 编辑模块
要在本地开发和测试您的模块，让我们使用 Android Studio 和 Xcode 来支持 Android 和 iOS。
#### Android
1. 从您的项目中打开 **android** 目录（该目录由步骤 1 中的 `npx expo prebuild` 生成），在 Android Studio 中可能需要一段时间以让 Gradle 完成同步原生目录项目。
2. 一旦项目完成同步，打开 **modules/my-module/android/src/main/java/expo/modules/mymodule/MyModule.kt** 文件。
3. 将 `hello` 函数更改为返回不同的字符串，例如 "Hello world! 🌎🤖"，并保存文件。
4. 通过点击顶部菜单栏中的 **Run 'app'** 按钮构建应用程序，您将看到屏幕上的更改。
每次对原生代码进行更改时，您都必须重复构建步骤。
#### iOS
1. 在 Xcode 中打开项目中的 **ios** 目录（该目录由步骤 1 中的 `npx expo prebuild` 生成），运行 `xed ios` 命令。
2. 在 **Pods** > **Development Pods** > **MyModule** 下，打开 **MyModule.swift** 文件。
3. 将 `hello` 函数更改为返回不同的字符串，例如 "Hello world! 🌎🍎"，并保存文件。
4. 通过点击顶部菜单栏中的 **Run** 按钮或按 <kbd>⌘ Cmd</kbd> + <kbd>R</kbd> 来构建您的应用程序，您将看到屏幕上的更改。
每次对原生代码进行更改时，您都必须重复构建步骤。
> **info** **提示**：如果您向模块添加新的原生文件或修改 **expo-module.config.json**，请使用 `npx pod-install` 重新安装 pods。
> **注意**：还可以使用其他流程并行处理 Expo 模块与您的应用程序。例如，您可以使用单一代码库或发布到 npm，具体说明见 [如何在项目中使用独立的 Expo 模块](/modules/use-standalone-expo-module-in-your-project) 指南。
## 使用示例项目创建新模块
Step 1: 
### 创建 Expo 模块
从头开始创建新的 Expo 模块，运行如下 `create-expo-module` 脚本。该脚本会询问您一些问题，然后生成原生 Expo 模块以及一个使用您新模块的 Android 和 iOS 示例应用程序。
```sh
`$ npx create-expo-module@latest my-module`
```
Step 2: 
### 打开模块并启动开发服务器
导航到模块目录，然后运行以下命令打开 Android 和/或 iOS 示例项目：
```sh
`$ cd my-module`
`$ npm run open:android`
`$ npm run open:ios`
```
转到 **example** 目录并在您的终端中启动开发服务器，以便在您编辑原生模块并在下一步构建应用程序时，所做的更改将反映在应用中：
```sh
$ cd example
$ npx expo start
```
> **注意：** 如果您使用 Windows，您可以通过在 Android Studio 中打开 **android** 目录来打开示例项目，但您无法打开 iOS 项目文件。
Step 3: 
### 编辑模块
#### Android
1. 打开 **my-module/android/src/main/java/expo/modules/mymodule/MyModule.kt** 文件。
2. 将 `hello` 函数更改为返回不同的字符串，例如 "Hello world! 🌎🤖"，并保存文件。
3. 通过点击顶部菜单栏中的 **Run 'app'** 按钮构建应用程序，您将看到屏幕上的更改。
每次对原生代码进行更改时，您都必须重复构建步骤。
#### iOS
1. 在 **Pods** > **Development Pods** > **MyModule** 下，打开 **MyModule.swift** 文件。
2. 将 `hello` 函数更改为返回不同的字符串，例如 "Hello world! 🌎🍎"，并保存文件。
3. 通过点击顶部菜单栏中的 **Run** 按钮或按 <kbd>⌘ Cmd</kbd> + <kbd>R</kbd> 来构建您的应用程序，您将看到屏幕上的更改。
每次对原生代码进行更改时，您都必须重复构建步骤。
> **info** **提示**：如果您向模块添加新的原生文件或修改 **expo-module.config.json**，请使用 `npx pod-install` 重新安装 pods。
## 下一步
现在您已经了解了如何初始化一个模块并对其进行简单更改，您可以继续进行教程或直接深入 API 参考。


# 教程

## 教程：创建原生模块

使用 Expo 模块 API 创建持久化设置的原生模块教程。

在本教程中，您将构建一个模块，该模块存储用户首选的应用主题：暗色、亮色或系统。Android 上使用 [`SharedPreferences`](https://developer.android.com/reference/android/content/SharedPreferences)，而在 iOS 上使用 [`UserDefaults`](https://developer.apple.com/documentation/foundation/userdefaults)。您还可以通过 [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) 实现 Web 支持，但本教程不会涵盖这一部分。
Video Tutorial: [观看：如何使用 Expo 模块 API 创建原生模块](https://www.youtube.com/watch?v=CdaQSlyGik8)
---
Step 1: 
## 初始化新模块
首先，创建一个新模块。对于本教程，该模块名为 `expo-settings` 或 `ExpoSettings`。您可以选择不同的名称，但请根据您的选择调整说明。
```sh
$ npx create-expo-module expo-settings
```
> **info** 由于您不打算实际发布这个库，因此您可以在所有提示中按 <kbd>return</kbd> 键以接受默认值。
Step 2: 
## 设置工作区
清理默认模块，以从干净的状态开始。删除视图模块，因为本指南不使用它。
```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
```
找到以下文件并将其内容替换为提供的最小样板：
```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: 
## 运行示例项目
启动 TypeScript 编译器以监视更改。
```sh
$ npm run build
```
在一个单独的终端窗口中，运行示例应用程序。
```sh
$ cd example
$ npx expo run:android
$ npx expo run:ios
```
您将在启动示例应用时在屏幕中央看到文本“主题：系统”。值“system”来自于同步调用原生模块中的 `getTheme()` 函数。您将在下一步中更改该值。
Step 4: 
## 获取、设置和持久化主题偏好值
### Android 原生模块
要读取值，请查找键为“theme”的 `SharedPreferences` 字符串。如果键不存在，则默认值为“system”。使用 `reactContext`（一个 React Native [ContextWrapper](https://developer.android.com/reference/android/content/ContextWrapper)）通过 `getSharedPreferences()` 访问 `SharedPreferences` 实例。
要设置该值，请使用 `SharedPreferences` 的 `edit()` 方法获取 `Editor` 实例。然后，使用 `putString()` 设置值。确保 `setTheme` 函数接受类型为 `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 原生模块
要在 iOS 上读取值，请查找键为“theme”的 `UserDefaults` 字符串。如果键不存在，则默认值为“system”。
要设置该值，请使用 `UserDefaults` 的 `set(_:forKey:)` 方法。确保 `setTheme` 函数接受类型为 `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 模块
更新 **ExpoSettingsModule.ts** 为 `ExpoSettingsModule` 原生模块添加 TypeScript 接口以更新主题。
```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');
```
现在，从 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);
}
```
### 示例应用
您现在可以在示例应用中使用设置 API。
```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();
  // 在暗色和亮色主题之间切换
  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>
  );
}
```
当您重新构建并运行应用程序时，“system”主题仍然被设置。按下按钮不会有任何反应，但重新加载应用程序时，主题会更改。这是因为应用程序没有获取新的主题值或重新渲染。您将在下一步中修复此问题。
Step 5: 
## 发出主题值的变更事件
确保使用您的 API 的开发人员可以通过在值更新时发出变更事件来响应主题值的更改。使用 [Events](/modules/module-api/#events) 定义组件来描述您的模块发出的事件，使用 `sendEvent` 从原生代码发出事件，以及使用 [EventEmitter](/modules/module-api/#sending-events) API 在 JavaScript 中订阅事件。事件负载为 `{ theme: string }`。
### Android 原生模块
事件负载在 Android 上表示为 [`Bundle`](https://developer.android.com/reference/android/os/Bundle.html) 实例，您可以使用 [`bundleOf`](<https://developer.android.com/reference/kotlin/androidx/core/os/package-summary#bundleOf(kotlin.Array)>) 函数创建。
```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 原生模块
```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 模块
```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);
}
```
### 示例应用
```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]);
  // 在暗色和亮色主题之间切换
  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: 
## 使用枚举提高类型安全性
在当前形式下使用 `Settings.setTheme()` API 时容易发生错误，因为它允许任何字符串值。通过使用枚举来限制可能的值为 `system`、`light` 和 `dark`，提高该 API 的类型安全性。
### Android 原生模块
```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 原生模块
```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 模块
```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);
}
```
### 示例应用
如果您将 `Settings.setTheme(nextTheme)` 更改为 `Settings.setTheme("not-a-real-theme")`，TypeScript 将引发错误。如果您忽略错误并按下按钮，您将看到以下运行时错误：
```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)
```
错误消息的最后一行显示 `not-a-real-theme` 不是 `Theme` 枚举的有效值。只有有效值为 `light`、`dark` 和 `system`。
恭喜！您已为 Android 和 iOS 创建了您的第一个 Expo 模块。
## 后续步骤


## 教程：创建本机视图

创建一个本机视图的教程，该视图使用 Expo 模块 API 渲染 WebView。

在本教程中，您将构建一个示例模块，其中包含一个渲染 WebView 的本机视图。对于 Android，您将使用 [`WebView`](https://developer.android.com/reference/android/webkit/WebView) 组件，而对于 iOS，使用 [`WKWebView`](https://developer.apple.com/documentation/webkit/wkwebview)。Web 支持可以通过 [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) 实现，留给您作为练习。
Step 1: 
## 初始化新模块
运行以下命令创建一个新模块，并将示例模块命名为 `expo-web-view`：
```sh
$ npx create-expo-module expo-web-view
```
> **info** 由于这是一个示例库且不会发布，因此对于所有提示，请按 <kbd>return</kbd> 接受默认值。
Step 2: 
## 设置工作区
通过删除以下文件来清理默认模块，以便从干净的状态开始：
```sh
$ cd expo-web-view
$ rm src/ExpoWebView.types.ts src/ExpoWebViewModule.ts
$ rm src/ExpoWebView.web.tsx src/ExpoWebViewModule.web.ts
```
找到以下文件并用提供的最小样板替换它们：
```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: 
## 运行示例项目
为了确保一切正常，启动 TypeScript 编译器以监视更改并重建模块的 JavaScript：
```sh
$ npm run build
```
```sh
$ cd example
$ npx expo run:android
$ npx expo run:ios
```
现在您应该会看到一个空白的紫色屏幕。虽然这不是很激动人心，但这是一个良好的开端。接下来，将其转变为 WebView。
Step 4: 
## 将系统 WebView 添加为子视图
将系统 `WebView` 以硬编码的 URL 添加为 `ExpoWebView` 的子视图。`ExpoWebView` 类扩展了 `ExpoView`，它扩展了来自 React Native 的 `RCTView`，最终在 Android 上扩展为 `View`，在 iOS 上扩展为 `UIView`。
确保 `WebView` 子视图使用与 `ExpoWebView` 相同的布局，其布局由 React Native 的布局引擎计算。
### Android 视图
在 Android 上，使用 `LayoutParams` 设置 WebView 的布局以匹配 `ExpoWebView` 布局。您可以在实例化 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://docs.expo.dev/modules/")
  }
}
```
### iOS 视图
在 iOS 上，将 `clipsToBounds` 设置为 `true`，并确保 WebView 的 `frame` 在 `layoutSubviews` 中与 `ExpoWebView` 的边界匹配。当创建视图时调用 `init` 方法，当布局发生变化时调用 `layoutSubviews`。
```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://docs.expo.dev/modules/")!
    let urlRequest = URLRequest(url:url)
    webView.load(urlRequest)
  }
  override func layoutSubviews() {
    webView.frame = bounds
  }
}
```
### 示例应用
不需要进行更改。使用以下命令重建并运行应用：
```sh
$ npx expo prebuild --clean
$ npx expo run:android
$ npx expo run:ios
```
之后，您将看到 [Expo Modules API 概述页面](/modules/overview) 被渲染。如果更改未反映，尝试重新安装应用。
Step 5: 
## 添加一个属性以设置 URL
要在视图上设置属性，请在 `ExpoWebViewModule` 中定义属性名称和设置器。在这种情况下，您可以直接访问 `webView` 属性以方便使用。然而，在现实场景中，请将逻辑保留在 `ExpoWebView` 类中，以最小化 `ExpoWebViewModule` 对其内部的了解。
使用 [属性定义组件](/modules/module-api/#prop) 来定义属性。在属性设置器块中，您可以访问视图和属性。指定 URL 的类型为 `URL` &mdash; Expo 模块 API 将字符串转换为本地的 `URL` 类型。
### Android 模块
```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 模块
```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 模块
接下来，将 `url` 属性添加到 `Props` 类型。
```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} />;
}
```
### 示例应用
最后，在示例应用中向您的 `WebView` 组件传递一个 `URL`。
```tsx example/App.tsx
import { WebView } from 'expo-web-view';
export default function App() {
  return <WebView style={{ flex: 1 }} url="https://expo.dev" />;
}
```
重建示例应用：
```sh
$ npx expo prebuild --clean
$ npx expo run:android
$ npx expo run:ios
```
之后，您将看到 [Expo 主页](https://expo.dev) 在 WebView 中。
Step 6: 
## 添加事件以通知页面已加载
[视图回调](/modules/module-api/#view-callbacks) 允许开发人员监听组件上的事件。它们通常通过组件上的属性注册，例如：`<Image onLoad={...} />`。使用 [事件定义组件](/modules/module-api/#events) 为您的 WebView 定义一个事件。将其命名为 `onLoad`。
### Android 视图和模块
在 Android 上，重写 `onPageFinished` 函数。然后，调用您在模块中定义的 `onLoad` 事件处理程序。
```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)
  }
}
```
在 `ExpoWebViewModule` 中指明 `View` 具有 `onLoad` 事件。
```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 视图和模块
在 iOS 上，实现 `webView(_:didFinish:)` 并使 `ExpoWebView` 扩展 `WKNavigationDelegate`。然后，从该委托方法调用 `onLoad`。
```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
      ])
    }
  }
}
```
在 `ExpoWebViewModule` 中指明 `View` 具有 `onLoad` 事件。
```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 模块
事件有效负载包含在事件的 `nativeEvent` 属性中。要从 `onLoad` 事件中访问 `url`，请读取 `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} />;
}
```
### 示例应用
更新示例应用，以便在页面加载完成时显示警报。复制以下代码，然后重建并运行您的应用，您将看到警报！
```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: 
## 奖励：围绕它构建一个网页浏览器 UI
现在您有了 WebView，围绕它构建一个网页浏览器 UI。尝试重建一个浏览器 UI，并根据需要添加新的本机功能（例如，后退或重新加载按钮）。如果您需要灵感，请参阅下面的示例。
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://docs.expo.dev/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>
  );
}
```
---
恭喜您！您已经为 Android 和 iOS 创建了第一个包含本机视图的 Expo 模块。
## 下一步


## 教程：创建具有配置插件的模块

一篇关于使用 Expo Modules API 创建本地模块和配置插件的教程。

[配置插件](/config-plugins/introduction/) 让您可以自定义通过 `npx expo prebuild` 生成的本地 Android 和 iOS 项目，适用于 [持续本地生成 (CNG)](/workflow/continuous-native-generation/) 项目。您可以利用它们向本地配置文件添加属性，复制资产到本地项目，或应用高级配置，例如添加 [应用扩展目标](/build-reference/app-extensions/)。
作为应用开发者，配置插件帮助您应用在默认的 [应用配置](/workflow/configuration) 中未公开的自定义设置。作为库作者，它们使您能够为使用您库的开发者自动配置本地项目。
本教程解释了如何从零开始创建一个新的配置插件，并读取您插件注入到 **AndroidManifest.xml** 和 **Info.plist** 中的自定义值。
Step 1: 
## 初始化模块
开始时，用 `create-expo-module` 初始化一个新的 Expo 模块项目。这将设置 Android、iOS 和 TypeScript 的脚手架，并包含一个示例项目以在应用中测试模块。运行以下命令开始：
```sh
$ npx create-expo-module expo-native-configuration
```
本指南使用名称 `expo-native-configuration`/`ExpoNativeConfiguration` 作为模块项目的名称，您可以选择任何您喜欢的名称。
Step 2: 
## 设置工作区
在本示例中，您不需要 `create-expo-module` 包含的视图模块。使用以下命令清理默认模块：
```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
```
找到以下文件并将其替换为提供的最小样板：
- **android/src/main/java/expo/modules/nativeconfiguration/ExpoNativeConfigurationModule.kt**
- **ios/ExpoNativeConfigurationModule.swift**
- **src/ExpoNativeConfigurationModule.ts**
- **src/index.ts**
- **example/App.tsx**
- **package.json**
```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>
  );
}
```
```json package.json
{
  "dependencies": {
    "expo-native-configuration": "file:.."
  }
}
```
Step 3: 
## 运行示例项目
在您的项目根目录中，运行 TypeScript 编译器以观察更改并重新构建模块的 JavaScript：
```sh
$ npm run build
```
在另一个终端窗口中，编译并运行示例应用程序：
```sh
$ cd example
$ rm -rf node_modules && npm install
$ npx expo run:android
$ npx expo run:ios
```
您应该会看到一个显示文本 "API key: api-key" 的屏幕。
Step 4: 
## 创建新的配置插件
[插件](/config-plugins/introduction/#plugin-function) 是接受 `ExpoConfig` 并返回修改过的 `ExpoConfig` 的同步函数。根据约定，这些函数以 `with` 作为前缀。将您的插件命名为 `withMyApiKey`，或使用其他名称，只要遵循这个约定即可。
以下是一个基本配置插件函数的示例：
```js
const withMyApiKey = config => {
  return config;
};
```
您还可以使用 `mods`，它是异步函数，用于修改本地项目中的文件，例如源代码或配置文件 (plist, xml)。`mods` 对象不同于其余的应用配置，因为它在初始读取后不会序列化。这使您可以在代码生成时执行操作。
编写配置插件时，请遵循以下注意事项：
- 插件必须是同步的，其返回值必须是可序列化的，除了添加的任何 `mods`。
- `plugins` 在每次 `expo/config` 的 `getConfig` 方法读取配置时被调用。相比之下，`mods` 仅在 `npx expo prebuild` 的“同步”阶段被调用。
> 尽管是可选的，但使用 [`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)。
开始创建您的插件，使用此最小样板。在 TypeScript 中为编写插件创建一个 **plugin** 目录，并在项目根目录中添加一个 **app.plugin.js** 文件，这将是插件的入口点。
### 创建 plugin/tsconfig.json 文件
```json plugin/tsconfig.json
{
  "extends": "expo-module-scripts/tsconfig.plugin",
  "compilerOptions": {
    "outDir": "build",
    "rootDir": "src"
  },
  "include": ["./src"],
  "exclude": ["**/__mocks__/*", "**/__tests__/*"]
}
```
### 为插件创建一个 plugin/src/index.ts 文件
```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;
```
### 在根目录中创建 app.plugin.js 文件
```js app.plugin.js
// 此文件配置插件的入口文件。
module.exports = require('./plugin/build');
```
在您的项目根目录中运行 `npm run build plugin` 以启动 TypeScript 编译器的观察模式。接下来，通过在 **example/app.json** 文件中添加以下行，配置您的示例项目以使用您的插件：
```json example/app.json
{
  "expo": {
    "plugins": ["../app.plugin.js"]
  }
}
```
当您在 **example** 目录中运行 `npx expo prebuild` 命令时，终端会通过控制台语句记录 "my custom plugin"。
```sh
$ cd example
$ npx expo prebuild --clean
```
要将自定义 API 密钥注入到 **AndroidManifest.xml** 和 **Info.plist** 中，请使用 [`expo/config-plugins`](/config-plugins/plugins-and-mods/#what-are-mods) 提供的帮助器 `mods`。这些帮助器使修改本地文件变得简单。对于这个示例，使用 `withAndroidManifest` 和 `withInfoPlist`。
如其名称所示，`withAndroidManifest` 允许您读取和修改 **AndroidManifest.xml** 文件。使用 `AndroidConfig` 帮助器将元数据项添加到主应用程序，如下所示：
```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;
};
```
同样，您可以使用 `withInfoPlist` 来修改 **Info.plist** 值。使用 `modResults` 属性，您可以添加自定义值，如以下代码片段所示：
```ts
const withMyApiKey: ConfigPlugin<{ apiKey: string }> = (config, { apiKey }) => {
  config = withInfoPlist(config, config => {
    config.modResults['MY_CUSTOM_API_KEY'] = apiKey;
    return config;
  });
  return config;
};
```
您可以通过将所有内容合并到单个函数中创建自定义插件：
```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;
```
插件准备好使用后，更新示例应用程序以将您的 API 密钥作为配置选项传递给插件。将 **example/app.json** 中的 `plugins` 字段修改如下：
```json example/app.json
{
  "expo": {
    "plugins": [["../app.plugin.js", { "apiKey": "custom_secret_api" }]]
  }
}
```
在进行此更改后，通过在 **example** 目录中运行 `npx expo prebuild --clean` 测试插件是否正常工作。此命令会执行您的插件并更新本地文件，将 `"MY_CUSTOM_API_KEY"` 注入到 **AndroidManifest.xml** 和 **Info.plist** 中。您可以通过检查 **example/android/app/src/main/AndroidManifest.xml** 和 **example/ios/exponativeconfigurationexample/Info.plist** 的内容来验证。
Step 5: 
## 从模块读取本地值
现在，让您的本地模块读取添加到 **AndroidManifest.xml** 和 **Info.plist** 中的字段，使用平台特定的方法访问其内容。
在 Android 上，使用 `packageManager` 类访问 **AndroidManifest.xml** 文件中的元数据。要读取 `"MY_CUSTOM_API_KEY"` 值，更新 **android/src/main/java/expo/modules/nativeconfiguration/ExpoNativeConfigurationModule.kt** 文件：
```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")
    }
  }
}
```
在 iOS 上，您可以使用 `Bundle.main.object(forInfoDictionaryKey: "")` 方法读取 **Info.plist** 属性的内容。要访问之前添加的 `"MY_CUSTOM_API_KEY"` 值，请更新 **ios/ExpoNativeConfigurationModule.swift** 文件，如下所示：
```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: 
## 运行您的模块
通过本地模块读取添加到本地文件的字段，您现在可以运行示例应用程序，并通过 `ExamplePlugin.getApiKey()` 函数访问您的自定义 API 密钥。
```sh
$ cd example
$ npx expo prebuild
$ npx expo run:android
$ npx expo run:ios
```
## 后续步骤
恭喜您，您创建了一个与 Android 和 iOS 的 Expo 模块交互的配置插件！
如果您想挑战自己，使插件更具多功能性，欢迎进行此练习。修改插件以允许传入任何任意配置键和值，并添加功能以从模块读取任意键。


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

学习如何在项目中使用使用 create-expo-module 创建的独立模块，方法是使用 monorepo 或将包发布到 npm。

**在现有项目中创建 Expo 模块的推荐方法** 在 [Expo Modules API: 开始使用](/modules/get-started/) 指南中进行了描述。本教程解释了在现有项目中使用 `create-expo-module` 创建的模块的另外两种方法：
- [配置 monorepo](#use-a-monorepo)
- [将模块发布到 npm](#publish-the-module-to-npm)
这些方法在您仍想将模块与应用程序分开或与其他开发人员共享时非常有用。
## 使用 monorepo
您的项目应该使用以下结构：
- **apps**: 存储多个项目的目录，包括 React Native 应用。
- **packages**: 存储您应用使用的不同包的目录。
- **package.json**: 根包文件，其中包含 Yarn 工作区配置。
> **info** 要了解如何将项目配置为 monorepo，请查看 [与 monorepos 一起工作](/guides/monorepos/) 指南。
Step 1: 
### 初始化新模块
一旦设置好基本的 monorepo 结构，使用 `create-expo-module` 创建一个新模块，使用 `--no-example` 标志跳过创建示例应用：
```sh
$ npx create-expo-module packages/expo-settings --no-example
```
Step 2: 
### 设置工作区依赖
将您的本地模块从 **packages** 添加到您应用的依赖中。更新每个使用您本地模块的 **apps** 目录中的 **package.json** 文件，并将您的本地模块添加到现有的依赖项中：
```json package.json
{
  "dependencies": {
    "expo-settings": "*"
  }
}
```
Step 3: 
### 运行模块
运行您的一个应用以确保一切正常。然后，在 **packages/expo-settings** 中启动 TypeScript 编译器以监视更改并重建模块的 JavaScript：
```sh
$ cd packages/expo-settings
$ npm run build
```
打开另一个终端窗口，从 **apps** 目录中选择一个应用，并使用 `--clean` 选项运行 `prebuild` 命令。对您的 monorepo 中的每个应用重复这些步骤以使用新模块。
```sh
$ npx expo prebuild --clean
```
使用以下命令编译并运行应用：
```sh
$ npx expo run:android
$ npx expo run:ios
```
您现在可以在您的应用中使用该模块。要进行测试，请编辑 **app/(tabs)/index.tsx** 文件并渲染来自 `expo-settings` 模块的文本消息：
```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>
  );
}
```
在此配置后，应用显示文本 "Hello world! 👋"。
## 将模块发布到 npm
您可以通过以下步骤在 npm 上发布模块，并将其作为依赖项安装到您的项目中。
Step 1: 
### 初始化新模块
首先创建一个新模块，使用 `create-expo-module`。认真按照提示操作，因为您将发布该库，并为您的 npm 包选择一个唯一的名称。
```sh
$ npx create-expo-module expo-settings
```
Step 2: 
### 运行示例项目
运行您的一个应用以确保一切正常。然后，在项目根目录中启动 TypeScript 编译器，以监视更改并重建模块的 JavaScript：
```sh
$ npm run build
```
打开另一个终端窗口，编译并运行示例应用：
```sh
$ cd example
$ npx expo run:android
$ npx expo run:ios
```
Step 3: 
### 将包发布到 npm
要将包发布到 npm，您需要一个 npm 帐户。如果没有，请在 [npm 网站](https://www.npmjs.com/signup) 上创建一个帐户。创建帐户后，通过运行以下命令登录：
```sh
$ npm login
```
导航到模块的根目录，然后运行以下命令将其发布：
```sh
$ npm publish
```
您的模块现在将发布到 npm，并可以使用 `npm install` 在其他项目中安装。
除了将您的模块发布到 npm，您还可以通过以下方式在项目中使用它：
- **创建 tarball**: 使用 `npm pack` 创建模块的 tarball，然后通过运行 `npm install /path/to/tarball` 将其安装到您的项目中。此方法非常适合在发布之前本地测试模块或与没有访问 npm 注册表的其他人共享。
- **运行本地 npm 注册表**: 使用像 [Verdaccio](https://verdaccio.org/) 这样的工具来托管本地 npm 注册表。您可以从此注册表安装模块，这对于管理公司或组织内部的包非常有用。
- **发布私有包**: [使用 EAS Build 的私有注册表](/build-reference/private-npm-packages/) 安全地管理私有模块。
Step 4: 
### 测试已发布的模块
要在新项目中测试已发布的模块，请创建一个新应用，并通过运行以下命令将模块作为依赖项安装：
```sh
$ npx create-expo-app my-app
$ cd my-app
$ npx expo install expo-settings
```
您现在可以在您的应用中使用该模块！要进行测试，请编辑 **app/(tabs)/index.tsx** 并渲染来自 **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>
  );
}
```
最后，对您的项目进行预构建并通过执行以下命令运行应用：
```sh
$ npx expo prebuild --clean
$ npx expo run:android
$ npx expo run:ios
```
在此配置后，您会在应用中看到文本 "Hello world! 👋"。
## 下一步


## 包装第三方本地库

学习如何使用 Expo Modules API 创建一个简单的包装器，围绕两个独立的本地库。

Expo 模块使得在 React Native 项目中轻松使用为 Android 和 iOS 构建的本地外部库成为可能。本教程重点在于利用 Expo 模块 API 创建径向图，使用两个在这两个本地平台上都可以访问的类似库。
- [MPAndroidChart by PhilJay](https://github.com/PhilJay/MPAndroidChart)
- [Charts by Daniel Cohen Gindi](https://github.com/danielgindi/Charts)
iOS 库受 Android 库的启发，因此它们都具有类似的 API 和功能。这使它们成为本教程的好例子。
Video Tutorial: [如何包装本地库](https://www.youtube.com/watch?v=M8eNfH1o0eE)
---
Step 1: 
## 创建新模块
以下步骤假设新模块是在新的 Expo 项目中创建的。然而，您可以通过遵循替代说明在现有项目中创建新模块。
For 在现有 Expo 项目中: 
另外，您可以将新模块作为视图使用，放在现有 Expo 项目目录中。在项目目录中运行以下命令：
```sh
$ npx create-expo-module --local expo-radial-chart
```
现在，打开新创建的 `modules/expo-radial-chart` 目录以开始编辑本地代码。
For 从新模块开始: 
通过运行以下命令创建一个新的空 Expo 模块，可以在 npm 上发布并在任何 Expo 应用中使用：
```sh
$ npx create-expo-module expo-radial-chart
```
> **info** **提示**：如果您不打算发布此库，请在终端窗口中对所有提示按 <kbd>return</kbd> 接受默认值。
现在，打开新创建的 `expo-radial-chart` 目录以开始编辑本地代码。
Step 2: 
## 运行示例项目
为了验证一切功能正常，让我们运行示例项目。
For 在现有 Expo 项目中: 
如果您是从现有的 Expo 项目开始的，请从 Expo 项目的根目录运行以下命令：
```sh
$ npx expo run:android
$ npx expo run:ios
```
For 在新模块中: 
如果您是从新模块项目开始的，打开终端窗口，启动 TypeScript 编译器以监视更改，并重建模块 JavaScript：
```sh
$ npm run build
```
在另一个终端窗口中，编译并运行示例应用：
```sh
$ cd example-expo-app
$ npx expo run:android
$ npx expo run:ios
```
Step 3: 
## 添加本地依赖
通过编辑 **expo-radial-chart/android/build.gradle** 和 **expo-radial-chart/ios/ExpoRadialChart.podspec** 文件，将本地依赖添加到模块中：
```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 兼容性
```
Note: 你是否尝试使用  依赖？
---
  For SDK 52 及更高版本: 
    在 **android** 目录下，创建另一个名为 **libs** 的目录，并将 **.aar** 文件放入其中。然后，从自动链接中添加该文件作为 Gradle 项目：
```diff expo-module.config.json
    "android": {
+     "gradleAarProjects": [
+       {
+         "name": "test-aar",
+         "aarFilePath": "android/libs/test.aar"
+       }
+     ],
    "modules": [
```
    最后，使用 `${project.name}$` 前缀将依赖项添加到 **android/build.gradle** 文件中的 `dependencies` 列表中：
```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 及更早版本: 
    在 **android** 目录下，创建另一个名为 **libs** 的目录，并将 **.aar** 文件放入其中。然后，将该目录作为一个存储库添加：
```diff android/build.gradle
  repositories {
    mavenCentral()
+   flatDir {
+       dirs 'libs'
+   }
  }
```
最后，将依赖项添加到 `dependencies` 列表中。使用包路径，而不是文件名，包路径在结尾包含 `@aar`：
```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: 你是否尝试使用  或  依赖？
---
在 iOS 上，您还可以通过使用 `vendored_frameworks` 配置选项来使用捆绑为框架的依赖项。
```diff ios/ExpoRadialChart.podspec
    s.static_framework = true
    s.dependency 'ExpoModulesCore'
+   s.vendored_frameworks = 'Frameworks/MyFramework.framework'
    # Swift/Objective-C 兼容性
```
> **info** **注意**：用来指定框架路径的文件模式是相对于 podspec 文件的，并且不支持遍历父目录 (`..`)，这意味着您需要将框架放置在 **ios** 目录中（或 **ios** 的子目录中）。
框架添加后，请确保 `source_files` 选项的文件模式不匹配框架内的任何文件。一种方法是将您的 iOS 源 Swift 文件（即 `ExpoRadialChartView.swift` 和 `ExpoRadialChartModule.swift`）移动到与您放置框架的目录分开的 **src** 目录，并将 `source_files` 选项更新为仅匹配 **src** 目录：
```diff ios/ExpoRadialChart.podspec
- s.source_files = '**/*.{h,m,mm,swift,hpp,cpp}'
+ s.source_files = 'src/**/*.{h,m,mm,swift,hpp,cpp}'
```
您的 **ios** 目录应最终具有类似于以下的文件结构：
```
Frameworks/
│   └── MyFramework.framework
src/
│   ├── ExpoRadialChartView.swift
│   └── ExpoRadialChartModule.swift
ExpoRadialChart.podspec
```
---
Step 4: 
## 定义 API
要在应用程序中使用模块，请为 props 定义类型。它接受一个系列列表&nbsp;— 每个系列都有一个颜色和一个百分比值。
```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[];
};
```
由于本示例中未为 Web 实现模块，因此让我们替换 **src/ExpoRadialChartView.web.tsx** 文件：
```tsx src/ExpoRadialChartView.web.tsx
import * as React from 'react';
export default function ExpoRadialChartView() {
  return <div>未实现</div>;
}
```
Step 5: 
## 在 Android 上实现模块
现在您可以通过编辑占位符文件，使用以下更改来实现本地功能：
1. 创建一个 `PieChart` 实例，并将其 `layoutParams` 设置为与父视图匹配。然后，使用 `addView` 函数将其添加到视图层次结构。
2. 定义一个 `setChartData` 函数，该函数接受一个 `Series` 对象的列表。您可以遍历列表，为每个系列创建一个 `PieEntry` 并将颜色存储在一个单独的列表中。
3. 创建一个 `PieDataSet`，用它创建一个 `PieData` 对象，并将其设置为 `PieChart` 实例的数据。
```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();
  }
}
```
您还需要使用 [`Prop`](/modules/module-api/#prop) 函数定义 `data` prop，并在 prop 更改时调用本地 `setChartData` 函数：
```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: 
## 在 iOS 上实现模块
现在您可以通过编辑占位符文件，使用以下更改来实现本地功能：
1. 创建一个新的 `PieChartView` 实例，并使用 `addSubview` 函数将其添加到视图层次结构。
2. 设置 `clipsToBounds` 属性，并重写 `layoutSubviews` 函数，以确保图表视图始终与父视图大小相同。
3. 创建一个 `setChartData` 函数，该函数接受一系列，使用数据创建一个 `PieChartDataSet` 实例，并将其分配给 `PieChartView` 实例的 `data` 属性。
```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
  }
}
```
您还需要使用 [`Prop`](/modules/module-api/#prop) 函数定义 `data` prop，并在 prop 更改时调用本地 `setChartData` 函数：
```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: 
## 编写示例应用以使用模块
您可以更新 **app** 目录中的应用来测试模块。使用 `ExpoRadialChartView` 组件渲染一个有三个切片的饼图：
```tsx app/(tabs)/index.tsx
import { ExpoRadialChartView } from '@/modules/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** **提示**：如果您创建了一个新模块，请确保将导入语句更新为：`import { ExpoRadialChartView } from 'expo-radial-chart';`
Step 8: 
## 重建并启动您的应用程序
为了确保您的应用在两个平台上都能成功构建，请从步骤 2 中重新运行构建命令。在任何平台成功构建应用后，您将看到一个有三个切片的饼图：
恭喜！您已经使用 Expo 模块 API 创建了围绕两个独立第三方本地库的第一个简单包装器。
## 下一步


## 在现有库中集成

学习如何将 Expo 模块 API 集成到现有的 React Native 库中。

有些情况下，您可能希望将 Expo 模块 API 集成到现有的 React Native 库中。例如，逐步重写您的库，或者利用 [Android 生命周期监听器](/modules/android-lifecycle-listeners/) 和 [iOS AppDelegate 订阅者](/modules/appdelegate-subscribers/) 来自动设置库，可能会很有用。
本指南将帮助您设置现有的 React Native 库以访问 Expo 模块 API。
## 先决条件
在您项目的根目录下创建 [**expo-module.config.json**](/modules/module-config/) 文件，并在其中添加一个空对象 `{}`。您稍后将填写它以启用特定功能。
创建此文件对于 [Expo 自动链接](/modules/autolinking/) 识别您的库为 Expo 模块并自动链接您的本机代码是必要的。
Step 1: 
## 添加 `expo-modules-core` 本机依赖
在您的 **build.gradle** 和 **podspec** 文件中将 `expo-modules-core` 添加为依赖项：
```groovy
// ...
dependencies {
  // ...
  implementation project(':expo-modules-core')
}
```
```ruby
# ...
Pod::Spec.new do |s|
  # ...
  s.dependency 'ExpoModulesCore'
end
```
Step 2: 
## 将 Expo 包添加为依赖项
在您的 **package.json** 中将 `expo` 包添加为对等依赖 &mdash; 我们推荐使用 `*` 作为版本范围，以避免在用户的 **node_modules** 目录中造成任何重复的包。
您的库还需要依赖于 `expo-modules-core`，但仅作为开发依赖 &mdash; 它已经由依赖于您库的项目中的 `expo` 包提供，版本与项目中使用的特定 SDK 兼容。
```json package.json
{
  "devDependencies": {
    "expo-modules-core": "^X.Y.Z"
  },
  "peerDependencies": {
    "expo": "*"
  },
  "peerDependenciesMeta": {
    "expo": {
      "optional": true
    }
  }
}
```
Step 3: 
## 创建本机模块
根据下面的模板创建 Kotlin 和 Swift 文件：
```kotlin
package my.module.package
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
class MyModule : Module() {
  override fun definition() = ModuleDefinition {
    // 定义组件在此处
  }
}
```
```swift
import ExpoModulesCore
public class MyModule: Module {
  public func definition() -> ModuleDefinition {
    // 定义组件在此处
  }
}
```
然后，将您的类添加到 [**expo-module.config.json**](/modules/module-config/) 文件的 Android 和/或 iOS `modules` 中。Expo 自动链接将自动将这些类链接为用户项目中的本机模块。
```json expo-module.config.json
{
  "ios": {
    "modules": ["MyModule"]
  },
  "android": {
    "modules": ["my.module.package.MyModule"]
  }
}
```
如果您在工作区中已经有一个示例应用，请确保模块正确链接。
- **在 Android** 中，本机模块类将在构建之前作为 Gradle 构建任务的一部分自动链接。
- **在 iOS** 中，您需要运行 `pod install` 来链接新类。
这些模块类现在可以通过 `expo-modules-core` 包中的 `requireNativeModule` 函数从 JavaScript 代码访问。我们建议创建一个单独的文件，导出本机模块以简化操作。
```ts MyModule.ts
import { requireNativeModule } from 'expo-modules-core';
export default requireNativeModule('MyModule');
```
现在类已经设置并链接，您可以开始实现其功能。请参阅 [本机模块 API](/modules/module-api/) 参考页和链接到 [示例](/modules/module-api/#examples) 的简单到中等复杂的实际模块，以了解如何使用 API。


## 额外平台支持

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

Expo Modules API 为 Android 和 iOS 提供了高级支持。然而，由于所有 Apple 平台都基于相同的基础并使用相同的编程语言，因此在 Expo 模块中针对其他 [Out-of-Tree 平台](https://reactnative.dev/docs/out-of-tree-platforms) 是可能的。
目前，仅支持 **macOS** 和 **tvOS** 平台。本指南将指导您添加对这些平台的支持。
Step 1: 
## 在 `expo-module.config.json` 中使用 `"apple"` 平台
为了无缝支持其他 Apple 平台，Expo SDK 引入了一个通用的 `"apple"` 平台，以指示 [autolinking](/modules/autolinking/) 模块可以支持任何 Apple 平台，并且在特定 CocoaPods 目标上链接模块的决定转移到 podspec。如果您之前使用过 `"ios"`，可以安全替换为：
```diff expo-module.config.json
{
-   "platforms": ["ios"],
-   "ios": {
-     "modules": ["MyModule"]
-   }
+   "platforms": ["apple"],
+   "apple": {
+     "modules": ["MyModule"]
+   }
}
```
Step 2: 
## 更新 podspec 以声明对其他平台的支持
模块的 podspec 需要更新受支持平台的列表。否则，CocoaPods 将无法在其他平台的目标上安装 pod。如第一步所述，规范的这一部分是当模块配置为通用的 `"apple"` 平台时，autolinking 的真实来源。
```diff Module's podspec
- s.platform       = :ios, '13.4'
+ s.platforms = {
+   :ios => '13.4',
+   :tvos => '13.4',
+   :osx => '10.15'
+ }
```
对 podspec 的任何更改都需要运行 `pod install` 才能生效。
Step 3: 
## 在应用中设置 `react-native-macos` 或 `react-native-tvos`
如果您正在编写本地模块，并且您的应用已设置，可以跳过此步骤。否则，如果您正在编写独立的（非本地）模块，则需要设置您的应用或示例应用。
- **对于 macOS**：请遵循 `react-native-macos` 文档中的官方 [安装 macOS 的 React Native](https://microsoft.github.io/react-native-windows/docs/rnm-getting-started#install-the-macos-extension) 指南。
- **对于 tvOS**：请遵循 [`react-native-tvos`](https://github.com/react-native-tvos/react-native-tvos) 存储库中的说明。如果您正在构建 Expo 应用，还应遵循 [构建 Expo 应用用于 TV 指南](/guides/building-for-tv/) 中的说明。
Step 4: 
## 审查使用在这些平台上不支持的 API 的代码
平台 API 可能在 Apple 平台之间有所不同。最明显的区别来自于依赖不同的 UI 框架 &mdash; iOS/tvOS 上的 `UIKit` 和 macOS 上的 `AppKit`。
`react-native-macos` 和 `expo-modules-core` 都提供别名和填充程序，以引用 macOS 目标上的 `UIKit` 类（例如，`UIView` 是 `NSView` 的别名，`UIApplication` 是 `NSApplication` 的别名），但通常对于以 iOS 为主的库来说，直接支持其他平台是不够的。您可能需要编写有条件编译的代码，根据平台使用不同的实现。
为此，使用 Swift 编译器指令和 `os` 条件，当我们的应用为特定平台构建时，包含给定的代码块。结合 `#if` 和 `#else` 指令，可以在跨平台代码中设置特定于平台的分支。
```swift
#if os(iOS)
  // iOS 实现
#elseif os(macOS)
  // macOS 实现
#elseif os(tvOS)
  // tvOS 实现
#endif
```
您的模块现在可以在 Out-of-Tree 平台上使用。


# 参考

## 模块 API 参考

Expo 模块 API 的 API 参考。

原生模块 API 是建立在 [JSI](https://reactnative.dev/architecture/glossary#javascript-interfaces-jsi) 及其他 React Native 构建的低级原语之上的一个抽象层。它使用现代语言（Swift 和 Kotlin）构建，并提供一个易于使用且方便的 API，使其在可能的情况下跨平台一致。
## 定义组件
正如您可能在 [入门](/modules/get-started) 页面上的片段中注意到的，每个模块类必须实现 `definition` 函数。
模块定义由描述模块功能和行为的 DSL 组件组成。
#### 名称
设置 JavaScript 代码将用于引用模块的模块名称。接受一个字符串作为参数。这可以从模块的类名推导出来，但建议为了清晰起见明确设置。
```swift Swift / Kotlin
Name("MyModuleName")
```
#### 常量
在 JavaScript 对象上定义一个常量属性。该属性仅在首次访问时计算，后续访问将返回缓存值。
```swift
Constant("PI") {
  Double.pi
}
```
```kotlin
Constant("PI") {
  Math.PI
}
```
#### 函数
定义一个将导出到 JavaScript 的本机同步函数。同步意味着当函数在 JavaScript 中执行时，它的本机代码在同一线程上运行，并阻止脚本的进一步执行，直到本机函数返回。
#### 参数
- **name**: `String` — 您将从 JavaScript 中调用的函数名称。
- **body**: `(args...) -> ReturnType` — 函数调用时要运行的闭包。
该函数最多可以接收 8 个参数。这是由于 Swift 和 Kotlin 中的泛型限制，因为此组件必须为每种参数数目单独实现。
有关可以在函数体中使用的类型的更多详细信息，请参见 [参数类型](#argument-types) 部分。
```swift
Function("mySyncFunction") { (message: String) in
  return message
}
```
```kotlin
Function("mySyncFunction") { message: String ->
  return@Function message
}
```
```js JavaScript
import { requireNativeModule } from 'expo-modules-core';
// 假设我们将模块命名为 "MyModule"
const MyModule = requireNativeModule('MyModule');
function getMessage() {
  return MyModule.mySyncFunction('bar');
}
```
#### AsyncFunction
定义一个始终返回 `Promise` 的 JavaScript 函数，并且默认情况下其本机代码将在与 JavaScript 运行时不同的线程上调度。
#### 参数
- **name**: `String` — 您将从 JavaScript 中调用的函数名称。
- **body**: `(args...) -> ReturnType` — 函数调用时要运行的闭包。
如果最后一个参数的类型是 `Promise`，该函数将在响应返回给 JavaScript 之前等待该 Promise 被解析或拒绝。否则，函数将立即用返回值解析或在抛出异常时拒绝。
该函数最多可以接收 8 个参数（包括 Promise）。
有关可以在函数体中使用的类型的更多详细信息，请参见 [参数类型](#argument-types) 部分。
当 `AsyncFunction` 在以下情况下更建议使用：
- 执行 I/O 绑定任务，例如发送网络请求或与文件系统交互
- 需要在不同线程上运行，例如，UI 相关任务的主 UI 线程
- 是大量或长时间运行的操作，这将阻塞 JavaScript 线程，从而减少应用程序的响应性
```swift
AsyncFunction("myAsyncFunction") { (message: String) in
  return message
}
// 或
AsyncFunction("myAsyncFunction") { (message: String, promise: Promise) in
  promise.resolve(message)
}
```
```kotlin
AsyncFunction("myAsyncFunction") { message: String ->
  return@AsyncFunction message
}
// 或
// 确保从 `expo.modules.kotlin` 导入 `Promise` 类，而不是 `expo.modules.core`。
AsyncFunction("myAsyncFunction") { message: String, promise: Promise ->
  promise.resolve(message)
}
```
```js JavaScript
import { requireNativeModule } from 'expo-modules-core';
// 假设我们将模块命名为 "MyModule"
const MyModule = requireNativeModule('MyModule');
async function getMessageAsync() {
  return await MyModule.myAsyncFunction('bar');
}
```
可以通过在该组件的结果上调用 `.runOnQueue` 函数来更改 `AsyncFunction` 的本机队列。
```swift
AsyncFunction("myAsyncFunction") { (message: String) in
  return message
}.runOnQueue(.main)
```
```kotlin
AsyncFunction("myAsyncFunction") { message: String ->
  return@AsyncFunction message
}.runOnQueue(Queues.MAIN)
```
---
#### Kotlin 协程 <PlatformTags prefix="" platforms={['android']} /
`AsyncFunction` 可以在 Android 上接收可挂起的主体。然而，它必须在 `Coroutine` 块后用中缀语法传入。您可以在 [协程概述](https://kotlinlang.org/docs/coroutines-overview.html) 上了解有关可挂起函数和协程的更多信息。
带有可挂起主体的 `AsyncFunction` 不能接收 `Promise` 作为参数。它使用挂起机制来执行异步调用。
函数将立即解析为提供的可挂起块的返回值，或在抛出异常时拒绝。该函数最多可以接收 8 个参数。
默认情况下，挂起函数在模块的协程范围内调度。此外，从主体块调用的每个其他可挂起函数都在同一范围内运行。
该范围的生命周期与模块的生命周期绑定 - 当模块被解除分配时，所有未完成的挂起函数将被取消。
```kotlin Kotlin
AsyncFunction("suspendFunction") Coroutine { message: String ->
  // 您可以在此处执行其他可挂起函数。
  // 例如，您可以使用 `kotlinx.coroutines.delay` 延迟解析底层 promise。
  delay(5000)
  return@Coroutine message
}
```
#### 事件
定义模块可以发送到 JavaScript 的事件名称。
> **注意:** 该组件可用在 [`View`](#view) 块内以定义回调名称。请参见 [`View 回调`](#view-callbacks)
```swift
Events("onCameraReady", "onPictureSaved", "onBarCodeScanned")
```
```kotlin
Events("onCameraReady", "onPictureSaved", "onBarCodeScanned")
```
请参见 [发送事件](#sending-events) 了解如何从本机代码发送事件到 JavaScript/TypeScript。
#### 属性
在表示原生模块的 JavaScript 对象上直接定义一个新属性。它与在模块对象上调用 [`Object.defineProperty`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) 是相同的。
要声明只读属性，您可以使用需要两个参数的简写语法：
- **name**: `String` — 您将从 JavaScript 使用的属性名称。
- **getter**: `() -> PropertyType` — 当调用属性的 getter 时要运行的闭包。
```swift
Property("foo") {
  return "bar"
}
```
```kotlin
Property("foo") {
  return@Property "bar"
}
```
在可变属性的情况下，getter 和 setter 闭包都是必需的（使用下面的语法也可以声明仅具有 setter 的属性）：
- **name**: `String` — 您将从 JavaScript 使用的属性名称。
- **getter**: `() -> PropertyType` — 当调用属性的 getter 时要运行的闭包。
- **setter**: `(newValue: PropertyType) -> void` — 当调用属性的 setter 时要运行的闭包。
```swift
Property("foo")
  .get { return "bar" }
  .set { (newValue: String) in
    // 对新值执行某些操作
  }
```
```kotlin
Property("foo")
  .get { return@get "bar" }
  .set { newValue: String ->
    // 对新值执行某些操作
  }
```
```js JavaScript
import { requireNativeModule } from 'expo-modules-core';
// 假设我们将模块命名为 "MyModule"
const MyModule = requireNativeModule('MyModule');
// 获取属性值
MyModule.foo;
// 设置新值
MyModule.foo = 'foobar';
```
#### 视图
使模块能够作为本机视图使用。视图定义中接受的定义组件：[`Prop`](#prop), [`Events`](#events), [`GroupView`](#groupview) 和 [`AsyncFunction`](#asyncfunction)。
在视图定义中的 [`AsyncFunction`](#asyncfunction) 将添加到表示本机视图的 React 组件的 React 引用。
此类异步函数会自动将本机视图的实例作为第一个参数接收，默认在 UI 线程上运行。
#### 参数
- **viewType** — 将被渲染的本机视图的类。注意：在 Android 上，提供的类必须继承自 [`ExpoView`](#expoview)，在 iOS 上是可选的。请参见 [`扩展 ExpoView`](#extending--expoview)。
- **definition**: `() -> ViewDefinition` — 视图定义的构建器。
```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 视图。
#### OnCreate
定义模块的生命周期监听器，该监听器在模块初始化后立即被调用。如果您需要在模块初始化时设置某些内容，请使用此方法，而不是模块的类初始化器。
#### OnDestroy
定义模块的生命周期监听器，该监听器在模块即将被解除分配时调用。请使用此方法取代模块的类析构函数。
#### OnStartObserving
定义当第一个事件监听器被添加时调用的函数。
#### OnStopObserving
定义当所有事件监听器被移除时调用的函数。
#### OnAppContextDestroys
定义模块的生命周期监听器，该监听器在拥有模块的应用上下文即将被解除分配时调用。
#### OnAppEntersForeground, Android only
定义当应用即将进入前台模式时调用的监听器。
> **注意:** 此函数在 Android 上不可用 — 您可能想要使用 [`OnActivityEntersForeground`](#onactivityentersforeground)。
#### OnAppEntersBackground, Android only
定义当应用进入背景模式时调用的监听器。
> **注意:** 此函数在 Android 上不可用 — 您可能想要使用 [`OnActivityEntersBackground`](#onactivityentersbackground) 代替。
#### OnAppBecomesActive, Android only
定义当应用再次变为活动状态时调用的监听器（在 `OnAppEntersForeground` 之后）。
> **注意:** 此函数在 Android 上不可用 — 您可能想要使用 [`OnActivityEntersForeground`](#onactivityentersforeground)。
#### OnActivityEntersForeground, Android only
定义活动生命周期监听器，该监听器在活动恢复后立即调用。
> **注意:** 此函数在 iOS 上不可用 — 您可能想要使用 [`OnAppEntersForeground`](#onappentersforeground) 替代。
#### OnActivityEntersBackground, Android only
定义活动生命周期监听器，该监听器在活动暂停后立即调用。
> **注意:** 此函数在 iOS 上不可用 — 您可能想要使用 [`OnAppEntersBackground`](#onappentersbackground) 代替。
#### OnActivityDestroys, Android only
定义活动生命周期监听器，该监听器在拥有 JavaScript 上下文的活动即将被销毁时调用。
> **注意:** 此函数在 iOS 上不可用 — 您可能想要使用 [`OnAppEntersBackground`](#onappentersbackground) 代替。
#### OnActivityResult, Android only
定义活动生命周期监听器，该监听器在使用 `startActivityForResult` 启动的活动返回结果时调用。
#### 参数
- **activity** — 收到结果的 Android 活动。
- **payload** — 一个包含活动结果数据的对象。
  - **requestCode**: `Int` — 最初提供给 `startActivityForResult` 的请求代码，用于识别结果的来源。
  - **resultCode**: `Int` — 子活动返回的结果代码（例如，`Activity.RESULT_OK` 或 `Activity.RESULT_CANCELED`）。
  - **data** — 可选的意图，携带从启动的活动返回的结果数据。可以为 `null`。
```kotlin Kotlin
AsyncFunction('someFunc') {
  activity.startActivityForResult(someIntent, SOME_REQUEST_CODE)
}
OnActivityResult { activity, payload ->
}
```
#### 常量
> **警告** **已弃用:** 请改用 [`Constant`](#constant)。
在模块上设置常量属性。可以接受字典或返回字典的闭包。
```swift
// 从字典创建
Constants([
  "PI": Double.pi
])
// 或由闭包返回
Constants {
  return [
    "PI": Double.pi
  ]
}
```
```kotlin
// 作为参数传递
Constants(
  "PI" to kotlin.math.PI
)
// 或由闭包返回
Constants {
  return@Constants mapOf(
    "PI" to kotlin.math.PI
  )
}
```
## 视图定义组件
视图定义由描述视图功能和行为的 DSL 组件组成。这些组件只能在 [`View`](#view) 闭包中使用。
#### 名称
设置 JavaScript 代码将用于引用视图的视图名称。接受一个字符串作为参数。这可以从视图的类名推导出来，但为了清晰起见建议显式设置。
```swift Swift / Kotlin
Name("MyViewName")
```
#### Prop
定义给定名称的视图属性的 setter。
#### 参数
- **name**: `String` — 您希望定义 setter 的视图属性的名称。
- **defaultValue**: `ValueType` — 当 setter 被调用时使用的可选默认值，值为 `null`。
- **setter**: `(view: ViewType, value: ValueType) -> ()` — 在视图重新渲染时调用的闭包。
此属性只能在 [`View`](#view) 闭包中使用。
```swift
Prop("background") { (view: UIView, color: UIColor) in
  view.backgroundColor = color
}
```
```kotlin
Prop("background") { view: View, @ColorInt color: Int ->
  view.setBackgroundColor(color)
}
```
具有默认值的属性定义。
```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)
}
```
> **注意:** 目前不支持函数类型（回调）的属性。
#### OnViewDidUpdateProps
定义视图生命周期方法，当视图完成更新所有属性时调用。
```swift
View(MyView.self) {
  OnViewDidUpdateProps { view: MyView in
  }
}
```
```kotlin
View(MyView::class) {
  OnViewDidUpdateProps { view: MyView ->
  }
}
```
#### (View) AsyncFunction
与模块定义中的 [`AsyncFunction`](#asyncfunction) 类似，您可以定义附加到视图引用的函数，以允许直接修改本机视图。
视图异步函数将始终在主队列上调度，并可以将视图实例作为第一个参数接收。
```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)。
#### 参数
- **viewType** — 本机视图的类。注意，提供的类必须继承自 Android `ViewGroup`。
- **definition**: `() -> ViewGroupDefinition` — 视图组定义的构建器。
此属性只能在 [`View`](#view) 闭包中使用。
```kotlin Kotlin
GroupView<ViewGroup> {
}
```
#### AddChildView, Android only
定义将子视图添加到视图组的动作。
#### 参数
- **action**: `(parent: ParentType, child: ChildType, index: Int) -> ()` — 将子视图添加到视图组的动作。
此属性只能在 [`GroupView`](#groupview) 闭包中使用。
```kotlin Kotlin
AddChildView { parent, child: View, index ->
  parent.addView(child, index)
}
```
#### GetChildCount, Android only
定义获取视图组中子视图数量的动作。
#### 参数
- **action**: `(parent: ParentType) -> Int` — 返回子视图数量的函数。
此属性只能在 [`GroupView`](#groupview) 闭包中使用。
```kotlin Kotlin
GetChildCount { parent ->
  return@GetChildCount parent.childCount
}
```
#### GetChildViewAt, Android only
定义从视图组中检索特定索引的子视图的动作。
#### 参数
- **action**: `(parent: ParentType, index: Int) -> ChildType` — 从视图组检索特定索引的子视图的函数。
此属性只能在 [`GroupView`](#groupview) 闭包中使用。
```kotlin Kotlin
GetChildViewAt { parent, index ->
  parent.getChildAt(index)
}
```
#### RemoveChildView, Android only
定义从视图组中移除特定子视图的动作。
#### 参数
- **action**: `(parent: ParentType, child: ChildType) -> ()` — 从视图组中移除特定子视图的函数。
此属性只能在 [`GroupView`](#groupview) 闭包中使用。
```kotlin Kotlin
RemoveChildView { parent, child: View ->
  parent.removeView(child)
}
```
#### RemoveChildViewAt, Android only
定义从视图组中移除特定索引的子视图的动作。
#### 参数
- **action**: `(parent: ParentType, child: ChildType) -> ()` — 从视图组中移除在特定索引的子视图的函数。
此属性只能在 [`GroupView`](#groupview) 闭包中使用。
```kotlin Kotlin
RemoveChildViewAt { parent, index ->
  parent.removeViewAt(child)
}
```
## 参数类型
从根本上说，只有原始类型和可序列化数据可以在线程之间来回传递。然而，通常原生模块需要接收自定义数据结构——比只带值为未知（`Any`）类型的字典/映射更复杂，因此每个值必须单独验证和转换。Expo 模块 API 提供协议，使得处理数据对象更为方便，提供自动验证，最终确保每个对象成员的本机类型安全。
#### 原始类型
所有函数和视图属性 setter 接受所有 Swift 和 Kotlin 中的公共原始类型作为参数。这包括原始类型的数组、字典/映射和可选值。
| 语言   | 支持的原始类型                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Swift  | `Bool`, `Int`, `Int8`, `Int16`, `Int32`, `Int64`, `UInt`, `UInt8`, `UInt16`, `UInt32`, `UInt64`, `Float32`, `Double`, `String` |
| Kotlin | `Boolean`, `Int`, `Long`, `Float`, `Double`, `String`, `Pair`                                                                  |
#### 可转换类型
_可转换类型_ 是指可以从某些特定类型的数据（从 JavaScript 接收）初始化的本机类型。这种类型可以作为 `Function` 主体中的参数类型使用。例如，当 `CGPoint` 类型作为函数参数类型使用时，其实例可以从一个包含两个数字的数组 `(x, y)` 或一个具有数值 `x` 和 `y` 属性的 JavaScript 对象创建。
内置的可转换类型在 [后面](#built-in-convertibles) 中有更详细的文档。您可以通过使本机 Swift 类型符合 `Convertible` 协议来定义额外的可转换类型：
#### Convertible, Android only
`Convertible` 是一个 Swift 协议，具有一个静态方法：
<APIMethod
  name="convert"
  comment="一个将动态类型的值从 JavaScript 转换为符合 `Convertible` 的 Swift 类型实例的静态方法。实现者应在给定值无效或类型不受支持时抛出异常。"
  returnTypeName="Self"
  parameters={[
    {
      name: 'value',
      comment: '要转换的来自 JavaScript 的值',
      typeName: 'Any?',
    },
    {
      name: 'appContext',
      comment: '当前运行 Expo 应用实例的上下文对象',
      typeName: 'AppContext',
    },
  ]}
/>
### 示例
```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)
  }
}
```
> **信息** 支持使用 Kotlin 定义可转换类型计划将在 SDK 53 可用。
---
## 内置可转换类型
一些来自 `CoreGraphics` 和 `UIKit` 系统框架的常见 iOS 类型已经被设置为可转换。
| 原生 iOS 类型           | TypeScript                                                                                                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `URL`                   | `string` 具有 URL。当未提供方案时，假设为文件 URL。                                                                                                            |
| `CGFloat`               | `number`                                                                                                                                                       |
| `CGPoint`               | `{ x: number, y: number }` 或 `number[]` 具有 _x_ 和 _y_ 坐标                                                                                                  |
| `CGSize`                | `{ width: number, height: number }` 或 `number[]` 具有 _width_ 和 _height_                                                                                     |
| `CGVector`              | `{ dx: number, dy: number }` 或 `number[]` 具有 _dx_ 和 _dy_ 向量差异                                                                                          |
| `CGRect`                | `{ x: number, y: number, width: number, height: number }` 或 `number[]` 具有 _x_, _y_, _width_ 和 _height_ 值                                                  |
| `CGColor``UIColor` | 颜色十六进制字符串（`#RRGGBB`, `#RRGGBBAA`, `#RGB`, `#RGBA`），遵循 [CSS3/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 类型也被设置为可转换。
> **注意:** 在 Android 上，尽可能使用原始数组。
| 原生 Android 类型                                                                         | 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`），遵循 [CSS3/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+" />                                                                                                       |
#### 记录
`记录` 是可转换类型，是字典（Swift）或映射（Kotlin）的等价物，但表示为一个结构体，每个字段可以具有其类型并提供默认值。
它是表示具有本机类型安全的 JavaScript 对象的更好方式。
```swift
struct FileReadOptions: Record {
  @Field
  var encoding: String = "utf8"
  @Field
  var position: Int = 0
  @Field
  var length: Int?
}
// 现在该记录可以用作函数或视图属性 setter 的参数。
Function("readFile") { (path: String, options: FileReadOptions) -> String in
  // 使用给定的 `options` 读取文件
}
```
```kotlin
class FileReadOptions : Record {
  @Field
  val encoding: String = "utf8"
  @Field
  val position: Int = 0
  @Field
  val length: Int? = null
}
// 现在该记录可以用作函数或视图属性 setter 的参数。
Function("readFile") { path: String, options: FileReadOptions ->
  // 使用给定的 `options` 读取文件
}
```
#### 枚举
使用枚举，我们可以更进一步，限制上述示例（使用 `FileReadOptions` 记录）支持的编码为 `"utf8"` 和 `"base64"`。要使用枚举作为参数或记录字段，它必须表示原始值（例如，`String`，`Int`），并遵循 `Enumerable`。
```swift
enum FileEncoding: String, Enumerable {
  case utf8
  case base64
}
struct FileReadOptions: Record {
  @Field
  var encoding: FileEncoding = .utf8
}
```
```kotlin
// 注意：构造函数必须带有一个名为 value 的参数。
enum class FileEncoding(val value: String) : Enumerable {
  utf8("utf8"),
  base64("base64")
}
class FileReadOptions : Record {
  @Field
  val encoding: FileEncoding = FileEncoding.utf8
}
```
#### 双重类型
有一些用例需要将不同的类型传递给单个函数参数。这时，双重类型可能会有用。
它们作为某几种类型中的一种的值的容器。
```swift
Function("foo") { (bar: Either<String, Int>) in
  if let bar: String = bar.get() {
    // `bar` 是一个字符串
  }
  if let bar: Int = bar.get() {
    // `bar` 是一个整数
  }
}
```
```kotlin
Function("foo") { bar: Either<String, Int> ->
  bar.get(String::class).let {
    // `it` 是一个字符串
  }
  bar.get(Int::class).let {
    // `it` 是一个整数
  }
}
```
目前提供三种双重类型的实现，允许您使用多达四种不同的子类型。
- `Either<FirstType, SecondType>` — 两种类型之一的容器。
- `EitherOfThree<FirstType, SecondType, ThirdType>` — 三种类型之一的容器。
- `EitherOfFour<FirstType, SecondType, ThirdType, FourthType>` — 四种类型之一的容器。
#### JavaScript 值
也可以使用 `JavaScriptValue` 类型，这是一个可以表示于 JavaScript 中的任何值的持有者。
当您要修改给定参数或想要省略类型验证和转换时，此类型非常有用。
请注意，使用特定于 JavaScript 的类型限制在同步函数中，因为 JavaScript 运行时中的所有读取和写入必须在线程中进行。
从不同线程访问这些值将导致崩溃。
除了原始值外，可以使用 `JavaScriptObject` 类型仅允许对象类型，`JavaScriptFunction<ReturnType>` 用于回调。
```swift
Function("mutateMe") { (value: JavaScriptValue) in
  if value.isObject() {
    let jsObject = value.getObject()
    jsObject.setProperty("expo", value: "modules")
  }
}
// 或
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")
  }
}
// 或
Function("mutateMe") { jsObject: JavaScriptObject ->
  jsObject.setProperty("expo", "modules")
}
```
## 本机类
#### 模块
原生模块的基类。
#### 属性
<APIMethod
  name="appContext"
  comment="提供对 [`AppContext`](#appcontext) 的访问。"
  returnTypeName="AppContext"
  isProperty
  isReturnTypeReference
/>
#### 方法
<APIMethod
  name="sendEvent"
  comment="使用给定名称和有效负载将事件发送到 JavaScript。请参见 [`发送事件`](#sending-events)"
  returnTypeName="void"
  parameters={[
    {
      name: 'eventName',
      comment: 'JavaScript 事件的名称',
      typeName: 'string',
    },
    {
      name: 'payload',
      comment: '事件有效负载',
      typeName: 'Android: Map<String, Any?> | Bundle\niOS: [String: Any?]',
    },
  ]}
/>
#### AppContext
应用上下文是单个 Expo 应用的接口。
#### 属性
<APIMethod
  name="constants"
  comment="提供对传统模块注册表中的应用常量的访问。"
  returnTypeName="Android: ConstantsInterface? iOS: EXConstantsInterface?"
  isProperty
/>
<APIMethod
  name="permissions"
  comment="提供对传统模块注册表中的权限管理器的访问。"
  returnTypeName="Android: Permissions? iOS: EXPermissionsInterface?"
  isProperty
/>
<APIMethod
  name="imageLoader"
  comment="提供对传统模块注册表中的图像加载器的访问。"
  returnTypeName="Android: ImageLoaderInterface? iOS: EXImageLoaderInterface?"
  isProperty
/>
<APIMethod
  name="barcodeScanner"
  comment="提供对传统模块注册表中的条形码扫描器管理器的访问。"
  returnTypeName="ImageLoaderInterface?"
  isProperty
  platforms={['Android']}
/>
<APIMethod
  name="camera"
  comment="提供对传统模块注册表中的相机视图管理器的访问。"
  returnTypeName="CameraViewInterface?"
  isProperty
  platforms={['Android']}
/>
<APIMethod
  name="font"
  comment="提供对传统模块注册表中的字体管理器的访问。"
  returnTypeName="FontManagerInterface?"
  isProperty
  platforms={['Android']}
/>
<APIMethod
  name="sensor"
  comment="提供对传统模块注册表中的传感器管理器的访问。"
  returnTypeName="SensorServiceInterface?"
  isProperty
  platforms={['Android']}
/>
<APIMethod
  name="taskManager"
  comment="提供对传统模块注册表中的任务管理器的访问。"
  returnTypeName="TaskManagerInterface?"
  isProperty
  platforms={['Android']}
/>
<APIMethod
  name="activityProvider"
  comment="提供对传统模块注册表中的活动提供者的访问。"
  returnTypeName="ActivityProvider?"
  isProperty
  platforms={['Android']}
/>
<APIMethod
  name="reactContext"
  comment="提供对 React 应用程序上下文的访问。"
  returnTypeName="Context?"
  isProperty
  platforms={['Android']}
/>
<APIMethod
  name="hasActiveReactInstance"
  comment="检查是否存在非空且存活的 React Native 实例。"
  returnTypeName="Boolean"
  isProperty
  platforms={['Android']}
/>
<APIMethod
  name="utilities"
  comment="提供对传统模块注册表中实用工具的访问。"
  returnTypeName="EXUtilitiesInterface?"
  isProperty
  platforms={['iOS']}
/>
#### ExpoView
所有导出视图应使用的基类。
在 iOS 上，`ExpoView` 扩展了处理一些样式（例如边框）和可访问性的 `RCTView`。
#### 属性
<APIMethod
  name="appContext"
  comment="提供对 [`AppContext`](#appcontext) 的访问。"
  returnTypeName="AppContext"
  isProperty
  isReturnTypeReference
/>
#### 扩展 `ExpoView`
要使用 [`View`](#view) 组件导出您的视图，您的自定义类必须继承自 `ExpoView`。通过这样做，您将能够访问 [`AppContext`](#appcontext) 对象。这是与其他模块和 JavaScript 运行时通信的唯一方法。此外，您不能更改构造函数参数，因为提供的视图将由 `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) {
    }
  }
}
```
## 指南
### 发送事件
虽然 JavaScript/TypeScript 到本机的通信主要由本机函数覆盖，但您可能还想让 JavaScript/TypeScript 代码知道某些系统事件，例如剪贴板内容的更改。
为此，在模块定义中，您需要提供模块可以使用 [Events](#events) 定义组件发送的事件名称。之后，您可以在模块实例上使用 `sendEvent(eventName, payload)` 函数来发送实际事件及其有效负载。例如，最小的剪贴板实现可以发送本机事件如下所示：
```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 中订阅这些事件，请使用 [`addListener`](/versions/latest/sdk/expo/#addlistenereventname-listener) 对由 `requireNativeModule` 返回的模块对象进行处理。模块扩展了内置的 [`EventEmitter`](/versions/latest/sdk/expo/#eventemitter) 类。
或者，您可以使用 [`useEvent`](/versions/latest/sdk/expo/#useeventeventemitter-eventname-initialvalue) 或 [`useEventListener`](/versions/latest/sdk/expo/#useeventlistenereventemitter-eventname-listener) 钩子。
```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');
});
```
### 视图回调
某些事件与特定视图相关联。例如，触摸事件只应发送到被按下的底层 JavaScript 视图。在这种情况下，您不能使用 [`发送事件`](#sending-events) 中描述的 `sendEvent`。`expo-modules-core` 引入了一种视图回调机制以处理视图绑定事件。
要使用它，在视图定义中，您需要使用 [Events](#events) 定义组件提供视图可以发送的事件名称。之后，您需要在视图类中声明一个类型为 `EventDispatcher` 的属性。声明的属性名称必须与 `Events` 组件中导出的名称相同。然后，您可以将其作为函数调用，并传递类型为 `[String: Any?]` 的有效负载（在 iOS 上为 `Map<String, Any?>`。
> **注意:** 在 Android 上，可以指定有效负载类型。在类型无法转换为对象的情况下，有效负载将被封装并存储在 `payload` 键下：`{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 中订阅这些事件，您需要将函数传递给本机视图，如下所示：
```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` 键下使用。
## 示例
```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 模块：


## Android 生命周期监听器

了解机制，使您的库能够通过 Expo 模块 API 挂钩 Android Activity 和 Application 功能。

为了响应与应用相关的某些 Android 系统事件，例如传入链接和配置更改，必须覆盖 **MainActivity.java** 和/或 **MainApplication.java** 中相应的生命周期回调。
React Native 模块 API 没有提供任何机制来挂钩这些事件，因此 React Native 库的设置说明通常包括将代码复制到这些文件的步骤。为了简化和自动化设置和维护，Expo Modules API 提供了一种机制，允许您的库挂钩 `Activity` 或 `Application` 函数。
## 开始使用
首先，您需要创建一个 Expo 模块或使用 React Native 模块 API 集成 Expo 模块 API。 [了解更多](./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` 方法。
## `Activity` 生命周期监听器
您可以使用 `ReactActivityLifecycleListener` 挂钩 `Activity` 生命周期。`ReactActivityLifecycleListener` 使用其 `ReactActivityDelegate` 挂钩 React Native 的 `ReactActivity` 生命周期，并提供与 Android `Activity` 生命周期类似的体验。
当前支持以下 `Activity` 生命周期回调：
- `onCreate`
- `onResume`
- `onPause`
- `onDestroy`
- `onNewIntent`
- `onBackPressed`
要创建 `ReactActivityLifecycleListener`，您应该在派生的 `Package` 类中实现 `createReactActivityLifecycleListeners`。例如，`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` 的类，您可以在其中挂钩生命周期。您只需重写所需的方法。
```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?) {
    // 在 `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) {
    // 在 `Activity.onCreate` 中执行您的初始化代码。
    doSomeSetupInActivityOnCreate(activity);
  }
}
```
您还可以重写其他生命周期方法。以下示例显示了如何在单个监听器类中重写多个生命周期方法。该示例基于 `expo-linking` 模块，它使用不同的生命周期方法来处理深链接。您可以只实现适合您用例的方法：
```kotlin
// android/src/main/java/expo/modules/mylib/MyLibReactActivityLifecycleListener.kt
package expo.modules.mylib
import android.app.Activity
import android.content.Intent
import android.os.Bundle
import expo.modules.core.interfaces.ReactActivityLifecycleListener
class MyLibReactActivityLifecycleListener : ReactActivityLifecycleListener {
  override fun onCreate(activity: Activity?, savedInstanceState: Bundle?) {
    // 当活动首次创建时调用
    // 在这里初始化您的设置，例如处理深链接
    val deepLinkUrl = activity?.intent?.data
    if (deepLinkUrl != null) {
      handleDeepLink(deepLinkUrl.toString())
    }
  }
  override fun onResume(activity: Activity) {
    // 当活动进入前台时调用
    // 例如，跟踪用户何时返回到应用程序
    trackAppStateChange("active")
  }
  override fun onPause(activity: Activity) {
    // 当活动进入后台时调用
    // 例如，暂停正在进行的操作，例如跟踪分析
    trackAppStateChange("inactive")
  }
  override fun onDestroy(activity: Activity) {
    // 当活动被销毁时调用
    // 在这里清理资源
    cleanup()
  }
  override fun onNewIntent(intent: Intent?): Boolean {
    // 当应用程序在运行时接收到新的意图时调用
    // 例如，在应用程序打开时处理新的深链接
    val newUrl = intent?.data
    if (newUrl != null) {
      handleDeepLink(newUrl.toString())
      return true
    }
    return false
  }
  override fun onBackPressed(): Boolean {
    // 当用户按下返回按钮时调用
    // 返回 true 以防止默认的返回行为
    return handleCustomBackNavigation()
  }
  // 现在，您可以添加私有函数来处理
  // 您的深链接、应用状态跟踪、清理等逻辑。
}
```
```java
// android/src/main/java/expo/modules/mylib/MyLibReactActivityLifecycleListener.java
package expo.modules.mylib;
import android.app.Activity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import expo.modules.core.interfaces.ReactActivityLifecycleListener;
public class MyLibReactActivityLifecycleListener implements ReactActivityLifecycleListener {
  @Override
  public void onCreate(Activity activity, Bundle savedInstanceState) {
    // 当活动首次创建时调用
    // 在这里初始化您的设置，例如处理深链接
    Uri deepLinkUrl = activity.getIntent().getData();
    if (deepLinkUrl != null) {
      handleDeepLink(deepLinkUrl.toString());
    }
  }
  @Override
  public void onResume(Activity activity) {
    // 当活动进入前台时调用
    // 例如，跟踪用户何时返回到应用程序
    trackAppStateChange("active");
  }
  @Override
  public void onPause(Activity activity) {
    // 当活动进入后台时调用
    // 例如，暂停正在进行的操作，例如跟踪分析
    trackAppStateChange("inactive");
  }
  @Override
  public void onDestroy(Activity activity) {
    // 当活动被销毁时调用
    // 在这里清理资源
    cleanup();
  }
  @Override
  public boolean onNewIntent(Intent intent) {
    // 当应用程序在运行时接收到新的意图时调用
    // 例如，在应用程序打开时处理新的深链接
    Uri newUrl = intent.getData();
    if (newUrl != null) {
      handleDeepLink(newUrl.toString());
      return true;
    }
    return false;
  }
  @Override
  public boolean onBackPressed() {
    // 当用户按下返回按钮时调用
    // 返回 true 以防止默认的返回行为
    return handleCustomBackNavigation();
  }
  // 现在，您可以添加私有函数来处理
  // 您的深链接、应用状态跟踪、清理等逻辑。
}
```
## JavaScript 事件流的生命周期监听器
生命周期监听器是独立于您的 Expo 模块实例的单例类。要在生命周期监听器和您的模块之间进行通信（例如，将事件发送到应用程序的 JavaScript 代码），您需要观察来自模块的事件，并在事件发生时通知生命周期监听器。典型的流程可能包括以下步骤：
- **系统集成**：生命周期监听器捕获带有 URL 数据的 Android 意图
- **观察者模式**：单例生命周期监听器与模块实例通信
- **事件桥接**：模块将结构化事件发送到 JavaScript
- **内存管理**：弱引用防止内存泄漏
- **类型安全和 React 集成**：通过适当的事件类型和自定义钩子提供 TypeScript 支持，便于访问深链接事件
您的自定义模块实现可能不需要上述所有内容。不过，您可以将此模式调整为其他系统事件，例如应用状态更改、配置更改或需要将 Android 生命周期事件桥接到 React Native 应用程序的自定义业务逻辑。
以下示例演示如何使用生命周期监听器将 Android 系统事件桥接到您的 React Native 应用程序。该示例基于 [`expo-linking`](https://github.com/expo/expo/tree/main/packages/expo-linking)，该模块使用生命周期监听器创建一个深链接处理程序，当应用程序打开或接收新意图时捕获 URL。
Step 1: 
### 模块注册
首先创建一个模块类，注册您的生命周期监听器：
```kotlin
// android/src/main/java/expo/modules/deeplinkhandler/DeepLinkHandlerPackage.kt
package expo.modules.deeplinkhandler
import android.content.Context
import expo.modules.core.interfaces.Package
import expo.modules.core.interfaces.ReactActivityLifecycleListener
class DeepLinkHandlerPackage : Package {
  override fun createReactActivityLifecycleListeners(activityContext: Context?): List<ReactActivityLifecycleListener> {
    return listOf(DeepLinkHandlerActivityLifecycleListener())
  }
}
```
```java
// android/src/main/java/expo/modules/deeplinkhandler/DeepLinkHandlerPackage.java
package expo.modules.deeplinkhandler;
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 DeepLinkHandlerPackage implements Package {
  @Override
  public List<? extends ReactActivityLifecycleListener> createReactActivityLifecycleListeners(Context activityContext) {
    return Collections.singletonList(new DeepLinkHandlerActivityLifecycleListener());
  }
}
```
Step 2: 
### 带有观察者通知的 Activity 生命周期监听器
创建一个生命周期监听器，捕获深链接并通知模块观察者：
```kotlin
// android/src/main/java/expo/modules/deeplinkhandler/DeepLinkHandlerActivityLifecycleListener.kt
package expo.modules.deeplinkhandler
import android.app.Activity
import android.content.Intent
import android.net.Uri
import android.os.Bundle
import expo.modules.core.interfaces.ReactActivityLifecycleListener
class DeepLinkHandlerActivityLifecycleListener : ReactActivityLifecycleListener {
  override fun onCreate(activity: Activity?, savedInstanceState: Bundle?) {
    handleIntent(activity?.intent)
  }
  override fun onNewIntent(intent: Intent?): Boolean {
    handleIntent(intent)
    return true
  }
  private fun handleIntent(intent: Intent?) {
    val url = intent?.data
    if (url != null) {
      // 存储初始 URL，以便以后检索
      DeepLinkHandlerModule.initialUrl = url
      // 通知所有观察者新的深链接
      DeepLinkHandlerModule.urlReceivedObservers.forEach { observer ->
        observer(url)
      }
    }
  }
}
```
```java
// android/src/main/java/expo/modules/deeplinkhandler/DeepLinkHandlerActivityLifecycleListener.java
package expo.modules.deeplinkhandler;
import android.app.Activity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import expo.modules.core.interfaces.ReactActivityLifecycleListener;
public class DeepLinkHandlerActivityLifecycleListener implements ReactActivityLifecycleListener {
  @Override
  public void onCreate(Activity activity, Bundle savedInstanceState) {
    handleIntent(activity.getIntent());
  }
  @Override
  public boolean onNewIntent(Intent intent) {
    handleIntent(intent);
    return true;
  }
  private void handleIntent(Intent intent) {
    if (intent == null) return;
    Uri url = intent.getData();
    if (url != null) {
      // 存储初始 URL，以便以后检索
      DeepLinkHandlerModule.initialUrl = url;
      // 通知所有观察者新的深链接
      for (java.util.function.Consumer<Uri> observer : DeepLinkHandlerModule.urlReceivedObservers) {
        observer.accept(url);
      }
    }
  }
}
```
Step 3: 
### 具有事件发送的 Expo 模块
创建一个模块，维护观察者并将事件发送给 JavaScript：
```kotlin
// android/src/main/java/expo/modules/deeplinkhandler/DeepLinkHandlerModule.kt
package expo.modules.deeplinkhandler
import android.net.Uri
import androidx.core.os.bundleOf
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
import java.lang.ref.WeakReference
class DeepLinkHandlerModule : Module() {
  companion object {
    var initialUrl: Uri? = null
    var urlReceivedObservers: MutableSet<((Uri) -> Unit)> = mutableSetOf()
  }
  private var urlReceivedObserver: ((Uri) -> Unit)? = null
  override fun definition() = ModuleDefinition {
    Name("DeepLinkHandler")
    Events("onUrlReceived")
    Function("getInitialUrl") {
      initialUrl?.toString()
    }
    OnStartObserving("onUrlReceived") {
      val weakModule = WeakReference(this@DeepLinkHandlerModule)
      val observer: (Uri) -> Unit = { uri ->
        weakModule.get()?.sendEvent(
          "onUrlReceived",
          bundleOf(
            "url" to uri.toString(),
            "scheme" to uri.scheme,
            "host" to uri.host,
            "path" to uri.path
          )
        )
      }
      urlReceivedObservers.add(observer)
      urlReceivedObserver = observer
    }
    OnStopObserving("onUrlReceived") {
      urlReceivedObservers.remove(urlReceivedObserver)
    }
  }
}
```
```java
// android/src/main/java/expo/modules/deeplinkhandler/DeepLinkHandlerModule.java
package expo.modules.deeplinkhandler;
import android.net.Uri;
import androidx.core.os.Bundle;
import expo.modules.kotlin.modules.Module;
import expo.modules.kotlin.modules.ModuleDefinition;
import java.lang.ref.WeakReference;
import java.util.HashSet;
import java.util.Set;
import java.util.function.Consumer;
public class DeepLinkHandlerModule extends Module {
  public static Uri initialUrl = null;
  public static Set<Consumer<Uri>> urlReceivedObservers = new HashSet<>();
  private Consumer<Uri> urlReceivedObserver;
  @Override
  public ModuleDefinition definition() {
    return ModuleDefinition.create()
      .name("DeepLinkHandler")
      .events("onUrlReceived")
      .function("getInitialUrl", () -> {
        return initialUrl != null ? initialUrl.toString() : null;
      })
      .onStartObserving("onUrlReceived", () -> {
        WeakReference<DeepLinkHandlerModule> weakModule = new WeakReference<>(this);
        Consumer<Uri> observer = uri -> {
          DeepLinkHandlerModule module = weakModule.get();
          if (module != null) {
            Bundle bundle = new Bundle();
            bundle.putString("url", uri.toString());
            bundle.putString("scheme", uri.getScheme());
            bundle.putString("host", uri.getHost());
            bundle.putString("path", uri.getPath());
            module.sendEvent("onUrlReceived", bundle);
          }
        };
        urlReceivedObservers.add(observer);
        urlReceivedObserver = observer;
      })
      .onStopObserving("onUrlReceived", () -> {
        urlReceivedObservers.remove(urlReceivedObserver);
      });
  }
}
```
Step 4: 
### TypeScript 接口和 React 使用
为您的模块定义一个 TypeScript 接口，以桥接 Android 生命周期事件到 JavaScript：
```ts DeepLinkHandler.ts
import { requireNativeModule, NativeModule } from 'expo-modules-core';
export type DeepLinkEvent = {
  url: string;
  scheme?: string;
  host?: string;
  path?: string;
};
type DeepLinkHandlerModuleEvents = {
  onUrlReceived(event: DeepLinkEvent): void;
};
declare class DeepLinkHandlerNativeModule extends NativeModule<DeepLinkHandlerModuleEvents> {
  getInitialUrl(): string | null;
}
const DeepLinkHandler = requireNativeModule<DeepLinkHandlerNativeModule>('DeepLinkHandler');
export default DeepLinkHandler;
```
为深链接事件提供易于访问的 React 钩子：
```tsx useDeepLinkHandler.ts
import { useEffect, useState } from 'react';
import DeepLinkHandler, { DeepLinkEvent } from './DeepLinkHandler';
export function useDeepLinkHandler(): {
  initialUrl: string | null;
  url: string | null;
  event: DeepLinkEvent | null;
} {
  const [initialUrl] = useState<string | null>(DeepLinkHandler.getInitialUrl());
  const [event, setEvent] = useState<DeepLinkEvent | null>(null);
  useEffect(() => {
    const subscription = DeepLinkHandler.addListener('onUrlReceived', event => {
      setEvent(event);
    });
    return () => subscription.remove();
  }, []);
  return {
    initialUrl,
    url: event?.url ?? initialUrl,
    event,
  };
}
```
在您的 React 组件中使用它：
```tsx App.tsx
import { Text, View, StyleSheet } from 'react-native';
import { useDeepLinkHandler } from './useDeepLinkHandler';
export function App() {
  const { initialUrl, url, event } = useDeepLinkHandler();
  return (
    <View style={styles.container}>
      <Text>Initial URL: {initialUrl || 'None'}</Text>
      <Text>Current URL: {url || 'None'}</Text>
      {event && (
        <View style={styles.textContainer}>
          <Text>Latest Deep Link:</Text>
          <Text>Scheme: {event.scheme}</Text>
          <Text>Host: {event.host}</Text>
          <Text>Path: {event.path}</Text>
        </View>
      )}
    </View>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  textContainer: {
    marginTop: 20,
  },
});
```
Step 5: 
### 模块配置
最后，在 **expo-module.config.json** 中配置您的模块，以连接模块到生命周期监听器：
```json expo-module.config.json
{
  "platforms": ["android"],
  "android": {
    "modules": ["expo.modules.deeplinkhandler.DeepLinkHandlerModule"]
  }
}
```
## `Application` 生命周期监听器
您可以使用 `ApplicationLifecycleListener` 挂钩 `Application` 生命周期。
当前支持以下 `Application` 生命周期回调：
- `onCreate`
- `onConfigurationChanged`
要创建 `ApplicationLifecycleListener`，您应该在派生的 `Package` 类中实现 `createApplicationLifecycleListeners`。例如，`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)）。
```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) {
    // 在 `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) {
    // 在 `Application.onCreate` 中执行您的初始化代码。
    doSomeSetupInApplicationOnCreate(application);
  }
}
```
## 已知问题
### 为什么没有 `onStart` 和 `onStop` Activity 监听器
在当前实现中，我们没有从 `MainActivity` 设置钩子，而是从 [`ReactActivityDelegate`](https://github.com/facebook/react-native/blob/400902093aa3ccfc05712a996c592a86f342253a/ReactAndroid/src/main/java/com/facebook/react/ReactActivityDelegate.java) 设置。`MainActivity` 和 `ReactActivityDelegate` 之间存在一些细微的差异。由于 `ReactActivityDelegate` 没有 `onStart` 和 `onStop`，我们在这里尚不支持它们。
### 接口稳定性
监听器接口可能会在 Expo SDK 发布之间发生变化。我们的向后兼容性策略始终是添加新的接口，并对我们计划删除的接口添加 `@Deprecated` 注释。我们的接口均基于 Java 8 接口默认方法；您不必也不应实现所有方法。这样做将有利于在不同的 Expo SDK 之间降低模块的维护成本。


## iOS AppDelegate 订阅者

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

要响应某些与应用相关的 iOS 系统事件，例如传入链接和通知，有必要在 `AppDelegate` 中处理相应的方法。
React Native 模块 API 并不提供任何钩住这些方法的机制，因此 React Native 库的设置说明通常包括将代码复制到 `AppDelegate` 文件的步骤。为了简化和自动化设置和维护，Expo 模块 API 提供了一种机制，允许您的库订阅对 `AppDelegate` 函数的调用。为了使其工作，应用的 `AppDelegate` 必须继承自 `ExpoAppDelegate`，这是使用 Expo 模块的要求。
`ExpoAppDelegate` 实现了 [`UIApplicationDelegate`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate) 协议的大多数函数，并将它们的调用转发给所有订阅者。
## 开始
首先，您需要创建一个 Expo 模块或使用 React Native 模块 API 集成 Expo 模块 API。 [了解更多](./overview.mdx#setup)。
创建一个新的公共 Swift 类，该类扩展自 `ExpoAppDelegateSubscriber`，并将其名称添加到 [模块配置](/modules/module-config/) 的 `apple.appDelegateSubscribers` 数组中。运行 `pod install`，订阅者将在应用程序项目中的 **ExpoModulesProvider.swift** 文件中生成。
现在，您可以通过向订阅者类添加委托函数来订阅事件。有关您可以订阅的函数的完整列表，请参阅 [`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)）。
> 不支持 Objective-C 类。
## 返回值
需要返回值的委托函数有一些额外的逻辑，用于协调多个订阅者的响应并尽量满足它们。以下是两个良好的边缘案例示例：
#### `application(_:didFinishLaunchingWithOptions:) -> Bool`
根据 [Apple 文档](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622921-application)，如果应用无法处理 URL 资源或继续用户活动，则应返回 `false`，否则应返回 `true`。如果应用因远程通知启动，则返回值将被忽略。
在此情况下，如果至少一个订阅者返回 `true`，则 `ExpoAppDelegate` 也将返回 `true`。
#### `application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`
此方法通知应用委托收到远程通知，并为应用提供了获取新数据的机会。它接收一个完成块，以便在获取操作完成时执行。该块应使用最佳描述获取请求结果的获取结果值进行调用。可能的值为：`UIBackgroundFetchResult.newData`、`UIBackgroundFetchResult.noData` 或 `UIBackgroundFetchResult.failed`。
在此场景中，`ExpoAppDelegate` 向每个订阅者传递一个新的完成块，等待所有完成后收集结果，然后再调用原始完成块。最终结果取决于从订阅者收集的结果，顺序如下：
- 如果至少一个订阅者以 `failed` 结果调用完成块，则委托也返回 `failed`。
- 如果存在至少一个 `newData` 结果，则委托返回 `newData`。
- 否则返回 `noData`。
> 要查看其他函数如何处理您的订阅者的结果，我们建议直接阅读代码：[`ExpoAppDelegate.swift`](https://github.com/expo/expo/blob/main/packages/expo/ios/AppDelegates/ExpoAppDelegate.swift)。
## 示例
```swift AppLifecycleDelegate.swift
import ExpoModulesCore
public class AppLifecycleDelegate: ExpoAppDelegateSubscriber {
  public func applicationDidBecomeActive(_ application: UIApplication) {
    // 应用已变为活动状态。
  }
  public func applicationWillResignActive(_ application: UIApplication) {
    // 应用即将变为非活动状态。
  }
  public func applicationDidEnterBackground(_ application: UIApplication) {
    // 应用现在处于后台。
  }
  public func applicationWillEnterForeground(_ application: UIApplication) {
    // 应用即将进入前台。
  }
  public func applicationWillTerminate(_ application: UIApplication) {
    // 应用即将终止。
  }
  public func applicationDidReceiveMemoryWarning(_ application: UIApplication) {
    // The app has received a memory warning.
  }
}
```
```json expo-module.config.json
{
  "apple": {
    "appDelegateSubscribers": ["AppLifecycleDelegate"]
  }
}
```


## 自动链接

学习如何使用 Expo 自动链接在您的 Expo 项目中自动链接原生依赖。

通常，当您开发一个原生移动应用并想要安装第三方库时，您需要将依赖项添加到包管理器的清单文件中（**build.gradle** 在 Android 上，**Podfile** 在 iOS 的 CocoaPods 上，**Package.swift** 在 iOS 的 SwiftPM 上）。
在 Expo 和 React Native 中，您通过从 [npm](https://www.npmjs.com) 注册表中安装包，已经使用了您的 **package.json** 文件。由于大多数 React Native 库都带有某些原生（特定平台的）代码，
安装库将需要配置多达三个不同的包管理器！
Expo 自动链接是自动化此过程的机制，将库安装过程减少到最小——通常只需从 `npm` 安装包并重新运行 `pod install`。
核心实现可以在 [`expo-modules-autolinking`](https://github.com/expo/expo/tree/main/packages/expo-modules-autolinking) 包中找到，并分为三个部分：
1. 带有模块解析算法的 CLI 命令
2. 与 Android 的 Gradle 构建系统集成的代码
3. 与 iOS 的 CocoaPods 集成的代码
自 SDK 52 起，Expo 自动链接不仅链接 Expo 模块，还链接 React Native 模块。要使用 React Native 社区 CLI 的自动链接，请参见 [选择退出 Expo 自动链接以用于 React Native 模块](#opting-out-of-expo-autolinking-for-react-native-modules) 部分。
## 链接行为
Expo 自动链接集成到 Android 的 Gradle 构建系统和 iOS 的 CocoaPods 中。当构建您的应用时，Expo 自动链接 CLI 会被调用并搜索 Expo 和 React Native 模块以进行自动链接。
该模块解析在四个单独的步骤中搜索要自动链接的候选依赖项：
1. 仅针对 React Native 模块，它考虑您项目根目录的 **react-native.config.js** 中包含显式 `root` 路径的任何 `dependencies`。此文件是可选的，且在大多数 Expo 项目中并不存在。
2. 它搜索您自动链接配置中的 `searchPaths` 选项指定的所有目录。
3. 它搜索在您自动链接配置的 `nativeModulesDir` 选项中指定的目录中的本地模块，默认为 `./modules/`。
4. 它递归解析您的应用的依赖及任何依赖或同伴依赖。这符合 [Node.js 解析算法](https://nodejs.org/api/modules.html#loading-from-node_modules-folders)。
自动链接的模块会自动添加到构建中，这通常意味着您应用中的包含原生（特定平台）代码的依赖被自动设置。
## 配置
模块解析的行为可以使用一些配置选项进行自定义。这些选项可以在三个不同的位置定义，从最低优先级到最高优先级：
- 应用程序的 **package.json** 中的 `expo.autolinking` 配置对象
- 通过 `expo.autolinking.ios` 和 `expo.autolinking.android` 对象进行每个平台的覆盖
- 提供给 CLI 命令的选项，**Podfile** 中的 `use_expo_modules!` 方法或 **settings.gradle** 中的 `useExpoModules` 函数
#### searchPaths
一个路径列表，相对于应用的根目录，Expo 自动链接应搜索以进行模块自动链接。
在您的项目具有自定义结构或您想要链接来自于与 **node_modules** 不同目录的本地包时很有用。
您指定的路径仍然必须像 **node_modules** 目录那样结构化。
```json package.json
{
  "expo": {
    "autolinking": {
      "searchPaths": ["../../packages"]
    }
  }
}
```
> **info** 在 **SDK 54** 之前，此列表默认指向您应用的 **node_modules** 目录，以及在单体仓库中高于它的所有 **node_modules** 目录。
> 要恢复为旧行为，请将此列表设置为您应用的 **node_modules** 目录，例如：`["../../node_modules", "./node_modules"]`。
#### nativeModulesDir
一个路径，相对于应用的根目录，Expo 自动链接应搜索以进行本地模块的自动链接。此选项默认为 `"./modules"`。更改此选项仅在您需要更改 [本地 Expo 模块](/#) 的路径时有用。
```json package.json
{
  "expo": {
    "autolinking": {
      "nativeModulesDir": "./modules"
    }
  }
}
```
#### exclude
一个要从自动链接中排除的包名称列表。如果您不想链接某些特定平台不使用的包以减少二进制大小，这很有用。
以下在 **package.json** 中的配置将在 Android 上排除 `expo-random` 和 `third-party-expo-module` 的自动链接：
```json package.json
{
  "expo": {
    "autolinking": {
      "android": {
        "exclude": ["expo-random", "third-party-expo-module"]
      }
    }
  }
}
```
React Native 模块也可以通过在项目的根目录中创建 **react-native.config.js** 并将应排除的平台配置设置为 `null` 来排除。以下配置将在 Android 上排除 `library-name` 的自动链接：
```js react-native.config.js
module.exports = {
  dependencies: {
    'library-name': {
      platforms: {
        android: null,
      },
    },
  },
};
```
> **info** 在 **SDK 54** 之前，`exclude` 选项仅适用于 Expo 模块，而不适用于 React Native 模块。React Native 模块只能通过在您项目的根目录中使用 **react-native.config.js** 文件进行排除。
#### flags, Android only
传递给每个自动链接的 pod 的 CocoaPods 标志。 `inhibit_warnings` 可能是大多数开发人员希望使用的唯一标志，以抑制编译自动链接模块时产生的 Xcode 警告。
您可以参考 [CocoaPods Podfile 文档](https://guides.cocoapods.org/syntax/podfile.html#pod) 获取可用的标志。
```ruby
use_expo_modules!({
  flags: {
    :inhibit_warnings => false
  }
})
```
```json
{
  "expo": {
    "autolinking": {
      "ios": {
        "flags": {
          "inhibit_warnings": true
        }
      }
    }
  }
}
```
#### buildFromSource, Android only
一个要选择退出预构建 Expo 模块的包名称列表。完整参考，请参见 [为 Android 选择退出预构建 Expo 模块](/guides/prebuilt-expo-modules/#selectively-opt-out).
#### legacy_shallowReactNativeLinking
在解析您的应用的 React Native 模块时，Expo 自动链接搜索您的应用的依赖以及这些依赖的依赖（符合 [Node.js 解析算法](https://nodejs.org/api/modules.html#loading-from-node_modules-folders)）。在 **SDK 54** 之前，Expo 自动链接未递归搜索依赖项，仅解析您应用的直接依赖。
启用时，此标志让您选择退出新行为，并恢复到 **SDK 54** 之前的行为，仅搜索您应用的直接依赖项以查找 React Native 模块。此选项在解析 Expo 模块时不予考虑。
## CLI 命令
#### search
此命令由构建系统调用以在自动链接的第一阶段解析 Expo 模块。其实现与所有平台共享。 `search` 的输出将包含每个包的 `duplicates` 列表（如果找到任何重复）。
```sh
$ npx expo-modules-autolinking search
```
上述命令返回一个 JSON 格式的对象，包含 Expo 自动链接找到的 Expo 模块：
```json
{
  "expo-random": {
    "path": "/absolute/path/to/node_modules/expo-random",
    "version": "13.0.0",
    "config": {
      // `expo-module.config.json` 的内容
    },
    "duplicates": [
      // 此模块的冲突重复项列表（优先级较低）
    ]
  }
  // 更多模块...
}
```
#### resolve
此命令在自动链接的第二阶段由构建系统调用。它输出每个 Expo 模块的更多（特定平台）详细信息，例如 **build.gradle** 或 podspec 文件的路径和需要链接的模块类。
```sh
$ npx expo-modules-autolinking resolve --platform <apple|android>
```
例如，使用 `--platform apple` 选项，它以 JSON 格式返回一个对象，其中包含模块和该平台的解析详细信息的数组：
```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
    }
    // 更多模块...
  ]
}
```
#### verify
验证自动链接的原生模块，通过检查重复项。对于每个冲突的重复安装，会显示警告。
```sh
$ npx expo-modules-autolinking verify
```
传递 `--verbose` 选项以列出所有自动链接的原生模块。
#### react-native-config
此命令在自动链接 React Native 模块时由构建系统调用。它输出每个 React Native 模块的更多特定平台详细信息，例如 gradle 或 podspec 文件的路径。
```sh
$ npx expo-modules-autolinking react-native-config
```
例如，使用 `--platform ios` 选项，它返回一个 **react-native.config.js** 输出格式的对象，包含每个 React Native 依赖项的信息及其 React Native 安装的路径。
```json
{
  "root": "/absolute/path/to",
  "reactNativePath": "/absolute/path/to/node_modules/react-native",
  "dependencies": {
    "@react-native-async-storage/async-storage": {
      "root": "/absolute/path/to/node_modules/@react-native-async-storage/async-storage",
      "name": "@react-native-async-storage/async-storage",
      "platforms": {
        "ios": {
          "podspecPath": "/absolute/path/to/node_modules/@react-native-async-storage/async-storage/RNCAsyncStorage.podspec",
          "version": "",
          "configurations": [],
          "scriptPhases": []
        }
      }
    }
    // 更多模块...
  }
}
```
## 依赖解析和冲突
> **重要** 这是从 SDK 54 开始的实验性功能。
自动链接和 Node 解析有不同的目标，而 Node 和 Metro 中的模块解析算法有时可能会发生冲突。如果您的应用包含由自动链接选中的原生模块的重复安装，则您的 JavaScript 包可能同时包含该原生模块的两个版本，而自动链接和您的原生应用中仅包含一个版本。这可能导致运行时崩溃，并存在不兼容的风险。
这是一个在孤立依赖或单体仓库中特别常见的问题，您应该 [检查并去重您的依赖中的原生模块](/guides/monorepos/#duplicate-native-packages-within-monorepos)。
从 **SDK 54** 开始，您可以在 [应用配置](/workflow/configuration/) 中将 `experiments.autolinkingModuleResolution` 设置为 `true`，以自动将自动链接应用于 Expo CLI 和 Metro 打包程序。这将强制 Metro 解析的依赖项与 **自动链接** 解析的原生模块相匹配。
## 常见问题
### 如何在我的应用中设置自动链接？
所有使用 `npx create-expo-app` 命令创建的项目都已配置为使用 Expo 自动链接。如果您的项目是使用其他工具创建的，请参见 [安装 Expo 模块](/bare/installing-expo-modules)，以确保您的项目包含所有必要的更改。
### 我需要在我的模块中有什么才能使其支持自动链接？
模块解析算法仅搜索包含 [Expo 模块配置](/modules/module-config/) 文件（**expo-module.config.json**）的包，该文件位于根目录，位于 **package.json** 文件旁边。
还需要在 `platforms` 数组中包含支持的平台——如果进行自动链接算法运行的平台不在此数组中，则在搜索结果中将被跳过。
### 与 React Native 社区 CLI 自动链接有何不同？
- Expo 自动链接内置支持单体仓库、包管理器工作区、传递依赖和孤立依赖安装。
- 它的速度也显著更快，尽管模块解析算法更复杂，以便更可靠并匹配 Node.js 的模块解析。
- Expo 模块解析还能够检测重复依赖，这是单体仓库中常见的问题。
- 最后但同样重要的是，它与 Expo 模块 API 提供的功能集成良好，并支持 React Native 模块。
### 选择退出 Expo 自动链接以用于 React Native 模块
自 SDK 52 起，Expo 自动链接默认替代了 React Native 社区 CLI 自动链接。如果您希望使用 React Native 社区 CLI 的自动链接，请设置环境变量 `EXPO_USE_COMMUNITY_AUTOLINKING=1` 并将 `@react-native-community/cli` 添加为您项目的开发依赖。
设置此环境变量后，将不会使用 Expo 自动链接来解析 React Native 模块，但将继续自动链接 Expo 模块。


## expo-module.config.json

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

Expo 模块在 **expo-module.config.json** 中配置。此文件目前能够配置自动链接和模块注册。以下属性可用：
- `platforms` — 支持的平台数组。可接受的值为 `android`，`apple`（或使用更细化的 `ios` / `macos` / `tvos`），`web` 和 `devtools`（参见 [创建开发工具插件](/debugging/create-devtools-plugins)）。
- `apple` — 针对 Apple 平台的特定选项配置
  - `modules` — 要放入生成的模块提供文件的 Swift 原生模块类的名称。
  - `appDelegateSubscribers` — 连接到 `ExpoAppDelegate` 以接收 AppDelegate 生命周期事件的 Swift 类的名称。
- `android` — 针对 Android 平台的特定选项配置
  - `modules` — 要放入生成的包提供文件的 Kotlin 原生模块类的全名（包 + 类名）。


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

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

在Expo项目中编写单元测试的推荐方法是使用 [Jest](https://jestjs.io/) 和 `jest-expo` 预设。
要为使用原生代码的应用编写单元测试，需要模拟原生调用。  
**模拟**一词的意思是用一个不执行任何操作的假版本来替换函数的实际实现。这种方法有助于在本地计算机上运行单元测试，因为它绕过了只能在设备上使用的原生代码，任何在本地机器上调用原生函数的代码都将无法工作。
Expo SDK 包含了我们每个社区包的默认模拟集。您也可以使用内置的 Jest API（如 [mock functions](https://jestjs.io/docs/mock-functions)）自行模拟任何 JS 代码。
但是，为了在您的 Expo 模块中提供默认模拟，我们提供了一种将其打包的方法。这确保了当您的模块用户运行单元测试时，他们将自动使用模拟实现。
## 为模块提供模拟
创建一个与您要模拟的原生模块同名的文件，并将其放在模块的 **mocks** 目录中。确保从该文件中导出模拟实现。  
`jest-expo` 预设将在单元测试期间因为一个 `requireNativeModule` 调用而自动返回导出的函数。
例如，`expo-clipboard` 库有一个名为 `ExpoClipboard` 的原生模块。您将在 **mocks** 目录中创建一个 **ExpoClipboard.ts** 文件来模拟它。
```ts ExpoClipboard.ts
export async function hasStringAsync(): Promise<boolean> {
  return false;
}
```
现在，在单元测试中，调用 `ExpoClipboard.hasStringAsync()` 返回 `false`。
## 自动生成模拟
如果原生模块有多个方法，维护原生模块的模拟可能会很繁琐。为了简化这个过程，我们提供了一个脚本，可以自动为模块中的所有原生函数生成模拟。  
它基于您的模块中的 Swift 实现，支持生成 TypeScript 和 JavaScript 的模拟。
要使用此脚本，您需要安装 [SourceKitten](https://github.com/jpsim/SourceKitten) 框架。然后，导航到模块目录（即您的模块的 **expo-module.config.json** 所在的位置），并运行 `generate-ts-mocks` 命令。
```sh
$ brew install sourcekitten
$ npx expo-modules-test-core generate-ts-mocks
```
上述命令将在您的模块的 **mocks** 目录中生成 **ExpoModuleName.ts**。它包含模块中每个原生方法和视图的模拟实现。
> **提示：** 您还可以运行 `generate-js-mocks` 以生成 JavaScript 模拟。
## 更多


## Expo 模块 API：设计考虑

Expo 模块 API 背后的设计考虑概述。

Expo 团队维护着一大套库，随着时间推移和不断变化的环境，维护原生模块可能是一个挑战。通过 Expo 模块 API，我们着手构建强大的工具，以简化构建和维护这些库的过程。
### 利用现代语言特性
在维护超过 50 个原生模块的 Expo SDK 多年后，我们发现许多问题都是由于未处理的空值或不正确的类型造成的。现代语言特性可以帮助开发者避免这些错误；例如，缺乏可选类型与 Objective-C 的动态性结合，使得某些类型的错误在 Swift 中会被编译器捕获，而在 Objective-C 中却难以捕获。
编写 React Native 模块的另一个难点是不同平台之间在写原生模块时的语言和范式的上下文切换。由于这些平台之间的差异，这种情况是无法完全避免的。我们感觉需要有一个通用的 API 和文档，以尽可能简化开发，方便单一开发者在多个平台上维护库。
这也是 Expo 模块生态系统从头开始设计以与现代原生语言（Swift 和 Kotlin）一起使用的原因之一。
### 简化在运行时之间传递数据的过程
Expo 模块 API 对原生函数期望的参数类型有完全的了解。它可以为你进行预验证和转换参数，并且字典可以表示为我们称之为 [Records](/modules/module-api/#records) 的原生结构。
我们旨在通过 API 解决的一个大痛点是验证从 JavaScript 传递到原生函数的参数。当涉及到 `NSDictionary` 或 `ReadableMap` 时，这特别容易出错、耗时，且维护困难，因为在运行时值的类型是未知的，每个属性都需要开发人员单独验证。
了解参数类型后，也可以 [自动转换参数](/modules/module-api/#convertibles) 为一些特定于平台的类型（例如，`{ x: number, y: number }` 或 `[number, number]` 可以方便地转换为 CoreGraphics 的 `CGPoint`）。
总之，Expo 模块具有强大的内置和可扩展的类型转换和类型安全性。它支持原始值的自动转换（例如，`Bool`/`Int`/`UInt`/`Float32`/`Double`/`Pair`/`String`）、复杂的内置类型（例如，`URL`、`CGPoint`、`UIColor`、`Data`、`java.net.URL`、`android.graphics.Color`、`kotlin.ByteArray`）、记录（用户定义类型，例如 `struct`/`Object`）和枚举。
### 支持表现力丰富的面向对象 API
将你的原生模块状态的真实来源保持在一个地方，而不是在 JavaScript 和原生之间分散，并自行处理相关的记账工作。我们称这个特性为 **共享对象**。例如，[`expo-sqlite` 数据库实例由共享对象支持](https://github.com/expo/expo/blob/718a9ac107231475ca4b2e6427317ade9d1e70fa/packages/expo-sqlite/src/SQLiteDatabase.ts#L421)。有关共享对象的详细文档即将推出。
### 提供一个安全且可组合的机制以挂钩应用程序生命周期事件
[Android 生命周期监听器](/modules/android-lifecycle-listeners/) 和 [iOS AppDelegate 订阅者](/modules/appdelegate-subscribers/) 是一个强大的特性，允许你挂钩到应用程序的生命周期，而无需将你的模块代码分散到 `MainActivity` 和 `AppDelegate` 类中，也不要求你的库使用者这样做。这对于与 [持续原生生成](/workflow/continuous-native-generation/) 的平滑集成特别有用，因为它为库提供了以可组合方式挂钩到应用程序生命周期事件的机制——而无需担心其他库可能正在做什么。
### 在保持向后兼容的同时支持新架构
React Native 版本 0.68 引入了 [新架构](https://reactnative.dev/docs/the-new-architecture/landing-page)，为开发者构建移动应用提供了新功能。它由名为 [Turbo 模块](https://reactnative.dev/docs/the-new-architecture/pillars-turbomodules) 的新原生模块系统和名为 [Fabric](https://reactnative.dev/architecture/fabric-renderer) 的新渲染系统组成。
原生库需要进行调整以利用这些新系统。对于 Fabric，它需要更多的工作，因为它不提供任何兼容层，这意味着以旧方式编写的视图管理器不适用于 Fabric，反之亦然——Fabric 原生组件无法与旧的渲染器一起工作。这基本意味着现有库在一段时间内必须支持两种架构，从而增加了技术负担。
新架构主要是用 C++ 编写的，因此你可能最终需要为你的库编写一些 C++ 代码。作为每天都使用高级 JavaScript 的 React Native 开发者，我们通常不愿意编写 C++，因为这是相对较为复杂的语言。此外，在库中包含 C++ 代码会对构建时间产生负面影响，特别是在 Android 上，并且可能会更难以调试。
在设计 Expo 模块 API 时，我们考虑了这些因素，目的是使其与渲染器无关，以便模块不需要知道应用程序是否在新架构上运行，从而显著降低库开发者的成本。


# 推送通知

## Expo 推送通知：概述

Expo 推送通知服务的概述。

Expo 通过处理与 Firebase Cloud Messaging (FCM) 或 Apple Push Notification Service (APNs) 通信中涉及的复杂性，简化了实现推送通知的过程。这使您能够以相同的方式处理 Android 和 iOS 通知，并在前端和后端节省时间。
请按照下面的视频或链接了解如何设置推送通知、发送推送通知以及在应用中处理接收到的通知。
Video Tutorial: [Expo 通知与 EAS | 完整指南](https://www.youtube.com/watch?v=BCCjGtKtBjE)


## 关于通知的注意事项

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

通知是告知用户新信息或事件的警报，即使应用程序未在使用中。它们的覆盖范围很大，平台之间的差异可能使实现通知变得令人生畏。
无论您是刚开始接触通知，还是已有一定了解，本文件均会解释不同类型的通知及其行为。
Expo 的通知支持建立在 Android 和 iOS 提供的原生功能之上。来自原生平台的相同概念和行为适用于 Expo 应用。如果您对特定的通知功能感到不确定，请参见每个平台的 [官方文档](#external-references)。
## 远程和本地通知
1. **推送通知**：（也称为“远程通知”）从远程服务器发送到用户设备的通知。
2. **本地通知**：（也称为“应用内通知”）在应用程序内部创建和显示的通知。由于创建这些通知的许多 API 将在特定时间创建它们，因此这些通知有时也称为“定时通知”。
`expo-notifications` 支持推送和本地通知。您必须使用 [开发版本](/develop/development-builds/introduction/) 才能使用推送通知，因为此功能未内置到 Expo Go 中。
有关如何创建和显示本地通知，请参见 [应用内通知](/versions/latest/sdk/notifications/#present-a-local-in-app-notification-to-the-user)。本指南的其余部分重点关注推送通知。
## 推送通知的传递
当推送通知到达您的应用程序时，其行为取决于应用程序的状态和通知类型。让我们澄清术语：
### 应用程序状态
- **前台**：应用程序在前台积极运行。其界面当前显示在屏幕上。
- **后台**：应用程序在后台运行，“最小化”。其界面当前未显示在屏幕上。
- **已终止**：应用程序被“关闭”，通常是在应用切换器中通过滑动手势关闭。在 Android 上，如果用户从设备设置强制停止应用程序，则必须手动重新打开才能使通知开始工作（这是 Android 的一个限制）。
### 推送通知的行为
对于任何类型的通知，当应用程序在前台时，应用程序控制如何处理传入的通知。应用程序可以直接展示它，显示一些自定义的应用内 UI，甚至忽略它（这由 [`NotificationHandler`](/versions/latest/sdk/notifications/#setnotificationhandlerhandler) 控制）。当应用程序不在前台时，行为取决于通知的类型。
下表总结了推送通知传递到设备时发生的情况：
| 通知类型                                                                                                                                                                                 | 应用在前台                                                                                                                                                                                         | 应用在后台                                                                        | 应用已终止                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [通知消息](/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) |
当用户与通知交互时（例如，按下操作按钮），以下处理程序将提供给您。
| 应用状态 | 触发的 iOS 监听器                      | 触发的 Android 监听器                                                                                              |
| -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| 前台     | `NotificationResponseReceivedListener` | `NotificationResponseReceivedListener`                                                                             |
| 后台     | `NotificationResponseReceivedListener` | `NotificationResponseReceivedListener` 和 [JS 任务](/versions/latest/sdk/notifications/#registertaskasynctaskname) |
| 已终止   | `NotificationResponseReceivedListener` | [JS 任务](/versions/latest/sdk/notifications/#registertaskasynctaskname)                                           |
在上表中，每当 `NotificationResponseReceivedListener` 被触发，`useLastNotificationResponse` 的返回值也会发生变化。
> **info** 当应用程序未运行或已终止，并通过点击通知启动时，`NotificationResponseReceivedListener` 必须提前注册（模块顶层），以便在 iOS 上触发。对于将应用程序带到前台的操作按钮，我们建议在应用程序启动后使用 `useLastNotificationResponse` 或 `getLastNotificationResponse` 捕获响应。
## 推送通知类型
### 通知消息
通知消息是指定展示信息的通知，如标题或正文文本。
- 在 Android 上，这相当于包含 [`AndroidNotification`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidNotification) 的推送通知请求。
- 在 iOS 上，这相当于包含 [`aps.alert` 字典](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Create-the-JSON-payload) 和 `apns-push-type` 头设置为 `alert` 的推送通知请求。
当您使用 Expo 推送服务，并指定 `title`、`subtitle`、`body`、`icon` 或 `channelId` 时，生成的推送通知请求即为通知消息。
[//]: # 'TODO vonovak clarify what fields make a notification to be considered a Notification Message'
通知消息的典型用例是立即向用户展示，而没有额外的处理。
### 含数据负载的通知消息
这是一个仅限 Android 的术语 ([查看官方文档](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages))，其中推送通知请求同时包含 `data` 字段和 `notification` 字段。
在 iOS 上，额外数据可能是常规通知消息请求的一部分。Apple 不区分是否携带数据的通知消息。
### 无头后台通知
无头通知是一种远程通知，它不直接指定展示信息，如标题或正文文本。除了下面的例外\*，无头通知不会展示给用户。相反，它们携带数据（JSON），由您通过 [`registerTaskAsync`](/versions/latest/sdk/notifications/#registertaskasynctaskname) 在应用中定义的 JavaScript 任务进行处理。该任务可以执行任意逻辑。例如，写入 `AsyncStorage`、进行 API 请求或展示本地通知，其内容来自推送通知的数据。
> **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 数据，并允许应用进行后台处理。
无头后台通知能够在收到通知时运行自定义 JavaScript _即使应用已终止_。这很强大，但也有一个限制：即使通知已传递到设备，操作系统也不保证将其传递到您的应用程序。这可能由于多种原因发生，例如，当 Android 上启用 [待机模式](https://developer.android.com/training/monitoring-device-state/doze-standby) 时，或者当您发送太多后台通知时 &mdash; Apple 建议不要 [每小时发送超过两个或三个](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#overview)。
当您使用 Expo 推送服务，并仅指定 `data` 和 `_contentAvailable: true`（以及其他非交互字段，如 `ttl`）时，生成的推送通知请求会产生无头后台通知。
[//]: # 'TODO vonovak clarify how setting priority behaves here, because apns-priority field should be 5 on iOS but can be specified on Android'
> 要在 iOS 上使用无头后台通知，您必须首先 [配置](/versions/latest/sdk/notifications/#background-notification-configuration) 它们。
通常的原则是，如果您不需要在后台运行 JavaScript，最好使用常规通知消息。
\* 例外是当您在 [`data`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidConfig) 中指定 `title` 或 `message` 时。此时，`expo-notifications` 包会自动在 Android 上展示无头通知，但在 iOS 上则不会。我们计划在未来的版本中使这种行为在各个平台之间更加一致。
### 仅数据通知
Android 有 [数据消息](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) 的概念。iOS 并没有完全相同的概念，但一个较接近的等价体是 [无头后台通知](#headless-background-notifications)。
您可能还会遇到“静默通知”这一术语，这是指不向用户展示任何内容的通知 &mdash; 我们将这些描述为 [无头后台通知](#headless-background-notifications)。
## 外部参考
这是关于 Android 和 iOS 推送通知的官方资源的非详尽列表：
- [Android - 关于 FCM 消息](https://firebase.google.com/docs/cloud-messaging/concept-options)
- [iOS - 生成远程通知](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)
- [iOS - 向您的应用推送后台更新](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app)


## Expo 推送通知设置

学习如何设置推送通知，获取开发和生产的凭证，并发送测试推送通知。

要利用 Expo 推送通知服务，您必须通过安装一组库来配置您的应用程序，实现处理通知的功能，并为 Android 和 iOS 设置凭证。
完成本指南中列出的步骤，或按照以下更详细的视频进行操作。最后，您将能够发送推送通知并在设备上接收它。
Video Tutorial: [使用 EAS 的 Expo 通知 | 完整指南](https://www.youtube.com/watch?v=BCCjGtKtBjE)
要准备好客户端以接收推送通知，需要以下事项：
- 用户的许可，以便向他们发送推送通知。
- 应用的 [`ExpoPushToken`](/versions/latest/sdk/notifications/#expopushtoken)。
Note: 您想直接使用 FCM / APNs，而不是 Expo 推送通知服务吗？
---
如果您需要对通知进行更细致的控制，则可能需要直接与 FCM 和 APNs 进行通信。Expo 并未限制您使用 Expo 应用程序服务，`expo-notifications` API 是独立于推送服务的。了解如何 ["使用 FCM 和 APNs 发送通知"](/push-notifications/sending-notifications-custom/)。
---
## 先决条件
> **warning** **重要：** Android 模拟器和 iOS 模拟器不支持推送通知。需要真实设备。
本指南中描述的步骤使用 [EAS Build](/build/introduction/)。这是设置通知的最简单方法，因为您的 EAS 项目还将包含 [通知凭证](#get-credentials-for-development-builds)。不过，您也可以通过在 [本地构建项目](/guides/local-app-development/) 时使用 `expo-notifications` 库，而无需 EAS Build。
Step 1: 
## 安装库
运行以下命令以安装 `expo-notifications`、`expo-device` 和 `expo-constants` 库：
```sh
$ npx expo install expo-notifications expo-device expo-constants
```
- [`expo-notifications`](/versions/latest/sdk/notifications) 库用于请求用户的许可并获取用于发送推送通知的 `ExpoPushToken`。
- [`expo-device`](/versions/latest/sdk/device) 用于检查应用是否在物理设备上运行。
- [`expo-constants`](/versions/latest/sdk/constants) 用于从应用配置中获取 `projectId` 值。
Step 2: 
## 添加配置插件
在您的 [应用配置](/workflow/configuration/) 的 `plugins` 数组中添加 `expo-notifications` 插件：
```json app.json
{
  "expo": {
    "plugins": [
      "expo-notifications"
      ]
  }
}
```
Step 3: 
## 添加最小工作示例
以下代码展示了如何在 React Native 应用中注册、发送和接收推送通知的工作示例。将其复制并粘贴到您的项目中：
```tsx App.tsx
import { useState, useEffect, useRef } from 'react';
import { Text, View, Button, Platform } from 'react-native';
import * as Device from 'expo-device';
import * as Notifications from 'expo-notifications';
import Constants from 'expo-constants';
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldPlaySound: true,
    shouldSetBadge: true,
    shouldShowBanner: true,
    shouldShowList: true,
  }),
});
async function sendPushNotification(expoPushToken: string) {
  const message = {
    to: expoPushToken,
    sound: 'default',
    title: 'Original Title',
    body: 'And here is the body!',
    data: { someData: 'goes here' },
  };
  await fetch('https://exp.host/--/api/v2/push/send', {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'Accept-encoding': 'gzip, deflate',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(message),
  });
}
function handleRegistrationError(errorMessage: string) {
  alert(errorMessage);
  throw new Error(errorMessage);
}
async function registerForPushNotificationsAsync() {
  if (Platform.OS === 'android') {
    await Notifications.setNotificationChannelAsync('default', {
      name: 'default',
      importance: Notifications.AndroidImportance.MAX,
      vibrationPattern: [0, 250, 250, 250],
      lightColor: '#FF231F7C',
    });
  }
  if (Device.isDevice) {
    const { status: existingStatus } = await Notifications.getPermissionsAsync();
    let finalStatus = existingStatus;
    if (existingStatus !== 'granted') {
      const { status } = await Notifications.requestPermissionsAsync();
      finalStatus = status;
    }
    if (finalStatus !== 'granted') {
      handleRegistrationError('Permission not granted to get push token for push notification!');
      return;
    }
    const projectId =
      Constants?.expoConfig?.extra?.eas?.projectId ?? Constants?.easConfig?.projectId;
    if (!projectId) {
      handleRegistrationError('Project ID not found');
    }
    try {
      const pushTokenString = (
        await Notifications.getExpoPushTokenAsync({
          projectId,
        })
      ).data;
      console.log(pushTokenString);
      return pushTokenString;
    } catch (e: unknown) {
      handleRegistrationError(`${e}`);
    }
  } else {
    handleRegistrationError('Must use physical device for push notifications');
  }
}
export default function App() {
  const [expoPushToken, setExpoPushToken] = useState('');
  const [notification, setNotification] = useState<Notifications.Notification | undefined>(
    undefined
  );
  useEffect(() => {
    registerForPushNotificationsAsync()
      .then(token => setExpoPushToken(token ?? ''))
      .catch((error: any) => setExpoPushToken(`${error}`));
    const notificationListener = Notifications.addNotificationReceivedListener(notification => {
      setNotification(notification);
    });
    const responseListener = Notifications.addNotificationResponseReceivedListener(response => {
      console.log(response);
    });
    return () => {
      notificationListener.remove();
      responseListener.remove();
    };
  }, []);
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'space-around' }}>
      <Text>Your Expo push token: {expoPushToken}</Text>
      <View style={{ alignItems: 'center', justifyContent: 'center' }}>
        <Text>Title: {notification && notification.request.content.title} </Text>
        <Text>Body: {notification && notification.request.content.body}</Text>
        <Text>Data: {notification && JSON.stringify(notification.request.content.data)}</Text>
      </View>
      <Button
        title="Press to Send Notification"
        onPress={async () => {
          await sendPushNotification(expoPushToken);
        }}
      />
    </View>
  );
}
```
### 配置 `projectId`
使用前面的示例，当您注册推送通知时，您需要使用 [`projectId`](/versions/latest/sdk/constants/#easconfig)。此属性用于将 Expo 推送令牌归因于特定项目。对于使用 EAS 的项目，`projectId` 属性表示该项目的全局唯一标识符（UUID）。
`projectId` 在创建开发构建时会自动设置。但是，**我们建议在项目代码中手动设置它**。为此，您可以使用 [`expo-constants`](/versions/latest/sdk/constants/) 从应用配置中获取 `projectId` 值。
```ts
const projectId = Constants?.expoConfig?.extra?.eas?.projectId ?? Constants?.easConfig?.projectId;
const pushTokenString = (await Notifications.getExpoPushTokenAsync({ projectId })).data;
```
将 Expo 推送令牌归因于您项目的唯一 ID 的一个优点是，当项目在不同帐户之间转移或现有帐户更名时，它不会更改。
Step 4: 
## 获取开发版凭证
对于 Android 和 iOS，有不同的要求来设置您的凭证。
    对于 Android，您需要配置 **Firebase Cloud Messaging (FCM)** 以获取凭证，并设置您的 Expo 项目。
    请按照 [添加 Android FCM V1 凭证](/push-notifications/fcm-credentials) 中的步骤来设置您的凭证。
    > **warning** 需要付费的 Apple 开发者账户来生成凭证。
    对于 iOS，请确保您在要测试的设备上 [注册了您的 iOS 设备](/develop/development-builds/create-a-build/#create-a-development-build-for-the-device)，然后第一次运行 `eas build` 命令时。
    如果您第一次创建开发构建，系统会询问您启用推送通知。初次提示时，回答以下问题为“是”：
    - 为您的项目设置推送通知
    - 生成新的 Apple 推送通知服务密钥
> 如果您不使用 EAS Build，请手动运行 `eas credentials`。
Step 5: 
## 构建应用
```sh
$ eas build
```
Step 6: 
## 使用推送通知工具进行测试
创建并安装开发构建后，您可以使用 [Expo 推送通知工具](https://expo.dev/notifications) 快速向您的设备发送测试通知。
1. 启动项目的开发服务器：
   ```sh
$ npx expo start
```
2. 在您的设备上打开开发构建。
3. 在生成 `ExpoPushToken` 后，将该值与其他详细信息（例如消息标题和正文）一起输入到 Expo 推送通知工具中。
4. 点击 **Send a Notification** 按钮。
从工具发送通知后，您应该会在设备上看到通知。以下是 Android 设备接收推送通知的示例。


## 使用 Expo 推送服务发送通知

学习如何从您的服务器调用 Expo 推送服务 API 发送推送通知。

[`expo-notifications`](/versions/latest/sdk/notifications) 库提供了推送通知的所有客户端功能。Expo 还处理将推送通知发送到 FCM 和 APNs，然后将其发送到特定设备。您所需要做的就是使用 [`getExpoPushTokenAsync`](/versions/latest/sdk/notifications/#getexpopushtokenasyncoptions) 获得的 `ExpoPushToken` 向 Expo 推送 API 发送请求。
> 如果您更愿意构建一个直接与 APNs 和 FCM 通信的服务器，请参阅 [使用 FCM 和 APNs 发送通知](/push-notifications/sending-notifications-custom/)。这比使用 Expo 推送服务更复杂，但允许更精细的控制，并且可以完全访问所有 FCM 和 APNs 功能。
## 使用服务器发送推送通知
在您设置完推送通知凭据并添加逻辑以获取 `ExpoPushToken` 后，您可以通过 HTTPS POST 请求将其发送到 Expo API。您可以通过设置一个有数据库的服务器来做到这一点（或者您也可以编写一个命令行工具来发送它们，或直接从您的应用程序发送它们）。
Expo 团队和社区为您在几种不同的语言中创建了后端：
| SDKs                                                                                                     | Back-end | Maintained by |
| -------------------------------------------------------------------------------------------------------- | -------- | ------------- |
| [expo-server-sdk-node](https://github.com/expo/expo-server-sdk-node)                                     | Node.js  | Expo team     |
| [expo-server-sdk-python](https://github.com/expo/expo-server-sdk-python)                                 | Python   | Community     |
| [expo-server-sdk-ruby](https://github.com/expo/expo-server-sdk-ruby)                                     | Ruby     | Community     |
| [expo-push-notification-client-rust](https://github.com/katayama8000/expo-push-notification-client-rust) | Rust     | Community     |
| [expo-notifier](https://github.com/symfony/expo-notifier)                                                | Symfony  | Symfony       |
| [exponent-server-sdk-php](https://github.com/Alymosul/exponent-server-sdk-php)                           | PHP      | Community     |
| [expo-server-sdk-php](https://github.com/ctwillie/expo-server-sdk-php)                                   | PHP      | Community     |
| [exponent-server-sdk-golang](https://github.com/oliveroneill/exponent-server-sdk-golang)                 | Golang   | Community     |
| [exponent](https://github.com/9ssi7/exponent)                                                            | Golang   | Community     |
| [exponent-server-sdk-elixir](https://github.com/rdrop/exponent-server-sdk-elixir)                        | Elixir   | Community     |
| [expo-server-sdk-dotnet](https://github.com/glyphard/expo-server-sdk-dotnet)                             | dotnet   | Community     |
| [expo-server-sdk-java](https://github.com/hlspablo/expo-server-sdk-java)                                 | Java     | Community     |
| [laravel-expo-notifier](https://github.com/YieldStudio/laravel-expo-notifier)                            | Laravel  | Community     |
上述每个示例服务器都是 Expo 推送服务 API 的包装器。
## 可靠地实现推送通知
推送通知从您的服务器到接收设备要经过多个系统。通知大多数时间都能送达。然而，偶尔会出现沿途系统的问题以及它们之间的网络连接。处理错误有助于推送通知更可靠地到达目的地。
### 限制并发连接
在一次性发送大量推送通知时，请限制并发连接的数量。[Node SDK](https://github.com/expo/expo-server-sdk-node) 为您实现了这一点，并最多打开六个并发连接。这可以平滑您的峰值负载，并帮助 Expo 推送通知服务成功接收推送通知请求。
### 出现失败时重试
发送推送通知的第一步是将其交付给 Expo 推送通知服务，后者会将其内部添加到一个队列中，以便交付给 Google（FCM v1）和 Apple （APNs）。这第一步可能由于几种原因而失败：
- 您的服务器与 Expo 推送通知服务之间的网络问题
- Expo 通知服务出现停机或可用性降低
- 错误配置的推送凭据
- 无效的通知有效负载
其中一些故障是临时的。例如，如果 Expo 推送通知服务宕机或无法访问并且您遇到网络错误——HTTP 429 错误（请求过多）或 HTTP 5xx 错误（服务器错误）——请使用 [指数退避](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) 等待几秒钟后再重试。如果第一次重试尝试失败，请等待更长时间（遵循指数退避）然后再次重试。这样可以让临时不可用的服务在您重试之前恢复。
其他故障则不会自行解决。例如，如果您的推送通知有效负载格式错误，您可能会收到一个解释有效负载问题的 HTTP 400 响应。如果您的项目没有推送凭据，或者您在同一请求中为不同项目发送推送通知，您也会收到错误。
### 检查推送凭据以寻找错误
Expo 推送通知服务在成功接收通知时会响应[**推送票据**](#push-tickets)。推送票据表明 Expo 已收到您的通知有效负载，但可能还需要发送它。每个推送票据包含一个票据 ID，您稍后可使用该 ID 查找[推送收据](#push-receipts)。推送收据在 Expo 尝试将通知交付给 FCM 或 APNs 后可用。它告诉您推送通知提供方的交付是否成功。
您必须检查您的推送收据。如果在交付推送通知时出现问题，推送收据是获取底层原因信息的最佳途径。例如，收据可能会指示 FCM 或 APNs、Expo 推送通知服务或您的通知有效负载存在问题。
推送收据也可能会告诉您接收设备是否已取消订阅通知（例如，通过撤销通知权限或卸载应用程序）。如果 APNs 或 FCM 返回该信息，推送收据将包含一个 `details` → `error` 字段，设置为 `DeviceNotRegistered`。在这种情况下，除非该设备重新向您的服务器注册，否则停止向该设备的推送令牌发送通知，以确保您的应用程序依然良好。`DeviceNotRegistered` 错误只在 Google 或 Apple 认为设备未注册时出现在推送收据中。需要一段未定义的时间，通常很难通过卸载应用程序然后立即发送推送通知来测试。
我们建议在发送推送通知后 15 分钟检查推送收据。尽管推送收据通常会更快可用，但 15 分钟的窗口能给 Expo 推送通知服务提供充裕的时间来使收据可获取。如果在 15 分钟后没有推送收据，则很可能表示 Expo 推送通知服务出现错误。最后，推送收据在 24 小时后被清除。
### 服务水平协议（SLA）
Expo 推送通知服务没有 SLA，FCM 和 APNs 服务也可能会偶尔中断。通过遵循上述指导，您可以使您的应用程序在临时服务中断时仍然保持稳健。
## HTTP/2 API
您可以选择直接向我们的 HTTP/2 API 发送请求，而不是使用之前列出的其中一个库（该 API 当前不需要任何身份验证）。
为此，向 `https://exp.host/--/api/v2/push/send` 发送 POST 请求，带有以下 HTTP 头：
```text
host: exp.host
accept: application/json
accept-encoding: gzip, deflate
content-type: application/json
```
这是使用 cURL 发送的 "hello world" 推送通知，您可以使用终端发送（请将占位符推送令牌替换为您自己的）：
```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 服务器发送请求的数量。** 这是一个发送四条消息的示例请求正文：
```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 推送服务还可选择接受 gzip 压缩请求正文。这可以大大减少发送大量通知所需的上传带宽。[Node Expo Server SDK](https://github.com/expo/expo-server-sdk-node) 会为您自动 gzip 请求，并自动限制您的请求以平滑负载，因此我们强烈推荐它。
### 推送票据
上述请求将以 JSON 对象响应，包含两个可选字段 `data` 和 `errors`。`data` 将包含一系列[**推送票据**](#push-ticket-format)，按消息发送的顺序排列（或者一个推送票据对象，如果您仅将单条消息发送给单个接收者）。每个票据包括一个 `status` 字段，指示 Expo 是否成功接收了通知，如果成功，则还有一个 `id` 字段可用于稍后获取推送收据。
> `ok` 的状态以及收据 ID 表示消息已被 Expo 的服务器接收，**而不是**接收者收到（要证明这一点，您需要检查[推送收据](#push-receipts)）。
继续上述示例，以下是成功响应正文的样子：
```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`，并包含描述错误的字段，如下所示：
```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 推送通知服务。
### 推送收据
在接收一批通知后，Expo 会将每条通知排队交付给 Android 和 iOS 推送通知服务（分别为 FCM 和 APNs）。大多数通知通常会在几秒钟内发送。但是，有时可能需要更长时间才能交付通知，特别是当 Android 或 iOS 推送通知服务花费的时间超出正常范围时，或者如果 Expo 的推送服务基础设施负载较高。
一旦 Expo 将通知交付给 Android 或 iOS 推送通知服务，Expo 将创建一个[**推送收据**](#push-receipt-response-format)，指示 Android 或 iOS 推送通知服务是否成功接收了通知。如果在交付通知时发生错误，可能是由于凭据故障或服务停机，推送收据将包含该错误的更多信息。
要获取推送收据，向 `https://exp.host/--/api/v2/push/getReceipts` 发送 POST 请求。请求正文必须是一个 JSON 对象，包含名为 `ids` 的数组，其元素为票据 ID 字符串：
```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)与推送票据的正文非常相似；它是一个 JSON 对象，包含两个可选字段 `data` 和 `errors`。`data` 包含收据 ID 到收据的映射。收据包括一个 `status` 字段以及两个可选的 `message` 和 `details` 字段（当 `"status": "error"` 的情况下）。如果没有请求的收据 ID 的推送收据，则该映射不会包含该 ID。这是对上述请求的成功响应的样子：
```json
{
  "data": {
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": { "status": "ok" },
    "ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ": { "status": "ok" }
    // 当没有给定 ID 的收据时（例如 YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY），
    // 响应中会省略该 ID。
  }
}
```
**您必须检查每个推送收据，因为它可能包含您需要解决的错误信息。** 例如，如果某个设备不再符合接收通知的条件，Apple 的文档建议您停止向该设备发送通知。推送收据包含有关这些错误的信息。
> 即使收据的 `status` 显示为 `ok`，也不能保证设备已收到该消息；推送收据中的 "ok" 仅表示 Android（FCM）或 iOS（APNs）推送通知服务成功接收了该通知。如果接收设备关闭，例如，iOS 或 Android 推送通知服务将尝试交付消息，但设备并不一定会接收它。
如果整个请求失败，HTTP 状态码将为 4xx 或 5xx，而 `errors` 字段将是一个错误对象数组（通常只有一个）。否则，HTTP 状态码将为 200，您的消息将送往用户的设备。
## 错误
Expo 提供有关此整个过程中发生的任何错误的详细信息。我们将在下面介绍一些最常见的错误，以便您在服务器上实现自动处理的逻辑。
如果出于某种原因，Expo 无法将消息传递给 Android 或 iOS 推送通知服务，推送收据的详细信息也可能包含特定于服务的信息。这主要用于调试和向 Expo 报告可能的错误。
### 单个错误
在推送票据和推送收据内，寻找一个 `details` 对象及其 `error` 字段。如果存在，它可能是以下值之一，您应如下处理这些错误：
### 推送票据错误
- `DeviceNotRegistered`: 该设备无法再接收推送通知，您应停止向相应的 Expo 推送令牌发送消息。
### 推送收据错误
- `DeviceNotRegistered`: 该设备无法再接收推送通知，您应停止向相应的 Expo 推送令牌发送消息。
- `MessageTooBig`: 总的通知有效负载过大。在 Android 和 iOS 上，总有效负载必须最大为 4096 字节。
- `MessageRateExceeded`: 您向给定设备发送消息的频率太高。实施指数退避并慢慢重试发送消息。
- `MismatchSenderId`: 这表明您的 FCM 推送凭据存在问题。FCM 推送凭据有两个部分：您的 FCM 服务器密钥和您的 **google-services.json** 文件。两者必须与相同的发送者 ID 关联。您可以在[找到服务器密钥的同一位置](/push-notifications/push-notifications-setup/#upload-server-credentials)找到发送者 ID。检查您项目的 EAS 控制面板中的服务器密钥，确保该密钥与项目中的 **google-services.json** 文件的 `project_number` 保持一致，这些信息可以在 Firebase 控制台的 **项目设置** > **云消息** 标签 > **云消息 API（遗留版）** 中找到。
- `InvalidCredentials`: 您独立应用的推送通知凭据无效（例如，您可能已经撤销了它们）。
  - **Android**: 确保按照[上传 FCM V1 服务器凭据](/push-notifications/fcm-credentials)中指定的方式正确上传 Firebase 控制台中的服务器密钥。
  - **iOS**: 运行 `eas credentials` 并按照提示重新生成新的推送通知凭据。如果您撤销了 APN 密钥，所有依赖该密钥的应用在您上传新的密钥之前都将无法发送或接收推送通知。上传新的 APN 密钥将**不**更改用户的 Expo 推送令牌。有时，这些错误将包含更多细节，声称存在 `InvalidProviderToken` 错误。这实际上与您的 APN 密钥**和**您的配置文件有关。要解决此错误，您应重新构建应用，并重新生成新的推送密钥和配置文件。
> 要更好地理解 iOS 凭据，包括推送通知凭据，请阅读我们的[应用签名文档](/app-signing/app-credentials#ios)。
### 请求错误
如果整个请求中推送票据或推送收据发生错误，`errors` 对象可能包含以下值之一，您应处理这些错误：
- `TOO_MANY_REQUESTS`: 您超过了每个项目每秒 600 条通知的请求限制。我们建议在您的服务器中实现速率限制，以防止每秒发送超过 600 条通知（请注意，如果您使用 [expo-server-sdk-node](https://github.com/expo/expo-server-sdk-node)，这已经实现，并且还实现了重试的指数退避）。
- `PUSH_TOO_MANY_EXPERIENCE_IDS`: 您正在尝试向不同的 Expo 体验发送推送通知，例如，`@username/projectAAA` 和 `@username/projectBBB`。检查 `details` 字段，以获取请求中体验名称与其相关联推送令牌之间的映射，并删除来自另一体验的任何推送令牌。
- `PUSH_TOO_MANY_NOTIFICATIONS`: 您尝试在一个请求中发送超过 100 条推送通知。确保您在每个请求中仅发送 100 条（或更少）通知。
- `PUSH_TOO_MANY_RECEIPTS`: 您尝试在一个请求中获取超过 1000 条推送收据。确保您只发送最多 1000 条（或更少）票据 ID 字符串以获取推送收据。
## 额外安全性
您可以要求所有推送请求在我们将其发送到用户之前使用有效的[访问令牌](/accounts/programmatic-access)。您可以从 [EAS 控制面板](https://expo.dev/settings/access-tokens)启用此增强的推送安全性。
默认情况下，您可以通过发送他们的 Expo 推送令牌和消息所需的任何文本或附加数据来向用户发送通知。这很容易设置，但**如果令牌泄漏，恶意用户将能够伪装您的服务器并向您的用户发送消息。** 我们从未收到过此类报告。然而，为了遵循最佳安全实践，我们提供了将访问令牌与推送令牌一起作为额外的安全层的选项。
如果您使用 [`expo-server-sdk-node`](https://github.com/expo/expo-server-sdk-node#usage)，请升级到至少 `v3.6.0` 并在构造函数中将您的 `accessToken` 作为选项传递。否则，请在与我们的推送 API 的任何请求中传入头部 `'Authorization': 'Bearer ${accessToken}'`。
在您启用推送安全性后，任何未使用有效访问令牌发送的请求都将导致错误代码：`UNAUTHORIZED`。
## 格式
### 消息请求格式
每条消息必须是具有给定字段的 JSON 对象（仅 `to` 字段为必填项）：
| 字段                | 平台           | 类型                                                      | 描述                                                                                                                                                                                                                                                                                                                        |
| ------------------- | -------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`                | Android 和 iOS | `string \| string[]`                                      | Expo 推送令牌或指定此消息接收者的 Expo 推送令牌数组。                                                                                                                                                                                                                                                                       |
| `_contentAvailable` | 仅限 iOS       | `boolean \| undefined`                                    | 当此字段设置为 true 时，通知将导致 iOS 应用在后台启动以运行[后台任务](/versions/latest/sdk/notifications/#background-notifications)。您的应用需要[配置](/versions/latest/sdk/notifications/#background-notification-configuration)以支持此功能。                                                                            |
| `data`              | Android 和 iOS | `Object`                                                  | 传递到您的应用程序的 JSON 对象。它最多可以达到大约 4KiB；发送给 Apple 和 Google 的通知有效负载总计必须最多为 4KiB，否则您将收到“消息过大”错误。                                                                                                                                                                             |
| `title`             | Android 和 iOS | `string`                                                  | 在通知中显示的标题。通常在通知正文上方显示。映射到 [`AndroidNotification.title`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidNotification) 和 [`aps.alert.title`](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Payload-key-reference)。 |
| `body`              | Android 和 iOS | `string`                                                  | 在通知中显示的消息。映射到 [`AndroidNotification.body`](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidNotification) 和 [`aps.alert.body`](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Payload-key-reference)。                           |
| `ttl`               | Android 和 iOS | `number`                                                  | 生命时间：消息在未被送达的情况下可以被保留的秒数以便后续交付。默认设置为 `undefined`，以使用每个提供者的相应默认值（Android/FCM 和 iOS/APNs 的一个月）。                                                                                                                                                                    |
| `expiration`        | Android 和 iOS | `number`                                                  | Unix 纪元以来的时间戳，指定消息过期的时间。效果与 `ttl` 相同（`ttl` 优先于 `expiration`）。                                                                                                                                                                                                                                 |
| `priority`          | Android 和 iOS | `'default' \| 'normal' \| 'high'`                         | 消息的交付优先级。指定 `default` 或省略此字段以在每个平台上使用默认优先级（Android 为“normal”，iOS 为“high”）。                                                                                                                                                                                                             |
| `subtitle`          | 仅限 iOS       | `string`                                                  | 在通知标题下方显示的副标题。映射到 [`aps.alert.subtitle`](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Payload-key-reference)。                                                                                                                                             |
| `sound`             | 仅限 iOS       | `string \| null`                                          | 当接收者接收到此通知时播放声音。指定 `default` 以播放设备的默认通知声音，或省略此字段以不播放声音。自定义声音需要通过配置插件[配置](/versions/latest/sdk/notifications/#configurable-properties)，然后指定包括文件扩展名。示例：`bells_sound.wav`。                                                                         |
| `badge`             | 仅限 iOS       | `number`                                                  | 要在应用程序图标上显示的徽章编号。指定零以清除徽章。                                                                                                                                                                                                                                                                        |
| `interruptionLevel` | 仅限 iOS       | `'active' \| 'critical' \| 'passive' \| 'time-sensitive'` | 通知的重要性和交付时机。字符串值对应于 [`UNNotificationInterruptionLevel`](https://developer.apple.com/documentation/usernotifications/unnotificationinterruptionlevel) 枚举案例。                                                                                                                                          |
| `channelId`         | 仅限 Android   | `string`                                                  | 显示此通知的通知通道的 ID。如果指定了 ID，但相应的通道在设备上（尚未由您的应用创建）不存在，则通知将不会显示给用户。                                                                                                                                                                                                        |
| `icon`              | 仅限 Android   | `string`                                                  | 通知的图标。Android 可绘制资源的名称（示例：`myicon`）。默认值为 [配置插件](/versions/latest/sdk/notifications/#configurable-properties) 中指定的图标。                                                                                                                                                                     |
| `richContent`       | Android 和 iOS | `Object`                                                  | 当前支持设置通知图片。提供一个键为 `image`、值为字符串类型的对象，该值是图片 URL。Android 将直接显示该图片。在 iOS 上，您需要向您的应用添加一个通知服务扩展目标。请参见[此示例](https://github.com/expo/expo/pull/36202)了解如何实现。                                                                                      |
| `categoryId`        | Android 和 iOS | `string`                                                  | 此通知关联的通知类别 ID。[在此处了解更多关于通知类别的信息](/versions/latest/sdk/notifications/#manage-notification-categories-interactive-notifications)。                                                                                                                                                                 |
| `mutableContent`    | 仅限 iOS       | `boolean`                                                 | 指定此通知是否可以被[客户端应用拦截](https://developer.apple.com/documentation/usernotifications/modifying_content_in_newly_delivered_notifications?language=objc)。默认为 `false`。                                                                                                                                        |
**关于 `ttl` 的说明**：在 Android 上，我们尽力立即交付零 TTL 的消息，并且不对其进行限制。然而，设置 TTL 为低值（例如零）可能会导致正常优先级的通知无法到达处于待机模式的 Android 设备。为确保通知发送，TTL 必须足够长，以便设备能够从待机模式中唤醒该通知。此字段在指定了两者时对 `expiration` 优先。
**关于 `priority` 的说明**：在 Android 上，正常优先级的消息不会在待机设备上打开网络连接，因此它们的交付可能会延迟，以节省电池。高优先级消息更有可能立即交付，可能会唤醒待机设备以打开网络连接，从而消耗电能。在 iOS 上，正常优先级消息会在考虑设备电量问题的情况下发送，并可能会分组并集中交付。它们受到限制，Apple 可能不会交付。高优先级消息通常会被立即发送。正常优先级对应于 APNs 优先级级别 5，而高优先级对应于 10。
**关于 `channelId` 的说明**：如果为 null，将使用“默认”通道；如果该通道尚未创建，Expo 会在设备上创建该通道。但是请谨慎使用，因为“默认”通道是用户可见的，您可能无法完全删除它。
### 推送票据格式
```js
{
  "data": [
    {
      "status": "error" | "ok",
      "id": string, // 这是收据 ID
      // 如果 status === "error"
      "message": string,
      "details": JSON
    },
    ...
  ],
  // 仅如果整体请求出现错误时填充
  "errors": [{
    "code": string,
    "message": string
  }]
}
```
### 推送收据请求格式
```js
{
  "ids": string[]
}
```
### 推送收据响应格式
```js
{
  "data": {
    收据 ID: {
      "status": "error" | "ok",
      // 如果 status === "error"
      "message": string,
      "details": JSON
    },
    ...
  },
  // 仅如果整体请求出现错误时填充
  "errors": [{
    "code": string,
    "message": string
  }]
}
```
## 交付保证
Expo 尽力将通知交付给 Google 和 Apple 操作的推送通知服务。Expo 的基础设施旨在至少尝试一次将通知交付给基础的推送通知服务。通知更可能多次交付给 Google 或 Apple，而不是一次都不交付；然而，这两种结果都是不常见的。
一旦通知被交给基础推送通知服务，Expo 将创建一个“推送收据”，记录交接是否成功。推送收据表示基础推送通知服务是否接收了该通知。
最后，Google 和 Apple 的推送通知服务遵循它们自己的政策将通知交付到设备。
## 故障排除
Note: 网络连接问题
---
本节帮助您诊断和解决常见网络问题。您的服务器必须能够连接到美国地区的 Google Cloud Platform 服务，因为 Expo 的推送通知服务托管在这里。
#### DNS 解析
测试您的服务器是否能解析 Expo 的推送服务域名：
```bash
dig exp.host
# 使用公共 DNS 服务器检查
dig @8.8.8.8 exp.host
```
#### 网络路由和连接
验证您的服务器是否能到达 Expo 的终端节点：
```bash
# 使用 traceroute 识别路由问题
traceroute exp.host
# 测试基本连接性
ping exp.host
# 测试与推送服务器的 HTTPS 连接。
# 您应该收到带有 200 状态代码的 HTTP 响应头。
curl --verbose https://exp.host/
```
需要检查的常见问题：
- 防火墙规则阻止出站 HTTPS（端口 443）流量
- 可能需要身份验证或特殊配置的企业代理服务器
- 限制出站连接的网络 ACL 或安全组（在云环境中）
- 由于 MTU 大小问题导致的分包
#### TLS 证书验证
确保您的服务器能够验证服务器的 TLS 证书：
```bash
openssl s_client -connect exp.host:443 -servername exp.host
```
我们使用主要服务提供商（包括 Cloudflare、Google 和 Let's Encrypt）签名的标准 TLS 证书。
---


## 处理传入通知

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

[`expo-notifications`](/versions/latest/sdk/notifications) 库包含事件监听器，用于处理您的应用在接收到通知时的响应方式。
## 通知事件监听器
[`addNotificationReceivedListener`](/versions/latest/sdk/notifications/#addnotificationreceivedlistenerlistener) 和 [`addNotificationResponseReceivedListener`](/versions/latest/sdk/notifications/#addnotificationresponsereceivedlistenerlistener) 事件监听器在接收到通知或与其互动时接收一个对象。
这些监听器允许您在应用打开并处于前台时及应用处于后台或关闭状态并且用户点击通知时，添加通知接收时的行为。
```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 通知对象示例来自 
---
使用 `Notifications.addNotificationReceivedListener` 时，回调函数接收到的 `notification` 对象示例：
```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
}
```
您可以通过记录 `notification.request.content.data` 对象直接访问通知自定义数据：
```json
// console.log(notification.request.content.data);
{
  "senderId": "user123",
  "senderName": "John Doe",
  "messageId": "msg789",
  "conversationId": "conversation-456",
  "messageType": "text",
  "timestamp": 1724766427
}
```
---
Note: iOS 通知对象示例来自 
---
使用 `Notifications.addNotificationReceivedListener` 时，回调函数接收到的 `notification` 对象示例：
```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
}
```
您可以通过记录 `notification.request.content.data` 对象直接访问通知自定义数据：
```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) 文档。
## 前台通知行为
要处理应用在 **前台** 接收到通知时的行为，请使用 [`Notifications.setNotificationHandler`](/versions/latest/sdk/notifications/#handling-incoming-notifications-when-the-app-is) 和 `handleNotification()` 回调来设置以下选项：
- `shouldPlaySound`
- `shouldSetBadge`
- `shouldShowBanner`
- `shouldShowList`
```jsx
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldPlaySound: false,
    shouldSetBadge: false,
    shouldShowBanner: true,
    shouldShowList: true,
  }),
});
```
## 关闭通知行为
在 Android 上，用户可以设置某些操作系统级别的设置，通常涉及性能和电池优化，这可能会在应用关闭时阻止通知的送达。例如，在使用 Android 9 及更低版本的 OnePlus 设备上有一个设置选项是 **深度清理**。


# 参考资料

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

学习如何创建或使用 Google 服务账户密钥，以通过 FCM 发送 Android 通知。

## 创建新的 Google 服务账户密钥
以下是在 EAS 中配置新的 Google 服务账户密钥以通过 FCM V1 发送 Android 通知的步骤。
Step 1: 
在 [Firebase 控制台](https://console.firebase.google.com) 中为你的应用创建一个新的 Firebase 项目。如果你已经为你的应用创建了 Firebase 项目，请继续下一步。
Step 2: 
在 Firebase 控制台中，打开 **项目设置** > [**服务账户**](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk)。
Step 3: 
点击 **Generate New Private Key**，然后通过点击 **Generate Key** 来确认。安全存储包含私钥的 JSON 文件。
Step 4: 
将 JSON 文件上传到 EAS 并配置它以发送 Android 通知。这可以使用 EAS CLI 或在 [EAS 仪表板](https://expo.dev) 中完成。
- 运行 `eas credentials`
- 选择 `Android` > `production` > `Google Service Account`
- 选择 `Manage your Google Service Account Key for Push Notifications (FCM V1)`
- 选择 `Set up a Google Service Account Key for Push Notifications (FCM V1)` > `Upload a new service account key`
- 如果你之前已将 JSON 文件存储在项目目录中，则 EAS CLI 会自动检测该文件并提示你选择它。按 <kbd>Y</kbd> 继续。
> **注意**: 将 JSON 文件添加到你的版本源控制忽略文件中（例如，**.gitignore**），以避免将其提交到你的仓库，因为它包含敏感数据。
- 在 **项目设置** 下，点击导航菜单中的 [**凭据**](https://expo.dev/accounts/[account]/projects/[project]/credentials)
- 对于 **Android**，点击 **添加应用标识符** 或选择现有的 **应用标识符**
- 在 **服务凭据** > **FCM V1 服务账户密钥** 下，点击 **添加服务账户密钥**
- 在 **Upload new key** 下，上传你的 JSON 凭据并点击 **Save**
Step 5: 
在你的项目中配置 **google-services.json** 文件。从 Firebase 控制台下载并将其放置在项目目录的根目录中。
此文件是将你的 Android 应用注册到 FCM 所必需的。你可以将此文件提交到你的仓库，因为它包含来自 Firebase 项目的公开标识符。
**注意**: 如果 **google-services.json** 已经设置好，你可以跳过此步骤。
在 **app.json** 中，添加 [`expo.android.googleServicesFile`](/versions/latest/config/app/#googleservicesfile)，其值为 **google-services.json** 的路径。
```json app.json
{
  "expo": {
  "android": {
    "googleServicesFile": "./path/to/google-services.json"
  }
}
```
Step 6: 
一切就绪！你现在可以使用 FCM V1 协议通过 Expo 推送通知向 Android 设备发送通知。
## 使用现有的 Google 服务账户密钥
Step 1: 
在 Google Cloud 控制台中打开 [IAM 管理页面](https://console.cloud.google.com/iam-admin/iam?authuser=0)。在权限选项卡中，找到您打算修改的 **主体**，并点击 **编辑主体** 的铅笔图标。
Step 2: 
点击 **Add Role**，然后从下拉菜单中选择 **Firebase Messaging API Admin** 角色。点击 **Save**。
Step 3: 
你必须通过 EAS CLI 或在 [EAS 仪表板](https://expo.dev) 中指定 EAS 使用哪个 JSON 凭据文件来发送 FCM V1 通知。你可以上传一个新的 JSON 文件或选择之前上传的文件。
- 运行 `eas credentials`
- 选择 `Android` > `production` > `Google Service Account`
- 选择 `Manage your Google Service Account Key for Push Notifications (FCM V1)`
- 选择 `Set up a Google Service Account Key for Push Notifications (FCM V1)` > `Upload a new service account key`
- EAS CLI 会自动检测你本地机器上的文件并提示你选择它。按 <kbd>Y</kbd> 继续。
> **注意**: 将 JSON 文件添加到你的版本源控制忽略文件中（例如，**.gitignore**），以避免将其提交到你的仓库，因为它包含敏感数据。
- 在 **Project settings** 下，点击导航菜单中的 [**凭据**](https://expo.dev/accounts/[account]/projects/[project]/credentials)
- 对于 **Android**，点击 **Add Application Identifier** 或选择现有的 **Application identifier**
- 在 **Service Credentials** > **FCM V1 service account key** 下，点击 **Add a service account key**
- 在 **Upload new key** 下，上传你的 JSON 凭据并点击 **Save**
Step 4: 
在你的项目中配置 **google-services.json** 文件。从 Firebase 控制台下载并将其放置在项目目录的根目录中。
此文件是将你的 Android 应用注册到 FCM 所必需的。你可以将此文件提交到你的仓库，因为它包含来自 Firebase 项目的公开标识符。
**注意**: 如果 **google-services.json** 已经设置好，你可以跳过此步骤。
在 **app.json** 中，添加 [`expo.android.googleServicesFile`](/versions/latest/config/app/#googleservicesfile)，其值为 **google-services.json** 的路径。
```json app.json
{
  "expo": {
    "android": {
    }
  }
}
```
Step 5: 
一切就绪！你现在可以使用 FCM V1 协议通过 Expo 推送通知向 Android 设备发送通知。


## 使用 FCM 和 APNs 发送通知

学习如何使用 FCM 和 APNs 发送通知。

您可能需要对通知进行更精细的控制，在这种情况下，直接与 FCM 和 APNs 通信可能是必要的。Expo 平台并不强制您使用 Expo 应用服务，并且 `expo-notifications` API 是与推送服务无关的。
> **注意**：本指南并不旨在成为通过 FCM 或 APNs 发送通知的全面资源。我们建议您阅读官方文档，以确保您遵循最新的说明。
## 获取 FCM 或 APNs 的设备令牌
使用 Expo 通知服务时，您使用通过 [`getExpoPushTokenAsync`](/versions/latest/sdk/notifications/#getexpopushtokenasyncoptions-expotokenoptions-expopushtoken) 获得的 `ExpoPushToken`。
如果您想通过 FCM 或 APNs 发送通知，您需要通过 [`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
```
## FCMv1 服务器
本指南基于 [Firebase 官方文档](https://firebase.google.com/docs/cloud-messaging/server)。
与 FCM 的通信是通过发送 POST 请求来完成的。然而，在发送或接收任何通知之前，您需要按照步骤 [配置 FCM](/push-notifications/fcm-credentials/) 并获取您的 `FCM-SERVER-KEY`。
### 获取身份验证令牌
FCM 需要一个 Oauth 2.0 访问令牌，必须通过其中一种方法生成，[“更新发送请求的授权”](https://firebase.google.com/docs/cloud-messaging/migrate-v1#update-authorization-of-send-requests)。
出于测试目的，您可以使用 Google Auth Library 和您之前获得的私钥文件，生成短期令牌用于单个通知，如下所示，这是根据 Firebase 文档调整的 Node 示例：
```ts
import { JWT } from 'google-auth-library';
function getAccessTokenAsync(
  key: string // 您 FCM 私钥文件的内容
) {
  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);
    });
  });
}
```
### 发送通知
下面的示例代码调用了上面的 `getAccessTokenAsync()` 来获取 Oauth 2.0 令牌，然后构建并发送通知 POST 请求。请注意，与 FCM 旧版协议不同，请求的端点包含您的 Firebase 项目的名称。
```ts
// FCM_SERVER_KEY: 您 FCM 私钥文件路径的环境变量
// FCM_PROJECT_NAME: 您的 Firebase 项目名称
// FCM_DEVICE_TOKEN: 客户端的设备令牌（见上文）
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` 支持哪些字段。
FCM 还提供了一些 [多种语言的服务器端库](https://firebase.google.com/docs/cloud-messaging/send-message#node.js)，您可以使用这些库代替原始的 `fetch` 请求。
### 如何找到 FCM 服务器密钥
您的 FCM 服务器密钥可以通过确保您已经遵循了 [配置步骤](/push-notifications/push-notifications-setup/#android)，而不是将您的 FCM 密钥上传到 Expo，您可以直接在您的服务器中使用该密钥（在上一个示例中的 `FCM-SERVER-KEY`）。
## APNs 服务器
> **info** 本文档基于 [Apple 的文档](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html)，本节涵盖了让您入门的基础知识。
与 APNs 的通信比与 FCM 更复杂。一些库将所有这些功能包装成一到两个函数调用，例如 [`node-apn`](https://github.com/node-apn/node-apn)。然而，在下面的示例中，仅使用了一小部分库。
### 客户端 APNs 权限
只有当您的 iOS 应用具有 APNs 权限时，接收推送通知才有效。对于使用 [CNG](/workflow/continuous-native-generation/) 的应用，Expo 配置需要以两种方式之一进行修改：
- **推荐**：将 `expo-notifications` 库添加到您的应用中，并确保其插件出现在您的 [应用配置](/workflow/configuration/) 的 `plugins` 数组中：
```json app.json
{
  "expo": {
    "plugins": [
      "expo-notifications"
      ]
  }
}
```
- 如果您不打算使用 `expo-notifications` 库，则应 [手动将 `aps-environment` 权限添加到 Expo 配置中](/build-reference/ios-capabilities/#entitlements)，如下示例所示：
```json app.json
{
  "expo": {
    "ios": {
      "entitlements": {
        "aps-environment": "development"
      }
    }
  }
}
```
如果您没有使用 CNG，那么您应该 [在 Xcode 中添加推送通知权限](https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns)。
> **注意**：如果您正在将 Expo 应用程序从 SDK 51 及更早版本升级，您应该参考 [此 FYI 文档](https://expo.fyi/apns-entitlement-sdk-51)。
### 授权
最初，在向 APNS 发送请求之前，您需要获得向您的应用发送通知的权限。这是通过使用 iOS 开发者凭证生成的 JSON Web 令牌授予的：
- 与您的应用相关的 APN 密钥（`.p8` 文件）
- 上述 `.p8` 文件的密钥 ID
- 您的 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",
    },
  }
);
```
### HTTP/2 连接
获取 `authorizationToken` 后，您可以打开与 Apple 服务器的 HTTP/2 连接。在开发中，发送请求到 `api.sandbox.push.apple.com`。在生产中，发送请求到 `api.push.apple.com`。
以下是如何构造请求：
```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, // 这是您在客户端获取的原生设备令牌
  authorization: `bearer ${authorizationToken}`, // 这是在“授权”步骤中生成的 JSON Web 令牌
});
request.setEncoding('utf8');
request.write(
  JSON.stringify({
    aps: {
      alert: {
        title: "\uD83D\uDCE7 You've got mail!",
        body: 'Hello world! \uD83C\uDF10',
      },
    },
    experienceId: '@yourExpoUsername/yourProjectSlug', // 测试时需要在 Expo Go 应用中
    scopeKey: '@yourExpoUsername/yourProjectSlug', // 测试时需要在 Expo Go 应用中
  })
);
request.end();
```
> 此示例是最小的，并且不包含错误处理和连接池功能。出于测试目的，您可以参考 [`sendNotificationToAPNS`](https://github.com/expo/expo/blob/main/docs/public/static/examples/sendNotificationToAPNS.js) 示例代码。
APNs 在 [通知有效负载](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification#Payload-key-reference) 中提供了其支持字段的完整列表。


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

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

在设置 `expo-notifications` 库和 Expo 推送通知服务时的常见问题和常见问题解答的集合。
## Expo 推送通知服务常见问题解答
### 推送通知服务的费用
通过 Expo 推送通知服务发送通知没有相关费用。
### 发送通知的限制
每个项目每秒最多可以发送 600 条通知。如果超过此速率，将失败后续请求，直到速率再次低于每秒 600 条。
为了获得最佳结果，我们建议您在服务器上添加速率限制（这在 [`expo-server-sdk-node`](https://github.com/expo/expo-server-sdk-node) 中自动处理）和重试逻辑。
### 使用 Expo 推送通知服务不是强制的
您可以为 Expo 项目使用任何推送通知服务。 [`getDevicePushTokenAsync` 方法来自 `expo-notifications`](/versions/latest/sdk/notifications/#getdevicepushtokenasync-devicepushtoken) 允许您获取本地设备的推送令牌，您可以将其与其他服务一起使用，甚至可以 [通过 FCM 和 APNs 直接发送通知](/push-notifications/sending-notifications-custom)。
### 与通知服务的连接是加密的
Expo 与 Apple 和 Google 的连接是加密的并使用 HTTPS。
### 通知的内容不被存储
Expo 不会存储推送通知的内容，时间不超过将其传送到 Google 和 Apple 操作的推送通知服务所需的时间。通知仅存储在内存中和消息队列中，而不在数据库中。
### 通知内容可能会被 Expo 员工看到
如果 Expo 团队正在积极调试推送通知服务，我们可能会看到通知内容（例如，在断点处），但 Expo 不能看到推送通知内容。
### 投递保障
Expo 尽最大努力将通知投递到 Google 和 Apple 操作的推送通知服务。Expo 的基础设施设计用于至少一次交付给基础推送通知服务。在某些情况下，通知可能被 Google 或 Apple 投递多次或根本不投递，尽管这些情况很少见。
在将通知移交给基础推送通知服务后，Expo 创建一个“推送回执”，记录移交是否成功。推送回执标记基础推送通知服务是否接收了通知。
最后，Google 和 Apple 的推送通知服务根据其政策将通知投递给设备。
### `ExpoPushToken` 何时以及为何会改变
`ExpoPushToken` 在应用程序升级期间保持不变。在 Android 上，重新安装应用可能会导致令牌改变。在 iOS 上，即使卸载并重新安装应用，令牌也保持不变。
如果您更改了 [`applicationId`](/versions/latest/sdk/application/#applicationapplicationid) 或 `experienceId`（通常是 `@expoUsername/projectSlug`），它也会改变。
`ExpoPushToken` 永不失效。但是，如果您的用户卸载了应用，您将从 Expo 的服务器收到 `DeviceNotRegistered` 错误。这意味着您应该停止向此令牌发送通知。
## 推送通知故障排除
### 通知无法工作
推送通知有很多移动部分，因此可能由于多种原因导致此情况。为了缩小问题范围，请检查 [推送票据](/push-notifications/sending-notifications/#push-tickets) 和 [推送回执](/push-notifications/sending-notifications/#push-receipts) 中的错误消息。
您还可以通过测试 [本地通知](/versions/latest/sdk/notifications/#schedulenotificationasyncnotificationrequest-notificationrequestinput-promisestring) 进一步缩小范围。这确保您所有的客户端逻辑都是正确的，并将问题缩小到服务器端或应用凭据。
Note: 查看此处的快速终端命令以获取推送回执
---
1. 发送通知：
```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. 使用生成的票据 `id` 请求推送回执：
```sh
curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/getReceipts" -d '{
  "ids": [
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  ]
}'
```
---
### 开发时通知有效，但在发布模式下无效
这表明您可能配置了错误的凭据，或者根本没有在生产应用中配置它们。Expo Go 使用 Expo 的凭据，这使得在开发中可以处理通知。
当您为应用商店构建应用时，您需要生成并使用自己的凭据。在 Android 上，请按照 [此指南](/push-notifications/fcm-credentials) 操作。在 iOS 上，由您的 [推送密钥](/app-signing/app-credentials/#push-notification-keys) 处理（撤销与您的应用关联的推送密钥会导致您的通知无法投递。为此，请使用 `eas credentials` 添加新的推送密钥）。
有关更多信息，请参见 [应用签名](/app-signing/app-credentials)。
### Android 上偶尔停止接收通知
这可能与您发送的通知的 `priority` 级别有关。您可以了解更多关于 [Android 优先级](https://firebase.google.com/docs/cloud-messaging/http-server-ref#downstream-http-messages-json)。 [Expo 接受四种优先级](/push-notifications/sending-notifications/#message-request-format)：
- `default`：手动映射到 Apple 和 Google 文档中的默认优先级
- `high`：映射到 Apple 和 Google 文档中的高优先级
- `normal`：映射到 Apple 和 Google 文档中的正常优先级
- （省略优先级）：与指定 `default` 的效果完全相同
将优先级设置为 `high` 可以使您的通知在 Android 上更有可能显示。
### 处理过期的推送通知凭据
当您的推送通知凭据过期时，运行 `eas credentials`，选择 iOS 和构建配置文件，然后删除您的推送通知密钥并生成一个新的。
### iOS 上没有找到有效的 aps-environment 权限字符串错误
如果您尚未为您的 iOS 项目设置推送通知密钥，则会发生此错误。要检查，请访问 [项目凭据页面](https://expo.dev/accounts/[account]/projects/[project]/credentials/ios)。
要生成新的推送通知密钥，通过运行以下命令触发新构建：
```sh
$ eas build --profile [profile] --platform ios
```
有关视觉指南，请参见 [Expo 与 EAS 视频](https://youtu.be/BCCjGtKtBjE?t=2123)。
### 发送通知时出现错误信息
检查返回的推送票据或回执的 `details` 属性以获取更多信息。 [阅读此文](/push-notifications/sending-notifications/#errors) 了解常见错误代码响应及其相关解决方案。
### 在 iOS 上获取推送令牌耗时较长
`getDevicePushTokenAsync` 和 `getExpoPushTokenAsync` 有时在 iOS 上可能需要较长时间才能解析。这超出了 `expo-notifications` 的控制，正如 Apple 的 [推送通知故障排除](https://developer.apple.com/library/archive/technotes/tn2265/_index.html) 技术说明中所述：
> 这不一定是错误条件。系统可能根本没有互联网连接，因为它超出了任何蜂窝塔或 Wi-Fi 接入点的范围，或者可能处于飞行模式。您的应用应正常继续运行，仅禁用依赖于推送通知的功能，而不是将其视为错误。
以下是我们社区成员解决此问题的一些方法：
Note: 阅读苹果的技术说明以排除推送通知故障
---
阅读苹果的 [推送通知故障排除技术说明](https://developer.apple.com/library/archive/technotes/tn2265/_index.html)！这是此问题的单一最可靠信息来源。帮助您理解他们的建议：
- 确保设备与互联网有可靠的连接（尝试关闭 Wi-Fi 或切换到其他网络，并根据 [此 SO 答复](https://stackoverflow.com/a/34332047/1123156) 禁用对端口 5223 的防火墙阻止）。
- **裸 React Native 应用** 必须 [手动启用 **推送通知** 能力](/build-reference/ios-capabilities#manual-setup)。如果您在设置此功能时遇到问题，请参考 [此 Stack Overflow 答复](https://stackoverflow.com/a/10791240/1123156)。您可能还想通过记录持续连接的调试信息，进一步调试此问题，如 [此 Stack Overflow 答复](https://stackoverflow.com/a/8036052/1123156) 所述。
---
Note: 稍后再试
---
- 设备附近的 APNS 服务器可能因 [此论坛线程](https://developer.apple.com/forums/thread/52224) 指示而宕机。出去走走，稍后再试！
- 根据 [此 GitHub 评论](https://github.com/expo/expo/issues/10369#issuecomment-717872956) 的建议，再等几天再试。
---
Note: 禁用设备上的网络共享
---
您可能需要禁用网络共享，因为这可能影响注册，正如 [此 Stack Overflow 答复](https://stackoverflow.com/a/59156989/1123156) 所建议的。
---
Note: 重启设备
---
如果您刚更改了应用应注册的 APNS 服务器（通过在同一设备上安装 TestFlight 构建来自 Xcode 构建），您可能需要根据 [此 Stack Overflow 答复](https://stackoverflow.com/a/59864028/1123156) 重启设备。
---
Note: 为设备设置 SIM 卡
---
如果您遇到此问题的设备尚未设置 SIM 卡，则配置它可能有助于减轻此错误，正如 [此 Stack Overflow 答复](https://stackoverflow.com/a/19432504/1123156) 所建议的。
---
## 其他事项
### 通过 FCM 和 APNs 直接发送通知
如果您不使用 [Expo 推送通知服务](/push-notifications/sending-notifications)，而是希望直接与 Google 和 Apple 通信，请参阅 [通过 FCM 和 APNs 发送通知](/push-notifications/sending-notifications-custom)。
### Android 上的通知图标是灰色或白色方块
这表示您提供的图像资产存在问题。图像应该是全白色并带有透明背景（这是必需的，并由 Google 强制执行，而不是 Expo）。有关更多信息，请参见 [这篇文章](https://clevertap.com/blog/fixing-notification-icon-for-android-lollipop-and-above/)。


# 更多

## 升级 Expo SDK

了解如何在项目中逐步升级 Expo SDK 版本。

> **info** 我们建议逐步升级 SDK 版本，逐个进行。这样可以帮助你精准定位在升级过程中出现的故障和问题。
随着新的 SDK 发布，最新版本进入当前发布状态。这适用于 Expo Go，因为它只支持最新的 SDK 版本，而之前的版本不再受到支持。我们建议对生产应用使用 [开发版本](/develop/development-builds/introduction/)，因为在 EAS 服务上，较旧 SDK 版本的向后兼容性往往更长，但不是永久的。
如果你希望安装特定版本的 Expo Go，请访问 [expo.dev/go](https://expo.dev/go)。它支持 Android 设备/模拟器和 iOS 模拟器的下载。然而，由于 iOS 平台的限制，只有最新版本的 Expo Go 可用于实际的 iOS 设备安装。
## 如何升级到最新的 SDK 版本
Step 1: 
### 升级 Expo SDK
安装新的 Expo 包版本：
  For npm: 
    ```sh
$ npm install expo@^54.0.0
```
  For Yarn: 
    ```sh
$ yarn add expo@^54.0.0
```
  For pnpm: 
    ```sh
$ pnpm add expo@^54.0.0
```
  For Bun: 
    ```sh
$ bun install expo@^54.0.0
```
根据你要升级的 SDK，替换 `expo@^54.0.0` 为你所针对的 Expo SDK 版本范围。例如，`expo@^54.0.0` 代表 SDK 54。
Step 2: 
### 升级依赖项
升级所有依赖项以匹配安装的 SDK 版本。然后运行 [`expo-doctor`](/develop/tools/#expo-doctor) 命令检查常见问题。
```sh
$ npx expo install --fix
$ npx expo-doctor
```
Step 3: 
### 更新原生项目
- **如果你使用 [持续原生生成](/workflow/continuous-native-generation/)**: 如果你为以前的 SDK 版本在本地项目目录中生成了 **android** 和 **ios** 目录，请删除它们。下次你运行构建时，它们将被重新生成，无论是使用 `npx expo run:ios`、`npx expo prebuild`，还是使用 EAS Build。
- **如果你不使用 [持续原生生成](/workflow/continuous-native-generation/)**: 如果你有 **ios** 目录，请运行 `npx pod-install`。应用来自 [原生项目升级助手](/bare/upgrade/) 的任何相关更改。或者，你可以考虑 [采用 prebuild](/guides/adopting-prebuild/) 以便将来更轻松地升级。
Step 4: 
### 根据发布说明遵循其他说明
阅读你要升级的 SDK 版本的 [SDK 变更日志](#sdk-changelogs)。其中包含有关重大更改、弃用和可能影响你应用的其他更改的重要信息。请参阅发布说明页面底部的“升级你的应用”部分以获取任何附加说明。
## SDK 变更日志
每个 SDK 公告发布说明帖子包含有关弃用、重大更改以及可能特定于该 SDK 版本的其他信息。在升级时，请务必查看这些内容，以确保你不会遗漏任何内容。
- **SDK 54**: [发布说明](https://expo.dev/changelog/sdk-54)
- **SDK 53**: [发布说明](https://expo.dev/changelog/sdk-53)
- **SDK 52**: [发布说明](https://expo.dev/changelog/2024-11-12-sdk-52)
  - **React Native 0.77 已随 Expo SDK 52 提供**。要升级，请查看这些 [发布说明](https://expo.dev/changelog/2025/01-21-react-native-0.77)。
### 已弃用 SDK 版本变更日志
以下博客文章可能包含过时信息，但如果你在 SDK 升级方面落后，这些信息仍然有参考价值。
Note: 查看已弃用 SDK 发布变更日志的完整列表
---
- **SDK 51**: [发布说明](https://expo.dev/changelog/2024-05-07-sdk-51)
- **SDK 50**: [发布说明](https://expo.dev/changelog/2024-01-18-sdk-50)
- **SDK 49**: [发布说明](https://blog.expo.dev/expo-sdk-49-c6d398cdf740)
- **SDK 48**: [发布说明](https://blog.expo.dev/expo-sdk-48-ccb8302e231)
- **SDK 47**: [发布说明](https://blog.expo.dev/expo-sdk-47-a0f6f5c038af)
- **SDK 46**: [发布说明](https://blog.expo.dev/expo-sdk-46-c2a1655f63f7)
- **SDK 45**: [发布说明](https://blog.expo.dev/expo-sdk-45-f4e332954a68)
- **SDK 44**: [发布说明](https://blog.expo.dev/expo-sdk-44-4c4b8306584a)
- **SDK 43**: [发布说明](https://blog.expo.dev/expo-sdk-43-aa9b3c7d5541)
- **SDK 42**: [发布说明](https://blog.expo.dev/expo-sdk-42-579aee2348b6)
- **SDK 41**: [发布说明](https://blog.expo.dev/expo-sdk-41-12cc5232f2ef)
- **SDK 40**: [发布说明](https://dev.to/expo/expo-sdk-40-is-now-available-1in0)
- **SDK 39**: [发布说明](https://dev.to/expo/expo-sdk-39-is-now-available-1lm8)
- **SDK 38**: [发布说明](https://dev.to/expo/expo-sdk-38-is-now-available-5aa0)
- **SDK 37**: [发布说明](https://dev.to/expo/expo-sdk-37-is-now-available-69g)
- **SDK 36**: [发布说明](https://blog.expo.dev/expo-sdk-36-is-now-available-b91897b437fe)
- **SDK 35**: [发布说明](https://blog.expo.dev/expo-sdk-35-is-now-available-beee0dfafbf4)
---


# 杂项

## Authentication with OAuth or OpenID providers

Learn how to utilize the expo-auth-session library to implement authentication with OAuth or OpenID providers.

[`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.
## Rules for all authentication providers
When using the `AuthSession` API, the following rules apply to all authentication providers:
- Use `WebBrowser.maybeCompleteAuthSession()` to dismiss the web popup. If you forget to add this then the popup window will not close.
- 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`.
- Build requests using `AuthSession.useAuthRequest()`, the hook allows for async setup which means mobile browsers won't block the authentication.
- Be sure to disable the prompt until `request` is defined.
- You can only invoke `promptAsync` in user interaction on the web.
- 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.
## Obtaining access tokens
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.
Since [your client application code is not a secure place to store secrets](https://reactnative.dev/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.
## Examples
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}
>
| Website                                                   | Provider  | PKCE      | Auto Discovery |
| --------------------------------------------------------- | --------- | --------- | -------------- |
| [Get Your Config](https://github.com/settings/developers) | OAuth 2.0 | Supported | Not Available  |
- Provider only allows one redirect URI per app. You'll need an individual app for every method you want to use:
  - Standalone / development build: `com.your.app://*`
  - Web: `https://yourwebsite.com/*`
- The `redirectUri` requires two slashes (`://`).
- `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}
>
| Website                                                      | Provider | PKCE      | Auto Discovery |
| ------------------------------------------------------------ | -------- | --------- | -------------- |
| [Sign-up](https://developer.okta.com/signup/) > Applications | OpenID   | Supported | Available      |
- 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 */}
## Redirect URI patterns
Here are a few examples of some common redirect URI patterns you may end up using.
### Standalone/development build
> `yourscheme://path`
In some cases there will be anywhere between 1 to 3 slashes (`/`).
- **Environment:**
  - Bare workflow
    - `npx expo prebuild`
  - Standalone builds in the App or Play Store or testing locally
    - Android: `eas build` or `npx expo run:android`
    - iOS: `eas build` or `npx expo run:ios`
- **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()`
  - 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`.
  - 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`).
- **Usage:** `promptAsync({ redirectUri })`
## Improving user experience
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:
### Warming the browser
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 ...
}
```
### Implicit login
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` 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" />;
}
```
### Storing data
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...
}
```


## Using Hermes Engine

A guide on configuring Hermes for both Android and iOS in an Expo project.

[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.
## Support
The Hermes engine is the default JavaScript engine used by Expo and it is fully supported across all Expo tooling.
### Switch JavaScript engine on a specific platform
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"
    }
  }
}
```
## Publish updates
Publishing updates with `eas update` and `npx expo export` will generate Hermes bytecode bundles and their source maps.
Note that the Hermes bytecode format may change between different Hermes versions &mdash; 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://reactnative.dev/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.
## JavaScript 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.
Alternatively, you can use the JavaScript inspector by opening [Google Chrome DevTools manually](https://reactnative.dev/docs/other-debugging-methods#remote-javascript-debugging-deprecated)
### Troubleshooting
> **warning** `No compatible apps connected. JavaScript Debugging can only be used with the Hermes engine.` when opening the debugger.
- Make sure you [set up Hermes in the `jsEngine` field](#setup).
- If your app is built by `eas build`, `npx expo run:android` or `npx expo run:ios`, make sure it is a debug build.
- Internally, the app will establish a WebSocket connection, make sure your app is connected to the development server.
  - Try to reload the app by pressing <kbd>r</kbd> in the Expo CLI Terminal UI.
  - 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.dev/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.dev/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"
    }
  ]
  ```
### Can I use Remote Debugging with Hermes?
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 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 Developer Mode

Learn how to enable iOS developer mode on iOS 16 and above to run internal distribution builds and local development builds.

> This does not apply to builds signed using enterprise provisioning or to any builds installed on an iOS Simulator.
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:
- Directly on an iOS device
- By connecting an iOS device with a Mac that has Xcode installed
## Prerequisites
The instructions specified below need to be followed once per device.
## Enable Developer Mode
### Directly on an iOS device
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 Vector Icons

Learn how to use various types of icons in your Expo app, including react native vector icons, custom icon fonts, icon images, and icon buttons.

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.
## `@expo/vector-icons`
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).
The component loads the `Ionicons` font and renders a checkmark icon in the following example:
<SnackInline label='Vector icons' dependencies={['@expo/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',
  },
});
```
> 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')}`.
## Custom icon fonts
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` exposes three methods to help you create an icon set:
### `createIconSet`
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.
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" />;
}
```
### `createIconSetFromIcoMoon`
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`.
See the example below that uses the `useFonts` hook to load the font:
<SnackInline
label='Icomoon Icons'
files={{
    'assets/icomoon/icomoon.ttf': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/71ce651cbddbee5366aef87c456a80bb',
    'assets/icomoon/selection.json': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/a06aa5b6e7eb1df1fa1c8d06d4ab8463'
  }}
dependencies={['@expo/vector-icons', 'expo-font']}>
```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',
  },
});
```
### `createIconSetFromFontello`
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`.
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');
```
## Button component
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`.
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.
<SnackInline label='Icon Button Component' dependencies={['@expo/vector-icons']}>
```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',
  },
});
```
### Properties
Any [`Text`](http://reactnative.dev/docs/text), [`TouchableHighlight`](http://reactnative.dev/docs/touchablehighlight), or [`TouchableWithoutFeedback`](http://reactnative.dev/docs/touchablewithoutfeedback) property in addition to these:
| Prop              | Description                                                                                                                                       | Default             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `color`           | Text and icon color, use `iconStyle` or nest a `Text` component if you need different colors.                                                     | `white`             |
| `size`            | Icon size.                                                                                                                                        | `20`                |
| `iconStyle`       | Styles applied to the icon only, good for setting margins or a different color. _Note: use `iconStyle` for margins or expect unstable behaviour._ | `{marginRight: 10}` |
| `backgroundColor` | Background color of the button.                                                                                                                   | `#007AFF`           |
| `borderRadius`    | Border radius of the button, set to `0` to disable.                                                                                               | `5`                 |
| `onPress`         | A function called when the button is pressed.                                                                                                     | _None_              |


## Localization

Learn about getting started and configuring localization in an Expo project using expo-localization.

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.
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.
## Getting the user's language
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;
```
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.
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)
- 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)
### Enabling per-app language selection via system settings
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.
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": {
    "plugins": [
      [
        "expo-localization",
        {
          "supportedLocales": {
            "ios": ["en", "ja"],
            "android": ["en", "ja"]
          }
        }
      ]
    ]
  }
}
```
> 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).
>
> On iOS, use the language name or ISO language designator.
## 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.
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'));
```
Now, you can use the `i18n.t` function to translate strings throughout your application.
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;`.
On Android, when a user changes the device's language, the app will not reset. You can use the [`AppState`](https://reactnative.dev/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.
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.
### 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,
  },
});
```
### Other translation libraries
This guide uses `i18n-js` as an example. Other libraries can also help you with translations, and each has different features:
- 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).
- 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/) is a stable, well-maintained library based on `i18next`.
- [`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.
### Translating app metadata
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"
    }
  }
}
```
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.
## Enabling RTL support
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.
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"]
  }
}
```
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`.
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.
### Forcing RTL layout
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://reactnative.dev/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://reactnative.dev/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://developer.mozilla.org/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.
>
> For this you need to use `expo-localization`, JS code on the web, or third-party or custom native code on Android and iOS.


## Configure JS engines

A guide on configuring JS engines for both Android and iOS in an Expo project.

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. 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.
## Configuring the `jsEngine` through app config
> **warning** 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.
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`.
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.
---
## Switch JavaScript engine on a specific platform
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"
    }
  }
}
```


## Using Bun

A guide on using Bun with Expo and EAS.

[Bun](https://bun.sh/) is a JavaScript runtime and a drop-in alternative for [Node.js](https://nodejs.org/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.
## Prerequisites
> **Note:** While Bun replaces Node.js for most use cases in your project, at this time, a [Node.js LTS version](https://nodejs.org/) 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.
To create a new app using Bun, [install Bun on your local machine](https://bun.sh/docs/installation#installing).
## Start a new Expo project with Bun
To create a new project, run the command:
```sh
$ bun create expo-app my-app
```
You can also run any **package.json** script with `bun run`:
```sh
$ bun run ios
```
To install any Expo library, you can use `bun expo install`:
```sh
$ bun expo install expo-av
```
## Use Bun for EAS builds
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.
### Customize Bun version on EAS
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.
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"
    }
  }
}
```
## Trusted dependencies
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**.
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`.
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
```
## Common errors
### EAS Build fails when using Sentry and Bun
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.
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>` 组件，可以在许多简单情况下实现这一点，几乎不需要任何努力。
然而，有时您需要更灵活一些。想想长的社交媒体帖子、笔记应用或文档编辑器。理想情况下，您需要允许不同的文本样式、列表、标题、嵌入图片等。这被称为富文本编辑器，这是一个在任何地方都难以解决的问题，包括在 React Native 中。
当前在 React Native 生态系统中没有默认的解决方案。然而，本指南探讨了一些选项和有前景的方法，每种方法都有其自身的权衡。
Video Tutorial: [观看：如何使用 DOM 组件实现富文本编辑器](https://www.youtube.com/watch?v=CxORa1tXMjw)
## 渲染富文本
有很多良好的选项可以显示富文本：
- 对于 markdown 内容，您可以使用 markdown 渲染器，例如 [`react-native-markdown-display`](https://www.npmjs.com/package/react-native-markdown-display) 或其他。
- 对于 HTML 内容，您可以使用 [`@expo/html-elements`](https://www.npmjs.com/package/@expo/html-elements) 或 webview ([`react-native-webview`](/versions/latest/sdk/webview/))。
- 为了拥有自定义格式和更多控制，您可以利用嵌套的 `<Text>` 组件来渲染样式和布局。
  ```jsx
  <TextInput>
    <Text>
      <Text style={{ fontWeight: 900 }}>Some bold text</Text>Some regular text
    </Text>
  </TextInput>
  ```
- 您还可以使用 [Expo Modules API](/modules/overview/) 来使用第三方库（如 Android 上的 [Markwon](https://github.com/noties/Markwon) 和 iOS 上的 `AttributedString`）编写自定义渲染器组件。
## 编辑富文本的方法
有几种方法可以使富文本渲染工作。然而，所有方法都有不同的限制。
### 基于 WebView 的编辑器
虽然大多数 React Native UI 组件包装了原生平台原语，因此快速、有效，且 **具有本地感觉**，但基于 WebView 的富文本编辑器使用了不同的方法。
它们将为 Web 构建的现有富文本编辑器与 JavaScript 包裹在 [`react-native-webview`](/versions/latest/sdk/webview/) 中。它在所有平台（Android, iOS, Web）上都可以使用，并可以利用在 Web 平台上可用的流行富文本编辑器，但它存在性能和 UX 的些许损失。
您将无法在编辑器内部使用原生 UI 组件。实现提及或图片嵌入等功能的任何实现都将重复功能，并需要大量的努力进行实现。
### 现有的基于 WebView 的 React Native 库
有一些现有的 React Native 库可以允许富文本编辑。如果您需要一个具有有限配置的基本富文本编辑器，并且没有严格的性能或 UX 要求，这是最简单的选项：
- [`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)
### 自定义基于 WebView 的编辑器
如果您需要更多的可配置性，可以与现有的仅基于 Web 的编辑器构建一个类似的库。然而，您必须自行处理信息传递和 Web 实现。这将使您能够使用底层编辑器提供的所有选项，并让您实现更多功能。
- [Quill](https://quilljs.com/)
- [lexical](https://github.com/facebook/lexical)
- [slate](https://github.com/ianstormtaylor/slate)
您需要使用信息传递来在 WebView 中传递文本和 `onChange` 事件。由于富文本通常会变得很长，最好将其建模为一个不受控的组件，以防在每次按键时出现延迟。此外，如果您能够避免在每次按键时序列化和发送整个状态，那也会提高性能。
## 基于 React Native TextInput 的构建
在这一节中，我们来讨论是否可能拥有一个功能完整的通用富文本输入。
React Native 允许嵌套的 `<Text>` 组件，并允许它们作为 `<TextInput>` 的子组件来渲染和编辑样式文本。它与新的 React Native 架构是同步的（在文本输入字段中输入新字符后，`onChange` 事件会立即触发）。
不幸的是，`<TextInput>` 组件被构建为与常规文本一起使用，并且它只在其 `onTextChange` 回调中返回一个字符串。这是一个重大限制。
这是一个快速示例。让我们开始渲染一个带有以下粗体文本的文本输入：
```jsx
<TextInput>
  <Text>
    {/* 下面将以这种格式渲染粗体文本： **aa**aa */}
    <Text style={{ fontWeight: 900 }}>aa</Text>aa
  </Text>
</TextInput>
```
然后，让我们在文本输入中追加第五个字母 `a`。光标的位置应决定新的字母是否属于粗体字符串。不幸的是，回调只返回 `aaaaa`。
还有一个额外的 `onSelectionChange` 属性可以用来获取该信息。然而，这使得任务变得更加困难。插入额外字符（例如用于列表或项目符号的新行）也会造成选择的不同步。
有一些尝试构建这样的编辑器，如 [`markdown-editor`](https://github.com/shakogegia/markdown-editor)（未积极维护）和 [`rn-text-editor`](https://github.com/amjadbouhouch/rn-text-editor)（在测试版中），但没有广泛使用的包存在。
## 具有可见样式标记的 Markdown 编辑器
如果使用 markdown 来样式化文本满足您的要求，您可以在编辑时在一个单独的、不可编辑的视图中渲染 markdown。使用任何 markdown 渲染器构建自己的并不复杂。您还可以使用第三方库，如 [`react-native-markdown-editor`](https://github.com/kunall17/react-native-markdown-editor)。
这种编辑体验适合高级用户或编程/技术应用。您还可以探索在显示 markdown 只在选定的文本块中或其他混合方法时渲染富文本。
## 原生编辑器
您可以使用包装在 React Native 模块中的原生 Android 或 iOS 富文本编辑器。有几个选项：
- [`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)
- [`react-native-enriched`](https://github.com/software-mansion-labs/react-native-enriched)
您还可以使用 [Expo Modules API](/modules/overview/) 包装任何原生富文本编辑器，但如果您在每个平台上使用不同的编辑器，则需要统一它们的 API 和输入格式。
> 富文本通常使用 [抽象语法树](https://en.wikipedia.org/wiki/Abstract_syntax_tree) 表示。例如，一个项目符号列表可以是类型为 `bulleted-list` 的节点，其中有多个类型为 `list-item` 的子节点。您可以将 HTML 和 markdown 转换为适当的 AST 格式。
还有一个努力将 lexical 编辑器移植到 Android 和 iOS，并提供一个 React Native 包装器 [可以在这里跟踪](https://github.com/facebook/lexical/discussions/2410)。
## 总结
虽然有许多很好的选项来显示富文本，但在 React Native 中没有一种适合所有情况的富文本编辑解决方案。没有一个流行的解决方案可以满足大多数用例。社区的进一步贡献对于改善现有解决方案或添加新方案是必要的。
目前，您需要仔细选择在功能上更复杂的原生编辑器，这提供更多功能但可能更难维护，或基于 React Native 原语构建的编辑器。这取决于该功能在您的应用中有多核心、您在编辑器中需要多少功能以及您愿意花多少精力来构建它。


## Create app store assets

Learn how to create screenshots and previews for your app's store pages.

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.
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.
## 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.
### Option 1: actual screenshots
The most straightforward option &mdash; 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.
### 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.
### 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.
## Google Play Store Asset Requirements
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.
### App icon
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.
### 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.
### Screenshots
You need to upload at least four screenshots to publish your app.
### Video (optional)
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.
## iOS App Store Asset Requirements
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.
### Screenshots
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.
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.
### 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.
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.
## Bare minimum
Below is the bare minimum needed to publish your apps.
### Play Store - Android
| Type            | Amount | Dimensions                                                          | Requirements                                        |
| --------------- | ------ | ------------------------------------------------------------------- | --------------------------------------------------- |
| App Icon        | 1      | 512 × 512                                                           | 32-bit PNG (with alpha); Maximum file size: 1024 KB |
| Feature Graphic | 1      | 1024 × 500                                                          | JPEG or 24-bit PNG (no alpha)                       |
| Screenshots     | 4-10   | minimum: 1024 × 500maximum width: 3840px9:16 aspect ratio | JPEG or 24-bit PNG (no alpha)                       |
### App Store - iPhone
| Type                                         | Amount | Dimensions (choose one)     | Requirements          |
| -------------------------------------------- | ------ | --------------------------- | --------------------- |
| Screenshots (iPhone with the dynamic island) | 2-10   | 1320 × 28681290 × 2796 | JPG or PNG (no alpha) |
### App Store - iPad
If your app also runs on an iPad, you need to supply additional screenshots.
| Type        | Amount | Dimensions (choose one)     | Requirements          |
| ----------- | ------ | --------------------------- | --------------------- |
| Screenshots | 2-10   | 2064 × 27522048 × 2732 | JPG or PNG (no alpha) |


## 本地优先架构与 Expo

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

> **info** 本指南仍在完善中。如果您有任何反馈，请在我们的 GitHub 存储库中[提交问题](https://github.com/expo/expo/issues/new/choose)。
“本地优先”这一术语最早出现在研究实验室 [Ink & Switch](https://www.inkandswitch.com/) 撰写的论文 ["Local-first software"](https://www.inkandswitch.com/local-first/) 中，但其背后的理念早已存在。它是支持一些我们最喜爱的应用程序的架构，如 [Linear](https://linear.app/)、[Superhuman](https://superhuman.com/)、[Excalidraw](https://excalidraw.com/) 甚至 [Apple Notes](<https://en.wikipedia.org/wiki/Notes_(Apple)>).
在本地优先软件中，“另一台计算机的可用性永远不应妨碍你工作”（[通过 Martin Kleppmann](https://www.youtube.com/watch?v=NMq0vncHJvU)）。当你离线时，你仍然可以直接从/写入设备上的数据库。你可以信任软件在离线状态下的可靠性，并且当你连接到互联网时，数据会无缝地同步并在运行该应用程序的任何设备上可用。当你在线时，这种架构非常适合“多人”应用程序，[如 Figma 所推广的](https://www.figma.com/blog/how-figmas-multiplayer-technology-works/)。
要深入了解本地优先的意义及其工作原理，请参考下面的 [附加资源](#additional-resources)。
## 为什么使用本地优先架构？
### 用户体验的好处
本地优先软件感到 **快速**，因为交互不再依赖于网络，你可以直接从/写入设备上的数据库。
你可以信任软件在离线状态下的运行，当你连接到互联网时，数据会无缝地同步并在运行该应用程序的任何设备上可用。
本地优先软件的另一个特点是它是协作性的——多个设备可以共同处理相同的数据，并且所有变化会在它们之间同步。当你在 [Figma](https://www.figma.com/) 中共同设计时，这种同步可以实时发生，或者是在离线状态下在 Linear 中创建任务并在你再次在线时同步。
### 开发者体验的好处
你不再需要为每个网络请求管理应用程序的各种状态——“已加载”、“加载中”、“错误”等，以及它们相应的 UI 状态和其他逻辑。写入本地数据库，应用程序将自动将更改同步到服务器。这意味着你可以专注于构建应用程序，而不必过多担心网络和离线状态的问题。
你的服务器可用性可能仍然很重要，但在停机的情况下，用户仍然可以访问应用程序并继续工作。你甚至可以提供一个机制，在不经过服务器的情况下同步数据。
## 构建本地优先应用程序的挑战
今天可用的工具仍处于早期阶段，因此你可能会发现自己在解决本应由你今天使用的工具解决的问题。例如，你可能需要实现一个自定义的同步层，或者可能必须弄清楚如何处理多个用户在同一数据上操作的权限。随着生态系统的发展，我们预计构建本地优先应用程序将变得更加简单。如果你没有准备好成为早期采用者，以及随之而来的所有挑战，可能想等到工具成熟后再开始使用本地优先工具构建应用程序。
## 构建本地优先应用程序的工具
关于工具的全面列表可以在 ["Local-first software" community website](https://localfirstweb.dev/) 上找到。以下是我们在 Expo 直接使用过的一些工具的简略列表。
一种思考本地优先工具的方式是按以下类别进行分组：持久性、状态管理和同步。如果某些工具处理了问题的多个方面，它们可能会适合多个类别。同步可以进一步细分为可同步的数据结构和传输层。
### Legend-State
[Legend-State](https://legendapp.com/open-source/state/v3/) 是一个超级快速的全能状态和同步库，让你输入更少的代码来制作更快的应用程序。它有以下主要目标：
- 更快的 React 应用状态管理
- 细粒度反应以实现最小渲染
- 强大的同步和持久化（支持 Supabase 内置）
它与 Expo 和 React Native 一起使用（通过 [`react-native-async-storage`](https://github.com/react-native-async-storage/async-storage?tab=readme-ov-file#react-native-async-storage)）。这使得它成为构建本地优先移动和 Web 应用程序的完美选择。通过使用 [Legend-State Supabase 示例](https://github.com/expo/examples/tree/master/with-legend-state-supabase) 开始：
```sh
$ npx create-expo-app --example with-legend-state-supabase
```
### TinyBase
[TinyBase](https://tinybase.org/) 自称为“本地优先应用的反应式数据存储”。它是一个状态管理库，可以与许多流行的同步和持久层（如 [Yjs](#yjs) 和 [SQLite](#sqlite)）结合使用。它是构建需要持久和同步数据的本地优先应用的一个好选择。通过使用 [TinyBase 示例](https://github.com/expo/examples/tree/master/with-tinybase) 开始：
```sh
$ npx create-expo-app --example with-tinybase
```
TinyBase 与 Expo Go 无缝协作，使你能够快速开发。在安卓和 iOS 上，它使用 [`expo-sqlite`](/versions/latest/sdk/sqlite/) 库来持久化数据。在 Web 上，它依赖于 [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) API。[Beto Moedano](https://github.com/betomoedano) 在以下视频中展示了如何构建一个 [通用本地优先购物清单应用](https://github.com/betomoedano/groceries-shopping-list-app) ：
Video Tutorial: [观看：使用 Expo 和 TinyBase 构建本地优先实时购物清单应用](https://www.youtube.com/watch?v=HqOiB2tDM8Q)
### 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/)。
### 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)。
### Prisma
[Prisma](https://prisma.io) 作为 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)。
Video Tutorial: [观看：使用 React Native Expo 和 Prisma 构建本地优先 Notion 克隆](https://www.youtube.com/watch?v=uTrPte0sCiw)
### Jazz
[Jazz.tools](https://jazz.tools/docs/react-native) 是一个构建本地优先应用的框架。它是开源的，提供对 Expo 的一流支持，你可以自托管它或使用 [Jazz Cloud](https://jazz.tools/cloud) 快速开始。[Jazz](https://jazz.tools)。要了解更多，请查看 [示例](https://jazz.tools/examples#react-native) 或参阅 [入门指南](https://jazz.tools/docs/react-native) 以获取详细说明。
### LiveStore
[LiveStore](https://docs.livestore.dev/getting-started/expo/) 是一个以客户端为中心的本地优先数据层，适用于高性能应用程序。它为 Expo 提供了一流的支持，是构建本地优先应用的不错选择。请参见关于 [LiveStore: 基于 SQLite 的本地优先应用的数据层](https://expo.dev/blog/local-first-application-development-with-livestore) 的博客文章。
Video Tutorial: [观看：如何使用 LiveStore 和 Expo 构建本地优先原生应用](https://www.youtube.com/watch?v=zQIhJqYU1Qw)
### Turso
[Turso](https://turso.tech) 是一个基于 SQLite 的现代数据库服务。它现在支持 [离线同步](https://turso.tech/blog/turso-offline-sync-public-beta)，使真正的本地优先体验得以实现。你可以在本地和远程源之间以双向同步和内置冲突检测同步数据库。虽然自动冲突解决功能尚不可用，但这一特性仍然是一个重大进步。你今天可以与 [expo-sqlite](/versions/latest/sdk/sqlite) 一起使用 Turso。要了解更多信息，请阅读 [Turso: 离线同步公共测试版](https://turso.tech/blog/turso-offline-sync-public-beta) 的博客文章。有关示例集成，请查看 [Notes App](https://github.com/betomoedano/notes-app)。
Video Tutorial: [观看：如何使用 Turso 和 Expo 构建本地优先 Notes App](https://www.youtube.com/watch?v=SBv32tmyb3k)
### Instant
[Instant](https://www.instantdb.com/) 是 Firebase 的现代替代品。它为你提供了一个实时数据库，让你能专注于构建应用程序的前端。要开始，请查看 [入门指南](https://www.instantdb.com/docs/start-rn)。你还可以探索下面视频中展示的 [Sketch App](https://github.com/betomoedano/sketch-app)。
Video Tutorial: [观看：使用 Expo、Instant 和 Reanimated 构建本地优先 Sketch App](https://www.youtube.com/watch?v=DEJIcaGN3vY)
### 其他工具
以下列表并不全面，但提供了其他一些引起我们关注的工具，您可能会发现它们有趣并值得探索。有关更全面的工具列表，请参见 ["Local-first software" community website](https://localfirstweb.dev/)。
- [Automerge](https://automerge.org/)
- [ElectricSQL](https://electric-sql.com/)
- [PowerSync](https://www.powersync.com/)
## 附加资源
- ["本地优先的过去、现在与未来"](https://www.youtube.com/watch?v=NMq0vncHJvU) 由 Martin Kleppmann
- ["本地优先软件"](https://www.inkandswitch.com/local-first/) 由 Ink & Switch
- ["本地优先软件"社区网站](https://localfirstweb.dev/) 和 [YouTube 上的聚会播放列表](https://www.youtube.com/playlist?list=PLTbD2QA-VMnXFsLbuPGz1H-Najv9MD2-H)
- [localfirst.fm 播客](https://localfirst.fm/) 由 Johannes Schickling


## 键盘处理

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

键盘处理对于在您的 Expo 应用中创建出色的用户体验至关重要。React Native 提供了 [`Keyboard`](https://reactnative.dev/docs/keyboard) 和 [`KeyboardAvoidingView`](https://reactnative.dev/docs/keyboardavoidingview)，这些组件通常用于处理键盘事件。对于更复杂或自定义的键盘交互，您可以考虑使用 [`react-native-keyboard-controller`](https://kirillzyusko.github.io/react-native-keyboard-controller)，这是一个提供高级键盘处理功能的库。
本指南涵盖了常见的键盘交互及其有效管理方法。
Video Tutorial: [React Native应用的键盘处理教程](https://www.youtube.com/watch?v=Y51mDfAhd4E)
## 键盘处理基础
以下部分解释如何使用常见API处理键盘交互。
### 键盘避免视图
`KeyboardAvoidingView` 是一个组件，它会根据键盘的高度自动调整视图的高度、位置或底部填充，以便在键盘显示时保持可见。
Android 和 iOS 对 `behavior` 属性的交互方式不同。在 iOS 中，通常使用 `padding` 是最有效的，而在Android中，仅仅使用 `KeyboardAvoidingView` 就可以防止输入框被覆盖。这就是以下示例在 Android 中使用 `undefined` 的原因。尝试不同的 `behavior` 选项是个好习惯，因为不同的选项可能适合您的应用。
```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` 的高度会根据设备的键盘高度自动调整，这确保了输入框始终可见。
在 Android 上使用底部标签导航器时，您可能会注意到聚焦输入字段会导致底部标签被推到键盘上方。为了解决此问题，请在 [app config](/workflow/configuration/) 的Android配置中添加 `softwareKeyboardLayoutMode` 属性，并将其设置为 `pan`。
```json app.json
"expo" {
  "android": {
    "softwareKeyboardLayoutMode": "pan"
  }
}
```
添加此属性后，重新启动开发服务器并重新加载您的应用以应用更改。
还可以使用 [`tabBarHideOnKeyboard`](https://reactnavigation.org/docs/bottom-tab-navigator/#tabbarhideonkeyboard) 在键盘打开时隐藏底部标签。这是底部标签导航器的一项选项。如果设置为 `true`，将在键盘打开时隐藏标签栏。
```tsx app/_layout.tsx
import { Tabs } from 'expo-router';
export default function TabLayout() {
  return (
    <Tabs
      screenOptions={{
        tabBarHideOnKeyboard: true,
      }}>
      <Tabs.Screen name="index" />
    </Tabs>
  );
}
```
### 键盘事件
React Native 中的 `Keyboard` 模块允许您监听本机事件，对其做出反应，并对键盘进行更改，例如退出键盘。
要监听键盘事件，请使用 `Keyboard.addListener` 方法。此方法接受一个事件名称和一个回调函数作为参数。当键盘显示或隐藏时，回调函数将与事件数据一起调用。
以下示例说明了添加键盘监听器的用例。状态变量 `isKeyboardVisible` 在每次键盘显示或隐藏时切换。根据此变量，按钮允许用户仅在键盘处于活动状态时关闭键盘。此外，请注意按钮使用了 `Keyboard.dismiss` 方法。
```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>
  );
}
```
## 使用键盘控制器进行高级键盘处理
对于更复杂的键盘交互，例如包含多个文本输入字段的大型可滚动输入表单，请考虑使用 [`react-native-keyboard-controller` (键盘控制器)](https://kirillzyusko.github.io/react-native-keyboard-controller) 库。它提供的功能超出了内置的React Native键盘API，提供了一致的Android和iOS体验，配置较少，并提供用户所期望的原生感觉。
### 先决条件
以下步骤使用 [开发构建](/develop/development-builds/introduction/) 描述，因为键盘控制器库未包含在Expo Go中。有关更多信息，请参见 [创建开发构建](/develop/development-builds/create-a-build/)。
[键盘控制器](https://kirillzyusko.github.io/react-native-keyboard-controller) 还需要 `react-native-reanimated` 正常工作。要安装它，请遵循这些 [安装说明](/versions/latest/sdk/reanimated/#installation)。
### 安装
首先在您的Expo项目中安装键盘控制器库：
```sh
$ npx expo install react-native-keyboard-controller
```
### 设置提供程序
要完成设置，请将 `KeyboardProvider` 添加到您的应用中。
```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>
  );
}
```
### 处理多个输入
[`KeyboardAvoidingView`](#keyboard-avoiding-view) 组件非常适合原型设计，但它需要特定于平台的配置，且不易自定义。
作为更强大的替代方案，您可以使用 [`KeyboardAwareScrollView`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/components/keyboard-aware-scroll-view) 组件。它会自动滚动到聚焦的 `TextInput`，并提供类似原生的性能。对于只有几个元素的简单屏幕，使用 `KeyboardAwareScrollView` 是一个不错的方法。
对于具有多个输入的屏幕，键盘控制器库还提供了 `KeyboardToolbar` 组件，可以与 `KeyboardAwareScrollView` 一起使用。它们共同处理输入导航，并防止键盘覆盖屏幕，而无需自定义配置：
```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` 组件显示导航控件和关闭按钮。尽管它可以在没有配置的情况下工作，但您可以根据需要自定义工具栏内容。
### 根据键盘高度同步动画视图
对于更加高级和可定制的方法，您可以使用 [`useKeyboardHandler`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/keyboard/use-keyboard-handler)。它提供对键盘生命周期事件的访问。它允许我们确定键盘何时开始动画，以及其在动画每一帧中的位置。
使用 `useKeyboardHandler` 钩子，您可以创建一个自定义钩子，以便在每一帧中访问键盘的高度。它使用来自reanimated的 `useSharedValue` 返回高度，如下所示。
```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`，其设置为键盘的高度。
`fakeView` 动画样式在 `TextInput` 之后的动画视图中使用。该视图的高度将在每一帧中根据键盘的高度进行动画，从而有效地将内容推送到键盘上方，并在键盘被关闭时将其高度减少到零。
```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,
  },
});
```
## 其他资源


## 使用 Expo UI 构建 SwiftUI 应用

了解如何使用 Expo UI 将 SwiftUI 集成到您的 Expo 应用中。

> **信息** 可用于 **SDK 54 及更高版本**。
Expo UI 将 SwiftUI 带入 React Native。您可以使用现代 SwiftUI 原语来构建您的应用。
本指南涵盖了使用 Expo UI 将 SwiftUI 集成到您的 Expo 应用中的基础知识。
Video Tutorial: [Expo UI iOS 液态玻璃教程](https://www.youtube.com/watch?v=2wXYLWz3YEQ)
## 特点
- **SwiftUI 原语**：Expo UI 不是另一个 UI 库。它将 SwiftUI 原语带到了 Expo。
- **1 对 1 映射**：Expo UI 中的组件与 SwiftUI 视图具有 1 对 1 的映射。您可以轻松探索 SwiftUI 生态系统中的可用视图，例如 [Explore SwiftUI](https://exploreswiftui.com/) 或 [Libraried 应用](https://apps.apple.com/us/app/libraried-ui-components/id1642862540)，并找到相应的 Expo UI 组件。
- **全应用支持**：Expo UI 旨在在整个应用中使用。您可以完全用 Expo UI 编写应用，同时保持灵活性。集成在组件级别进行。您还可以混合 [React Native 组件](https://reactnative.dev/docs/components-and-apis)、[Expo UI 组件](/versions/latest/sdk/ui/)、[DOM 组件](/guides/dom-components/) 或使用 [`react-native-skia`](https://shopify.github.io/react-native-skia/) 的自定义 2D 组件。
## 安装
您需要在 Expo 项目中安装 `@expo/ui` 包。运行以下命令进行安装：
```sh
$ npx expo install @expo/ui
```
## 使用
Expo UI 有多个可用的 SwiftUI 组件。您可以通过从 `@expo/ui/swift-ui` 导入它们来在您的应用中使用。然而，要从 React Native (UIKit) 跨越到 SwiftUI，您需要使用 [`Host`](/versions/latest/sdk/ui/#host) 组件。[`Host`](/versions/latest/sdk/ui/#host) 是 SwiftUI 视图的容器。您可以将其视为 DOM 中的 [`<svg>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/svg) 或 [`react-native-skia`](https://shopify.github.io/react-native-skia/) 中的 [`<Canvas>`](https://shopify.github.io/react-native-skia/docs/canvas/overview/)。在底层，它使用 [`UIHostingController`](https://developer.apple.com/documentation/swiftui/uihostingcontroller) 在 UIKit 中渲染 SwiftUI 视图。
### 使用 `Host` 的基本用法
  For 代码: 
    ```tsx SwiftUI loading view
    import { CircularProgress, Host } from '@expo/ui/swift-ui';
    import { View, Text } from 'react-native';
    export default function LoadingView() {
      return (
        <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
          <Host matchContents>
            <CircularProgress />
          </Host>
          <Text>加载中...</Text>
        </View>
      );
    }
    ```
  For 预览: 
### 使用 `HStack` 和 `VStack`
您还可以使用 `HStack` 和 `VStack` 组件在 SwiftUI 中构建整个布局。
  For 代码: 
    ```tsx SwiftUI loading with HStack and VStack
    import { CircularProgress, Host, HStack, LinearProgress, VStack } from '@expo/ui/swift-ui';
    export default function LoadingView() {
      return (
        <Host style={{ flex: 1, margin: 32 }}>
          <VStack spacing={32}>
            <HStack spacing={32}>
              <CircularProgress />
              <CircularProgress color="orange" />
            </HStack>
            <LinearProgress progress={0.5} />
            <LinearProgress color="orange" progress={0.7} />
          </VStack>
        </Host>
      );
    }
    ```
  For 预览: 
### 修饰符
[SwiftUI 修饰符](<https://developer.apple.com/documentation/swiftui/view/modifier(_:)>) 是自定义 SwiftUI 组件外观和行为的一种强大方式。Expo UI 也为 SwiftUI 组件提供修饰符。您可以从 `@expo/ui/swift-ui/modifiers` 导入修饰符，并将它们作为数组传递给 `modifiers` 属性。在下面的示例中，[`expo-mesh-gradient`](/versions/latest/sdk/mesh-gradient/) 和 `glassEffect` 修饰符结合在一起创建了液体玻璃文本。
  For 代码: 
    > **注意**：`glassEffect` 修饰符需要 Xcode 26+ 和 iOS 26+。
    ```tsx SwiftUI modifiers
    import { Host, Text } from '@expo/ui/swift-ui';
    import { glassEffect, padding } from '@expo/ui/swift-ui/modifiers';
    import { MeshGradientView } from 'expo-mesh-gradient';
    import { View } from 'react-native';
    export default function Page() {
      return (
        <View style={{ flex: 1 }}>
          <MeshGradientView
            style={{ flex: 1 }}
            columns={3}
            rows={3}
            colors={['red', 'purple', 'indigo', 'orange', 'white', 'blue', 'yellow', 'green', 'cyan']}
            points={[
              [0.0, 0.0],
              [0.5, 0.0],
              [1.0, 0.0],
              [0.0, 0.5],
              [0.5, 0.5],
              [1.0, 0.5],
              [0.0, 1.0],
              [0.5, 1.0],
              [1.0, 1.0],
            ]}
          />
          <Host style={{ position: 'absolute', top: 0, right: 0, left: 0, bottom: 0 }}>
            <Text
              size={32}
              modifiers={[
                padding({
                  all: 16,
                }),
                glassEffect({
                  glass: {
                    variant: 'clear',
                  },
                }),
              ]}>
              Glass effect text
            </Text>
          </Host>
        </View>
      );
    }
    ```
  For 预览: 
### iOS 设置应用示例
结合 Expo UI 组件和修饰符，您可以构建类似于 iOS 设置应用的 UI。
  For 代码: 
    ```tsx SwiftUI Form example to build iOS Settings app
    import {
      Button,
      Form,
      Host,
      HStack,
      Image,
      Section,
      Spacer,
      Switch,
      Text,
    } from '@expo/ui/swift-ui';
    import { background, clipShape, frame } from '@expo/ui/swift-ui/modifiers';
    import { Link } from 'expo-router';
    import { useState } from 'react';
    export default function SettingsView() {
      const [isAirplaneMode, setIsAirplaneMode] = useState(true);
      return (
        <Host style={{ flex: 1 }}>
          <Form>
            <Section>
              <HStack spacing={8}>
                <Image
                  systemName="airplane"
                  color="white"
                  size={18}
                  modifiers={[
                    frame({ width: 28, height: 28 }),
                    background('#ffa500'),
                    clipShape('roundedRectangle'),
                  ]}
                />
                <Text>Airplane Mode</Text>
                <Spacer />
                <Switch value={isAirplaneMode} onValueChange={setIsAirplaneMode} />
              </HStack>
              <Link href="/wifi" asChild>
                <Button>
                  <HStack spacing={8}>
                    <Image
                      systemName="wifi"
                      color="white"
                      size={18}
                      modifiers={[
                        frame({ width: 28, height: 28 }),
                        background('#007aff'),
                        clipShape('roundedRectangle'),
                      ]}
                    />
                    <Text color="primary">Wi-Fi</Text>
                    <Spacer />
                    <Image systemName="chevron.right" size={14} color="secondary" />
                  </HStack>
                </Button>
              </Link>
            </Section>
          </Form>
        </Host>
      );
    }
    ```
  For 预览: 
## 常见问题
Note: 我可以在 SwiftUI 组件中使用 flexbox 或其他样式吗？
---
Flexbox 样式可以应用于 `Host` 组件本身。然而，一旦进入 SwiftUI 上下文，[`Yoga`](https://www.yogalayout.dev/) 将不可用 &mdash; 布局应使用 `<HStack>` 和 `<VStack>` 来定义。
---
Note: 什么是  组件？
---
`Host` 是 SwiftUI 视图的容器。你可以将其视为 DOM 中的 [`<svg>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/svg) 或 [`react-native-skia`](https://shopify.github.io/react-native-skia/) 中的 [`<Canvas>`](https://shopify.github.io/react-native-skia/docs/canvas/overview/)。在底层，它使用 [`UIHostingController`](https://developer.apple.com/documentation/swiftui/uihostingcontroller) 在 UIKit 中渲染 SwiftUI 视图。
---
Note: Expo UI 与  或  类似的库有什么不同？
---
Expo UI 不是“另一个” UI 库，也不是一个有观点的设计工具包。相反，它是一个原语库。它直接将原生 SwiftUI 和 Jetpack Compose 组件暴露给 JavaScript，而不是在 JavaScript 中重新实现或模拟 UI。
---
Note: 我可以在 Android 或 Web 上使用  吗？
---
Expo UI 的第一个里程碑是实现 SwiftUI 与 Expo UI 之间的 1 对 1 映射。通用支持将在路线图的下一阶段到来。我们的优先事项是首先建立强大的 SwiftUI 支持，然后扩展到 Android 上的 Jetpack Compose 和 Web 上的 DOM 支持。
---
Note: 我可以在 SwiftUI 组件内部使用 React Native 组件吗？
---
是的，您可以将 React Native 组件作为 JSX 子元素放置在 Expo UI 组件中。Expo UI 自动为您创建一个 [`UIViewRepresentable`](https://developer.apple.com/documentation/swiftui/uiviewrepresentable) 包装器。
然而，请记住，SwiftUI 布局系统的工作方式与 UIKit 不同，并且存在一些限制。根据苹果的文档：
> **warning** SwiftUI 完全控制 UIKit 视图的 [`center`](https://developer.apple.com/documentation/UIKit/UIView/center)、[`bounds`](https://developer.apple.com/documentation/UIKit/UIView/bounds)、[`frame`](https://developer.apple.com/documentation/UIKit/UIView/frame) 和 [`transform`](https://developer.apple.com/documentation/UIKit/UIView/transform) 属性。请勿在您自己的代码中直接设置由 [`UIViewRepresentable`](https://developer.apple.com/documentation/swiftui/uiviewrepresentable) 实例管理的视图的这些布局相关属性，因为这与 SwiftUI 冲突，并导致未定义行为。
请注意，一旦您渲染 React Native 组件，就会离开 SwiftUI 上下文。如果您想再次添加 Expo UI 组件，您需要重新引入一个 `Host` 包裹。
我们建议将 SwiftUI 布局保持自包含。互操作是可能的，但在界限清晰时效果最佳。
---
Note: 我是 SwiftUI 开发者。我为什么要学习 Expo UI？
---
因为 React 的承诺是 _“学习一次，随处编写”_，现在扩展到了 SwiftUI 和 Jetpack Compose。通过 Expo UI，您可以运用您的 SwiftUI 知识来构建在 React Native 生态系统中运行的应用，扩展到通过 [DOM 组件](/guides/dom-components/) 的 Web，甚至集成 [2D](https://shopify.github.io/react-native-skia/) 和 [3D](https://github.com/wcandillon/react-native-webgpu) 渲染。该系统具有足够的灵活性，不同部分的应用可以使用不同的方法——在组件级别为您提供无缝集成。
---
## 额外资源


# 集成

## React Native analytics SDKs and libraries

An overview of analytics services available in the Expo and React Native ecosystem.

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.
The following list provides common analytics providers that are available in the Expo and React Native ecosystem.
> 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.


## Using Facebook authentication

A guide on using react-native-fbsdk-next library to integrate Facebook authentication in your Expo project.

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.
This guide provides additional information on configuring the library with Expo for Android.
## Prerequisites
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/).
## Installation
See `react-native-fbsdk-next` documentation for instructions on how to install and configure the library:
## Configuration for Android
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:
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.
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.
- 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.
- You can find the Package name in your [app config](/versions/latest/config/app) under the [`android.package`](/versions/latest/config/app/#package) field.
- 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.
Now, you can use your Facebook project for development or release builds and production apps.


## Using Supabase

Add a Postgres Database and user authentication to your React Native app with Supabase.

[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 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 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.
## Prerequisites
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.
### Get the API Keys
Get the Project URL and `anon` key from the API settings.
1. Go to the [API Settings](https://supabase.com/dashboard/project/_/settings/api) page in the Dashboard.
1. Find your Project `URL`, `anon`, and `service_role` keys on this page.
## Using the Supabase TypeScript SDK
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.
### 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 expo-sqlite
```
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 'expo-sqlite/localStorage/install';
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: localStorage,
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false,
  },
});
```
Now you can `import { supabase } from '/utils/supabase'` throughout your application to leverage the full power of Supabase!
## Next steps


## Using Firebase

A guide on getting started and using Firebase JS SDK and React Native Firebase library.

[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.
There are two different ways you can use Firebase in your projects:
- Using [Firebase JS SDK](#using-firebase-js-sdk)
- Using [React Native Firebase](#using-react-native-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.
## Prerequisites
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/).
## Using Firebase JS SDK
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.
### When to use Firebase JS SDK
You can consider using the Firebase JS SDK when you:
- 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/).
- Want a quick start with Firebase services.
- Want to create a universal app for Android, iOS, and the web.
#### Caveats
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.
### Install and initialize Firebase JS SDK
> **warning** Expo SDK 53 and later only support `firebase@^12.0.0`. Versions before this version cause ES module resolution errors.
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).
### 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.
---
### Next steps
After configuring React Native Firebase library, you can use any module it provides in your Expo project.


## Using Google authentication

A guide on using @react-native-google-signin/google-signin library to integrate Google authentication in your Expo project.

The [`@react-native-google-signin/google-signin`](https://github.com/react-native-google-signin/google-signin) library provides a way to 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.
## Prerequisites
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/).
## Installation
See `@react-native-google-signin/google-signin` documentation for instructions on how to install and configure the library:
## Configure Google project for Android and iOS
Below are instructions on how to configure your Google project for Android and iOS.
### Upload app to Google Play Store
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:
### Configure your Firebase or Google Cloud Console project
> 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.
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:
- 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**.
- 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**.
### With Firebase
For more instructions on how to configure your project for Android and iOS with Firebase:
#### Upload google-services.json and GoogleService-Info.plist to 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.
### With Google Cloud Console
This is an alternate method to configure a Google project when you are not using [Firebase](#with-firebase).
For more instructions on how to configure your Google project Android and iOS with Google Cloud Console:


## Using ESLint and Prettier

A guide on configuring ESLint and Prettier to format Expo apps.

[ESLint](https://eslint.org/) 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.io/docs/en/), a code formatter that ensures all the code files follow a consistent styling.
This guide provides steps to set up and configure ESLint and Prettier.
## ESLint
### Setup
> **info** **From SDK 53 onwards**, the default ESLint config file uses the [Flat config](https://eslint.org/blog/2022/08/new-config-system-part-2/) format. It also supports legacy config. **For SDK 52 and earlier**, the default ESLint config file uses legacy config and does not support Flat config.
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
```
### Usage
> **info** **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.
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
```
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)
```
### Environment configuration
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.
The approach to configure environment-specific globals differs between Flat config and legacy config:
For Flat config: 
For Flat config, **metro.config.js** files already work with Node.js globals because of the built-in support in `eslint-config-expo`. For other configuration files that might need Node.js globals, use [`languageOptions.globals`](https://eslint.org/docs/latest/use/configure/language-options#predefined-global-variables) in your **eslint.config.js**:
```js eslint.config.js
const { defineConfig, globalIgnores } = require('eslint/config');
const expoConfig = require('eslint-config-expo/flat');
module.exports = defineConfig([
  globalIgnores(['dist/*']),
  expoConfig,
  {
    files: ['babel.config.js'],
    languageOptions: {
      globals: globals.node,
    },
  },
]);
```
For example, with this setup, you can now use Node.js globals in **babel.config.js**:
```js babel.config.js
import path from 'path';
const __dirname = path.dirname(__filename);
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
  };
};
```
For Legacy config: 
For legacy config, you can add the `eslint-env` comment to the top of a file to tell ESLint which environment the file is running in:
```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;
```
## Prettier
### Installation
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
```
### Setup
For Flat config: 
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: 
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',
  },
};
```
> **Note:** In the above configuration, you can use `"prettier/prettier": "warn"` if you prefer these formatting issues as warnings instead of errors.
Now, when you run `npx expo lint`, anything that is not aligned with Prettier formatting will be caught as an error.
To customize Prettier settings, create a **.prettierrc** file at the root of your project and add your configuration.
## Troubleshooting
### ESLint is not updating in VS Code
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).
### ESLint is slow
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
```
## Migration to Flat config
> **info** **Note:** Flat config is supported in Expo SDK 53 and later.
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
```
If you haven't customized your ESLint config at all, delete your **.eslintrc.js** and generate the new config with:
```sh
$ npx expo lint
```
Alternatively, migrate your config based on the [ESLint's migration guide](https://eslint.org/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.


## Using Next.js with Expo for Web

A guide for integrating Next.js with Expo for the web.

> **warning** Using Next.js is not an official part of Expo's universal app development workflow.
[Next.js](https://nextjs.org/) 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.
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 can only be used with Expo for web as there is no support for Server-Side Rendering (SSR) for native apps.
## Automatic setup
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
```
- **Native**: `npx expo start` &mdash; start the Expo project
- **Web**: `npx next dev` &mdash; start the Next.js project
## Manual setup
### Install dependencies
Ensure you have `expo`, `next`, `@expo/next-adapter` installed in your project:
```sh
$ yarn add expo next @expo/next-adapter
```
### Transpilation
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://nextjs.org/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
```
## Limitations or differences compared to the default Expo for Web
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 adapter does not support the experimental **app** directory.
- For file-based routing on native, we recommend using [Expo Router](https://github.com/expo/router).
## Contributing
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)
## Troubleshooting
### Cannot use import statement outside a module
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...
    ],
  },
});
```


## Using LogRocket

A guide on installing and configuring LogRocket for session replays and error monitoring.

[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.
## Install and configure LogRocket
You can install the LogRocket SDK with the following command:
```sh
$ npx expo install @logrocket/react-native expo-build-properties
```
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"
  ]
}
```
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,
    });
  }, []);
};
```
In the code above, replace `<App ID>` with your [LogRocket App ID](https://app.logrocket.com/r/settings/setup).
## Connecting LogRocket on the EAS dashboard
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.
Go to your **Account settings** > [**Overview**](https://expo.dev/accounts/%5Baccount%5D/settings) > **Connections** and click **Connect** to authenticate with LogRocket:
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:
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.
## Learn more about LogRocket
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).


## Using Sentry

A guide on installing and configuring Sentry for crash reporting.

[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**.
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.
## What you'll learn
This guide covers three main aspects of integrating Sentry with your Expo projects:
- [Install and configure Sentry](#install-and-configure-sentry) in your React Native app
- Using Sentry with EAS:
  - [EAS Build](#usage-with-eas-build) for building your app
  - [EAS Update](#usage-with-eas-update) for over-the-air updates
- [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 />
## 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]** to view Sentry data from a Release.
With this integration, you can:
- 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
- Navigate seamlessly between EAS and Sentry for debugging
## Learn more about 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.


## Using BugSnag

A guide on installing and configuring BugSnag for end-to-end error reporting and analytics.

[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/).
With BugSnag, developers and engineering organizations can:
- **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.
- **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.
## Integration
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/).
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).


## Using Vexo

A guide on installing and configuring Vexo for real-time user analytics.

[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.
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.
## 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.
## Getting started
1. Create an account: Sign up for a [Vexo account](https://www.vexo.co/).
2. 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. 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. 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. Rebuild and run your app: Since `vexo-analytics` includes native code, you need to rebuild your application.
6. Verify integration: Go to your app's page on Vexo and you should see your first event!
## Compatibility
- Expo: Vexo is compatible with [Development builds](/development/introduction/) and does not require additional configuration plugins.
- Expo Go: Not supported, as Vexo requires custom native code.
## Learn more about Vexo
To learn more about using Vexo with Expo, check out the [Vexo documentation](https://docs.vexo.co/).


## Build Expo apps for TV

A guide for building an Expo app for an Android TV or Apple TV target.

> **Warning** 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).
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.
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.
## Prerequisites
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:
### Android
- **AndroidManifest.xml** is modified:
  - The default phone portrait orientation is removed
  - The required intent for TV apps is added
- **MainApplication.kt** is modified to remove unsupported Flipper invocations
### iOS
- **ios/Podfile** is modified to target tvOS instead of iOS
- The Xcode project is modified to target tvOS instead of iOS
- The splash screen (**SplashScreen.storyboard**) is modified to work on tvOS
## System requirements for TV development
### Android TV
- [Node.js (LTS)](https://nodejs.org/en/) on macOS or Linux.
- Android Studio (Iguana or later).
- 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).
- 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).
### Apple TV
- [Node.js (LTS)](https://nodejs.org/en/) on macOS.
- Xcode 16 or later.
- tvOS SDK 17 or later. (This is not installed automatically with Xcode. You can install it later with `xcodebuild -downloadAllPlatforms`).
## Quick start
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
```
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
```
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/)
- [BackgroundTask](/versions/latest/sdk/background-task/)
- [BlurView](/versions/latest/sdk/blur-view/)
- [BuildProperties](/versions/latest/sdk/build-properties/)
- [Constants](/versions/latest/sdk/constants/)
- [Crypto](/versions/latest/sdk/crypto/)
- [DevClient](/versions/latest/sdk/dev-client/)
- [Device](/versions/latest/sdk/device/)
- [Expo UI](/versions/latest/sdk/ui/)
- [FileSystem](/versions/latest/sdk/filesystem/)
- [FlashList](/versions/latest/sdk/flash-list/)
- [Font](/versions/latest/sdk/font/)
- [Image](/versions/latest/sdk/image)
- [ImageManipulator](/versions/latest/sdk/imagemanipulator/)
- [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/)
- [Skia](/versions/latest/sdk/skia/)
- [SplashScreen](/versions/latest/sdk/splash-screen/)
- [SQLite](/versions/latest/sdk/sqlite/)
- [Svg](/versions/latest/sdk/svg/)
- [SystemUI](/versions/latest/sdk/system-ui/)
- [TaskManager](/versions/latest/sdk/task-manager/)
- [TrackingTransparency](/versions/latest/sdk/tracking-transparency/)
- [Updates](/versions/latest/sdk/updates/)
- [Video](/versions/latest/sdk/video/)
- [VideoThumbnails](/versions/latest/sdk/video-thumbnails/)
TV also works with [React Navigation](https://reactnavigation.org/), [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 only supported in SDK 54 and later:
  - **Android TV**: All operations are supported, similar to an Android phone.
  - **Apple TV**: Basic operations with a local or tunneled packager are supported. Authentication to EAS and listing of EAS builds and updates is not yet supported.
---
## 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": {}
}
```
## Examples and demonstration projects


## Using TypeScript

An in-depth guide on configuring an Expo project with TypeScript.

Expo has first-class support for [TypeScript](https://www.typescriptlang.org/). The JavaScript interface of Expo SDK is written in 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.
## Quick start
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:
- [Set up your environment](/get-started/set-up-your-environment/) which provides required steps for setting local development environment.
- [Start developing](/get-started/start-developing/) which provides information on triggering a development server, file structure, and details about other features.
## Migrating existing JavaScript project
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://www.typescriptlang.org/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://www.typescriptlang.org/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://www.typescriptlang.org/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://www.typescriptlang.org/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;
};
```
---
### app.config.js
**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;
```
## Other TypeScript features
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://www.typescriptlang.org/docs/handbook/compiler-options.html) documentation.
## Learn how to use TypeScript
A good place to start learning TypeScript is the official [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html).
**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.


## Using in-app purchases

Learn about how to use in-app purchases in your Expo app.

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.
> 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.
## Tutorial
Video Tutorial: [Watch: How to Implement In-App Purchases in Expo](https://www.youtube.com/watch?v=R3fLKC-2Qh0)
## Libraries
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.


## Using push notifications

Learn about push notification services that are compatible with Expo and React Native apps.

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:
> 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.
## Expo push notifications
[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.
### Key capabilities
- Fully compatible with the [`expo-notifications`](/versions/latest/sdk/notifications/) library
- Includes an EAS dashboard to track notification delivery to FCM and APNs
- Supports testing notifications with the [Expo Notifications Tool](https://expo.dev/notifications)
### Considerations and limitations
- 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)).
- Volumes are limited to 600 notifications per second per project.
For implementation details, see the following guides:
## OneSignal
[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.
## Braze
[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.
## 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.
## CleverTap
[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 &mdash; 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).
## Send notifications directly via FCM and APNs
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.
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.
## React Native Firebase messaging
[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.
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.
> 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).
## 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 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.
- **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 feature flag services

An overview of feature flag services available in the Expo and React Native ecosystem.

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.
## Feature flag services
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.
### Posthog
[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.
### Statsig
[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.
### LaunchDarkly
[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.
### Firebase Remote Config
[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.


# 故障排除

## Troubleshooting overview

An overview of troubleshooting guides for app development with Expo and EAS.

This page lists a collection of various troubleshooting guides for Expo and EAS.
## Error and warnings
## Runtime issues in development and production
## Expo Router
## Push notifications
## EAS


## "Application has not been registered" error

Learn about what the Application has not been registered error means and how to resolve it in an Expo or React Native app.

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.
```
In this particular error, `"main"` can be any string.
## What this error means
### An exception may be preventing your app from registering itself
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. 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.
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.
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 &mdash; 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.
### Your app root component may not be registered
Another possibility is that there is a mismatch between the `AppKey` being provided to [`AppRegistry.registerComponent`](https://reactnative.dev/docs/appregistry#registercomponent), and the `AppKey` being registered on the native iOS or Android side.
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.
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);
```
where `registerRootComponent` is implemented as:
```js
function registerRootComponent(component) {
  AppRegistry.registerComponent('main', () => component);
}
```
And on the native side, in **AppDelegate.m** you should see:
```objectivec
RCTRootView *rootView = [[RCTRootView alloc] initWithBridge:bridge moduleName:@"main" initialProperties:nil];
```
and in **MainActivity.java**:
```java
@Override
protected String getMainComponentName() {
  return "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").
## 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:
- 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"`).
- 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.


## Clear bundler caches on macOS and Linux

Learn how to clear the bundler cache when using Yarn or npm with Expo CLI or React Native CLI on macOS and Linux.

> 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:
## 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
```
## 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
```
## 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
```
## 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
```
## What these commands are doing
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.
| Command                   | Description                                                                   |
| ------------------------- | ----------------------------------------------------------------------------- |
| `rm -rf node_modules`     | Clear all of the dependencies of your project                                 |
| `yarn cache clean`        | Clear the global Yarn cache                                                   |
| `npm cache clean --force` | Clear the global npm cache                                                    |
| `yarn`/`npm install`      | Reinstall all dependencies                                                    |
| `watchman watch-del-all`  | Reset the `watchman` file watcher                                             |
| `rm -rf $TMPDIR/<cache>`  | Clear the given packager/bundler cache file or directory                      |
| `npx expo start --clear`  | Restart the development server and clear the JavaScript transformation caches |


## Clear bundler caches on Windows

Learn how to clear the bundler cache when using Yarn or npm with Expo CLI or React Native CLI on Windows.

> 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.
## 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
```
## 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
```
## 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
```
## 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
```
## What these commands are doing
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.
| Command                           | Description                                                                   |
| --------------------------------- | ----------------------------------------------------------------------------- |
| `del node_modules`                | Clear all of the dependencies of your project                                 |
| `yarn cache clean`                | Clear the global Yarn cache                                                   |
| `npm cache clean --force`         | Clear the global npm cache                                                    |
| `yarn`/`npm install`              | Reinstall all dependencies                                                    |
| `watchman watch-del-all`          | Reset the `watchman` file watcher                                             |
| `del %localappdata%\Temp/<cache>` | Clear the given packager/bundler cache file or directory                      |
| `npx expo start --clear`          | Restart the development server and clear the JavaScript transformation caches |


## "React Native version mismatch" errors

Learn about what React Native version mismatch means and how to resolve it in an Expo or React Native app.

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...
```
## What this error means
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.
## How to fix it
- 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"`).
- 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.
- 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.
- 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:
  - 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`
    - Commands if you are using npm can be found [here.](clear-cache-macos-linux)
    - Commands if you are using Windows can be found [here.](clear-cache-windows)
  - 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)


## Troubleshooting Proxies

Learn about troubleshooting proxies with a set of recommended tools.

## macOS proxy configuration (Sierra)
> 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`.
### Overview
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).
#### Open macOS network preferences
1. Open `System Preferences` for your Mac (Apple Menu > System Preferences).
2. Go to Network.
3. Be sure your `Location` is set to your proxy network, and not "Automatic".
4. With Wi-Fi selected on the left and/or ethernet connection, click `Advanced...` on the bottom right side of the window.
#### Configure proxy address
1. Disable/uncheck "Automatic Proxy Configuration" if it is set.
2. Check "Web Proxy (HTTP)" and set "Web Proxy Server" to 127.0.0.1 : 8888
3. Check "Secure Web Proxy (HTTPS)" and set "Secure Web Proxy Server" to 127.0.0.1 : 8888
### Configure `Charles`
1. Open Charles
2. 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. In the menu of Charles go to `Proxy > External Proxy Settings`, check `Use external proxy servers`
4. Check `Web Proxy (HTTP)`, and enter `your-corporate-proxy-uri:port-number`
5. Check `Proxy server requires a password`
6. Domain: YOUR DOMAIN,
   Username: YOUR USERNAME
   Password: YOUR PASSWORD
7. Same for Secure Web Proxy (HTTPS). _Be sure to fill in the same proxy, username, and password address_ fields.
8. 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"
### iOS Simulator configuration
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.
Now, in Charles under the "Help" menu > Install Charles Root Certificate, and then again for Install Charles Root Certificate in iOS Simulators
> **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/ which is required to run Expo.  **Also note:** Configure applications that need internet access, such as Spotify, to use 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.
## Command line application proxy configuration
npm, git, Brew, Curl, and any other command line applications need proxy access too.
#### For npm
Open `~/.npmrc` and set:
```ini .npmrc
http_proxy=http://localhost:8888
https_proxy=http://localhost:8888
```
### For git
Open `~/.gitconfig` and set
```ini .gitconfig
[http]
  proxy = http://localhost:8888
[https]
  proxy = http://localhost:8888
```
### For command line applications
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"
```
> 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.


# 合规性

## Data and Privacy protection

An overview of data and privacy protection policies that Expo offers.

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.
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.
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 compliance and Expo

Learn about how applications built with Expo can be GDPR compliant.

## Are apps built with Expo GDPR compliant?
**They can be! You can build GDPR compliant apps with Expo if you follow the requirements.**
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 compliance and Expo

Learn about how applications built with Expo can be HIPAA compliant.

## Are apps built with Expo HIPAA compliant?
**They can be! You can build HIPAA compliant apps with Expo if you follow the requirements.**
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.