企业官网建设流程全解析

简介：这是一份 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 与 dependencies：YAML 如何被解析成一张执行图

把管道理解成 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_test，unit_test成功后调度package，Build全部结束后才允许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 时有两个阶段：先是编译期解析，做 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: - main

trigger是 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-version=7.0"

返回的 records 数组里，每个节点对应一个 stage、job 或 step，附带result、startTime、finishTime、父节点引用。把这份数据拉下来看，你能精确知道哪一层在等哪一层、哪个 step 耗时最长、哪个 job 被跳过以及被谁跳过。这比在网页上翻日志可靠得多。

从那以后，我每次改完管道，都强制自己走一遍「编译期预览 → 手动触发最小试运行 → timeline 对比」的循环：先在 YAML 编辑器里看解析结果有没有报错，再手动触发一次跑通最小路径，最后拉 timeline 确认依赖图和预期一致。这套流程帮我挡掉了绝大多数「拍脑袋改配置」的返工。希望帮到你。

本文还有配套的精品资源，点击获取