TeamCity On-Premises 2026.2 Help

在链中传递数据

构建链的成员可以交换两种数据：

  • 文件 — 通过 工件依赖项。 上游构建发布文件；下游构建在开始前下载这些文件。

  • 值 — 通过 输出参数。 在一个对象中设置的名称-值对会由链中更下游的另一个对象读取。

这两种机制都沿链的方向流动：数据从上游移动到下游，而不会反向移动。

工件依赖项

工件依赖项会在另一个构建中复用某个构建的输出（工件）。 配置后，TeamCity 会在下游构建开始前将所需文件下载到代理。

工件可以取自：

  • 同一链中上游对象的构建。

  • 不属于该链的配置的构建。

  • 同一配置的先前构建。

配置工件依赖项

对于构建配置，请在配置设置的 依赖 页面上添加工件依赖项。

添加构件依赖

该对话框包含以下密钥设置：

工件依赖项对话框
依赖于

要使用其工件的配置。

获取工件

要从源配置的哪个构建中获取工件：

  • 最新成功构建/最新的已固定构建/最新完成构建 — 最近匹配的构建。

  • 从同一链构建 — 同一链中的构建。 请将此项与快照依赖项一起使用。 如果源在链外，构建将失败。

  • 来自相同链或最新完成的构建 — 与上面相同，但当源不在链中时，会回退到最新完成的构建。

  • 使用指定的构建编号进行构建/具有指定标签的最新完成构建 — 由编号或标记标识的特定构建。

工件规则

要下载哪些文件以及将它们放置在何处。 请参阅下面的 工件规则。

在下载工件之前清理目标路径

下载前删除目标目录的内容，应用于所有包含规则。

在流水线中，工件依赖项在 YAML 中配置。 这涉及两个独立的流水线，每个流水线都有自己的配置文件。

首先， 上游 流水线中的作业通过 files-publication 块发布文件：

# Upstream pipeline jobs: Build: steps: - type: gradle tasks: clean build files-publication: - path: ./build/libs/todo.jar share-with-jobs: true publish-artifact: true

然后， 下游 流水线中的作业通过 download-artifacts 块导入它，并引用在其 dependencies 中声明的上游流水线：

# Downstream pipeline jobs: Docker: steps: - type: script script-content: docker build -t myapp:%build.number% . download-artifacts: - UpstreamPipeline_ID: # same ID as in the 'dependencies' block from: dependency artifact-rules: todo.jar=>./build/libs clean-destination: true dependencies: - UpstreamPipeline_ID: reuse: none

工件规则

工件规则指定要下载哪些工件以及将它们存储在何处。 每条规则单独占一行，并使用以下语法：

[+:|-:|?:]SourcePath[!ArchivePath][=>DestinationPath]
前缀

  • +: — 包含（默认； mylib.dll 和 +:mylib.dll 相同）。

  • -: — 从下载中排除文件或模式。

  • ?: — 可选包含。 如果文件缺失，构建将继续并显示警告，而不是失败。

源路径

相对于源构建的工件目录的路径。 接受文件、目录或 类似 Ant 的通配符。 从第一个通配符开始保留源目录结构。

归档路径

从下载的归档文件中提取文件（zip、 7z、 jar、 tar、 tar.gz 等）。 例如， release.zip!*.dll 会从归档根目录中提取 .dll 文件。

目标路径

代理上的目标目录，相对于构建检出目录。 如果省略，工件将转到检出根目录。 对 -: 规则忽略。

示例：

# Download a directory tree into lib/ (a/b/c/file.txt → lib/c/file.txt) a/b/**=>lib # Download all text files, preserving structure **/*.txt=>lib # Extract all DLLs from matching archives release-*.zip!*.dll=>dlls # Download everything except one file **/*.txt=>texts -:bad/exclude.txt # Optional file — build continues even if it is missing ?:output.txt

?: 前缀在 部分链中特别有用：如果通常提供文件的上游构建被跳过，可选规则可防止下游构建失败。

参数

链成员通过 构建参数交换值。 本节是快速概述 — 如需完整语法、示例和边缘情况，请参阅 在构建链中使用参数。

通过在上游对象中将值声明为 输出参数 ，可沿链向下共享该值。 输入参数对其所有者保持私有；输出参数对下游对象可见。

读取上游值

下游对象通过 dep.<upstream-ID>.<param-name> 读取上游输出参数。

读取另一个作业的值

在单个流水线中，作业通过 job.<job-ID>.<param-name> 读取前一个作业的参数。

重写上游值

下游对象通过 override.dep.<upstream-ID>.<param-name> 写回上游输入参数。 这是数据逆链方向流动的唯一情况，并且会在上游构建开始前解析。

输出参数设计为由 其他对象读取，而不是由声明它们的对象读取。 如果配置或流水线引用自己的输出参数，该引用不会解析：TeamCity 会将未解析的 %...% 视为 隐式代理要求 ，并且构建会因 "no compatible agents" 错误而无法启动。 下面的代码段演示了这一点。

parameters: PipelineInputParam: foo output-parameters: PipelineOutputParam: bar jobs: Job1: name: Job 1 steps: - type: script script-content: |- # Prints 'foo' echo "Input param: %PipelineInputParam%" # Unresolved reference: no compatible agents echo "Output param: %PipelineOutputParam%"

对于构建配置，等效声明使用 形参 和 outputParams 块。 请参阅 在构建链中使用参数 ，了解上述全部三种模式的完整示例、用于一次重写多个对象的 * 通配符，以及冲突解决规则。

高级概念

构建级别的认证

系统属性 system.teamcity.auth.userId 和 系统团队城市认证密码 自动存储生成的独特构建值，这些值可以用于在 TeamCity 服务器上进行认证。 这些数值仅在构建运行期间有效。 此生成的用户拥有有限的权限，允许进行与构建相关的操作。 用户的主要意图是使用身份验证在构建脚本中从其他 TeamCity 构建下载工件。

使用属性优于使用真实用户凭证，因为它允许服务器跟踪您的构建下载的工件。 如果工件是通过构建配置工件依赖项或使用提供的属性下载的，则构建使用的特定工件将显示在 依赖 选项卡的 构建结果 页面上。 此外，用于获取制品的构建，可以配置不同的 清理 逻辑。

使用 Ant 构建脚本配置工件依赖项

这一部分描述了如何在构建脚本中下载 TeamCity 构建工件。 这些指令也可以用于从 TeamCity 外部下载工件。

为了处理构建之间的工件依赖性，这个解决方案比在 TeamCity UI 中配置依赖性更复杂，但允许更大的灵活性。 例如，以这种方式管理依赖关系将允许您启动个人构建，并验证您的构建是否仍然与依赖关系兼容。

通过 Ant 构建脚本配置依赖项：

  1. 下载 Ivy。

  2. 将 Ivy 添加到您的构建的类路径中。

  3. 创建一个包含有关 TeamCity 仓库部分元数据的 ivyconf.xml 文件。 这个文件应包含以下内容：

    <ivysettings> <property name='ivy.checksums' value=''/> <caches defaultCache="${teamcity.build.tempDir}/.ivy/cache"/> <statuses> <status name='integration' integration='true'/> </statuses> <resolvers> <url name='teamcity-rep' alwaysCheckExactRevision='yes' checkmodified='true'> <ivy pattern='http://YOUR_TEAMCITY_HOST_NAME/httpAuth/repository/download/[module]/[revision]/teamcity-ivy.xml' /> <artifact pattern='http://YOUR_TEAMCITY_HOST_NAME/httpAuth/repository/download/[module]/[revision]/[artifact](.[ext])' /> </url> </resolvers> <modules> <module organisation='.*' name='.*' matcher='regexp' resolver='teamcity-rep' /> </modules> </ivysettings>

  4. 将 YOUR_TEAMCITY_HOST_NAME 替换为您的 TeamCity 服务器的主机名称。

  5. 将 ivyconf.xml 放置在您的 build.xml 将要运行的目录中。

  6. 在同一目录中创建 ivy.xml 文件，定义需要下载哪些构件并将它们放在哪里，例如：

    <ivy-module version="1.3"> <info organisation="YOUR_ORGANIZATION" module="YOUR_MODULE"/> <dependencies> <dependency org="org" name="BUILD_TYPE_EXT_ID" rev="BUILD_REVISION"> <include name="ARTIFACT_FILE_NAME_WITHOUT_EXTENSION" ext="ARTIFACT_FILE_NAME_EXTENSION" matcher="exactOrRegexp"/> </dependency> </dependencies> </ivy-module>

    where:

    • YOUR_ORGANIZATION 替换为您的组织名称。

    • YOUR_MODULE 请用您计划或模块的名称替换，那里将会使用到文物。

    • BUILD_TYPE_EXT_ID 用构建配置的 external ID 替换，这是被下载的构件。

    • BUILD_REVISION 可以是编译号，也可以是以下字符串之一： * latest.lastFinished

      • latest.lastSuccessful

      • latest.lastPinned

    • TAG_NAME.tcbuildtag - 最后一个用 TAG_NAME 标签标记的构建

    • ARTIFACT_FILE_NAME_WITHOUT_EXTENSION 艺术品的文件名或正则表达式，不包括扩展名部分。

    • ARTIFACT_FILE_NAME_EXTENSION 文件名中的扩展部分。

  7. 修改您的 build.xml 文件并添加用于下载工件的任务，例如（适用于 Ant 1.6 及以后版本）：

    <target name="fetchArtifacts" description="Retrieves artifacts for TeamCity" xmlns:ivy="antlib:org.apache.ivy.ant"> <taskdef uri="antlib:org.apache.ivy.ant" resource="org/apache/ivy/ant/antlib.xml"/> <classpath> <pathelement location="${basedir}/lib/ivy-2.0.jar"/> <pathelement location="${basedir}/lib/commons-httpclient-3.0.1.jar"/> <pathelement location="${basedir}/lib/commons-logging.jar"/> <pathelement location="${basedir}/lib/commons-codec-1.3.jar"/> </classpath> </taskdef> <ivy:configure file="${basedir}/ivyconf.xml" /> <ivy:cleancache /> <ivy:retrieve pattern="${basedir}/[artifact].[ext]"/> </target>

制品库受到基础身份验证的保护。 为了访问这些工件，您需要为 <ivy:configure/> 任务提供凭证。 例如：

<ivy:configure file="${basedir}/ivyconf.xml" host="TEAMCITY_HOST" realm="TeamCity" username="USER_ID" passwd="PASSWORD"/>

其中 TEAMCITY_HOST 是您的 TeamCity 服务器的主机名或 IP 地址（不包括端口和 servlet 上下文）。
作为 USER_ID/PASSWORD ，您可以使用普通 TeamCity 用户的用户名/密码（该用户应具有访问源构建配置的工件的相应权限）或系统属性 system.teamcity.auth.userId/系统团队城市认证密码。

2026年 9月 11日
配置链依赖项配置运行构建链