了解如何使用 --local 标志在你的计算机或自定义基础架构上本地使用 EAS Build。

---

你可以使用 eas build --local 标志直接在你的机器上运行通常在 EAS Build 服务器上运行的相同构建过程。这是一种调试云构建中发生的构建失败的有用方法，如果不运行相同的步骤，你可能无法重现这些失败。

¥You can run the same build process that is typically run on the EAS Build servers directly on your machine by using the eas build --local flag. This is a useful way to debug build failures that are happening on your cloud builds, which you may not be able to reproduce without running the same set of steps.

注意：要使用 Expo CLI 在本地编译和运行你的应用，请改用 npx expo run:android 或 npx expo run:ios 命令。如果你使用 持续的原生生成，你还可以运行 prebuild 来生成你的 android 和 ios 目录，然后继续在相应的 IDE 中打开项目并像任何原生项目一样构建它们。使用这两种方法，你都不会遵循使用 EAS Build 在云上运行的确切过程 - 这就是 eas build --local 标志的用途。

¥Note: To compile and run your app locally with Expo CLI, use npx expo run:android or npx expo run:ios commands instead. If you use Continuous Native Generation, you can also run prebuild to generate your android and ios directories and then proceed to open the projects in the respective IDEs and build them like any native project. With both of these approaches, you will not be following the exact process that is run on the cloud with EAS Build — that is what the eas build --local flag is for.

先决条件

¥Prerequisites

你需要通过 Expo 的身份验证：

¥You need to be authenticated with Expo:

• 运行 eas login

  ¥Run eas login

• 或者，设置 EXPO_TOKEN 使用基于令牌的身份验证

  ¥Alternatively, set EXPO_TOKEN using token-based authentication

本地构建的用例

¥Use cases for local builds

• EAS 服务器上的 调试 构建失败。

  ¥Debugging build failures on EAS servers.

• 限制使用第三方 CI/CD 服务的公司政策。通过本地构建，整个过程在你的基础设施上运行，与 EAS 服务器的唯一通信是：

  ¥Company policies that restrict the use of third-party CI/CD services. With local builds, the entire process runs on your infrastructure and the only communication with EAS servers is:

  • 确保项目 @account/slug 存在

    ¥to make sure project @account/slug exists

  • 如果你使用托管凭据来下载它们

    ¥if you are using managed credentials to download them

使用本地构建进行调试

¥Use local builds for debugging

如果你在 EAS 服务器上遇到构建失败，并且无法通过检查日志确定原因，你可能会发现在本地调试问题很有帮助。为了简化该过程，我们支持多个环境变量来配置本地构建过程。

¥If you encounter build failures on EAS servers and you're unable to determine the cause from inspecting the logs, you may find it helpful to debug the issue locally. To simplify that process we support several environment variables to configure the local build process.

• EAS_LOCAL_BUILD_SKIP_CLEANUP=1 - 设置此选项可在构建过程完成后禁用清理工作目录。

  ¥EAS_LOCAL_BUILD_SKIP_CLEANUP=1 - Set this to disable cleaning up the working directory after the build process is finished.

• EAS_LOCAL_BUILD_WORKINGDIR - 指定构建过程的工作目录，默认情况下它位于 /tmp 目录中的某个位置（取决于平台）。

  ¥EAS_LOCAL_BUILD_WORKINGDIR - Specify the working directory for the build process, by default it's somewhere (it's platform dependent) in /tmp directory.

• EAS_LOCAL_BUILD_ARTIFACTS_DIR - 成功构建后复制工件的目录。默认情况下，这些文件会被复制到当前目录，如果你正在运行许多连续的构建，这可能是不理想的。

  ¥EAS_LOCAL_BUILD_ARTIFACTS_DIR - The directory where artifacts are copied after a successful build. By default, these files are copied to the current directory, which may be undesirable if you are running many consecutive builds.

如果你使用 EAS_LOCAL_BUILD_SKIP_CLEANUP 和 EAS_LOCAL_BUILD_WORKINGDIR 进行 iOS 构建，你应该能够检查工作目录的 logs 子目录的内容以读取你的 Xcode 日志。

¥If you use EAS_LOCAL_BUILD_SKIP_CLEANUP and EAS_LOCAL_BUILD_WORKINGDIR for iOS builds you should be able to inspect the contents of the logs subdirectory of the working directory to read your Xcode logs.

局限性

¥Limitations

一些可用于云构建的选项在本地不可用。你应该注意的限制：

¥Some of the options available for cloud builds are not available locally. Limitations you should be aware of:

• 你只能针对特定平台进行构建（选项 all 已禁用）。

  ¥You can only build for a specific platform (option all is disabled).

• 不支持自定义软件版本，eas.json 中的 node、yarn、fastlane、cocoapods、ndk、image 字段将被忽略。

  ¥Customizing versions of software is not supported, fields node, yarn, fastlane, cocoapods, ndk, image in eas.json are ignored.

• 不支持缓存。

  ¥Caching is not supported.

• 不支持 EAS Secret（请在本地环境中设置它们）。

  ¥EAS Secrets are not supported (set them in your environment locally instead).

• 你有责任确保环境安装了所有必要的工具：

  ¥You are responsible for making sure that the environment has all the necessary tools installed:

  • Node.js/Yarn/npm

  • 快速通道（仅限 iOS）

    ¥fastlane (iOS only)

  • CocoaPods（仅限 iOS）

    ¥CocoaPods (iOS only)

  • Android SDK 和 NDK

    ¥Android SDK and NDK

• 在 Windows 上，你可以使用 WSL 进行本地 EAS 构建。但是，我们并未针对此平台进行正式测试，并且不支持 Windows 本地构建（支持 macOS 和 Linux）。

  ¥On Windows, you can use WSL for local EAS Builds. However, we do not officially test against this platform and do not support Windows for local builds (macOS and Linux are supported).