`、`
` 和 `![]()
`。在为 web 开发时，RNW 是可选的，因为你可以直接使用 React DOM，但在跨平台构建时，我们通常推荐使用它，因为它能最大化代码复用。
> React Native for web 被用来驱动整个 [X](https://x.com/) 网站。
Expo SDK 中的所有库都设计为同时支持浏览器和服务器渲染环境（在适用时）。这些库也针对其所面向的各个平台进行了优化。
像 Fast Refresh、调试、环境变量以及[打包](/guides/customizing-metro)等开发功能也都完全通用，从而提供统一的开发体验。Expo CLI 在你构建生产版本时会使用[平台摇树优化](/guides/tree-shaking#platform-shaking)等技术，**自动优化代码**以适配各个平台。
## 开始使用
### 安装 web 依赖
```sh
npx expo install react-dom react-native-web @expo/metro-runtime
```
还没有在你的应用中使用 `expo` 包？
如果你还没有为你的 React Native 应用添加 Expo，你可以[安装 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 {AppRegistry} from 'react-native';
- import {name as appName} from './app.json';
+ import {registerRootComponent} from 'expo';
import App from './App';
- AppRegistry.registerComponent(appName, () => App);
+ registerRootComponent(App);
```
### 启动开发服务器
现在你可以启动开发服务器，并在浏览器中使用以下命令进行开发：
```sh
npx expo start --web
```
应用可以通过以下命令导出为生产网站：
```sh
npx expo export --platform web
```
## 下一步
[基于文件的路由](/router/introduction) — 使用 Expo Router 构建路由和导航。
[静态渲染与 SEO](/router/web/static-rendering) — 使用 Expo Router 将你的网站渲染为静态 HTML，以提升 SEO 和性能。
[使用 EAS Hosting 立即部署](/eas/hosting/get-started) — EAS Hosting 是部署你的 Expo Router 和 React Native web 应用的最佳方式，支持自定义域名、SSL 等更多功能。
[自定义 JavaScript 打包器](/guides/customizing-metro) — 为你的项目自定义 Metro 打包器。
---
---
title: 发布网站
description: 了解如何将 Expo 网站部署到生产环境。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/publishing-websites/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 发布网站
了解如何将 Expo 网站部署到生产环境。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
Expo Web 应用可以在本地提供服务以测试生产环境下的行为，也可以部署到托管服务。我们建议部署到 [EAS Hosting](/eas/hosting)，以获得最佳的功能支持。你也可以自行托管，或者使用第三方服务。
[使用 EAS 立即部署](/eas/hosting/get-started) — EAS Hosting 是部署 Web 应用的最佳方式，支持自定义域名、SSL 等更多功能。
> 对于 SDK 49 及更早版本，你可能需要参考 [`webpack` 构建发布指南](/archive/publishing-websites-webpack)。
## 输出目标
可以在 [应用配置](/workflow/configuration) 中配置 [`web.output`](/versions/latest/config/app#output) 目标，以设置 Web 应用的导出方式：
```json
{
"expo": {
"web": {
"output": "server",
"bundler": "metro"
}
}
}
```
Expo Router 支持 Web 应用的三种输出目标。
| 输出 | Expo Router | API Routes | 描述 |
| --- | --- | --- | --- |
| `single`（默认） | ✓ | ✗ | 输出一个单页应用（SPA），在输出目录中只有一个 **index.html**，并且没有可静态索引的 HTML。 |
| `server` | ✓ | ✓ | 创建 **client** 和 **server** 目录。客户端文件会作为独立的 HTML 文件输出。API 路由会作为独立的 JavaScript 文件输出，用于配合自定义 Node.js 服务器托管。 |
| `static` | ✓ | ✗ | 为 **app** 目录中的每条路由输出独立的 HTML 文件。 |
> **注意**：对于 `static` 和 `server` 输出模式，你可以通过 `expo-router` 插件配置适用于所有路由响应的 [全局 HTTP 头](/router/web/server-headers)。
## 创建构建
为项目创建构建是发布 Web 应用的第一步。无论你是想在本地提供服务还是部署到托管服务，都需要导出项目的所有 JavaScript 和资源文件。这称为静态 bundle。可以通过运行以下命令进行导出：
运行通用导出命令以编译 Web 项目：
```sh
npx expo export -p web
```
生成的项目文件位于 **dist** 目录中。**public** 目录中的任何文件也会被复制到 **dist** 目录。
> 某些路径（例如 `/assets`）会被 Metro 保留。避免将文件放在 **public/assets/** 或其他保留路径中。完整列表请参见 [保留路径](/router/reference/reserved-paths)。
## 在本地提供服务
使用 `npx expo serve` 可以快速在本地测试你的网站在生产环境中的托管效果。运行以下命令以提供静态 bundle 服务：
```sh
npx expo serve
```
打开 [`http://localhost:8081`](http://localhost:8081) 查看项目运行效果。这是**仅限 HTTP**，因此权限、相机、位置以及许多其他安全功能可能无法按预期工作。
## 使用 EAS 托管
当你准备上线时，可以使用 EAS CLI 立即部署你的网站。
[使用 EAS 立即部署](/eas/hosting/get-started) — EAS Hosting 是部署 Web 应用的最佳方式，支持自定义域名、SSL 等更多功能。
## 使用第三方服务托管
### Netlify
[Netlify](https://www.netlify.com/) 是一个对部署 Web 应用几乎不施加预设限制的平台。它对 Expo Web 应用具有最高兼容性，因为它对框架的假设很少。
#### 使用 Netlify CDN 手动部署
通过运行以下命令安装 Netlify CLI：
```sh
npm install -g netlify-cli
```
为单页应用配置重定向。
> 如果你的应用使用 [静态渲染](/router/web/static-rendering)，那么可以跳过此步骤。
`expo.web.output: 'single'` 会生成一个单页应用。这意味着只有一个 **dist/index.html** 文件，所有请求都必须重定向到它。在 Netlify 中可以通过创建 **./public/_redirects** 文件，并将所有请求重定向到 **/index.html** 来实现。
```sh
/* /index.html 200
```
如果你修改了此文件，必须使用 `npx expo export -p web` 重新构建项目，才能安全地将其复制到 **dist** 目录。
通过运行以下命令部署 Web 构建目录：
```sh
netlify deploy --dir dist
```
你会看到一个 URL，可用于在线查看你的项目。
#### 持续交付
Netlify 也可以在你推送到 git 或打开新的拉取请求时自动构建并部署：
- [开始一个新的 Netlify 项目](https://app.netlify.com/signup)。
- 选择你的 Git 托管服务并选中你的仓库。
- 点击 **Build your site**。
### Vercel
[Vercel](https://vercel.com/) 提供单命令部署流程。
安装 [Vercel CLI](https://vercel.com/docs/cli)。
```sh
npm install -g vercel@latest
```
为单页应用配置重定向。
在你的应用根目录下创建一个 **vercel.json** 文件，并添加以下配置：
```json
{
"buildCommand": "expo export -p web",
"outputDirectory": "dist",
"devCommand": "expo",
"cleanUrls": true,
"framework": null,
"rewrites": [
{
"source": "/:path*",
"destination": "/"
}
]
}
```
如果你的应用使用 [静态渲染](/router/web/static-rendering)，你可能还需要添加额外的 [动态路由配置](/router/web/static-rendering#dynamic-routes)。
部署网站。
```sh
vercel
```
现在你会看到一个 URL，可用于在线查看你的项目。构建完成后，将该 URL 粘贴到浏览器中，你就会看到已部署的应用。
### AWS Amplify Console
[AWS Amplify Console](https://console.amplify.aws) 提供基于 Git 的工作流，用于持续部署和托管全栈无服务器 Web 应用。Amplify 会从仓库而不是从你的电脑部署你的 PWA。在本指南中，我们将使用 GitHub 仓库。开始之前，请先在 GitHub 上[创建一个新仓库](https://github.com/new)。
将 [**amplify-explicit.yml**](https://github.com/expo/amplify-demo/blob/master/amplify-explicit.yml) 文件添加到仓库根目录。确保你已从 **.gitignore** 文件中移除了生成的 **dist** 目录，并提交了这些更改。
将你的本地 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)。
登录 [Amplify Console](https://console.aws.amazon.com/amplify/home)，选择一个现有应用或创建一个新应用。授予 Amplify 读取你 GitHub 账号或拥有该仓库的组织的权限。
添加你的仓库，选择分支，并勾选 **Connecting a monorepo?**，以输入你的应用 **dist** 目录路径，然后选择 **Next**。
Amplify Console 会检测你项目中的 **amplify.yml** 文件。选择 **Allow AWS Amplify to automatically deploy all files hosted in your project root directory**，然后选择 **Next**。
检查你的设置并选择 **Save and deploy**。你的应用现在将部署到一个 `https://branchname.xxxxxx.amplifyapp.com` URL。你现在可以访问你的 Web 应用、部署另一个分支，或在 Expo 移动端和 Web 应用之间添加统一的后端环境。
按照 **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/) 是适用于 Web 项目的生产级 Web 内容托管服务。
使用 [Firebase Console](https://console.firebase.google.com) 创建一个 Firebase 项目，并按照这些[说明](https://firebase.google.com/docs/hosting)安装 Firebase CLI。
使用 CLI，通过运行以下命令登录你的 Firebase 账号：
```sh
firebase login
```
然后，通过运行以下命令初始化你的 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**。
在 **package.json** 的现有 `scripts` 属性中，添加 `predeploy` 和 `deploy` 属性。它们的值如下：
```json
"scripts": {
...
"predeploy": "expo export -p web",
"deploy-hosting": "npm run predeploy && firebase deploy --only hosting",
}
```
要进行部署，请运行以下命令：
```sh
npm run deploy-hosting
```
打开控制台输出中的 URL 以检查你的部署，例如：`https://project-name.firebaseapp.com`。
如果你想更改托管的 header，请在 **firebase.json** 中为 `hosting` 部分添加以下配置：
```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 仓库发布网站。
首先在你的项目中初始化一个新的 git 仓库，并配置将其推送到 GitHub 仓库。如果你已经在与 GitHub 仓库同步更改，可以跳过此步骤。
在 GitHub 网站上创建一个仓库。然后，在你的项目根目录中运行以下命令：
```sh
git init
git remote add origin https://github.com/username/expo-gh-pages.git
```
上述命令会初始化一个新的 Git 仓库，并配置将你的源代码推送到指定的 GitHub 仓库。
将 `gh-pages` 包作为开发依赖安装到你的项目中：
```sh
# npm
npm install --save-dev gh-pages
# yarn
yarn add -D gh-pages
# pnpm
pnpm add -D gh-pages
# bun
bun add -D gh-pages
```
要部署项目，请在 [应用配置](/workflow/configuration) 中使用 [`baseUrl`](/versions/latest/config/app#baseurl) 属性将其配置到一个子域。将其值设为字符串 `/repo-name`。
例如，如果 GitHub 仓库是 `expo-gh-pages`，那么下面将是 [实验性 `baseUrl` 属性](/more/expo-cli#hosting-with-sub-paths) 的值：
```json
{
"expo": {
"experiments": {
"baseUrl": "/expo-gh-pages"
}
}
}
```
通过在 **package.json** 文件中添加 `predeploy` 和 `deploy` 脚本来修改 `scripts`。每个脚本都有自己的值：
```json
"scripts": {
...
"deploy": "gh-pages --nojekyll -d dist",
"predeploy": "expo export -p web"
}
```
由于 Expo 在生成的文件中使用下划线，你需要使用 `--nojekyll` 标志来禁用 Jekyll。
要生成 Web 应用的生产构建并将其部署到 GitHub Pages，请运行以下命令：
```sh
# npm
npm run deploy
# yarn
yarn run deploy
# pnpm
pnpm run deploy
# bun
bun run deploy
```
这会将 Web 应用的构建发布到 GitHub 仓库的 `gh-pages` 分支。该分支只包含 **dist** 目录中的构建产物，以及 `gh-pages` 生成的 **.nojekyll** 文件。不包含开发源代码。
现在 Web 应用已经发布到 `gh-pages` 分支，请将 GitHub Pages 配置为从该分支提供应用服务。
- 进入 GitHub 仓库的 **Settings** 选项卡。
- 向下滚动到 **Pages** 部分。
- 确保 **Source** 设置为 **Deploy from a branch**。
- 在 **Branch** 部分，选择 **gh-pages** 和 **root** 目录。
- 点击 **Save**。
一旦 Web 应用发布完成并设置好 GitHub Pages 配置，GitHub Action 将会部署你的网站。你可以通过进入仓库的 **Actions** 选项卡来监控进度。完成后，你的 Web 应用将可通过 URL `http://username-on-github.github.io/repo-name` 访问。
对于后续部署和更新，运行 `deploy` 命令，GitHub Action 会自动启动以更新你的 Web 应用。
---
---
title: 在 Expo 原生应用中使用 React DOM
description: 了解如何在 Expo 原生应用中使用 'use dom' 指令渲染 React DOM 组件。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/dom-components/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 在 Expo 原生应用中使用 React DOM
了解如何在 Expo 原生应用中使用 'use dom' 指令渲染 React DOM 组件。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
Expo 提供了一种新颖的方式，通过 `'use dom'` 指令直接在原生应用中使用现代 Web 代码。这使得可以通过按组件逐步迁移，将整个网站增量式地迁移为统一应用。
虽然 Expo 原生运行时通常不支持 `
` 或 `
![]()
` 之类的元素，但在某些情况下，你可能需要快速集成 Web 组件。在这种情况下，DOM 组件提供了一个有用的解决方案。
## 前提条件
你的项目必须使用 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) 指南。
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，请在 Web 组件文件顶部添加 `'use dom'` 指令：
```tsx
'use dom';
export default function DOMComponent({ name }: { name: string }) {
return (
你好，{name}
);
}
```
在原生组件文件中，导入该 Web 组件以使用它：
```tsx
import DOMComponent from './my-component.tsx';
export default function App() {
return (
// 这是一个 DOM 组件。它在底层重新导出了一个包装过的 `react-native-webview`。
);
}
```
## 特性
- Web、原生和 DOM 组件共享同一套 bundler 配置。
- DOM 组件中启用了 React、TypeScript、CSS 以及所有其他 Metro 特性。
- 可在终端以及 Safari/Chrome 中进行日志记录和调试。
- Fast Refresh 和 HMR。
- 为离线支持提供嵌入式导出。
- 资源在 Web 和原生之间统一。
- DOM 组件 bundle 可在 [Expo Atlas](/guides/analyzing-bundles#analyzing-bundle-size-with-atlas) 中进行检查以便调试。
- 无需原生重新构建即可访问所有 Web 功能。
- 开发环境下的运行时错误覆盖层。
- 支持 Expo Go。
## WebView 属性
要将属性传递给底层原生 **WebView**，请在组件上使用 `dom` 属性。这个属性内置于每个 DOM 组件中，并接受一个对象，其中可以包含你想要修改的任意 [`WebView` 属性](https://github.com/react-native-webview/react-native-webview/blob/master/docs/Reference.md)。
```tsx
import DOMComponent from './my-component';
export default function App() {
return (
);
}
```
在你的 DOM 组件中，添加 `dom` 属性以便 TypeScript 能识别它：
```tsx
'use dom';
export default function DOMComponent({}: { dom: import('expo/dom').DOMProps }) {
return (
你好，世界！
);
}
```
## 序列化属性
你可以通过可序列化属性（`number`、`string`、`boolean`、`null`、`undefined`、`Array`、`Object`）将数据发送到 DOM 组件。例如，在原生组件文件中，你可以向 DOM 组件传递一个属性：
```tsx
import DOMComponent from './my-component';
export default function App() {
return
;
}
```
在 Web 组件文件中，你可以像下面的示例那样接收该属性：
```tsx
'use dom';
export default function DOMComponent({ hello }: { hello: string }) {
return
你好，{hello}
;
}
```
属性通过异步桥接发送，因此不会同步更新。它们作为属性传递给 React 根组件，这意味着它们会导致整个 React 树重新渲染。
## 原生动作
你可以通过将异步函数作为 DOM 组件的顶层属性传递，向 DOM 组件发送类型安全的原生函数：
```tsx
import DomComponent from './my-component';
export default function App() {
return (
{
console.log('你好', data);
}}
/>
);
}
```
```tsx
'use dom';
export default function MyComponent({ hello }: { hello: (data: string) => Promise }) {
return hello('world')}>点我
;
}
```
> 你不能将函数作为嵌套属性传递给 DOM 组件。它们必须是顶层属性。
原生动作始终是异步的，并且只接受可序列化的参数（也就是说不能是函数），因为数据会通过桥接发送到 DOM 组件的 JavaScript 引擎。
原生动作可以向 DOM 组件返回可序列化数据，这对于从原生侧获取数据很有用。
```tsx
getDeviceName(): Promise {
return DeviceInfo.getDeviceName();
}
```
你可以把这些函数看作 React Server Functions，只不过它们不是存在于服务器上，而是本地运行在原生应用中，并与 DOM 组件通信。这种方式为向 DOM 组件添加真正的原生功能提供了强大的手段。
## 传递 refs
> **重要** 这项功能目前处于 [alpha](/more/release-statuses#alpha) 阶段，未来可能会发生变化。
你可以在 DOM 组件内部使用 `useDOMImperativeHandle` 钩子，从而接受来自原生侧的 ref 调用。这个钩子类似于 React 的 [`useImperativeHandle`](https://react.dev/reference/react/useImperativeHandle) 钩子，但它不需要传入 ref 对象。
```tsx
import { useRef } from 'react';
import { Button, View } from 'react-native';
import MyComponent, { type DOMRef } from './my-component';
export default function App() {
const ref = useRef(null);
return (
);
}
```
Expo SDK 53 及更高版本使用 React 19。这意味着 `ref` 属性会作为属性传递给组件，你可以在组件中直接使用它。
```tsx
'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;
dom?: import('expo/dom').DOMProps;
}) {
const inputRef = useRef(null);
useDOMImperativeHandle(
props.ref,
() => ({
focus: () => {
inputRef.current?.focus();
},
}),
[]
);
return ;
}
```
React 旨在实现单向数据流，因此使用回调函数向上层树传递数据并不符合其惯用模式。请预期这种行为可能不稳定，并且在未来 React 的新版本中可能会被逐步移除。将数据返回到上层树的首选方式是使用原生动作，它会更新状态，然后再将其传回 DOM 组件。
## 特性检测
由于 DOM 组件用于运行网站，你可能需要额外的限定条件来更好地支持某些库。你可以使用以下代码检测某个组件是否在 DOM 组件中运行：
```ts
import { IS_DOM } from 'expo/dom';
```
虽然在 DOM 组件中 `process.env.EXPO_OS` 始终会是 web，但你可以使用 `process.env.EXPO_DOM_HOST_OS` 来检测 _顶层_ 平台。它要么是 `ios`、`android`，取决于最上层原生平台的操作系统；在 web 上则为 `undefined`。
## 公共资源
> **重要** **警告：** 这项功能目前处于 [alpha](/more/release-statuses#alpha) 阶段，未来可能会发生变化。EAS Update 不支持公共资源。请改用 `require()` 来加载本地资源。
根目录下 **public** 目录的内容会被复制到原生应用的二进制文件中，以支持在 DOM 组件中使用公共资源。由于这些公共资源将从本地文件系统提供，请使用 `process.env.EXPO_BASE_URL` 前缀来引用正确的路径。例如：
```tsx
```
## 调试
默认情况下，WebView 中所有 `console.log` 方法都会被扩展，以便将日志转发到终端。这样就可以快速而轻松地查看 DOM 组件中正在发生的事情。
Expo 还会在开发模式打包时启用 WebView 检查和调试。你可以打开 **Safari** > **Develop** > **Simulator** > **MyComponent.tsx** 来查看 WebView 的控制台并检查元素。
## 手动 WebView
你可以使用 `react-native-webview` 中的 `WebView` 组件创建一个手动 WebView。这对于从远程服务器渲染网站很有用。
```tsx
import { WebView } from 'react-native-webview';
export default function App() {
return Hello, world!' }} />;
}
```
## 路由
Expo Router API，例如 `` 和 `useRouter`，可以在 DOM 组件中用于在路由之间导航。
```tsx
'use dom';
import Link from 'expo-router/link';
export default function DOMComponent() {
return (
你好，世界！
关于
);
}
```
像 `useLocalSearchParams()`、`useGlobalSearchParams()`、`usePathname()`、`useSegments()`、`useRootNavigation()` 和 `useRootNavigationState()` 这类会同步返回路由信息的 API 不会自动受到支持。相反，请在 DOM 组件外部读取这些值，并将它们作为 props 传入。
```tsx
import DOMComponent from './my-component';
import { usePathname } from 'expo-router';
export default function App() {
const pathname = usePathname();
return ;
}
```
`router.canGoBack()` 和 `router.canDismiss()` 函数也不受支持，并且需要手动编组，这可确保不会触发多余的渲染循环。
避免使用标准网页 `` 锚点元素进行导航，因为这会以一种用户可能无法返回的方式更改 DOM 组件的来源。若你想展示外部网站，优先使用启动 `WebBrowser` 的方式。
由于 DOM 组件不能渲染原生子组件，布局路由（`_layout`）永远不能是 DOM 组件。你可以从布局路由中渲染 DOM 组件来创建头部、背景等内容，但布局路由本身应始终保持为原生。
## 测量 DOM 组件
你可能希望测量 DOM 组件的尺寸，并将其回传给原生端（例如，用于原生滚动）。这可以通过 `matchContents` prop 或手动原生操作来实现：
### 通过 `matchContents` prop 自动测量
你可以使用 `dom={{ matchContents: true }}` prop 自动测量 DOM 组件的尺寸并调整原生视图大小。这对于某些布局特别有用，因为 DOM 组件必须具有固有尺寸才能显示，例如当组件居中于父视图中时：
```tsx
import DOMComponent from './my-component';
export default function Route() {
return ;
}
```
### 通过指定尺寸手动设置
你也可以通过 `dom` prop 将尺寸传递给 `WebView` 的 `style` prop 来手动提供尺寸：
```tsx
import DOMComponent from './my-component';
export default function Route() {
return (
);
}
```
### 观察尺寸变化
如果你希望将 DOM 组件尺寸的变化回传给原生端，可以向 DOM 组件添加一个原生操作，每当尺寸发生变化时就会被调用：
```tsx
'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 ;
}
```
然后更新你的原生代码，以便在 DOM 组件报告尺寸变化时，将尺寸设置到状态中：
```tsx
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 (
{
if (containerSize?.width !== width || containerSize?.height !== height) {
setContainerSize({ width, height });
}
}}
dom={{
containerStyle:
containerSize != null
? { width: containerSize.width, height: containerSize.height }
: null,
}}
/>
);
}
```
## 架构
内置的 DOM 支持仅将网站渲染为单页应用程序（没有 SSR 或 SSG）。这是因为搜索引擎优化和索引对嵌入式 JS 代码并不必要。
当一个模块被标记为 `'use dom'` 时，它会在运行时被一个代理引用替换。此特性主要通过一系列打包器和 CLI 技术实现。
如果需要，你仍然可以通过将原始 HTML 传递给 `WebView` 组件，使用标准方式来使用 WebView。
在网站或其他 DOM 组件中渲染的 DOM 组件将表现为普通组件，且 `dom` prop 会被忽略。这是因为 Web 内容是直接透传的，而不是包裹在 `iframe` 中。
总体而言，这套系统与 Expo 的 React Server Components 实现有许多相似之处。
## 注意事项
我们建议使用 `View`、`Image` 和 `Text` 等通用原语构建真正的原生应用。DOM 组件仅支持标准 JavaScript，其解析和启动速度比经过优化的 Hermes 字节码更慢。
数据只能通过异步 JSON 传输系统在 DOM 组件和原生组件之间传递。避免依赖跨 JS 引擎的数据，以及在 DOM 组件中深度链接到嵌套 URL，因为它们目前不支持与 Expo Router 的完整协调。
虽然 DOM 组件并不专属于 Expo Router，但它们是针对 Expo Router 应用开发和测试的，以便在与 Expo Router 一起使用时提供最佳体验。
如果你有用于共享数据的全局状态，它将无法跨 JS 引擎访问。
虽然 Expo SDK 中的原生模块可以被优化以支持 DOM 组件，但这一优化目前尚未实现。请使用原生操作和 props 与 DOM 组件共享原生功能。
与原生视图相比，DOM 组件和网站整体上并不那么理想，但它们仍有一些合理用途。例如，Web 在概念上是渲染富文本和 markdown 的最佳方式。Web 对 WebGL 的支持也非常好，不过在低电量模式下，设备通常会限制网页帧率以节省电量。
许多大型应用也会为辅助路由使用一些 Web 内容，例如博客文章、富文本（例如 X 上的长文）、设置页面、帮助页面，以及应用中其他访问频率较低的部分。
## 服务端组件
DOM 组件目前仅渲染为单页应用程序，不支持静态渲染或 React Server Components（RSC）。当项目使用 React Server Components 时，无论平台如何，`'use dom'` 的行为都将与 `'use client'` 相同。RSC Payload 可以作为属性传递给 DOM 组件。不过，它们无法在原生平台上被正确 hydrate，因为它们会为原生运行时进行渲染。
## 限制
- 与服务端组件不同，你不能将 `children` 传递给 DOM 组件。
- DOM 组件是独立的，不会在不同实例之间自动共享数据。
- 你不能向 DOM 组件添加原生视图。虽然你可以尝试将原生视图浮在 DOM 组件之上，但这种方式会导致较差的用户体验。
- 函数 props 不能同步返回值。它们必须是异步的。
- DOM 组件目前只能作为嵌入内容，且不支持 OTA 更新。此功能未来可能会作为 React Server Components 的一部分加入。
最终，通用架构才是最令人兴奋的类型。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 组件。
**通过 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
```
---
---
title: 渐进式 Web 应用
description: 了解如何为 Expo 网站添加渐进式 Web 应用支持。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/progressive-web-apps/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 渐进式 Web 应用
了解如何为 Expo 网站添加渐进式 Web 应用支持。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
渐进式 Web 应用（简称 PWA）是可以安装到用户设备上并可离线使用的网站。我们建议尽可能构建原生应用，因为它们具有最佳的离线支持，但对于桌面用户来说，PWA 也是一个很好的选择。
## 图标
Expo CLI 会根据 **app.json** 中的 `web.favicon` 字段自动生成 **favicon.ico** 文件。
```json
{
"web": {
"favicon": "./assets/favicon.png"
}
}
```
另外，你也可以在 **public** 目录中创建一个 **favicon.ico** 文件来手动指定图标。
## 清单文件
PWA 可以通过 [manifest 文件进行配置](https://developer.mozilla.org/en-US/docs/Web/Manifest)，该文件描述应用的名称、图标和其他元数据。
在 **public/manifest.json** 中创建一个 PWA manifest：
```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"
}
```
**logo192.png** 和 **logo512.png** 文件是在应用安装到用户设备上时会使用的图标。它们也应该添加到 **public** 目录中。
`public`
`manifest.json``PWA 清单`
`logo192.png``192x192 图标`
`logo512.png``512x512 图标`
现在在你的 HTML 文件中链接 manifest。这里的方法取决于你网站的输出模式（在 **app.json** 中由 `web.output` 指示——默认值为 `single`）。
如果你使用的是单页应用，可以先在 **public/index.html** 中创建一个模板 HTML，然后在你的 HTML 文件中链接 manifest：
```sh
npx expo customize public/index.html
```
然后在 `` 标签中添加 manifest：
```html
```
## Service workers
Service worker 主要用于为网站添加离线支持。Google 的 Workbox 是为网站添加 service worker 的最佳方式。请参考 [使用 Workbox CLI](https://developer.chrome.com/docs/workbox/modules/workbox-cli/) 的指南，并且其中凡是提到 “build script（构建脚本）” 的地方，都改为使用 `npx expo export -p web`。
> 添加 service worker 时请务必小心，因为它们已知会在 Web 上引发意外行为。如果你不小心发布了一个激进缓存你网站的 service worker，用户将无法轻松请求更新。若想获得最佳的移动端离线体验，请使用 Expo 创建原生应用。与带有 service worker 的网站不同，原生应用可以通过应用商店更新来清除缓存体验。这类似于重置用户的原生浏览器（如果 service worker 足够激进，他们可能不得不这样做）。更多信息请参见 [为什么 service worker 不是最佳选择](https://github.com/facebook/create-react-app/issues/2398)。
例如，下面是一个设置 Workbox 的可能流程：
使用以下命令创建一个新项目：
```sh
npm create expo -t tabs my-app
cd my-app
```
现在在 HTML 文件中注册 service worker。这里的方法取决于你网站的输出模式（在 **app.json** 中由 `web.output` 指示——默认值为 `single`）。
接下来在根 **index.html** 中添加一个 service worker 注册脚本。
如果尚不存在，先在 **public/index.html** 中创建一个模板 HTML：
```sh
npx expo customize public/index.html
```
然后在 `` 标签中创建 service worker 注册脚本：
```html
```
现在在运行向导之前先构建网站：
```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
{
"scripts": {
"build:web": "expo export -p web && npx workbox-cli generateSW workbox-config.js"
}
}
```
如果你托管了你的网站并使用 Chrome 访问，可以在 Chrome DevTools 中通过进入 **Application > Service Workers** 来检查 service worker。
---
---
title: Tailwind CSS
description: 学习如何在你的 Expo 项目中配置和使用 Tailwind CSS。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/tailwind/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# Tailwind CSS
学习如何在你的 Expo 项目中配置和使用 Tailwind CSS。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
> 标准 Tailwind CSS 仅支持 Web 平台。若要获得通用支持，请使用类似 [NativeWind](https://www.nativewind.dev/) 或 [Uniwind](https://uniwind.dev/) 这样的库，它们允许使用 Tailwind CSS 创建带样式的 React Native 组件。
[Tailwind CSS](https://tailwindcss.com/) 是一个实用优先的 CSS 框架，可与 Metro 一起用于 Web 项目。本指南将说明如何配置你的 Expo 项目以使用该框架。
## 先决条件
将修改以下文件以设置 Tailwind CSS 配置：
`app.json`
`package.json`
`global.css`
`index.js`
确保你的项目正在为 Web 使用 Metro。你可以通过检查 `web.bundler` 字段来验证这一点，该字段在 **app.json** 文件中设置为 `metro`。
```json
{
"expo": {
"web": {
"bundler": "metro"
}
}
}
```
## 配置
请根据 [Tailwind PostCSS 文档](https://tailwindcss.com/docs/installation/using-postcss) 在你的 Expo 项目中配置 Tailwind CSS。
安装 `tailwindcss` 及其所需的同级依赖。然后运行初始化命令，在项目根目录中创建 **tailwind.config.js** 和 **post.config.js** 文件。
```sh
npx expo install tailwindcss@3 postcss autoprefixer --dev
npx tailwindcss init -p
```
将所有模板文件的路径添加到 **tailwind.config.js** 中。
```js
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
// 确保这里指向你的源代码
'./src/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)的信息。
在项目根目录创建一个 **global.css** 文件，并为 Tailwind 的每一层添加指令：
```css
/* 此文件添加 Tailwind 正常工作所需的实用类。 */
@tailwind base;
@tailwind components;
@tailwind utilities;
```
在你的 **src/app/_layout.tsx**（如果使用 Expo Router）或 **index.js** 文件中导入 **global.css** 文件：
```tsx
import '../../global.css';
```
```tsx
// 在 index.js 文件中导入 global.css 文件：
import './global.css';
```
> 如果你正在使用 [DOM 组件](/guides/dom-components)，由于它们不共享全局变量，请将此文件导入添加到每个使用 `"use dom"` 指令的模块中。
> 始终在根级 **_layout.tsx** 中导入全局 CSS，而不是在嵌套布局中。Expo Router 会从根布局开始遍历依赖图。在嵌套布局中导入 CSS（例如 **app/blog/_layout.tsx**）会导致 **node_modules** 中的 CSS 先于你的自定义样式加载，这可能会破坏你期望的样式顺序。
现在启动你的项目，并在组件中使用 Tailwind CSS 类。
```sh
npx expo start
```
## 用法
你可以直接在 React DOM 元素中使用 Tailwind：
```tsx
export default function Index() {
return (
);
}
```
你可以使用 `{ $$css: true }` 语法将 Tailwind 与 React Native web 元素一起使用：
```tsx
import { View, Text } from 'react-native';
export default function Index() {
return (
欢迎使用 Tailwind
);
}
```
## Android 和 iOS 的 Tailwind
Tailwind 不支持 Android 和 iOS 平台。你可以使用兼容性库，例如 [NativeWind](https://www.nativewind.dev/) 或 [Uniwind](https://uniwind.dev/)，以获得跨平台支持。
## Android 和 iOS 的替代方案
或者，你可以使用 [DOM components](/guides/dom-components) 在原生环境中的 `WebView` 里渲染你的 Tailwind Web 代码。
```tsx
'use dom';
// 记得在每个 DOM 组件中导入 global.css 文件。
import '../../global.css';
export default function Page() {
return (
);
}
```
## 故障排查
如果你在 **metro.config.js** 中自定义了 `config.cacheStores`，你需要扩展 `FileStore` 的 Expo 超类：
```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
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname, {
// 使用 Tailwind 时，不要禁用 CSS 支持。
isCSSEnabled: true,
});
```
---
---
title: 使用本地 HTTPS 开发
description: 了解如何为 Expo Web 应用设置本地 HTTPS。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/local-https-development/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 使用本地 HTTPS 开发
了解如何为 Expo Web 应用设置本地 HTTPS。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
在本地开发 Expo web 应用时，您可能需要在本地开发环境中使用 HTTPS，以测试安全的浏览器 API。本指南将向您展示如何为 Expo web 应用设置本地 HTTPS。
## 前提条件
本指南要求您的机器上安装以下工具：
- `mkcert`：用于创建开发证书的工具。安装说明请参见 [`mkcert` GitHub 仓库](https://github.com/FiloSottile/mkcert#installation)。
## 优势
- **团队可扩展性**：相同的设置适用于所有人
- **身份验证支持**：HTTP-Only Cookie 和安全上下文
- **生产环境一致性**：与您的生产 HTTPS 环境保持一致
- **易于共享**：团队之间保持一致的开发 URL
## 设置您的项目
创建或进入您的 Expo 项目：
```sh
npx create-expo-app@latest example-app --template default@sdk-55
cd example-app
cd your-expo-project
```
启动您的 Expo 开发服务器：
```sh
npx expo start --web
```
您的应用将运行在 `http://localhost:8081`。请保持这个终端窗口打开。
使用 `mkcert` 为 localhost 生成证书。在新终端窗口中，从项目根目录运行以下命令：
```sh
mkcert localhost
```
> **提示**：请确保在安装 `mkcert` 后运行 `mkcert -install` 以安装本地证书颁发机构（CA）。
这将在您的项目根目录中生成两个已签名的证书文件：`localhost.pem`（证书）和 `localhost-key.pem`（私钥）。
在您的项目根目录中运行以下命令以启动代理：
```sh
npx local-ssl-proxy --source 443 --target 8081 --cert localhost.pem --key localhost-key.pem
```
> **提示**：[`local-ssl-proxy`](https://github.com/cameronhunter/local-ssl-proxy) 是一个代理工具，它会创建一个代理服务器，将 443 端口的 HTTPS 流量转发到您位于 8081 端口的 Expo 开发服务器。
这将创建一个代理，把 443 端口的 HTTPS 流量转发到您位于 8081 端口的 Expo 开发服务器。
在浏览器中打开 `https://localhost` 以访问您的应用。您的 Expo 应用现在已通过 HTTPS 运行。
---
---
title: Metro 打包器
description: 了解可以自定义的不同 Metro 打包器配置。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/customizing-metro/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# Metro 打包器
了解可以自定义的不同 Metro 打包器配置。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
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
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 要求在启动打包器之前，必须显式定义源代码和资源的所有扩展名。这可以通过在 Metro 配置中添加 `resolver.sourceExts` 和 `resolver.assetExts` 选项来实现。默认情况下，包含以下扩展名：
- [`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
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
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
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` 这样的基于转换的系统，则需要清除缓存才能看到应用的更改。
[自定义 Metro 解析](/versions/latest/config/metro#custom-resolving) — 了解项目中更高级的 Metro 解析方式。
## 包拆分
Expo CLI 会根据异步导入（仅限 web）自动拆分包。
这种技术可与 Expo Router 一起使用，根据 **app** 目录中的路由文件自动拆分包。它只会加载当前路由所需的代码，并推迟加载额外的 JavaScript，直到用户导航到其他页面。有关更多信息，请参阅 [异步路由](/router/web/async-routes)。
## Tree shaking
[Tree shaking](/guides/tree-shaking) — 了解 Expo CLI 如何优化生产环境的 JavaScript 包。
## 压缩
[Minifying JavaScript](/guides/minify) — 了解如何在 Expo CLI 中使用 Metro 打包器自定义 JavaScript 压缩过程。
## 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 支持
修改你的 [应用配置](/workflow/configuration)，通过 `expo.web.bundler` 字段启用该功能：
```json
{
"expo": {
"web": {
"bundler": "metro"
}
}
}
```
#### 开发
要启动开发服务器，请运行以下命令：
```sh
npx expo start --web
```
或者，在 Expo CLI 终端 UI 中按 W。
#### 静态文件
Expo 的 Metro 实现支持通过将静态文件放在根目录 **public/** 中，由开发服务器提供托管。这与许多其他 Web 框架类似。
使用 `npx expo export` 导出时，**public** 目录中的内容会被复制到 **dist/** 目录中。这意味着你的应用可以按相对于主机 URL 的路径去获取这些资源。最常见的例子是 **public/favicon.ico**，网站会用它来渲染标签页图标。
你可以通过在项目中创建 **public/index.html** 文件来覆盖 Metro web 中默认的 **index.html**。
未来，这将通过 EAS Update 托管在所有平台上通用。目前，此功能仅限 web，并且基于原生应用所使用的静态主机，例如，旧版 Expo 服务更新不支持此功能。
> **警告** 某些路径（如 `/assets`）被 Metro 保留。避免将文件放在 **public/assets/** 或其他保留路径中。有关完整列表，请参阅 [保留路径](/router/reference/reserved-paths)。
## TypeScript
Expo 的 Metro 配置支持项目 **tsconfig.json**（或 **jsconfig.json**）文件中的 `compilerOptions.paths` 和 `compilerOptions.baseUrl` 字段。这使项目支持绝对导入和别名。有关更多信息，请参阅 [TypeScript](/guides/typescript) 指南。
此功能在裸项目中需要额外设置。有关更多信息，请参阅 [Metro 设置指南](/versions/latest/config/metro#bare-workflow-setup)。
## CSS
[Metro web CSS 指南](/versions/latest/config/metro#css) — 了解如何在由 Expo CLI 和 Metro 打包器打包的网站中使用 CSS。
---
---
title: 使用 Expo Atlas 和 Lighthouse 分析 JavaScript bundle
description: 了解如何使用 Expo Atlas 和 Lighthouse 提升 Expo 应用和网站的生产环境 JavaScript bundle 大小。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/analyzing-bundles/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 使用 Expo Atlas 和 Lighthouse 分析 JavaScript bundle
了解如何使用 Expo Atlas 和 Lighthouse 提升 Expo 应用和网站的生产环境 JavaScript bundle 大小。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
不同平台的打包性能各不相同。例如，Web 浏览器不支持预编译字节码，因此 JavaScript 包的大小对于提升启动时间和性能很重要。包越小，下载和解析就越快。
## 使用 Expo Atlas 分析包大小
项目中使用的库会影响生产环境 JavaScript 包的大小。你可以使用 [Expo Atlas](https://github.com/expo/expo-atlas#readme) 来可视化生产包，并找出哪些库对包大小有贡献。
### 在 `npx expo start` 中使用 Atlas
你可以在本地开发服务器中使用 Expo Atlas。这种方法允许在你修改项目中的任何代码时，Atlas 自动更新。
一旦你的应用在 Android、iOS 和/或 web 上通过本地开发服务器运行起来，你就可以使用 shift + m，通过 [开发工具插件菜单](/debugging/devtools-plugins#using-a-dev-tools-plugin) 打开 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
```
### 将 Expo Atlas 与 `npx expo export` 一起使用
在为你的应用或 EAS Update 生成生产包时，你也可以使用 Expo Atlas。Atlas 会在导出期间生成一个 **.expo/atlas.jsonl** 文件，你可以在没有访问项目的情况下共享并打开它。
```sh
EXPO_ATLAS=true npx expo export
npx expo-atlas .expo/atlas.jsonl
```
你也可以使用 `--platform` 选项指定要分析的平台。Expo Atlas 只会收集已导出平台的数据。
### 分析转换后的模块
在 Atlas 中，你可以按住 ⌘ Cmd 并点击图中的节点，查看转换后的模块详情。此功能可帮助你了解模块是如何被 Babel 转换的，它导入了哪些模块，以及哪些模块导入了它。你可以借此沿着依赖图追踪模块的来源。
## 使用 source-map-explorer 分析包大小
> **SDK 50 及更早版本** 的替代方法。
如果你使用的是 SDK 50 或更低版本，可以使用 [`source-map-explorer`](https://www.npmjs.com/package/source-map-explorer) 库来可视化并分析生产环境 JavaScript 包。
要使用 source map explorer，请运行以下命令进行安装：
```sh
npm i --save-dev source-map-explorer
```
在 **package.json** 中添加一个脚本来运行它。根据你使用的平台或 SDK，你可能需要调整输入路径。为简洁起见，以下示例假设项目使用的是 Expo SDK 50，并且不使用 Expo Router `server` 输出。
```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 的 web `server` 输出，那么请使用以下命令来映射 web 包：
```sh
npx source-map-explorer 'dist/client/_expo/static/js/web/*.js' 'dist/client/_expo/static/js/web/*.js.map'
```
Web 包会输出到 **dist/client** 子目录，以防止将服务器代码暴露给客户端。
导出你的生产环境 JavaScript 包，并包含 `--source-maps` 标志，这样 source map explorer 就可以读取 source map。对于使用 Hermes 的原生应用，你可以使用 `--no-bytecode` 选项来禁用字节码生成。
```sh
npx expo export --source-maps --platform web
npx expo export --source-maps --platform ios --no-bytecode
```
此命令会在输出中显示 JavaScript 包和 source map 的路径。在下一步中，你将把这些路径传递给 source map explorer。
> 避免将 source map 发布到生产环境，因为它们可能同时带来安全问题和性能问题（浏览器会下载很大的映射文件）。
运行脚本来分析你的包：
```sh
npm run analyze:web
```
运行该命令时，你可能会看到以下错误：
```text
你必须通过调用 SourceMapConsumer.initialize({ 'lib/mappings.wasm': ... }) 来提供 lib/mappings.wasm 的 URL，然后才能使用 SourceMapConsumer
```
这很可能是由于 `source-map-explorer` 在 Node.js 18 及以上版本中的一个[已知问题](https://github.com/danvk/source-map-explorer/issues/247)。要解决此问题，请在运行 analyze 脚本之前设置环境变量 `NODE_OPTIONS=--no-experimental-fetch`。
你可能会遇到类似 `Unable to map 809/13787 bytes (5.87%)` 的警告。这是因为 source map 通常会排除打包器运行时代码定义（例如，`__d(() => {}, [])`）。这个数值是恒定的，不必担心。
## Lighthouse
Lighthouse 是了解你的网站速度、可访问性和性能表现的绝佳方式。你可以在 Chrome 的 **Audit** 选项卡中测试你的项目，或者使用 [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 --view
```
---
---
title: Tree shaking 和代码移除
description: 了解 Expo CLI 如何优化生产环境的 JavaScript bundle。
platforms: ['android', 'ios', 'web', 'tvos']
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/tree-shaking/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# Tree shaking 和代码移除
了解 Expo CLI 如何优化生产环境的 JavaScript bundle。
Android, iOS, tvOS, Web
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
Tree shaking（也称为 _死代码移除_）是一种从生产包中移除未使用代码的技术。Expo CLI 采用多种技术，包括 [压缩](/guides/minify)，通过移除未使用的代码来提升启动速度。
## 平台摇树
Expo CLI 在应用打包时采用一种称为 **平台摇树** 的流程，它会为每个平台（Android、iOS、web）创建独立的包。它会确保某段代码只在一个平台上使用，并从其他平台中移除。
任何基于 `react-native` 中的 `Platform` 模块进行条件判断的代码，都会从其他平台中移除。不过，这种排除仅适用于在每个文件中直接从 react-native 导入 `Platform.select` 和 `Platform.OS` 的情况。如果它们通过其他模块重新导出，则在不同平台的打包过程中不会被移除。
例如，考虑以下转换输入：
```js
import { Platform } from 'react-native';
if (Platform.OS === 'ios') {
console.log('Hello on iOS');
}
```
生产包会移除基于平台的条件判断：
```js
在 Android 上为空
```
```js
console.log('Hello on iOS');
```
这种优化仅在生产环境中生效，并且按文件级别运行。如果你通过其他模块重新导出 `Platform.OS`，它就不会从生产包中移除。
可以使用 `process.env.EXPO_OS` 来检测 JavaScript 被打包到哪个平台（运行时无法更改）。由于 Metro 在依赖解析之后会对代码进行压缩，这个值不支持平台摇树式导入。
## 移除仅开发环境代码
在你的项目中，可能会有一些用于辅助开发流程的代码。它应该从生产包中排除。要处理这些场景，请使用 `process.env.NODE_ENV` 环境变量或非标准的 `__DEV__` 全局布尔值。
例如，以下代码片段会从生产包中移除：
```js
if (process.env.NODE_ENV === 'development') {
console.log('Hello in development');
}
if (__DEV__) {
console.log('Another development-only conditional...');
}
```
在 _常量折叠_ 之后，这些条件可以被静态求值：
```js
if ('production' === 'development') {
console.log('Hello in development');
}
if (false) {
console.log('Another development-only conditional...');
}
```
这些不可达条件会在 [压缩](/guides/minify) 过程中被移除：
```js
空文件
```
为了提升速度，Expo CLI 只会在生产构建中执行代码消除。上面代码片段中的条件判断在开发构建中会被保留。
## 自定义代码移除
`EXPO_PUBLIC_` 环境变量会在压缩过程之前被内联。这意味着它们可以用来从生产包中移除代码。例如：
```js
EXPO_PUBLIC_DISABLE_FEATURE=true;
```
```js
if (!process.env.EXPO_PUBLIC_DISABLE_FEATURE) {
console.log('Hello from the feature!');
}
```
经过 `babel-preset-expo` 之后，上面的输入代码片段会被转换为以下内容：
```js
if (!'true') {
console.log('Hello from the feature!');
}
```
然后，上面的代码片段会被压缩，从而移除未使用的条件判断：
```js
// 空文件
```
- 该系统不适用于服务器代码，因为环境变量不会在服务器包中内联。
- 库作者不应使用 `EXPO_PUBLIC_` 环境变量，因为出于安全原因，它们仅在应用代码中运行。
## 移除服务器代码
通常会使用 `typeof window === 'undefined'` 来有条件地为服务端和客户端环境启用或禁用代码。
`babel-preset-expo` 在为服务器环境打包时，会将 `typeof window === 'undefined'` 转换为 `true`。默认情况下，在为 web 客户端环境打包时，这个检查保持不变。这个转换在开发和生产环境中都会运行，但只会在生产环境中移除条件 `require`。
你可以通过传入 `{ minifyTypeofWindow: true }` 来配置 `babel-preset-expo` 以启用此转换。 默认情况下，即使在 web 环境中，此转换也保持禁用，因为 web worker 没有 `window` 全局对象。
```js
if (typeof window === 'undefined') {
console.log('Hello on the server!');
}
```
上一节中的输入代码在为服务器环境打包时，会在 `babel-preset-expo` 之后转换为以下代码片段（API 路由、服务端渲染）：
```js
if (true) {
console.log('Hello on the server!');
}
```
为 web 或原生应用打包客户端代码时，不会替换 `typeof window`，除非设置了 `minifyTypeOfWindow: true`：
```js
if (typeof window === 'undefined') {
console.log('Hello on the server!');
}
```
对于服务器环境，上面的代码片段随后会被压缩，从而移除未使用的条件判断：
```js
console.log('Hello on the server!');
```
```js
if (typeof window === 'undefined') {
console.log('Hello on the server!');
}
// 空文件
```
## React Native web 导入
`babel-preset-expo` 为 `react-native-web` 的 barrel 文件提供了内置优化。如果你直接使用 ESM 导入 `react-native`，那么该 barrel 文件会从生产包中移除。
如果你使用静态 `import` 语法导入 `react-native`，barrel 文件会被移除。
```js
import { View, Image } from 'react-native';
```
```js
import View from 'react-native-web/dist/exports/View';
import Image from 'react-native-web/dist/exports/Image';
```
## 移除未使用的导入和导出
> [实验性](/more/release-statuses#experimental) 功能，适用于 SDK 52 及更高版本。
你可以以实验方式启用支持，自动移除模块之间未使用的导入和导出。这对于加快原生 OTA 下载以及优化 web 性能很有用，因为 JavaScript 必须使用标准 JavaScript 引擎进行解析和执行。
考虑下面的示例代码：
```js
import { ArrowUp } from './icons';
export default function Home() {
return ;
}
```
```js
export function ArrowUp() {
/* ... */
}
export function ArrowDown() {
/* ... */
}
export function ArrowRight() {
/* ... */
}
export function ArrowLeft() {
/* ... */
}
```
由于在 `index.js` 中只使用了 `ArrowUp`，生产包会移除 `icons.js` 中所有其他组件。
```js
export function ArrowUp() {
/* ... */
}
```
该系统可扩展到自动优化应用中所有平台上的 `import` 和 `export` 语法。虽然这会生成更小的包，但处理 JS 仍然需要时间和内存，因此请避免导入数百万个模块。
- Tree-shaking 只在生产包中运行，并且只能作用于使用 `import` 和 `export` 语法的模块。使用 `module.exports` 和 `require` 的文件不会被 tree-shaking。
- 避免添加诸如 `@babel/plugin-transform-modules-commonjs` 之类的 Babel 插件，因为它们会将 `import`/`export` 语法转换为 CJS。这会破坏你项目中的 tree-shaking。
- 被标记为有副作用的模块不会从依赖图中移除。
- `export * from "..."` 会被展开并优化，除非导出使用了 `module.exports` 或 `exports`。
- Expo SDK 中的所有模块都以 ESM 形式发布，并且可以被彻底 tree-shaken。
## 启用 tree shaking
> [实验性](/more/release-statuses#experimental) 功能，适用于 SDK 52 及更高版本。
确保启用 `experimentalImportSupport`，并确保你的应用构建和运行符合预期。
> **注意**：从 SDK 54 及更高版本开始默认启用。
如何在较旧的 SDK 版本中启用 import 支持？
```js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.getTransformOptions = async () => ({
transform: {
experimentalImportSupport: true,
},
});
module.exports = config;
```
实验性 import 支持使用了 `@babel/plugin-transform-modules-commonjs` 插件的自定义版本。这会大幅减少解析数量并简化输出包。此功能可以与 `inlineRequires` 一起使用，以实验性地进一步优化你的包。
打开环境变量 `EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1`，以便在整个图创建完成之前保留模块。在继续之前，请确保在启用此功能的生产环境中，你的应用构建和运行符合预期。
```sh
EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1
```
这只会在生产模式下使用。
打开环境变量 `EXPO_UNSTABLE_TREE_SHAKING=1` 来启用该功能。
```sh
EXPO_UNSTABLE_TREE_SHAKING=1
```
这只会在生产模式下使用。
以生产模式打包你的应用，以查看 tree shaking 的效果。
```sh
npx expo export
```
此功能仍然非常实验性，因为它改变了 Metro 打包代码的基础结构。默认情况下，Metro 会按需并以惰性方式打包所有内容，以确保尽可能快的开发速度。相比之下，tree shaking 需要将某些转换延迟到整个包创建完成之后。这意味着可缓存的代码会更少，不过这通常没问题，因为 tree shaking 只是生产环境功能，而且生产包通常不会使用转换缓存。
## 条带文件
> [实验性地](/more/release-statuses#experimental) 在 SDK 52 及更高版本中可用。
借助 Expo 树摇，星号导出会根据使用情况自动展开并进行摇树优化。例如，考虑以下代码片段：
```js
export * from './icons';
```
优化过程会遍历 `./icons` 并将导出添加到当前模块中。如果这些导出未被使用，它们将从生产包中移除。
```js
export { ArrowRight, ArrowLeft } from './icons';
```
这将按照标准的树摇规则进行优化。如果你只导入 `ArrowRight`，那么 `ArrowLeft` 将从生产包中移除。
如果星号导出引入了歧义导出，例如 `module.exports.ArrowUp` 或 `exports.ArrowDown`，那么优化过程不会展开该星号导出，并且条带文件中的任何导出都不会被移除。你可以使用 [Expo Atlas](/guides/analyzing-bundles#analyzing-bundle-size-with-atlas) 来检查展开后的导出。
你可以将此策略用于像 `lucide-react` 这样的库，以移除应用中未使用的所有图标。
## 递归优化
> [实验性地](/more/release-statuses#experimental) 在 SDK 52 及更高版本中可用。
Expo 会通过对图进行穷尽式递归来优化模块，以查找未使用的导入。考虑以下代码片段：
```js
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
{
"name": "library",
"sideEffects": ["./src/*.js"]
}
```
副作用会阻止未使用模块的移除，并禁用模块内联，以确保 JS 代码按预期顺序运行。如果副作用为空，或仅包含注释和指令（`"use strict"`、`"use client"` 等），它们将被移除。
当启用 Expo 树摇时，你可以安全地在生产包中为 **metro.config.js** 启用 `inlineRequires`。这会在模块被求值时延迟加载它们，从而加快启动时间。如果不使用 Expo 树摇，请避免使用此功能，因为它会以可能改变副作用执行顺序的方式重新排列模块。
```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
import { doSomething } from './dev-only';
if (process.env.NODE_ENV === 'development') {
doSomething();
}
```
在这两种情况下，整个模块在生产包中都将为空。
---
---
title: 压缩 JavaScript
description: 了解如何在 Expo CLI 中使用 Metro bundler 自定义 JavaScript 压缩流程。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/minify/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 压缩 JavaScript
了解如何在 Expo CLI 中使用 Metro bundler 自定义 JavaScript 压缩流程。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
压缩是一个优化构建步骤。它会从源代码中移除不必要的字符，例如压缩空白字符、删除注释以及缩短静态操作。这个过程可以减小最终体积并提升加载速度。
## Expo CLI 中的压缩
在 Expo CLI 中，压缩会在生产导出期间对 JavaScript 文件执行（当运行 `npx expo export`、`npx expo export:embed`、`eas build` 等命令时）。
例如，考虑项目中的以下代码片段：
```js
// 这条注释会被移除
console.log('a' + ' ' + 'long' + ' string' + ' to ' + 'collapse');
```
这段代码会被 Expo CLI 压缩为：
```js
console.log('a long string to collapse');
```
> **提示：** 可以通过使用 `/** @preserve */` 指令来保留注释。
Expo CLI 的默认压缩对大多数项目来说已经足够。不过，你可以自定义压缩器，以优化速度或移除额外功能，例如日志。
## 移除 console 日志
你可以从生产构建中移除 console 日志。使用 Terser 压缩器配置中的 `drop_console` 选项。
```js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.transformer.minifierConfig = {
compress: {
// 下面的选项会移除生产环境中的所有 console 日志语句。
drop_console: true,
},
};
module.exports = config;
```
如果你希望保留某些日志，也可以传入一个要移除的 console 类型数组。例如：`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)）。
要在项目中安装 Terser，请运行以下命令：
```sh
yarn add --dev metro-minify-terser
```
使用 `transformer.minifierPath` 将 Terser 设置为压缩器，并将 [`terser` 选项](https://github.com/terser/terser#compress-options) 传入 `transformer.minifierConfig`。
```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
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)：
要在项目中安装 Uglify，请运行以下命令：
```sh
yarn add --dev metro-minify-uglify
```
> 请确保 `metro-minify-uglify` 的版本与你项目中的 `metro` 版本一致。
使用 `transformer.minifierPath` 将 Uglify 设置为压缩器，并将 [选项](https://github.com/mishoo/UglifyJS#compress-options) 传入 `transformer.minifierConfig`。
```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;
```
---
---
title: 为什么选择 Metro？
description: 了解为什么 Metro 是 React Native 中通用打包的未来，以及它如何帮助开发者。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/why-metro/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 为什么选择 Metro？
了解为什么 Metro 是 React Native 中通用打包的未来，以及它如何帮助开发者。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
[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 的一个特性首次[引入](https://reactnative.dev/blog/2019/09/18/version-0.61)。React Web 社区在次年通过 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 Server Components 实现数据获取、流式传输、React Suspense、服务端渲染以及构建时静态渲染。可在 React Conf 2024 的 [Universal React Server Components](https://www.youtube.com/watch?v=djhEgxQf3Kw) 演讲中了解更多。
Expo 团队与 Meta 合作，为 Expo Router 开发 Metro，添加了诸如[基于文件的路由](/develop/app-navigation)、[Web 支持](/guides/customizing-metro#web-support)、[包拆分](/guides/customizing-metro#bundle-splitting)、[tree shaking](/guides/tree-shaking)、[CSS](/versions/latest/config/metro#css)、[DOM 组件](/guides/dom-components)、服务端组件以及 [API 路由](/router/web/api-routes)等功能。
## 大规模实战检验
世界上几乎每个 React Native 应用都在使用 Metro，这使它成为一个经过大规模项目实战检验的解决方案。无论是个人开发者还是大型公司，它都同样适用。Metro 专为处理 Meta 的大规模应用而设计，这也是它具备通过 Watchman 进行原生文件监视以及[共享远程缓存](https://metrobundler.dev/docs/caching)等特性的原因。
## 按需处理
在开发过程中，Metro 在被请求之前不会执行任何平台相关工作。这使开发者能够在大型项目上工作，而无需为所支持的平台数量付出性能成本。结合激进的缓存和[异步路由](/router/web/async-routes)，开发者可以逐步打包当前正在处理的应用部分。
## 多维度
与传统打包器会创建多个实例来打包服务端和客户端代码不同，Metro 在不同平台和环境之间（服务端、客户端、DOM 组件）最大化资源复用。这种架构非常适合多平台和服务端开发。
## 可复用的转换记忆化
Metro 是增量式的，并且可以创建可缓存的转换产物，这些产物可以在不同机器之间复用。这使大型团队能够复用远程构建器的工作成果，这也是 Meta 在所有大型项目中使用的一种技术。
## 针对自定义运行时优化
虽然其他打包器是围绕网页浏览器的静态规范设计的，但 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 parser（WebAssembly）解析为与 Babel 兼容的格式。
- AST 转换由 Babel 完成。这最大化了开发者的自定义能力。
- 压缩在原生平台上使用 Hermes，在 Web 上使用 Terser（可选支持 ESBuild）。
- CSS 解析和压缩使用 [LightningCSS](https://lightningcss.dev/)（Rust）完成。
这种方式与 Meta 和社区工具保持一致，同时也让开发者更容易进行调试、性能分析和补丁修改。
---
---
title: 使用 Expo 与现有 React Native 应用的概览
description: 了解如何在现有 React Native 应用中使用 Expo 工具和服务。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/bare/overview/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 使用 Expo 与现有 React Native 应用的概览
了解如何在现有 React Native 应用中使用 Expo 工具和服务。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
如果你有一个不使用任何 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 来构建和维护模块有多么容易。
还有很多内容值得探索，下面的链接将帮助你了解可用的选项。
## 渐进式采用步骤
下面是四个建议的渐进式采用阶段。这些阶段通常从快速改进开发者体验开始，逐步过渡到更显著的工作流和代码库优化。
只有第一阶段——先决条件——是其他阶段所必需的。按照其说明完成后，你可以直接跳到最符合你采用 Expo 目标的工具和服务。
### 先决条件
以下这些初始步骤是后续采用 Expo 工具和服务所必需的：
[安装 Expo 模块](/bare/installing-expo-modules) — 要解锁 Expo 功能，你需要在现有的 React Native 项目中安装 expo 包。此指南同时提供自动和手动安装步骤。 — expo
[使用 Expo CLI](/bare/using-expo-cli) — 迁移到 Expo CLI 可以直接替换 @react-native-community/cli。它与所有 Expo 工具和服务完全兼容。此指南解释了其优势，并提供了在安装 expo 包后启动开发服务器的编译命令。 — @react-native-community/cli — expo
### 快速见效
以下内容有助于改善开发体验，并且需要进行配置：
[使用 Expo SDK](/versions) — 使用 Expo SDK 提供的众多库之一。Expo SDK 是一套广泛的库，提供对原生 API 的访问。
[安装 expo-dev-client](/bare/install-dev-builds-in-bare) — expo-dev-client 为你的调试版应用提供类似 Expo Go 的应用启动器界面。了解如何在你现有的 React Native 项目中安装和配置它。 — expo-dev-client
[编写原生模块](/modules/overview) — 使用 Expo Modules API 通过 Swift 和 Kotlin 编写原生模块。
[原生项目升级助手](/bare/upgrade) — 按文件查看你需要对原生项目进行的所有更改的差异，以便将它们升级到下一个 Expo SDK 和 React Native 版本。
### 新工作流
一旦你的应用安装了 `expo` 包，你就可以通过单个命令将应用提交到应用商店，或者配置 `expo-updates` 库来管理应用代码的远程更新：
[应用分发](/distribution/introduction) — 通过一个命令构建并将你的应用提交到应用商店。
[安装 expo-updates](/bare/installing-updates) — 了解如何安装和配置 expo-updates 来管理远程更新并启用 PR 预览。 — expo-updates
### 新思维方式
以下内容有助于提升项目的长期可维护性、原生代码维护以及更轻松的升级：
[采用 Prebuild](/guides/adopting-prebuild) — 了解如何通过根据配置按需生成原生项目，来简化它们的维护。
[Expo Router](/router/introduction) — Expo Router 是一个基于文件的路由库，提供诸如有组织的导航层级、自动深度链接支持等优势。
## 常见问题
在我现有的 React Native 项目中采用 Expo 需要多长时间？
采用 Expo 不必一步完成。你可以从_快速见效_开始，然后再转向更复杂的部分。你也可以根据项目最需要的内容，选择性地采用你想要的功能。
在我的 React Native 应用中使用 Expo 我能获得什么？
在你现有的 React Native 应用中采用 Expo 工具，可以帮助你使用 [Expo SDK](/versions/latest) 更快开发，通过 [CNG](/workflow/continuous-native-generation) 简化原生代码维护和升级，通过 [EAS Update](/eas-update/introduction) 更快部署，以及更多功能。
谁在使用 Expo？
Expo 被全球顶级公司使用，这些公司服务于数百万最终用户。更多信息请参阅我们的 [Expo 案例展示](https://expo.dev/customers)。
采用 Expo 会对我应用的体积产生什么影响？
`expo` 包体积很小，因为它只包含每个应用都需要的最小模块集，以及自动链接基础设施和其他内置的 Expo SDK 库。有关如何确定应用实际大小的更多信息，请参阅[了解应用大小](/distribution/app-size)。
为什么 React Native 推荐使用 Expo？
大多数 React Native 开发者在构建应用时都会解决常见问题，例如实现导航、访问原生 API、升级到新版本等。这需要使用一组特定的工具和库来构建和维护你的应用——这意味着你正在创建自己的框架。
Expo 通过提供一组基础构件并帮助你（开发者）专注于构建应用来解决这些问题。它还提供了更快迭代开发的工具。更多信息请参阅[为什么 React Native 推荐使用框架](https://reactnative.dev/blog/2024/06/25/use-a-framework-to-build-react-native-apps)。
我是否必须移除原生项目才能使用 Expo？
默认情况下，使用 `create-expo-app` 创建的 Expo 项目会使用[持续原生生成（CNG）](/workflow/continuous-native-generation)，并且不包含 **android** 和 **ios** 原生目录。如果你在现有的 React Native 应用中逐步采用 Expo，就不需要移除这些目录。你可以使用 `npx expo run:[android|ios]` 作为 `@react-native-community/cli` 提供的命令的替代方案，在本地编译你的应用，并保留原生项目的配置。
我在使用 CodePush。还能继续和 Expo 一起使用吗？
CodePush 将于 2025 年 3 月退役，并且与 React Native 的新架构不兼容，因此从长远来看，我们建议切换到 EAS Update 来管理应用代码的远程更新。不过，你今天就可以在启用了 CodePush 的应用中开始使用 Expo 工具，包括 Expo SDK、Expo CLI、EAS Build 等。
我必须使用 EAS 来构建吗？
[Expo Application Services (EAS)](/eas) 是深度集成的云服务，适用于 Expo 和 React Native 应用，提供构建、测试和部署应用的工具。
虽然我们建议使用 EAS 以便与你的团队成员顺畅协作并快速分发，但你也可以在本地、CI 上，或者你喜欢的任何其他方式编译应用。
我可以在代码中安装第三方原生库吗？
可以，你可以安装并使用需要原生项目（**android** 和 **ios**）配置的第三方库，或者在[开发构建](/workflow/overview#development-builds)中提供[配置插件](/config-plugins/introduction)的库。更多信息请参阅[使用第三方库](/workflow/using-libraries#third-party-libraries)。
我在使用 React Navigation。我必须使用 Expo Router 吗？
你可以继续在项目中使用任何导航库。不过，我们推荐使用 Expo Router，以获得[此处所描述](/router/introduction)的所有优势。
---
---
title: 在现有 React Native 项目中安装 Expo 模块
description: 了解如何准备你的现有 React Native 项目，以安装和使用任何 Expo 模块。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/bare/installing-expo-modules/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 在现有 React Native 项目中安装 Expo 模块
了解如何准备你的现有 React Native 项目，以安装和使用任何 Expo 模块。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
要在你的应用中使用 Expo 模块，你需要安装并配置 `expo` 包。
`expo` 包体积很小；它只包含几乎每个应用都需要的一小组基础包，以及其他 Expo SDK 包所依赖的模块和自动链接基础设施。只要 `expo` 包已在你的项目中安装并配置好，你就可以使用 `npx expo install` 来添加 SDK 中的任何其他 Expo 模块。
根据你[初始化项目](/bare/overview)的方式不同，你可以通过两种方式安装 Expo 模块：[自动](/bare/installing-expo-modules#automatic-installation)或[手动](/bare/installing-expo-modules#manual-installation)。
## 自动安装
要安装并使用 Expo 模块，最简单的上手方式是使用 `install-expo-modules` 命令。
```sh
npx install-expo-modules@latest
```
- ✓ **当命令成功执行时**，你就可以在应用中添加任意 Expo 模块了！更多信息请继续查看[用法](/bare/installing-expo-modules#usage)。
- ✗ **如果命令失败**，请按照手动安装说明进行操作。以编程方式更新代码可能比较棘手，如果你的项目与默认的 React Native 项目有较大差异，那么你需要执行手动安装，并将此处的说明适配到你的代码库中。
## 手动安装
以下说明适用于在 React Native 0.83 中安装最新版 Expo 模块。对于更早的版本，请查看[native upgrade helper](/bare/upgrade)以了解这些文件是如何定制的。
```sh
npm install expo
```
安装完成后，请根据下面的差异内容对项目进行相应修改，以在你的项目中配置 Expo 模块。这预计需要大约五分钟，并且根据你的项目定制程度，可能需要稍作调整。
### Android 配置
### iOS 配置
你也可以选择在 **AppDelegate.swift** 中添加额外的 delegate 方法。有些库可能需要它们，因此除非你有充分理由不添加，否则建议添加。[查看 AppDelegate.swift 中的 delegate 方法](https://github.com/expo/expo/blob/sdk-54/templates/expo-template-bare-minimum/ios/HelloWorld/AppDelegate.swift#L24-L42)。
保存所有更改，并在 Xcode 中将 iOS Deployment Target 更新为 `iOS 15.1`：
- 在 Xcode 中打开 **your-project-name.xcworkspace**，在左侧边栏中选择你的项目。
- 选择 **Targets** > **your-project-name** > **Build Settings** > **iOS Deployment Target**，并将其设置为 `iOS 15.1`。
最后一步是重新安装项目的 CocoaPods，以引入我们在 **Podfile** 中添加的 `use_expo_modules!` 指令所检测到的 Expo 模块：
```sh
npx pod-install
npx expo run:ios
```
### 配置 Expo CLI 以在 Android 和 iOS 上进行打包
我们建议使用 Expo CLI 及相关工具配置来打包应用的 JavaScript 代码和资源文件。这样会增加对在 **package.json** 中使用 `"main"` 字段并使用 [Expo Router](/router/introduction) 库的支持。未使用 Expo CLI 进行打包可能会导致意外行为。[了解更多关于 Expo CLI 的信息](/bare/using-expo-cli)。
在 babel.config.js 中使用 babel-preset-expo
在 metro.config.js 中扩展 expo/metro-config
配置 Android 项目以使用 Expo CLI 打包
配置 iOS 项目以使用 Expo CLI 打包
将 Xcode 中 **Build Phases** > **Bundle React Native code and images** 下的 shell 脚本替换为以下内容：
```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
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) - 提供对 manifest 的访问。
- [`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) - 在开发你的应用时防止设备进入睡眠状态。该模块是可选的，并且可以安全移除。
要排除这些模块中的任何一个，请参阅以下关于[从自动链接中排除模块](/bare/installing-expo-modules#excluding-specific-modules-from-autolinking)的指南。
### 从自动链接中排除特定模块
如果你需要排除你没有使用、但由其他依赖安装进来的 Expo 模块中的原生代码，你可以在 **package.json** 中使用 [`expo.autolinking.exclude`](/modules/autolinking#exclude) 属性：
```json
{
"name": "...",
"dependencies": {},
"expo": {
"autolinking": {
"exclude": ["expo-keep-awake"]
}
}
}
```
---
---
title: 从 React Native CLI 迁移到 Expo CLI
description: 了解如何将任何 React Native 项目从 React Native CLI（@react-native-community/cli）迁移到 Expo CLI。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/bare/using-expo-cli/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 从 React Native CLI 迁移到 Expo CLI
了解如何将任何 React Native 项目从 React Native CLI（@react-native-community/cli）迁移到 Expo CLI。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
要从 React Native CLI（`npx @react-native-community/cli@latest init`）迁移到 Expo CLI，你需要安装 `expo` 包，其中包含 Expo Modules API 和 Expo CLI。本指南涵盖安装步骤、使用 Expo CLI 的优势，以及迁移到 Expo CLI 后如何编译和运行你的项目。
强烈建议在使用其他 Expo 工具时使用 Expo CLI。许多工具都需要它，例如 EAS Update、Expo Router 和 expo-dev-client；如果没有它，其他功能也可能无法正常工作。
## 安装 `expo` 包
在大多数情况下，只需在项目目录中执行以下命令来安装该包即可：
```sh
npx install-expo-modules@latest
```
有关详细的安装指南，请参阅[安装 Expo 模块](/bare/installing-expo-modules)。
> 安装 `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
与 `@react-native-community/cli` 中类似的命令相比，Expo CLI 命令提供了多项优势，包括：
- 按下 j 即可立即使用 Hermes 调试器。
- 调试器自带 [React Native DevTools](/debugging/tools#debugging-with-react-native-devtools)。
- 支持使用 [`expo prebuild`](/more/glossary-of-terms#prebuild) 进行 [Continuous Native Generation (CNG)](/workflow/continuous-native-generation) 用于升级、白标化、轻松设置第三方包，以及通过减少代码表面积来提高代码库可维护性。
- 支持通过 [`expo-router`](/router/introduction) 进行基于文件的路由。
- 开发环境中的 [异步打包](/router/web/async-routes)。
- 内置 [环境变量支持](/guides/environment-variables) 和 **.env** 文件集成。
- 可直接在终端中查看原生日志，与 JavaScript 日志并列显示。
- 使用 Expo CLI 专为 React Native 应用构建的 `xcpretty` 风格工具后，原生构建日志格式更佳。例如，在编译 Pod 时，你可以看到它是由哪个 Node 模块引入的。
- [一流的 TypeScript 支持](/guides/typescript)。
- 内置支持 **tsconfig.json** 别名中的 `paths` 和 `baseUrl`，[已集成到 Metro 中](/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 进行静态站点生成。
- 开箱即用地[支持 monorepo](/guides/monorepos)。
- 支持 Expo 工具，例如 [`expo-dev-client`](/develop/development-builds/introduction)、[Expo Updates 协议](/technical-specs/expo-updates-1) 和 [EAS Update](/eas-update/introduction)。
- 使用 `npx expo run:ios` 时会自动执行 `pod install`。
- `npx expo install` 会为知名包选择兼容的依赖版本。
- 运行 `npx expo run:[android|ios]` 和 `npx expo start` 时会自动检测端口。如果默认端口上已有其他应用在运行，则会使用其他端口。
- 在交互式提示中使用 Shift + a 或 Shift + i 可快速选择启动 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` 命令独立启动打包器，可以在 `npx expo run:[android|ios]` 命令中传入 `--no-bundler`。
## 常见问题
我可以在不安装 Expo Modules API 的情况下使用 Expo CLI 吗？
安装 `expo` 包时，`npx install-expo-modules` 也会安装 Expo Modules API。如果你现在想先试用 Expo CLI，而不安装 Expo Modules API，可以使用 `npm install` 安装 `expo` 包，然后配置 **react-native.config.js**，将该包排除在自动链接之外：
```js
module.exports = {
dependencies: {
expo: {
platforms: {
android: null,
ios: null,
macos: null,
},
},
},
};
```
> **注意：** 如果未安装 Expo API Modules，某些功能（例如 `expo-dev-client` 或 `expo-router`）将不可用。
我可以将 prebuild 用于树外平台，例如 macOS 或 Windows 吗？
可以！更多信息请参阅 [Customized Prebuild Example 仓库](https://github.com/byCedric/custom-prebuild-example)。
## 下一步
现在，`expo` 包已经安装并在你的项目中配置完成，你就可以开始使用 Expo CLI 和 SDK 的所有功能了。以下是一些建议的后续步骤，帮助你深入了解：
[Expo CLI 参考](/more/expo-cli) — 了解 Expo CLI 中可用的命令和参数。
[自定义 Metro](/guides/customizing-metro) — 了解如何为你的项目自定义 Metro 打包器配置。
[采用 Prebuild](/guides/adopting-prebuild) — 使用 app.json 自动管理你的原生目录。 — app.json
[使用 Expo SDK](/versions) — 在你的应用中试用 Expo SDK 中的库。
[Expo Router](/router/introduction) — Expo Router 将 Web 上最优秀的路由理念带到原生 Android 和 iOS 应用中。
---
---
title: 在现有的 React Native 项目中安装 expo-updates
description: 了解如何在现有的 React Native 项目中安装和配置 expo-updates。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/bare/installing-updates/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 在现有的 React Native 项目中安装 expo-updates
了解如何在现有的 React Native 项目中安装和配置 expo-updates。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
`expo-updates` 是一个库，可让你的应用管理应用代码的远程更新。它会与已配置的远程更新服务通信，以获取可用更新的信息。本指南说明如何为裸 React Native 项目配置，以便与 [EAS Update](/eas-update/introduction) 一起使用；EAS Update 是一个托管的远程更新服务，提供工具来简化 `expo-updates` 库的安装和配置。
你在项目中使用 Continuous Native Generation（CNG）吗？
你可能在查看错误的指南。要在使用 [CNG](/workflow/continuous-native-generation) 的项目中使用 `expo-updates`，请参阅 [EAS Update “Get started”](/eas-update/getting-started)。
## 先决条件
**必须安装并配置 `expo` 包。** 如果你使用 `npx @react-native-community/cli@latest init` 创建项目，并且没有安装任何其他 Expo 库，那么在继续之前，你需要先[安装 Expo modules](/bare/installing-expo-modules)。
## 安装
开始之前，先安装 `expo-updates`：
```sh
npx expo install expo-updates
```
然后，安装 iOS 的 pods：
```sh
npx pod-install
```
## 配置 expo-updates 库
按照以下各节中的 diff 进行相应更改，以便在项目中配置 `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 会为 EAS Update 服务正确设置此 URL。
如果你想改为设置一个[自定义 `expo-updates` 服务器](https://github.com/expo/custom-expo-updates-server)，请在 **app.json** 中将你的 URL 添加到 `updates.url`。
```diff
"expo": {
"name": "MyApp",
- "updates": {
- "url": "https://u.expo.dev/[your-project-id]"
- }
+ "updates": {
+ "url": "http://localhost:3000/api/manifest"
+ }
}
}
```
### Android
修改 **android/app/build.gradle**，以检查 Expo 文件中的 JS 引擎配置（JSC 或 Hermes）：
修改 **android/app/src/main/AndroidManifest.xml**，添加 `expo-updates` 配置 XML，使其与 **app.json** 的内容一致：
如果使用更新服务器 URL（在同一台机器上运行的自定义非 HTTPS 更新服务器），你需要修改 **android/app/src/main/AndroidManifest.xml**，添加更新服务器 URL 并启用 `usesCleartextTraffic`：
将 Expo 运行时版本字符串键添加到 **android/app/src/main/res/values/strings.xml**：
### iOS
将文件 **Podfile.properties.json** 添加到 **ios** 目录：
```json
{
"expo.jsEngine": "hermes"
}
```
修改 **ios/Podfile**，以检查 Expo 文件中的 JS 引擎配置（JSC 或 Hermes）：
使用 Xcode，将 **Expo.plist** 文件添加到 **ios/your-project/Supporting**，内容如下，以与 **app.json** 的内容保持一致：
```xml
EXUpdatesCheckOnLaunch
ALWAYS
EXUpdatesEnabled
EXUpdatesLaunchWaitMs
0
EXUpdatesRuntimeVersion
1.0.0
EXUpdatesURL
http://localhost:3000/api/manifest
```
## 后续步骤
- 要开始将 EAS Update 与 EAS Build 一起使用，请参阅 EAS Update 的 [Get started](/eas-update/getting-started)。
- 有关如何使用该库的更多信息，请参阅 [`expo-updates` API reference](/versions/latest/sdk/updates)。
- 了解如何直接在本地构建中使用 [EAS Update with a local build directly](/eas-update/standalone-service)。
- 你也可以将 `expo-updates` 与实现了 [Expo Updates protocol](/technical-specs/expo-updates-1) 的自定义服务器一起使用。请参阅 [`custom-expo-updates-server` README](https://github.com/expo/custom-expo-updates-server#readme)。
---
---
title: 在现有 React Native 项目中安装 expo-dev-client
description: 了解如何在现有 React Native 项目中安装并配置 expo-dev-client。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/bare/install-dev-builds-in-bare/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 在现有 React Native 项目中安装 expo-dev-client
了解如何在现有 React Native 项目中安装并配置 expo-dev-client。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
以下指南说明如何在现有 React Native 项目中安装和配置 `expo-dev-client`。
你需要创建一个新项目吗？
如果你是从一个新项目开始，请使用 `with-dev-client` 模板创建它：
```sh
npx create-expo-app -e with-dev-client
```
你的项目中使用 Continuous Native Generation (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)。
## 安装 expo-dev-client
将 `expo-dev-client` 库添加到你的 **package.json** 中：
```sh
npx expo install expo-dev-client
```
如果你的项目磁盘上有一个 **ios** 目录，请运行以下命令以完全安装 `expo-dev-client` 的原生代码：
```sh
npx pod-install
```
如果你的项目没有 **ios** 目录，则可以跳过这一步。
## 配置深度链接
Expo CLI 使用深度链接来启动你的项目；如果你计划在项目中添加自定义深度链接 scheme 后，使用 [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)。
## 构建并安装应用
使用你选择的工具创建应用的调试构建。例如，你可以[在本地使用 Expo CLI](/guides/local-app-development)完成，或者[在云端使用 EAS Build](/develop/development-builds/create-a-build)完成。
---
---
title: 原生项目升级助手
description: 查看你需要对原生项目进行的所有更改的逐文件差异，以将它们升级到下一个 Expo SDK 版本。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/bare/upgrade/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 原生项目升级助手
查看你需要对原生项目进行的所有更改的逐文件差异，以将它们升级到下一个 Expo SDK 版本。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
如果你管理自己的原生项目（以前称为 bare workflow），要[升级到最新的 Expo SDK](/workflow/upgrading-expo-sdk-walkthrough)，你必须对原生项目进行一些更改。找出哪些原生文件发生了变化，以及需要在每个文件中更新什么内容，可能是一个复杂的过程。
以下指南提供了用于比较你项目当前 SDK 版本和你想升级到的目标 SDK 版本之间原生项目文件差异的 diff。你可以根据项目所使用的 `expo` 包版本，使用它们对项目进行修改。本页中的工具与 [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) 类似。不过，它们是围绕使用 Expo 模块及相关工具链的项目设计的。
> 想要完全避免升级原生代码？请查看 [Continuous Native Generation (CNG)](/workflow/continuous-native-generation)，了解 Expo Prebuild 如何在构建前生成你的原生项目。
## 升级原生项目文件
一旦你[升级了 Expo SDK 版本和相关依赖](/workflow/upgrading-expo-sdk-walkthrough#how-to-upgrade-to-the-latest-sdk-version)，请使用下面的 diff 工具了解你需要对原生项目做出的更改，并使其与当前 Expo SDK 版本保持一致。
选择你的**起始 SDK 版本**和**目标 SDK 版本**以查看生成的 diff。然后，通过复制粘贴或手动修改项目文件，将这些更改应用到你的原生项目中。
#### From SDK version:
#### To SDK version:
### Native code changes from SDK 54 to 55
[android/app/build.gradleMODIFIED](#androidappbuildgradle)
```diff
react {
entryFile = file(["node", "-e", "require('expo/scripts/resolveAppEntry')", projectRoot, "android", "absolute"].execute(null, rootDir).text.trim())
reactNativeDir = new File(["node", "--print", "require.resolve('react-native/package.json')"].execute(null, rootDir).text.trim()).getParentFile().getAbsoluteFile()
- hermesCommand = new File(["node", "--print", "require.resolve('react-native/package.json')"].execute(null, rootDir).text.trim()).getParentFile().getAbsolutePath() + "/sdks/hermesc/%OS-BIN%/hermesc"
+ hermesCommand = new File(["node", "--print", "require.resolve('hermes-compiler/package.json', { paths: [require.resolve('react-native/package.json')] })"].execute(null, rootDir).text.trim()).getParentFile().getAbsolutePath() + "/hermesc/%OS-BIN%/hermesc"
codegenDir = new File(["node", "--print", "require.resolve('@react-native/codegen/package.json', { paths: [require.resolve('react-native/package.json')] })"].execute(null, rootDir).text.trim()).getParentFile().getAbsoluteFile()
enableBundleCompression = (findProperty('android.enableBundleCompression') ?: false).toBoolean()
```
[android/app/src/main/AndroidManifest.xmlMODIFIED](#androidappsrcmainandroidmanifestxml)
```diff
-
+
-
-
+
+
-
+
```
[android/app/src/main/java/com/helloworld/MainApplication.ktMODIFIED](#androidappsrcmainjavacomhelloworldmainapplicationkt)
```diff
import com.facebook.react.PackageList
import com.facebook.react.ReactApplication
import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
- import com.facebook.react.ReactNativeHost
import com.facebook.react.ReactPackage
import com.facebook.react.ReactHost
import com.facebook.react.common.ReleaseLevel
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint
- import com.facebook.react.defaults.DefaultReactNativeHost
import expo.modules.ApplicationLifecycleDispatcher
- import expo.modules.ReactNativeHostWrapper
+ import expo.modules.ExpoReactHostFactory
class MainApplication : Application(), ReactApplication {
- override val reactNativeHost: ReactNativeHost = ReactNativeHostWrapper(
- this,
- object : DefaultReactNativeHost(this) {
- override fun getPackages(): List =
- PackageList(this).packages.apply {
- // Packages that cannot be autolinked yet can be added manually here, for example:
- // add(MyReactNativePackage())
- }
- override fun getJSMainModuleName(): String = ".expo/.virtual-metro-entry"
- override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG
- override val isNewArchEnabled: Boolean = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED
- }
- )
- override val reactHost: ReactHost
- get() = ReactNativeHostWrapper.createReactHost(applicationContext, reactNativeHost)
+ override val reactHost: ReactHost by lazy {
+ ExpoReactHostFactory.getDefaultReactHost(
+ context = applicationContext,
+ packageList =
+ PackageList(this).packages.apply {
+ // Packages that cannot be autolinked yet can be added manually here, for example:
+ // add(MyReactNativePackage())
+ }
+ )
+ }
override fun onCreate() {
super.onCreate()
```
[android/gradle/wrapper/gradle-wrapper.propertiesMODIFIED](#androidgradlewrappergradle-wrapperproperties)
```diff
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
- distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip
+ distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
```
[android/gradlewMODIFIED](#androidgradlew)
```diff
#!/bin/sh
#
- # Copyright © 2015-2021 the original authors.
+ # Copyright © 2015 the original authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
```
[ios/HelloWorld/AppDelegate.swiftMODIFIED](#ioshelloworldappdelegateswift)
```diff
- import Expo
+ internal import Expo
import React
import ReactAppDependencyProvider
- @UIApplicationMain
- public class AppDelegate: ExpoAppDelegate {
+ @main
+ class AppDelegate: ExpoAppDelegate {
var window: UIWindow?
var reactNativeDelegate: ExpoReactNativeFactoryDelegate?
reactNativeDelegate = delegate
reactNativeFactory = factory
- bindReactNativeFactory(factory)
#if os(iOS) || os(tvOS)
window = UIWindow(frame: UIScreen.main.bounds)
```
[ios/PodfileMODIFIED](#iospodfile)
```diff
def ccache_enabled?(podfile_properties)
# Environment variable takes precedence
return ENV['USE_CCACHE'] == '1' if ENV['USE_CCACHE']
# Fall back to Podfile properties
podfile_properties['apple.ccacheEnabled'] == 'true'
end
- ENV['RCT_NEW_ARCH_ENABLED'] ||= '0' if podfile_properties['newArchEnabled'] == 'false'
ENV['EX_DEV_CLIENT_NETWORK_INSPECTOR'] ||= podfile_properties['EX_DEV_CLIENT_NETWORK_INSPECTOR']
- ENV['RCT_USE_RN_DEP'] ||= '1' if podfile_properties['ios.buildReactNativeFromSource'] != 'true' && podfile_properties['newArchEnabled'] != 'false'
- ENV['RCT_USE_PREBUILT_RNCORE'] ||= '1' if podfile_properties['ios.buildReactNativeFromSource'] != 'true' && podfile_properties['newArchEnabled'] != 'false'
+ ENV['RCT_USE_RN_DEP'] ||= '1' if podfile_properties['ios.buildReactNativeFromSource'] != 'true'
+ ENV['RCT_USE_PREBUILT_RNCORE'] ||= '1' if podfile_properties['ios.buildReactNativeFromSource'] != 'true'
+ ENV['RCT_HERMES_V1_ENABLED'] ||= '1' if podfile_properties['expo.useHermesV1'] == 'true'
platform :ios, podfile_properties['ios.deploymentTarget'] || '15.1'
prepare_react_native_project!
```
[package.jsonMODIFIED](#packagejson)
```diff
"name": "expo-template-bare-minimum",
"description": "This bare project template includes a minimal setup for using unimodules with React Native.",
"license": "0BSD",
- "version": "54.0.50",
+ "version": "55.0.26",
"main": "index.js",
"scripts": {
"start": "expo start --dev-client",
"web": "expo start --web"
},
"dependencies": {
- "expo": "~54.0.33",
- "expo-status-bar": "~3.0.9",
- "react": "19.1.0",
- "react-native": "0.81.5"
+ "expo": "~55.0.14",
+ "expo-status-bar": "~55.0.5",
+ "react": "19.2.0",
+ "react-native": "0.83.4"
}
}
```
---
---
title: 将 Expo 工具集成到现有原生应用中
description: 关于如何将 Expo 工具集成到现有原生应用（“brownfield” 应用）中的概述。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/brownfield/overview/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 将 Expo 工具集成到现有原生应用中
关于如何将 Expo 工具集成到现有原生应用（“brownfield” 应用）中的概述。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
使用另一种技术构建的现有原生应用，其主入口点 _不是_ React Native 视图，通常被称为“brownfield”应用。例如，如果你的应用是使用 UIKit 和 Swift 构建的，并且你想仅对一个屏幕使用 React Native，那么这就被视为“现有原生应用”和“brownfield”。
相比之下，“greenfield”应用是从一开始就使用 Expo 或 React Native 创建的，或者 React Native 本身就是入口点，而所有其他 UI 都从这里分支出去。
按照这些定义，如果你有一个面向 Android 或 iOS 的“现有原生应用”，并且你想了解如何在项目中使用 Expo 和 React Native（也许只是在单个屏幕，甚至单个功能中），那么本指南就是为你准备的。
## 与现有原生应用的兼容性
> 将 Expo 模块集成到现有原生项目中的支持处于 [alpha](/more/release-statuses#alpha) 阶段。如果你遇到问题，请 [在 GitHub 上创建 issue](https://github.com/expo/expo/issues)。当在现有原生应用的上下文中使用时，下方工具和服务并非所有功能都可用。
Expo 主要是为 greenfield 应用构建的，但我们正在越来越多地投入到 brownfield 场景中。并非所有 Expo 工具和服务目前都与现有原生项目兼容。此外，针对 brownfield 集成的完整文档可能尚未提供，你可能需要根据你的上下文调整其他相关文档。
| 工具/服务 | 支持 brownfield？ |
| --- | --- |
| [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) - 为 Debug 构建添加应用内开发者工具 | 否 |
| [EAS Build](/build/introduction) - 专为 Expo/React Native 构建的 CI/CD 服务 | 是 |
| [EAS Submit](/submit/introduction) - 将应用上传到商店的托管服务 | 是 |
| [EAS Update](/eas-update/introduction) - 应用 JavaScript 和资源的即时更新 | 是 |
## 集成式与隔离式方案
当你将 React Native 集成到现有原生应用中时，你可以在两种主要方案之间进行选择：集成式和隔离式。最适合你的方案取决于项目结构、团队工作流程以及长期目标。
### 集成式方案
在集成式方案中，你的 React Native 代码位于现有原生项目内部。这使 React Native 代码与原生代码之间能够紧密耦合。
例如，你可以将现有的 Android 或 iOS 原生项目添加到 React Native 项目的一个子目录中。这对于最初使用 React Native 开始、后来又添加原生代码的项目来说是常见配置，但它也可以用于现有原生应用。如果你的原生项目不能使用标准的 `android` 和 `ios` 子目录，你可以通过一个简单的 monorepo 设置，为 React Native 代码配置一个自定义根目录。
**如果符合以下情况，请选择此方案：**
- 你需要频繁地同时迭代原生代码和 React Native 代码。
- 你有一个同时负责原生开发和 React Native 开发的单一团队。
- 你的项目结构允许直接添加一个 React Native 项目。
### 隔离式方案
在隔离式方案中，你的 React Native 代码与原生项目分开开发和维护，并且可以维护在独立仓库中，或放在一个 monorepo 中。
采用这种方案时，你会将 React Native 应用打包为一个原生库（Android 使用 AAR，iOS 使用 XCFramework）。然后，你像集成任何其他原生依赖一样，将这个库集成到你的原生应用中。
这种分离简化了原生开发者的工作流程，因为他们不需要设置 Node.js 环境，也不需要处理 React Native 的构建依赖。他们只需将应用中 React Native 部分作为一个预构建产物来使用即可。
**如果符合以下情况，请选择此方案：**
- 你有独立的原生团队和 React Native 团队。
- 你希望尽量减少为现有原生构建流程引入 React Native 所带来的影响。
- 你更倾向于将应用中的 React Native 部分视为一个自包含模块。
## 下一步
[隔离式方案：将 Expo 打包为原生库](/brownfield/isolated-approach) — 将你的 React Native 代码构建为 AAR/ XCFramework 产物，并将它们集成到任何原生应用中。
[集成式方案：将 Expo 直接添加到你的原生项目中](/brownfield/integrated-approach) — 配置你现有的原生项目，直接使用 React Native 和 Expo。
---
---
title: 如何使用隔离方法将 Expo 添加到原生应用
description: 一份关于将 Expo 和 React Native 作为原生库添加，并使用隔离方法将其集成到现有（brownfield）原生应用中的指南。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/brownfield/isolated-approach/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 如何使用隔离方法将 Expo 添加到原生应用
一份关于将 Expo 和 React Native 作为原生库添加，并使用隔离方法将其集成到现有（brownfield）原生应用中的指南。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
在隔离式方案中，你的 React Native 代码是独立于原生项目进行开发和维护的。你将其打包为原生库，Android 使用 AAR，iOS 使用 XCFramework，并像其他依赖一样将其集成到原生应用中。
当你希望尽量减少 React Native 对现有原生构建流程的影响，或者原生开发与 React Native 开发由不同团队负责时，这种方案最为理想。使用这种方案后，原生开发者不需要 Node.js、Yarn 或任何 React Native 构建工具链，他们只需使用已经构建好的产物即可。
> 如果你想了解另一种将 React Native 直接集成到原生项目中的方案，请参阅 [集成式方案指南](/brownfield/integrated-approach)。
## 前提条件
要将 React Native 集成到现有应用中，你需要先搭建 JavaScript 开发环境。这包括安装用于运行 Expo CLI 的 Node.js，以及用于管理项目 JavaScript 依赖的 Yarn。
- [Node.js (LTS)](https://nodejs.org/en/): 用于执行 JavaScript 代码和 Expo CLI 的运行时。
- [Yarn](https://yarnpkg.com/): 用于安装和管理 JavaScript 依赖的包管理器。
更多信息请参阅 [环境搭建指南](/get-started/set-up-your-environment)。
## 设置 Expo 项目
### 创建新的 Expo 项目
运行以下命令创建一个名为 **my-project** 的新目录，其中包含你的新 Expo 项目。虽然你可以将项目命名为任意名称，但本指南为保持一致性，使用 **my-project**。
```sh
npx create-expo-app@latest my-project --template default@sdk-55
```
**my-project** 不需要放在现有原生应用内部，也可以创建在单独的仓库中或 monorepo 中。新项目包含一个示例 TypeScript 应用，帮助你快速开始。
### 安装 expo-brownfield
进入你的新 Expo 项目并安装 `expo-brownfield` 库，它提供了将 React Native 代码构建为原生库并集成到现有原生应用中的工具。
```sh
npx expo install expo-brownfield
```
### 调整配置插件（可选）
`expo-brownfield` 应会自动使用默认配置在你的 **app.json** 中的 `plugins` 数组里添加一项，这对于大多数项目来说已经足够。
```json
{
"expo": {
"plugins": ["expo-brownfield"]
}
}
```
默认值会根据你的应用配置推导而来（例如，目标名称会基于应用的 scheme 或 slug）。你也可以传入选项来自定义目标名称、包标识符和发布配置。
自定义 expo-brownfield 配置
```json
{
"expo": {
"plugins": [
[
"expo-brownfield",
{
"ios": {
"targetName": "MyBrownfield",
"bundleIdentifier": "com.example.mybrownfield"
},
"android": {
"libraryName": "mybrownfield",
"group": "com.example",
"package": "com.example.mybrownfield",
"version": "1.0.0"
}
}
]
]
}
}
```
有关所有可用选项的详细信息，请参阅 [`expo-brownfield` API 参考](/versions/v55.0.0/sdk/brownfield)。
## 将 Expo 项目导出为原生库
完成 Expo 项目设置后，使用 `expo-brownfield` CLI 将你的 React Native 代码构建为 Android 的 AAR 和 iOS 的 XCFramework。
在你的 Expo 项目目录中运行：
```sh
npx expo-brownfield build:android
```
这会构建 AAR 并将其发布到 Maven 仓库。默认情况下，它会发布到你的本地 Maven 仓库（`~/.m2`），但也可以配置为发布到远程仓库。 生成的产物名称将由你的配置插件设置决定，在这个例子中是 `com.username.myproject:brownfield:1.0.0`。
有关构建选项的更多细节，例如仅构建 debug 或 release、指定自定义输出目录等，请参阅 [API 参考](/versions/v55.0.0/sdk/brownfield)。
调试原生目标
如果你需要调试 Expo 项目目标的原生代码，可以运行 `npx expo prebuild` 来生成带有 brownfield 库目标的原生项目，位于 **android** 和 **ios** 目录中。
```sh
npx expo prebuild
```
上述命令会生成以下内容：
- **Android**：一个单独的库模块，包含 `ReactNativeHostManager`、`BrownfieldActivity`、`ReactNativeFragment`、`ReactNativeViewFactory` 和 `BrownfieldMessaging`。
- **iOS**：一个单独的 Xcode framework 目标，包含 `ReactNativeHostManager`、`ReactNativeViewController`、`ReactNativeView`（SwiftUI）、`BrownfieldMessaging` 和 `ReactNativeDelegate`。
## 集成到你的原生应用中
在构建好产物后，你现在可以将它们集成到现有原生应用中。具体步骤将取决于你的项目结构和构建系统，但整体流程包括将预构建产物作为依赖添加进去，并初始化 React Native host。
#### 添加 Maven 依赖
首先将依赖添加到你的应用 **build.gradle.kts** 中。group、artifact 名称和版本应与你的配置插件设置一致：
```kotlin
dependencies {
implementation("com.username.myproject:brownfield:1.0.0")
}
```
如果该库是发布到本地 Maven，请确保在仓库配置中添加 `mavenLocal()`：
```kotlin
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
mavenLocal()
}
}
```
#### 显示 React Native 屏幕
创建一个继承自 `BrownfieldActivity` 的 activity，并使用 `showReactNativeFragment()` 扩展方法：
```kotlin
import android.os.Bundle
import com.example.brownfield.BrownfieldActivity
import com.example.brownfield.showReactNativeFragment
class ExpoActivity : BrownfieldActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
showReactNativeFragment()
}
}
```
在你的 **AndroidManifest.xml** 中添加该 activity，并使用一个非 ActionBar 主题：
```xml
```
然后在应用中的任意位置启动它：
```kotlin
startActivity(Intent(this, ExpoActivity::class.java))
```
`BrownfieldActivity` 继承自 `AppCompatActivity`，并负责将配置变化转发给 Expo 模块。`showReactNativeFragment()` 扩展方法也会自动配置原生返回按钮处理。
## 测试你的集成
你已经完成了将 React Native 集成到应用中的所有基础步骤。现在是时候测试一下了。具体流程取决于你运行的是 debug 还是 release 构建。
### 开发（debug 构建）
现在在 React Native 目录中运行以下命令，以启动 [Metro bundler](https://metrobundler.dev/)
```sh
npx expo start
```
然后，从 Android Studio 或 Xcode 构建并运行原生应用。当你进入 React Native 屏幕时，它会从 Metro 开发服务器加载，并支持热重载。
### 生产（release 构建）
在 release 构建中，JavaScript bundle 会嵌入到产物（AAR 或 XCFramework）中，因此不需要 Metro 服务器。以 Release 配置构建原生应用，并确认 React Native 屏幕能够正确加载。
## 下一步
[生命周期监听器](/brownfield/lifecycle-listeners) — 为 Expo 模块配置应用生命周期监听器，以实现更深度的集成。
[expo-brownfield API 参考](/versions/v55.0.0/sdk/brownfield) — 查看用于通信、导航等功能的完整 JavaScript API。
---
---
title: 如何使用集成方式将 Expo 添加到原生应用中
description: 一份使用集成方式将 Expo 和 React Native 添加到现有原生（brownfield）应用中的指南。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/brownfield/integrated-approach/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 如何使用集成方式将 Expo 添加到原生应用中
一份使用集成方式将 Expo 和 React Native 添加到现有原生（brownfield）应用中的指南。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
React Native 和 Expo 非常灵活，可以逐步采用，一次一个屏幕（甚至一次一个视图）。你甚至可能会发现，以这种方式使用 Expo 最适合你的特定应用；或者，你也可能会在应用的更多界面中逐渐采用它。无论哪种方式，这种灵活性都使开发者能够立即在原生应用中采用现代的跨平台工具，而不是冒着完全重写的风险。
本指南将带你了解如何将 React Native 视图添加到现有的原生应用中。这里介绍的方法是我们所说的“集成”方式，因为 React Native 和 Expo 会像集成其他任意库一样被集成进来。
> 另一种流行的技术是我们所说的“隔离”方式，在这种方式下，你的 Expo 应用会被打包成一个库，并被主应用当作黑盒处理。详情请参阅 [isolated approach guide](/brownfield/isolated-approach)。
## 前置条件
要将 React Native 集成到你现有的应用中，你需要先搭建一个 JavaScript 开发环境。这包括安装用于运行 Expo CLI 的 Node.js，以及用于管理项目 JavaScript 依赖的 Yarn。
- [Node.js (LTS)](https://nodejs.org/en/): 用于执行 JavaScript 代码和 Expo CLI 的运行时。
- [Yarn](https://yarnpkg.com/): 用于安装和管理 JavaScript 依赖的包管理器。
- iOS [CocoaPods](https://cocoapods.org/): iOS 可用的依赖管理系统之一。CocoaPods 是一个 Ruby [gem](https://en.wikipedia.org/wiki/RubyGems)。你可以使用最新版 macOS 自带的 Ruby 来安装 CocoaPods。
可从 [设置环境指南](/get-started/set-up-your-environment) 了解更多。
## 创建 Expo 项目
首先，在现有原生项目的根目录内创建一个 Expo 项目。
```sh
npx create-expo-app@latest my-project --template default@sdk-55
```
此命令会创建一个名为 **my-project** 的新目录，其中包含你的新 Expo 项目。虽然你可以将项目命名为任何名称，但为了保持一致，本指南使用 **my-project**。新项目包含一个示例 TypeScript 应用，帮助你快速上手。
## 设置项目结构
标准的 React Native 项目会将原生代码放在 **android** 和 **ios** 目录中。具体如何操作取决于你的项目，但最简单的情况可能只是创建这些目录并将你的项目移过去。例如：
```sh
mkdir my-project/android
mv /path/to/your/android-project my-project/android/
```
无法将你的原生项目移动到 android 和 ios 目录？
### 设置 monorepo
Monorepo，或“单体仓库”，是包含多个应用或包的单一仓库。[了解更多](/guides/monorepos)。
设置 monorepo 将确保即使在自定义文件夹结构下，Android 和 iOS 脚本也能够调用 Node 库中的命令。要设置 Yarn monorepo，请在项目根目录创建一个 **package.json** 文件，并添加以下内容：
```json
{
"version": "1.0.0",
"private": true,
"workspaces": ["my-project"]
}
```
然后运行 `yarn install` 来安装依赖。这将确保 **node_modules** 安装在项目根目录，并且原生脚本可以与 React Native 代码交互。请务必将 `["my-project"]` 改为你在上一步创建的 Expo 项目名称。
> 采用 monorepo 方式需要你在 Gradle/CocoaPods 中配置自定义项目根目录。下一节会对此进行说明。
## 配置你的原生项目
要在 Android 上集成 React Native，你需要通过修改以下文件来配置原生项目：
- **Gradle 文件**：**settings.gradle**、顶层 **build.gradle**、**app/build.gradle** 和 **gradle.properties**，用于添加 React Native Gradle Plugin（RNGP）及其他属性。
- **AndroidManifest.xml**：用于添加必要权限。（[了解更多](/brownfield/integrated-approach#configuring-your-manifest)）
- **MainActivity**：用于加载你的 React Native 应用。
### 配置 Gradle
首先编辑你的 **settings.gradle** 文件，并添加以下行（可参考 [最小模板](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/settings.gradle)）：
```groovy
// 为自动链接配置 React Native Gradle Settings 插件
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)
// 在这里包含你现有的 Gradle 模块。
// include(":app")
```
使用自定义文件夹结构？
如果你使用的是自定义文件夹结构，那么为了让自动链接正常工作，你需要在 **settings.gradle** 中显式设置项目根目录。请修改以下行：
然后打开顶层 **build.gradle** 并包含这一行（如 [最小模板](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/build.gradle) 所示）：
这可以确保 React Native Gradle 和 Expo 插件在你的项目中可用并被应用。
在你应用的 **build.gradle** 文件中添加以下几行（通常是 **app/build.gradle** —— 你可以参考 [最小模板文件](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/app/build.gradle)）：
使用自定义文件夹结构？
如果你使用的是自定义文件夹结构，那么你需要在 **app/build.gradle** 中调整 `projectRoot` 的值，使其指向你的 Expo 项目根目录。请修改以下行：
最后，打开你应用的 **gradle.properties** 文件，并添加以下几行（可参考 [最小模板文件](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/gradle.properties)）：
```properties
reactNativeArchitectures=armeabi-v7a,arm64-v8a,x86,x86_64
newArchEnabled=true
hermesEnabled=true
```
### 配置你的 manifest
首先，确保你的 **AndroidManifest.xml** 中包含 `INTERNET` 权限：
现在，在你的 **debug** **AndroidManifest.xml** 中启用 [明文流量](https://developer.android.com/training/articles/security-config#CleartextTrafficPermitted)：
这是让你的应用通过 HTTP 与本地 [Metro bundler](https://metrobundler.dev/) 通信所必需的。你可以将最小模板中的 **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。你可以参考 [最小模板](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/app/src/main/java/com/helloworld/MainApplication.kt) 中的 **MainApplication.kt**：
#### 创建一个 `ReactActivity`
创建一个新的 `Activity`，让它继承 `ReactActivity` 并承载 React Native 代码。这个 activity 将负责启动 React Native 运行时并渲染 React 组件。你可以参考 [最小模板中的 **MainActivity.kt**](https://github.com/expo/expo/blob/main/templates/expo-template-bare-minimum/android/app/src/main/java/com/helloworld/MainActivity.kt)：
```kotlin
// package
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`：
现在你的 activity 已准备好运行一些 JavaScript 代码。
## 测试你的集成
你已经完成了将 React Native 与你的应用集成所需的所有基本步骤。现在，在 React Native 目录中运行以下命令以启动 [Metro bundler](https://metrobundler.dev/)
```sh
yarn start
```
Metro 会将你的 TypeScript 应用代码构建成一个 bundle，通过其 HTTP 服务器提供该 bundle，并将开发环境中 `localhost` 上的 bundle 共享到模拟器或设备，从而支持 [热重载](https://reactnative.dev/blog/2016/03/24/introducing-hot-reloading)。现在你可以像往常一样构建并运行你的应用。一旦你在应用中进入由 React 驱动的 Activity，它就应该从开发服务器加载 JavaScript 代码。
---
---
title: 配置生命周期监听器
description: 了解允许 Expo Modules API 钩入应用生命周期的机制。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/brownfield/lifecycle-listeners/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 配置生命周期监听器
了解允许 Expo Modules API 钩入应用生命周期的机制。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
一些 Expo 库需要通过实现 `Activity`/`Application` 或 `AppDelegate` 生命周期回调来处理系统事件，例如深度链接、推送通知和配置更改。
Expo Modules API 提供了一种简单的方法来管理此类回调：
- Android `ApplicationLifecycleDispatcher` 和 `ReactActivityHandler` 会将 `Application` 和 `Activity` 生命周期事件转发给已注册的监听器。模块可以通过 `Package` 类提供 `ReactActivityLifecycleListener` 和 `ApplicationLifecycleListener` 实现来注册回调。
- iOS `ExpoAppDelegate` 会将 `AppDelegate` 调用转发给已注册的 订阅者。模块可以提供 `ExpoAppDelegateSubscriber` 实现来注册 回调。
使用这些机制可以让模块注册行为，而无需你反复编辑原生入口点。
## 配置你的原生项目
### Android
要在 Android 上集成 `Application` 生命周期监听器，请将你的 `Application` 类中的 `onCreate()` 和 `onConfigurationChanged()` 调用转发给 `ApplicationLifecycleDispatcher`：
### iOS
要在 iOS 上集成 `AppDelegate` 订阅者，请在你现有的 `AppDelegate` 实现中将相关调用转发给 `ExpoAppDelegateSubscriberManager`，以便订阅者能够响应它们：
或者，如果你的 `AppDelegate` 还没有继承其他类，你可以通过继承 `ExpoAppDelegate` 来简化设置，它会自动处理转发：
> **注意：** 并非所有可能导致重大副作用的 `UIApplicationDelegate` 方法都受支持。如果你需要依赖某个特定的委托，请查看 Expo 源码（**ExpoAppDelegate.swift**）以获取完整的转发方法列表。
## 测试你的集成
要测试回调是否正常工作，请安装一个依赖它们的模块。安装 `expo-linking`，它使用生命周期监听器来处理深度链接：
```sh
npx expo install expo-linking
```
在代码中为深度链接添加一个监听器，并在打开深度链接时观察控制台：
```jsx
import * as Linking from 'expo-linking';
import { useEffect } from 'react';
useEffect(() => {
const listener = Linking.addEventListener('url', ({ url }) => {
console.log('收到深度链接：', url);
});
return listener.remove;
}, []);
```
运行以下命令以打开指向你应用的深度链接：
```sh
npx uri-scheme open com.example.app://somepath/details --android
npx uri-scheme open myapp://somepath/details --ios
```
---
---
title: 使用 monorepo 开发
description: 了解如何在 monorepo 中使用 workspaces 设置 Expo 项目。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/monorepos/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 使用 monorepo 开发
了解如何在 monorepo 中使用 workspaces 设置 Expo 项目。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
Monorepo，或 _“单体仓库”_，是包含多个应用或包的单个仓库。它们可以帮助加快大型项目的开发速度，让代码共享更容易，并作为单一事实来源。本指南将使用一个 Expo 项目搭建一个简单的 monorepo。Expo 对由支持工作区的包管理器管理的 monorepo 提供一流支持：[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 Classic 和 Berry）。Expo 会自动检测 monorepo，并为添加到 monorepo 中的新应用项目进行配置。检测基于你项目中的工作区配置。
> Monorepo 并不适合每个项目。若多个应用位于同一个仓库中并共享代码，它会很有用；或者将原生模块与应用放在一起也会很方便。代价是在设置和配置工具链时复杂度会增加。在搭建 monorepo 之前，请先检查你的工具和库是否能在 monorepo 中良好工作。
自动配置（迁移到 SDK 52+）
Expo 会为 monorepo 自动配置 Metro。在使用 monorepo 时，如果你使用的是 [`expo/metro-config`](/guides/customizing-metro)，就不需要手动配置 Metro。
如果你之前为 monorepo 手动配置过 Metro，并且你的 **metro.config.js** 修改了以下属性之一，请将它们从配置中删除：
- `watchFolders`
- `resolver.nodeModulesPath`
- `resolver.extraNodeModules`
- `resolver.disableHierarchicalLookup`
删除这些选项后，你需要使用 `npx expo start --clear` 运行一次 Expo，以清除过时的 Metro 缓存。如果之后你的应用仍能按预期运行，那么它就是一个普通的 Node monorepo，今后不需要任何特殊配置。
手动配置（在 SDK 52 之前）
Expo 的 Metro 配置内置支持 Bun、npm、pnpm 和 Yarn 的 monorepo。如果你使用的是来自 [`expo/metro-config`](/guides/customizing-metro) 的配置，在使用 monorepo 时就不需要手动配置 Metro。
在 SDK 52 之前，使用 Metro 配置 monorepo 需要两项手动更改：
1. 必须手动配置 Metro 去监视 monorepo 内的代码（例如，不仅仅是 **apps/cool-app**。）
2. 需要调整 Metro 的解析方式，以便查找其他工作区中的包以及多个 `node_modules` 文件夹（例如，**apps/cool-app/node_modules** 或 **node_modules**。）
配置是通过[创建一个 **metro.config.js**](/guides/customizing-metro#customizing) 并使用以下内容来完成的：
```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. 监视 monorepo 中的所有文件
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)的信息。
## 搭建 monorepo
在 monorepo 中，你的应用通常会位于仓库的一个子目录中，而你的包管理器会配置为允许你在 monorepo 内为其他包添加依赖。 例如，一个包含 Expo 应用的 monorepo 的基本结构可能如下所示：
- **apps**：包含多个项目，包括 Expo 应用。
- **packages**：包含应用使用的不同包。
- **package.json**：根目录包文件。
所有 monorepo 都应该有一个“根” **package.json** 文件。它是 monorepo 的主要配置，并且可能包含为仓库中所有项目安装的工具。根据你使用的包管理器不同，设置工作区的步骤可能会有所不同，但对于 [Bun](https://bun.sh/docs/install/workspaces)、[npm](https://docs.npmjs.com/cli/using-npm/workspaces) 和 [Yarn](https://yarnpkg.com/features/workspaces)，应在根 **package.json** 文件中添加一个 `workspaces` 属性，用来为 monorepo 中的所有工作区指定 [glob 模式](https://classic.yarnpkg.com/lang/en/docs/workspaces/#toc-tips-tricks)：
```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
packages:
- 'apps/*'
- 'packages/*'
```
### 创建你的第一个应用
现在你已经完成了基本的 monorepo 结构设置，接下来添加你的第一个应用。
在创建应用之前，你需要先创建 **apps** 目录。这个目录包含属于这个 monorepo 的所有独立应用或网站。在这个 **apps** 目录中，你可以创建一个包含 Expo 应用的子目录。
```sh
# npm
npx create-expo-app@latest --template default@sdk-55 apps/cool-app
# yarn
yarn create expo-app --template default@sdk-55 apps/cool-app
# pnpm
pnpm create expo-app --template default@sdk-55 apps/cool-app
# bun
bun create expo --template default@sdk-55 apps/cool-app
```
> 如果你已经有一个现有应用，可以把所有这些文件复制到 **apps** 内的一个目录中。
复制或创建第一个应用后，请从 monorepo 的根目录使用你的包管理器安装依赖，以检查常见警告。
### 创建一个包
Monorepo 可以帮助我们将代码分组到一个仓库中。这包括应用，也包括独立的包。它们也不一定需要发布。[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**。
```sh
# npm
mkdir -p packages/cool-package && cd packages/cool-package && npm init
# yarn
mkdir -p packages/cool-package && cd packages/cool-package && yarn init
# pnpm
mkdir -p packages/cool-package && cd packages/cool-package && pnpm init
# bun
mkdir -p packages/cool-package && cd packages/cool-package && bun init --minimal
```
我们不会过多展开如何创建一个包。如果你对此不熟悉，建议使用一个不带 monorepo 的简单应用。不过，为了让示例完整，我们来添加一个 **index.js** 文件，并包含以下内容：
```js
export const greeting = 'Hello!';
```
### 使用该包
像标准包一样，我们需要将 **cool-package** 作为依赖添加到我们的 **cool-app** 中。标准包和 monorepo 中的包之间的主要区别是，你通常总是想使用 _“包的当前状态”_ 而不是某个版本。让我们通过在应用的 **package.json** 文件中添加 `"cool-package": "*"` 来把 **cool-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": "~55.0.0",
"expo-status-bar": "~55.0.0",
"react": "19.2.0",
"react-native": "0.83"
}
}
```
Bun、npm 和 pnpm 支持使用 `"workspace:*"` 而不是 `"*"` 来指定工作区依赖。这可以确保工作区包不会从 npm registry 解析到同名的已发布包，但这是可选的。
添加包之后，请再次从 monorepo 的根目录使用你的包管理器安装依赖，以再次检查常见警告。
现在你应该能够在应用中使用这个包了！为了测试这一点，让我们编辑应用中的 **App.js**，并渲染来自 **cool-package** 的 `greeting` 文本。
```jsx
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 (
{greeting}
);
}
```
## 常见问题
Monorepo 可能会带来普通项目不会遇到的解析和依赖问题。它们需要更深入的知识，并且需要特定的工具配置。你需要接受更高的复杂度，并解决一些在没有工作区时不会遇到的问题。以下是你可能会遇到的一些常见问题。
### 具有隔离依赖的包管理器
> 从 **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 模块。相反，更多其他包所依赖的模块会被提升并变得可访问。这可能导致非确定性行为，并使你拥有有问题的依赖链；这些链更脆弱，并且在更新或升级包时可能引发解析错误。这在 monorepo 中尤其常见。
**从 SDK 54 开始**，Expo 支持隔离依赖。不幸的是，并非你安装的所有包都能正常工作，有些 React Native 库在与隔离依赖一起使用时可能会导致构建或解析错误。如果你在使用 [pnpm](https://pnpm.io/settings#nodelinker) 的隔离安装时遇到问题，可以通过修改仓库根目录下 **pnpm-workspace.yaml** 文件中的 `nodeLinker` 设置，切换为 **hoisted** 安装策略：
```yaml
nodeLinker: hoisted
```
### monorepo 中重复的原生包
Expo 已改进对更完整的 **node_modules** 模式的支持，例如隔离模块。不幸的是，如果你的应用包含重复依赖，问题仍然可能出现：
- 单个 monorepo 中不支持重复的 React Native 版本
- 单个应用中重复的 React 版本会导致运行时错误
- Turbo 和 Expo 模块的重复版本可能导致运行时或构建错误
你可以检查 monorepo 中是否存在某个包的多个版本，例如 `react-native`，以及它们是通过你使用的包管理器为什么会被安装的。
```sh
# npm
npm why react-native
# yarn
yarn why react-native
# pnpm
pnpm why --depth=10 react-native
# bun
bun pm why react-native
```
这些命令的输出在不同包管理器之间会有很大差异，但你可以通过查找该包的多个版本来识别输出中的重复包，例如 `react-native@0.79.5` 和 `react-native@0.81.0`。 **npm**，
#### 为 peer 依赖添加依赖解析
如果重复依赖无法通过你修改依赖来解决，那么你可能需要添加一个解析。例如，并非所有包都已更新其 **peerDependencies** 以支持 React 19。为了解决这个问题，你可以创建一个解析，强制安装单一版本的 `react`。
```json
{
"name": "monorepo",
"private": true,
"version": "0.0.0",
"workspaces": ["apps/*", "packages/*"],
"resolutions": {
"react": "^19.2.0"
}
}
```
对于 [npm](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides)，你必须使用名为 `overrides` 的属性，而不是 `resolutions`。
#### 为自动链接的原生模块去重
很多时候，重复依赖不会造成任何问题。然而，原生模块绝不应该重复，因为一次应用构建中只能编译一个版本的原生模块。与 JavaScript 依赖不同，原生构建不能包含同一个原生模块的两个冲突版本。
从 **SDK 54** 开始，你可以在 **app.json** 中将 `experiments.autolinkingModuleResolution` 设为 `true`，以将自动链接自动应用于 Expo CLI 和 Metro bundler。这将强制让 Metro 解析到的依赖与 [autolinking](/modules/autolinking) 为你的原生构建所链接的原生模块保持一致。
从 **SDK 55** 开始，这在 monorepo 中的应用里会自动启用。
### Script '...' does not exist
React Native 使用包来同时提供 JavaScript 和原生文件。这些原生文件也需要被链接，就像 **android/app/build.Gradle** 中的 [**react-native/react.Gradle**](https://github.com/facebook/react-native/blob/v0.70.6/react.gradle) 文件一样。通常，这个路径会被硬编码为类似下面这样的内容：
**Android** ([source](https://github.com/facebook/react-native/blob/e918362be3cb03ae9dee3b8d50a240c599f6723f/template/android/app/build.gradle#L84))
```groovy
apply from: "../../node_modules/react-native/react.gradle"
```
**iOS** ([source](https://github.com/facebook/react-native/blob/e918362be3cb03ae9dee3b8d50a240c599f6723f/template/ios/Podfile#L1))
```ruby
require_relative '../node_modules/react-native/scripts/react_native_pods'
```
不幸的是，由于 [hoisting](https://classic.yarnpkg.com/blog/2018/02/15/nohoist/)，在 monorepo 中这个路径可能不同。它也没有使用 [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/main/packages/expo-modules-core/README.md)。
所有 Expo SDK 模块和模板都使用这些动态引用，因此可以在 monorepo 中正常工作。不过，偶尔你可能会遇到仍然使用硬编码路径的包。你可以使用 [`patch-package`](https://github.com/ds300/patch-package#readme) 手动修改它，或者向该包的维护者提出来。
---
---
title: 查看日志
description: 了解如何在使用 Expo CLI 时查看日志、在 Android Studio 和 Xcode 中查看原生日志，以及查看系统日志。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/workflow/logging/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 查看日志
了解如何在使用 Expo CLI 时查看日志、在 Android Studio 和 Xcode 中查看原生日志，以及查看系统日志。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
在 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
```
---
---
title: 开发模式与生产模式
description: 了解如何在开发模式或生产模式下运行项目。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/workflow/development-mode/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 开发模式与生产模式
了解如何在开发模式或生产模式下运行项目。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
你的项目将始终以 **开发** 或 **生产** 模式运行。默认情况下，使用 `npx expo start` 在本地运行项目会以开发模式运行，而已发布的项目（使用 `eas update`），或者任何独立应用，都将以生产模式运行。
**开发模式** 包含有用的警告，并让你能够使用使开发和调试更轻松的工具。**生产模式** [会压缩你的代码](/guides/customizing-metro#minification)，并更好地反映应用在最终用户设备上的实际性能。让我们更详细地了解这两种模式，并学习如何在它们之间切换。
## 开发模式
React Native 包含一些非常有用的开发工具：Chrome 中的远程 JavaScript 调试、实时重载、热重载，以及一个类似于你在 Chrome 中使用的、备受喜爱的元素检查器。如果你想了解如何使用这些工具，请参阅 [调试](/debugging/runtime-issues)。
开发模式还会在应用运行时执行验证以给出警告。例如，当你使用了已弃用的属性，或者忘记向组件传递必需属性时。下面的视频展示了元素检查器和性能监视器在 Android 模拟器和 iOS 模拟器上的实际运行情况：
> **这样做是有代价的。你的应用在开发模式下运行会更慢。**
> 你可以使用 Expo CLI 将其开启或关闭，参见 [生产模式](/workflow/development-mode#production-mode)。当你切换之后，请关闭并重新打开应用，使更改生效。**任何时候当你测试应用性能时，请务必关闭开发模式**。
### 查看开发者菜单
该菜单提供了一系列功能，使开发和调试更加轻松。有关如何在 Android 和 iOS 上打开它的更多信息，请参阅 [开发者菜单](/debugging/tools#developer-menu)。
## 生产模式
生产模式主要有两个用途：
- 测试应用的性能，因为开发模式会显著拖慢应用。
- 捕获只会在生产环境中出现的 bug。
模拟项目在最终用户设备上运行方式的最简单方法是使用以下命令：
```sh
npx expo start --no-dev --minify
```
它会以生产模式运行你应用的 JavaScript（这会告诉 Metro bundler 将 `__DEV__` 环境变量设为 `false`，以及其他一些操作）。`--minify` 标志会压缩你的应用。该标志还会删除不必要的数据，例如注释、格式以及未使用的代码。如果你在独立应用中遇到错误或崩溃，使用此命令运行项目可以为你节省大量查找根本原因的时间。
要将你的应用完整编译为生产版本，请参阅 [编译 Android](/more/expo-cli#compiling-android) 和 [编译 iOS](/more/expo-cli#compiling-ios)。
---
---
title: 常见开发错误
description: 使用 Expo 的开发者经常遇到的常见开发错误列表。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/workflow/common-development-errors/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 常见开发错误
使用 Expo 的开发者经常遇到的常见开发错误列表。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
此页面列出了一些使用 Expo 的开发者常见会遇到的错误。对于每个错误，第一条项目符号提供该错误发生原因的说明，第二条项目符号包含调试建议。如果你认为这里还应该包含某个错误，我们欢迎并鼓励你 [创建 PR](https://github.com/expo/expo/pulls)！
### Metro bundler ECONNREFUSED 127.0.0.1:19001
- 有错误阻止了与本地开发服务器的连接。
- 运行 `rm -rf .expo` 来清除本地状态。检查是否有防火墙或 [代理](/troubleshooting/proxies) 影响你当前连接的网络。
### Module AppRegistry is not a registered callable module (calling runApplication)
- 你的代码中存在错误，导致 JavaScript bundle 在启动时无法执行。
- 尝试运行 `npx expo start --no-dev --minify` 在本地复现生产环境的 JS bundle。如果可能，连接你的设备，并通过 Android Studio 或 Xcode 访问设备日志。设备日志包含更详细的堆栈跟踪和信息。检查你的 Babel 配置中是否有任何更改或错误。在某些罕见情况下，此问题可能是由 Metro JavaScript 压缩器与应用中的某些代码不兼容导致的（[更多信息](https://forums.expo.dev/t/change-minifierconfig-for-minify-uglify/36460/2)）。
### npm ERR! No git binary found in $PATH
- 要么你没有安装 git，要么它没有在你的 `$PATH` 中正确配置。
- 如果你还没有安装，请[安装 git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)。否则，根据你的操作系统检查如何将其设置到你的 `$PATH` 中。
### XX.X.X is not a valid SDK version
- 你正在运行的 SDK 版本已被弃用，不再受支持。
- [升级你的项目](/workflow/upgrading-expo-sdk-walkthrough)到受支持的 SDK 版本。如果你使用的是受支持的版本但仍看到此消息，你需要更新你的 Expo Go 应用。
### React Native version mismatch
- 终端中运行的开发服务器正在打包一个与设备或模拟器中的应用不同版本的 React Native。
- 通过检查 **app.json** 和 **package.json** 中的版本，[使你的 react-native 版本保持一致](/troubleshooting/react-native-version-mismatch)。
### Application has not been registered
- 你的应用在原生端和 JS 端注册的 AppKey 不匹配。
- 将你的 AppKey 与项目的原生部分[保持一致](/troubleshooting/application-has-not-been-registered)。
### Application not behaving as expected
- 可能是缓存阻止你看到应用的当前状态。
- 清除与你的项目相关的所有缓存，适用于 [Unix-like](/troubleshooting/clear-cache-macos-linux) 或 [Windows](/troubleshooting/clear-cache-windows) 系统。
---
---
title: Android Studio 模拟器
description: 了解如何设置 Android 模拟器，以便在虚拟 Android 设备上测试您的应用。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/workflow/android-studio-emulator/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# Android Studio 模拟器
了解如何设置 Android 模拟器，以便在虚拟 Android 设备上测试您的应用。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
如果你没有可用于测试的 Android 设备，我们建议使用 Android Studio 自带的默认模拟器。如果你在设置过程中遇到任何问题，请按照本指南中的步骤进行操作。
## Install Watchman and JDK
#### Prerequisites
Use a package manager such as [Homebrew](https://brew.sh/) to install the following dependency.
#### Install dependencies
[Install Watchman](https://facebook.github.io/watchman/docs/install#macos) using a tool such as Homebrew:
```sh
brew install watchman
```
Install OpenJDK distribution called Azul Zulu using Homebrew. This distribution offers JDKs for both Apple Silicon and Intel Macs.
Run the following commands in a terminal:
```sh
brew install --cask zulu@17
```
After you install the JDK, add the `JAVA_HOME` environment variable in **~/.bash_profile** (or **~/.zshrc** if you use Zsh):
```bash
export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
```
## Set up Android Studio
Download and install [Android Studio](https://developer.android.com/studio).
Open the **Android Studio** app, you will see the **SDK Components setup** screen. Click **Next** to continue to install the Android SDK and Android SDK Platform. Click **Next** again to verify the settings and install.
By default, Android Studio will install the latest version of the Android SDK. However, Android 15 (`VanillaIceCream`) SDK is required to compile a React Native app.
Open Android Studio, go to **Settings** > **Languages & Frameworks** > **Android SDK**. From the **SDK Platforms** tab, and under **Android 15 (`VanillaIceCream`)**, select **Android SDK Platform 35** and **Sources for Android 35**.
Then, click on the **SDK Tools** tab and make sure you have at least one version of the **Android SDK Build-Tools** and **Android Emulator** installed.
Copy or remember the path listed in the box that says **Android SDK Location**.
Add the following lines to your **/.zprofile** or **~/.zshrc** (if you are using bash, then **~/.bash_profile** or **~/.bashrc**) config file:
```sh
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
```
Reload the path environment variables in your current shell:
```sh
source $HOME/.zshrc
source $HOME/.bashrc
```
Finally, make sure that you can run `adb` from your terminal.
Troubleshooting: Android Studio not recognizing JDK
If Android Studio doesn't recognize your homebrew installed JDK, you can create a Gradle configuration file to explicitly set the Java path:
1. Create a Gradle properties file in your home directory:
```sh
touch ~/.gradle/gradle.properties
```
2. Add the following line to the **gradle.properties** file, replacing the path with your actual Java installation path:
```bash
java.home=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
```
3. If you have an existing `.gradle` folder in your project directory, delete it and reopen your project in Android Studio:
```sh
rm -rf .gradle
```
This should resolve issues with Android Studio not detecting your JDK installation.
## Set up an emulator
On the Android Studio main screen, click **More Actions**, then **Virtual Device Manager** in the dropdown.
Click the **Create device** button.
Under **Add device**, choose the type of hardware you'd like to emulate. We recommend testing against a variety of devices, but if you're unsure where to start, the newest device in the Pixel line could be a good choice.
Select an OS version to load on the emulator (probably one of the system images), and download the image (if required).
Change any other settings you'd like, and press **Finish** to create the emulator. You can now run this emulator anytime by pressing the Play button in the AVD Manager window.
## 故障排除
### 多个 `adb` 版本
系统中存在多个 `adb` 版本可能会导致以下错误：
```sh
adb server version (xx) doesn't match this client (xx); killing...
```
这是因为你系统上的 `adb` 版本与 Android SDK platform-tools 中的 `adb` 版本不同。
打开终端并检查系统上的 `adb` 版本：
```sh
adb version
```
然后从 Android SDK platform-tool 目录中检查：
```sh
cd ~/Library/Android/sdk/platform-tools
./adb version
```
将 Android SDK 目录中的 `adb` 复制到 `usr/bin` 目录：
```sh
sudo cp ~/Library/Android/sdk/platform-tools/adb /usr/bin
```
---
---
title: iOS 模拟器
description: 了解如何在你的 Mac 上安装 iOS 模拟器，并使用它来开发你的应用。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/workflow/ios-simulator/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# iOS 模拟器
了解如何在你的 Mac 上安装 iOS 模拟器，并使用它来开发你的应用。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
直接在电脑上开发你的应用，可能比不断与 iPhone 或 iPad 交互更方便，尤其是在网络条件较慢，或者由于 LAN 限制需要使用 [隧道连接](/more/expo-cli#tunneling) 时。
本指南说明如何在 Mac 上安装 iOS 模拟器以进行应用开发。请注意，iOS 模拟器只能安装在 macOS 上。如果你正在使用 Windows 或 Linux 机器开发 iOS 应用，则需要一台实体 iOS 设备。
## 设置 Xcode 和 Watchman
### Install Xcode
Open up the Mac App Store, search for [Xcode](https://apps.apple.com/us/app/xcode/id497799835), and click **Install** (or **Update** if you have it already).
### Install Xcode Command Line Tools
Open Xcode, choose **Settings...** from the Xcode menu (or press cmd ⌘ + ,). Go to the **Locations** and install the tools by selecting the most recent version in the **Command Line Tools** dropdown.
### Install an iOS Simulator in Xcode
To install an iOS Simulator, open **Xcode > Settings... > Components**, and under **Platform Support > iOS ...**, click **Get**.
### Install Watchman
[Watchman](https://facebook.github.io/watchman/docs/install#macos) is a tool for watching changes in the filesystem. Installing it will result in better performance. You can install it with:
```sh
brew update
brew install watchman
```
### 试试看
运行 `npx expo start` 启动你的应用，然后在命令行中按 i。
你可能会收到一条关于需要接受 Xcode 许可的警告。运行它建议的命令。再次打开你的应用，看看是否成功。如果没有，请查看下面的[故障排除](/workflow/ios-simulator#troubleshooting)提示。
你也可以在 Expo CLI 中按 shift + i，交互式选择要打开的模拟器。
## Expo Orbit
你可以使用 Expo Orbit 应用，它允许你在 macOS 的菜单栏中一键启动构建并管理模拟器。
[使用 Expo Orbit](/build/orbit) — 了解更多关于如何使用 Expo Orbit。
## 限制
尽管 iOS 模拟器非常适合快速开发，但它确实存在一些限制。下面我们会列出一些会影响 Expo API 的主要差异。不过，更多详情请参阅 [Apple 的文档](https://help.apple.com/simulator/mac/current/#/devb0244142d)。
模拟器中不可用的以下硬件：
- 音频输入
- 气压计
- 摄像头
- 运动支持（加速度计和陀螺仪）
在 iOS 11 及更高版本中，模拟器还会挂起后台应用和进程。
## 故障排除
### 打开模拟器时，CLI 似乎卡住了
有时 iOS 模拟器不会响应打开命令。如果它似乎卡在这个提示上，你可以手动打开 iOS 模拟器（`open -a Simulator`），然后在 macOS 工具栏中选择 **File** > **Open Simulator**，并选择你想打开的 iOS 版本和设备。
你可以使用此菜单打开任意版本的模拟器。你也可以同时打开多个模拟器，不过，Expo CLI 始终会以最近打开的模拟器为目标。
### 模拟器已打开，但 Expo Go 应用没有在其中启动
你第一次在模拟器中安装该应用时，iOS 会询问你是否要打开 Expo Go 应用。你可能需要与模拟器进行交互（点击几下、拖动某些内容），这个提示才会出现，然后按 **OK**。
### 如何强制更新到最新版本？
创建一个使用所需 SDK 版本的项目，并在模拟器中打开它，以安装特定版本的 Expo Go。
```sh
npx create-expo-app --template blank@53
npx expo start --ios
```
### Expo CLI 打印了一条关于 `xcrun` 的错误信息，我该怎么办？
对于其他错误，请尝试以下操作：
- 在你的模拟器上手动卸载 Expo Go，然后在 Expo CLI 终端 UI 中按 shift + i 并选择所需的模拟器，以重新安装。
- 如果这没有帮助，聚焦模拟器窗口，并在 Mac 工具栏中选择 **Device** > **Erase All Content and Settings...**
这将使用空白镜像重新初始化你的模拟器。这在你的电脑内存不足、模拟器无法保存某些内部文件，从而使设备处于损坏状态时，有时会很有用。
---
---
title: React Native 的新架构
description: 了解 React Native 的“新架构”，以及为何以及如何迁移到它。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/new-architecture/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# React Native 的新架构
了解 React Native 的“新架构”，以及为何以及如何迁移到它。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
> **SDK 55 及以后版本完全运行在新架构上。** 新架构始终处于启用状态，且无法禁用。如果你需要使用旧版架构，请使用 SDK 54 或更早版本。
新架构是我们用来描述 React Native 内部全面重构的名称。它也用于解决原始 React Native 架构在 Meta 和其他公司多年生产使用中发现的局限性。
在本指南中，我们将介绍如何在 Expo 项目中使用新架构。
[新架构来了](https://reactnative.dev/blog/2024/10/23/the-new-architecture-is-here) — Meta 的 React Native 团队发布的一篇博客文章，概述了新架构的特性以及构建它的动机。
[React Native 0.82 - 一个新时代](https://reactnative.dev/blog/2025/10/08/react-native-0.82) — React Native 0.82 是第一个完全运行在新架构上的版本。SDK 55 使用 React Native 0.83，并继承了这一行为。
为什么要迁移到新架构？
**新架构是 React Native 的现在和未来**。从 React Native 0.82 开始，新架构始终处于启用状态，且无法禁用。SDK 55 使用 React Native 0.83，并继承了这一行为。[旧版架构已于 2025 年 6 月被冻结](https://github.com/reactwg/react-native-new-architecture/discussions/290)，这意味着它不会再开发新功能或修复 bug。
**新的 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)，而这些在旧版架构中都没有实现。许多流行库现在也只支持新架构。
**如果你使用的是 SDK 54 或更早版本**，仍然可以通过将 `newArchEnabled` 设为 `false` 来使用旧版架构。但是，在升级到 SDK 55 或更高版本之前，你需要迁移到新架构。
## Expo 工具与新架构
从 SDK 53 开始，Expo SDK 中所有 `expo-*` 包都支持新架构（包括 [bridgeless](https://github.com/reactwg/react-native-new-architecture/discussions/154)）。[了解更多已知问题](/guides/new-architecture#known-issues-in-expo-sdk-libraries)。
此外，所有使用 [Expo Modules API](/modules/overview) 编写的模块默认都支持新架构！因此，如果你已经使用该 API 构建了自己的原生模块，那么无需额外工作即可在新架构中使用它们。
**截至 2026 年 1 月，使用 [EAS Build](/build/introduction) 构建的 SDK 54 项目中，约有 83% 使用了新架构**。
## 第三方库与新架构
许多最流行库的兼容性状态都可以在 [React Native Directory](https://reactnative.directory/) 上跟踪（[了解第三方库中的已知问题](/guides/new-architecture#known-issues-in-third-party-libraries)）。我们已在 Expo Doctor 中集成了与 React Native Directory 的工具，以帮助你验证依赖项，因此你可以快速了解哪些库无人维护，以及哪些库与新架构不兼容或尚未测试。
### 使用 React Native Directory 验证依赖项
运行 `npx expo-doctor` 来检查你的依赖项是否符合 React Native Directory 中的数据。
```sh
npx expo-doctor@latest
```
你可以在 **package.json** 文件中配置 React Native Directory 检查。例如，如果你想将某个包排除在验证之外：
```json
{
"expo": {
"doctor": {
"reactNativeDirectoryCheck": {
"exclude": ["react-redux"]
}
}
}
}
```
查看所有可用选项
- **enabled**：如果为 `true`，当某些包不在 React Native Directory 中时，该检查会发出警告。将其设为 `false` 可禁用此行为。在 SDK 52 及更高版本中，此项默认设为 `true`，否则默认设为 `false`。你也可以使用 `EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK` 环境变量覆盖此设置（0 表示 `false`，1 表示 `true`）。
- **exclude**：列出你想从检查中排除的包。支持精确包名和正则表达式模式。例如，`["exact-package", "/or-a-regex-.*/"]`。
- **listUnknownPackages**：默认情况下，当某些包不在 React Native Directory 中时，该检查会发出警告。将其设为 false 可禁用此行为。
## 使用新架构初始化新项目
**从 SDK 52 开始**，所有新项目在初始化时默认都会启用新架构。
```sh
npx create-expo-app@latest --template default@sdk-55
```
## 在现有项目中启用新架构
**在 SDK 55 及以后版本中，新架构始终处于启用状态**。没有选项可以将其禁用。SDK 55 使用 React Native 0.83。[React Native 0.82 是第一个移除禁用新架构选项的版本](https://reactnative.dev/blog/2025/10/08/react-native-0.82)，并且这适用于所有更高版本。
如果你之前在应用配置中使用了 `newArchEnabled: false`，这个设置将被忽略。请将其从配置中移除，以免造成混淆。
你是在一个裸 React Native 应用中启用新架构吗？
如果你使用的是 Expo SDK 53 或更高版本，新架构默认已启用。对于 SDK 55 及以后版本，新架构始终处于启用状态，且无法禁用。以下说明适用于 SDK 52 及更早版本的项目。
- **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) 部分。
## 在现有项目中禁用新架构
> **SDK 55 及以后不支持禁用新架构。** SDK 55 使用 React Native 0.83。从 [React Native 0.82 开始，禁用新架构的选项已被移除](https://reactnative.dev/blog/2025/10/08/react-native-0.82)，因此将 `newArchEnabled` 设为 `false` 不会产生任何效果。如果你需要使用旧版架构，请使用 SDK 54 或更早版本。
> Expo Go 仅支持新架构。
在 **SDK 54 及更早版本** 中，你可以通过在应用配置中将 `newArchEnabled` 属性设为 `false` 来退出新架构，并创建一个 [开发构建](/develop/development-builds/introduction)。
```json
{
"expo": {
"newArchEnabled": false
}
}
```
你是在一个裸 React Native 应用中禁用新架构吗（SDK 54 及更早）？
- **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 正在努力让新架构成为所有新应用的默认选项，并确保尽可能轻松地迁移现有应用。不过，新架构不仅仅是一个名称 — React Native 的许多内部机制都已从头开始重新设计并重建。因此，在你的应用中启用新架构时，可能会遇到一些问题。以下是一些用于排查这些问题的建议。
即使我使用的某些库不受支持，我还可以尝试新架构吗？
即使你使用的某些库不受支持，你也许仍然可以在应用中尝试新架构，但这需要暂时移除这些库。在你的仓库中创建一个新分支，并移除所有不兼容的库，直到你的应用可以运行。这将帮助你了解在完全迁移到新架构之前，还需要哪些库进行适配。我们建议在这些库的仓库中创建 issue 或 pull request，帮助它们与新架构兼容。或者，你也可以切换到其他与新架构兼容的库。请参阅 [React Native Directory](https://reactnative.directory/) 查找兼容的库。
React Native 中的已知问题
请参阅 [React Native GitHub 仓库中带有“Type: New Architecture”标签的问题](https://github.com/facebook/react-native/issues?q=is%3Aopen+is%3Aissue+label%3A%22Type%3A+New+Architecture%22)。
Expo 库中的已知问题
Expo 库中没有针对新架构的已知问题。
第三方库中的已知问题
自 React Native 0.74 起，默认启用了多种互操作层。这使得许多为旧架构构建的库无需任何更改即可在新架构上运行。不过，这种互操作并不完美，因此有些库仍需要更新。最可能需要更新的库是那些包含或依赖第三方原生代码的库。[了解有关新架构中库支持的更多信息](https://github.com/reactwg/react-native-new-architecture/discussions/167)。
请参阅 [React Native Directory](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`。
启用新架构后我的构建失败了
这并不完全令人意外！并非所有库都已兼容，在某些情况下，兼容性也是最近才添加的，因此你需要确保将库更新到最新版本。阅读日志以确定是哪个库不兼容。同时，运行 `npx expo-doctor@latest`，根据 React Native Directory 中的数据检查你的依赖项。
当你使用某个库的最新版本但它仍不兼容时，请将你遇到的任何问题报告到相应的 GitHub 仓库。创建一个 [最小可复现示例](https://stackoverflow.com/help/minimal-reproducible-example)，并将问题报告给该库的作者。如果你认为问题出在 React Native 本身而不是某个库，请向 React Native 团队报告（同样需要提供最小可复现示例）。
---
---
title: React 编译器
description: 了解如何在 Expo 应用中启用和使用 React 编译器。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/react-compiler/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# React 编译器
了解如何在 Expo 应用中启用和使用 React 编译器。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
新的 [React Compiler](https://react.dev/learn/react-compiler) 会自动对组件和 hooks 进行 memoize，从而实现细粒度响应。这可以显著提升你应用的性能。你可以按照下面的说明在你的应用中启用它。
## 启用 React Compiler
[检查兼容性](https://react.dev/learn/react-compiler#checking-compatibility) 以了解你的项目与 React Compiler 的兼容程度。
```sh
npx react-compiler-healthcheck@latest
```
这通常会验证你的应用是否遵循了 [**React 规则**](https://react.dev/reference/rules)。
在你的项目中安装 `babel-plugin-react-compiler` 和 React compiler runtime：
Expo SDK 54 及更高版本会自动配置 Babel。
在你的应用配置文件中开启 React Compiler 实验特性：
```json
{
"expo": {
"experiments": {
"reactCompiler": true
}
}
}
```
### 启用 linter
> 未来，以下所有步骤都将由 Expo CLI 自动完成。
此外，你应该使用 ESLint 插件持续在你的项目中强制执行 React 规则。
运行 [`npx expo lint`](/guides/using-eslint#eslint) 以确保你的应用已设置好 ESLint，然后安装 React Compiler 的 ESLint 插件：
```sh
npx expo install eslint-plugin-react-compiler -- -D
```
更新你的 [ESLint 配置](/guides/using-eslint) 以包含该插件：
```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 Compiler：
配置 Babel 插件仅在特定文件或组件上运行。为此：
1. 如果你的项目没有 [**babel.config.js**](/versions/latest/config/babel)，请运行 `npx expo customize babel.config.js` 创建一个。
2. 将以下配置添加到 **babel.config.js** 中：
```js
module.exports = function (api) {
api.cache(true);
return {
presets: [
[
'babel-preset-expo',
{
'react-compiler': {
sources: filename => {
// 匹配要包含到 React Compiler 中的文件名。
return filename.includes('src/path/to/dir');
},
},
},
],
],
};
};
```
每当你更改 **babel.config.js** 文件时，都需要重启 Metro bundler 以应用这些更改：
```sh
npx expo start --clear
```
使用 `"use no memo"` 指令，针对特定组件或文件让 React Compiler 不生效。
```jsx
function MyComponent() {
'use no memo';
return Will not be optimized;
}
```
## 使用
> 要更好地理解 React Compiler 的工作方式，请查看 [React Playground](https://playground.react.dev/)。
改进主要是自动完成的。你可以移除 `useCallback`、`useMemo` 和 `React.memo` 的使用，改为依赖自动 memoization。类组件不会被优化，应改为迁移到函数组件。
Expo 对 React Compiler 的实现只会在应用代码上运行（不包括 node modules），并且只在为客户端打包时运行（服务端渲染中禁用）。
## 配置
你可以通过在 Babel 配置中使用 `react-compiler` 对象，向 React Compiler Babel 插件传递额外设置：
```js
module.exports = function (api) {
api.cache(true);
return {
presets: [
[
'babel-preset-expo',
{
'react-compiler': {
// 直接传递给 React Compiler Babel 插件。
compilationMode: 'all',
panicThreshold: 'all_errors',
},
web: {
'react-compiler': {
// 仅限 Web 的设置...
},
},
},
],
],
};
};
```
---
---
title: Expo Router 简介
description: Expo Router 是一个开源路由库，适用于使用 Expo 构建的 Universal React Native 应用程序。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/router/introduction/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# Expo Router 简介
Expo Router 是一个开源路由库，适用于使用 Expo 构建的 Universal React Native 应用程序。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
Expo Router 是一个用于 React Native 和 web 应用的基于文件的路由器。它允许你管理应用中屏幕之间的导航，使用户能够在应用 UI 的不同部分之间无缝切换，并在多个平台（Android、iOS 和 web）上使用相同的组件。
Expo Router 将来自 web 的最佳文件系统路由理念带入一个通用应用 — 让你的路由在每个平台上都能正常工作。当一个文件被添加到 **app** 目录时，该文件会自动成为你导航中的一个路由。
## 快速开始
我们建议使用 `create-expo-app` 创建一个新的 Expo 应用，以创建一个已经安装并配置好 Expo Router 库的项目：
```sh
# npm
npx create-expo-app@latest --template default@sdk-55
# yarn
yarn create expo-app --template default@sdk-55
# pnpm
pnpm create expo-app --template default@sdk-55
# bun
bun create expo --template default@sdk-55
```
> **注意：** 在 SDK 55 过渡期间，不带 `--template` 标志的 `create-expo-app@latest` 会创建一个 SDK 54 项目。如果你计划在实体设备上使用 Expo Go，请使用 SDK 54 项目。否则，请使用 `--template default@sdk-55` 来创建一个 SDK 55 项目。
现在，你可以通过运行以下命令启动项目：
```sh
npx expo start
```
- 若要在移动设备上查看你的应用，我们建议从 [Expo Go](/get-started/set-up-your-environment#how-would-you-like-to-develop) 开始。随着应用复杂度增加并且你需要更多控制时，你可以创建一个 [development build](/develop/development-builds/introduction)。
- 在终端 UI 中按 w 可在网页浏览器中打开项目。按 a 可打开 Android（需要 Android Studio），或按 i 可打开 iOS（需要安装 Xcode 的 macOS）。
## 资源
[Expo 教程](/tutorial/introduction) — 一个逐步指南，用于构建可在 Android、iOS 和 web 上运行的 Expo 应用。
[Expo Router API 参考](/versions/latest/sdk/router) — API 组件、hooks、方法和配置选项。
[Expo Router 视频播放列表](https://www.youtube.com/playlist?list=PLsXDmrmFV_AT17JDf-otXSNE_eH7s0uDD) — 从核心概念到更复杂导航流程的教程系列。
## 主要特性
- **原生**：构建于我们强大的 [React Navigation 套件](https://reactnavigation.org/) 之上，Expo Router 导航从默认开始就是真正原生且针对平台优化的。
- **可分享**：应用中的每个屏幕都会自动支持 [深度链接](/linking/overview)，使应用中的任何路由都可以通过链接分享。
- **离线优先**：应用会被缓存并以离线优先方式运行，在你发布新版本时自动更新。无需网络连接或服务器即可处理所有传入的原生 URL。
- **已优化**：路由会通过 [生产环境中的懒加载评估](/router/web/async-routes) 自动优化，并在开发环境中进行延迟打包。
- **迭代**：在 Android、iOS 和 web 上提供通用的 Fast Refresh，同时在打包器中进行产物记忆化，以帮助你在大规模项目中保持快速推进。
- **通用**：Android、iOS 和 web 共享统一的导航结构，并且可以在路由级别下沉到平台特定 API。
- **可发现**：Expo Router 在 web 上支持构建时 [静态渲染](/router/web/static-rendering)，并支持原生端的 [通用链接](/linking/overview)。这意味着你的应用内容可以被搜索引擎索引。
## 使用其他导航库
你可以在 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。
## 常见问题
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/web/async-routes) 功能为所有人提供了懒打包。此前，懒打包只在 Meta 内部用于构建 Facebook 应用。
我可以在现有的 React Native 应用中使用 Expo Router 吗？
可以，Expo Router 是通用 React Native 应用的框架。由于路由器与打包器之间有着深度耦合，Expo Router 仅在使用 Metro 的 Expo CLI 项目中可用。幸运的是，你也可以在任何 React Native 项目中 [使用 Expo CLI](/bare/using-expo-cli)！
基于文件的路由有什么好处？
- 文件系统是一个广为人知且易于理解的概念。更简单的心智模型使得教育新成员并扩展你的应用更容易。
- 让新用户最快上手的方式，是让他们打开一个通用链接，根据他们是否安装了应用，自动打开正确的屏幕或网站。这个技巧非常高级，通常只有能负担得起平台间一致性开发和维护的大公司才会拥有。但借助 Expo 的基于文件的路由，你可以开箱即用地获得这一功能！
- 重构更容易，因为你可以移动文件，而无需更新任何 imports 或路由组件。
- Expo Router 能够自动对路由进行静态类型化。这能确保你只能链接到有效路由，并且不能链接到不存在的路由。类型化路由还会在链接损坏时给出类型错误，从而改善重构体验。
- Async Routes（代码分割）可提升开发速度，尤其是在大型项目中。它们也让升级更容易，因为错误会被隔离到单个路由，这意味着你可以逐页增量更新或重构应用，而不是像传统 React Native 那样一次性全部处理。
- 深度链接始终有效，适用于每个页面。这使得分享应用中任何内容的链接成为可能，这对于推广应用、收集 bug 报告、E2E 测试、自动化截图等都非常有帮助。
- Expo Head 使用自动链接来实现深度原生集成。像 Quick Notes、Handoff、Siri 上下文以及通用链接这类功能只需要配置，不需要代码改动。这使得与你的用户所拥有的整个智能设备生态系统实现完美的垂直集成成为可能，从而带来只有通用应用（web ⇄ native）才能实现的用户体验。
- Expo Router 能够自动在 web 上静态渲染每个页面，从而实现真正的 SEO 和应用内容的完全可发现性。这只有依赖基于文件的约定才有可能。
- **Expo CLI** 在应用遵循已知约定时，可以推断出大量信息。例如，我们可以实现按路由自动拆分打包，或者为你的网站自动生成站点地图。当你的应用只有单一入口点时，这是不可能的。
- 像通知和主屏幕小组件这样的再互动功能更容易集成，因为你只需在应用任意位置拦截启动和深度链接，并附带查询参数即可。
- 和 web 一样，分析和错误报告可以很容易地配置为自动包含路由名称，这对于调试和理解用户行为非常有用。
为什么我应该用 Expo Router 而不是 React Navigation？
Expo Router 和 React Navigation 都是来自 Expo 团队的库。我们在 React Navigation 之上构建了 Expo Router，以实现基于文件路由的优势。Expo Router 是 React Navigation 的超集，这意味着你可以在 Expo Router 中使用任何 React Navigation 组件和 API。
如果基于文件的路由不适合你的项目，你可以直接使用 React Navigation，并手动设置路由、类型和链接。
我该如何对我的 Expo Router 网站进行服务器渲染？
Expo Router 支持基本的静态渲染（SSG）。服务器端渲染目前需要自定义基础设施来搭建。
## 下一步
[手动安装](/router/installation) — 关于如何开始并将 Expo Router 添加到你现有应用中的详细说明。
[Router 101](/router/basics/core-concepts) — 如需了解核心概念、表示模式、导航布局以及常见导航模式，请从 Router 101 部分开始。
[示例应用](https://github.com/expo/expo/tree/main/templates/expo-template-tabs) — 在 GitHub 上查看示例应用的源代码。
---
---
title: 手动安装
description: 了解如何通过这些详细说明将 Expo Router 添加到现有项目中。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/router/installation/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 手动安装
了解如何通过这些详细说明将 Expo Router 添加到现有项目中。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
如果你已经有一个现有项目，并且想添加 Expo Router，请按照以下步骤操作。对于新项目，请参阅介绍指南中的 [Quick start](/router/introduction#quick-start)。
### 前置条件
请确保你的电脑已[配置好运行 Expo 应用](/get-started/create-a-project)。
### 安装依赖
你需要安装以下依赖：
```sh
npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar
```
上述命令会安装与你项目当前使用的 Expo SDK 版本兼容的这些库版本。
### 设置入口点
对于 `main` 属性，请在 **package.json** 中将其值设为 `expo-router/entry`。初始客户端文件是 [**src/app/_layout.tsx**](/router/reference/src-directory)（如果未使用 **src** 目录，则为 [**app/_layout.tsx**](/router/basics/navigation-layouts#root-layout)）。
```json
{
"main": "expo-router/entry"
}
```
自定义入口点以初始化并加载副作用
你可以在 Expo Router 项目中创建一个自定义入口点，在应用加载根布局（**src/app/_layout.tsx**）之前初始化并加载副作用。下面是一些常见的自定义入口点使用场景：
- 初始化全局服务，例如分析、错误报告等。
- 设置 polyfill
- 使用来自 `react-native` 的 `LogBox` 忽略特定日志
1. 在项目根目录下创建一个新文件，例如 **index.js**。创建此文件后，项目结构应如下所示：
`src`
`app`
`_layout.tsx`
`index.js`
`package.json`
`Other project files`
2. 在文件中导入或添加你的自定义配置。然后，导入 `expo-router/entry` 来注册应用入口。记住一定要最后导入它，以确保在应用渲染之前所有配置都已正确设置。
```js
// 首先导入副作用和服务
// 初始化服务
// 通过 Expo Router 注册应用入口
import 'expo-router/entry';
```
3. 更新 **package.json** 中的 `main` 属性，使其指向新的入口文件。
```json
{
"main": "index.js"
}
```
### 修改项目配置
在你的[应用配置](/workflow/configuration)中添加一个深度链接 `scheme`，并启用[类型化路由](/router/reference/typed-routes)：
```json
{
"scheme": "your-app-scheme",
"experiments": {
"typedRoutes": true
}
}
```
如果你正在为 web 开发应用，请安装以下依赖：
```sh
npx expo install react-native-web react-dom
```
然后，通过在你的[应用配置](/workflow/configuration)中添加以下内容来启用 [Metro web](/guides/customizing-metro#adding-web-support-to-metro) 支持：
```json
{
"web": {
"bundler": "metro"
}
}
```
### 修改 babel.config.js
如果你的项目有一个 **babel.config.js** 文件，请确保将 `babel-preset-expo` 用作 `preset`。如果你不需要任何自定义 Babel 配置，可以直接删除该文件：
```js
module.exports = function (api) {
api.cache(true);
return {
presets: ['babel-preset-expo'],
};
};
```
### 配置路径别名
如果你正在使用 [`src` 目录](/router/reference/src-directory)，请在 **tsconfig.json** 中添加路径别名，这样你就可以使用像 `@/components/button` 这样的简短导入路径，而不是相对路径：
```json
{
"extends": "expo/tsconfig.base",
"compilerOptions": {
"strict": true,
"paths": {
"@/*": ["./src/*"]
}
},
"include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"]
}
```
上面的示例中，`@/*` 别名映射到 **src** 目录。
### 清除打包器缓存
更新配置后，运行以下命令来清除打包器缓存：
```sh
npx expo start --clear
```
### 更新 resolutions
如果你正在从较旧版本的 Expo Router 升级，请确保删除 **package.json** 中所有过时的 Yarn resolutions 或 npm overrides。具体来说，请从 **package.json** 中删除 `metro`、`metro-resolver`、`react-refresh` 的 resolutions。
---
---
title: Expo Router 中基于文件路由的核心概念
description: 了解 Expo Router 的基本规则，以及它与其余代码的关系。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/router/basics/core-concepts/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# Expo Router 中基于文件路由的核心概念
了解 Expo Router 的基本规则，以及它与其余代码的关系。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
在深入了解如何使用 Expo Router 构建应用的导航树之前，我们先来理解构成 Expo Router 中基于文件路由基础的核心概念，以及 Expo Router 项目的结构可能与其他 React Native 项目有何不同。
## Expo Router 的规则
### 1\. 所有屏幕/页面都是 src/app 目录中的文件
你应用中的所有导航路由都由 [**src/app**](/router/reference/src-directory) 目录中的文件和子目录定义。**src/app** 目录中的每个文件都有一个默认导出，用于定义你应用中的一个独立页面（特殊的 **_layout** 文件除外）。
因此，**src/app** 中的目录会将相关的屏幕分组在一起。
### 2\. 所有页面都有一个 URL
所有页面都有一个与 **src/app** 目录中该文件位置相匹配的 URL 路径，你可以在网页浏览器的地址栏中使用它来导航到该页面，或者在原生移动应用中将其作为应用专属的深度链接。这就是 Expo Router 支持 [通用深度链接](/linking/overview) 的含义。你应用中的所有页面都可以通过 URL 进行导航，而不受平台限制。
### 3\. 第一个 index.tsx 是初始路由
使用 Expo Router 时，你不会在代码中定义初始路由或第一个屏幕。相反，当你打开应用时，Expo Router 会寻找匹配 `/` URL 的第一个 **index.tsx** 文件。在 [默认模板](/router/installation#quick-start) 中，这个文件是 **src/app/index.tsx**。如果应用用户默认应该从导航树更深处开始，你可以使用一个 [路由组](/router/basics/notation#parentheses)（目录名被圆括号包围的目录），而它不会被计入 URL 的一部分。如果你希望第一个屏幕是一个标签页组，你可以把所有标签页页面都放在 **src/app/(tabs)** 目录中，并将默认标签页定义为 **index.tsx**。这样，`/` URL 会直接将用户带到 **src/app/(tabs)/index.tsx** 文件。
### 4\. 根目录 _layout.tsx 取代 App.jsx/tsx
每个项目都应该在 **src/app** 目录下直接包含一个 **_layout.tsx** 文件。这个文件会在应用中的任何其他路由之前渲染，你可以把以前可能放在 **App.jsx** 文件中的初始化代码放在这里，例如加载字体、设置主题提供者，或者与启动画面交互。例如，默认模板会用 `ThemeProvider` 包裹应用，以支持深色和浅色模式，并在这个文件中渲染 `AppTabs` 组件。
### 5\. 默认模板使用平台特定的标签页
默认模板会根据平台使用两种不同的标签页实现。在 Android 和 iOS 上，标签页使用 [原生标签页](/router/advanced/native-tabs) 渲染，它使用平台内置的标签栏，具有原生的外观和交互体验。在 web 上，标签页使用来自 `expo-router/ui` 的 [自定义标签页](/router/advanced/custom-tabs) 渲染，这些是无样式且灵活的组件，允许完全控制标签栏的外观。
这通过 [平台特定文件扩展名](/router/advanced/platform-specific-modules) 来实现。标签页组件定义在两个文件中：用于 Android 和 iOS 的 **src/components/app-tabs.native.tsx**，以及用于 web 的 **src/components/app-tabs.tsx**。Expo 的模块解析会根据平台自动选择正确的文件。采用这种模式是因为原生平台拥有系统标签栏，能够提供诸如点击回到顶部和原生动画等预期行为，而 web 需要一个符合典型网站导航模式的自定义样式标签栏。
### 6\. 非导航组件放在 src/app 目录之外
在 Expo Router 中，**src/app** 目录专门用于定义应用的路由。应用的其他部分，比如组件、hooks、工具函数等等，应该放在其他目录中，例如 **src/components**、**src/hooks** 和 **src/constants**。如果你把一个非路由文件放在 **src/app** 目录中，Expo Router 会尝试把它当作路由来处理。
### 7\. 底层仍然是 React Navigation
虽然这听起来和 React Navigation 有很大不同，但 Expo Router 实际上是建立在 React Navigation 之上的。你可以把 Expo Router 看作是 Expo CLI 的一种优化，它将你的文件结构转换为你过去在自己的代码中定义的 React Navigation 组件。
这也意味着，你通常可以参考 React Navigation 文档来了解如何设置导航样式或配置导航，因为默认的栈导航器和标签导航器使用的是完全相同的选项。
## 将 Expo Router 的规则应用起来
让我们把这些 Expo Router 的基础规则应用到以下项目文件结构中，快速识别关键元素：
`src`
`app`
`index.tsx`
`home.tsx`
`_layout.tsx`
`profile`
`friends.tsx`
`components`
`app-tabs.native.tsx`
`app-tabs.tsx`
`text-field.tsx`
`toolbar.tsx`
- **src/app/index.tsx** 是初始路由，当你打开应用或访问网页应用的根 URL 时，它会首先显示。
- **src/app/home.tsx** 是一个路由为 `/home` 的页面，因此你可以在浏览器中使用类似 `yourapp.com/home` 的 URL，或者在原生应用中使用 `yourapp://home` 来导航到它。
- **src/app/_layout.tsx** 是根布局。你以前可能放在 **App.jsx** 中的任何初始化代码都应该放在这里。
- **src/app/profile/friends.tsx** 是一个路由为 `/profile/friends` 的页面。
- **src/components/app-tabs.native.tsx** 和 **src/components/app-tabs.tsx** 是 [平台特定](/router/advanced/platform-specific-modules) 的标签页组件。**.native.tsx** 文件用于 Android 和 iOS，而 **.tsx** 文件用于 web。根布局会导入这些组件来渲染标签导航器。
- **src/components/text-field.tsx** 和 **src/components/toolbar.tsx** 不在 **src/app** 目录中，因此它们不会被视为页面。它们没有 URL，也不能作为导航操作的目标。不过，它们可以作为组件在 **src/app** 目录中的页面里使用。
---
---
title: Expo Router 标记法
description: 了解如何使用特殊文件名和标记，在项目的文件结构中以富有表现力的方式定义应用的导航树。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/router/basics/notation/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# Expo Router 标记法
了解如何使用特殊文件名和标记，在项目的文件结构中以富有表现力的方式定义应用的导航树。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
当你查看一个典型的 Expo Router 项目中的 **src/app** 目录时，你会发现里面远不只是一些简单的文件名和目录名。括号和方括号是什么意思？让我们来了解一下基于文件的路由标记的意义，以及它如何让你定义复杂的导航模式。
## 路由标记的类型
### 简单名称/无标记
`src`
`app`
`home.tsx`
`feed`
`favorites.tsx`
没有任何标记的普通文件名和目录名表示 _静态路由_。它们的 URL 与它们在文件树中的显示完全一致。比如，**feed** 目录中的一个名为 **favorites.tsx** 的文件，其 URL 将是 `/feed/favorites`。
### 方括号
`src`
`app`
`[userName].tsx`
`products`
`[productId]`
`index.tsx`
如果你在文件名或目录名中看到方括号，那么你看到的是一个 _动态路由_。路由名称包含一个参数，这个参数可在渲染页面时使用。这个参数既可以出现在目录名中，也可以出现在文件名中。例如，名为 **[userName].tsx** 的文件会匹配 `/evanbacon`、`/expo` 或其他用户名。然后，你可以在页面内部使用 `useLocalSearchParams` 钩子访问该参数，并据此加载该特定用户的数据。
### 括号
`src`
`app`
`(home)`
`index.tsx`
`settings.tsx`
目录名被括号包围表示一个 _路由组_。这些目录用于将路由分组在一起，而不影响 URL。例如，名为 **src/app/(home)/settings.tsx** 的文件，其 URL 将是 `/settings`，即使它并不直接位于 **src/app** 目录下。
路由组可用于简单的组织目的，但在定义路由之间更复杂的关系时，往往会变得更加重要。
### index.tsx 文件
`src`
`app`
`(home)`
`index.tsx`
`profile`
`index.tsx`
和网页端一样，**index.tsx** 文件表示某个目录的默认路由。例如，名为 **profile/index.tsx** 的文件将匹配 `/profile`。名为 **(home)/index.tsx** 的文件将匹配 `/`，实际上成为整个应用的默认路由。
### _layout.tsx 文件
`src`
`app`
`_layout.tsx`
`(home)`
`_layout.tsx`
`feed`
`_layout.tsx`
**_layout.tsx** 文件是特殊文件，本身不是页面，而是定义目录中各组路由之间如何相互关联。如果一个路由目录被组织成堆栈或标签页，那么布局路由就是你通过使用 stack navigator 或 tab navigator 组件来定义这种关系的地方。
布局路由会先于其目录中的实际页面路由渲染。这意味着，直接位于 **src/app** 目录下的 **_layout.tsx** 会在应用中的其他内容之前渲染，并且这里是你放置初始化代码的地方，这些代码以前可能位于 **App.jsx** 文件中。
### 加号
`src`
`app`
`+not-found.tsx`
`+html.tsx`
`+native-intent.tsx`
`+middleware.ts`
包含 `+` 的路由对 Expo Router 有特殊意义，并用于特定用途。以下是一些示例：
- [`+not-found`](/router/error-handling#unmatched-routes)，用于捕获所有未匹配到你应用中路由的请求。
- [`+html`](/router/web/static-rendering#root-html) 用于自定义应用在网页端使用的 HTML 基础模板。
- [`+native-intent`](/router/advanced/native-intent) 用于处理进入应用但未匹配到特定路由的深度链接，例如由第三方服务生成的链接。
- [`+middleware`](/router/web/middleware) 用于在路由渲染之前运行代码，使你能够对每个请求执行身份验证或重定向等任务。
> 某些路径名（如 `/assets`）已被 Metro 和 Expo Router 保留。请避免将它们用于路由。完整列表请参见 [Reserved paths](/router/reference/reserved-paths)。
## 路由标记的应用
考虑下面的项目文件结构，以识别所表示的不同类型路由：
`src`
`app`
`(home)`
`_layout.tsx`
`index.tsx`
`feed.tsx`
`profile.tsx`
`_layout.tsx`
`users`
`[userId].tsx`
`+not-found.tsx`
`about.tsx`
- **src/app/about.tsx** 是一个静态路由，匹配 `/about`。
- **src/app/users/[userId].tsx** 是一个动态路由，匹配 `/users/123`、`/users/456` 等。
- **src/app/(home)** 是一个路由组。它不会计入 URL，因此 `/feed` 会匹配 **src/app/(home)/feed.tsx**。
- **src/app/(home)/index.tsx** 是 **(home)** 目录的默认路由，并会匹配 `/` URL。
- **src/app/(home)/_layout.tsx** 是一个布局文件，定义 **src/app/(home)/** 内的页面如何相互关联。
- **src/app/_layout.tsx** 是根布局文件，会在应用中的任何其他路由之前渲染。
- **src/app/+not-found.tsx** 是一个特殊路由，当用户导航到应用中不存在的路由时会显示它。
---
---
title: Expo Router 中的导航布局
description: 了解如何通过使用目录和布局文件来构建页面之间的不同关系。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/router/basics/navigation-layouts/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# Expo Router 中的导航布局
了解如何通过使用目录和布局文件来构建页面之间的不同关系。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
[Expo Router 布局文件介绍](https://www.youtube.com/watch?v=Yh6Qlg2CYwQ) — 什么是布局文件、如何在屏幕之间导航，以及如何使用重定向阻止访问。
**src/app** 目录中的每个目录（包括 **src/app** 本身）都可以通过该目录内的 **_layout.tsx** 文件定义一个布局。这个文件定义了该目录下所有页面的排列方式。你可以在这里定义栈导航器、标签导航器、抽屉导航器，或任何你希望用于该目录页面的其他布局。布局文件会导出一个默认组件，它会在你导航到该目录中的任意页面之前先被渲染。
让我们来看几个常见的布局场景。
## 根布局
几乎每个应用都会在 **src/app** 目录中直接放置一个 **_layout.tsx** 文件。这就是根布局，代表你导航的入口点。除了描述应用的顶层导航器之外，这个文件也是你放置之前可能写在 **App.jsx** 文件中的初始化代码的地方，例如加载字体、与启动画面交互，或添加上下文提供器。
下面是一个根布局示例：
```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 ;
}
```
上面的示例会先显示启动画面，然后在字体加载完成后渲染一个栈导航器，这将使你的应用继续进入初始路由。
## 栈
你可以像上面那样在根布局中实现栈导航器，也可以在目录中的任何其他布局文件中实现。假设你有如下所示、在某个目录内包含栈的文件结构：
`src`
`app`
`products`
`_layout.tsx`
`index.tsx`
`[productId].tsx`
`accessories`
`index.tsx`
如果你希望 **src/app/products** 目录中的所有内容都以栈关系排列，那么在 **_layout.tsx** 文件中返回一个 `Stack` 组件：
```tsx
import { Stack } from 'expo-router';
export default function StackLayout() {
return ;
}
```
当你导航到 `/products` 时，它会先进入默认路由，也就是 **products/index.tsx**。如果你导航到 `/products/123`，那么该页面会被压入栈中。默认情况下，栈会在标题栏中渲染一个返回按钮，用于将当前页面从栈中弹出，从而返回到上一页。即使某个页面不可见，只要它仍然被压入栈中，它就仍然在被渲染。
`Stack` 组件实现了 [React Navigation 的原生栈](https://reactnavigation.org/docs/native-stack-navigator/)，并且可以使用相同的屏幕选项。不过，你不必在导航器中显式定义页面。目录中的文件会自动被视为栈中的可用路由。但是，如果你想定义屏幕选项，可以在 `Stack` 组件内部添加一个 `Stack.Screen` 组件。`name` 属性应与路由名称匹配，但你不需要提供 `component` 属性；Expo Router 会自动映射：
```tsx
import { Stack } from 'expo-router';
export default function StackLayout() {
return (
);
}
```
虽然可以嵌套导航器，但只有在真正需要时才应这样做。在上面的示例中，如果你想将 **products/accessories/index.tsx** 压入栈中，那么就没有必要在 **accessories** 目录下额外创建一个带有 `Stack` 导航器的 **_layout.tsx**。那样会在第一个栈中再定义另一个栈。添加仅影响 URL 的目录是可以的，否则就使用与父目录相同的导航器。
## 标签页
Expo Router 提供了多种实现标签导航的方式，具体取决于你的需求。
### JavaScript 标签页
你可以在布局文件中使用 `Tabs` 组件实现基于 JavaScript 的标签导航器。该目录下直接包含的所有路由都会被视为标签页。请看下面的文件结构：
`src`
`app`
`(tabs)`
`_layout.tsx`
`index.tsx`
`feed.tsx`
`profile.tsx`
在 **_layout.tsx** 文件中，返回一个 `Tabs` 组件：
```tsx
import { Tabs } from 'expo-router';
import MaterialIcons from '@expo/vector-icons/MaterialIcons';
export default function TabLayout() {
return (
,
}}
/>
);
}
```
这会使 **index.tsx**、**feed.tsx** 和 **profile.tsx** 文件一起出现在同一个底部标签导航器中。这个 `Tabs` 组件使用了 [React Navigation 的原生底部标签](https://reactnavigation.org/docs/bottom-tab-navigator/)，并支持相同的选项。
对于 `Tabs`，你通常会希望在导航器中定义这些标签，因为这会影响标签的显示顺序、标题以及标签内的图标。index 路由将是默认选中的标签页。
### 原生标签页
在 Android 和 iOS 上，你可以使用 [原生标签页](/router/advanced/native-tabs) 来渲染平台内置的标签栏。原生标签页提供了符合预期的平台行为，例如点击时滚动到顶部、原生动画，以及原生的外观和体验。
与 JavaScript 标签页一样，原生标签页也可以在路由组目录中的布局文件里使用：
`src`
`app`
`(tabs)`
`_layout.tsx`
`index.tsx`
`feed.tsx`
`profile.tsx`
```tsx
import { NativeTabs } from 'expo-router/unstable-native-tabs';
export default function TabLayout() {
return (
首页
动态
个人资料
);
}
```
### 平台特定标签页
由于原生标签页仅适用于 Android 和 iOS，一个常见模式是使用 [平台特定的文件扩展名](/router/advanced/platform-specific-modules) 为原生端和 web 提供不同的标签实现。根布局渲染一个标签组件，而 Expo 的模块解析会根据平台自动选择正确的文件。
`src`
`app`
`_layout.tsx`
`index.tsx`
`explore.tsx`
`components`
`app-tabs.native.tsx``原生标签页（Android 和 iOS）`
`app-tabs.tsx``自定义标签页（web）`
根布局会导入并渲染 `AppTabs` 组件。**app-tabs.native.tsx** 用于 Android 和 iOS，**app-tabs.tsx** 用于 web：
```tsx
import AppTabs from '@/components/app-tabs';
export default function RootLayout() {
return ;
}
```
在 Android 和 iOS 上，**app-tabs.native.tsx** 使用 [原生标签页](/router/advanced/native-tabs)：
```tsx
import { NativeTabs } from 'expo-router/native-tabs';
export default function AppTabs() {
return (
首页
探索
);
}
```
在 web 上，**app-tabs.tsx** 使用来自 `expo-router/ui` 的 [自定义标签页](/router/advanced/custom-tabs)，它们是不带样式且灵活的组件：
```tsx
import { Tabs, TabList, TabTrigger, TabSlot } from 'expo-router/ui';
export default function AppTabs() {
return (
首页
探索
);
}
```
## 插槽
在某些情况下，你可能希望使用不带导航器的布局。这对于在当前路由外包裹一个头部或底部，或者在某个目录内的任意路由上方显示一个模态框都很有帮助。在这种情况下，你可以使用 `Slot` 组件，它充当当前子路由的占位符。
请看下面的文件结构：
`src`
`app`
`social`
`_layout.tsx`
`index.tsx`
`feed.tsx`
`profile.tsx`
例如，你可能希望用头部和底部将 **social** 目录中的任意路由包裹起来，但你又希望页面之间的导航只是简单地替换当前页面，而不是将新页面压入栈中，然后再通过“返回”导航操作将其弹出。在 **_layout.tsx** 文件中，返回一个由头部和底部包裹的 `Slot` 组件：
```tsx
import { Slot } from 'expo-router';
export default function Layout() {
return (
<>
);
}
```
## 其他布局
这些只是一些常见布局的示例，帮助你了解其工作方式。你还可以通过布局实现更多功能：
- 实现一个 [Drawer 导航器](/router/advanced/drawer)
- 在 Android 和 iOS 上使用 [原生标签页](/router/advanced/native-tabs) 来实现平台原生的标签栏
- 用 [完全自定义的标签页](/router/advanced/custom-tabs) 替换默认标签页
- 使用 [模态框](/router/advanced/modals) 来显示一个带透明效果的页面，使其下方仍能看到父级导航器
- [适配任何与 React Navigation 兼容的导航器](/versions/latest/sdk/router#withlayoutcontextnav-processor)，包括顶部标签页、底部抽屉等
---
---
title: 在 Expo Router 中在页面之间导航
description: 了解在 Expo Router 中链接到页面和导航到页面的不同方式。
---
## Submitting Feedback
If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/router/basics/navigation/","feedback":"🤖 Agent feedback: "}'
Only submit when you have something specific and actionable to report.
# 在 Expo Router 中在页面之间导航
了解在 Expo Router 中链接到页面和导航到页面的不同方式。
> For the complete documentation index, see [llms.txt](/llms.txt). Use this Use this file to discover all available pages.
一旦你的应用中有了几个页面并完成了它们的布局设置，就该开始在它们之间进行导航了。Expo Router 中的导航很像 React Navigation，但由于所有页面默认都有一个 URL，我们可以创建链接，并使用这些 URL 通过熟悉的 Web 模式在应用中移动。
## 使用 `useRouter` 的原生导航基础
和 React Navigation 一样，你可以在 `onPress` 处理函数中调用一个函数来导航到另一个页面。在 Expo Router 中，你可以使用 `useRouter` Hook 来访问导航函数：
```tsx
import { useRouter } from 'expo-router';
import { Button } from 'react-native';
export default function Home() {
const router = useRouter();
return