CI/CD / 系统课时
按代码变更范围选择阶段
按代码变更范围选择阶段
同一仓库中的文档、前端、后端或部署文件发生变化时,并不一定需要执行整条流水线。本节使用 Jenkins Declarative Pipeline 的 changeset 条件,让阶段根据本次提交的文件范围决定是否运行,并通过构建日志验证跳过行为。
学习目标
- 理解按变更范围执行阶段能解决什么问题
- 使用
when与changeset为阶段设置文件匹配条件 - 识别变更检测的适用边界,避免错误跳过必要阶段
把文件变化映射到阶段
假设仓库同时包含 backend/、frontend/ 和 docs/。如果只修改文档,重新编译后端和前端通常没有价值;如果只修改前端,则可以跳过后端测试。这里的核心不是“少跑几个命令”,而是建立文件范围与验证责任之间的明确映射。
一个常见映射是:backend/** 变化时运行后端测试,frontend/** 变化时运行前端构建,而部署清单或公共构建配置变化时执行额外验证。共享依赖、根目录构建文件等能够影响多个组件的文件,应纳入所有受影响阶段,不能只匹配组件目录。

使用 changeset 控制阶段
Declarative Pipeline 可以在阶段的 when 中使用 changeset。下面的 Jenkinsfile 根据目录变化分别决定是否执行后端和前端阶段。示例假定 Jenkins 已完成 SCM checkout,仓库中存在相应目录。
pipeline {
agent any
stages {
stage('Checkout') {
steps {
checkout scm
}
}
stage('Backend Test') {
when {
changeset 'backend/**'
}
steps {
echo 'Run backend tests'
}
}
stage('Frontend Build') {
when {
changeset 'frontend/**'
}
steps {
echo 'Build frontend'
}
}
}
}如果本次变更只包含 frontend/src/app.js,预期结果是后端阶段因条件不满足而跳过,前端阶段执行。Jenkins 的具体日志前缀和时间戳会因版本与插件而不同。
预期输出
Stage "Backend Test" skipped due to when conditional
Build frontendchangeset 判断的是 Jenkins 获得的 SCM 变更记录,而不是运行时执行 git status 后看到的工作区状态。因此,流水线自己生成的新文件不会自动成为本次 SCM changeset 的一部分。
组合多个影响范围
真实项目经常存在公共文件。例如修改根目录的构建脚本可能同时影响前后端,此时可以使用 anyOf 把多个匹配条件组合起来。下面是片段示例,需要放在 Declarative Pipeline 的 stage 中使用。
when {
anyOf {
changeset 'backend/**'
changeset 'build.gradle'
}
}该配置表示后端目录或根目录 build.gradle 任一发生变化,都执行对应阶段。验证时应分别提交组件文件和公共文件,确认两种情况都能触发阶段。
不要把路径匹配当成依赖分析
changeset 只负责匹配变更文件,不理解代码依赖。如果 common/ 被前后端共同引用,那么只匹配 backend/** 会在修改 common/ 时错误跳过后端测试。路径规则必须依据真实依赖关系设计。
还要注意首次构建、不同 SCM 插件以及不同触发方式可能影响可用的变更记录。上线条件执行前,应先用实际仓库验证“仅改组件文件”“仅改共享文件”“同时修改多个目录”三种情况。只有这些边界都符合预期,按变更范围跳过阶段才真正减少构建时间,而不会减少必要验证。