简介这是一份面向 Azure DevOps 使用者的 Azure Pipelines 中文操作手册适合正在搭建持续集成、持续交付CI/CD流程的开发、运维与 DevOps 工程师。内容先说明什么是 Azure Pipelines、使用要求与定价/免费额度再按快速入门、教程、关键概念、参考指南、操作指南、疑难解答等模块组织覆盖免费注册、创建第一个管道、克隆或导入管道、自定义管道、经典发布管道以及代理、条件、表达式、环境、作业、运行时参数、阶段、任务、模板、触发器这类核心概念。同时给出容器映像、.NET Core、Anaconda、Android、AKS、Java、Node.js、Python、PHP 等多语言多生态的部署示例。资源共 1 个 PDF 文件包体约 106.6MB适合离线查阅和团队内部分享目前已有 412 人学习下载。读者据此可从零编写 YAML 管道掌握多分支生成、环境部署、持续测试、资源管理与常见疑难排查思路直接把 Azure Pipelines 落到日常交付流程中。1. Azure Pipelines 管道报错为什么每次构建失败都要查半天你在 Azure Pipelines 里点下运行几分钟后看到那行刺眼的No agent found in pool或者被 YAML 解析错误逼着逐行数缩进——这类持续集成/持续交付CI/CD管道的报错是团队开发里最耽误事的问题之一。管道一挂合并、发布全被卡住而报错往往只给一小段上下文要自己拼。更麻烦的是官方文档把 YAML、代理、服务连接、发布拆在各章真实报错却常常横跨几块。这份排错手册按故障场景把 Azure DevOps Pipeline 常见问题重排现象先摆清再追根因最后给可抄作业的命令适合正在被流水线卡住、想快速恢复构建的开发者。2. YAML 管道解析报错先把缩进、求值时机和触发器理清YAML 管道是现在新建 Azure Pipelines 的首选方式但它带来的报错也最让人头疼。写错一个缩进、混用空格、把运行时变量塞进编译时表达式都可能让整个流水线在解析阶段就翻车。这一章从三类最常碰到的 YAML 报错讲起。2.1 缩进与语法错误报错不在真正出错的那一行前阵子有个同事把一份 YAML 从别的项目拷过来改完池名就提交了结果管道运行一分钟不到就红在 Queue 阶段。日志里只有一句mapping values are not allowed in this context可你去对照 YAML 文件怎么都看不出哪个 map 写错了。这类报错最磨人的地方在于解析器报的行号往往不是真正有问题的行而是它发现结构不对时的最后一行。常见根因有三个同一列表里混用了不同数量的空格缩进、-列表项后没有空格、把键值对写错了层级。# 错误写法第二个步骤少了缩进YAML 解析器无法判断它属于 steps steps: - script: echo hello - script: echo world# 正确写法列表项缩进一致必要时用 | 声明多行脚本 steps: - script: | echo hello - script: | echo world我一般会先用yamllint这类本地校验工具过一遍再提交比在网页里来回点“运行”快得多。yamllint azure-pipelines.ymlyamllint会精确给出第几行第几个字符有问题并且把「缩进不一致」「行尾空格」这类隐形错误一次性列出来。命令行输出里可能包含syntax error字样但不用慌它后面会跟行号和错误码按指示改即可。如果本地没装也可以在项目设置里找到管道编辑页右上角有一个校验入口作用类似。还有一类常见的 YAML 报错是任务名拼写问题比如UseDotNet2写成UseDotNet1或者把pool错误地写进了steps下。这类报错会直接提示Unexpected value pool看到这种关键词先回 YAML 顶层结构检查层级关系通常不用怀疑别的。2.2 条件表达式与变量编译时求值、运行时求值别混淆条件表达式是 YAML 管道里另一个高频翻车点。你想让某些步骤只在 main 分支跑结果条件要么永远成立要么永远不成立日志里还看不出明显错误。根因在于 Azure Pipelines 有两套完全不同的求值机制${{ }}是编译阶段求值的模板表达式在管道编译展开 YAML 时就计算$( )和variables[xxx]是作业运行时求值到了每个任务执行时才解析。把运行时变量包进${{ }}拿到的只是字面量条件自然不对。# 错误写法Build.SourceBranch 是运行时变量用 ${{ }} 包裹后不会展开 condition: and(succeeded(), eq(${{ variables[Build.SourceBranch] }}, refs/heads/main))# 正确写法运行时变量用 variables[] 表达式引用 steps: - script: echo 构建分支: $(Build.SourceBranch) condition: and(succeeded(), eq(variables[Build.SourceBranch], refs/heads/main)) - script: echo 构建配置: ${{ parameters.buildConfiguration }}注意上面两个例子的区别Build.SourceBranch要运行时才能确定所以用variables[Build.SourceBranch]parameters.buildConfiguration是编译期就能确定的模板参数用${{ }}没问题。判断标准很简单——这个值是在 YAML 展开前就知道还是要等作业跑起来才有拿不准时就用运行时写法适用范围更广。与条件表达式紧密相关的是阶段依赖。很多人写完stages以为会从上到下顺序执行实际上不写dependsOn的阶段会并行运行这在部署链路上会造成“测试还没跑完就部署了”的诡异现象。stages: - stage: Build jobs: - job: Compile steps: - script: dotnet build - stage: Deploy dependsOn: Build condition: succeeded() jobs: - job: DeployJob steps: - script: dotnet publish --output $(Build.ArtifactStagingDirectory)dependsOn指定了前置阶段condition: succeeded()表示只有前序阶段成功才继续。如果你想在所有阶段结束后无论如何都跑一个清理任务那要在这类 step 上用condition: always()我在第 5 章会专门讲这个坑。2.3 触发器不触发先检查分支筛选和路径筛选还有一种非常容易误判的故障代码推上去了管道却没反应看起来像是触发器坏了。实际上大多数情况是分支筛选或路径筛选的配置把这次提交过滤掉了。trigger: branches: include: - main - releases/* paths: include: - src/* exclude: - docs/*这段配置表示只有 main 分支和 releases 前缀分支上的推送才会触发并且只有改动涉及src目录才触发如果提交只改了docs下的文档管道不会跑——这是预期行为不是故障。新人在遇到“不触发”时要先去「运行历史」里看这次提交是否连记录都没有如果有记录但失败了那是构建问题如果根本没记录再回来查筛选条件。注意触发器在 YAML 里可以写成trigger: none此时管道完全手动运行。做调试或演示项目时常用这个配置免得每次推代码都触发一次完整构建。路径筛选的 include 和 exclude 同时写时Azure Pipelines 的处理顺序是先算 include 再减去 exclude。官方文档里「触发器」那一节专门强调了这个规则实际排查时可以先临时把 paths 整段注释掉看管道是否恢复触发以此确认是不是路径筛选误伤。3. 代理与代理池No agent found 的根因和自托管代理注册No agent found in pool可以说是 Azure Pipelines 里出现频率最高的报错。它本身不是一个任务失败而是整个作业根本没有代理可跑所以日志通常很短也不指向具体代码。这一章把它的三个主要根因和对应的处理方式拆开。3.1 No agent found需求不匹配、池为空与免费分钟用尽先看作业运行的池配置pool: name: 默认 demands: - agent.version -equals 2.170.1name指定代理池demands指定代理必须满足的标签或版本要求。如果池里所有在线代理都不满足 demandsAzure Pipelines 就报No agent found in pool 默认。常见做法是把 demands 删掉或把池名改回环境里真实存在的那个还要确认池里的代理当前是 Online 而不是 Offline。第二个很隐蔽的原因是额度问题。文档里写得很明确私有项目每月可以免费运行 1800 分钟30 小时的管道作业公共项目则是免费并行。你在界面上会看到作业长期停留在“排队中”日志只有一句Waiting for an available agent看起来像卡死其实是月度免费分钟耗尽后面的作业按顺序排队等待放出。注意额度耗尽的表现为「等待代理」不是任务标红失败。先去组织设置里的并行作业页面看剩余分钟数再决定扩容还是把部分作业切到自托管代理省得白查一场。第三种原因是代理池为空。新建的账号默认只有一个 Microsoft 托管代理池如果你在 YAML 里写了自定义池名但还没创建作业自然找不到代理。处理方式是先去代理池页面确认池存在、确认作业用的池名和它完全一致再回头看作业配置。3.2 自托管 Linux 代理注册参数与常见失败很多团队为了省钱或安全会把自托管代理跑在自己服务器上注册过程本身不复杂但失败往往发生在细节里。下面是常见的注册流程。mkdir -p ~/agents/myagent cd ~/agents/myagent tar xzf vsts-agent-linux-x64-对应版本号.tar.gz ./config.sh --unattended \ --url https://dev.azure.com/你的组织名 \ --auth pat \ --token 个人访问令牌 \ --pool 默认 \ --agent myagent ./run.sh先到项目组织的设置页面下载对应版本的代理包解压后执行config.sh。--url填组织域名--auth pat表示用个人访问令牌鉴权--token后接的 PAT 需要有代理池管理的权限--pool指定要注册到哪个池--agent是代理在这台机器上的显示名。最后的run.sh让代理前台运行看到Listening for Jobs字样说明注册成功。如果config.sh报 401基本是 PAT 失效或权限不够去用户设置里生成一个新的 PAT勾选 Agent Pools 的读写权限再来一次。如果报连接超时先检查这台服务器到dev.azure.com的连通性再看代理池名字是否打错。代理注册成功后想在后台稳定跑常见做法是注册成服务比如用 systemd 守护[Unit] DescriptionAzure Pipelines Agent Afternetwork.target [Service] Typesimple Userazure ExecStart/home/azure/agents/myagent/run.sh Restartalways [Install] WantedBymulti-user.targetRestartalways让它在崩溃或服务器重启后自动拉起Userazure指定以哪个系统用户运行。把这份 unit 文件放到/etc/systemd/system/执行systemctl enable开机自启比手动跑run.sh省心很多。3.3 托管代理与自托管代理怎么选到这里很多人会问到底用托管代理还是自托管代理我一般建议按场景分。任务多且短、需要多平台并行跑编译用托管代理最省事系统镜像齐全YAML 里写vmImage: ubuntu-latest就能跑起来。而构建耗时长、需要访问内网资源、或希望省下月度分钟数就用自托管代理。自托管代理有个需要接受的事实环境是你自己维护的代理跑的机器如果缺依赖任务会失败得很莫名其妙。比如 Linux 代理上没装dotnet构建任务报找不到命令这时候去重启代理是没用的得先补运行时环境再在代理池的 capabilities 里确认标签已刷新。从那以后我每次把代理解压到新服务器都会先跑一次最简单的echo任务验证注册成功再放复杂的构建上去。4. 服务连接与经典发布管道部署失败大多是权限和配置问题构建跑通只是第一步部署阶段的报错往往更折磨人。这类报错的特征是任务本身成功但和远端服务握手时被拒比如 Azure 资源管理器连接验证失败或者经典发布管道卡在某一步。这一章专讲部署链路。4.1 Azure 资源管理器服务连接鉴权失败排查顺序如果你的管道用了 AzureCLI 任务或部署任务日志里出现Failed to get access token、Insufficient privileges to complete the operation这类信息先别怀疑 YAML 语法这是服务连接本身出了问题。服务连接的底层是一个服务主体Service Principal它拿着应用注册的凭据去访问订阅里的资源。最常见的根因有三个凭据过期或轮换后没有更新连接、订阅被迁移到其他租户、服务主体在订阅下的 RBAC 角色权限不足。排查顺序很重要我一般先从 UI 验证开始。进入项目设置选择「服务连接」找到出错的那个连接点右侧的“验证”按钮。验证通过说明连接本身的鉴权没问题问题在后续任务用的权限范围验证失败说明连接底层的凭据已经无效。在本地命令行用 Azure CLI 直接模拟一次登录能快速区分是连接坏了还是权限不够az login --service-principal \ --username 应用注册ID \ --password 客户端密钥 \ --tenant 租户ID az account show--username填服务主体的应用客户端ID--password填客户端密钥--tenant填订阅所属的租户 ID。如果这段命令能成功返回订阅信息说明凭据本身没问题失败则直接去 Azure 门户检查应用注册是否被删除或密钥是否过期。本地能登录而管道还报错时检查服务主体在目标订阅的角色。az role assignment list --assignee 服务主体ID --output table没有任何角色说明它没有权限操作订阅资源给它分配 Contributor 角色是最快的验证做法az role assignment create \ --assignee 服务主体ID \ --role Contributor \ --scope /subscriptions/订阅ID--role Contributor是 Azure 内置角色覆盖大多数部署场景--scope限定了授权范围指向某个订阅。注意这个命令本身需要登录者有足够的权限权限不足时它会返回授权错误而不是正常的“已创建角色”。注意服务连接的密码和任何客户端密钥都不要直接写进 YAML 或 UI 变量。管道的成功做法是在「服务连接」里保存凭据YAML 中只写连接名AzureCLI 等任务会自动帮你处理鉴权。4.2 经典发布管道部署组、任务组与审批卡住还在用经典发布管道的旧项目排错思路和 YAML 管道不太一样。经典发布管道的每一步都在 UI 里配置日志信息却更分散常见的坑集中在工件来源和部署目标上。第一个高频报错是「找不到生成工件」。经典发布管道里的「工件」需要显式指定来源构建管道如果原来的构建定义被删除或重命名发布运行时就会提示找不到对应的产物。你按报错进发布运行的详情页看「阶段」下引用的源会直接标红。处理方式是重选一次工件源或者把工件源切换为保存到 Azure Artifacts 的统一包源。第二个坑是部署组。经典发布管道的部署阶段通常指向「部署组」它和代理池是两回事代理池运行构建作业部署组里的机器是发布阶段的执行目标。如果部署阶段卡着不动日志提示找不到可用的部署目标先检查部署组里是否注册了机器以及机器上的代理是否在线。注册脚本在部署组的概览页里会生成复制到目标服务器以管理员身份执行一遍即可。经典发布管道还经常因为「审批人」卡住。环境配置里设置了发布审批但审批人账号被停用或角色变更后不再有审批权限发布就会永远停在「等待批准」的状态。此时不要反复点重试直接看阶段状态旁显示的审批人姓名确认此人是否还有项目的成员权限。任务组的坑也类似任务组被修改版本后引用它的管道在发布时会锁定到旧版本界面会提示「任务组版本不一致」需要手动选择要使用的版本否则任务内容可能和你预期的不一样。5. 常见问题Azure Pipelines 排错最容易踩的 5 个坑这一章整理的是我自己和身边同事反复踩过、文档里又散落在各处的坑。每条按「现象 → 原因 → 解决」来写方便你直接对照。5.1 脚本明明成功任务却标红现象命令行里 echo 了Build succeeded输出也正常但任务状态是红色后续步骤全部被跳过。原因任务判定成功与否是看进程退出码不是看输出文本。PowerShell 脚本最后一个命令失败但脚本没加错误处理退出码为负数时任务就会被标记失败。解决在脚本开头加set -ebash或$ErrorActionPreference StopPowerShell并检查脚本最后一条命令的返回值。定位时看日志里有没有Exit code 1这类行有就是退出码问题。5.2 condition: always() 失灵清理步骤没跑现象把某个应该在管道失败后执行的清理任务写成了condition: always()结果失败时它照样没跑。原因条件写错层级或写错了函数名。always()是一个函数调用必须写成condition: always()如果写成字符串always会不生效另外条件必须挂在对应 step 上不能只写在作业级别。解决回到 YAML 确认 conditions 是否缩进在task下并检查是否带了()。5.3 私有仓库克隆一直失败任务日志提示认证错误现象构建任务里拉取代码仓库时弹出Authentication failed本地却能正常 clone。原因管道使用的服务连接权限不够或者 PAT 过期。Git 类仓库的凭据存在「服务连接」里新建的个人访问令牌默认可能只勾了代码读取权限没有勾仓库状态等权限。解决进入服务连接重新验证错的话重新生成 PAT 并更新连接如果仓库在另一个组织下还要确认连接的范围包含那个组织的访问权限。完成后先去服务连接页点一次「验证」再重跑管道。5.4 变量组里的 Secret 取出来是空的现象密钥放在变量组里任务里用$(mySecret)引用日志输出***甚至直接是空字符串。原因YAML 管道必须在variables里显式声明要引用的变量组可能默认的 secret 为了安全在条件表达式里无法参与比较。解决在管道顶部声明变量组例如variables: - group: 我的变量组声明后再用$(mySecret)引用。不要在condition里直接比较 secret 值Azure Pipelines 会把它禁用这是刻意设计的保护机制不是 bug。5.5 自托管代理显示 Online接任务却失败现象代理池列表里状态明明是 Online但一接任务就握手失败或报连接错误。原因最常见的是代理的注册凭据失效比如当初配置时用的 PAT 已过期或者代理版本太旧和服务端通信协议不匹配。解决先看代理机器上run.sh的日志有没有认证错误有就重新执行一次config.sh并输入新 PAT如果代理版本太旧到代理目录执行./config.sh remove移除旧注册解压新版本代理包重新注册一遍。注册新的实例时尽量用不同的 agent 名称以免旧的离线实例影响判断。6. 快速定位30 分钟理清一个管道故障的排查顺序最后分享一套我每次排查管道故障都会固化的顺序不管报错长什么样先按这个流程走一遍大部分问题都能在半小时内定位。第一步先看运行摘要页面里失败的那个任务点进日志搜索##[error]前缀的行。这是 Azure Pipelines 标记错误的标准格式搜到它就等于找到了任务失败的第一现场。很多报错被前面的冗长输出挡住直接搜这个前缀能跳过大量干扰。第二步打开调试模式。YAML 管道里加一个变量就能看到详细诊断variables: system.debug: true经典发布管道则在发布管道的变量区域添加同名变量值为 true。开启后再跑一次失败的任务日志里会出现大量##[debug]行包括每一步任务的传参、环境变量、代理与服务的请求响应。调试模式下信息量很大但它在定位“任务为什么在这个环境里失败”时不可替代。定位完记得关掉避免日志膨胀和敏感信息泄露。第三步判断故障属于哪一层。我常用下面这张表来快速分流报错片段故障层优先排查No agent found in pool代理与额度池名、代理在线状态、并行分钟数mapping values are not allowedYAML 解析模块缩进、列表项对齐Failed to get access token服务连接服务主体凭据、RBAC 角色Authentication failed代码仓库连接服务连接权限、PAT 有效期任务日志只有##[error]且输出极短运行时/调试开启 system.debug 后重跑第四步做最小复现。把出问题的管道复制一份删掉一半步骤留一个空 job 和一个失败任务先确认代理、服务连接这些基础设施是好的再逐步加步骤观察哪一步引入问题。这个方法看起来很笨但比对着完整日志猜快得多。这四步走完大部分故障的场景都能定位到具体章节去翻细节。从那以后我每次新建管道都会强制走一遍这套顺序——看日志、开 debug、对表、做最小复现尤其是system.debug这个开关比反复点重试有用得多。完整的排查对照表和命令集都整理在这份 PDF 手册里遇到本文没覆盖的报错时翻一遍目录会省很多时间。希望帮到你。本文还有配套的精品资源点击获取
简介这是一份面向 Azure DevOps 使用者的 Azure Pipelines 中文操作手册适合正在搭建持续集成、持续交付CI/CD流程的开发、运维与 DevOps 工程师。内容先说明什么是 Azure Pipelines、使用要求与定价/免费额度再按快速入门、教程、关键概念、参考指南、操作指南、疑难解答等模块组织覆盖免费注册、创建第一个管道、克隆或导入管道、自定义管道、经典发布管道以及代理、条件、表达式、环境、作业、运行时参数、阶段、任务、模板、触发器这类核心概念。同时给出容器映像、.NET Core、Anaconda、Android、AKS、Java、Node.js、Python、PHP 等多语言多生态的部署示例。资源共 1 个 PDF 文件包体约 106.6MB适合离线查阅和团队内部分享目前已有 412 人学习下载。读者据此可从零编写 YAML 管道掌握多分支生成、环境部署、持续测试、资源管理与常见疑难排查思路直接把 Azure Pipelines 落到日常交付流程中。1. Azure Pipelines 管道报错为什么每次构建失败都要查半天你在 Azure Pipelines 里点下运行几分钟后看到那行刺眼的No agent found in pool或者被 YAML 解析错误逼着逐行数缩进——这类持续集成/持续交付CI/CD管道的报错是团队开发里最耽误事的问题之一。管道一挂合并、发布全被卡住而报错往往只给一小段上下文要自己拼。更麻烦的是官方文档把 YAML、代理、服务连接、发布拆在各章真实报错却常常横跨几块。这份排错手册按故障场景把 Azure DevOps Pipeline 常见问题重排现象先摆清再追根因最后给可抄作业的命令适合正在被流水线卡住、想快速恢复构建的开发者。2. YAML 管道解析报错先把缩进、求值时机和触发器理清YAML 管道是现在新建 Azure Pipelines 的首选方式但它带来的报错也最让人头疼。写错一个缩进、混用空格、把运行时变量塞进编译时表达式都可能让整个流水线在解析阶段就翻车。这一章从三类最常碰到的 YAML 报错讲起。2.1 缩进与语法错误报错不在真正出错的那一行前阵子有个同事把一份 YAML 从别的项目拷过来改完池名就提交了结果管道运行一分钟不到就红在 Queue 阶段。日志里只有一句mapping values are not allowed in this context可你去对照 YAML 文件怎么都看不出哪个 map 写错了。这类报错最磨人的地方在于解析器报的行号往往不是真正有问题的行而是它发现结构不对时的最后一行。常见根因有三个同一列表里混用了不同数量的空格缩进、-列表项后没有空格、把键值对写错了层级。# 错误写法第二个步骤少了缩进YAML 解析器无法判断它属于 steps steps: - script: echo hello - script: echo world# 正确写法列表项缩进一致必要时用 | 声明多行脚本 steps: - script: | echo hello - script: | echo world我一般会先用yamllint这类本地校验工具过一遍再提交比在网页里来回点“运行”快得多。yamllint azure-pipelines.ymlyamllint会精确给出第几行第几个字符有问题并且把「缩进不一致」「行尾空格」这类隐形错误一次性列出来。命令行输出里可能包含syntax error字样但不用慌它后面会跟行号和错误码按指示改即可。如果本地没装也可以在项目设置里找到管道编辑页右上角有一个校验入口作用类似。还有一类常见的 YAML 报错是任务名拼写问题比如UseDotNet2写成UseDotNet1或者把pool错误地写进了steps下。这类报错会直接提示Unexpected value pool看到这种关键词先回 YAML 顶层结构检查层级关系通常不用怀疑别的。2.2 条件表达式与变量编译时求值、运行时求值别混淆条件表达式是 YAML 管道里另一个高频翻车点。你想让某些步骤只在 main 分支跑结果条件要么永远成立要么永远不成立日志里还看不出明显错误。根因在于 Azure Pipelines 有两套完全不同的求值机制${{ }}是编译阶段求值的模板表达式在管道编译展开 YAML 时就计算$( )和variables[xxx]是作业运行时求值到了每个任务执行时才解析。把运行时变量包进${{ }}拿到的只是字面量条件自然不对。# 错误写法Build.SourceBranch 是运行时变量用 ${{ }} 包裹后不会展开 condition: and(succeeded(), eq(${{ variables[Build.SourceBranch] }}, refs/heads/main))# 正确写法运行时变量用 variables[] 表达式引用 steps: - script: echo 构建分支: $(Build.SourceBranch) condition: and(succeeded(), eq(variables[Build.SourceBranch], refs/heads/main)) - script: echo 构建配置: ${{ parameters.buildConfiguration }}注意上面两个例子的区别Build.SourceBranch要运行时才能确定所以用variables[Build.SourceBranch]parameters.buildConfiguration是编译期就能确定的模板参数用${{ }}没问题。判断标准很简单——这个值是在 YAML 展开前就知道还是要等作业跑起来才有拿不准时就用运行时写法适用范围更广。与条件表达式紧密相关的是阶段依赖。很多人写完stages以为会从上到下顺序执行实际上不写dependsOn的阶段会并行运行这在部署链路上会造成“测试还没跑完就部署了”的诡异现象。stages: - stage: Build jobs: - job: Compile steps: - script: dotnet build - stage: Deploy dependsOn: Build condition: succeeded() jobs: - job: DeployJob steps: - script: dotnet publish --output $(Build.ArtifactStagingDirectory)dependsOn指定了前置阶段condition: succeeded()表示只有前序阶段成功才继续。如果你想在所有阶段结束后无论如何都跑一个清理任务那要在这类 step 上用condition: always()我在第 5 章会专门讲这个坑。2.3 触发器不触发先检查分支筛选和路径筛选还有一种非常容易误判的故障代码推上去了管道却没反应看起来像是触发器坏了。实际上大多数情况是分支筛选或路径筛选的配置把这次提交过滤掉了。trigger: branches: include: - main - releases/* paths: include: - src/* exclude: - docs/*这段配置表示只有 main 分支和 releases 前缀分支上的推送才会触发并且只有改动涉及src目录才触发如果提交只改了docs下的文档管道不会跑——这是预期行为不是故障。新人在遇到“不触发”时要先去「运行历史」里看这次提交是否连记录都没有如果有记录但失败了那是构建问题如果根本没记录再回来查筛选条件。注意触发器在 YAML 里可以写成trigger: none此时管道完全手动运行。做调试或演示项目时常用这个配置免得每次推代码都触发一次完整构建。路径筛选的 include 和 exclude 同时写时Azure Pipelines 的处理顺序是先算 include 再减去 exclude。官方文档里「触发器」那一节专门强调了这个规则实际排查时可以先临时把 paths 整段注释掉看管道是否恢复触发以此确认是不是路径筛选误伤。3. 代理与代理池No agent found 的根因和自托管代理注册No agent found in pool可以说是 Azure Pipelines 里出现频率最高的报错。它本身不是一个任务失败而是整个作业根本没有代理可跑所以日志通常很短也不指向具体代码。这一章把它的三个主要根因和对应的处理方式拆开。3.1 No agent found需求不匹配、池为空与免费分钟用尽先看作业运行的池配置pool: name: 默认 demands: - agent.version -equals 2.170.1name指定代理池demands指定代理必须满足的标签或版本要求。如果池里所有在线代理都不满足 demandsAzure Pipelines 就报No agent found in pool 默认。常见做法是把 demands 删掉或把池名改回环境里真实存在的那个还要确认池里的代理当前是 Online 而不是 Offline。第二个很隐蔽的原因是额度问题。文档里写得很明确私有项目每月可以免费运行 1800 分钟30 小时的管道作业公共项目则是免费并行。你在界面上会看到作业长期停留在“排队中”日志只有一句Waiting for an available agent看起来像卡死其实是月度免费分钟耗尽后面的作业按顺序排队等待放出。注意额度耗尽的表现为「等待代理」不是任务标红失败。先去组织设置里的并行作业页面看剩余分钟数再决定扩容还是把部分作业切到自托管代理省得白查一场。第三种原因是代理池为空。新建的账号默认只有一个 Microsoft 托管代理池如果你在 YAML 里写了自定义池名但还没创建作业自然找不到代理。处理方式是先去代理池页面确认池存在、确认作业用的池名和它完全一致再回头看作业配置。3.2 自托管 Linux 代理注册参数与常见失败很多团队为了省钱或安全会把自托管代理跑在自己服务器上注册过程本身不复杂但失败往往发生在细节里。下面是常见的注册流程。mkdir -p ~/agents/myagent cd ~/agents/myagent tar xzf vsts-agent-linux-x64-对应版本号.tar.gz ./config.sh --unattended \ --url https://dev.azure.com/你的组织名 \ --auth pat \ --token 个人访问令牌 \ --pool 默认 \ --agent myagent ./run.sh先到项目组织的设置页面下载对应版本的代理包解压后执行config.sh。--url填组织域名--auth pat表示用个人访问令牌鉴权--token后接的 PAT 需要有代理池管理的权限--pool指定要注册到哪个池--agent是代理在这台机器上的显示名。最后的run.sh让代理前台运行看到Listening for Jobs字样说明注册成功。如果config.sh报 401基本是 PAT 失效或权限不够去用户设置里生成一个新的 PAT勾选 Agent Pools 的读写权限再来一次。如果报连接超时先检查这台服务器到dev.azure.com的连通性再看代理池名字是否打错。代理注册成功后想在后台稳定跑常见做法是注册成服务比如用 systemd 守护[Unit] DescriptionAzure Pipelines Agent Afternetwork.target [Service] Typesimple Userazure ExecStart/home/azure/agents/myagent/run.sh Restartalways [Install] WantedBymulti-user.targetRestartalways让它在崩溃或服务器重启后自动拉起Userazure指定以哪个系统用户运行。把这份 unit 文件放到/etc/systemd/system/执行systemctl enable开机自启比手动跑run.sh省心很多。3.3 托管代理与自托管代理怎么选到这里很多人会问到底用托管代理还是自托管代理我一般建议按场景分。任务多且短、需要多平台并行跑编译用托管代理最省事系统镜像齐全YAML 里写vmImage: ubuntu-latest就能跑起来。而构建耗时长、需要访问内网资源、或希望省下月度分钟数就用自托管代理。自托管代理有个需要接受的事实环境是你自己维护的代理跑的机器如果缺依赖任务会失败得很莫名其妙。比如 Linux 代理上没装dotnet构建任务报找不到命令这时候去重启代理是没用的得先补运行时环境再在代理池的 capabilities 里确认标签已刷新。从那以后我每次把代理解压到新服务器都会先跑一次最简单的echo任务验证注册成功再放复杂的构建上去。4. 服务连接与经典发布管道部署失败大多是权限和配置问题构建跑通只是第一步部署阶段的报错往往更折磨人。这类报错的特征是任务本身成功但和远端服务握手时被拒比如 Azure 资源管理器连接验证失败或者经典发布管道卡在某一步。这一章专讲部署链路。4.1 Azure 资源管理器服务连接鉴权失败排查顺序如果你的管道用了 AzureCLI 任务或部署任务日志里出现Failed to get access token、Insufficient privileges to complete the operation这类信息先别怀疑 YAML 语法这是服务连接本身出了问题。服务连接的底层是一个服务主体Service Principal它拿着应用注册的凭据去访问订阅里的资源。最常见的根因有三个凭据过期或轮换后没有更新连接、订阅被迁移到其他租户、服务主体在订阅下的 RBAC 角色权限不足。排查顺序很重要我一般先从 UI 验证开始。进入项目设置选择「服务连接」找到出错的那个连接点右侧的“验证”按钮。验证通过说明连接本身的鉴权没问题问题在后续任务用的权限范围验证失败说明连接底层的凭据已经无效。在本地命令行用 Azure CLI 直接模拟一次登录能快速区分是连接坏了还是权限不够az login --service-principal \ --username 应用注册ID \ --password 客户端密钥 \ --tenant 租户ID az account show--username填服务主体的应用客户端ID--password填客户端密钥--tenant填订阅所属的租户 ID。如果这段命令能成功返回订阅信息说明凭据本身没问题失败则直接去 Azure 门户检查应用注册是否被删除或密钥是否过期。本地能登录而管道还报错时检查服务主体在目标订阅的角色。az role assignment list --assignee 服务主体ID --output table没有任何角色说明它没有权限操作订阅资源给它分配 Contributor 角色是最快的验证做法az role assignment create \ --assignee 服务主体ID \ --role Contributor \ --scope /subscriptions/订阅ID--role Contributor是 Azure 内置角色覆盖大多数部署场景--scope限定了授权范围指向某个订阅。注意这个命令本身需要登录者有足够的权限权限不足时它会返回授权错误而不是正常的“已创建角色”。注意服务连接的密码和任何客户端密钥都不要直接写进 YAML 或 UI 变量。管道的成功做法是在「服务连接」里保存凭据YAML 中只写连接名AzureCLI 等任务会自动帮你处理鉴权。4.2 经典发布管道部署组、任务组与审批卡住还在用经典发布管道的旧项目排错思路和 YAML 管道不太一样。经典发布管道的每一步都在 UI 里配置日志信息却更分散常见的坑集中在工件来源和部署目标上。第一个高频报错是「找不到生成工件」。经典发布管道里的「工件」需要显式指定来源构建管道如果原来的构建定义被删除或重命名发布运行时就会提示找不到对应的产物。你按报错进发布运行的详情页看「阶段」下引用的源会直接标红。处理方式是重选一次工件源或者把工件源切换为保存到 Azure Artifacts 的统一包源。第二个坑是部署组。经典发布管道的部署阶段通常指向「部署组」它和代理池是两回事代理池运行构建作业部署组里的机器是发布阶段的执行目标。如果部署阶段卡着不动日志提示找不到可用的部署目标先检查部署组里是否注册了机器以及机器上的代理是否在线。注册脚本在部署组的概览页里会生成复制到目标服务器以管理员身份执行一遍即可。经典发布管道还经常因为「审批人」卡住。环境配置里设置了发布审批但审批人账号被停用或角色变更后不再有审批权限发布就会永远停在「等待批准」的状态。此时不要反复点重试直接看阶段状态旁显示的审批人姓名确认此人是否还有项目的成员权限。任务组的坑也类似任务组被修改版本后引用它的管道在发布时会锁定到旧版本界面会提示「任务组版本不一致」需要手动选择要使用的版本否则任务内容可能和你预期的不一样。5. 常见问题Azure Pipelines 排错最容易踩的 5 个坑这一章整理的是我自己和身边同事反复踩过、文档里又散落在各处的坑。每条按「现象 → 原因 → 解决」来写方便你直接对照。5.1 脚本明明成功任务却标红现象命令行里 echo 了Build succeeded输出也正常但任务状态是红色后续步骤全部被跳过。原因任务判定成功与否是看进程退出码不是看输出文本。PowerShell 脚本最后一个命令失败但脚本没加错误处理退出码为负数时任务就会被标记失败。解决在脚本开头加set -ebash或$ErrorActionPreference StopPowerShell并检查脚本最后一条命令的返回值。定位时看日志里有没有Exit code 1这类行有就是退出码问题。5.2 condition: always() 失灵清理步骤没跑现象把某个应该在管道失败后执行的清理任务写成了condition: always()结果失败时它照样没跑。原因条件写错层级或写错了函数名。always()是一个函数调用必须写成condition: always()如果写成字符串always会不生效另外条件必须挂在对应 step 上不能只写在作业级别。解决回到 YAML 确认 conditions 是否缩进在task下并检查是否带了()。5.3 私有仓库克隆一直失败任务日志提示认证错误现象构建任务里拉取代码仓库时弹出Authentication failed本地却能正常 clone。原因管道使用的服务连接权限不够或者 PAT 过期。Git 类仓库的凭据存在「服务连接」里新建的个人访问令牌默认可能只勾了代码读取权限没有勾仓库状态等权限。解决进入服务连接重新验证错的话重新生成 PAT 并更新连接如果仓库在另一个组织下还要确认连接的范围包含那个组织的访问权限。完成后先去服务连接页点一次「验证」再重跑管道。5.4 变量组里的 Secret 取出来是空的现象密钥放在变量组里任务里用$(mySecret)引用日志输出***甚至直接是空字符串。原因YAML 管道必须在variables里显式声明要引用的变量组可能默认的 secret 为了安全在条件表达式里无法参与比较。解决在管道顶部声明变量组例如variables: - group: 我的变量组声明后再用$(mySecret)引用。不要在condition里直接比较 secret 值Azure Pipelines 会把它禁用这是刻意设计的保护机制不是 bug。5.5 自托管代理显示 Online接任务却失败现象代理池列表里状态明明是 Online但一接任务就握手失败或报连接错误。原因最常见的是代理的注册凭据失效比如当初配置时用的 PAT 已过期或者代理版本太旧和服务端通信协议不匹配。解决先看代理机器上run.sh的日志有没有认证错误有就重新执行一次config.sh并输入新 PAT如果代理版本太旧到代理目录执行./config.sh remove移除旧注册解压新版本代理包重新注册一遍。注册新的实例时尽量用不同的 agent 名称以免旧的离线实例影响判断。6. 快速定位30 分钟理清一个管道故障的排查顺序最后分享一套我每次排查管道故障都会固化的顺序不管报错长什么样先按这个流程走一遍大部分问题都能在半小时内定位。第一步先看运行摘要页面里失败的那个任务点进日志搜索##[error]前缀的行。这是 Azure Pipelines 标记错误的标准格式搜到它就等于找到了任务失败的第一现场。很多报错被前面的冗长输出挡住直接搜这个前缀能跳过大量干扰。第二步打开调试模式。YAML 管道里加一个变量就能看到详细诊断variables: system.debug: true经典发布管道则在发布管道的变量区域添加同名变量值为 true。开启后再跑一次失败的任务日志里会出现大量##[debug]行包括每一步任务的传参、环境变量、代理与服务的请求响应。调试模式下信息量很大但它在定位“任务为什么在这个环境里失败”时不可替代。定位完记得关掉避免日志膨胀和敏感信息泄露。第三步判断故障属于哪一层。我常用下面这张表来快速分流报错片段故障层优先排查No agent found in pool代理与额度池名、代理在线状态、并行分钟数mapping values are not allowedYAML 解析模块缩进、列表项对齐Failed to get access token服务连接服务主体凭据、RBAC 角色Authentication failed代码仓库连接服务连接权限、PAT 有效期任务日志只有##[error]且输出极短运行时/调试开启 system.debug 后重跑第四步做最小复现。把出问题的管道复制一份删掉一半步骤留一个空 job 和一个失败任务先确认代理、服务连接这些基础设施是好的再逐步加步骤观察哪一步引入问题。这个方法看起来很笨但比对着完整日志猜快得多。这四步走完大部分故障的场景都能定位到具体章节去翻细节。从那以后我每次新建管道都会强制走一遍这套顺序——看日志、开 debug、对表、做最小复现尤其是system.debug这个开关比反复点重试有用得多。完整的排查对照表和命令集都整理在这份 PDF 手册里遇到本文没覆盖的报错时翻一遍目录会省很多时间。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
