Expo CLI

Expo CLI 是一个命令行工具，是开发者与其他 Expo 工具之间的主要接口。

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

expo 包提供了一个小巧而强大的 CLI 工具 npx expo，旨在帮助你在应用开发过程中保持高效推进。

亮点

• 为开发你的应用 启动服务器：npx expo start。
• 为你的项目 生成原生 Android 和 iOS 目录：npx expo prebuild。
• 在本地 构建并运行 原生应用：npx expo run:ios 和 npx expo run:android。
• 安装和更新 与项目中 react-native 版本兼容的包：npx expo install package-name。
• npx expo 可以与 npx react-native 同时使用。

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

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

输出应如下所示：

Usage
  $ npx expo <command>

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

Options
  --version, -v   版本号
  --help, -h      使用信息

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

安装

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

未使用 Expo Prebuild 的项目（也称为 Bare 项目）需要进行额外设置，以确保所有自定义 Expo 打包功能正常工作：Metro：Bare 工作流设置。

开发

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

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

此命令会在 http://localhost:8081 上启动一个服务器，客户端可以通过它与打包器交互。默认的打包器是 Metro。

进程中显示的 UI 被称为 终端 UI。它包含一个二维码（用于开发服务器 URL）以及你可以按下的一组键盘快捷键：

启动目标

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

或者，你也可以通过向命令传递以下标志来强制指定启动目标：

• --dev-client：始终以开发构建启动应用。
• --go：始终在 Expo Go 中启动应用。

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

服务器 URL

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

其他可用选项包括：

• --port：启动开发服务器所使用的端口（不适用于 webpack 或 隧道 URL）。使用 --port 0 可自动使用第一个可用端口。默认值：8081。
• --https：（已弃用，推荐使用 --tunnel） 使用安全来源启动开发服务器。目前仅支持 web。

你可以通过 EXPO_PACKAGER_PROXY_URL 环境变量强制将 URL 设置为任意值。例如：

将会打开应用到：exp://expo.dev:80（:80 是针对 Android WebSockets 的临时解决方法）。

隧道

受限的网络条件（公共 Wi-Fi 中很常见）、防火墙（Windows 用户中很常见）或模拟器配置错误，都会使远程设备难以通过 lan/localhost 连接到你的开发服务器。

有时，通过一个任何设备在有互联网连接时都可访问的代理 URL 连接开发服务器会更容易，这被称为 隧道。npx expo start 通过 ngrok 提供了对 隧道 的内置支持。

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

然后运行以下命令，通过一个 隧道 URL 启动你的开发服务器：

这将通过如下公共 URL 提供你的应用：https://xxxxxxx.bacon.19000.exp.direct:80。

使用 EXPO_TUNNEL_SUBDOMAIN 环境变量可以实验性地设置隧道 URL 的子域名。这对于在 iOS 上测试通用链接很有用。这可能会导致 expo-linking 和 Expo Go 出现意外问题。通过传递一个 string 值来选择要使用的精确子域名，该值不能是以下之一：true、false、1、0。

缺点

• 隧道比本地连接更慢，因为请求必须被转发到公共 URL。
• 隧道 URL 是公开的，任何有网络连接的设备都可以访问。Expo CLI 通过在 URL 开头添加随机性来降低暴露风险。你可以通过清空项目中的 .expo 目录来重置随机性。
• 隧道要求两台设备都具备网络连接，这意味着该功能不能与 --offline 标志一起使用。

隧道依赖第三方托管服务，这意味着它有时可能会遇到间歇性问题，例如 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 正常工作。

离线

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

离线模式会阻止 CLI 发出网络请求。如果你不使用该标志且你的电脑没有互联网连接，则会自动启用离线支持，只是验证连通性会多花一点时间。

Expo CLI 会发出网络请求，使用你的用户凭据对 manifest 进行签名，以确保敏感信息在 Expo Go 这类可复用运行时中处于沙箱隔离状态。

.expo 目录

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

• devices.json：包含最近打开过该项目的设备信息。
• settings.json：包含用于提供项目 manifest 的服务器配置信息。

这两个文件都包含与你本地电脑相关的信息。这就是为什么在创建新项目时，默认情况下 .expo 目录会被包含到 .gitignore 文件中的原因。它并不打算与其他开发者共享。

构建

一个 React Native 应用由两部分组成：一个原生运行时（编译），以及静态文件，例如 JavaScript bundle 和资源文件（导出）。Expo CLI 提供了执行这两项任务的命令。

编译

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

亮点

• 使用 --device 标志可直接在已连接设备上构建，不会产生全局副作用。支持锁定设备，让你可以立即重试，而不必重新构建。
• 可通过 CLI 自动为开发环境对 iOS 应用进行代码签名，无需打开 Xcode。
• 智能日志解析会显示来自项目源代码的警告和错误，不像 Xcode 那样会显示来自 node_modules 的数百条无害警告。
• 导致应用崩溃的致命错误会直接显示在终端中，从而无需在 Xcode 中复现。

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

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

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

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

跨平台参数

• --no-build-cache: 在构建前清除原生缓存。在 iOS 上，这指的是 derived data 目录。清除缓存有助于分析构建耗时。
• --no-install: 跳过安装依赖。在 iOS 上，如果项目 package.json 中的 dependencies 字段发生变化，这也会跳过运行 npx pod-install。
• --no-bundler: 跳过启动开发服务器。如果开发服务器已经通过其他进程在提供应用，则会自动启用。
• -d, --device [device]: 要在哪个设备名称或 ID 上构建应用。你可以在不带参数的情况下使用 --device，从可用选项列表中选择一个设备。它支持已连接设备和虚拟设备。使用 --device generic 可在不针对特定设备的情况下构建（仅构建工作流）。
• -o, --output <path>: 构建完成后，将生成的应用二进制文件复制到的目录。适用于 CI/CD 流水线，或当你希望二进制文件位于可预测位置时。
• -p, --port <port>: 启动开发服务器的端口。默认：8081。这仅与开发构建相关。生产构建会先导出项目，并在安装到设备前将文件嵌入原生二进制中。
• --binary <path>: 要安装到设备上的二进制文件路径。提供此参数后，将跳过构建过程并尝试直接安装二进制文件。如果该二进制文件不是为正确设备构建的，例如它是为模拟器构建的或已安装到设备上，则命令会失败。

编译 Android

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

debug 变体

使用 debug 变体进行调试构建：

debugOptimized 变体

重要 debugOptimized 从 SDK 54 开始可用。

使用 debugOptimized 变体可以获得更快的开发体验，同时性能接近发布构建，并保持整体构建处于便于调试的模式：

使用此变体时，请注意以下几点：

• 如同发布构建一样优化 C++ 库，提升运行时性能
• 在 EAS Build 中，使用匹配的 Gradle 命令，例如 eas.json 中的 :app:assembleDebugOptimized
• 限制：C++ 调试已禁用，C++ 崩溃可能具有可读性较差的堆栈跟踪

release 变体

你可以通过运行以下命令为生产环境编译 Android 应用：

此构建不会自动进行代码签名，因此不能直接提交到 Google Play 商店。此命令应用于测试只会在生产构建中出现的 bug。要生成可为 Play 商店进行代码签名的生产构建，我们建议使用 EAS Build。

调试原生 Android 项目

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

如果你使用自定义的 Android 项目并配置了不同的 product flavor，你可以使用 --variant 和 --app-id 标志同时配置 flavor 和应用 ID：

有关更多信息，请参见使用 Android product flavors 进行本地构建指南。

编译 iOS

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

你选择的 scheme 会过滤掉在选择提示中显示的 --device 选项，例如，选择 Apple TV scheme 时只会显示可用的 Apple TV 设备。

你可以通过运行以下命令为生产环境编译 iOS 应用：

此构建不会自动进行代码签名，因此不能直接提交到 Apple App Store。npx expo run:ios 主要应用于测试只会在生产构建中出现的 bug。原生代码签名需要进行多次网络请求，并且容易受到 Apple 服务器上多种不同类型错误的影响。要生成可为 App Store 进行代码签名的生产构建，我们建议使用 EAS Build。

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

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

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

仅构建工作流

你可以使用 generic 设备选项，在不针对特定设备的情况下构建 iOS 模拟器应用：

上述命令使用通用的 Xcode 目标（generic/platform=iOS Simulator），而不是特定的模拟器 UDID，这对于以下场景很有用：

• CI/CD 流水线：在构建机上无需配置模拟器即可构建模拟器应用。
• 分发模拟器构建：创建可共享并可在任何兼容模拟器上运行的 .app 包。
• 仅构建工作流：当你只需要编译后的二进制文件，而不需要安装或启动时。

构建完成后，CLI 会输出生成的 .app 包路径：

✓ 构建完成
Binary: ~/Library/Developer/Xcode/DerivedData/.../Release-iphonesimulator/MyApp.app

你可以将其与 --configuration Release 组合，创建生产模拟器构建，并使用 --output 将二进制文件复制到指定目录：

上述命令会将生成的 .app 包复制到 ./build/MyApp.app。

iOS 开发签名

如果你想看看应用在设备上的运行方式，只需连接设备，运行 npx expo run:ios --device，然后选择你已连接的设备即可。

Expo CLI 会自动为开发环境对设备进行签名、安装应用并启动它。

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

导出

你可以通过运行以下命令，使用 Metro bundler 导出应用的 JavaScript 和资源文件：

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

• bundler 会将应用代码转译并打包到 生产 环境中，剥离所有受 __DEV__ 布尔值保护的代码。
• 所有静态文件都会被复制到静态 dist 目录中，可由静态主机提供服务。
• public 目录中的内容会按原样复制到 dist 目录中。

提供以下选项：

• --platform <platform>: 选择要编译的平台：'ios'、'android'、'all'。默认：all。如果在 app 配置中进行了设置，也可以使用 'web'。更多信息请参见 自定义 Metro。
• --dev: 为 开发 环境打包，不进行代码压缩，也不剥离 __DEV__ 布尔值。
• --output-dir <dir>: 导出静态文件的目录。默认：dist
• --max-workers <number>: 允许 bundler 创建的最大任务数。将其设置为 0 会在同一进程中执行所有转译，这意味着你可以轻松调试 Babel 转译。
• -c, --clear: 在导出前清除 bundler 缓存。
• --no-minify: 跳过 JavaScript 和 CSS 资源的压缩。
• --no-bytecode: 跳过为原生平台生成 Hermes 字节码。仅在分析 bundle 大小时使用，切勿将 UTF-8 bundle 直接发布到原生平台，因为这会导致启动时间大幅延长。
• --no-ssg: 跳过为 Web 路由导出静态 HTML 文件。此选项仅在 dist 目录中生成服务器代码。适用于 API 路由。

使用子路径托管

重要 实验性 功能。

你可以通过在 app 配置 中设置 experiments.baseUrl 字段来配置静态资源前缀：

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

这将导出一个所有资源都以前缀 /my-root 发布的网站。例如，位于 assets/image.png 的图片将预期托管在 /my-root/assets/image.png。实际文件将位于与服务器上预期托管在 /my-root 的整个目录相同的文件系统位置。

Expo Router 对 baseUrl 提供了内置支持。当使用 Link 和 router API 时，baseUrl 会自动添加到 URL 前面。

import { Link } from 'expo-router';

export default function Blog() {
  return <Link href="/blog/123">前往博客文章</Link>;
}

这将 导出 为以下内容：

<a href="/my-root/blog/123">前往博客文章</a>

如果你直接使用 <a>、React Navigation 或 Linking API，则需要手动在前面添加 baseUrl。

baseUrl 功能仅用于生产环境，且必须在导出网站之前设置。如果你更改了该值，必须重新导出网站。

如果你通过 require 或 import 引用图片和其他资源，它们会自动工作。如果你直接引用资源 URL，则需要手动追加 baseUrl。

import { Image } from 'expo-image';

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

这将 导出 为以下内容：

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

如果手动传入 URL，则需要手动添加前缀：

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

使用 webpack 导出

警告 已弃用：从 SDK 50 开始，Expo Webpack 已被弃用，建议改用通用 Metro（npx expo export）。更多信息请参见从 Webpack 迁移到 Expo Router。

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

• --dev: 以 'development' 模式打包，不进行代码压缩，也不剥离 __DEV__ 布尔值。
• -c, --clear: 在导出前清除 bundler 缓存。

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

预构建

在原生应用可以编译之前，必须先生成原生源代码。Expo CLI 提供了一个名为 prebuild 的独特而强大的系统，它会为你的项目生成原生代码。要了解更多，请阅读 Expo Prebuild 文档。

代码检查

代码检查有助于强制执行最佳实践，并确保你的代码保持一致。npx expo lint 命令会使用 Expo 特定设置来配置 ESLint，并运行针对 Expo 框架优化过选项的 npx eslint 命令。通过运行 npx expo lint --fix，代码检查问题可以自动修复。

默认情况下，运行 npx expo lint 会针对 src、app 和 components 目录中的所有文件。你也可以将自定义文件或目录作为参数传递给 lint 命令。例如：

默认情况下，所有匹配 .js, .jsx, .ts, .tsx, .mjs, .cjs 扩展名的文件都会被检查。你可以通过传递 --ext 标志来自定义扩展名。例如，要只检查 .ts 和 .tsx 文件，你可以使用 --ext 选项：npx expo lint --ext .ts,.tsx 或 npx expo lint --ext .js --tsx .tsx。

如果你需要更多自定义，可以使用 -- 运算符传递额外参数。例如，要向 ESLint 传递 --no-error-on-unmatched-pattern 标志，可以运行：

如果你需要更多自定义，可以直接使用 npx eslint。

配置

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

• --full：包含所有项目配置数据。
• --json：以 JSON 格式输出，这对于将 app.config.js 转换为 app.config.json 很有用。
• -t, --type：要显示的配置类型。

配置类型

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

• public：与 OTA 更新一起使用的清单文件。可以把它想象成原生应用中的 index.html 文件的 <head /> 元素。
• prebuild：由 Expo Prebuild 使用的配置，包括异步修饰器。这是配置不可序列化的唯一时机。
• introspect：prebuild 配置的一个子集，只显示内存中的修改，例如 Info.plist 或 AndroidManifest.xml 的更改。了解更多关于 introspection。

安装

与 Web 不同，React Native 不向后兼容。这意味着 npm 包通常需要与你项目中当前安装的 react-native 副本完全匹配正确的版本。Expo CLI 提供了一个尽力而为的工具，通过使用常用包列表和已知可用的版本组合来完成这项工作。只需使用 install 命令，就可以直接替代 npm install：

运行该命令的单个实例时，你也可以安装多个包：

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

版本验证

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

• --check：检查哪些已安装包需要更新。
• --fix：自动更新任何无效的包版本。

示例：

npx expo install --check 会提示你哪些已安装包的安装不正确。它还会提示是否将这些包在本地安装为兼容版本。在持续集成（CI）中，它会以非零状态退出。这意味着你可以用它来进行持续的不可变验证。相较之下，npx expo install --fix 会在需要时始终修复包，不受环境影响。

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

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

配置依赖验证

在某些情况下，你可能想使用一个不同于 npx expo install 所推荐版本的包版本。在这种情况下，你可以通过在项目的 package.json 中使用 expo.install.exclude 属性，将特定包从版本检查中排除。

安装包管理器

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

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

• --bun：使用 bun 安装依赖。若存在 bun.lockb 或 bun.lock，则为默认值。
• --npm：使用 npm 安装依赖。若存在 package-lock.json，则为默认值。
• --pnpm：使用 pnpm 安装依赖。若存在 pnpm-lock.yaml，则为默认值。
• --yarn：使用 yarn 安装依赖。若存在 yarn.lock，则为默认值。

身份验证

Expo CLI 提供可与 npx expo start 命令配合使用的身份验证方法。身份验证用于对清单进行“代码签名”，以便安全地使用 OTA。可以把它理解为 Web 上的 HTTPS。

1. 使用 npx expo register 注册账户。
2. 使用 npx expo login 登录你的账户。
3. 使用 npx expo whoami 查看当前已认证的是哪个账户。
4. 使用 npx expo logout 退出登录。

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

自定义

有时你可能希望自定义一个原本会由 Expo CLI 在内存中生成的项目文件。当使用 Expo CLI 之外的工具时，你需要保留默认配置文件，否则你的应用可能无法按预期运行。你可以通过运行以下命令生成文件：

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

• babel.config.js -- Babel 配置。如果你计划使用 Expo CLI 之外的工具来打包项目，则必须存在此文件。
• webpack.config.js -- 用于 Web 开发的默认 webpack 配置。
• metro.config.js -- 用于通用开发的默认 Metro 配置。npx react-native 需要使用它。
• tsconfig.json -- 创建一个 TypeScript 配置文件并安装所需依赖。

环境变量

遥测

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