EAS 工作流程的语法

EAS Workflows 配置文件语法的参考指南。

工作流是由一个或多个作业组成的可配置自动化过程。你必须创建一个 YAML 文件来定义你的工作流配置。

¥A workflow is a configurable automated process made up of one or more jobs. You must create a YAML file to define your workflow configuration.

要开始使用工作流，请参阅 开始使用 EAS 工作流 或参阅 示例 了解完整的工作流配置。

¥To get started with workflows, see Get Started with EAS Workflows or see Examples for complete workflow configurations.

工作流文件

¥Workflow files

工作流文件使用 YAML 语法，必须具有 .yml 或 .yaml 文件扩展名。如果你是 YAML 新手并想了解更多信息，请参阅 在 Y 分钟内学习 YAML。

¥Workflow files use YAML syntax and must have either a .yml or .yaml file extension. If you're new to YAML and want to learn more, see Learn YAML in Y minutes.

工作流文件位于项目中的 .eas/workflows 目录中。.eas 目录应与你的 eas.json 文件处于同一级别。

¥Workflow files are located in the .eas/workflows directory in your project. The .eas directory should be at the same level as your eas.json file.

例如：

¥For example:

name

工作流的名称。这显示在工作流列表页的 Expo 仪表板上，是工作流详细信息页的标题。

¥The name of the workflow. This is displayed on the Expo dashboard on the workflows list page and is the title of the workflow's detail page.

name: My workflow

on

on 键定义哪些 GitHub 事件触发工作流。任何工作流程都可以使用 eas workflow:run 命令触发，无论 on 密钥如何。

¥The on key defines which GitHub events trigger the workflow. Any workflow can be triggered with the eas workflow:run command, regardless of the on key.

on:
  # Trigger on pushes to main branch
  push:
    branches: ['main']
  # And on pull requests starting with 'version-'
  pull_request:
    branches: ['version-*']

on.push

当拉取请求带有匹配标签时运行你的工作流程。

¥Runs your workflow when you push a commit to matching branches and/or tags.

使用 branches 数组，你只能在推送到那些指定的分支时触发工作流。例如，如果你使用 branches: ['main']，则只有推送到 main 分支才会触发工作流。支持 glob。

¥With the branches array, you can trigger the workflow only when those specified branches are pushed to. For example, if you use branches: ['main'], only push to the main branch will trigger the workflow. Supports globs.

使用 tags 数组，你只能在推送那些指定的标签时触发工作流。例如，如果你使用 tags: ['v1']，则只有推送的 v1 标签才会触发工作流程。支持 glob。

¥With the tags array, you can trigger the workflow only when those specified tags are pushed. For example, if you use tags: ['v1'], only the v1 tag being pushed will trigger the workflow. Supports globs.

当未提供 branches 和 tags 时，branches 默认为 ['*']，tags 默认为 []，这意味着工作流将在推送事件到所有分支时触发，而不会在标签推送时触发。如果仅提供两个数组中的一个，则另一个默认为 []。

¥When neither branches nor tags are provided, branches defaults to ['*'] and tags defaults to [], which means the workflow will trigger on push events to all branches and will not trigger on tag pushes. If only one of the two arrays is provided the other defaults to [].

on:
  push:
    branches:
      - 'main'
      - 'feature/**'
      # other branch names and globs
    tags:
      - 'v1'
      - 'v2*'
      # other tag names and globs

on.pull_request

使用根据你的项目检测到的包管理器（bun、npm、pnpm 或 Yarn）运行 命令，并使用最适合你的构建类型和构建环境的命令。

¥Runs your workflow when a pull request event occurs on the matching branches.

使用 branches 数组，你只能在那些指定的分支是拉取请求的目标时触发工作流。例如，如果你使用 branches: ['main']，则只有对 main 分支的拉取请求才会触发工作流。支持 glob。未提供时默认为 ['*']，这意味着工作流将在所有分支的拉取请求事件上触发。

¥With the branches array, you can trigger the workflow only when those specified branches are the target of the pull request. For example, if you use branches: ['main'], only pull requests to the main branch will trigger the workflow. Supports globs. Defaults to ['*'] when not provided, which means the workflow will trigger on pull request events to all branches.

使用 types 数组，你只能在指定的拉取请求事件类型上触发工作流。例如，如果你使用 types: ['opened']，则只有 pull_request.opened 事件（首次打开拉取请求时发送）才会触发工作流。未提供时默认为 ['opened', 'reopened', 'synchronize']。支持的事件类型：

¥With the types array, you can trigger the workflow only on the specified pull request event types. For example, if you use types: ['opened'], only the pull_request.opened event (sent when a pull request is first opened) will trigger the workflow. Defaults to ['opened', 'reopened', 'synchronize'] when not provided. Supported event types:

• opened

• reopened

• synchronize

• labeled

on:
  pull_request:
    branches:
      - 'main'
      - 'feature/**'
      # other branch names and globs
    types:
      - 'opened'
      # other event types

on.pull_request_labeled

当匹配分支上发生拉取请求事件时运行你的工作流程。

¥Runs your workflow when a pull request is labeled with a matching label.

使用 labels 数组，你可以指定哪些标签在分配给拉取请求时会触发工作流。例如，如果你使用 labels: ['Test']，则只有使用 Test 标签标记拉取请求才会触发工作流。未提供时默认为 []，这意味着没有标签会触发工作流。

¥With the labels array, you can specify which labels, when assigned to your pull request, will trigger the workflow. For example, if you use labels: ['Test'], only labeling a pull request with the Test label will trigger the workflow. Defaults to [] when not provided, which means no labels will trigger the workflow.

你还可以将匹配标签的列表直接提供给 on.pull_request_labeled，以获得更简单的语法。

¥You can also provide the list of matching labels directly to on.pull_request_labeled for simpler syntax.

on:
  pull_request_labeled:
    labels:
      - 'Test'
      - 'Preview'
      # other labels

或者：

¥Alternatively:

on:
  pull_request_labeled:
    - 'Test'
    - 'Preview'
    # other labels

jobs

工作流程运行由一个或多个作业组成。

¥A workflow run is made up of one or more jobs.

jobs:
  job_1:
    # ...
  job_2:
    # ...

jobs.<job_id>

每个作业都必须有一个 ID。ID 在工作流中应该是唯一的，并且可以包含字母数字字符和下划线。例如，以下 YAML 中的 my_job：

¥Each job must have an ID. The ID should be unique within the workflow and can contain alphanumeric characters and underscores. For example, my_job in the following YAML:

jobs:
  my_job:
    # ...

jobs.<job_id>.name

工作流详细信息页面上显示的作业名称。

¥The name of the job displayed on the workflow's detail page.

jobs:
  my_job:
    name: Build app

jobs.<job_id>.environment

要为作业设置的 EAS 环境变量 环境。有三个可能的值：

¥The EAS environment variable environment to set for the job. There are three possible values:

• production（默认）

  ¥production (default)

• preview

• development

environment 键可用于除预打包的 build、submit 和 get-build 作业之外的所有作业。

¥The environment key is available on all jobs except for the pre-packaged build, submit, and get-build jobs.

jobs:
  my_job:
    environment: production | preview | development

jobs.<job_id>.defaults.run.working_directory

为作业中的所有步骤设置运行命令的目录。

¥Sets the directory to run commands in for all steps in the job.

jobs:
  my_job:
    defaults:
      run:
        working_directory: ./my-app
    steps:
      - name: My first step
        run: pwd # prints: /home/expo/workingdir/build/my-app

控制流

¥Control flow

你可以使用 needs 和 after 关键字控制作业的运行时间以及在作业运行之前必须成功完成的作业。此外，你可以使用 if 关键字来控制是否应根据条件运行作业。

¥You can control when jobs run and what jobs must complete successfully before a job runs using the needs and after keywords. In addition, you can use the if keyword to control whether a job should run based on a condition.

jobs.<job_id>.needs

在运行此作业之前必须成功完成的作业 ID 列表。

¥A list of job IDs that must complete successfully before this job will run.

jobs:
  test:
    steps:
      - uses: eas/checkout
      - uses: eas/use_npm_token
      - uses: eas/install_node_modules
      - name: tsc
        run: yarn tsc
  build:
    needs: [test] # This job will only run if the 'test' job succeeds
    type: build
    params:
      platform: ios

jobs.<job_id>.after

在运行此作业之前必须完成（成功或失败）的作业 ID 列表。

¥A list of job IDs that must complete (successfully or not) before this job will run.

jobs:
  build:
    type: build
    params:
      platform: ios
  notify:
    after: [build] # This job will run after build completes (whether build succeeds or fails)

jobs.<job_id>.if

if 条件确定是否应运行作业。

¥The if conditional determines if a job should run.

jobs:
  my_job:
    if: ${{ github.ref_name == 'main' }}

预打包作业

¥Pre-packaged jobs

jobs.<job_id>.type

指定要运行的预打包作业的​​类型。预打包的作业根据工作流详细信息页面上的作业类型生成专门的 UI。

¥Specifies the type of pre-packaged job to run. Pre-packaged jobs produce specialized UI according to the type of job on the workflow's detail page.

jobs:
  my_job:
    type: build

了解以下不同的预打包作业。

¥Learn about the different pre-packaged jobs below.

build

使用 EAS 构建 创建项目的 Android 或 iOS 版本。

¥Creates an Android or iOS build of your project using EAS Build.

jobs:
  my_job:
    type: build
    params:
      platform: ios | android # required
      profile: string # optional, default: production

此作业输出以下属性：

¥This job outputs the following properties:

{
  "build_id": string,
  "app_build_version": string | null,
  "app_identifier": string | null,
  "app_version": string | null,
  "channel": string | null,
  "distribution": "internal" | "store" | null,
  "fingerprint_hash": string | null,
  "git_commit_hash": string | null,
  "platform": "ios" | "android" | null,
  "profile": string | null,
  "runtime_version": string | null,
  "sdk_version": string | null,
  "simulator": "true" | "false" | null
}

可以自定义构建作业，以便你可以在构建过程中执行自定义命令。请参阅 定制构建 了解更多信息。

¥Build jobs can be customized so that you can execute custom commands during the build process. See Custom builds for more information.

deploy

使用 EAS 托管 部署你的应用。

¥Deploys your application using EAS Hosting.

jobs:
  my_job:
    type: deploy
    params:
      alias: string # optional
      prod: boolean # optional

get-build

从 EAS 中检索与提供的参数匹配的现有构建。

¥Retrieves an existing build from EAS that matches the provided parameters.

jobs:
  my_job:
    type: get-build
    params:
      platform: ios | android # optional
      profile: string # optional
      distribution: store | internal | simulator # optional
      channel: string # optional
      app_identifier: string # optional
      app_build_version: string # optional
      app_version: string # optional
      git_commit_hash: string # optional
      fingerprint_hash: string # optional
      sdk_version: string # optional
      runtime_version: string # optional
      simulator: boolean # optional

此作业输出以下属性：

¥This job outputs the following properties:

{
  "build_id": string,
  "app_build_version": string | null,
  "app_identifier": string | null,
  "app_version": string | null,
  "channel": string | null,
  "distribution": "internal" | "store" | null,
  "fingerprint_hash": string | null,
  "git_commit_hash": string | null,
  "platform": "ios" | "android" | null,
  "profile": string | null,
  "runtime_version": string | null,
  "sdk_version": string | null,
  "simulator": "true" | "false" | null
}

submit

使用 EAS 提交 向应用商店提交 Android 或 iOS 版本。对于 environment，它使用 build_id 中引用的用于创建构建的环境。

¥Submits an Android or iOS build to the app store using EAS Submit. For environment it uses the environment used to create build referenced in build_id.

jobs:
  my_job:
    type: submit
    params:
      build_id: string # required
      profile: string # optional, default: production

update

使用 EAS 更新 发布更新。

¥Publishes an update using EAS Update.

jobs:
  my_job:
    type: update
    params:
      message: string # optional
      platform: string # optional - android, ios, or all
      branch: string # optional
      channel: string # optional - cannot be used with branch

maestro

运行 大师 并在编译之前删除生成的原生目录。

¥Runs Maestro tests on a build.

maestro:
  type: maestro
  environment: production | preview | development # optional, defaults to preview
  image: string # optional, defaults to 'default'. See https://expo.nodejs.cn/build-reference/infrastructure/ for a list of available images.
  params:
    build_id: string # required
    flow_path: string | string[] # required

自定义作业

¥Custom jobs

在构建上运行 测试。不需要 type 字段。

¥Runs custom code and can use built-in EAS functions. Does not require a type field.

jobs:
  my_job:
    steps:
      # ...

jobs.<job_id>.runs_on

指定将执行作业的工作线程。仅适用于自定义作业。

¥Specifies the worker that will execute the job. Available only on custom jobs.

jobs:
  my_job:
    runs_on: linux-medium | linux-large | linux-medium-nested-virtualization | linux-large-nested-virtualization | macos-medium | macos-large

注意：对于 iOS 构建和 iOS 模拟器作业，你必须使用 macos-* 工作者。对于 Android 模拟器作业，你必须使用 linux-*-nested-virtualization 工作器。

¥Note: For iOS builds and iOS Simulator jobs, you must use a macos-* worker. For Android Emulator jobs, you must use a linux-*-nested-virtualization worker.

jobs.<job_id>.outputs

作业的输出列表。作业输出可用于所有依赖于此作业的下游作业。使用 set-output 函数设置步骤中的输出。

¥A list of outputs for the job. Job outputs are available to all downstream jobs that depend on this job. Set outputs in a step using the set-output function.

在下面的例子中，set-output 函数在 job_1 的 step_1 步骤中将 test 输​​出设置为 hello world。稍后在 job_2 中，使用 needs.job_1.outputs.output_1 在 step_2 中访问它。

¥In the example below, the set-output function sets the test output to hello world in job_1's step_1 step. Later in job_2, it's accessed in step_2 using needs.job_1.outputs.output_1.

jobs:
  job_1:
    outputs:
      output_1: ${{ steps.step_1.outputs.test }}
    steps:
      - id: step_1
        run: set-output test "hello world"
  job_2:
    needs: [job_1]
    steps:
      - id: step_2
        run: echo ${{ needs.job_1.outputs.output_1 }}

jobs.<job_id>.steps

作业包含名为 steps 的一系列任务。步骤可以运行命令。

¥A job contains a sequence of tasks called steps. Steps can run commands.

jobs:
  my_job:
    steps:
      - name: My first step
        run: echo "Hello World"

jobs.<job_id>.steps.<step>.id

id 属性用于引用作业中的步骤。用于在下游作业中使用步骤的输出。

¥The id property is used to reference the step in the job. Useful for using the step's output in a downstream job.

jobs:
  my_job:
    outputs:
      test: ${{ steps.step_1.outputs.test }} # References the output from step_1
    steps:
      - id: step_1
        run: set-output test "hello world"

jobs.<job_id>.steps.<step>.name

步骤的名称，显示在作业的日志中。

¥The name of the step, which is displayed in the job's logs.

jobs:
  my_job:
    steps:
      - name: My first step
        run: echo "Hello World"

jobs.<job_id>.steps.<step>.run

在步骤中运行的命令。

¥The command to run in the step.

jobs:
  my_job:
    steps:
      - run: echo "Hello World"

jobs.<job_id>.steps.<step>.working_directory

运行命令的目录。在步骤级别定义时，如果作业上也定义了 jobs.<job_id>.defaults.run.working_directory 设置，它将覆盖该设置。

¥The directory to run the command in. When defined at the step level, it overrides the jobs.<job_id>.defaults.run.working_directory setting on the job if it is also defined.

jobs:
  my_job:
    steps:
      - uses: eas/checkout
      - run: pwd # prints: /home/expo/workingdir/build/my-app
        working_directory: ./my-app

jobs.<job_id>.steps.<step>.uses

EAS 提供了一组内置可重用函数，你可以在工作流步骤中使用它们。uses 关键字用于指定要使用的函数。所有内置函数都以 eas/ 前缀开头。

¥EAS provides a set of built-in reusable functions that you can use in workflow steps. The uses keyword is used to specify the function to use. All built-in functions start with the eas/ prefix.

jobs:
  my_job:
    steps:
      - uses: eas/checkout
      - uses: eas/install_node_modules
      - uses: eas/prebuild
      - name: List files
        run: ls -la

以下是你可以在工作流步骤中使用的内置函数列表。

¥Below is a list of built-in functions you can use in your workflow steps.

eas/checkout

签出你的项目源文件。

¥Checks out your project source files.

jobs:
  my_job:
    steps:
      - uses: eas/checkout

eas/install_node_modules

使用根据你的项目检测到的包管理器 (bun、npm、pnpm 或 Yarn) 安装节点模块。与 monorepos 一起使用。

¥Installs node modules using the package manager (bun, npm, pnpm, or Yarn) detected based on your project. Works with monorepos.

jobs:
  my_job:
    steps:
      - uses: eas/checkout
      - uses: eas/install_node_modules

eas/prebuild

运行 iOS 作业，包括模拟器。

¥Runs the expo prebuild command using the package manager (bun, npm, pnpm, or Yarn) detected based on your project with the command best suited for your build type and build environment.

jobs:
  my_job:
    steps:
      - uses: eas/checkout
      - uses: eas/install_node_modules
      - uses: eas/prebuild

jobs:
  my_job:
    steps:
      - uses: eas/checkout
      - uses: eas/install_node_modules
      - uses: eas/resolve_apple_team_id_from_credentials
        id: resolve_apple_team_id_from_credentials
      - uses: eas/prebuild
        with:
          clean: false
          apple_team_id: ${{ steps.resolve_apple_team_id_from_credentials.outputs.apple_team_id }}

eas/send_slack_message

将指定的消息发送到配置的 Slack Webhook URL，然后将其发布到相关的 Slack 通道中。消息可以指定为纯文本或 Slack 块套件 消息。对于这两种情况，你都可以在消息中引用构建作业属性和 使用其他步骤输出 以进行动态评估。例如，'Build URL: ${{ eas.job.expoBuildUrl }}'、Build finished with status: ${{ steps.run_fastlane.status_text }}、Build failed with error: ${{ steps.run_gradle.error_text }}。必须指定 "message" 或 "payload"，但不能同时指定两者。

¥Sends a specified message to a configured Slack webhook URL, which then posts it in the related Slack channel. The message can be specified as plaintext or as a Slack Block Kit message. With both cases, you can reference build job properties and use other steps outputs in the message for dynamic evaluation. For example, 'Build URL: ${{ eas.job.expoBuildUrl }}', Build finished with status: ${{ steps.run_fastlane.status_text }}, Build failed with error: ${{ steps.run_gradle.error_text }}. Either "message" or "payload" has to be specified, but not both.

jobs:
  my_job:
    steps:
      - uses: eas/send_slack_message
        with:
          message: 'This is a message to plain input URL'
          slack_hook_url: 'https://hooks.slack.com/services/[rest_of_hook_url]'

eas/use_npm_token

配置节点包管理器（bun、npm、pnpm 或 Yarn）以用于发布到 npm 或私有注册表的私有包。

¥Configures node package managers (bun, npm, pnpm, or Yarn) for use with private packages, published either to npm or a private registry.

在项目的密钥中设置 NPM_TOKEN，此函数将通过使用令牌创建 .npmrc 来配置构建环境。

¥Set NPM_TOKEN in your project's secrets, and this function will configure the build environment by creating .npmrc with the token.

jobs:
  my_job:
    name: Install private npm modules
    steps:
      - uses: eas/checkout
      - uses: eas/use_npm_token
      - name: Install dependencies
        run: npm install # <---- Can now install private packages