简介Azure Pipelines 操作手册是一份依据官方文档整理的系统性参考 PDF面向需要搭建持续集成、持续交付流程的 DevOps 工程师、开发与运维人员。内容覆盖快速入门、创建第一个管道、自定义管道并深入讲解代理、条件、表达式、环境、作业、运行时参数、阶段、任务、模板与触发器这些核心概念同时包含多分支生成、部署到 Azure SQL 与 AKS、使用 Key Vault 机密、管理代理池与服务连接、设置保留策略等实践可帮助读者从零掌握从代码提交到生产部署的全生命周期。手册还整理了持续测试、UI 测试、代码覆盖率查看、测试结果分析以及 NuGet、npm、Maven、通用包发布和 Slack、Microsoft Teams 集成等进阶内容适合当作日常排障与方案设计参考。资源为单个 PDF 文件共 1 个文件大小 106.6MB目录结构清晰适合离线通读与按需检索当前已有 409 人学习使用。1. 从标题到流水线先弄清 Azure DevOps Pipelines 到底在解决什么问题很多团队把代码仓库接到 Azure DevOps Pipelines 后第一反应是界面上一排陌生设置。其实你只需要记住一点这是一套由 Azure 云托管的 CI/CD 执行环境用 YAML 文件定义一切把代码提交、自动构建、自动测试、部署到目标环境这一整条链路串起来。这篇文章不是官方文档的复述而是我从零接手这类流水线时的记录先跑通最小用例再把变量、环境和部署策略逐个补上最后讲几个真实踩过的坑。适合刚接手配置、维护或改造流水线的开发者也适合想判断这套方案适不适合自己项目的技术负责人。2. 最小流水线跑通从建立仓库到第一份 YAML 可执行文件2.1 经典编辑器与 YAML 该怎么选三个判断条件Azure DevOps Pipelines 的入口通常会给你两条路经典编辑器Classic Editor和 YAML 定义。很多新手看到经典编辑器有可视化表单觉得更友好但我的建议是一律选 YAML除非你只是临时做一次性的构建验证。原因有三个。第一YAML 文件本身就是配置即代码它可以跟着仓库走代码评审时能直接看到流水线改动经典编辑器里的配置分散在网页上改了什么没有历史记录可追溯。第二YAML 支持分支级别的差异不同分支用不同触发条件经典编辑器很难做到。第三也是最重要的一旦流水线出问题YAML 可以直接在本地用 linter 或编辑器插件提前发现缩进和格式错误不用去网页上反复点提交。如果你的团队已有大量经典编辑器配置先别急着迁移。常见做法是保留现状新项目一律走 YAML。等团队对 YAML 的写法熟悉了再把旧的经典编辑器配置慢慢搬过去按阶段迁移而不是一次性推倒重来。2.2 一个最小 YAML 文件签出、还原、构建、发布四次操作我一般会把第一个 YAML 控制在四步签出代码、安装 SDK、还原依赖、构建并发布产物。以 .NET 项目为例最小文件长这样trigger: - main pool: vmImage: ubuntu-latest steps: - task: UseDotNet2 inputs: version: 8.x displayName: 安装 .NET 8 SDK - task: DotNetCoreCLI2 inputs: command: restore projects: **/*.csproj displayName: 还原 NuGet 包 - task: DotNetCoreCLI2 inputs: command: publish publishWebProjects: false arguments: --configuration Release --output $(Build.ArtifactStagingDirectory) displayName: 发布 Release 产物 - task: PublishPipelineArtifact1 inputs: targetPath: $(Build.ArtifactStagingDirectory) artifact: drop displayName: 上传构建产物这段配置里trigger指定了监听main分支的 push意味着每次往主干提交都会触发流水线。pool用的是微软托管的 Ubuntu 镜像默认环境里已经装了不少常用工具但如果项目需要固定某个 SDK 版本必须显式装一次否则镜像升级后你的构建可能突然失败。$(Build.ArtifactStagingDirectory)是系统预定义变量指代一个临时输出目录最后一步把它打包成名为drop的 artifact后续部署阶段直接下载这个产物即可。这里有一个新手上路最容易忽略的点restore和publish都用了DotNetCoreCLI2任务而不是直接写script: dotnet restore。原因是任务内置了日志分组和缓存支持输出更友好排错时能在网页上直接看到是哪一步挂的。2.3 手动触发和 Push 触发两条最常用的运行途径配置好 YAML 后运行方式有两种。第一种是提交 commit 触发只要trigger里写了分支名push 到该分支就会自动排队。第二种是手动触发在 Pipelines 页面选择对应流水线点 Run Pipeline适合临时验证某个修复分支。如果你习惯命令行也可以用 Azure CLI 手动触发az pipelines run \ --organization https://dev.azure.com/某组织 \ --project 某项目 \ --name 最小流水线 \ --branch main这条命令的关键参数是--branch它覆盖了 YAML 里默认的分支适合临时跑一个非触发分支的验证。--name对应流水线名称如果你在网页上建流水线时用的是别的名称这里要改成一致否则会报找不到流水线的错误。第一次跑通后我通常会在浏览器里打开这次运行的日志确认四步都变绿再去改触发逻辑和其他进阶配置。3. 把配置写扎实变量、参数、任务和缓存命中3.1 变量、变量组与参数化一份流水线适配三套环境跑通最小用例之后接下来要面对的必然是环境差异开发、测试、生产用的连接字符串不一样构建参数不一样部署目标也不一样。如果每套环境都复制一份 YAML后期维护就是噩梦。所以要用变量和参数做抽象。变量用variables块定义参数用parameters块定义。两者最大区别是变量在运行期通过$(变量名)引用参数则在编译期通过${{ parameters.参数名 }}替换。参数适合需要手动选择的值变量适合流水线内部传递的值。parameters: - name: environment displayName: 目标环境 type: string default: dev values: - dev - staging - production variables: - group: 公共变量组 - name: buildConfiguration value: Release steps: - script: | echo 当前环境是 ${{ parameters.environment }} echo 构建配置是 $(buildConfiguration) displayName: 打印关键配置变量组在 Azure DevOps 的 Library 页面维护适合存放连接字符串、API Key 这类不常变但需要统一管理的值。需要特别注意的是变量优先级同名时YAML 里显式定义的变量会覆盖变量组里同名的值手动运行流水线时填写的参数会覆盖 YAML 里的默认值。这个优先级很容易记反实际踩坑时经常发现“变量组改了没生效”其实是 YAML 里有个同名变量把它盖住了。3.2 常用任务清单脚本、还原、测试与文件复制除了DotNetCoreCLI2日常用得最多的三类任务是脚本类、测试类和文件复制类。脚本类最常见的写法是Bash3或 PowerShell 任务它们比裸的script关键字多出可控的失败条件。比如我要跑一个自定义脚本- task: Bash3 inputs: targetType: inline script: | npm install npm run lint displayName: 安装依赖并执行 LinttargetType: inline表示脚本直接写在 YAML 里如果脚本文件放在仓库的scripts目录可以把targetType改成filePath并指定filePath: scripts/ci.sh。Bash3比直接在script里写命令多了一个好处任务级别的continueOnError和超时设置是独立的不会影响其他步骤。测试任务的坑在于测试结果文件的路径。以 .NET 为例通常需要先跑测试再把测试结果发布到流水线报告- task: VSTest2 inputs: testSelector: testAssemblies testAssemblyVer2: **/*Tests.dll searchFolder: $(Build.SourcesDirectory) resultsFolder: $(Agent.TempDirectory)/TestResults displayName: 执行单元测试resultsFolder建议放到临时目录而不是源码目录否则测试产生的临时文件会被下次构建捡到造成环境污染。搜索路径带**通配时注意项目文件放在多个子目录的情况路径匹配容易把旧版本的程序集也包含进来。3.3 发布与下载构建产物Pipeline Artifact 的完整闭环构建产物是连接构建阶段和部署阶段的桥梁。很多人只在构建阶段上传了 artifact却不知道后续阶段怎么拉下来导致部署时找不到文件。这就需要用DownloadPipelineArtifact2- task: DownloadPipelineArtifact2 inputs: source: current artifact: drop path: $(Build.SourcesDirectory)/drop displayName: 下载构建产物这个任务和PublishPipelineArtifact1是配套的。artifact参数必须和上传时写的artifact: drop完全一致否则下载不到文件。path指定了产物解压后放在哪。很多部署任务的输入框并不会自动帮你解压需要先用这个任务把产物放到部署任务指定的目录下。一个容易忽略的细节是下载产物时如果没有指定path默认会放到$(Pipeline.Workspace)下。我在多阶段流水线里习惯显式指定一个目录一方面让日志里能看到下载位置另一方面避免多个阶段共享工作区时互相覆盖。3.4 缓存任务参数命中率和构建耗时的三个关键字段构建时间长了之后缓存是收益最明显的优化。包管理工具的缓存最常用Cache2- task: Cache2 inputs: key: npm | $(Agent.OS) | package-lock.json path: $(npm_config_cache) cacheHitVar: CACHE_RESTORED displayName: 缓存 npm 依赖key是判断缓存是否命中的依据格式上用竖线分开多个字段。$(Agent.OS)保证不同操作系统之间不共用缓存package-lock.json是内容指纹只要依赖没有变化这个文件就保持不变缓存就能命中。如果你不用锁文件而是用package.json那么哪怕只是改了一个不相关的版本范围描述缓存也会失效这是缓存命中率上不去的常见原因。cacheHitVar是一个自定义变量名任务跑完后会变成true或false。在后续步骤里可以用条件语句判断比如命中时跳过安装- script: npm install displayName: 安装依赖 condition: ne(variables.CACHE_RESTORED, true)这样能大幅缩短非首次构建的时间。注意Cache2的path必须指向真实的缓存目录各工具默认缓存路径不同最好先在执行器上跑一次并把路径打印出来否则缓存存了却找不到文件等于白配。4. 从单段升级为多阶段Stage、Job 和 Environment 的协作方式4.1 什么时候必须拆 Stage构建、测试、部署三者边界很多刚接触 YAML 的人会把所有步骤堆在一个steps列表里构建、测试、部署一把梭。前期项目小还好一旦并发分支多了、部署环境复杂了你就会发现同一个工作区被各种产物污染而且构建成功但部署失败时你不得不重新跑整条流水线。这时候就需要把流水线拆成多个stage。每个 stage 是一组逻辑边界明确的 jobstage 之间默认按顺序执行前一个失败后一个就不跑。我习惯的拆法是构建一个 stage测试一个 stage部署每个环境各一个 stage。stages: - stage: Build displayName: 构建 jobs: - job: BuildJob steps: - script: echo 构建产物打包 displayName: 模拟构建 - stage: Test displayName: 自动化测试 dependsOn: Build jobs: - job: TestJob steps: - script: echo 执行测试 displayName: 模拟测试 - stage: Deploy displayName: 部署到生产 dependsOn: Test jobs: - job: DeployJob steps: - script: echo 部署 displayName: 模拟部署dependsOn用来显式声明依赖关系。如果不写默认依赖前一个 stage。当阶段比较多时我建议把dependsOn都写出来这样在网页上查看依赖图时一目了然后续调整顺序也不会误改默认结构。4.2 用 Environment 和审批拦下生产部署生产部署最怕手一抖就点错。Azure DevOps Pipelines 的 Environment 功能就是干这个的它可以关联具体的部署目标还能在部署前加一道人工审批。jobs: - deployment: DeployWebJob displayName: 部署到生产环境 environment: production strategy: runOnce: deploy: steps: - task: AzureWebApp1部署任务用的是deployment关键字而不是普通job这就告诉流水线这是一个部署任务它和 Environment 绑定。environment: production引用的环境需要提前在 Environments 页面创建好审批开关也在这个页面配置。配置后运行到这个 job 时会进入等待状态直到审批人点击批准。我最开始没建 Environment直接在 YAML 里写了environment: production结果发现流水线照着这个名称自动创建了一个环境但没有任何审批策略生产部署处于裸奔状态。正确的做法是先到环境页面建好并配置审批人再回流水线引用不要指望 YAML 能自动把审批也配好。4.3 部署策略三选一runOnce、rolling 和 canary 怎么选runOnce是最简单的策略意思是一次性完成部署失败就停止。适合大多数中小项目。rolling是把部署目标分成几批逐批更新每批成功后再推下一批适合有多台服务器做负载均衡的服务。canary则是先给一小部分流量部署新版本验证通过后再扩展到全量。在资源池足够的前提下rolling的配置形态大致如下strategy: rolling: maxParallel: 2 deploy: steps: - script: echo 部署到该批次maxParallel表示同时部署的实例数它决定了一次更新几台。数量设得越大部署越快但故障爆炸半径也越大。我见过有人把maxParallel设成总实例数结果和runOnce没有区别完全失去了滚动部署的意义。初学阶段建议先在新环境上用runOnce把整个链路跑通等监控告警和回滚预案都成熟了再上rolling。5. 避坑手册维护 Azure DevOps Pipelines 时遇到的五个典型问题5.1 YAML 缩进报错现象太像“随机翻车”提前用三个检查点现象明明照着示例写的流水线却报You have encountered an unexpected error没有任何有效信息反复刷新又好了。实际上大概率不是随机问题而是 YAML 解析器在缩进和列表对齐上卡住了。原因Azure DevOps 的 YAML 解析对缩进极其敏感尤其在steps列表里任务缩进多一格少一格解释器可能把任务当成上一个任务的子参数或者把某个参数当成列表项。错误提示往往指向一段完全不存在问题的代码因为解析器是从错误发生处才开始报警。解决我做了三个检查点。第一所有缩进全部用空格不要混用 Tab建议在编辑器中开启空白符显示。第二列表项下面的属性必须和列表项同级对齐比如displayName和task是同一任务的并列属性inputs的下一层属性要比任务级别缩进两格。第三用 VS Code 的 YAML 插件写完先本地校验插件能直接标出第几行有问题。5.2 本地能跑、托管执行器上就挂路径与换行符的真实差异现象同样的脚本在 Windows 本地跑得好好的放到ubuntu-latest镜像上却报Could not find a part of the path或者文件找不到。代码还是那份代码环境变量也没改。原因执行器操作系统变了Windows 的路径分隔符是反斜杠Linux 是正斜杠脚本里写死的\bin\Release在 Linux 上会被当成转义序列或非法路径。另一个隐藏点是换行符。Windows 下提交的.sh脚本带 CRLF 换行到 Linux 上直接执行经常报bad interpreter。解决路径统一用正斜杠即使脚本只跑在 Windows 上也建议这么做因为复制到其他环境时不容易翻车。shell 脚本的文件属性要在仓库里显式设置换行符为 LFGit 的core.autocrlf设置要和团队统一。更省事的方式是尽量用跨平台任务比如文件操作类任务用CopyFiles2而不是copy命令。5.3 服务连接突然失效一次权限变更引发整条流水线失败现象流水线昨天还正常今天运行到部署阶段突然报The service connection ... is not authorized。代码没改配置没改找了一圈发现在某个私有平台的后台做了账号权限调整。原因服务连接的本质是一套存储在 DevOps 里的授权凭证底层关联某个账号或令牌。权限回收、账号密码轮换、双因素认证开启等操作都会让这条连接在下次调用时失效。它不报错在配置阶段而是报错在实际调用服务的当时给人感觉完全没有预兆。解决在 Project Settings 的 Service Connections 页面定期检查连接状态重新执行一次“验证连接”操作。涉及生产环境的连接我会手动在日历上设好提醒每季度统一验证一轮。如果用了令牌类连接创建时把过期时间设成一个不会忘记的固定日期宁可换得勤一点也不要等到生产部署时才发现失效。5.4 缓存没命中锁文件内容变化与 key 结构设计现象加了缓存后构建日志里一直显示Cache restored: false构建时间并没有缩短。包管理器已经正常工作依赖文件也没有大改。原因缓存的key设计太粗糙。最常见的错误是只把包管理器名称和操作系统放进去比如npm | $(Agent.OS)只要依赖接文件被 touch 过缓存就失效。另一个常见问题是包管理器的锁文件没有提交到仓库导致每次运行拿到的内容都不一致缓存永远无法命中。解决key里至少包含锁文件名比如package-lock.json或yarn.lock它们的哈希值能客观反映依赖是否发生变化。如果项目里有多个子项目还要把每个子项目对应的锁文件相对路径都拼进去否则任何一个子项目的依赖变了缓存的命中依据都不准确。我把这个 key 的规则写成团队约定任何新建项目都按这个格式来不搞特殊。5.5 任务一直排队免费并发额度与资源池限制现象运行流水线后任务一直处于Queued状态几十分钟都不动。Pipelines 页面显示等待时间但没有任何报错。原因绝大多数情况是并发额度用满了。免费层级的并行任务数有限一旦有别人在前台压着任务后面的人只能排队。另一个原因是自托管执行器资源池里的执行器都在忙碌或者执行器离线了任务找不到空闲机器。解决先到 Organization Settings 的 Parallel jobs 页面看当前额度是多少、用了多少。如果只是临时验证可以等别人跑完如果频繁排队就得考虑减少并发调度或升级并行额度。我说的减少并发不是让你降低团队效率而是控制触发条件比如只在合并到主干时跑完整流水线功能分支只跑快速检查把有限额度用在不必要的地方就是在浪费团队时间。6. 进阶技巧自托管执行器的维护与定时构建的验证思路6.1 自托管执行器安装流程与最小健康检查当项目对构建环境有特殊要求比如必须在内网完成编译、需要访问内网私有源时托管执行器就满足不了了。自托管执行器可以装在自己的机器或虚拟机上流水线通过资源池指定使用它。安装方式很直接在组织设置里的 Agent Pools 页面找到下载入口把安装包解压到目标目录后在目录里执行配置命令mkdir -p /opt/agent cd /opt/agent tar zxvf vsts-agent-linux-x64-*.tar.gz ./config.sh --unattended --url https://dev.azure.com/某组织 \ --auth pat --token 个人访问令牌 \ --pool default --replace配置完成后执行器默认以服务形式运行。健康检查的方式是用安装目录下的svc.sh status命令查看运行状态同时回到 Agent Pools 页面确认执行器节点显示在线。要记住的一点是自托管执行器的环境不会像托管执行器那样自动清理你必须定期检查磁盘空间、环境变量和旧版本缓存。6.2 定时触发 schedulesUTC 换算与分支过滤定时构建的用途很明确每天早上出门前看一个最新的全量构建结果。写法是在 YAML 顶部增加schedulesschedules: - cron: 0 2 * * * displayName: 每日凌晨构建 branches: include: - main always: true这个 cron 里的时间按 UTC 计算如果你在东八区0 2 * * *对应北京时间上午 10 点。分支的include决定哪个分支参与定时触发always: true则表示即使分支没有新提交也按规则跑适合需要每日产物汲取的场景。修改 cron 后建议先在页面手动运行一次确认时间符合预期避免因为时区换算错误大早上被构建通知吵醒。6.3 最后的检查习惯跑通、卡住、看日志、留记录我从接手第一个流水线项目开始养成了一个习惯每次改动 YAML 后先用最小分支手动触发一次确认四个阶段全绿如果卡住先看具体卡在哪一个 job再看 job 里的日志流最后才去翻代码。不要一上来就怀疑环境问题90% 的情况都是配置写错了。留记录的另一个作用是回头复查时不用重新推理当时的改动思路对维护周期长的项目来说这比任何文档都可靠。希望帮到你。本文还有配套的精品资源点击获取