简介围绕 Azure DevOps 中的 Azure Pipelines这份 PDF 操作手册面向开发、运维及 DevOps 工程师系统讲解如何为任意语言和平台搭建持续集成与持续交付CI/CD自动化链路并覆盖从初次创建管道到多环境发布的核心环节。内容包含 YAML 配置、代理与条件、阶段、作业、任务、模板、触发器、运行时参数等关键概念同时结合 GitHub、Azure Repos 等仓库集成以及容器、AKS、SQL 数据库、虚拟机和 PaaS 服务等部署场景既适合零基础入门也便于日常配置时快速检索。资源为单个 PDF 文件体积 106.6MB将 Azure Pipelines 官方文档整理成中文操作手册支持离线阅读和团队内部分享。目前已有 409 人浏览/学习读者可借此系统掌握代码构建、自动测试、制品发布与故障排查的完整流程降低 CI/CD 落地过程中的试错成本。1. Azure DevOps Pipelines 是什么以及这份操作手册怎么用一条跑在 Azure DevOps Pipelines 上的流水线凌晨三点静默失败比白天编译报错更折磨人——因为你根本不知道日志去哪看、是哪一步死的。Azure DevOps Pipelines 是 Azure DevOps 平台里的 CI/CD 引擎用一份 YAML 文件把拉代码、编译、测试、打包、部署串成自动链路并绑定到分支、标签和 PR 事件上按规则触发。这份操作手册适合两类人一类是接手了别人留下的流水线、只敢改参数不敢动结构另一类是准备从零搭一套稳定构建流程的团队。后面的章节按「概念 → 最小实现 → 调优参数 → 踩坑 → 进阶习惯」推进照着抄就能跑起来。2. 先拆清楚 pipeline 的四块积木Agent、Pool、Job、Step打开一份azure-pipelines.yml第一眼觉得复杂的人通常是没有先把执行模型理清。流水线看似全是steps其实背后由四层构成Step 是最小命令Job 是一组 Step 的执行单元Pool 决定了跑在哪些机器上Agent 才是真正干活的机器。先把这四层映射到 YAML 的字段后面看任何一份配置都不再发怵。2.1 为什么 YAML 已经取代可视化编辑器成为事实标准Azure DevOps 平台里其实有两种流水线形态旧的经典编辑器Classic和现在的 YAML。经典编辑器适合不写代码的人快速配一个简单构建但它的配置以数据库里的 JSON 形式保存没法入库、没法 diff、没法做代码评审。只要改动稍大你根本说不清上一次是谁改了哪个开关出了事故想回滚都找不到入口。YAML 是平台默认推荐的新形态。一份azure-pipelines.yml提交进仓库跟着源码走版本改动可 diff、可 review、可回滚同一个文件能复制到多个项目里复用配合模板参数就能实现「一套模板多处流水线」。我的建议很直接新项目一律用 YAML老项目里的经典流水线如果还能跑迁移前可以继续用但不要再往里面加新任务。理由是 YAML 流水线排查路径短语法错误直接指到第几行而经典流水线报错时你经常得靠猜。选 YAML 还有一个现实原因换人或换团队时新人看仓库里的文件就能理解全部构建逻辑而不需要在项目设置里逐个点开几十个任务卡片。对团队来说这就是把「黑匣子」变成了「可读的代码资产」。2.2 Agent、Pool、Job、Step 的映射关系概念一句话解释在 YAML 里的位置Step一条命令或一个内置任务steps下的每一项Job在同一个 Agent 上按顺序跑完的一组 Stepjobs下的job: 名字Pool一组相同环境配置的 Agent 集合pool字段填vmImage或自建池名Agent真正执行命令的机器或容器不在 YAML 里直接指定由 Pool 决定关系是逐层包含的一个流水线可以有多个 Stage一个 Stage 里可以有多个 Job一个 Job 里按顺序跑多个 Step。Job 与 Job 之间默认并行执行只有你写了dependsOn或通过condition声明依赖时才串行等待。一个最常见的误解是「我写了多个 steps它们是不是并行的」。不是。同一个 Job 里的 Step 永远是顺序执行前一个失败默认直接中断整个 Job想并行应该在 Job 层级拆而不是在 Step 层级堆。另一个常见误用是把所有任务全塞进一个大 job导致一个机器上串行跑完构建和测试白白浪费并行额度。Agent 分两类平台托管的选vmImage比如 ubuntu-latest用完即焚、环境干净和自托管的自建 Agent 池机器常驻、环境自定义。选型没有绝对对错平台托管省心但每次构建环境全新装依赖耗时自托管快但环境漂移要靠你自己管住。后面第 5 章会专门讲自托管踩过的坑。2.3 最小可运行的 pipeline逐行读一份 YAMLtrigger: - main pool: vmImage: ubuntu-latest steps: - script: echo 流水线跑起来了 displayName: 第一个任务这是能跑的最小文件。trigger声明只有 main 分支的推送才触发构建pool指定跑在平台托管的 ubuntu 镜像上steps里只有一个script就是一段 shell 命令。displayName只是 UI 上的展示名方便在日志里定位任务建议每个 step 都写否则日志里全是「CmdLine」根本分不清谁是谁。你可以把这份内容提交到仓库根目录的azure-pipelines.yml然后在 Pipelines 页面新建 pipeline选择该仓库平台会自动识别这个文件。如果连trigger都不写平台默认只在默认分支上监听推送不会全仓库乱跑。这一点新手往往不知道以为配好了就会全部分支构建结果开发分支改了代码死活不触发。注意vmImage的取值是有讲究的ubuntu-latest是当前推荐的 Linux 镜像windows-latest和macos-latest分别在需要 Windows 语法或苹果生态编译时使用。镜像里的预装工具会随平台更新而变化所以构建脚本里不要假设某工具一定存在必要时先跑tool --version。3. 从零跑通第一条流水线最小 YAML 与三个必调参数概念理清后就该让流水线真的跑出绿勾了。这一章以一个 .NET 后端项目为例原因是它覆盖了最常见的链路还原依赖、编译、测试、发布产物。换成 Node 或 Java 项目任务名变一下思路完全一样。3.1 创建 Pipeline 的三种入口常见做法是三种门户页面、命令行、直接把文件提交进仓库。第一种适合一次性建。页面路径是 Pipelines → New Pipeline → 选择仓库 → 选择已有的azure-pipelines.yml或使用 Starter 模板。平台会先在页面上解析一遍 YAML有语法错误会直接红字提示这一步等于免费的校验。第二种适合批量建尤其是要在一个组织里给几十个仓库统一建流水线时。先把 CLI 扩展装好再创建az extension add --name azure-devops az devops configure --defaults organizationhttps://dev.azure.com/你的组织名 project你的项目名 az pipelines create --name ci-main --repository-type tfsgit --repository 你的仓库名 --branch main --yaml-path azure-pipelines.yml第三种最「Git 原生」直接把 YAML 和代码一起提交然后等平台的自动检测。细节是仓库里必须先有文件平台检测到根目录存在azure-pipelines.yml时会在 Pipelines 页面提示你创建对应流水线。3.2 一份能直接抄的最小 YAML构建 测试 发包trigger: branches: include: - main - release/* paths: exclude: - docs/* pool: vmImage: ubuntu-latest variables: configuration: Release steps: - checkout: self fetchDepth: 1 - task: UseDotNet2 displayName: 安装 .NET 8 SDK inputs: packageType: sdk version: 8.x - task: DotNetCoreCLI2 displayName: 还原 NuGet 包 inputs: command: restore - task: DotNetCoreCLI2 displayName: 编译 inputs: command: build arguments: --configuration $(configuration) --no-restore - task: DotNetCoreCLI2 displayName: 跑单元测试 inputs: command: test arguments: --configuration $(configuration) --no-build - task: DotNetCoreCLI2 displayName: 发布产物 inputs: command: publish arguments: --configuration $(configuration) --no-build --output $(Build.ArtifactStagingDirectory)/app - task: PublishPipelineArtifact1 displayName: 上传构建产物 inputs: targetPath: $(Build.ArtifactStagingDirectory)/app artifactName: drop三段关键步骤说明restore负责还原 NuGet 依赖build后面加了--no-restore避免每步重复还原浪费时间test加--no-build直接跑编译产物。这三条参数组合是把构建时间压下去的基础操作否则同样的编译会重复执行两到三次。三个必调参数分别是vmImage决定构建环境换项目语言时要确认镜像里有没有对应 SDKfetchDepth: 1只拉取最近一次提交大仓库省几十分钟做 Git 历史分析时才需要调大artifactName决定产物在「构建产物」页面的名字下游部署任务靠这个名字来下载建议定成固定规范如drop。产物发布用的是PublishPipelineArtifact1这是新版任务推荐优先使用。老教程里常见的PublishBuildArtifacts1也能用但新项目没必要再回头。3.3 触发器与分支策略什么时候该跑什么时候别乱跑trigger里的branches.include和exclude控制哪些分支推送会触发 CI。release 分支用通配符release/*是很常见的写法但要注意它只匹配一级目录release/2024/12这种多级路径不会命中需要写release/**。paths是 monorepo 的救星也是翻车高发区。前端改动不该触发后端流水线就在paths.exclude里排除掉比如trigger: paths: include: - src/backend/** - azure-pipelines.yml有个细节必须记住一旦你写了paths过滤流水线配置文件自身的改动默认也不会触发。想让自己改完 YAML 立刻生效必须把azure-pipelines.yml也加进include这是最容易踩的坑之一。另外 PR 触发是独立的pr:块和trigger:互不继承如果团队希望 PR 不跑构建显式写pr: none别以为不写就默认关闭。4. 让构建又稳又快缓存、变量组与服务连接跑通只是起点接下来三件事直接决定这条流水线能不能长期用下去恢复依赖的速度、敏感信息的管理方式、部署阶段的权限边界。4.1 缓存依赖把 restore 从五分钟压到三十秒平台托管 Agent 每次构建都是全新环境NuGet 和 npm 依赖每次都要重新下载。解决办法是用缓存任务把依赖目录暂存下来命中时直接解压。variables: NUGET_PACKAGES: $(Pipeline.Workspace)/.nuget/packages steps: - task: Cache2 displayName: 缓存 NuGet 全局包目录 inputs: key: nuget | $(Agent.OS) | **/packages.lock.json restoreKeys: | nuget | $(Agent.OS) nuget path: $(NUGET_PACKAGES) cacheHitVar: NUGET_CACHE_RESTOREDkey决定缓存是否命中把锁文件路径写进去packages.lock.json变了缓存就失效restoreKeys是降级匹配主 key 没命中时依次尝试更宽松的 keypath是要缓存的目录cacheHitVar会在命中时被置为true你可以在后续步骤里用它跳过不必要的操作。注意缓存路径要指向$(Pipeline.Workspace)下而不是默认的~/.nuget/packages否则平台托管的镜像每次也会把目录隔离掉缓存等于白设。另一个常见误区是不用锁文件、只写死 key结果是依赖一变全部缓存作废性能优化成了玄学。npm 项目思路一样把 key 换成yarn.lock的路径、path 换成$(YARN_CACHE_FOLDER)即可。还要提醒一点平台对单条流水线的缓存总量有硬上限超出后会按最旧优先驱逐别把几十 GB 的构建中间产物也塞进去。缓存只适合依赖目录和小体积中间产物真正的构建输出应该走 artifact 流转。4.2 变量、变量组与密钥哪些该写死哪些必须托管变量在 YAML 里有三种写法展开时机完全不同这是新手最容易混淆的地方写法展开时机典型用途$(变量名)宏在任务执行前展开给任务传参数最常用$[ variables.变量名 ]运行时表达式阶段间求值条件判断里引用变量${{ 表达式 }}模板表达式解析 YAML 时展开模板参数、静态拼接三种混用是踩坑重灾区在condition里写$(Build.Reason)不会报错但比较的是字面量字符串条件永远不成立。正确写法是eq(variables[Build.Reason], IndividualCI)这一条记住能省很多排查时间。密钥变量来自变量组时不能直接用在条件里也不能作为模板参数传入唯一安全的通路是映射成环境变量- script: echo $API_KEY env: API_KEY: $(api-key)变量组的创建位置在 Library → Variable groups创建时可选关联 Azure Key Vault从密钥保管库自动拉取机密。推荐做法非敏感的版本号、构建参数写 YAML 里跨流水线共享的配置放普通变量组真正的密码、令牌放 Key Vault 变量组。同名变量的优先级是 YAML 内行内变量高于变量组理解了这个顺序排查「我改了变量组为什么没生效」就快了。4.3 服务连接部署任务的权限边界流水线里的部署任务要访问 Azure 资源时不能直接把账号密码写进 YAML而是通过服务连接Service Connection授权。创建入口在 Project Settings → Service connections常用的两种是 Azure Resource Manager 和 Generic。Azure Resource Manager 类型的连接现在优先推荐工作负载联合身份验证避免在连接里存长期有效的 client secret创建时按资源组或单个应用来限定权限范围不要为了省事给整个订阅授权。Generic 连接适合 SSH、第三方 API 这类场景本质是把令牌或密钥托管起来YAML 里用变量引用。在任务里消费服务连接的方式是直接传名字- task: AzureWebApp1 inputs: azureSubscription: 你的服务连接名 appName: 你的应用名 package: $(Build.ArtifactStagingDirectory)/**/*.zip服务连接权限是共享的任何能编辑流水线的人都能用它部署所以创建时命名要能看出环境比如dev-订单系统-sp和prod-订单系统-sp分开建别让测试环境用的连接拥有生产资源权限。这是企业内部审计最常问的问题也是最容易忽略的合规点。5. Pipeline 常见问题与排查五条高频踩坑记录这一章把我见过的高频问题按「现象 → 原因 → 解决」整理成五条。每一条都对应真实发生过的情况排查思路通用。5.1 本地能编译自托管 Agent 上却随机失败现象同样的代码本地构建通过自托管 Agent 上偶尔报错错误指向 SDK 版本或警告被当错误处理。更诡异的是早上能过、下午不行。原因自托管机器的 SDK 是常驻的机器上同时装了 6.x、7.x、8.x选择器每次解析的版本可能不同或系统 PATH 里混入了用户级安装的 SDK导致隐式选择。本地开发机恰好是正版版本所以一直正常。解决仓库根目录提交global.json锁死 SDK 版本并在流水线里用 UseDotNet 任务显式安装如果项目多目标框架还要检查Directory.Build.props里的TargetFrameworks是否依赖了机器上没装的目标框架。版本锁定后把构建环境变成可复现的此类玄学问题基本绝迹。5.2 改了前端文件却把整套流水线跑了一遍现象monorepo 仓库只改了web/src下的一个按钮后端流水线、测试流水线全被触发资源疯狂占用。原因trigger只配了分支没配paths。平台检测到分支有提交就触发不关心你改的是哪个目录。解决按 3.3 节的办法给每条业务流水线配paths.include和paths.exclude并且把azure-pipelines.yml自己加进 include否则下次改 YAML 会静默失效。注意 Git 的路径匹配是基于变更文件的和目录深度无关src/backend/**能覆盖深层子目录但src/backend/*只能命中一层。5.3 脚本里明明有这个命令Agent 却提示 command not found现象script步骤里执行node --version本地正常Agent 上输出command not found或者上午能跑下午同一段脚本突然报错。原因自托管 Agent 以服务方式运行时使用的是系统服务账户的环境这个账户的 PATH 里没有用户级安装的 Node、Python 等工具有些工具是装在用户目录下的服务账户看不到。平台托管镜像则可能因为镜像升级移除了某个预装工具。解决脚本开头显式指定工具路径或在流水线变量里统一设置 PATH对平台托管环境不要假设工具永远存在任务前先跑版本探测命令缺了就用对应安装任务补上。服务账户的 PATH 是黑匣子别跟它赌运气全路径最稳。5.4 条件判断拿到的变量不是我写的那个值现象写了condition: eq(variables[buildConfiguration], $(buildConfiguration))手动跑构建时配置明明是 Release但步骤就是不执行或模板参数在 YAML 里展开成奇怪的值。原因$()宏在 condition 里不会被展开平台把它当字面量字符串和右侧比较永远不相等。模板表达式${{ }}则在解析阶段就展开用它做条件会有「编译期决定」和「运行期决定」的差异。解决记住三条铁律——任务参数用$( )condition 里引用变量用variables[名字]模板拼接用${{ }}。判断构建原因时写成condition: and(succeeded(), eq(variables[Build.Reason], IndividualCI))不要混用。排查方法是在流水线上加一个临时步骤- script: env把当前环境变量全打出来对照实际值检查。5.5 日志太大被截断任务失败了却不知道死在哪儿现象任务显示失败打开日志发现只有开头一点后面全是省略号或几百 MB 的构建日志里真正出错的那行早被冲没了。原因平台对单个任务的日志有大小限制超出后 UI 只展示前后片段中间被截断。大日志通常来自dotnet build -v diag、全量 npm 输出或循环打印。解决把重输出重定向到文件关键内容用Write-Host/echo摘要输出失败时先下载原始日志压缩包再定位问题别在页面上翻。另外给长任务显式设置timeoutInMinutes默认单任务 60 分钟超时超过会被强制杀掉加上这两行可以避免「任务跑了很久突然消失」的情况- task: DotNetCoreCLI2 timeoutInMinutes: 90 continueOnError: false6. 把模板复用和本地验证变成默认习惯6.1 用模板抽公共步骤多项目维护才轻松当第二个项目开始复制第一份 YAML 时就该抽模板了。把构建、测试、发布这三步定义成模板文件# templates/dotnet-ci-steps.yml parameters: - name: solution type: string steps: - task: UseDotNet2 inputs: version: 8.x - task: DotNetCoreCLI2 inputs: command: build arguments: ${{ parameters.solution }}业务流水线里引用它只需两三行steps: - template: templates/dotnet-ci-steps.yml parameters: solution: MyApp.sln模板参数在解析期用${{ }}展开路由到不同项目的不同解决方案。这个习惯的价值是后悔药某天要统一升级 SDK 版本只改模板一处几十条流水线同步生效不用逐个项目手工点。6.2 提交前先用 CLI 跑一次验证我最常做的一件事是改完 YAML 先不提交先在本地用az pipelines run把当前分支跑一遍确认语法和触发逻辑都对再合入az devops configure --defaults organizationhttps://dev.azure.com/你的组织名 project你的项目名 az pipelines run --pipeline-id 1 --branch devYAML 解析错误会在运行前直接抛出来比提交后再等仓库触发快得多。配合 PR 场景还有一个技巧先开 Draft PR草稿状态默认不会触发构建确认 YAML 没问题后再 Mark ready避免用一整条流水线的资源去试错。这个习惯我坚持了两年至少救回过三次差点在生产上翻车的配置改动。希望帮到你。本文还有配套的精品资源点击获取