简介这是一份 Azure Pipelines 官方文档的中文整理手册面向需要落地持续集成与持续交付的 DevOps 工程师、开发与运维人员解决从零创建管道到多环境部署的常见问题。内容覆盖经典发布管道、YAML 架构、代理条件、表达式、环境、作业、阶段、任务、模板与触发器并包含 GitHub、Bitbucket、Subversion 等仓库集成以及部署到 Azure Kubernetes Service、Azure SQL 数据库、Key Vault 等实操指南。对于持续测试还整理了 Selenium UI 测试、代码覆盖率、测试结果分析等模块并给出代理池、部署组、服务连接和保留策略等资源管理方法。压缩包为单份 PDF 文档大小 106.6MB系统性强、目录清晰适合作为日常查手册在用。目前已有 412 人学习/下载对想快速掌握 Azure Pipelines 全貌的团队来说是一份可随时查阅的中文参考资料。1. 一次代码推送背后为什么 Azure Pipelines 像调度器多过像 CI 脚本把代码推到远端仓库几秒后你看到一条流水线被自动拉起编译、跑测试、打包、发布。表面上看Azure Pipelines 做的是「持续集成和持续交付」这件事——抓取代码、执行脚本、上报结果。但如果把它拆开看你会发现真正有价值的不是那几条 script 命令而是那套决定「什么该跑、什么时候跑、在哪里跑、跑失败后怎么处理」的调度内核。它本质上是一个事件驱动的声明式执行引擎你提交一份 azure-pipelines.yml平台把它解析成一张有向无环图再分派给具体的代理去执行。搞懂这层机制你才能解释为什么 job 会并行、为什么测试没跑部署就报错、为什么换台机器结果就变了——这正是值得往下拆的原因。2. 执行内核阶段-作业-步骤三层模型以及管道为什么不是「脚本合集」2.1 三层模型stage、job、step 各自约束了什么很多人第一次写 YAML 管道只是把本地 shell 步骤一行行挪过来结果发现「跑的顺序和我预期不一样」。原因很简单你还在用脚本思维写管道而平台把执行语义强加成了三层结构——一个管道由一个或多个 stage 组成每个 stage 包含一个或多个 job每个 job 包含一个或多个 step。step 是最小执行单元job 是分配粒度一个 job 完整地跑在同一个代理上stage 是组织和门禁粒度。这三层不是文档上的漂亮分层而是调度器做决策的三个层次。看一个最小例子stages: - stage: Build jobs: - job: compile_and_test pool: vmImage: ubuntu-latest steps: - script: npm ci - script: npm run lint - script: npm test这段 YAML 被解析后三个 step 会依次在同一个代理上执行任意一个失败后续 step 默认不再运行。这是第一个容易被忽略的约束job 内的 step 是严格串行的失败即停止除非你显式写continueOnError: true。job 是「调度单元」这意味着整个 job 的所有 step 共享同一个文件系统和环境变量但 job 与 job 之间没有任何共享状态。想让两个 job 之间传递构建产物必须走 artifact 或变量而不是靠文件拷贝。stage 则是最上层的门禁单位它可以插入审批、可以整体跳过、可以设置独立的超时时间。所以说这三层模型本质上是把「自由脚本」改造成了「有结构的执行单元」每一层都有对应的控制原语condition、timeoutInMinutes、retry 等等。2.2 dependsOn 与 dependenciesYAML 如何被解析成一张执行图把管道理解成 DAG是解释一切调度行为的起点。平台读取 YAML 后并不会按文件从上到下机械执行而是先建立一张依赖图再做拓扑排序最后把可并行的节点分发给不同代理。默认情况下同一 stage 内的 job 是并行调度的不同 stage 之间默认串行依赖——前一个 stage 全部成功后一个 stage 才会开始。但你可以用dependsOn显式改写依赖关系甚至用dependsOn: []声明「我不依赖任何人」从而让多个 stage 并行跑。看一个带依赖的示例stages: - stage: Build jobs: - job: compile steps: - script: npm run build - job: unit_test dependsOn: compile steps: - script: npm test - job: package dependsOn: unit_test steps: - script: npm pack - stage: Deploy dependsOn: Build jobs: - job: push_image steps: - script: docker push $(imageName)这里compile、unit_test、package在声明上形成一条链Deploystage 依赖整个Buildstage。执行时平台先把整张图展开compile成功后调度unit_testunit_test成功后调度packageBuild全部结束后才允许Deploy开始。凡是没被依赖的 job都会在资源允许时并行被拉起。理解这张图还有一个实际用处排错时看到某个 job 的状态是 Skipped不是它坏了而是它在图上的前置节点失败了。点开 Skipped 的 job最常见的提示是 Not started because a previous job failed.。这行字就是依赖图在运行结果上的投影。一个 job 失败后所有直接或间接依赖它的下游节点都会被取消或跳过这是 DAG 调度的标准行为不是随机故障。2.3 从经典编辑器到 YAML为什么「管道即代码」的代价是值得的经典编辑器时代管道是在 Web UI 里拖拽出来的底层其实也存成 JSON 定义。UI 让初学者友好代价是管道定义散落在服务端不可评审、不可版本化、不可 diff——时间一长就变成只有某个人敢碰的「黑匣子」。YAML 管道把定义文件放回代码仓库于是每次改动都能走分支策略和 PR 评审。你改管道就像改代码一样留下审计痕迹。这个转变的关键词是「版本化」YAML 和代码一起进仓库哪个分支用什么管道定义由该分支上的文件内容决定。经典编辑器做不到这一点——它的定义是全局的换分支还是同一份配置。维度YAML 管道经典编辑器定义位置仓库内 azure-pipelines.ymlWeb UI/服务端存储变更评审走 PR、分支策略手动操作难以留痕复用方式模板 参数任务组触发器与文件同版本配置在服务端平台读 YAML 时有两个阶段先是编译期解析做 schema 校验、模板展开、变量替换再是运行期调度。这也是 YAML 管道最需要学习成本的环节——你在文件里写的某些语法根本不会活到运行期它在解析阶段就被替换掉了。这个点留到第 4 章展开。现在只需要记住YAML 管道不是脚本解释器而是一套有编译期的声明式配置系统。3. 代理体系管道代码在哪儿执行、作业如何与代理「配对」3.1 平台托管代理为什么每次拿到的环境都是「干净」的YAML 里写vmImage: ubuntu-latest这是告诉调度器这个 job 要跑在平台托管的代理上。平台托管代理的本质是预置好镜像的虚拟机——每次接收 job 时分配一台全新 VM跑完即销毁。你不需要关心操作系统补丁、不需要维护构建机代价是你对运行环境几乎没有定制权。这种「用完即焚」的模型带来一个关键特性隔离。上一个 job 留下的进程、环境变量、文件系统垃圾不会泄漏到你的 job 里。这也是为什么同样的 YAML 在平台托管代理上复现性远高于自托管代理。缓存是唯一的例外平台提供了cache任务把依赖目录保存起来供后续运行复用但缓存的命中与否不影响隔离保证——它只是把下载好的依赖塞回工作目录而已。平台托管代理也有明确的物理边界预装镜像里有什么工具、什么版本由平台维护清单决定。如果你需要特定 SDK 或者私有插件就得切到自托管。这里有个常用的判断标准能用托管代理解决的不要自建代理需要固定 IP、内网资源、自定义工具链的才值得自托管。3.2 自托管代理注册、代理池与常驻进程自托管代理并不是把你自己的笔记本电脑「映射」到云上而是在一台你能长期控制的机器上跑一个代理服务。这个服务周期性地向 Azure DevOps 服务端轮询「有没有分给我的 job」有就领取没有就继续待命。注册是第一步。以下命令在一台 Linux 机器上交互式地完成代理注册# 在目标机器上解压代理包后执行注册 ./config.sh \ --url https://dev.azure.com/{组织}/ \ --pat 注册用的一次性 PAT \ --pool Linux-Pool \ --agent agent-01 \ --work _work \ --replace参数含义--url指向组织地址--pool指定代理池池是代理的逻辑分组--agent给这台代理命名--work设置工作目录所有 job 的源码和产物都落在这里--replace表示如果同名代理已存在则覆盖。--pat是注册用的个人访问令牌注意它只在握手阶段使用注册完成后代理会拿到服务端下发的长期凭据并写入.credentials文件——这个文件丢了代理就得重新注册。注册完成后启动./run.sh代理就开始常驻。它本质上是一个轮询守护进程不是一次性的构建命令。理解这一点很重要如果你想省资源、按需启停代理就必须自己处理它和调度器之间的心跳与排队关系。代理在离线状态下池里配给它的 job 会一直停在队列里等待。3.3 capabilities 与 demands作业和代理是怎么「配对」的自托管代理有个平台托管代理没有的概念capabilities。代理启动时会采集自身环境把「操作系统」「已安装的 JDK 版本」「自定义标签」等上报为键值对。对应地job 可以声明 demands也就是「我要跑在满足什么条件的代理上」。调度器匹配 job 与代理时会把 job 的 demands 逐个与代理的 capabilities 比对键存在且值相等才算匹配成功。这就是排队的底层原因——你的 job 看起来没坏但池里所有代理都不满足 demands于是只能干等。jobs: - job: build_on_linux pool: name: Linux-Pool demands: - agent.os -equals Linux - java -equals 17这段声明要求代理池Linux-Pool里选一台操作系统是 Linux、预装 Java 17 的机器。如果池里有三台代理只有一台装了 Java 17那么并发高时另外两台空闲你的 job 也会在队列里排队。排查这类问题先看 job 状态里的「Waiting for an agent」阶段是否超时再看池里代理的 capabilities 列表有没有你要的那个值。自托管代理的工作目录结构也常让人困惑。_work下按 job 编号生成文件夹源码放在s构建输出在b临时目录在a。同一个代理跑多个 job 时这些目录会被复用——这种复用既是自托管高效的来源也是「上一份作业污染下一份」的根源。第 5 章的避坑里会专门讲这个。4. 触发器、条件与表达式事件驱动的声明式执行引擎4.1 触发器从代码事件到运行实例的映射管道不是凭空调度自己的它必须等到一个事件。最常见的触发器是 CI 触发——代码 push 到仓库后服务端通过 webhook 或轮询感知变化取出该分支上的 azure-pipelines.yml解析后创建一次运行。这里的关键点触发器本身也是 YAML 的一部分意味着不同分支可以有不同的触发规则。trigger: branches: include: - main - releases/* exclude: - releases/old-* pr: branches: include: - main schedules: - cron: 0 2 * * * displayName: Nightly build branches: include: - maintrigger是 CI 触发pr是拉取请求验证触发schedules是定时触发。它们对应不同的事件源push 事件验证已提交的代码PR 事件验证待合并的代码——这两个是不同的运行类型运行 UI 上看到的前缀和图标都不一样。搞混了它们就会出现「PR 验证一直不跑但 push 正常」的困惑。还有一个容易踩的默认行为如果 YAML 里根本没写trigger块默认策略是「所有分支的 push 都触发」。而一旦你写出了trigger规则就变成精确匹配——分支不在 include 列表里就不会触发。很多人把 trigger 从 main 分支的 模板里带过来导致 feature 分支推了代码毫无反应原因就是默认行为被显式配置覆盖了。4.2 表达式与条件$()、${{ }}、condition 的求值时机这是整个 Azure Pipelines 机制里最容易翻车的部分。平台对 YAML 的处理分成两个时间窗口编译期和运行期。${{ }}语法在编译期被展开$()语法在运行期由代理展开condition 表达式则在调度阶段由服务端求值。三者看起来都是在「取值」实际发生在完全不同的时刻。variables: isMain: ${{ eq(variables[Build.SourceBranch], refs/heads/main) }} jobs: - job: echo_examples variables: envFromVarGroup: ${{ variables.envName }} steps: - script: echo 编译期值: $(envFromVarGroup) - script: echo 运行期值: $(envName) condition: and(succeeded(), eq(variables[envName], dev))${{ }}在编译期展开时能访问的只有「编译期可用」的信息YAML 里定义的参数、内置的variables[Build.SourceBranch]这类静态值。你没法在${{ }}里读取变量组的值——变量组是运行期才注入的。而 condition 表达式里不能写$(envName)因为服务端解析器不认识宏语法它会把$(envName)当成普通字符串去比较。condition 里取变量必须用variables[envName]这种函数式写法。理解了求值时机很多玄学就消失了。比如你发现某个 step 明明应该被跳过但它还是跑了——多半是 condition 里用了${{ }}把编译期的值写死成了某个字符串而这个字符串在运行期已经不是真实值了。再比如你看到$(var)在 echo 里正常输出但放在 job 的displayName里却显示为字面量$(var)——因为显示名在编译期格式化宏还没来得及展开。这类问题没有统一的排查口诀只能靠「先判断这个字段在哪个阶段被消费」这个思路去定位。4.3 模板与变量编译期宏展开、运行期变量注入模板是 YAML 管道复用代码的主要手段。它的本质是编译期的「文件包含」把另一个 YAML 文件的内容按参数替换后内联进当前文件然后再做整体解析。这跟编程语言里的函数调用有根本区别——模板没有运行时栈它是纯粹的文本级展开。# templates/ci-steps.yml parameters: - name: buildCommand type: string default: npm run build steps: - script: ${{ parameters.buildCommand }} displayName: Execute build# azure-pipelines.yml 中引用 steps: - template: templates/ci-steps.yml parameters: buildCommand: npm run build:prod模板展开发生在编译期所以parameters必须是编译期能确定的常量或表达式你不能在某个 step 运行到一半时「传入」参数。这也解释了一个常见困惑为什么模板里的参数不能是另一个 job 的输出变量因为 job 的输出要到运行期才产生而模板在编译期就已经被拆光了。变量系统同样分成两个家族。宏变量macro variables是编译期可访问的定义在 YAML 顶层运行时变量runtime variables由变量组、任务输出或发布阶段的运行时注入。变量组的读取发生在 job 开始前——调度器先把变量组的键值对拉下来再注入到代理环境变量里。所以变量组里的值在 condition 里可以读在${{ }}里不能读。作用域优先级大致是job 级变量覆盖 stage 级stage 级覆盖管道级管道级再覆盖变量组。把握住「编译期只能看静态定义运行期才能看注入值」这条线变量系统就不再有秘密。5. 避坑与排查表达式求值、代理残留、触发器失效的定位思路5.1 condition 里写$(var)永远不生效现象把condition: eq(variables[envName], dev)改写成condition: eq($(envName), dev)之后这个 step 要么永远按条件执行要么永远跳过跟你环境变量实际是什么完全无关。原因condition 表达式由服务端调度器求值解析器只认variables[x]这类表达式函数语法不认代理端的$(var)宏。它把$(envName)当作普通字符串字面量比较结果当然不会随环境变化。解决condition 里取变量一律走variables[x]宏语法只留给 step 的脚本正文。遇到「我想在条件里比较变量组的值」正确写法就是eq(variables[envName], dev)不要套宏。这条规则没有例外。5.2 自托管代理第二次运行就失败工作目录残留现象同一个自托管代理上首次构建顺利通过第二次运行时报文件冲突、依赖重复安装、或者产物里混进旧文件。典型的「在我机器上是好的」翻车现场。原因job 默认不会清理工作目录。_work是持久磁盘上一次 job 拉的源码、node_modules、编译中间文件全部还躺在那里。脚本在「不干净的目录」上叠加执行碰撞是必然的。解决在 job 或阶段级别声明清理策略。workspace: clean: all会删掉整个工作目录等价于把托管代理的一次性隔离搬回自托管环境只想重置源码不碰依赖时用clean: resources。如果不想每次全量清理至少让构建产物写到独立输出目录避免与旧产物混在一起。5.3 推送了代码但管道没触发现象git push 成功流水线运行列表里却没有任何新记录。手动点「Run pipeline」可以触发说明定义本身没坏但自动触发失灵。原因最常见的两个——一是该分支不在 trigger 的 include 列表里二是分支的 YAML 里写了 trigger覆盖了「无 trigger 则全分支触发」的默认行为。另一个隐蔽因素仓库与平台之间的 webhook 断连这种往往伴随持续一段时间的静默。解决先手动触发确认管道定义可用再看当前分支是否匹配 trigger 的 include/exclude 规则最后检查仓库服务连接或 webhook 状态。路径过滤也是同类问题——paths.include限定了只有改动某些目录才触发你以为推了代码就该跑但规则只看路径变更。5.4 构建全绿但部署失败服务连接过期现象CI 阶段全部成功Deploy 阶段却报 401、403或者提示找不到服务端点。看起来很像权限问题但同一套配置上周还能跑。原因服务连接本质上是一组存储在项目里的远端凭据比如一个服务主体及其密钥。凭据过期后UI 上不会自动标红只有真正发起调用的部署作业会暴露问题。很多团队把这个当「玄学故障」其实只是没做凭据轮换。解决进入项目的服务连接管理页面点「验证」检查连接是否可用确认服务主体对目标资源仍有正确的角色权限再核对 YAML 里引用的连接名与实际定义完全一致——项目迁移后旧连接名失效也是高发原因。5.5 排查手法打开系统诊断别只盯着「失败」两个字现象失败时 UI 只显示一条命令输出看不出环境准备、文件映射、缓存命中这类关键信息或者你怀疑 job 被分到了错误的代理但页面上能确认的信息太少。原因默认日志是裁剪过的诊断信息被隐藏自托管代理的完整日志在代理机本地不在网页上。解决在管道变量里加system.debug: true或用「调试模式」重新运行一次。这时每个 step 会额外输出环境初始化、任务分派、依赖下载的详细信息。同时把 job 面板里的「Agent name」记下来确认它跑在哪台机器上——很多自托管问题在看清代理归属后立刻明朗。排查的通用路径是先确认 job 被分配到哪个代理再确认依赖图上的前置节点状态最后才看脚本输出。前两步能过滤掉大多数误判。6. 设计取舍的延伸约束换可观测性以及如何验证你的管道如果只从「能不能跑」的角度看YAML 管道里写的任何逻辑都能用一段 shell 脚本实现。于是真正的设计问题浮现了为什么平台要把自由的脚本改造成「stage-job-step」这种僵硬的三层结构答案是约束换可观测性。自由脚本可以任意跳转、随意定义函数但平台因此无法在失败后安全重试、无法判断哪些节点可并行、无法在 stage 之间插入审批门禁。三层模型的每个层级平台都能记录状态、统计耗时、设置超时与重试策略。换句话说结构化的代价换来的是整个执行过程可以被枚举、被查询、被审计。artifact 是另一个同样的取舍stage 与 stage 之间禁止共享文件系统强制用发布工件传递产物。这个限制看起来很烦但它保证了每个 job 可以独立重跑、可以换代理执行、可以回溯「某个产物到底由哪次构建产生」。「一切皆工件」的统一抽象是流水线可复现性的基石。验证管道设计是否合理不要靠肉眼盯 UI。平台暴露了 timeline 接口它返回一次运行的完整调度记录curl -u :$TOKEN \ https://dev.azure.com/{组织}/{项目}/_apis/build/builds/{runId}/timeline?api-version7.0返回的 records 数组里每个节点对应一个 stage、job 或 step附带result、startTime、finishTime、父节点引用。把这份数据拉下来看你能精确知道哪一层在等哪一层、哪个 step 耗时最长、哪个 job 被跳过以及被谁跳过。这比在网页上翻日志可靠得多。从那以后我每次改完管道都强制自己走一遍「编译期预览 → 手动触发最小试运行 → timeline 对比」的循环先在 YAML 编辑器里看解析结果有没有报错再手动触发一次跑通最小路径最后拉 timeline 确认依赖图和预期一致。这套流程帮我挡掉了绝大多数「拍脑袋改配置」的返工。希望帮到你。本文还有配套的精品资源点击获取