简介：Azure DevOps Pipelines 官方文档离线整理版，适合需要系统搭建持续集成/持续交付体系的开发、运维与 DevOps 工程师。全书围绕 CI/CD 展开，涵盖从免费注册、创建第一个管道到自定义 YAML 管道的完整流程，并对代理、条件、表达式、环境、作业、运行时参数、阶段、任务、模板、触发器九个核心概念逐一说明；实操部分包括容器镜像、.NET Core、Java、JavaScript、Python、Android、AKS 等场景，也覆盖与 GitHub、Azure Repos、Bitbucket、Subversion 等代码仓库的集成。整包为单个 PDF 文件，大小约 106.6MB，便于离线查阅和团队分享。该资源已有 412 人学习下载；除快速入门教程外，还提供生成多分支、部署到 Azure、配置自托管代理、UI 测试与代码覆盖率、Slack/Teams 集成、发布 NuGet/npm/Python 包等操作指南，可作为日常排错与持续交付落地的参考手册。
1. 第一次跑 Pipeline 就翻车：从 YAML 加载失败说起
第一次在 Azure DevOps 里配置 Pipeline 的人，多半都撞过这种场面：代码刚推上去，管道立刻红了，展开日志却只有一行An error occurred while loading the YAML build pipeline. Object reference not set to an instance of an object.。没有行号，没有文件定位，连哪个任务挂了都看不出来。我最早给模拟项目X搭 Azure DevOps Pipeline 持续集成（CI）时，在这行报错上耗了一下午，最后才发现是模板参数少了个冒号，YAML 在服务端被解析成了空对象。后来进入持续交付（CD）阶段，又在代理池、服务连接、测试报告上踩了一串坑。这篇笔记不铺开讲概念，直接按报错现象拆根因和解决步骤，新手能照着命令操作，熟手可以跳过现象直接看排查思路。
2. YAML 管道加载失败：语法、触发器与变量的定位清单
YAML 管道是现在新建 Azure Pipelines 的默认方式，但 YAML 本身就是最容易翻车的环节。它允许缩进自由、引号可省、类型自动推断，这些“灵活性”在图形界面的管道编辑器里反而成了负担。我在实际项目里遇到的大部分 YAML 加载失败，都可以归到三类：语法解析错误、顶层键位置错误、变量与运行参数的取值混淆。下面按这三个方向逐个说。
2.1 报错：YAML 加载失败，日志却不给行号
现象是在 Azure DevOps 的管道页面看到红色失败状态，点击“查看日志”只有An error occurred while loading the YAML build pipeline，后面跟着一个空引用异常。这类报错最气人的地方是服务端不会告诉你到底哪一行出了问题。出现这个情况通常有两种可能：YAML 里有空值，例如trigger:或variables:后面没有内容；或者使用了 Azure Pipelines 不认识的键，导致解析器在构造对象时抛出了空引用。
我一般会先在本地做一次语法校验，用 Python 的 PyYAML 快速扫一遍：
python -c "import yaml,sys; yaml.safe_load(open('azure-pipelines.yml')); print('YAML OK')"这段命令用yaml.safe_load读取本地的azure-pipelines.yml，如果文件存在缩进错误、制表符混用、括号不闭合，会直接抛出ScannerError并给出行号。注意它只能验证 YAML 语法本身，不能验证 Azure Pipelines 的 Schema，所以本地通过不等于平台能通过。本地校验通过后，我还会把内容粘到管道编辑器里，点一下“验证”按钮，这时候 Azure DevOps 会给出更接近真正行号的提示，两个结果互相印证，基本能定位到出错的那一行。
提示：如果项目使用 Azure Repos，修改后的
azure-pipelines.yml必须先提交到分支，服务端才按新内容解析。不要只看本地文件。
2.2 报错：代码推上去管道却不触发
这个问题的现象是推送代码后没有任何新的 Run，管道页面安静得像是被暂停了。最常见的原因是trigger写错了位置或写错了格式。trigger是 YAML 顶层键，必须放在jobs之前，而且它的值是对象，不能直接写分支名。错误写法经常是这样的：
# 错误：trigger 写成了字符串，且放在 jobs 之后 jobs: - job: build steps: - script: echo build trigger: main这段 YAML 里trigger虽然语法合法，但 Azure Pipelines 不会把它当作顶层触发器，导致管道按默认行为运行，也就是每次推送都跑，而不是只跑 main 分支。更常见的是写成trigger: main，这会被解析成一个字符串，不是分支过滤器。正确写法应该是：
trigger: branches: include: - main - release/*include下面的列表决定哪些分支的推送会触发管道；release/*是通配符，表示所有以release/开头的分支。如果希望拉取请求（PR）也触发验证，需要另外配置pull_request触发器，它的结构和trigger一样，也是branches.include。触发器是否生效，可以在管道页面的“运行”按钮旁看到当前分支对应的触发器状态，点进去会列出哪些分支匹配、哪些被排除。
2.3 报错：运行参数填了值，脚本里取到的是空
这类问题隐蔽在变量解析的时机上。Azure Pipelines 里有两种引用方式：$(variable)是运行时变量替换，由代理在执行任务前替换；${{ parameters.name }}是模板展开期替换，在 YAML 被解析阶段就完成了。很多人把两者混用，导致在脚本里用$(environment)去取运行参数environment，结果拿到空字符串，或者更糟，拿到字面量${{ parameters.environment }}。
一个能同时用清楚的示例：
parameters: - name: environment values: - dev - test - prod default: dev variables: envName: ${{ parameters.environment }} steps: - script: | echo "runtime variable: $(envName)" echo "template expression: ${{ parameters.environment }}"parameters.environment定义在parameters块里，用户运行管道时可以下拉选择；variables.envName使用${{ }}在解析期把参数值直接写死到变量里，所以脚本里$(envName)能拿到值。而${{ parameters.environment }}在步骤里也会被替换成具体值。把这两种方式分开理解后，再遇到空值问题，优先检查是不是把parameters当成了普通变量。
2.4 常见问题：本地通过，上传后却报非法字符
还有一种情况是本地 VSCode 怎么校验都通过，上传到 Azure DevOps 后却报mapping values are not allowed或found character that cannot start any token。根因通常是 Windows 下保存的 YAML 带了 UTF-8 BOM，或者行尾是 CRLF。Azure Pipelines 的解析器对 BOM 处理有时会抽风，尤其是在模板文件里。解决办法是在.gitattributes里统一文本文件的换行符和编码：
*.yml text eol=lf *.yaml text eol=lf这段规则让 Git 在检出文件时强制把换行符转为 LF，从源头避免 CRLF 混入。保存文件时还要注意编码，VSCode 右下角选择“UTF-8（无 BOM）”。这类问题属于典型的“玄学报错”，因为日志里给出的字符位置和真实问题完全对不上，经历过一次之后，我每次改完 YAML 都会顺手看一眼文件底部的编码信息。
3. 代理池空转：No agent found 与自托管代理离线的排障顺序
YAML 能通过验证只是第一步，管道跑起来之后，另一个高发故障是任务一直排队，最后失败时日志里只有一句No agent found in pool。这句话背后可能是代理池真的空着，也可能代理在线但能力不匹配，或者托管代理并行额度用完了。定位顺序应该从最外层往内部查：先确认池里有没有可用代理，再确认代理是否在线，最后确认代理能力是否满足作业要求。
3.1 报错：作业等待很久，提示找不到代理
现象是任务卡在“已排队”状态，几十分钟后失败，日志显示类似This request is waiting for a runner to be available。如果用的是 Azure 托管代理，先检查组织的并行作业额度是否用完。Azure DevOps 对专用项目每月提供一定量免费并行分钟数，额度耗尽后作业只能排队。可以在“项目设置 → Pipelines → Parallel jobs”里查看剩余额度。
如果额度充足，就要看代理池本身。在“项目设置 → Agent pools”里点开对应池，看“代理”页签下有没有显示为绿色的在线代理。如果是空的，说明这个池没人注册代理。解决办法是把作业切换回 Azure 托管代理，或者注册一个自托管代理。注册自托管代理的命令在 Linux 上通常是：
./config.sh --pool "Default" --agent "my-agent" --url "https://dev.azure.com/你的组织" --work "agent-work" --replace--pool指定代理池名称，--agent是代理在池里显示的名称，--url是 Azure DevOps 组织地址，--work是代理工作目录，--replace表示允许替换同名代理。执行时会提示输入 PAT（个人访问令牌），这个令牌必须有“代理池读取/管理”和“部署组读取/管理”权限。注册完成后，需要运行./run.sh或注册成服务，代理才会保持在线。
3.2 报错：自托管代理启动后立刻离线
注册成功后并不代表一劳永逸。常见情况是代理运行一段时间后自动掉线，重新./run.sh又能跑，过一会儿又掉。原因通常是代理进程没有作为后台服务运行，终端一关代理就退出。在 Linux 下，安装目录里有现成的脚本：
sudo ./svc.sh install sudo ./svc.sh startsvc.sh install会把代理注册成 systemd 服务，start启动它。之后就算退出终端，代理也会保持在线。如果机器需要走 HTTP 代理才能访问外网，还要在代理安装目录的.env文件里设置：
https_proxy=http://proxy.example:8080 http_proxy=http://proxy.example:8080注意这个设置对代理本身生效，它影响代理与 Azure DevOps 服务端的通信，不影响管道任务里应用访问外部网络。
3.3 报错：代理在线，但作业就是不匹配
有时代理池页面显示代理在线，端口也是绿色，但作业依然卡住。这就要看需求（demands）是否匹配。YAML 作业里可以声明需求，例如：
pool: name: Default demands: - Maven - JDKdemands列表中的每一项都是代理必须具备的能力（capability）。自托管代理注册时，会自动收集机器上的环境变量和安装的工具，形成一份能力列表，在代理池的代理详情里可以看到。如果代理机器上没有安装 Maven，它就不满足这个作业，系统不会把作业分配给它。解决方式有两种：把缺少的工具装到代理机器上，然后重启代理服务让能力列表刷新；或者移除作业里不必要的demands声明。使用 Azure 托管代理时，托管代理的能力是官方预置的，很少出现这种不匹配，所以问题多发生在自托管场景。
3.4 注意：不要手动修改代理配置文件
代理目录下的.agent、.credentials文件记录了注册信息和凭据，我曾经因为想改动 agent 名称，直接去编辑.agent文件，结果代理彻底失联，只能重新注册。正确做法是用官方脚本重新配置：
./config.sh remove ./config.sh --pool "Default" --agent "my-agent" --url "https://dev.azure.com/你的组织" --replaceconfig.sh remove会清理旧的注册信息，然后再执行新的注册命令。重新配置时也可以指定新的代理名称，不需要手动改文件。这个操作给“后悔药”留下了一个标准入口，只要 PAT 还在，随时可以重来。
4. 部署到 Azure 失败：服务连接验证不通过时的排查顺序
自托管代理能跑任务之后，下一个容易爆雷的是部署阶段。Azure Pipelines 要部署到 Azure 资源，通常通过服务连接（Service Connection）来认证。服务连接本质上是把 Azure AD 里的服务主体凭据托管到 Azure DevOps，管道任务用这些凭据调用 Azure 资源管理器。问题往往不出在“创建”环节，而是出在“权限边界”上。常见现象是服务连接验证成功，但部署任务依旧报 401、403 或权限不足。
4.1 报错：服务连接验证成功，任务却返回 403
在项目设置里创建好 Azure 资源管理器服务连接后，会有一个“验证”按钮，它能确认服务主体是否能访问 Azure 订阅。但这里有个误区：验证成功只能证明服务主体有效、能获取令牌，不能证明它对目标资源有操作权限。部署任务要往某个资源组写入资源，服务主体必须在那个资源组上有相应的角色分配。我用 Azure CLI 给服务主体授权时习惯用这个命令：
az role assignment create --assignee <appId> --role Contributor --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>"assignee是服务主体的应用 ID，可以在服务连接详情里找到；role是角色名称，部署应用时通常用Contributor，只读场景用Reader；scope限定了权限的作用范围，这里指定到资源组。如果多个环境共用同一个订阅，最好把权限分别分配到每个资源组，而不是给整个订阅的 Contributor，避免部署管道误操作其他资源。
4.2 报错：从 Key Vault 读取机密提示权限不足
部署过程中经常要读取 Azure Key Vault 里的连接字符串、证书或密码。管道任务已经能访问订阅，但拉取 Key Vault 机密时还是会报The user, group or application does not have secrets get permission。这是因为 Key Vault 的权限体系独立于 ARM 权限，即便服务主体在订阅层面有 Contributor，也要单独在 Key Vault 的访问策略中授权。
解决方式有两种：如果是旧版访问策略模式，进入 Key Vault 的“访问策略”，添加服务主体，并勾选“获取”（Get）权限；如果是 RBAC 模式，给服务主体分配“Key Vault Secrets User”角色。推荐用 RBAC 模式，因为可以在 Azure DevOps 服务连接的界面直接查看到底是哪个服务主体，再回到 Azure 门户按名称授权。
4.3 报错：经典发布管道的部署组代理令牌过期
还在使用经典发布管道时，部署组（Deployment Group）是另一种部署目标。部署组里的每台机器都装了一个代理，它和服务器之间有一个注册令牌，令牌过期会导致目标机器离线。现象是发布任务目标状态显示“无法访问”，但机器本身网络正常。
解决办法是在目标机器上重新配置部署组代理。Windows 上进入代理目录，执行：
.\config.cmd --configure --pipelineswindows-service执行后会要求重新输入部署组令牌，令牌可以从发布管道的“部署组”页面复制。配置完成后重启代理服务，目标机器就会重新上线。为了避免频繁过期，可以在部署组的注册信息里查看令牌有效期，提前做替换。
4.4 排查步骤：在调试模式下运行发布
服务连接的权限问题，靠肉眼观察日志很难定位，因为普通日志只显示 HTTP 状态码。Azure Pipelines 提供了一个隐藏入口：发布运行界面的“运行”按钮旁边有“在调试模式下运行”选项。勾选后会输出更详细的 REST API 调用日志，包括请求的具体 URL、请求头和响应体。这时能看到服务主体在调用哪个资源管理器接口时被拒绝，再回到 Azure 门户检查对应权限。
注意：调试模式会输出敏感信息，包括部分请求头里的认证令牌，不要在公共屏幕上共享调试日志。
我一般会在普通日志显示 403 或 401 时，立刻用调试模式重跑一次，把失败的那次 REST 调用记录下来，再对照服务连接适用的服务主体，这样定位权限错误比盲目在门户里翻角色分配要快很多。
5. 常见问题排错：测试任务与发布任务的隐藏坑
走到测试和发布阶段，很多问题不再表现为“任务红色”，而是表现为“任务绿色但结果缺失”。这类问题更坑，因为在持续集成里，任务退出码为 0 不代表真的成功。下面是三个高发场景，以及对应的踩坑记录。
5.1 报错：测试有失败，但管道仍然显示成功
现象是测试任务里明明有断言失败，管道状态却是绿色。原因是测试命令在被调用时，退出码被外层脚本吞掉了。比如用script写：
set +e dotnet test echo "test done"这个写法里即便dotnet test失败，脚本继续执行echo，最后步骤退出码是 0，管道任务自然认为成功。正确做法是去掉set +e，或者将dotnet test作为脚本的最后一行，让它的退出码直接传递给管道。更稳妥的是直接用 Azure Pipelines 内置的测试任务，例如：
- task: DotNetCoreCLI@2 inputs: command: 'test' arguments: '--configuration Release'DotNetCoreCLI任务会正确捕获dotnet test的退出码，并自动把测试结果发布到管道页面。如果必须用自定义脚本，确保脚本以测试命令结束，或者用bash -e让脚本在任何非零退出码时立即失败。
5.2 报错：覆盖率结果页面是空的
测试跑完后可以生成覆盖率数据，但除非明确把覆盖率文件发布到管道，否则页签里永远不会显示内容。覆盖率结果不是一个隐式行为，需要额外任务处理。我在 YAML 里通常会加一个发布任务：
- task: PublishCodeCoverageResults@1 inputs: codeCoverageTool: 'cobertura' summaryFileLocation: '$(Agent.TempDirectory)/coverage/cobertura.xml'codeCoverageTool指定覆盖率文件格式，常见值有cobertura、jacoco；summaryFileLocation是覆盖率 XML 的相对路径。这个任务只负责上传和展示，实际生成 XML 的工作要在前面的测试任务里完成。对于 .NET 项目，需要在测试命令里加/p:CollectCoverage=true /p:CoverletOutputFormat=cobertura这样的参数。如果只看日志不看页签，很容易误以为覆盖率功能没配置成功。
5.3 报错：NuGet 包发布认证失败
发布包到 Azure Artifacts 时，常见报错是401 Unauthenticated或Unable to load the service index。根因是 NuGet 源没有正确配置凭据。使用内置任务时，先要加一步认证任务：
- task: NuGetAuthenticate@1 inputs: onlyAddExtraCredential: falseNuGetAuthenticate会给当前管道运行注入 Azure Artifacts 的凭据，之后的dotnet nuget push就不再需要手动提供--api-key。如果缺少这一步，命令行里的 NuGet 源请求就带着未授权状态，返回 401。如果是自建 NuGet 私有源，需要检查是否在项目里配置了nuget.config的source，并且认证方式是否被任务支持。
5.4 踩坑记录：三条最容易被忽略的失败模式
第一条：任务里使用continueOnError: true，导致错误被忽略。原因是我当时为了让一个可选脚本失败不阻塞后续流程，给整条任务加了 continueOnError，结果测试失败也被吞掉了。解决方法是只在确实允许失败的步骤加这个属性，并且把condition设置成仅在失败时运行上传测试结果的逻辑。
第二条：自托管代理的时区不对，测试报告时间显示混乱。原因是没有在代理环境变量里设置TZ，导致时间戳全部偏移。解决是在代理的.env文件里加TZ=Asia/Shanghai，然后重启代理服务。
第三条：发布通用的包时，包版本冲突导致409 Conflict。原因是同一个版本号被重复上传。解决是在 YAML 中每次生成版本时使用$(Build.BuildNumber)作为版本号的一部分，保证每次构建版本唯一。
6. 快速定位：把管道黑匣子变成白盒
遇到管道失败，最快的方式不是逐行看 YAML，而是先确定失败发生的层级。我现在的排查习惯是固定的四步：先看失败的是哪个任务，再进日志找退出码，然后按需打开调试模式重跑，最后回到本地用相同命令模拟。这四步能覆盖绝大多数持续集成和持续交付问题。
如果日志不够，可以在 YAML 里显式打开系统调试变量：
variables: system.debug: truesystem.debug为 true 时，所有任务都会输出更详细的执行日志，包括脚本实际执行的命令和每个步骤的耗时。但这个变量会明显增加日志量，我只在定位问题时临时开启，定位完就移除。对于自托管代理，还有一个常被忽略的线索是工作目录。代理的_work文件夹下保留了每个运行的相关文件，默认路径是：
ls -lt _work/1/s # s 是源代码目录如果任务在下载源或生成文件时失败，可以直接看工作目录里有没有生成物，判断是命令问题还是环境问题。从那次 YAML 空引用报错之后，我养成了一个习惯：每次修改azure-pipelines.yml都先本地做一次语法校验，再跑一个只含echo的最小管道验证代理和服务连接，最后才加入真正的构建步骤。这个顺序看起来多花一分钟，实际上能省下半天排查时间。希望你也能在后续的 Pipeline 排错里少绕几个弯，少红几次管道。希望帮到你。
本文还有配套的精品资源，点击获取
