在本地创建调试版本

了解如何在本地为你的 Expo 应用创建调试版本。

要在本地使用你的计算机将项目构建为应用，你必须在测试调试版本或创建用于提交到应用商店的生产版本之前手动生成原生代码。有两种方式可以在本地构建你的应用。本指南简要介绍了这两种方法，并提供了创建此工作流程所需的其他指南的参考。

🌐 To build your project into an app locally using your machine, you have to manually generate native code before testing the debug build or creating a production build for it to submit to the app store. There are two ways you can build your app locally. This guide provides a brief introduction to both methods and references to other guides that are necessary to create this workflow.

先决条件

🌐 Prerequisites

你需要安装并设置 Android Studio 和 Xcode，以便在本地机器上编译和运行 Android 和 iOS 项目。有关如何设置这些工具，请参见以下内容：

🌐 You need to install and set up Android Studio and Xcode to compile and run Android and iOS projects on your local machine. See the following on how to set up these tools:

• Android Studio
• Xcode

本地应用编译

🌐 Local app compilation

要在本地构建你的项目，你可以使用 Expo CLI 的编译命令，这些命令会生成 android 和 ios 目录：

🌐 To build your project locally you can use compile commands from Expo CLI which generates the android and ios directories:

上述命令会将你的项目编译成调试版应用，使用的是你本地安装的 Android SDK 或 Xcode。每条命令执行两个步骤：首先编译并将原生二进制文件安装到你的设备或模拟器上，然后启动 Metro 打包器以服务你的 JavaScript 或 TypeScript 代码。

🌐 The above commands compile your project, using your locally installed Android SDK or Xcode, into a debug build of your app. Each command performs two steps: it compiles and installs the native binary on your device or emulator, then starts the Metro bundler to serve your JavaScript or TypeScript code.

• 这些编译命令会先运行 npx expo prebuild 来生成本地目录（android 和 ios），然后再进行构建，如果这些目录尚不存在。如果目录已经存在，则会跳过此步骤。
• 你也可以添加 --device 标志来选择运行应用的设备——你可以选择一个物理连接的设备或模拟器/模拟器。
• 你可以传入 --variant release（Android）或 --configuration Release（iOS）来构建 应用的生产版本。请注意，这些构建未签名，无法提交到应用商店。要为你的生产版本签名，请参见 本地应用生产。
• 仅限 Android：从 SDK 54 开始，你可以传递 --variant debugOptimized 变体以加快开发迭代。有关更多信息，请参阅 在 Expo CLI 中编译 Android 参考 。

第一次构建后：使用 npx expo start

🌐 After the first build: use npx expo start

一旦应用被编译并安装到你的设备或模拟器上，每次修改时都不需要重新构建。如果你只是修改 JavaScript 或 TypeScript 代码，可以单独启动 Metro 打包器：

🌐 Once the app is compiled and installed on your device or emulator, you don't need to rebuild every time you make a change. If you're only modifying JavaScript or TypeScript code, you can start the Metro bundler on its own:

然后在终端中按 a 启动已安装的 Android 应用，或按 i 启动 iOS 应用。Metro 会提供更新后的 JavaScript 包，而无需重新编译原生代码，因此应用几秒钟内即可加载，而不是几分钟。

要在第一次构建后修改项目的配置或原生代码，你需要使用 npx expo run:android|ios 重新构建项目。再次运行 npx expo prebuild 会将更改叠加在现有文件之上。构建完成后，它也可能产生不同的结果。

🌐 To modify your project's configuration or native code after the first build, you will have to rebuild your project using npx expo run:android|ios again. Running npx expo prebuild again layers the changes on top of existing files. It may also produce different results after the build.

为了避免这种情况，当你创建新项目时，本地目录会自动添加到项目的 .gitignore 文件中，你可以使用 npx expo prebuild --clean 命令。这确保了项目始终被管理，并且 --clean 标志 会在重新生成之前删除现有目录。你可以使用 应用配置 或创建一个 配置插件 来修改项目配置或本地目录中的代码。

🌐 To avoid this, the native directories are automatically added to the project's .gitignore when you create a new project, and you can use npx expo prebuild --clean command. This ensures that the project is always managed, and the --clean flag will delete existing directories before regenerating them. You can use app config or create a config plugin to modify your project's configuration or code inside the native directories.

要了解有关编译和预构建如何工作的更多信息，请参阅以下指南：

🌐 To learn more about how compilation and prebuild works, see the following guides:

使用 expo-dev-client 的本地构建

🌐 Local builds with expo-dev-client

如果你在项目中安装 expo-dev-client，那么项目的调试版本将包含 expo-dev-client 用户界面和工具，我们称这些为开发版本。

🌐 If you install expo-dev-client to your project, then a debug build of your project will include the expo-dev-client UI and tooling, and we call these development builds.

要创建开发版本，你可以使用 本地应用编译 命令（npx expo run:[android|ios]），它将创建一个调试版本并启动开发服务器。

🌐 To create a development build, you can use local app compilation commands (npx expo run:[android|ios]) which will create a debug build and start the development server.

使用 Android 产品风格进行本地构建

🌐 Local builds using Android product flavors

警告 此功能仅适用于 SDK 52 及更高版本。

如果你有一个使用不同应用 ID 的多产品版本的自定义 Android 项目，你可以配置 npx expo run:android 来使用正确的版本和构建类型。Expo 支持使用 --variant 和 --app-id 来定制构建和启动行为。

🌐 If you have a custom Android project with multiple product flavors using different application IDs, you can configure npx expo run:android to use the correct flavor and build type. Expo supports both --variant and --app-id to customize the build and launch behavior.

--variant 标志可以将 Android 构建类型从 debug 切换为 release。当以驼峰命名格式使用时，此标志还可以配置产品风味和构建类型。例如，如果你同时有 免费 和 付费 产品风味，你可以使用以下命令构建应用的开发版本：

🌐 The --variant flag can switch the Android build type from debug to release. This flag can also configure a product flavor and build type, when formatted in camelCase. For example, if you have both free and paid product flavors, you can build a development version of your app with:

--app-id 标志可以在使用自定义应用 ID 构建后启动应用。例如，如果你的产品风味 free 使用的是 applicationIdSuffix ".free" 或 applicationId "dev.expo.myapp.free"，你可以运行构建并启动应用，命令如下：

🌐 The --app-id flag can be used to launch the app after building using a customized application id. For example, if your product flavor free is using applicationIdSuffix ".free" or applicationId "dev.expo.myapp.free" you can run build and launch the app with:

信息 也可以自定义 Android 构建类型，但这会破坏 Expo 对生产环境使用 release 构建类型的假设。你可以在应用中使用不同于 release 的构建类型来构建未优化的代码。

使用 EAS 进行本地构建

🌐 Local builds with EAS