中文网
Nodejs.cn 旗下网站
首页指南EAS参考教程

解决构建错误和崩溃问题

使用 EAS Build 时排除构建错误和崩溃的参考。

当出现问题时，可能会以以下两种方式之一出现问题：

¥When something goes wrong, it probably will go wrong in one of two following ways:

  1. 你的构建将会失败。

    ¥Your build will fail.

  2. 构建将成功，但会遇到运行时错误，例如，运行时崩溃或挂起。

    ¥The build will succeed but encounter a runtime error, for example, it crashes or hangs when you run it.

关于 缩小错误来源范围 的所有标准建议均适用于此处；本文档提供的信息可能对你的典型故障排除过程和技术有用。故障排除是一门艺术，你可能需要创造性地思考。

¥All standard advice around narrowing down the source of an error applies here; this document provides information that may be useful on top of your typical troubleshooting processes and techniques. Troubleshooting is an art, and you might need to think creatively.

查找相关错误日志

¥Find the related error logs

在进一步操作之前，你需要确保已找到错误消息并阅读它。根据你是调查构建失败还是运行时错误，执行此操作的方式会有所不同。

¥Before you go further, you need to be sure that you have located the error message and read it. How you do this will be different depending on whether you're investigating a build failure or runtime error.

运行时错误

¥Runtime errors

属于此类别的常见问题有："我的应用在本地运行良好，但当我运行构建时立即崩溃" 或 "我的应用可以在 Expo Go 中运行，但在我的构建中挂在启动屏幕上"。当你的应用构建成功但在运行时崩溃或挂起时，这被视为运行时错误。

¥Common questions that fall under this category are: "my app runs well locally but crashes immediately when I run a build" or "my app works in Expo Go but hangs on the splash screen in my build". When your app builds successfully but crashes or hangs when you run it, this is considered a runtime error.

请参阅 调试指南 "生产错误" 部分 了解如何在发布版本在运行时崩溃时查找日志。

¥Refer to the "Production errors" section of the debugging guide to learn how to locate logs when your release builds are crashing at runtime.

如果你无法通过这种方法找到任何有用的信息，请尝试 逐步缩小崩溃根源。

¥If you can't find any useful information through this approach, try narrowing down the source of the crash step by step.

构建错误

¥Build errors

转到构建详细信息页面（如果尚未打开，请在 构建仪表板 上找到它）并通过单击任何失败的构建阶段来展开它们。通常，最早出现错误的阶段将包含最有用的信息，并且任何后续失败的阶段都将从第一个阶段开始级联。

¥Go to your build details page (find it on the build dashboard if you don't have it open already) and expand any failed build phases by clicking on them. Often, the earliest phase with errors will contain the most useful information and any subsequent failed phase will have cascaded from the first.

无论处于哪个阶段，都经常会看到以 [stderr] 为前缀的日志条目，但请记住，这并不一定意味着这些日志指向错误；CLI 工具通常使用 stderr 来输出警告和其他诊断信息。

¥Regardless of the phase, it's common to see log entries prefixed with [stderr], but keep in mind that this doesn't necessarily mean those logs point to errors; it's common for CLI tools to use stderr to output warnings and other diagnostics.

例如，你可能会在 Android 版本上看到类似的内容：

¥For example, you might see something like this on your Android builds:

Terminal
[stderr] Note: /build/workingdir/build/app/node_modules/@react-native-async-storage/async-storage/android/src/main/java/com/reactnativecommunity/asyncstorage/AsyncStorageModule.java uses or overrides a deprecated API.[stderr] Note: Recompile with -Xlint:deprecation for details.

尽管你可能有兴趣跟进该警告，也可能不感兴趣，但这并不是构建失败的原因。那么你如何知道哪些日志真正负责呢？如果你正在构建一个裸项目，那么你已经擅长于此。如果你正在构建 管理项目，这可能会很棘手，因为你不直接与原生代码交互，只编写 JavaScript。

¥While you may or may not be interested in following up on that warning, it is not the cause of your failed build. So how do you know which logs are truly responsible? If you are building a bare project, you will already be good at this. If you are building a managed project, it may be tricky because you don't directly interact with the native code, only write JavaScript.

一个好的方法是确定构建是否由于原生错误或 JavaScript 错误而失败。当你的构建由于 JavaScript 构建错误而失败时，你通常会看到如下内容：

¥A good path forward is to determine if the build failed due to a native or JavaScript error. When your build fails due to a JavaScript build error, you will usually see something like this:

Terminal
❌ Metro encountered an error:Unable to resolve module ./src/Routes from /Users/expo/workingdir/build/App.js

此特定错误意味着应用正在导入 ./src/Routes 但未找到。原因可能是 Git 中的文件名大小写与开发者的文件系统不同（例如，Git 中的 paths.js 而不是 Routes.js），或者项目可能有一个构建步骤，但未设置为在其上运行 EAS 构建。在这种情况下，事实证明，在这种情况下 ./src/Routes 旨在导入 ./src/Routes/index.js，但该路径被意外地排除在开发者的 .gitignore 中。

¥This particular error means that the app is importing ./src/Routes and it is not found. The cause could be that the filename case is different in Git than the developer's filesystem (for example, routes.js in Git instead of Routes.js), or maybe the project has a build step and it wasn't set up to run on EAS Build. In this case, it turns out that in this case ./src/Routes was intended to import ./src/Routes/index.js, but that path was accidentally excluded in the developer's .gitignore.

需要注意的是，对于 iOS 构建，构建详细信息页面仅显示日志的缩略版本，因为 xcodebuild 的完整输出可能约为 10MB。有时需要打开完整的 Xcode 日志来查找所需的信息；例如，如果 JavaScript 构建失败，但你在构建详细信息页面上看不到任何有用的信息。要打开完整的 Xcode 日志，请在构建完成后滚动到构建详细信息页面的底部，然后单击查看或下载它们。

¥It's important to note that with iOS builds the build details page only displays an abridged version of the logs because the full output from xcodebuild can be in the order of 10MB. Sometimes it's necessary to open the full Xcode logs to find the information that you need; for example, if the JavaScript build failed but you don't see any useful information on the build details page. To open the full Xcode logs, scroll to the bottom of the build details page when the build has been completed and either click to view or download them.

如果你正在开发托管应用，并且构建错误是原生错误而不是 JavaScript 错误，则这可能是由于项目中的 配置插件 或依赖造成的。请留意日志中自上次成功构建以来添加的任何新软件包。运行 npx expo-doctor 以确定你的项目中的 Expo SDK 依赖的版本与你的 Expo SDK 版本兼容。

¥If you are working on a managed app and the build error is a native error rather than a JavaScript error, this is likely due to a config plugin or a dependency in your project. Keep an eye out in the logs for any new packages that you have added since your previous successful build. Run npx expo-doctor to determine that the versions of Expo SDK dependencies in your project are compatible with your Expo SDK version.

有了错误日志，你通常可以开始修复构建或搜索 forums 和 GitHub 问题以查找相关包以进行更深入的挖掘。下面列出了一些常见的问题来源。

¥Armed with your error logs, you can often start to fix your build or search the forums and GitHub issues for related packages to dig deeper. Some common sources of problems are listed below.

Are you using a monorepo?

Monorepos are incredibly useful but they do introduce their own set of problems. It's necessary to upload the entire monorepo to the EAS Build builders, set it up, and run the build.

EAS Build is more like a typical CI service in that we need the source code, rather than a compiled JavaScript bundle and manifest. EAS Build has first-class support for Yarn workspaces, and your success may vary when using other monorepo tools.

For more information, see Working with monorepos.

Out-of-memory (OOM) errors

If your build fails with "Gradle build daemon disappeared unexpectedly (it may have been killed or may have crashed)" in your Gradle logs, this is because the Node process responsible for bundling your app JavaScript was killed.

This can often be a sign that your app bundle is extremely large, which will make your overall app binary larger and lead to slow boot up times, especially on low-end Android devices. Sometimes the error can occur when large text files are treated as source code, for example, if you have a JavaScript file that contains a string of 1MB+ of HTML to load into a webview, or a similarly sized JSON file.

To determine how large your bundle is and to see a breakdown of where the size comes from, use Expo Atlas.

To increase memory limits on your EAS Build builders, use large resource class in your eas.json. See Android-specific resource class and iOS-specific resource class for more information.

None of the files exist error

When you run eas build, your project's files are uploaded to Expo's build servers. However, any file or directory mentioned in the .gitignore is not uploaded. This is intentional to prevent sensitive information, such as API keys, from being exposed in your app's code.

If your project imports a file listed in .gitignore, the build will fail with a None of these files exist error. There are different ways you can resolve this error:

  • Remove the import statement for the ignored file and test your project. If your project functions as expected, that import statement may have been outdated or unused.

  • Remove any files or directories Metro was unable to resolve from your .gitignore. However, this poses a security risk since any sensitive information included in these files will now be available in your project's source code and Git commit history.

  • Encode the file with base64, save that string as secrets, and create the file in an EAS Build hook. See How can I upload files to EAS Build if they are gitignored? for more information.

  • Refactor your source code to avoid importing sensitive files on the client side. If a file is an auto-generated code from a third-party provider and that provider has automatically listed files in your .gitignore, then that file probably contains sensitive information. You should not include it on the client side. During app development, ensure you follow secure practices, such as using environment variables or serving them through your backend. See Using secrets in environment variables for more information.

Verify that your JavaScript bundles locally

When a build fails with Task :app:bundleReleaseJsAndAssets FAILED (Android) or Metro encountered an error (iOS), it means Metro bundler was unable to bundle the app's JavaScript code while trying to embed it in your app's binary. This error message is usually followed by a syntax error or other details about why bundling failed. Unfortunately, a standard React Native project is configured to perform this step late in the Gradle/Xcode build step, meaning it can take a while to see this error.

You can build the production bundle locally by running npx expo export to bypass all of the other build steps so you can see this error much more quickly. Run this command repeatedly, resolving any syntax errors or other issues uncovered until the bundle builds successfully. Then try your EAS Build again.

Verify that your project builds and runs locally

If the logs weren't enough to immediately help you understand and fix the root cause, it's time to try to reproduce the issue locally. If your project builds and runs locally in release mode then it will also build on EAS Build, provided that the following are all true:

  • Relevant Build tool versions (for example, Xcode, Node.js, npm, Yarn) are the same in both environments.
  • Relevant environment variables are the same in both environments.
  • The archive that is uploaded to EAS Build includes the same relevant source files.

You can verify that your project builds on your local machine with the npx expo run:android and npx expo run:ios commands, with variant/configuration flags set to release to most faithfully reproduce what executes on EAS Build. For more information, see Android build process and iOS build process.

Terminal
# Locally compile and run the Android app in release mode
- npx expo run:android --variant release

# Locally compile and run the iOS app in release mode
- npx expo run:ios --configuration Release

If use CNG, these commands will run npx expo prebuild to generate native projects to compile them.You likely want to clean up the changes once you are done troubleshooting, unless you want to start managing these projects directly instead of generating them on demand.


You can alternatively run a local build with eas build --local — this command will run a series of steps that is as close as it can be to what runs remotely on the hosted EAS Build service. It will copy your project to a temporary directory and make any necessary changes there. Learn how to set this up and use it for debugging.

If your native toolchains are installed correctly and you are unable to build and run your project in release mode on your local machine, it will not build on EAS Build. Fix the issues locally, then try again on EAS Build. The other advice in this doc may be useful to help you resolve the issue locally, but often this requires some knowledge of native tooling or judicious application of Google, Stack Overflow, and GitHub Issues.

Don't have Xcode and Android Studio set up on your machine?

If you do not have native toolchains installed locally, for example, because you do not have an Apple computer and therefore cannot build an iOS app on your machine, it can be trickier to get to the bottom of build errors. The feedback loop of making small changes locally and then seeing the result on EAS Build is slower than doing the same steps locally because the EAS Build builder must set up its environment, download your project, and install dependencies before starting the build.

If you are willing and able to set up the appropriate native tools, then refer to the React Native environment setup guide.

My app builds locally, but not on EAS Build

By default, EAS Build follows a relatively straightforward process for building your app for (Android or iOS). If npx expo run:android --variant release and npx expo run:ios --configuration Release work locally, but your builds fail, then it's time to narrow down what configuration exists on your machine that hasn't been set up for your project on EAS Build yet.

  • Do a fresh git clone of your project to a new directory and get it running, ideally on a different machine. Pay attention to each of the steps that are needed and verify that they are also configured for EAS Build.
  • Check that your environment variables are properly configured.
  • Verify that versions of Node.js, npm, Yarn, Xcode, Java, and other tools are the same in both environments.
  • Ensure that the archive you are uploading to EAS Build includes the same relevant source files.
Why does my production app not match my development app?

You can test how the JS part of your app will run in production by starting it with npx expo start --no-dev. This tells the bundler to minify JavaScript before serving it, most notably stripping code protected by the __DEV__ boolean. This will remove most of the logging, HMR, Fast Refresh functionality, and make debugging a bit harder, but you can iterate on the production bundle faster this way.

Still having trouble?

This guide is far from being comprehensive, and depending on your level of experience you might still be struggling to get your app working.

If you have followed the advice here, you're now in a good position to describe your issue to other developers and get some help.

How to ask a good question

Join us on Discord and Forums

用于向社区和 Expo 团队寻求帮助。Expo 团队会尽最大努力回应高质量且清晰明确的问题，但除非你注册了 支持计划，否则不能保证得到回应。为确保 Expo 团队成员看到你的问题，你可以在 expo.dev/contact 提交票证。

¥to ask for help from the community and the Expo team. The Expo team does our best to respond to high quality and well-articulated questions and issues, but responses are not guaranteed unless you are signed up for a support plan. To ensure that an Expo team member sees your question, you can file a ticket at expo.dev/contact.

当你寻求故障排除帮助时，请务必分享以下信息：

¥When you ask for troubleshooting help, be sure to share the following information:

  • 指向你的构建页面的链接。只有你的团队或 Expo 员工才能访问此内容。如果你想更公开地分享，请截取屏幕截图。如果你想更私密地分享，请发送电子邮件至 secure@expo.dev，并在聊天或论坛上的帮助请求中提及这一点。如果你使用 eas build --local 在本地执行此构建，则可以省略这一点，但请提及这一事实。

    ¥A link to your build page. This can only be accessed by your team or Expo employees. If you'd like to share it more publicly, take a screenshot. If you'd like to share it more privately, send an email to secure@expo.dev and mention that in your help request on chat or forums. If you are performing this build locally with eas build --local, you can omit this, but do mention this fact.

  • 错误日志。你怀疑的任何事情都可能与你的构建或运行时错误有关。如果你无法提供此信息，请解释原因。

    ¥Error logs. Anything that you suspect may be related to your build or runtime error. If you can't provide this, explain why not.

  • 最小的可重现示例或存储库的链接。解决问题的最快方法是确保其他开发者可以重现该问题。如果你曾经在团队中工作过，你就会从经验中知道这一点。在许多情况下，如果你无法提供可重现的示例，那么它可能无法为你提供帮助，并且来回询问和回答问题的过程充其量只是一种低效的时间利用。在 手动调试指南 和 Stack Overflow 的 最小可行可重复示例 指南中了解有关如何创建可重现示例的更多信息。

    ¥Minimal reproducible example or a link to your repository. The quickest way to get a solution to your problem is to ensure that other developers can reproduce it. If you have ever worked on a team, you know this from experience. In many cases, if you can't provide a reproducible example then it may not be possible to help you, and at best the back-and-forth process of asking and answering questions will be an inefficient use of time. Learn more about how to create a reproducible example in the manual debugging guide and Stack Overflow's Minimal Viable Reproducible Example guide.

尽量做到清晰、准确且有帮助。Stack Overflow 的 如何提出一个好问题 指南提供的一般指导适用。

¥Try to be clear, precise, and helpful. General guidance provided by Stack Overflow's How to ask a good question guide applies.