本文档的内容是由机器翻译的。请通过反馈微件提交您的反馈。
 

矩阵构建

最后修改日期： 2025年 3月 21日

Matrix Build 构建功能 允许您通过迭代指定的参数值来定义一组构建，并为每种组合生成一个构建。

例如，给定一个使用以下参数配置的矩阵构建：

Browser: Chrome, Safari, Firefox
env.ShouldFail: true, false
Java: 11, 17, 21

当矩阵构建被触发时，它会针对 浏览器、 env.ShouldFail 和 Java 的每种指定值组合运行构建，并在矩阵构建的 概述 选项卡中生成以下构建摘要：

矩阵构建的汇总表格

配置矩阵构建

配置矩阵参数

矩阵构建 对话框使您能够定义矩阵构建的参数，其中每个参数定义由参数名称和相关值列表组成。

例如，假设您想要使用以下矩阵参数配置矩阵构建：

Browser: Chrome, Firefox
Java: jdk-17, jdk-21

在用户界面中配置 Matrix Build

  1. 从 添加构建功能 对话框中，选择 矩阵构建。

  2. 如下配置第一个参数：

    1. 输入参数名称： 浏览器

      tip

      参数名称可以是新参数、现有参数，或预定义的矩阵参数（请参见 预定义矩阵参数）。

    2. 输入关联的参数值： Chrome、 Firefox

      tip

      参数值以此格式指定， [可选显示标签=>]值。

      在 价值 由单行文字构成，并且（可选）一些 配置构建参数。 如果指定，矩阵构建概述中将显示 可选显示标签 ，而不是原始参数值。

      note

      如果您需要添加超过两个参数值，请点击 添加另一个值。

  3. 要配置第二个参数，点击 添加参数。

    • 输入参数名称： Java

    • 输入带有标签的参数值： JDK 17 => jdk-17 和 JDK 21=>jdk-21

    tip

    如果您需要删除一个参数，请点击参数名称旁边的垃圾桶图标。

  4. 点击 Save 来确认设置并启用矩阵构建功能。

预定义矩阵参数

TeamCity 提供了预定义的矩阵参数，以覆盖一些常见的矩阵构建用例：

形参

描述

arch

使您能够在不同的芯片组架构下运行构建。

将一个等同于代理需求的约束应用于： equals("teamcity.agent.jvm.os.arch", "%arch%")。

env.JAVA_HOME

允许您使用不同的 JDK 版本运行构建。

您从下拉列表中选择的每个值（例如， %env.JDK_11_0% ）都会应用一个约束，仅在定义了引用变量（env.JDK_11_0 ）的代理上运行构建。

tip

您在下拉列表中看到的值列表是从您所有代理的环境中收集的。

os

使您能够在不同的操作系统下运行构建。

将一个等同于代理需求的约束应用于： 包含("teamcity.agent.jvm.os.name", "%os%")。

Kotlin DSL 示例

在 Kotlin DSL 中配置预定义参数的示例：

object Build : BuildType({

    features {
        matrix {
           param("arch", listOf(
              value("x86"),
              value("ARM"),
              value("AMD64")
           ))
        }
    }
})

配置 Agent 要求

您可以在 代理需求 中引用矩阵参数，以确保 TeamCity 为每个值选择正确的构建代理。

例如，当针对不同的浏览器类型设置自动化 UI 测试时，您可能会定义以下 浏览器 矩阵参数：

Browser: Firefox, Chrome, Edge

鉴于代理使用环境变量来指定浏览器版本：

env.Chrome=119.0.6045.123
env.Firefox=119.0.1

您可以定义以下代理需求，根据相应环境变量的存在来选择适合的代理：

  • 参数名称： env.%Browser%

  • 条件： exists

在配置中使用矩阵参数

在许多不同的上下文中，引用矩阵参数可能非常有用。 下面是几个示例：

  • 您可以使用 条件构建步骤 ，使得某个特定构建步骤的执行依赖于矩阵参数的值。

    tip

    例如，如果您的矩阵构建中有一个部署步骤需要被精准地执行一次，您可以定义一个条件构建步骤来仅对矩阵参数值的一种组合执行部署步骤。

  • 为了引用构建所需的资源。 例如，如果 Java 矩阵参数可能有 java-17 或 java-21 的值，您可能会直接在为构建定义的 JDK 路径中引用它：

    /usr/lib/jvm/%\Java%-openjdk-amd64

  • 如果您有一个构建步骤用于为特定的 Java 版本构建 Dockerfile，您可以在生成的镜像文件名中引用 Java 矩阵参数，并将 镜像名称：标签 字段设置为 myapp:%Java%。

  • 对于更复杂的场景，您可以定义一个构建步骤，运行脚本以依照矩阵参数的不同值执行不同的任务。

发布制品

当您运行矩阵构建时，所有生成的构建中的工件都会被聚合到父构建中的同一位置。 这可能会导致工件文件被覆盖。

为避免覆盖 artifact 文件，最好使用由 matrix 参数值组合定义的目录名称来排序生成的 artifacts，例如：

%\Browser%-%\Java%

您可以然后定义如下的构件路径：

ch-simple/simple/target/*.jar => %\Browser%-%\Java%

生成的构建中的工件随后会被写入到不同的目录中：

Chrome-JDK_17/
Chrome-JDK_21/
Firefox-JDK_17/
Firefox-JDK_21/

运行 Matrix 构建

您可以像运行任何常规构建一样运行矩阵构建：通过单击 运行 ，通过配置构建触发器，或通过调用 REST API。

当矩阵构建开始时，TeamCity按照以下步骤运行构建：

  1. 矩阵构建首次运行时，会为矩阵参数值的每个组合生成新的虚拟构建配置。 矩阵构建实际上像这些生成的快照依赖项的父配置一样有效

    note

    生成的每一个构建配置都具有与父配置相同的构建步骤。 在父配置中对构建步骤进行的任何后续更改都将自动传播到生成的构建配置中。

  2. TeamCity 运行生成的构建。 每个构建都会单独添加到构建队列中，并且需要遵守关于构建优先级和代理选择的常规规则。

    note

    通常，生成的构建可以在多个代理上并行运行。 如果您在 自定义构建选项 中选择了特定的代理，那么，生成的构建将会在指定的代理上逐一运行。

  3. 一旦第一个生成的构建开始运行，TeamCity 就会启动父级构建（实际上，是一种依赖于生成构建的 composite build ），该构建将汇总所有生成的构建的结果。

  4. 矩阵构建完成后，您可以在矩阵构建的 概述 选项卡中查看摘要表。

如果您只需要构建矩阵的一部分，运行自定义构建是一种方便的方式（您也可以为专用 UI 运行单个组合的请求 TW-84312 投票）。 切换到 参数 选项卡的 运行自定义构建 对话框，并指定所需的参数值（使用逗号作为分隔符）。 您在此对话框中未覆盖的参数将会在 Matrix Builds 功能中指定的所有值之间循环。

运行矩阵的一部分

特别是，在矩阵构建上配置 构建触发器 时，您可以在触发器配置对话框的 构建自定义 选项卡中配置以自定义触发构建所使用的矩阵参数值。

note

在 构建自定义 选项卡中设置矩阵参数时，您必须以逗号分隔的列表形式输入参数值。 例如，要遍历两个浏览器值，您可以将参数名称设置为 浏览器 ，参数值设置为 Chrome，Firefox。

查看矩阵构建

您可以在两个不同的层次上查看矩阵构建：

  • 父构建 — 配置和组织生成的构建

    • 定义矩阵参数配置

    • 定义所有构建通用的配置设置

    • 负责触发构建

    • 提供构建的表格摘要

    • 不包含来自各个构建的详细结果

  • 生成的构建 — 代表单一参数值组合的构建

    • 继承自父构建的只读配置设置

    • 具有与父构建相同的构建步骤

    • 为特定构建提供详细结果

当您在矩阵中深入到特定的构建时，您会看到类似于典型构建页面的内容，其中包含了关于构建的完整信息。 然而，构建配置是 只读的，因为构建是从父级构建继承其配置设置的，尤其是，您不能直接运行此构建配置。

warning

如果项目启用了 版本控制设置 ，那么生成的构建配置不会提交到 VCS 仓库。

构建链中的矩阵构建

矩阵构建可以使用 快照依赖项或 工件依赖项链接在一起，就像常规构建一样。

如果一个常规构建依赖于矩阵构建，那么依赖关系将链接到矩阵的父构建。 生成的构建是只读的，所以您不能直接将依赖项链接到它们。 尽管如此，通过确保构件按照各自构建的参数组合进行排序，仍然可以使用生成的构建中的构件。

在本节中，我们关注的场景是 MatrixBuild1 -> RegularBuild2 ，在该场景中，矩阵构建和普通构建之间定义了工件依赖。 在这种情况下，您需要谨慎处理由生成的构建生成的工件。

构建链示例

请考虑一个普通的（非矩阵）构建链，它有两个阶段：

  • Build1 配置了 Maven 构建运行程序，用于生成 Java 包。 构建配置的常规设置部分中的 构建工件路径 字段被配置为将生成的包捕获为一个工件：

    ch-simple/simple/target/*.jar => packages

  • Build2 配置了对 Build1 的 工件依赖 ，并具有以下 构件规则 设置：

    packages => dependencies

为了扩展到多种浏览器和 Java 版本的测试，Build1 需要重构为矩阵构建，覆盖以下浏览器和 Java 版本组合：

Browser: Chrome, Firefox
Java: JDK_17, JDK_21

在对 Build1 进行矩阵参数配置后，您还需更新 artifact 设置：

  • 在 Build1 中，修改构建配置的常规设置部分中的 构建工件路径 字段，以按参数组合对聚合工件进行排序：

    ch-simple/simple/target/*.jar => packages/%\Browser%-%\Java%

已知限制

  • 反向依赖性参数， reverse.dep.* ，在矩阵构建中无法正确工作。 相关的 YouTrack 工单： TW-84730。

  • 当矩阵构建配置为对前一构建的快照依赖时，前一构建的测试结果会在矩阵构建中报告，这是一种意外的行为。 相关的 YouTrack 工单： TW-75412。

  • 当一个矩阵构建被配置为对前面构建的快照依赖时，报告的矩阵构建时间会增加，因为它包括了链中所有前面构建的持续时间。 这可能需要您修改超时设置。 相关的 YouTrack 工单： TW-76020。

  • 运行自定义构建 对话框不允许您为新值分配标签。

  • 如果在功能设置中指定的值有标签，并且其原始值包含逗号，您在自定义构建中无法仅通过标签引用它；必须同时输入标签和原始值部分。