Expo CLI

Expo CLI 是一个命令行工具，是开发者和其他 Expo 工具之间的主要界面。

本文档涉及 Local Expo CLI。有关旧版 CLI 的信息，请参阅 全局 Expo CLI。

expo 包提供了一个小而强大的 CLI 工具 npx expo，旨在让你在应用开发过程中快速前进。

¥The expo package provides a small and powerful CLI tool npx expo which is designed to keep you moving fast during app development.

高亮

¥Highlights

• 启动服务器 用于开发你的应用：npx expo start。

  ¥Start a server for developing your app: npx expo start.

• 生成原生 Android 和 iOS 目录 适合你的项目：npx expo prebuild。

  ¥Generate the native Android and iOS directories for your project: npx expo prebuild.

• 构建并运行 本地原生应用：npx expo run:ios 和 npx expo run:android。

  ¥Build and run the native apps locally: npx expo run:ios and npx expo run:android.

• 与项目中的 react-native 版本配合使用的 安装和更新包：npx expo install package-name。

  ¥Install and update packages that work with the version of react-native in your project: npx expo install package-name.

• npx expo 可与 npx react-native 同时使用。

  ¥npx expo can be used with npx react-native simultaneously.

要查看 Expo CLI 中的可用命令列表，请在项目中运行以下命令：

¥To view a list of available commands in Expo CLI, run the following in your project:

如果你更喜欢使用 yarn 作为包管理器，你也可以运行 yarn expo -h。

¥You can also run yarn expo -h if you prefer to use yarn as the package manager.

输出应如下所示：

¥The output should look something like below:

Usage
  $ npx expo <command>

Commands
  start, export
  run:ios, run:android, prebuild
  install, customize, config
  login, logout, whoami, register

Options
  --version, -v   Version number
  --help, -h      Usage info

你可以运行带有 --help 或 -h 标志的任何命令来了解更多信息：

¥You can run any command with the --help or -h flag to learn more about it:

安装

¥Installation

Expo CLI 包含在 expo 软件包中。你可以使用 npm 或 yarn 安装它：

¥Expo CLI is included in the expo package. You can install it with npm or yarn:

不使用 Expo 预建（通常称为裸工作流程）的项目将需要执行额外的设置以确保所有自定义 Expo 打包功能正常工作：Metro：裸工作流程设置。

¥Projects that are not using Expo Prebuild (often referred to as Bare workflow) will need to perform additional setup to ensure all custom Expo bundling features work: Metro: Bare workflow setup.

开发

¥Develop

通过运行以下命令启动开发服务器来处理你的项目：

¥Start a development server to work on your project by running:

你还可以将 npx expo 作为 npx expo start 的别名运行。

¥You can also run npx expo as an alias to npx expo start.

此命令在 http://localhost:8081 上启动服务器（对于 SDK 48 及更低版本，端口号为 19000），客户端可使用该服务器与打包器进行交互。默认打包程序是 Metro。

¥This command starts a server on http://localhost:8081 (for SDK 48 and lower, the port number is 19000) that a client can use to interact with the bundler. The default bundler is Metro.

进程中显示的 UI 称为终端 UI。它包含一个 QR 码（用于开发服务器 URL）和你可以按的键盘快捷键列表：

¥The UI that shows up in the process is referred to as the Terminal UI. It contains a QR code (for the dev server URL) and a list of keyboard shortcuts you can press:

触发目标

¥Launch target

如果项目中安装了 expo-dev-client，npx expo start 命令会自动在开发版本中启动应用。否则，它会在 Expo Go 中启动该应用。

¥The npx expo start command automatically launches the app in a development build if expo-dev-client is installed in the project. Otherwise, it launches the app in Expo Go.

或者，你可以通过将以下标志传递给命令来强制启动目标：

¥Alternatively, you can force the launch target by passing the following flags to the command:

• --dev-client：始终在开发版本中启动应用。

  ¥--dev-client: Always launch the app in a development build.

• --go：始终在 Expo Go 中启动该应用。

  ¥--go: Always launch the app in Expo Go.

你还可以通过在终端 UI 中按 S 在运行时切换启动目标。默认情况下，编译开发版本后，run 命令也会使用 --dev-client。

¥You can also switch the launch target during runtime by pressing S in the Terminal UI. The run commands also use --dev-client after compiling the development build, by default.

服务器地址

¥Server URL

默认情况下，该项目通过 LAN 连接提供服务。你可以使用标志 npx expo start --localhost 将此行为更改为仅限 localhost。

¥By default, the project is served over a LAN connection. You can change this behavior to localhost-only by using the flag npx expo start --localhost.

其他可用选项有：

¥Other available options are:

• --port：启动开发服务器的端口（不适用于 webpack 或 隧道 URL）。默认：8081.对于 SDK 48 及更低版本，默认为 19000。

  ¥--port: Port to start the dev server on (does not apply to webpack or tunnel URLs). Default: 8081. For SDK 48 and lower, defaults to 19000.

• --https：使用安全源启动开发服务器。目前仅在网络上支持此功能。

  ¥--https: Start the dev server using a secure origin. This is currently only supported on web.

你可以使用 EXPO_PACKAGER_PROXY_URL 环境变量强制 URL 为任意值。例如：

¥You can force the URL to be any value with the EXPO_PACKAGER_PROXY_URL environment variable. For example:

将打开应用以：exp://expo.dev:80（:80 是 Android WebSocket 的临时解决方法）。

¥Will open apps to: exp://expo.dev:80 (the :80 is a temporary workaround for Android WebSockets).

通道技术

¥Tunneling

限制性网络条件（公共 Wi-Fi 中常见）、防火墙（Windows 用户中常见）或模拟器配置错误可能会导致难以通过 lan/localhost 将远程设备连接到开发服务器。

¥Restrictive network conditions (common for public Wi-Fi), firewalls (common for Windows users), or Emulator misconfiguration can make it difficult to connect a remote device to your dev server over lan/localhost.

有时，通过代理 URL 连接到开发服务器会更容易，该代理 URL 可以从任何具有 Internet 访问权限的设备访问，这称为隧道。npx expo start 通过 ngrok 提供对隧道的内置支持。

¥Sometimes it's easier to connect to a dev server over a proxy URL that's accessible from any device with internet access, this is referred to as tunneling. npx expo start provides built-in support for tunneling via ngrok.

要启用隧道，请首先安装 @expo/ngrok：

¥To enable tunneling, first install @expo/ngrok:

然后运行以下命令从隧道 URL 启动你的开发服务器：

¥Then run the following to start your dev server from a tunnel URL:

这将从公共 URL 为你的应用提供服务，例如：http://xxxxxxx.bacon.19000.exp.direct:80。

¥This will serve your app from a public URL like: http://xxxxxxx.bacon.19000.exp.direct:80.

缺点

¥Drawbacks

• 隧道连接比本地连接慢，因为请求必须转发到公共 URL。

  ¥Tunneling is slower than local connections because requests must be forwarded to a public URL.

• 隧道 URL 是公共的，任何具有网络连接的设备都可以访问。Expo CLI 通过在 URL 开头添加熵来降低暴露风险。可以通过清除项目中的 .expo 目录来重置熵。

  ¥Tunnel URLs are public and can be accessed by any device with a network connection. Expo CLI mitigates the risk of exposure by adding entropy to the beginning of the URL. Entropy can be reset by clearing the .expo directory in your project.

• 隧道需要两个设备上都有网络连接，这意味着此功能不能与 --offline 标志一起使用。

  ¥Tunnels require a network connection on both devices, meaning this feature cannot be used with the --offline flag.

隧道需要第三方托管服务，这意味着它有时可能会遇到间歇性问题，例如 ngrok tunnel took too long to connect 或 Tunnel connection has been closed. This is often related to intermittent connection problems with the Ngrok servers...。在报告问题之前，请务必检查 Ngrok 中断。一些 Windows 用户还报告需要修改其防病毒设置才能允许 Ngrok 工作。

¥Tunneling requires a third-party hosting service, this means it may sometimes experience intermittent issues like ngrok tunnel took too long to connect or Tunnel connection has been closed. This is often related to intermittent connection problems with the Ngrok servers.... Be sure to check for Ngrok outages before reporting an issue. Some Windows users have also reported needing modify their antivirus settings to allow Ngrok to work.

离线

¥Offline

你可以使用 --offline 标志在没有网络连接的情况下进行开发：

¥You can develop without a network connection by using the --offline flag:

离线将阻止 CLI 发出网络请求。如果你不使用该标志并且你的计算机没有互联网连接，那么离线支持将自动启用，只是需要更长的时间来验证可达性。

¥Offline will prevent the CLI from making network requests. If you don't use the flag and your computer has no internet connection, then offline support will automatically be enabled, it will just take a bit longer to verify the reachability.

Expo CLI 发出网络请求，以使用你的用户凭据签署清单，以确保敏感信息在可重用运行时（如 Expo Go）中沙箱化。

¥Expo CLI makes network requests to sign manifests with your user credentials to ensure sensitive information is sandboxed in reusable runtimes like Expo Go.

.expo 目录

¥.expo directory

当你首次在项目中启动开发服务器时，会在该项目的根目录下创建一个 .expo 目录。它包含两个文件：

¥When you start the development server in a project for the first time, a .expo directory is created at the root of that project. It contains two files:

• 设备.json：包含有关最近打开此项目的设备的信息。

  ¥devices.json: Contains information about devices that have opened this project recently.

• 设置.json：包含有关用于提供项目清单的服务器配置的信息。

  ¥settings.json: Contains information about server configuration that is used to serve the project's manifest.

这两个文件都包含特定于你的本地计算机的信息。这就是为什么在创建新项目时默认将 .expo 目录包含在 .gitignore 文件中的原因。它并不意味着与其他开发者共享。

¥Both of these files have information that is specific to your local computer. This is the reason why .expo directory is included in the .gitignore file, by default, when a new project is created. It is not meant to be shared with other developers.

架构

¥Building

React Native 应用由两部分组成：原生运行时 (compiling) 以及 JavaScript 包和资源等静态文件 (exporting)。Expo CLI 提供了执行这两项任务的命令。

¥A React Native app consists of two parts: a native runtime (compiling), and static files like JavaScript bundles and assets (exporting). Expo CLI provides commands for performing both tasks.

编译

¥Compiling

你可以使用 run 命令在本地编译你的应用：

¥You can compile your app locally with the run commands:

高亮

¥Highlights

• 使用 --device 标志直接在连接的设备上构建，没有全局副作用。支持锁定设备，让你立即重试，而无需重建。

  ¥Build directly on connected devices with no global side effects using the --device flag. Supports locked devices, letting you retry instantly instead of needing to rebuild.

• 自动协同设计 iOS 应用，以便从 CLI 进行开发，无需打开 Xcode。

  ¥Automatically codesign iOS apps for development from the CLI without having to open Xcode.

• 智能日志解析显示项目源代码中的警告和错误，这与 Xcode 不同，Xcode 会显示来自节点模块的数百个良性警告。

  ¥Smart log parsing shows warnings and errors from your project source code, unlike Xcode which surfaces hundreds of benign warnings from your node modules.

• 导致应用崩溃的致命错误将在终端中显示，从而无需在 Xcode 中重现。

  ¥Fatal errors causing your app to crash will be surfaced in the terminal preventing the need to reproduce in Xcode.

npx expo run:ios 只能在 Mac 上运行，并且必须安装 Xcode。你可以使用 eas build -p ios 从任何计算机在云中构建应用。同样，npx expo run:android 需要在你的计算机上安装并配置 Android Studio 和 Java。

¥npx expo run:ios can only be run on a Mac, and Xcode must be installed. You can build the app in the cloud from any computer using eas build -p ios. Similarly, npx expo run:android requires Android Studio and Java to be installed and configured on your computer.

本地构建对于开发原生模块和 调试复杂的原生问题 很有用。由于预先配置的云环境，使用 eas build 进行远程构建是一个更具弹性的选项。

¥Building locally is useful for developing native modules and debugging complex native issues. Building remotely with eas build is a much more resilient option due to the pre-configured cloud environment.

如果你的项目没有相应的原生目录，则在构建之前将运行一次 npx expo prebuild 命令以生成相应的目录。

¥If your project does not have the corresponding native directories, the npx expo prebuild command will run once to generate the respective directory before building.

例如，如果你的项目根目录中没有 ios 目录，那么 npx expo run:ios 将首先运行 npx expo prebuild -p ios，然后再编译你的应用。有关此过程的更多信息，请参阅 Expo 预建。

¥For example, if your project does not have an ios directory in the root of your project, then npx expo run:ios will first run npx expo prebuild -p ios before compiling your app. For more information on this process, see Expo Prebuild.

跨平台争论

¥Cross-Platform Arguments

• --no-build-cache：构建之前清除原生缓存。在 iOS 上，这是派生数据文件夹。缓存清除对于分析构建时间很有用。

  ¥--no-build-cache: Clear the native cache before building. On iOS, this is the derived data folder. Cache clearing is useful for profiling your build times.

• --no-install：跳过安装依赖。在 iOS 上，如果项目 package.json 中的 dependencies 字段发生更改，这也将跳过运行 npx pod-install。

  ¥--no-install: Skip installing dependencies. On iOS, this will also skip running npx pod-install if the dependencies field in the project's package.json has changed.

• --no-bundler：跳过启动开发服务器。如果开发服务器已经从不同的进程为应用提供服务，则会自动启用。

  ¥--no-bundler: Skip starting the dev server. Enabled automatically if the dev server is already serving the app from a different process.

• -d, --device [device]：用于构建应用的设备名称或 ID。你可以传递不带参数的 --device 从可用选项列表中选择设备。这支持连接的设备以及虚拟设备。

  ¥-d, --device [device]: Device name or ID to build the app on. You can pass --device without arguments to select a device from a list of available options. This supports connected devices as well as virtual devices.

• -p, --port <port>：用于启动开发服务器的端口。默认：8081.这仅与开发版本相关。生产版本将对项目进行 export 并将文件嵌入原生二进制文件中，然后再将其安装到设备上。

  ¥-p, --port <port>: Port to start the development server. Default: 8081. This is only relevant for development builds. Production builds will export the project and embed the files in the native binary before installing them on a device.

编译 Android

¥Compiling Android

Android 应用可以有多个不同的变体，这些变体在项目的 build.gradle 文件中定义。可以使用 --variant 标志来选择变体：

¥Android apps can have multiple different variants which are defined in the project's build.gradle file. Variants can be selected with the --variant flag:

你可以通过运行以下命令来编译 Android 应用以用于生产：

¥You can compile the Android app for production by running:

此版本不会自动进行代码签名以提交到 Google Play 商店。此命令应用于测试可能仅出现在生产版本中的错误。要生成为 Play 商店进行代码签名的生产版本，我们建议使用 EAS 构建。

¥This build is not automatically code-signed for submission to the Google Play Store. This command should be used to test bugs that may only show up in production builds. To generate a production build that is code signed for the Play Store, we recommend using EAS Build.

你可以通过在 Android Studio 中打开 android 目录，使用原生调试工具来调试原生 Android 项目：

¥You can debug the native Android project using native debugging tools by opening the android directory in Android Studio:

编译 iOS

¥Compiling iOS

iOS 应用可以有多种方案来表示不同的子应用，例如 App Clip、watchOS 应用、Safari 扩展等。默认情况下，npx expo run:ios 将为你的 iOS 应用选择方案。你可以使用 --scheme <my-scheme> 参数选择自定义方案。如果你单独传递 --scheme 参数，那么 Expo CLI 将提示你从 Xcode 项目的可用选项列表中选择一个方案。

¥An iOS app can have multiple schemes for representing different sub-apps like App Clips, watchOS apps, Safari Extensions, and so on. By default, npx expo run:ios will choose the scheme for your iOS app. You can pick a custom scheme with the --scheme <my-scheme> argument. If you pass in the --scheme argument alone, then Expo CLI will prompt you to choose a scheme from the list of available options in your Xcode project.

你选择的方案将过滤掉选择提示中显示的 --device 选项，例如，选择 Apple TV 方案将仅显示可用的 Apple TV 设备。

¥The scheme you select will filter out which --device options show up in the selection prompt, for example, selecting an Apple TV scheme will only show available Apple TV devices.

你可以通过运行以下命令来编译用于生产的 iOS 应用：

¥You can compile an iOS app for production by running:

此版本不会自动进行代码签名以提交到 Apple App Store。npx expo run:ios 主要用于测试仅在生产版本中出现的错误。原生代码签名需要多个网络请求，并且很容易出现来自 Apple 服务器的许多不同类型的错误。要生成针对 App Store 进行代码签名的生产版本，我们建议使用 EAS 构建。

¥This build is not automatically code signed for submission to the Apple App Store. npx expo run:ios should mostly be used to test bugs that only show up in production builds. Native code signing requires several network requests and is prone to many different types of errors from the Apple servers. To generate a production build that is code signed for the App Store, we recommend using EAS Build.

当你将应用编译到模拟器上时，模拟器的原生错误日志将通过管道传输到终端中的 Expo CLI 进程。这对于快速查看可能导致致命错误的错误很有用。例如，缺少权限消息。错误管道不适用于物理 iOS 设备。

¥When you compile your app onto a Simulator, the Simulator's native error logs will be piped to the Expo CLI process in the terminal. This is useful for quickly seeing bugs that may cause a fatal error. For example, missing permission messages. Error piping is not available for physical iOS devices.

你可以通过在 Xcode 中打开项目并从 Xcode 重建来使用 lldb 和所有原生 Apple 调试工具进行调试：

¥You can debug using lldb and all of the native Apple debugging tools by opening the project in Xcode and rebuilding from Xcode:

从 Xcode 构建非常有用，因为你可以设置原生断点并分析应用的任何部分。请务必跟踪源代码管理 (git) 中的更改，以防你需要使用 npx expo prebuild -p ios --clean 重新生成原生应用。

¥Building from Xcode is useful because you can set native breakpoints and profile any part of the application. Be sure to track changes in source control (git) in case you need to regenerate the native app with npx expo prebuild -p ios --clean.

iOS 开发签名

¥iOS development signing

如果你想查看你的应用如何在你的设备上运行，你所要做的就是连接它，运行 npx expo run:ios —-device，然后选择你连接的设备。

¥If you want to see how your app will run on your device, all you have to do is connect it, run npx expo run:ios —-device, and select your connected device.

Expo CLI 将自动对设备进行签名以进行开发、安装应用并启动它。

¥Expo CLI will automatically sign the device for development, install the app, and launch it.

如果你的计算机上没有设置任何开发者配置文件，那么你需要按照本指南在 Expo CLI 之外手动设置它们：设置 Xcode 签名。

¥If you don't have any developer profiles setup on your computer then you'll need to set them up manually outside of Expo CLI by following this guide: Setup Xcode signing.

导出

¥Exporting

你可以通过运行以下命令使用 Metro 打包程序导出应用的 JavaScript 和资源：

¥You can export the JavaScript and assets for your app using Metro bundler by running:

当使用 eas update 或编译原生运行时时，这是自动补齐的。export 命令的工作方式与大多数 Web 框架类似：

¥This is done automatically when using eas update or when compiling the native runtime. The export command works similar to most web frameworks:

• 打包器会为生产环境转换并打包你的应用代码，并剥离由 __DEV__ 布尔值保护的所有代码。

  ¥A bundler transpiles and bundles your application code for production environments, stripping all code guarded by the __DEV__ boolean.

• 所有静态文件都复制到静态 dist/ 文件夹中，该文件夹可以从静态主机提供服务。

  ¥All static files are copied into a static dist/ folder which can be served from a static host.

• public/ 文件夹的内容将按原样复制到 dist/ 文件夹中。

  ¥Contents of the public/ folder are copied into the dist/ folder as-is.

提供以下选项：

¥The following options are provided:

• --platform <platform>：选择要编译的平台：'ios'、'android'、'all'。默认：全部。如果在应用配置中进行了配置，'web' 也可用。欲了解更多信息，请参阅 定制 Metro。

  ¥--platform <platform>: Choose the platform to compile for: 'ios', 'android', 'all'. Default: all. 'web' is also available if configured in the app config. For more information, see Customizing Metro.

• --dev：用于开发环境的打包包，无需缩小代码或剥离 __DEV__ 布尔值。

  ¥--dev: Bundle for development environments without minifying code or stripping the __DEV__ boolean.

• --output-dir <dir>：将静态文件导出到的目录。默认：dist

  ¥--output-dir <dir>: The directory to export the static files to. Default: dist

• --max-workers <number>：允许打包器生成的最大任务数。将其设置为 0 将在同一进程上运行所有转译，这意味着你可以轻松调试 Babel 转译。

  ¥--max-workers <number>: Maximum number of tasks to allow the bundler to spawn. Setting this to 0 will run all transpilation on the same process, meaning you can easily debug Babel transpilation.

• -c, --clear：导出前清除打包器缓存。

  ¥-c, --clear: Clear the bundler cache before exporting.

• --no-minify：跳过缩小 JavaScript 和 CSS 资源（SDK 49 及更高版本）。

  ¥--no-minify: Skip minifying JavaScript and CSS assets (SDK 49 and above).

• --no-bytecode：跳过为原生平台（SDK 50 及更高版本）生成 Hermes 字节码。仅使用它来分析打包包大小，切勿将 UTF-8 打包包发送到原生平台，因为这将导致启动时间显着延长。

  ¥--no-bytecode: Skip generating Hermes bytecode for native platforms (SDK 50 and above). Only use this for analyzing bundle sizes and never ship UTF-8 bundles to native platforms as this will lead to drastically longer startup times.

使用子路径托管

¥Hosting with sub-paths

实验功能。从 SDK 50 开始可用。

¥Experimental functionality. Available from SDK 50.

{
  "expo": {
    "experiments": {
      "baseUrl": "/my-root"
    }
  }
}

import { Link } from 'expo-router';

export default function Blog() {
  return <Link href="/blog/123">Go to blog post</Link>;
}

<a href="/my-root/post/123">Go to blog post</a>

import { Image } from 'expo-image';

export default function Blog() {
  return <Image source={require('@/assets/image.png')} />;
}

<img src="/my-root/assets/assets/image.png" />

export default function Blog() {
  return <img src="/my-root/assets/image.png" />;
}

使用 webpack 导出

¥Exporting with webpack

已弃用：在 SDK 50 及更高版本中，Expo Webpack 已被弃用，取而代之的是通用 Metro (npx expo export)。在 从 Webpack 迁移到 Expo Router 中了解更多信息。

你可以通过运行以下命令使用 webpack 导出 Web 应用的 JavaScript 和资源：

¥You can export the JavaScript and assets for your web app using webpack by running the following:

• --dev：以 'development' 模式打包，无需缩小代码或剥离 __DEV__ 布尔值。

  ¥--dev: Bundle in 'development' mode without minifying code or stripping the __DEV__ boolean.

• -c, --clear：导出前清除打包器缓存。

  ¥-c, --clear: Clear the bundler cache before exporting.

如果你的项目配置为使用 metro 通过 expo.web.bundler: 'metro' 字段打包 app.json 中的 Web 项目，则此命令将被禁用。

¥This command will be disabled if your project is configured to use metro for bundling web projects in the app.json via the expo.web.bundler: 'metro' field.

预建

¥Prebuild

必须先生成原生源代码，然后才能编译原生应用。Expo CLI 提供了一个独特而强大的系统，称为预构建，可以为你的项目生成原生代码。要了解更多信息，请阅读 Expo 预建文档。

¥Native source code must be generated before a native app can compile. Expo CLI provides a unique and powerful system called prebuild, that generates the native code for your project. To learn more, read the Expo Prebuild docs.

配置

¥Config

通过运行以下命令来评估应用配置（app.json 或 app.config.js）：

¥Evaluate the app config (app.json, or app.config.js) by running:

• --full：包括所有项目配置数据。

  ¥--full: Include all project config data.

• --json：以 JSON 格式输出，可用于将 app.config.js 转换为 app.config.json。

  ¥--json: Output in JSON format, useful for converting an app.config.js to an app.config.json.

• -t, --type：配置类型 显示。

  ¥-t, --type: Type of config to show.

配置类型

¥Config type

从应用配置生成三种不同的配置类型：

¥There are three different config types that are generated from the app config:

• public：用于 OTA 更新的清单文件。可以将其视为 index.html 文件的 <head /> 元素，但适用于原生应用。

  ¥public: The manifest file to use with OTA updates. Think of this like an index.html file's <head /> element but for native apps.

• prebuild：用于 Expo 预建 的配置，包括异步修饰符。这是唯一一次配置不可序列化。

  ¥prebuild: The config that is used for Expo Prebuild including async modifiers. This is the only time the config is not serializable.

• introspect：prebuild 配置的子集，仅显示内存中的修改，例如 Info.plist 或 AndroidManifest.xml 更改。了解有关 introspection 的更多信息。

  ¥introspect: A subset of the prebuild config that only shows in-memory modifications like Info.plist or AndroidManifest.xml changes. Learn more about introspection.

安装

¥Install

与 Web 不同，React Native 不向后兼容。这意味着 npm 包通常需要是项目中当前安装的 react-native 副本的正确版本。Expo CLI 提供了一个尽力而为的工具，使用流行的软件包列表和已知的工作版本组合来执行此操作。只需使用 install 命令作为 npm install 的直接替代：

¥Unlike the web, React Native is not backwards compatible. This means that npm packages often need to be the exact right version for the currently installed copy of react-native in your project. Expo CLI provides a best-effort tool for doing this using a list of popular packages and the known working version combinations. Simply use the install command as a drop-in replacement for npm install:

运行此命令的单个实例，你还可以安装多个包：

¥Running a single instance of this command, you can also install multiple packages:

你可以使用 -- 运算符直接将参数传递给底层包管理器：

¥You can directly pass arguments to the underlying package manager by using the -- operator:

版本验证

¥Version validation

你可以使用 --check 和 --fix 标志执行验证和更正：

¥You can perform validation and correction with the --check and --fix flags:

• --check：检查哪些已安装的软件包需要更新。

  ¥--check: Check which installed packages need to be updated.

• --fix：自动更新任何无效的软件包版本。

  ¥--fix: Automatically update any invalid package versions.

示例：

¥Example:

npx expo install --check 提示你安装不正确的软件包。它还会提示你在本地安装这些软件包到其兼容版本。在持续集成 (CI) 中，它以非零值退出。这意味着你可以使用它来进行连续的不可变验证。相比之下，无论环境如何，npx expo install --fix 都会在需要时修复软件包。

¥npx expo install --check prompts you about packages that are installed incorrectly. It also prompts about installing these packages to their compatible versions locally. It exits with non-zero in Continuous Integration (CI). This means you can use this to do continuous immutable validation. In contrast, npx expo install --fix will always fix packages if needed, regardless of the environment.

你可以通过传递特定包来验证它们：

¥You can validate specific packages by passing them:

命令 npx expo install expo-camera 和 npx expo install expo-camera --fix 具有相同的用途，--fix 命令对于升级项目中的所有包很有用，例如：

¥The command npx expo install expo-camera and npx expo install expo-camera --fix serve the same purpose, the --fix command is useful for upgrading all packages in your project like:

配置依赖验证

¥Configuring dependency validation

在 SDK 49 及更高版本中可用。

¥Available in SDK 49 and above.

在某些情况下，你想要使用的软件包版本可能与 npx expo install 推荐的版本不同。

¥There may be circumstances where you want to use a version of a package is different from the version recommended by npx expo install.

例如，你正在测试 react-native-reanimated 的新版本，以验证它在你的应用中运行良好并修复你遇到的错误。现在你希望 1) 不被 npx expo start 或 npx expo-doctor 警告，2) 在运行 npx expo install --fix 时不更改该软件包版本。

¥For example, you are testing a new version of react-native-reanimated to verify that it works well in your app and fixes a bug that you encountered. Now you want to 1) not be warned by npx expo start or npx expo-doctor and 2) not have that package version changed when you run npx expo install --fix.

你可以从版本检查中排除特定的软件包，同时仍然允许 install 命令安装、检查和修复任何其他依赖。此配置扩展到 npx expo-doctor 完成的检查。

¥You can exclude specific packages from the version checks while still allowing the install command to install, check, and fix any other dependencies. This configuration extends to the checking done by npx expo-doctor.

要从版本检查中排除软件包，请在项目的 package.json 中设置 expo.install 配置对象：

¥To exclude packages from version checking, set the expo.install config object in your project's package.json:

{
  "expo": {
    "install": {
      "exclude": ["expo-updates", "expo-splash-screen"]
    }
  }
}

安装包管理器

¥Install package managers

npx expo install 支持 bun、npm、pnpm 和 yarn。

¥npx expo install has support for bun, npm, pnpm, and yarn.

你可以强制包管理器使用命名参数：

¥You can force the package manager using a named argument:

• --bun：使用 bun 安装依赖。bun.lockb 存在时默认。

  ¥--bun: Use bun to install dependencies. Default when bun.lockb exists.

• --npm：使用 npm 安装依赖。当 package-lock.json 存在时默认。

  ¥--npm: Use npm to install dependencies. Default when package-lock.json exists.

• --pnpm：使用 pnpm 安装依赖。pnpm-lock.yaml 存在时的默认值。

  ¥--pnpm: Use pnpm to install dependencies. Default when pnpm-lock.yaml exists.

• --yarn：使用 yarn 安装依赖。当 yarn.lock 存在时默认。

  ¥--yarn: Use yarn to install dependencies. Default when yarn.lock exists.

验证

¥Authentication

Expo CLI 提供了与 npx expo start 命令一起使用的身份验证方法。身份验证用于 "代码符号" 清单以确保安全 OTA 使用。可以将其想象为网络上的 HTTPS。

¥Expo CLI provides authentication methods to use with the npx expo start command. Authentication is used to "code sign" manifests for secure OTA usage. Think of this like HTTPS on the web.

1. 注册 npx expo register 帐号。

   ¥Register an account with npx expo register.

2. 使用 npx expo login 登录你的账户。

   ¥Login to your account with npx expo login.

3. 检查当前哪个账户已通过 npx expo whoami 进行身份验证。

   ¥Check which account is currently authenticated with npx expo whoami.

4. 使用 npx expo logout 注销。

   ¥Logout with npx expo logout.

这些凭证在 Expo CLI 和 EAS CLI 之间共享。

¥These credentials are shared across Expo CLI and EAS CLI.

定制

¥Customizing

有时你可能想要自定义一个项目文件，否则该文件将由 Expo CLI 在内存中生成。使用 Expo CLI 以外的工具时，你需要提供默认配置文件，否则你的应用可能无法按预期工作。你可以通过运行以下命令生成文件：

¥Sometimes you may want to customize a project file that would otherwise be generated in memory by Expo CLI. When utilizing tools other than Expo CLI, you'll need to have the default config files present, otherwise your app may not work as expected. You can generate files by running:

从这里，你可以选择生成基本项目文件，例如：

¥From here, you can choose to generate basic project files like:

• babel.config.js —— Babel 配置。如果你计划使用 Expo CLI 以外的工具来打包你的项目，则需要提供此信息。

  ¥babel.config.js -- The Babel configuration. This is required to be present if you plan to use tooling other than Expo CLI to bundle your project.

• webpack.config.js —— Web 开发的默认 webpack 配置。

  ¥webpack.config.js -- The default webpack config for web development.

• Metro.config.js - 通用开发的默认 Metro 配置。这是与 npx react-native 一起使用所必需的。

  ¥metro.config.js -- The default Metro config for universal development. This is required for usage with npx react-native.

• tsconfig.json - 创建 TypeScript 配置文件并安装所需的依赖。

  ¥tsconfig.json -- Create a TypeScript config file and install the required dependencies.

环境变量

¥Environment Variables

遥测

¥Telemetry

Expo 开发工具收集有关一般使用情况的匿名数据。这有助于我们知道某个功能何时未按预期工作。遥测是完全可选的，你可以使用 EXPO_NO_TELEMETRY=1 环境变量选择退出。

¥Expo dev tools collect anonymous data about general usage. This helps us know when a feature is not working as expected. Telemetry is completely optional, you can opt out by using the EXPO_NO_TELEMETRY=1 environment variable.