手动安装

编辑页面

了解如何通过这些详细说明将 Expo Router 添加到现有项目中。

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

Prerequisites

1 requirement

设置你的开发环境

确保你的电脑已配置好用于运行 Expo 应用。

安装依赖

你需要安装以下依赖：

Terminal

-

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（如果未使用 src 目录，则为 app/_layout.tsx）。

package.json

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

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

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

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

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

src
app
_layout.tsx
index.js
package.json
其他项目文件
在文件中导入或添加你的自定义配置。然后，导入 expo-router/entry 来注册应用入口。记住一定要最后导入它，以确保在应用渲染之前所有配置都已正确设置。
index.js
```
// 首先导入副作用和服务

// 初始化服务

// 通过 Expo Router 注册应用入口
import 'expo-router/entry';
```
更新 package.json 中的 main 属性，使其指向新的入口文件。
package.json
```
{
  "main": "index.js"
}
```

修改项目配置

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

app.json

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

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

Terminal

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

然后，通过在你的应用配置中添加以下内容来启用 Metro web 支持：

app.json

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

修改 babel.config.js

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

babel.config.js

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

配置路径别名

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

tsconfig.json

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

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

清除打包器缓存

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

Terminal

- npx expo start --clear

更新 resolutions

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