简介：这份Azure DevOps Pipelines中文操作手册聚焦持续集成与持续交付，面向DevOps工程师、开发人员和运维人员。内容先介绍Azure Pipelines是什么、经典发布管道、快速入门及创建或导入管道，再围绕代理、条件、表达式、环境、作业、运行时参数、阶段、任务、模板、触发器十个核心概念展开，含容器镜像、.NET Core、Java、JavaScript、Node.js、Python、Android等多语言多平台的配置示例。资源为单个PDF文件，容量106.6MB，已有409人学习。手册同时覆盖GitHub、Azure Repos、Bitbucket等代码仓库集成，部署到Azure SQL数据库、Azure Kubernetes Service和Key Vault的典型场景，以及Selenium UI测试、代码覆盖率、测试结果分析、代理池与部署组配置等进阶操作。末尾还提供生成和发布疑难解答、调试模式及Azure资源管理器服务连接排查指南，有助于快速定位问题，整体模块划分清晰，既适合新手按步骤创建首个管道，也能作为团队日常DevOps参考手册。
1. 拿到 Azure DevOps Pipelines，先别急着写 YAML
很多团队第一次接触 Azure DevOps Pipelines，都是照着一个现成的模板往上堆任务：先 restore 再 build，跑完测试发布产物，看起来一切正常，可一旦换到生产分支、换成自有构建机，整个流水线就开始翻车。真正上手后你会发现，Azure DevOps Pipelines 不是写不出流水线，而是写不出「换了环境还能跑的流水线」。这份操作手册不是官方文档的复述，而是从实际迁移和排障中沉淀下来的操作惯例：从单条 YAML 怎么组织、agent 怎么选、变量和触发器怎么配，到缓存、模板化这些进阶玩法，每一步都会给出能直接抄走的最小可运行配置，以及那些文档里不会写的边界条件。新手跟完一遍能把第一个 pipeline 跑通，熟手则能在参数选择和排障思路上少走弯路。
2. YAML 流水线的最小骨架：从一条任务跑通到结构化组织
2.1 一条能跑的最小 pipeline 长什么样
先不讨论复杂语法，一个最小可用的azure-pipelines.yml只需要四个部分：触发器、agent 池、任务列表、任务细节。很多初学者一上来就复制大段模板，结果要么被条件表达式卡住，要么被多阶段配置吓退，其实完全没必要。以下是我经常作为起点的最小配置：
trigger: - main pool: vmImage: 'ubuntu-latest' steps: - script: echo "Hello from Azure Pipelines!" displayName: 'Say hello'这段配置的含义很直接：trigger指明当main分支有推送时自动触发；pool选择运行环境，ubuntu-latest是微软托管的 Linux 虚拟机镜像，用这个的好处是不用自建构建机就能跑通流程；steps是任务列表，此处只有一条用 shell 执行的脚本任务。整个 pipeline 从提交到运行完成，在托管 agent 上通常不到一分钟。
跑通这条之后，就可以往steps里逐个增加真实任务。常见做法是加一个use任务来安装依赖、加script或task来构建，再加PublishPipelineArtifact上传产物。这里有个容易忽略的点：每一条 step 默认是独立进程，前一步设置的环境变量不会自动传给下一步，想要传值要么写进文件、要么用task.setvariable这个内置命令，后面的章节会专门展开。
2.2 用 Task 还是用 Script：选择依据与常见误用
Azure DevOps Pipelines 里执行具体操作有两种方式：一种是预置的task，比如UseNode@1、DotNetCoreCLI@2；另一种是直接写script自己敲命令。很多新手会把两者混用，或者全部用script导致可维护性急剧下降，这里给出一个选择标准：官方有现成 task 且符合你的构建工具主版本时，优先用 task；工具链比较小众、或者需要在一行里串联多个命令时，用script更可控。
steps: - task: UseNode@1 inputs: version: '20.x' displayName: 'Install Node.js 20' - script: | npm ci npm run build displayName: 'Install dependencies and build'上面的UseNode@1会在托管 agent 上准备指定版本的 Node.js，inputs.version指定主版本号和小版本；script块里的竖线表示多行命令依次执行。逻辑说明：npm ci严格按package-lock.json安装依赖，比npm install更可靠，能避免锁文件被意外改写；npm run build是项目自身的构建脚本。参数上唯一要留意的是version别写死成20.18.0这种精确版本，建议写成20.x，让 agent 每次拉取该主版本的最新补丁，减少安全更新带来的维护负担。
如果把整个构建过程拆成一堆script且没有 displayName，一旦某一秒失败，日志里只有一串乱码般的命令，排查效率极低。我的习惯是每个 script 都写displayName，而且名称里带结果，比如'Build - output dist/'。task 和 script 混用的边界在于：如果是多平台（Windows/Linux/macOS）都要跑的项目，尽量用跨平台的 task，少在 script 里写 shell 特有的语法。
2.3 多阶段 Pipeline：把构建、测试、发布拆开的核心价值
当项目规模变大，单条流水线里堆十几个 step 就非常难读了。Azure DevOps Pipelines 提供了stages这个层级，可以把流水线拆成构建、测试、部署等多个阶段。每个阶段有独立的 agent、变量、条件，相当于多条流水线被编排在同一次运行里。
stages: - stage: Build jobs: - job: Compile pool: vmImage: 'ubuntu-latest' steps: - script: echo "Building" - stage: Test dependsOn: Build jobs: - job: RunTests pool: vmImage: 'ubuntu-latest' steps: - script: echo "Running tests"关键在dependsOn这个字段：它声明了阶段之间的先后依赖。有了它，Test阶段会在Build阶段全部 job 成功后才开始；不写dependsOn的话，默认只依赖前一个阶段，这个区别在实际排障时非常容易踩坑。另外，每个stage下的jobs可以并行执行，多个job之间也可以互相dependsOn。
实际落地时，我习惯把「编译出产物」和「跑单元测试」分开，因为测试失败不应该阻断产物上传，而产物上传一旦失败也不该重复跑一遍测试。阶段之间传递文件需要用PublishPipelineArtifact和DownloadPipelineArtifact这对内置任务，这里先记住结论：阶段和 job 之间没有共享文件系统，凡是要跨阶段用的文件，必须显式上传再下载。不要指望像本地脚本一样直接读上个阶段的输出。
3. Agent 选型与自托管构建机：托管镜像和本地环境的取舍
3.1 三种运行环境的本质差异
Azure DevOps Pipelines 的pool字段决定了任务跑在哪里。表面上只是换一台机器，实际上换的是：预装软件列表、网络隔离边界、磁盘持久性、以及排障方式。托管 agent（vmImage）开箱即用，但每次运行都从干净的虚拟机开始，任何依赖都要现装；自托管 agent（pool: name: mypool）跑在你自己的机器上，能复用本地缓存和已装软件，却要求你维护 agent 软件的版本和登录凭据。
用表格做个直接对比，方便选型时一眼定位：
| 对比维度 | 微软托管 agent | 自托管 agent |
|---|---|---|
| 环境干净度 | 每次全新，无残留 | 有缓存，但可能被上次构建污染 |
| 预装软件 | 多语言 SDK 齐全，但版本偏保守 | 可自定义，装什么由你决定 |
| 网络访问 | 有公网，但 IP 不固定 | 可在内网，访问受限服务更方便 |
| 维护成本 | 零维护 | 需升级 agent、清理磁盘、管理凭据 |
| 成本 | 按并发分钟数计费 | 无分钟费，但要自己掏机器 |
托管 agent 的最大优势是「不可变环境」，每次构建都像第一次安装依赖，能暴露出「本地能过但别人跑不了」的问题；自托管 agent 的优势则在缓存命中和访问内网资源。混合使用也是常见策略：PR 验证走托管 agent，正式发布走自托管 agent。
3.2 自托管 Agent 的注册步骤与必配参数
如果你确定要走自托管这条路，注册 agent 是绕不开的第一步。整个过程可以预先在配置阶段想清楚三件事：agent 池名称、token 权限、工作目录位置。
mkdir myagent && cd myagent curl -O https://vstsagentpackage.azureedge.net/agent/4.248.0/vsts-agent-linux-x64-4.248.0.tar.gz tar zxvf vsts-agent-linux-x64-4.248.0.tar.gz ./config.sh --unattended --url https://dev.azure.com/yourorg --auth pat --token YOUR_PAT --pool mypool --agent myagent --work /var/agent_work --replace ./run.sh上面的命令里，--url是你的组织地址，--auth pat表示用个人访问令牌认证，--pool指定 agent 要加入的池名称，--work设置工作目录（建议放到独立分区，避免和系统盘抢空间），--replace是覆盖同名 agent。配置完成后run.sh会在前台启动 agent，生产环境建议用 systemd 或 Windows 服务将其守护起来，不然终端一关构建就掉线。
运行自托管 agent 时，有一个参数常常被忽略：agent的权限组。默认情况下，agent 池里的 agent 不能直接访问流水线要用的某些服务连接（比如拉取私有 npm 源或容器镜像库），需要到项目设置的「服务连接」里给对应 agent 池授权。这一步不做好，现象就是任务一直在排队、报权限不足，日志里却看不到真实原因。
3.3 镜像预装清单怎么看：一份值得背下来的索引
微软官方公布了一份「托管 agent 软件清单」文档，列出每个 vmImage 里预装了哪些工具和版本。实际操作中最实用的不是背完整清单，而是知道两个查看入口：一是 pipeline 里加一条- script: node --version && npm --version自己打出来，二是直接查文档里对应 Ubuntu/Windows/macOS 镜像的「Included Software」表格。常见工具的预装情况大致符合这个规律：
- 每个镜像都装了常见语言运行时（Node、Python、Java、Go、.NET SDK），但版本不是最新的，往往会滞后一到两个大版本；
- 容器相关工具（Docker、Docker Compose）在 ubuntu 镜像上是完整的，Windows 镜像上 Docker 是 Windows 容器模式；
- 命令行工具（Git、GitHub CLI、Azure CLI、AWS CLI）基本都有，但版本更新节奏不同。
如果你发现托管镜像里的版本和项目要求差太多，别硬装，有两个选择：一是改用UseNode@1、UsePythonVersion@0这类版本切换 task 来指定版本；二是直接用script安装对应版本并放到 PATH 前面。前者的好处是 task 本身会处理缓存和版本切换，后者适合对网络源可控的团队。记住一个大原则：不要用 apt 往系统目录里装构建工具，尽量装到$(Agent.ToolsDirectory)或项目目录下，否则下一次构建可能因为上次的残留而出诡异问题。
4. 变量、触发器和条件表达式：流水线的动态控制面
4.1 变量定义的三种位置与优先级规则
Pipelines 里可以在三个地方定义变量：YAML 顶层、stage/job 级别、以及任务的inputs里。定义位置不同，覆盖规则也不同。顶层变量是全局默认值，stage 或 job 内可以同名覆盖。还有一类是运行时由命令动态写入的变量，优先级最高。
variables: buildConfiguration: 'Release' majorVersion: '1' stages: - stage: Build variables: buildConfiguration: 'Debug' jobs: - job: Compile steps: - script: | echo "##vso[task.setvariable variable=majorVersion]2" echo "Configuration is $(buildConfiguration)" displayName: 'Show config and set variable'这里的逻辑是：顶层buildConfiguration被 stage 级别的同名变量覆盖，因此 echo 输出的是Debug；majorVersion在脚本运行时被task.setvariable改成了2，这条命令对后续 step 生效。参数的注意点：task.setvariable只影响正在运行的这个 job 的后续步骤，不会反向改掉 stage 或顶层定义，跨 job 要用isOutput=true并配合dependencies引用，那是另一套更复杂的语法，一般用不到就别碰。
真实排障里最典型的变量问题就是「我在推送分支时改了变量，但流水线用的还是旧值」。原因基本是顶层变量在排队时已经编译成静态值，运行时再改不会影响已开始的运行。正确做法是：需要每次运行都不一样的值，用trigger里的variables或运行时参数（runtime parameters），而不是 YAML 顶层变量。
4.2 触发器的完整配置：避开默认分支和 PR 的坑
绝大多数团队的第一个 pipeline 是从仓库根目录的azure-pipelines.yml开始的，默认触发器会监听所有分支的推送。这在多人协作时相当吵：每次 push 都触发一次完整构建，资源浪费不说，日志还难筛。
trigger: branches: include: - main - release/* paths: include: - src/* - azure-pipelines.yml exclude: - docs/* pr: branches: include: - maintrigger控制 CI 触发条件：branches.include只在这些分支的推送时触发；paths.include和paths.exclude做路径过滤，docs/*下的改动不会浪费构建。pr分支策略单独控制 PR 验证触发，一般保持和主分支一致。含通配符的release/*能覆盖发布分支，但注意通配符只出现在最后一段，不能写release/*/hotfix这种形式。
路径过滤是很多人踩坑的重灾区。常见现象：改了一个README.md，流水线照样全量跑。原因就是paths只写了include没写exclude，而 include 之外的改动依然满足触发条件。把docs/*显式排除掉之后，不相关的文档提交就不会触发了。另外，如果 YAML 文件本身在paths.exclude里被排除，那么对这个 YAML 的修改不会触发流水线——这会导致你改了流水线配置却不重跑，看起来「改了对但没生效」，解决方法是把azure-pipelines.yml永远放在include列表里。
4.3 条件表达式与自定义条件：stage 和 step 的开关逻辑
条件表达式是流水线里按需执行任务的手段，语法核心是condition字段配合eq、ne、and、or等函数。常见用途：只有 main 分支才推送生产产物，只有手动运行时才执行某些高风险步骤。
- stage: Deploy condition: and(succeeded(), eq(variables['build.sourceBranch'], 'refs/heads/main')) jobs: - job: DeployToProd steps: - script: echo "Deploy to production"eq(variables['build.sourceBranch'], 'refs/heads/main')判断当前分支是不是main，注意完整的 Git ref 格式是refs/heads/main，不带前缀会恒为 false。and(succeeded(), ...)表示前一阶段成功了、且满足分支条件时才执行。如果把succeeded()忘掉，一旦构建失败，发布阶段还是会尝试运行，这是生产事故级别的坑。
自定义条件还能配合用户选择：在流水线界面选择「Run pipeline」时可以勾选参数。YAML 里加parameters就能实现交互式选择：
parameters: - name: deployEnv type: string default: 'staging' values: - staging - production steps: - script: echo "deploying to ${{ parameters.deployEnv }}"${{ }}是编译期求值的模板语法，运行时无法改变；而$( )是运行时变量语法，可以在脚本执行中动态求值。这个区别务必记牢——很多条件判断「看起来没生效」就是因为在if表达式里用了运行时变量而不是模板参数。
5. 高频避坑与排查：从 YAML 没生效到缓存玄学
5.1 现象：改了 YAML 但流水线还是跑旧配置
原因：Azure DevOps 对 YAML 的读取时机分两种：推送到分支的 CI 触发会在 push 后立即解析最新文件；但如果是手动运行一条之前排队的流水线，或者用了流水线缓存，就可能拿到旧定义。另外，azure-pipelines.yml不在仓库根目录时，需要在根目录放一个指向它的「管线文件」或用 UI 里指定路径，否则推送新提交不会触发任何构建。 解决：先从流水线编辑页看「YAML 来源」是否指向main分支的最新提交；再检查是不是多个分支各自维护了一份 YAML，导致看起来改了实际没改对分支。最稳妥的验证方式：在 pipeline 页面选择「Run」，确认弹出的 YAML 预览里包含你刚改的内容。如果预览还是旧的，多半是浏览器缓存或服务端缓存，等待一两分钟再刷新。
5.2 现象：自托管 agent 上任务一直排队，或者报「无法锁定工作目录」
原因：自托管 agent 同一时间只能跑一个 job，agent 池里有多个 agent 但你的demands把任务限定到了一个特定 agent 名；或者是多个 agent 共用了同一个--work目录，文件锁冲突导致任务互相踩踏。 解决：先到 agent 池页面看每个 agent 的状态是否为online；再到流水线的pool里确认要不要写demands。如果不需要特定 agent，把 demands 删掉，让调度器在池内任意挑选。多 agent 共机时，给每个 agent 独立--work目录，比如/var/agent_work_01、/var/agent_work_02，别共用。
5.3 现象：构建在本地能过，pipeline 里一跑就报「找不到模块 / SDK 版本不对」
原因：本地开发机的环境是长期演化的，依赖被全局安装过；托管 agent 每次都是干净环境，只装了默认版本的工具。特别是 Node.js 或 Python 版本不匹配，最常见。 解决：第一，在 YAML 里显式用版本 task 指定工具版本，不要依赖镜像默认值；第二，用npm ci而不是npm install，确保锁文件被完整尊重；第三，在脚本开头加一条node --version && npm --version把版本打印出来，先确认环境再跑构建，能省掉大量无头绪的翻日志时间。打印版本这步看似多余，实则是自托管 agent 上最强的排障第一招。
5.4 现象：流水线成功但产物下载下来是坏的，或者文件缺失
原因：最常见的是产物路径写错，打包时只上传了部分目录；或者多个 job 并行上传同一个 artifact 名称，相互覆盖。 解决：把PublishPipelineArtifact的pathToPublish明确指向构建输出目录，不要用通配符*去匹配整个工作目录，那会把.git、node_modules全部打进去。多个 job 要上传时，给每个 artifact 加独立名称，如artifact-web、artifact-api。下载端也要指定正确的 artifact 名，否则 Azure Pipelines 默认下载第一个匹配项，很可能不是你想要的。
5.5 现象：缓存任务从未命中，每次都在全量装依赖
原因：缓存 key 的生成规则太宽松或太严格。太宽松会导致命中错误的缓存，太严格则永远命中不了。比如每次构建前都执行一次git pull，缓存 key 里带上了 commit SHA，那每两次提交的 key 都不同，缓存形同虚设。 解决：缓存 key 要基于依赖锁文件而非 commit 变化。Node 项目用package-lock.json的哈希做 key，Python 项目用requirements.txt或poetry.lock。缓存恢复（Cache@2restore）失败不会让流水线整体失败，只是继续走正常安装流程——很多团队在日志里看到cache miss就忽略，结果缓存一直没生效还不自知。建议在恢复缓存之后加一步检查：如果是缓存命中，环境变量里会有一个标记，可以用它来快速判断。
5.6 现象：条件表达式里的变量值「好像不对」，分支判断永远走 false 分支
原因：在模板表达式${{ if eq(variables['build.sourceBranch'], 'refs/heads/main') }}中，build.sourceBranch是运行时变量，而模板表达式在编译期求值，此时运行时变量还未就绪，所以永远是默认值或空字符串。 解决：分支判断这类场景不要用模板表达式做条件，改用运行时条件condition: eq(variables['build.sourceBranch'], 'refs/heads/main')。一个简单的判断准则：需要依赖运行时数据的判断一律写condition，静态选择用${{ if }}语法。混用时要明确注释说明哪个是编译期、哪个是运行期，不然三个月后的自己会对着 YAML 发懵。
6. 进阶用法与验证技巧：模板化、缓存命中验证和本地排障习惯
模板化是让多套流水线保持一致性的关键手段。把重复的任务抽成一个模板文件，放到templates/目录下，主流水线里用template引用：
# templates/build-node.yml parameters: - name: nodeVersion type: string default: '20.x' steps: - task: UseNode@1 inputs: version: ${{ parameters.nodeVersion }} - script: npm ci && npm run build主流水线里引用时，可以传入不同参数：
steps: - template: templates/build-node.yml parameters: nodeVersion: '18.x'模板的维护价值在于：当构建工具链升级或新增公共步骤时，只需改一个文件，所有引用它的流水线一并更新。代价是调试链路变长，报错信息里会多一层「模板展开」的上下文。建议模板文件只放 step 级别的复用，不要滥用多层嵌套，否则排障时日志里全是模板路径，真正的问题反而被淹没。
缓存命中验证有一个值得养成的习惯：在流水线里加一个script步骤，把Cache@2任务设置的CACHE_RESTORED变量显式打出来。命中时值为true，未命中为false。有这个地方标记着，别人接手你的流水线时，不必阅读 YAML 里晦涩的缓存配置语义，一眼就能看出这条流水线到底有没有吃到缓存红利。
另一个进阶技巧是把 PR 验证和 CI 验证区分开。PR 验证只需要跑快速编译和单元测试，可以不加发布任务；而 CI 触发的主分支构建才做完整打包和产物上传。这个区分不只是在 YAML 里写条件，还要注意「PR 验证用的是合并后的代码」这一点。在pr触发器下，pipeline 跑的是源分支和目标分支合并后的结果，如果合并本身有冲突，流水线会在最开始就失败，这属于预期行为，不要在排障时试图绕过。
最后说一个我个人的排障习惯：任何一次手动运行的流水线，先点开第一个失败任务，看右下角有没有「查看原始日志」的链接。托管 agent 上很多错误信息在折叠的 UI 里看不全，原生日志里才有真正的 stack trace 或 exit code。这条铁律在自托管 agent 上更关键，因为你的 agent 日志可能会被系统日志截断，原生日志不会。有时候一个问题查了两小时，最后发现只是任务里某条 shell 命令因为权限问题静默失败，原生日志第一行就写着permission denied。养成这个习惯之后，我的平均排障时间缩短了至少三分之一。希望这份操作手册能帮你少走一些我走过的弯路，跑通自己的第一条流水线只是开始，能在生产环境稳定跑一年才是真功夫。
本文还有配套的精品资源，点击获取
