This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

了解如何诊断和解决运行 EAS 工作流时的常见问题。

本页列出了常见的 EAS 工作流故障模式以及解决方法。如果工作流无法启动或某个任务失败，可以先从你项目的工作流页面上的工作流运行详情页开始查看。那里会显示每个任务的状态、日志和错误信息。

🌐 This page lists common EAS Workflows failure modes and how to fix them. If a workflow doesn't start or a job fails, start with the workflow run's detail page on your project's workflows page. It shows each job's status, logs, and errors.

验证工作流程文件

🌐 Validate the workflow file

在运行之前，检查工作流文件的 YAML 语法和模式错误：

🌐 Check a workflow file for YAML syntax and schema errors before running it:

该命令还会验证工作流从其步骤或钩子调用的任何自定义函数。

🌐 The command also validates any custom functions that the workflow calls from its steps or hooks.

Expo Tools VS Code 扩展 在你编辑工作流文件时，也会提供描述和自动补全功能。

🌐 The Expo Tools VS Code extension also provides descriptions and autocompletion for workflow files as you edit them.

工作流在 GitHub 事件上没有启动

🌐 Workflow doesn't start on GitHub events

如果一个带有 on 触发器 的工作流从未启动，请检查以下内容：

🌐 If a workflow with an on trigger never starts, check the following:

• GitHub 连接：像 push、pull_request 和 ref_delete 这样的触发器需要你的 EAS 项目关联到 GitHub 仓库。
• 工作流文件位置和引用：文件必须在 .eas/workflows 目录下。对于 push 和 pull_request 事件，EAS 会从触发的提交中读取工作流文件，所以文件必须存在于该分支上。对于 schedule 和 ref_delete 事件，EAS 会从默认分支读取工作流文件。
• 触发器过滤器：branches、tags、paths、types 和 labels 过滤器必须匹配事件。例如，on.push.branches: ['main'] 会忽略对其他所有分支的推送。
• 提交信息跳过标记：当提交信息包含 [eas skip]、[skip eas] 或 [no eas] 时，由 push 和 pull_request 事件触发的运行会被跳过。
• 计划工作流：on.schedule 工作流仅从仓库的默认分支运行，按 GMT 时区执行，并且在高负载期间可能会延迟。

构建任务失败，提示“eas.json 中缺少构建配置”

🌐 Build job fails with "Missing build profile in eas.json"

预打包的 构建任务 需要它们使用的构建配置在你项目的 eas.json 中存在。构建任务会使用 production 配置，除非任务的 params.profile 另有说明，所以如果 eas.json 为空或不存在，就会出现这个错误。

🌐 Pre-packaged build jobs require the build profile they use to exist in your project's eas.json. Build jobs use the production profile unless the job's params.profile says otherwise, so an empty or missing eas.json fails with this error.

将配置文件添加到 eas.json，或运行 eas build:configure 生成带有默认配置文件的文件。构建还需要为每个平台提供应用签名凭据。使用相同的平台和配置文件通过 EAS CLI 完成一次构建即可同时设置两者。请参见 创建你的第一个构建。

🌐 Add the profile to eas.json, or run eas build:configure to generate the file with default profiles. Builds also need app signing credentials for each platform. Completing one build with EAS CLI using the same platform and profile sets up both. See create your first build.

环境变量为空或丢失

🌐 Environment variable is empty or missing

EAS 环境变量 是针对某个环境的：production、preview 或 development。一个作业只能看到由其 environment key 设置的环境中的变量，默认为 production。如果作业中的某个变量为空，请确认该变量存在于作业使用的环境中，或者将作业的 environment 设置为与变量定义的地方一致。

另外请注意，env 键 在 apple-device-registration-request、branch-delete、doc、get-build、github-comment、require-approval 和 slack 工作中不可用。

🌐 Also note that the env key is not available on the apple-device-registration-request, branch-delete, doc, get-build, github-comment, require-approval, and slack jobs.

更多帮助

🌐 More help

如果你仍然卡住了，可以把你的工作流文件和出错运行的链接发邮件到 workflows@expo.dev，或者在 Expo Discord 里问。

🌐 If you're still stuck, email workflows@expo.dev with your workflow file and a link to the failing run, or ask in the Expo Discord.