TeamCity On-Premises 2026.1 Help

管理运行

运行代表 TeamCity 中的构建执行。 teamcity run 命令组可以启动构建、实时监控、视图日志和测试结果、管理工件，并用标记、注释和固定组织运行。

列出运行

使用 teamcity run list 视图最近的构建：

teamcity run list
列出和筛选器运行

收藏夹运行

使用 teamcity run list --favorites 显示当前用户收藏夹构建，包括手动加星的构建和 TeamCity 标记为重要的构建：

teamcity run list --favorites teamcity run list --favorites --status failure --limit 10

--favorites 可与现有的 run list 筛选器和输出模式一起使用。

筛选

使用标志缩小结果范围：

# Builds for a specific job teamcity run list --job MyProject_Build # Filter by project teamcity run list --project MyProject # Filter by branch teamcity run list --branch main # Auto-detect the current git branch teamcity run list --branch @this # Filter by status teamcity run list --status failure # Show only your favorite builds teamcity run list --favorites # Show only your own recent builds teamcity run list --user @me # Show only the latest matching run teamcity run list --user @me --branch @this --limit 1 # Filter by user who triggered the build teamcity run list --user alice teamcity run list --user @me # Combine filters teamcity run list --job MyProject_Build --status failure --branch main

按修订筛选器

使用 --revision 查找包含特定 VCS 提交的所有构建：

# All builds for a commit teamcity run list --revision abc1234 # Scoped to a specific job teamcity run list --revision abc1234 --job MyProject_Build # Auto-detect the current HEAD commit teamcity run list --revision @head

基于时间的筛选器

使用 --since 和 --until 通过筛选器按时间筛选。 支持时长偏移（24h、 7d、 2w、 1mo、 4w2d5h ）或 ISO 日期（2026-01-15、 2026-01-15T12:00:00Z）：

# Builds from the last 24 hours teamcity run list --since 24h # Builds from the last week teamcity run list --since 7d # Builds from a specific date onward teamcity run list --since 2026-01-15 # Builds in a time range teamcity run list --since 2026-01-15 --until 2026-01-20

限制结果

teamcity run list --limit 20

输出选项

# JSON output (see Scripting and automation for details) teamcity run list --json teamcity run list --json=id,status,webUrl # Plain text for scripting teamcity run list --plain teamcity run list --plain --no-header

运行列表标志

标志

描述

-j， --job

按作业（构建配置）ID 筛选器

-p， --项目

根据项目 ID 筛选器筛选

-b， --branch

通过分支名称筛选器。 使用 @this 解析当前 git 分支。

--status

按状态筛选器： 成功、 失败、 running、 queued、 错误 或 unknown

--favorites

显示当前用户收藏夹构建。

-u， --用户

通过触发构建的用户筛选器。 使用 @me 指定当前用户。

--revision

通过 VCS 修订（提交 SHA）筛选器。 使用 @head 解析当前 git HEAD。

--since

显示在此时间之后完成的构建（例如 24h、 7d、 2026-01-21）

--until

显示在此时间之前完成的构建

-n， --limit

显示的最大运行数

--json

输出为 JSON。 使用 --json= 可列出可用字段， --json=f1,f2 可查看指定字段。

--plain

脚本用选项卡分隔输出

--no-header

省略页眉行（与 --plain 一起使用）

-w， --web

在浏览器中打开列表

启动运行

使用 teamcity run start 触发新构建：

teamcity run start MyProject_Build

指定分支和修订

# Build a specific branch teamcity run start MyProject_Build --branch feature/login # Build the branch you are currently on teamcity run start MyProject_Build --branch @this # Pin to a specific Git commit teamcity run start MyProject_Build --branch main --revision abc123def # Pin to the current HEAD teamcity run start MyProject_Build --branch @this --revision @head

构建参数

传递自定义参数、系统属性和环境变量：

teamcity run start MyProject_Build \ -P version=1.0 \ -S build.number=123 \ -E CI=true

构建选项

# Clean all source files before building teamcity run start MyProject_Build --clean # Rebuild all dependencies teamcity run start MyProject_Build --rebuild-deps # Rebuild only failed dependencies teamcity run start MyProject_Build --rebuild-failed-deps # Reuse existing builds as snapshot dependencies (pin by build ID) teamcity run start MyProject_Build --reuse-deps 6946,6917 # Add to the top of the queue teamcity run start MyProject_Build --top # Run on a specific agent teamcity run start MyProject_Build --agent 5

标记和注释

teamcity run start MyProject_Build --tag release --tag v2.0 --comment "Release build"

启动并监视

添加 --watch 在启动后跟踪构建：

teamcity run start MyProject_Build --branch main --watch
使用 --watch 启动构建

你还可以设置超时或调整轮询间隔：

teamcity run start MyProject_Build --watch --timeout 30m teamcity run start MyProject_Build --watch --interval 10

个人构建

在个人构建中包含未提交的本地更改：

# Auto-detect changes from Git working directory teamcity run start MyProject_Build --local-changes # From a patch file teamcity run start MyProject_Build --local-changes changes.patch # From stdin git diff | teamcity run start MyProject_Build --local-changes -

默认情况下，CLI 会在启动个人构建前将你的分支推送到远程。 使用 --no-push 跳过此操作：

teamcity run start MyProject_Build --local-changes --no-push

试运行

预览将会触发的内容，而不实际启动构建：

teamcity run start MyProject_Build --dry-run

运行启动标志

标志

描述

-b， --branch

要构建的分支。 使用 @this 解析当前 git 分支。

--revision

将构建固定到指定 Git 提交 SHA。 使用 @head 解析当前 HEAD；短 SHA 值将从本地仓库扩展。

-P， --param

构建参数作为 key=value （可重复）

-S， --system

系统属性作为 key=value （可重复）

-E， --env

环境变量作为 key=value （可重复）

-m， --comment

构建注释

-t， --tag

构建标记（可重复）

--personal

作为个人构建运行

-l， --local-changes

包含本地更改。 支持 git （默认）、 - （stdin）或文件路径。

--no-push

跳过分支自动推送到远程

--clean

在构建前清理源文件

--rebuild-deps

重建所有依赖项

--rebuild-failed-deps

只重建失败或未完成的依赖项

--reuse-deps

复用已有构建作为快照依赖项。 支持以逗号分隔的构建 ID 列表，或可重复。 TeamCity 会根据构建配置解析每个依赖项槽由哪个构建填充。

--top

加入构建队列顶部

--agent

在指定代理（按ID）上运行

--watch

启动后监视构建

-i， --interval

监视时刷新间隔（秒，默认：3）

--timeout

监视时的超时时间（例如 30m、 1h ），启用 --watch

--dry-run

预览但不启动

--json

以 JSON 格式输出

-w， --web

在浏览器中打开运行

查看运行详细信息

teamcity run view 12345 teamcity run view 12345 --web teamcity run view 12345 --json

快照依赖项树

使用 teamcity run tree 可可视化运行的快照依赖项链：

teamcity run tree 12345
查看运行快照依赖项树

限制树的深度：

teamcity run tree 12345 --depth 2

以 JSON 格式输出：

teamcity run tree 12345 --json

运行树标志

标志

描述

-d， --depth

限制树深度（0 = 不限）

--json

以 JSON 格式输出

监视运行

实时更新监控运行中的构建：

teamcity run watch 12345

监视时流式输出构建日志：

teamcity run watch 12345 --logs
实时日志流监视构建

设置自定义刷新间隔或超时：

teamcity run watch 12345 --interval 10 teamcity run watch 12345 --timeout 30m

使用 --quiet 实现最小化输出，仅显示状态变更及最终结果：

teamcity run watch 12345 --quiet

使用 --json 等待构建完成并以 JSON 输出最终结果（适用于脚本）：

teamcity run watch 12345 --json

运行监视标志

标志

描述

-i， --interval

刷新间隔秒

--logs

监视时流式输出构建日志

--quiet

最小化输出——只显示状态变化和结果

--json

等待补全并以 JSON 格式输出结果

--timeout

达到此时长后停止监视（例如 30m、 1h）

查看构建日志

视图运行日志输出：

teamcity run log 12345

视图特定作业的最新运行日志：

teamcity run log --job MyProject_Build
查看构建日志

显示失败诊断——包括构建问题、带完整堆栈跟踪的测试失败以及每个失败是否为新出现或历史问题：

teamcity run log 12345 --failed

跳过分页器并输出原始文本：

teamcity run log 12345 --raw

实时流式显示日志直到构建完成：

teamcity run log 12345 --follow

显示最近 50 条日志消息：

teamcity run log 12345 --tail 50

以 JSON 格式输出日志：

teamcity run log 12345 --json

在浏览器中打开构建日志：

teamcity run log 12345 --web

取消运行

取消正在运行或队列中的构建：

teamcity run cancel 12345 teamcity run cancel 12345 --comment "Canceling for hotfix"

使用 --yes 跳过确认提示：

teamcity run cancel 12345 --yes

重启运行

用相同配置重启运行：

teamcity run restart 12345 teamcity run restart 12345 --watch teamcity run restart 12345 --timeout 30m teamcity run restart 12345 --web

工件

列出工件

列出运行产出的工件但不下载：

teamcity run artifacts 12345 teamcity run artifacts --job MyProject_Build teamcity run artifacts 12345 --path html_reports/coverage teamcity run artifacts 12345 --json

下载工件

从已完成的运行中下载工件：

teamcity run download 12345 teamcity run download 12345 --path build/assets teamcity run download 12345 -o ./artifacts teamcity run download 12345 --artifact "*.jar" teamcity run download 12345 --path build/assets -a "*.js" teamcity run download 12345 --timeout 30m

--timeout 标志设置整个下载操作的最长时间（默认： 10m）。 对于大型工件集请使用更长的值，例如 --timeout 1h。

测试结果

显示运行的测试结果：

teamcity run tests 12345 teamcity run tests --job MyProject_Build

仅显示失败的测试，不包括静音失败：

teamcity run tests 12345 --failed

仅显示静音失败的测试：

teamcity run tests 12345 --muted
查看测试结果

限制结果数量：

teamcity run tests 12345 --limit 50 teamcity run tests 12345 --json

VCS 更改

显示运行中包含的 VCS 提交：

teamcity run changes 12345

只显示提交（不包含文件列表）：

teamcity run changes 12345 --no-files teamcity run changes 12345 --json

比较运行

并排比较两个运行并高亮显示它们之间的改变——包括状态、用时、代理、参数、测试结果、问题和 VCS 变更：

teamcity run diff 12345 12346
比较两个运行

如只给出一个运行 ID，CLI 将其与同一作业的上一次完成运行进行比较——方便了解“自上次有何变更？”：

teamcity run diff 12345

构建日志差异

传递 --log 以将两个构建日志以彩色统一差异进行比较。 时间戳、临时路径和噪声 git 进度行会标准化，以聚焦真正内容的差异：

teamcity run diff 12345 12346 --log teamcity run diff 12345 12346 --log -U5 # 5 lines of context

输出通过你的管道分页器（$PAGER ，默认是 less）。 去除颜色并通过管道发送到外部差异查看器以获得更丰富的显示：

teamcity run diff 12345 12346 --log --no-color | delta teamcity run diff 12345 12346 --log --no-color | diff-so-fancy

其他表单

在浏览器中同时打开这两次运行：

teamcity run diff 12345 12346 --web

脚本用可机器读取的输出：

teamcity run diff 12345 12346 --json

固定运行

固定运行，防止其被保留策略清理：

teamcity run pin 12345 teamcity run pin 12345 --comment "Release candidate"

移除固定：

teamcity run unpin 12345

为运行添加标签

为运行添加标记以分类和筛选：

teamcity run tag 12345 release teamcity run tag 12345 release v2.0 production

删除标签:

teamcity run untag 12345 release teamcity run untag 12345 release v2.0

消息

为运行设置注释：

teamcity run comment 12345 "Deployed to production"

视图当前注释：

teamcity run comment 12345

删除注释：

teamcity run comment 12345 --delete
2026年 8月 6日
关联仓库管理作业