迁移到 Expo CLI

了解如何在任何 React Native 项目中迁移到使用 Expo CLI 而不是 @react-native-community/cli。

要从 npx react-native init 迁移到 Expo CLI，你需要安装 expo 包，其中包括 Expo Modules API 和 Expo CLI。本指南介绍了安装步骤、使用 Expo CLI 的优点以及迁移到 Expo CLI 后如何编译和运行项目。

¥To migrate from npx react-native init to Expo CLI, you'll need to install the expo package, which includes the Expo Modules API and Expo CLI. This guide covers the installation step, the benefits of using Expo CLI, and how to compile and run your project after migrating to Expo CLI.

强烈建议在使用其他 Expo 工具时使用 Expo CLI。许多工具都需要它，例如 EAS Update、Expo Router 和 expo-dev-client，如果没有它，其他功能可能无法正常工作。

¥It is strongly recommended to use Expo CLI when using other Expo tools. It is required for many tools, such as EAS Update, Expo Router, and expo-dev-client, and other features may not work as well without it.

安装 expo 包

¥Install the expo package

在大多数情况下，你只需在项目目录中执行以下命令即可安装包：

¥In most cases, executing the following command in a project directory to install the package is all you need to do:

详细安装指南请参见 安装 Expo 模块。

¥For a detailed installation guide, see Install Expo modules.

为什么使用 Expo CLI 而不是 npx react-native

¥Why Expo CLI instead of npx react-native

与 @react-native-community/cli 中的类似命令相比，Expo CLI 命令具有多项优势，其中包括：

¥Expo CLI commands provide several benefits over the similar commands in @react-native-community/cli, which includes:

• 通过 j 按键即时访问 Hermes 调试器。

  ¥Instant access to Hermes debugger with j keystroke.

• 调试器附带已安装的 React Developer Tools (react-devtools)。

  ¥The debugger ships with React Developer Tools (react-devtools) already installed.

• 持续的原生生成 (CNG) 支持 expo prebuild，用于升级、白色标签、轻松的第三方包设置以及更好的代码库可维护性（通过减少表面积）。

  ¥Continuous Native Generation (CNG) support with expo prebuild for upgrades, white-labeling, easy third-party package setup, and better maintainability of the codebase (by reducing the surface area).

• 支持 expo-router 的基于文件的路由。

  ¥Support for file-based routing with expo-router.

  • 异步打包 正在开发中。

    ¥Async bundling in development.

• 内置 环境变量支持 和 .env 文件集成。

  ¥Built-in environment variable support and .env file integration.

• 直接在终端中查看原生日志以及 JavaScript 日志。

  ¥View native logs directly in the terminal alongside JavaScript logs.

• 使用专为 React Native 应用构建的 Expo CLI 的 xcpretty 风格工具改进了原生构建日志格式。例如，在编译 Pod 时，你可以看到哪个 Node 模块包含了它。

  ¥Improved native build log formatting using Expo CLI's xcpretty-style tool built specifically for React Native apps. For example, when compiling a Pod, you can see which Node module included it.

• 一流的 TypeScript 支持。

  ¥First-class TypeScript support.

• 支持 tsconfig.json 别名为 paths 和 baseUrl 内置于 Metro。

  ¥Support for tsconfig.json aliases with paths and baseUrl built-in to Metro.

• Web 支持 与 Metro。针对 React Native Web 的完全类型化。

  ¥Web support with Metro. Fully typed for React Native Web.

• 现代 CSS 支持 带有 Tailwind、PostCSS、CSS 模块、SASS 等。

  ¥Modern CSS support with Tailwind, PostCSS, CSS Modules, SASS, and more.

• 使用 Expo Router 和 Metro web 生成静态站点。

  ¥Static site generation with Expo Router and Metro web.

• 开箱即用 支持单一仓库。

  ¥Out of the box support for monorepos.

• 支持 expo-dev-client、Expo 更新协议 和 EAS 更新 等 Expo 工具。

  ¥Support for Expo tooling such as expo-dev-client, the Expo Updates protocol and EAS Update.

• 使用 npx expo run:ios 时自动执行 pod install。

  ¥Automated pod install execution when using npx expo run:ios.

• npx expo install 为众所周知的包选择兼容的依赖版本。

  ¥npx expo install selects compatible dependency versions for well-known packages.

• 运行 npx expo run:[android|ios] 和 npx expo start 时自动端口检测。如果另一个应用正在默认端口上运行，则会使用不同的端口。

  ¥Automatic port detection when running npx expo run:[android|ios] and npx expo start. If another app is running on the default port, a different port is used.

• Android 或 iOS 设备在交互式提示中使用 Shift + a 或 Shift + i 启动选择快捷方式。

  ¥Android or iOS device launch selection shortcuts using Shift + a or Shift + i from the interactive prompt.

• 内置支持通过 恩格罗克隧道 为你的应用提供服务。

  ¥Built-in support for serving your app over an ngrok tunnel.

• 使用任何入口 JavaScript 文件在任何端口上进行开发。

  ¥Develop on any port with any entry JavaScript file.

对于大多数面向 Android、iOS 和/或 Web 的 React Native 项目，我们建议使用 Expo CLI。它尚未内置对最流行的树外平台（例如 Windows 和 macOS）的支持。如果针对这些平台进行构建，你可以对支持的平台使用 Expo CLI，对其他平台使用 @react-native-community/cli。

¥We recommend Expo CLI for most React Native projects that target Android, iOS, and/or web. It does not yet have built-in support for the most popular out-of-tree platforms, such as Windows and macOS. If building for these platforms, you can utilize Expo CLI for the supported platforms and @react-native-community/cli for the others.

编译并运行你的应用

¥Compile and run your app

安装 expo 软件包后，你可以使用以下命令替代 npx react-native run-android 和 npx react-native run-ios：

¥After installing the expo package, you can use the following commands which are alternatives to npx react-native run-android and npx react-native run-ios:

构建项目时，你可以使用 --device 标志选择设备或模拟器。这也适用于连接到你的计算机的任何 iOS 设备。

¥When building your project, you can choose a device or simulator by using the --device flag. This also applies to any iOS device that is connected to your computer.

独立启动打包器

¥Start the bundler independently

npx expo run:[android|ios] 自动启动打包器/开发服务器。如果你想使用 npx expo start 命令独立启动打包程序，请将 --no-bundler 传递给 npx expo run:[android|ios] 命令。

¥npx expo run:[android|ios] automatically starts the bundler/development server. If you want to independently start the bundler with npx expo start command, pass the --no-bundler to the npx expo run:[android|ios] command.

常见问题

¥Common questions

module.exports = {
  dependencies: {
    expo: {
      platforms: {
        android: null,
        ios: null,
        macos: null,
      },
    },
  },
};

下一步

¥Next steps

现在，在你的项目中安装和配置 expo 软件包后，你可以开始使用 Expo CLI 和 SDK 中的所有功能。以下是一些建议的后续深入研究步骤：

¥Now, with the expo package installed and configured in your project, you can start using all features from Expo CLI and SDK. Here are some recommended next steps to dive deep: