手动安装

通过这些详细的说明，学习如何将 Expo Router 添加到现有项目中。

如果你已有现有项目并且想要添加 Expo Router，请按照以下步骤操作。对于新项目，请参阅介绍指南中的快速开始。

🌐 Follow the steps below if you have an existing project and want to add Expo Router. For new projects, see the Quick start in the introduction guide.

先决条件

1 要求

设置你的开发环境

确保你的计算机已设置好以运行 Expo 应用。

安装依赖

🌐 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.

设置入口点

🌐 Setup entry point

对于属性 main，在 package.json 中使用 expo-router/entry 作为其值。初始客户端文件是 src/app/_layout.tsx（如果不使用 src 目录，则为 app/_layout.tsx）。

🌐 For the property main, use the expo-router/entry as its value in the package.json. The initial client file is src/app/_layout.tsx (or app/_layout.tsx if not using the src directory).

package.json

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

自定义入口点以初始化和加载副作用

你可以在你的 Expo Router 项目中创建一个自定义入口点，以在应用加载根布局（src/app/_layout.tsx）之前初始化和加载副作用。以下是一些自定义入口点的常见情况：

🌐 You can create a custom entry point in your Expo Router project to initialize and load side-effects before your app loads the root layout (src/app/_layout.tsx). Below are some of the common cases for a custom entry point:

正在初始化全局服务，如分析、错误报告等。
设置 polyfill
使用 LogBox 从 react-native 忽略特定日志

在项目根目录下创建一个新文件，例如 index.js。创建该文件后，项目结构应如下所示：

src
app
_layout.tsx
index.js
package.json
Other project files
将你的自定义配置导入或添加到文件中。然后，导入 expo-router/entry 来注册应用入口。请记住始终最后导入它，以确保在应用渲染之前所有配置都已正确设置。
index.js
```
// Import side effects first and services

// Initialize services

// Register app entry through Expo Router
import 'expo-router/entry';
```
在 package.json 中更新 main 属性，以指向新的入口文件。
package.json
```
{
  "main": "index.js"
}
```

修改项目配置

🌐 Modify project configuration

在你的应用配置中添加深度链接 scheme 并启用类型化路由：

🌐 Add a deep linking scheme and enable typed routes in your app config:

app.json

{
  "expo": {
    "scheme": "your-app-scheme",
    "experiments": {
      "typedRoutes": true
    }
  }
}

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

🌐 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

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

修改 babel.config.js

🌐 Modify babel.config.js

如果你的项目有一个 babel.config.js 文件，确保你将 babel-preset-expo 用作 preset。如果你不需要任何自定义的 Babel 配置，你可以完全删除该文件：

🌐 If your project has a babel.config.js file, ensure you use babel-preset-expo as the preset. If you don't need any custom Babel configuration, you can delete the file entirely:

babel.config.js

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

配置路径别名

🌐 Configure path aliases

如果你正在使用 src 目录，请在你的 tsconfig.json 中添加路径别名，这样你就可以使用像 @/components/button 这样的简短导入路径，而不是相对路径：

🌐 If you are using the src directory, add path aliases to your tsconfig.json so you can use short import paths like @/components/button instead of relative paths:

tsconfig.json

{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"]
}

@/* 别名在上面的例子中映射到 src 目录。

🌐 The @/* alias maps to the src directory in the above example.

清除 bundler 缓存

🌐 Clear bundler cache

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

🌐 After updating the configuration, run the following command to clear the bundler cache:

Terminal

- npx expo start --clear

更新分辨率

🌐 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.