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:
-
npx expo -h
如果你更喜欢使用 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:
-
npx expo login -h
¥Installation
Expo CLI 包含在 expo
软件包中。你可以使用 npm 或 yarn 安装它:
¥Expo CLI is included in the expo
package. You can install it with npm or yarn:
-
yarn add expo
未使用 Expo 预建 的项目(也称为裸项目)将需要执行其他设置以确保所有自定义 Expo 打包功能正常工作:Metro:裸工作流程设置。
¥Projects that are not using Expo Prebuild (also referred to as Bare projects) 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 start
你还可以将
npx expo
作为npx expo start
的别名运行。¥You can also run
npx expo
as an alias tonpx expo start
.
此命令在 http://localhost:8081
上启动一个服务器,客户端可以使用它来与打包器交互。默认打包程序是 Metro。
¥This command starts a server on http://localhost:8081
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:
键盘快捷键 | 描述 |
---|---|
A | 在连接的 Android 设备上打开项目。 |
Shift + A | 选择要打开的 Android 设备或模拟器。 |
I | 在 iOS 模拟器中打开项目。 |
Shift + I | 选择要打开的 iOS 模拟器。 |
W | 在 Web 浏览器中打开该项目。这可能需要在你的项目中安装 webpack。 |
R | 在任何连接的设备上重新加载应用。 |
S | 在 Expo Go 和开发版本之间切换启动目标。 |
M | 在任何连接的原生设备上打开开发菜单(不支持 Web)。 |
Shift + M | 选择更多命令在连接的设备上触发。 这包括切换性能监视器、打开元素检查器、重新加载设备以及打开开发菜单。 |
J | 为任何使用 Hermes 作为 JavaScript 引擎的连接设备打开 Chrome 开发工具。了解更多。 |
O | 在编辑器中打开项目代码。这可以通过 EXPO_EDITOR 和 EDITOR 环境变量 进行配置。 |
E | 在终端中以二维码形式显示开发服务器 URL。 |
? | 显示所有终端 UI 命令。 |
¥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)。使用 --port 0
自动使用第一个可用端口。默认:8081.
¥--port
: Port to start the dev server on (does not apply to webpack or tunnel URLs). Use --port 0
to automatically use the first available port. Default: 8081.
--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:
-
export EXPO_PACKAGER_PROXY_URL=http://expo.dev
-
npx expo start
将打开应用以: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
:
-
npm i -g @expo/ngrok
然后运行以下命令从隧道 URL 启动你的开发服务器:
¥Then run the following to start your dev server from a tunnel URL:
-
npx expo start --tunnel
这将从公共 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 to modify their antivirus settings to allow Ngrok to work correctly.
¥Offline
你可以使用 --offline
标志在没有网络连接的情况下进行开发:
¥You can develop without a network connection by using the --offline
flag:
-
npx expo start --offline
离线将阻止 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 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:
# Build for iOS
-
npx expo run:ios
# Build for Android
-
npx expo run:android
高亮
¥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.
--binary <path>
:要安装在设备上的二进制文件的文件路径。当提供此信息时,将跳过构建过程并尝试直接安装二进制文件。如果二进制文件不是为正确的设备构建的,例如,它是为模拟器构建的或安装在设备上,则命令将失败。
¥--binary <path>
: File path to the binary to install on the device. When this is provided, the build process will be skipped and the binary will attempt to be installed directly. If the binary was not built for the correct device, for example, it is built for the simulator or installed on the device, then the command will fail.
¥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:
-
npx expo run:android --variant debug
你可以通过运行以下命令来编译 Android 应用以用于生产:
¥You can compile the Android app for production by running:
-
npx expo run:android --variant release
此版本不会自动进行代码签名以提交到 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:
-
open -a /Applications/Android Studio.app android
¥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:
-
npx expo run:ios --configuration Release
此版本不会自动进行代码签名以提交到 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:
-
xed ios
从 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:
-
npx expo export
当使用 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.
你可以通过设置 应用配置 中的 experiments.baseUrl
字段来配置静态资源的前缀:
¥You can configure the prefix for static assets by setting the experiments.baseUrl
field in your app config:
{
"expo": {
"experiments": {
"baseUrl": "/my-root"
}
}
}
这将导出包含所有前缀为 /my-root
的资源的网站。例如,assets/image.png
处的图片预计将托管在 /my-root/assets/image.png。实际文件将位于同一文件系统位置,因为整个目录预计托管在服务器上的 /my-root
处。
¥This will export the website with all resources prefixed with /my-root
. For example, an image at assets/image.png
will be expected to be hosted at /my-root/assets/image.png. The actual file will be located in the same file system location as the entire directory is expected to be hosted at /my-root
on the server.
Expo Router 内置了对 baseUrl
的支持。使用 Link
和 router
API 时,baseUrl
将自动添加到 URL 前面。
¥Expo Router has built-in support for baseUrl
. When using the Link
and router
APIs, the baseUrl
will be automatically prepended to the URL.
import { Link } from 'expo-router';
export default function Blog() {
return <Link href="/blog/123">Go to blog post</Link>;
}
这将导出到以下内容:
¥This will export to the following:
<a href="/my-root/blog/123">Go to blog post</a>
如果你直接使用 <a>
、React Navigation 或 Linking
API,则需要手动在前面添加 baseUrl
。
¥If you use <a>
, React Navigation, or the Linking
API directly, you'll need to manually prepend the baseUrl
.
baseUrl
功能仅供生产使用,必须在导出网站之前设置。如果更改该值,则必须重新导出网站。
¥The baseUrl
functionality is production-only and must be set before exporting the website. If you change the value, you must re-export the website.
如果你对图片和其他资源进行 require
或 import
,它们将自动工作。如果直接引用资源 URL,则需要手动附加 baseUrl。
¥Images and other assets will work automatically if you require
or import
them. If you directly reference a resource URL then you will need to append the baseUrl manually.
import { Image } from 'expo-image';
export default function Blog() {
return <Image source={require('@/assets/image.png')} />;
}
这将导出到以下内容:
¥This will export to the following:
<img src="/my-root/assets/assets/image.png" />
手动传递 URL 需要手动添加前缀:
¥Manually passing a URL will need to be manually prefixed:
export default function Blog() {
return <img src="/my-root/assets/image.png" />;
}
¥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:
-
npx expo export:web
--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
-
npx expo 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:
-
npx expo config
--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
:
-
npx expo install expo-camera
运行此命令的单个实例,你还可以安装多个包:
¥Running a single instance of this command, you can also install multiple packages:
-
npx expo install typescript expo-sms
你可以使用 --
运算符直接将参数传递给底层包管理器:
¥You can directly pass arguments to the underlying package manager by using the --
operator:
-
yarn expo install typescript -- -D
# yarn add typescript -D
¥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:
# Check all packages for incorrect versions, prompt to fix locally
-
npx expo install --check
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:
# Check only react-native and expo-sms
-
npx expo install react-native expo-sms --check
命令 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:
-
npx expo install --fix
¥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.
注册 npx expo register
帐号。
¥Register an account with npx expo register
.
使用 npx expo login
登录你的账户。
¥Login to your account with npx expo login
.
检查当前哪个账户已通过 npx expo whoami
进行身份验证。
¥Check which account is currently authenticated with npx expo whoami
.
使用 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:
-
npx expo customize
从这里,你可以选择生成基本项目文件,例如:
¥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
名称 | 类型 | 描述 |
---|---|---|
HTTP_PROXY | string | 用于连接所有网络请求的 HTTP/HTTPS 代理 URL。配置 Undici EnvHttpProxyAgent。 |
EXPO_NO_WEB_SETUP | boolean | 防止 CLI 在使用 Web 功能之前强制安装 Web 依赖(react-dom 、react-native-web 、@expo/webpack-config )。这对于你希望执行非标准 Web 开发的情况非常有用。 |
EXPO_OFFLINE | boolean | 如果适用,跳过所有网络请求。这使得网络连接较差的地区能够更快地发展。 |
EXPO_NO_TYPESCRIPT_SETUP | boolean | 防止 CLI 强制在 npx expo start .上配置 TypeScript 有关详细信息,请参阅 TypeScript 指南。 |
DEBUG=expo:* | string | 启用 CLI 的调试日志,你可以使用 debug 公约。 |
EXPO_DEBUG | boolean | DEBUG=expo:* 的别名。 |
EXPO_PROFILE | boolean | 启用 CLI 的分析统计信息,这不会分析你的应用。 |
EXPO_NO_CACHE | boolean | 禁用所有全局缓存。默认情况下,应用配置 JSON 架构、模拟器和模拟器的 Expo Go 二进制文件以及项目模板缓存在计算机上的全局 .expo 文件夹中。 |
CI | boolean | 启用后,CLI 将禁用交互功能、跳过可选提示,并在非可选提示上失败。 示例:如果任何已安装的软件包已过时, CI=1 npx expo install --check 将失败。 |
EXPO_NO_TELEMETRY | boolean | 禁用匿名使用收集。了解有关遥测的更多信息。 |
EXPO_NO_GIT_STATUS | boolean | 在 npx expo prebuild --clean 等潜在危险操作期间跳过有关 git 状态的警告。 |
EXPO_NO_REDIRECT_PAGE | boolean | 禁用用于选择应用的重定向页面,该页面显示用户何时安装了 expo-dev-client ,并使用 npx expo start 而不是 npx expo start --dev-client 启动项目。 |
EXPO_PUBLIC_FOLDER | string | 用于 Web 版 Metro 的公用文件夹路径。了解有关自定义 Metro 的更多信息. 默认: public |
EDITOR | string | 在终端 UI 中按 O 时要打开的编辑器的名称。该值在许多命令行工具中使用。 |
EXPO_EDITOR | string | EDITOR 变量的 Expo 特定版本,在定义时具有更高的优先级。 |
EXPO_IMAGE_UTILS_NO_SHARP | boolean | 禁用全局 Sharp CLI 安装,转而使用速度较慢的 Jimp 软件包进行图片处理。这在 npx expo prebuild 等地方用于生成应用图标。 |
EXPO_TUNNEL_SUBDOMAIN | boolean | Experimental 可使用 exp.direct 作为 --tunnel 连接的主机名。This enables https:// forwarding which can be used to test universal links on iOS.这可能会导致 expo-linking 和 Expo Go 出现意外问题。通过传递不属于以下之一的 string 值来选择要使用的确切子域:true 、false 、1 、0 。 |
EXPO_METRO_NO_MAIN_FIELD_OVERRIDE | boolean | 强制 Expo CLI 在所有平台上使用项目的 Metro.config.js 中的 resolver.resolverMainFields 。默认情况下,Expo CLI 将使用 ['browser', 'module', 'main'] ,这是 webpack 的默认值,用于 Web 以及其他平台的用户定义的主字段。 |
EXPO_NO_INSPECTOR_PROXY | boolean | Deprecated 启用自定义检查器代理,改进对 Chrome DevTools 协议的支持。这包括对网络检查器的支持。 |
EXPO_NO_CLIENT_ENV_VARS | boolean | SDK 49+ 防止在客户端打包包中内联 EXPO_PUBLIC_ 环境变量。 |
EXPO_NO_DOTENV | boolean | SDK 49+ 防止所有 .env 文件在 Expo CLI 中加载。 |
EXPO_NO_METRO_LAZY | boolean | 防止将 lazy=true 查询参数添加到 Metro URL(metro@0.76.3 及更高版本)。这将禁用 import() 支持。 |
EXPO_USE_TYPED_ROUTES | boolean | 使用 expo.experiments.typedRoutes 在 Expo Router 中启用静态类型路由。 |
EXPO_METRO_UNSTABLE_ERRORS | boolean | Experimental 能够在 Metro 打包器中改进不稳定的错误消息。该标志背后的功能可能会被删除,并且可能会被上游化。 |
EXPO_USE_METRO_WORKSPACE_ROOT | boolean | Deprecated: SDK 52+ 启用 Metro 的自动服务器根检测。这会将服务器根目录更改为工作区根目录。对于单一仓库很有用。 |
EXPO_NO_METRO_WORKSPACE_ROOT | boolean | SDK 52+ 启用 Metro 的自动服务器根检测。禁用不会将服务器根更改为工作区根。启用此功能对 monorepos 很有用。 |
EXPO_USE_UNSTABLE_DEBUGGER | boolean | Experimental 启用来自 React Native 的实验性调试器。 |
EXPO_ADB_USER | string | SDK 50+ 使用 ADB 命令设置应传递给 --user 的 user 编号。用于在具有多个配置文件的 Android 设备上安装 APK。默认为 0 。 |
EXPO_NO_TELEMETRY_DETACH | boolean | SDK 51+ 在 @expo/cli 的主线程中结束遥测事件。这会导致 CLI 在等待所有事件发送时变慢。 |
EXPO_USE_FAST_RESOLVER | boolean | SDK 51+ 能够在 Metro 中将解析速度提高 6 倍。没有已知问题,这很可能成为默认设置。 |
EXPO_UNSTABLE_ATLAS | boolean | Experimental SDK 51+ 开发或导出期间的其他 Metro 打包包信息。 |
EXPO_NO_BUNDLE_SPLITTING | boolean | Experimental SDK 51+ 在生产环境中启用 Metro 异步导入的分块(仅限网络)。 |
EXPO_USE_METRO_REQUIRE | boolean | SDK 52+ 能够使用 Expo 的自定义 Metro require 实现和基于 string 的模块 ID。这为 React Server Components 提供了更好的调试和确定性 ID。不支持旧版 RAM 打包包。 |
EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH | boolean | Experimental SDK 52+ 启用预打包,其中转换在创建整个打包包后不缓存运行。这是生产树摇动所必需的,并且针对开发打包的优化程度较低。 |
EXPO_UNSTABLE_TREE_SHAKING | boolean | Experimental SDK 52+ 能够在所有平台上支持不稳定的树摇动。详细信息请参见 使用部分。 |
¥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.