从 Expo GitHub 应用触发构建

了解如何使用 Expo GitHub 应用在 EAS 上触发应用的构建。

本指南介绍了如何使用 Expo GitHub 应用直接从 GitHub 存储库触发构建。

🌐 This guide explains how to trigger builds directly from your GitHub repository using the Expo GitHub App.

先决条件

🌐 Prerequisites

在你的 eas.json 中设置 `image` 字段

🌐 Set the image field in your eas.json

对于你想在 GitHub 上使用的构建配置文件，请在 eas.json 中为原生平台指定一个 image。

🌐 For the build profiles you want to use with GitHub, specify an image to use for the native platform in eas.json.

如果你的项目配置不依赖于特定的构建镜像，请使用 latest 镜像。例如：

🌐 Use the latest image if your project's configuration does not rely on a specific build image. For example:

eas.json

{
  %%placeholder-start%%... %%placeholder-end%%
  "build": {
    "production": {
      "android": {
        "image": "latest"
      },
      "ios": {
        "image": "latest"
      }
    }
  }
}

从本地计算机运行成功的构建

🌐 Run a successful build from your local machine

要从 GitHub 存储库触发 EAS 构建，你需要为 EAS 构建配置项目，并从你的计算机为你希望在 GitHub 上支持的每个平台成功运行构建。

🌐 To trigger EAS builds from a GitHub repo, you'll need to configure your project for EAS Build and successfully run a build from your computer for each platform that you'd like to support on GitHub.

如果你还没有成功运行 eas build -p [all|ios|android]，请参阅创建你的第一个构建获取更多信息。一旦完成，请继续本指南中的步骤。

🌐 If you haven't successfully run eas build -p [all|ios|android] yet, see Create your first build for more information. Once you have, continue with the steps in this guide.

以下也必须为真：

🌐 The following must also be true:

组织中的 Expo 用户必须拥有一个与目标仓库有访问权限的关联 GitHub 用户。请检查账户设置 > 概览 > 用户设置 > 连接，并确认你的 GitHub 用户账户已关联。
你必须接受 Expo GitHub 应用请求的权限。

为 GitHub 配置你的应用

🌐 Configure your app for GitHub

将你的 GitHub 存储库链接到你的 Expo 项目

🌐 Link your GitHub repository to your Expo project

访问你项目的GitHub 设置。

🌐 Visit your project's GitHub settings.

在你的 GitHub 账户上安装 Expo GitHub 应用。

🌐 Install the Expo GitHub App on your GitHub account.

注意: 你必须拥有 Expo 账户的所有者或管理员权限才能安装该应用。

然后，将 GitHub 存储库链接到你的 Expo 项目。

🌐 Then, link the GitHub repository to your Expo project.

注意：你只能将 GitHub 组织仓库链接到 Expo 组织。

The repository selector on the Expo project GitHub settings page

要从不同的 GitHub 账户添加仓库，请在账户选择下拉菜单中点击添加新账户选项。

🌐 To add a repository from a different GitHub account, click the Add new account option in the account selector dropdown.

The account selector on the Expo project GitHub settings page

配置你的存储库设置

🌐 Configure your repository settings

在运行构建之前，Expo GitHub 应用需要知道从哪里获取你项目的源代码。如果你的 Expo 项目源代码位于仓库的根目录下，则无需进行任何操作。如果你的 Expo 项目源代码位于子目录中，则需要在项目的 GitHub 设置页面上配置仓库的“基础目录”设置。

🌐 Before you run a build, the Expo GitHub App needs to know where to find the source code for your project. If your Expo project source code is in the root of your repository, then you don't need to do anything. If your Expo project source code is in a subdirectory, then you'll need to configure "Base directory" settings for your repository on your project's GitHub settings page.

The base directory input on the Expo project GitHub settings page

从 GitHub 触发构建

🌐 Trigger a build from GitHub

为 GitHub 配置应用后，你可以使用项目构建列表页面上的 UI 或 GitHub PR 上的标签从 GitHub 触发构建。

🌐 Once you have configured your app for GitHub, you can trigger a build from GitHub by using the UI on your project's build list page or by labels on your GitHub PRs.

使用 Expo 网站进行构建

🌐 Build using the Expo website

访问你项目的构建列表页面，然后点击“从 GitHub 构建”按钮。系统会提示你选择一个 Git 引用（分支/提交/标签）、要构建的平台，以及要应用的构建配置文件。

🌐 Visit your project's build list page and click the "Build from GitHub" button. You'll be prompted to select a Git ref (branch/commit/tag), a platform to build for, and the build profile to apply to it.

你也可以为此特定构建指定一个基本目录。这不会更改该项目的全局设置。

🌐 You can also specify a base directory for this specific build. That will not change the global settings for this project.

The build from GitHub UI on the Expo project builds list page

使用 GitHub PR 标签进行构建

🌐 Build using GitHub PR labels

你可以通过向 GitHub PR 添加标签来触发构建。标签必须采用 eas-build-[platform]:[profile] 的形式，其中 [platform] 可以是 android、ios 或 all，[profile] 是在你的 eas.json 文件中指定的构建配置名称。如果你没有指定构建平台，它将默认为 all。如果你没有指定构建配置，它将默认为 production。

🌐 You can trigger a build from a GitHub PR by adding a label to the PR. The label must be in the form of eas-build-[platform]:[profile] where [platform] is either android, ios, or all and [profile] is the name of a build profile specified in your eas.json file. If you don't specify a build platform, it will default to all. If you don't specify a build profile, it will default to production.

例如，如果你想触发 Android 的生产构建，请在拉取请求中添加标签 eas-build-android。

🌐 For example, if you want to trigger a production build for Android, add the label eas-build-android to the PR.

A PR with the eas-build label and live status checks

构建将针对 PR 基分支上的最新提交触发。你可以在 PR 的检查中查看构建状态。构建的链接将显示在检查的详细信息中。

🌐 The build will be triggered for the latest commit on the PR's base branch. You can view the status of the build in the PR's checks. A link to the build will be available in the check's details.

当代码推送到你的 GitHub 仓库时自动构建

🌐 Build automatically when code is pushed to your GitHub repository

当你将代码推送到 GitHub 时，你可以通过自动构建 Expo 项目来进一步实现构建自动化。

🌐 You can take your build automation further by automatically building your Expo project when you push code to GitHub.

使用 EAS 工作流

🌐 Using EAS Workflows

EAS Workflows 是 Expo 提供的一项服务，允许你在 EAS 上运行构建以及许多其他类型的任务。你可以使用 EAS Workflows 来自动化你的开发和发布流程，例如创建开发构建或自动构建并提交到应用商店。

🌐 EAS Workflows is a service from Expo that allows you to run builds, and many other types of jobs, on EAS. You can use EAS Workflows to automate your development and release processes, like creating development builds or automatically building and submitting to the app stores.

要使用 EAS 工作流创建构建，请首先在 .eas/workflows/build.yml 中添加以下代码：

🌐 To create a build with EAS Workflows, start by adding the following code in .eas/workflows/build.yml:

.eas/workflows/build.yml

name: Build

on:
  push:
    branches:
      - main

jobs:
  build_android:
    name: Build Android App
    type: build
    params:
      platform: android
  build_ios:
    name: Build iOS App
    type: build
    params:
      platform: ios

当提交推送到主分支时，此工作流将创建 Android 和 iOS 构建。你可以在 EAS 工作流文档中了解如何修改此工作流并安排其他类型的任务。

🌐 When a commit is pushed to the main branch, this workflow will create Android and iOS builds. You can learn how to modify this workflow and sequence other types of jobs in the EAS Workflows documentation.

设置构建触发器

🌐 Set up build triggers

警告已弃用：此功能已弃用，并且对新项目已禁用。我们建议改用 EAS 工作流程。

了解如何设置构建触发器

你可以设置构建触发器来配置 EAS 从 GitHub 构建你的应用的时间。我们允许你在推送到分支、拉取请求和 Git 标签时进行构建。

🌐 You can set up build triggers to configure when EAS builds your app from GitHub. We allow you to build when pushing to a branch, pull request, and Git tag.

在仪表板中打开你的 Expo 项目。要创建构建触发器，向下滚动到项目 GitHub 设置页面的 Build triggers（构建触发器）部分，然后点击 New Build Trigger（新建构建触发器）。

🌐 Open your Expo project in the dashboard. To create a build trigger, scroll down to the Build triggers section of the project GitHub settings page and click New Build Trigger.

The build triggers section on the Expo project GitHub settings page

当你点击新建构建触发器时，将显示一个表单，用于配置此构建的运行方式。

🌐 When you click New Build Trigger, you will be presented with a form to configure how this build should run.

这些模式可以包含由星号表示的通配符（*），它可以匹配模式中的任意字符和字符数量。例如，releases/* 可以匹配 releases/、release/1234、release/genesis 等。如果你将模式指定为单个星号（*），则会匹配所有分支/标签。

🌐 These patterns can include wildcards represented by asterisks (*), which can match any character and number of characters inside the pattern. For example, releases/* can match releases/, release/1234, release/genesis, and so on. If you specify the pattern as a sole asterisk (*), all branches/tags will be matched.

The default state of the new build trigger form

你还可以为特定平台和构建配置设置触发器。如果选择多个平台，将为每个平台创建一个单独的触发器。

🌐 You can also configure triggers for specific platforms and build profiles. If you select multiple platforms, a separate trigger will be made for each.

A filled-out version of the new build trigger form

The build triggers section on the Expo project GitHub settings page filled with build triggers

当你推送到分支或标签时，你可以在提交的检查部分找到构建。

🌐 When you push to a branch or tag, you can find the builds by looking at a commit's Checks section.

The GitHub checks section on a branch commit

The GitHub checks section on a tag commit

对于拉取请求，你可以配置一个目标分支模式。这是你希望构建的拉取请求的目标分支。通配符的相同规则在这里也适用。

🌐 For pull requests, you can configure a target branch pattern. This is the destination branch of the pull request you want to build. The same rules apply for wildcards here as well.

当你向与此触发器匹配的源分支和目标分支的拉取请求提交时，你会在拉取请求的检查部分找到这些构建：

🌐 When you push to a pull request with a source and target branch matching this trigger, you'll find these builds in the checks section of the pull request:

The GitHub checks section on a pull request

**注意：**要从拉取请求触发构建，拉取请求的作者必须是该 GitHub 仓库的协作者。如果你想构建来自外部贡献者的拉取请求，应用 PR 标签。

管理构建触发器

🌐 Manage build triggers

在 EAS 仪表板的项目 GitHub 设置页面中，你可以点击构建触发器行右侧的选项按钮来禁用、编辑或删除该触发器。

🌐 On your project's GitHub settings page in the EAS dashboard, you can click the options button to the right of a build trigger row to disable, edit, or delete the trigger.

The options button on the build trigger row

你也可以手动使用触发器的参数运行 GitHub 构建。这不会计入你的自动构建触发记录。

🌐 You can also run a GitHub build with the parameters from the trigger manually. This will not count toward your automatic build trigger record.

使用 EAS Submit 自动提交应用商店

🌐 Automatic app stores submission with EAS Submit

一旦构建完成，你可以使用 EAS Submit 自动将应用提交到应用商店。此功能简化了流程，减少了发布应用所需的手动步骤。

🌐 Once your build completes, you can automatically submit your app to the app stores using EAS Submit. This feature streamlines the process, reducing the manual steps required to publish your app.

要启用自动提交，你需要配置构建触发器，使提交成为构建过程的一部分。以下是设置方法：

🌐 To enable automatic submission, you need to configure your build triggers to include submission as part of the build process. Here's how you can set it up:

在 EAS 仪表板上导航到项目的 GitHub 设置页面。
找到你要修改的构建触发器，然后单击选项按钮。
选择编辑触发器，在出现的对话框中，勾选选项构建后提交到商店。

The EAS Submit form fields on the trigger edit form

保存你的更改。

An enabled build trigger with automatic submission enabled

启用后，每次从此配置触发构建时，它都会自动提交到你在 eas.json 中 submit 字段配置的应用商店。

🌐 Once enabled, every time a build is triggered from this configuration, it will automatically be submitted to the app stores you have configured in your eas.json under the submit field.

注意：请确保你的 eas.json 已正确配置以便提交，包括指定正确的应用商店凭据和提交配置文件。更多信息，请参阅 EAS Submit。

故障排除

🌐 Troubleshooting

当出现问题时，我们将使用一些错误信息对尝试构建的提交进行评论。
在尝试构建时，仔细检查先决条件部分的所有内容是否正确。
如果你使用的是 monorepo 设置，请确认你的基本目录是准确的。
你的构建配置文件正确吗？如果在 eas.json 中找不到匹配的配置文件，构建将无法启动。