安装 Expo 路由

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

请按照以下步骤使用 Expo Router 库创建新项目或将其添加到现有项目中。

¥Find the steps below to create a new project with Expo Router library or add it to your existing project.

快速开始

¥Quick start

我们建议使用 create-expo-app 创建一个新的 Expo 应用，以创建一个已安装和配置 Expo Router 库的项目：

¥We recommend creating a new Expo app using create-expo-app to create a project with Expo Router library already installed and configured:

Terminal

- npx create-expo-app@latest

现在，你可以通过运行以下命令来启动你的项目：

¥Now, you can start your project by running:

Terminal

- npx expo start

要在移动设备上查看你的应用，我们建议从 Expo 开始。随着你的应用变得越来越复杂并且你需要更多控制，你可以创建开发构建。

¥To view your app on a mobile device, we recommend starting with Expo Go. As your application grows in complexity and you need more control, you can create a development build.
在终端 UI 中按 w 在 Web 浏览器中打开项目。对于 Android，按 a（需要 Android Studio），对于 iOS，按 i（需要带有 Xcode 的 macOS）。

¥Open the project in a web browser by pressing w in the Terminal UI. Press a for Android (Android Studio is required), or i for iOS (macOS with Xcode is required).

手动安装

¥Manual installation

如果你的项目之前是使用 Expo 创建的，但没有安装 Expo Router 库，请按照以下步骤操作。

¥Follow the steps below if you have a project that was previously created with Expo but does not have Expo Router library installed.

先决条件

¥Prerequisites

确保你的计算机是设置运行 Expo 应用。

¥Make sure your computer is set up for running an Expo app.

安装依赖

¥Install dependencies

你需要安装以下依赖：

¥You'll need to install the following dependencies:

Terminal

-

npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar

上述命令将安装与你的项目正在使用的 Expo SDK 版本兼容的这些库的版本。

¥The above command will install versions of these libraries that are compatible with the Expo SDK version your project is using.

Terminal

-

npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar react-native-gesture-handler

上述命令将安装与你的项目正在使用的 Expo SDK 版本兼容的这些库的版本。

¥The above command will install versions of these libraries that are compatible with the Expo SDK version your project is using.

设置入口点

¥Setup entry point

对于属性 main，使用 expo-router/entry 作为其在 package.json 中的值。初始客户端文件是 app/_layout.js。

¥For the property main, use the expo-router/entry as its value in the package.json. The initial client file is app/_layout.js.

package.json

{
  "main": "expo-router/entry"
}

删除 package.json 中的入口点或将其替换为 index.js 以明确：

¥Either delete the entry point in your package.json or replace it with index.js to be explicit:

package.json

{
  "main": "index.js"
}

在项目的根目录中创建一个新文件 index.js。如果它已经存在，请将其替换为以下内容：

¥Create a new file index.js in the root of your project. If it exists already, replace it with the following:

index.js

import 'expo-router/entry';

修改项目配置

¥Modify project configuration

在应用配置中添加深度链接 scheme：

¥Add a deep linking scheme in your app config:

app.json

{
  "scheme": "your-app-scheme"
}

如果你正在开发网络应用，请安装以下依赖：

¥If you are developing your app for web, install the following dependencies:

Terminal

- npx expo install react-native-web react-dom

然后，通过将以下内容添加到应用配置来启用 Metro Web 支持：

¥Then, enable Metro web support by adding the following to your app config:

app.json

{
  "web": {
    "bundler": "metro"
  }
}

修改 babel.config.js

¥Modify babel.config.js

确保在 babel.config.js 文件中使用 babel-preset-expo 作为 preset 或删除该文件：

¥Ensure you use babel-preset-expo as the preset, in the babel.config.js file or delete the file:

babel.config.js

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
  };
};

如果你要从早于 v3 的 Expo Router 版本进行升级，请删除 plugins: ['expo-router/babel']。expo-router/babel 已合并到 SDK 50 (Expo Router v3) 的 babel-preset-expo 中。

¥If you're upgrading from a version of Expo Router that is older than v3, remove the plugins: ['expo-router/babel']. expo-router/babel was merged in babel-preset-expo in SDK 50 (Expo Router v3).

将 expo-router/babel 插件作为 plugins 数组中的最后一项添加到项目的 babel.config.js 中：

¥Add expo-router/babel plugin as the last item in the plugins array to your project's babel.config.js:

babel.config.js

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['expo-router/babel'],
  };
};

清除打包器缓存

¥Clear bundler cache

更新 Babel 配置文件后，运行以下命令清除打包器缓存：

¥After updating the Babel config file, run the following command to clear the bundler cache:

Terminal

- npx expo start -c

更新决议

¥Update resolutions

如果你要从旧版本的 Expo Router 升级，请确保删除 package.json 中所有过时的 Yarn 解析或 npm 覆盖。具体来说，从 package.json 中删除 metro、metro-resolver、react-refresh 解析。

¥If you're upgrading from an older version of Expo Router, ensure you remove all outdated Yarn resolutions or npm overrides in your package.json. Specifically, remove metro, metro-resolver, react-refresh resolutions from your package.json.

Expo 路由至少需要 react-refresh@0.14.0。从 SDK 49 / Expo Router v2 开始，React Native 尚未升级，因此你需要通过设置 Yarn 解析或 npm 覆盖来强制升级 react-refresh 版本。

¥Expo Router requires at least react-refresh@0.14.0. React Native hasn't upgraded as of SDK 49 / Expo Router v2, so you need to force upgrade your react-refresh version by setting a Yarn resolution or npm override.

package.json

{
  %%placeholder-start%%... %%placeholder-end%%
  "resolutions": {
    "react-refresh": "~0.14.0"
  }
}

package.json

{
  %%placeholder-start%%... %%placeholder-end%%
  "overrides": {
    "react-refresh": "~0.14.0"
  }
}

Expo 路由至少需要 metro@0.76.0。如果你使用的 Expo SDK 版本低于 49，则需要通过设置 Yarn 解析或 npm 覆盖来强制升级 metro 版本。

¥Expo Router requires at least metro@0.76.0. If you are using Expo SDK version below 49, you will need to force upgrade your metro version by setting a Yarn resolution or npm override.

package.json

{
  "resolutions": {
    "metro": "0.76.0",
    "metro-resolver": "0.76.0"
  }
}

package.json

{
  "overrides": {
    "metro": "0.76.0",
    "metro-resolver": "0.76.0"
  }
}