简介：围绕 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 上按顺序跑完的一组 Step | jobs下的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：逐行读一份 YAML
trigger: - 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 organization=https://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: UseDotNet@2 displayName: 安装 .NET 8 SDK inputs: packageType: sdk version: 8.x - task: DotNetCoreCLI@2 displayName: 还原 NuGet 包 inputs: command: restore - task: DotNetCoreCLI@2 displayName: 编译 inputs: command: build arguments: --configuration $(configuration) --no-restore - task: DotNetCoreCLI@2 displayName: 跑单元测试 inputs: command: test arguments: --configuration $(configuration) --no-build - task: DotNetCoreCLI@2 displayName: 发布产物 inputs: command: publish arguments: --configuration $(configuration) --no-build --output $(Build.ArtifactStagingDirectory)/app - task: PublishPipelineArtifact@1 displayName: 上传构建产物 inputs: targetPath: $(Build.ArtifactStagingDirectory)/app artifactName: drop三段关键步骤说明：restore负责还原 NuGet 依赖；build后面加了--no-restore，避免每步重复还原浪费时间；test加--no-build，直接跑编译产物。这三条参数组合是把构建时间压下去的基础操作，否则同样的编译会重复执行两到三次。
三个必调参数分别是：vmImage决定构建环境，换项目语言时要确认镜像里有没有对应 SDK；fetchDepth: 1只拉取最近一次提交，大仓库省几十分钟，做 Git 历史分析时才需要调大；artifactName决定产物在「构建产物」页面的名字，下游部署任务靠这个名字来下载，建议定成固定规范如drop。
产物发布用的是PublishPipelineArtifact@1，这是新版任务，推荐优先使用。老教程里常见的PublishBuildArtifacts@1也能用，但新项目没必要再回头。
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: Cache@2 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 没命中时依次尝试更宽松的 key；path是要缓存的目录；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: AzureWebApp@1 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: DotNetCoreCLI@2 timeoutInMinutes: 90 continueOnError: false6. 把模板复用和本地验证变成默认习惯
6.1 用模板抽公共步骤，多项目维护才轻松
当第二个项目开始复制第一份 YAML 时，就该抽模板了。把构建、测试、发布这三步定义成模板文件：
# templates/dotnet-ci-steps.yml parameters: - name: solution type: string steps: - task: UseDotNet@2 inputs: version: 8.x - task: DotNetCoreCLI@2 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 organization=https://dev.azure.com/你的组织名 project=你的项目名 az pipelines run --pipeline-id 1 --branch devYAML 解析错误会在运行前直接抛出来，比提交后再等仓库触发快得多。配合 PR 场景还有一个技巧：先开 Draft PR，草稿状态默认不会触发构建，确认 YAML 没问题后再 Mark ready，避免用一整条流水线的资源去试错。这个习惯我坚持了两年，至少救回过三次差点在生产上翻车的配置改动。希望帮到你。
本文还有配套的精品资源，点击获取
