腾讯云 CNB Monorepo 按需构建：只构建改动影响的模块

摘要：

Monorepo 大仓里改一行代码却触发全量构建，既慢又浪费算力。腾讯云 CNB 通过 .cnb.yml 中的 ifModify 路径匹配机制，只在改动命中某模块目录时才构建该模块，其余模块自动跳过，配合 include 模板复用与按核时计费，让大仓构建从"全量等待"变成"按需秒级响应"。

一、Monorepo 大仓的构建痛点

把多个服务、多个包放进同一个 Git 仓库统一管理，是 Monorepo 的核心价值：跨模块重构方便、依赖版本统一、一次提交就能关联多个子项目。但当仓库规模膨胀到几十个模块、上百万行代码时，构建环节的问题就暴露出来。

最典型的场景是：开发者只改了 packages/user-service 里的一行逻辑，提交后流水线却把 order-service、payment-service、gateway 等十几个模块全部重新构建一遍。结果是等待时间被拉长到十几分钟甚至更久，而其中绝大多数模块的构建结果与本次改动毫无关系。

这种"改一行、全量跑"的模式带来三重损耗。第一是时间损耗，团队每个人的反馈周期都被拉长，开发节奏被打断。第二是算力损耗，大量无关模块占用构建节点资源，把本可用于其他任务的 CPU 白白消耗掉。第三是成本损耗，在按核时计费的平台上，无差别的全量构建会直接推高月度账单。

问题的根源不在于 Monorepo 本身，而在于构建系统缺少"判断哪些模块真的被改动"的能力。腾讯云 CNB 的按需构建机制，正是为解决这一矛盾而设计的。

二、ifModify：让流水线"看懂"改动范围

CNB 按需构建的核心是 ifModify 配置项。它允许在每个包或模块的流水线声明中，指定一个 glob 路径模式，只有当本次提交改动的文件命中该模式时，这个模块的构建任务才会被触发；反之则直接跳过。

换句话说，ifModify 给每个模块装上了一道"过滤器"。流水线在启动前会先拿到本次事件涉及的文件列表，然后逐个模块比对其 ifModify 声明的路径。命中则执行，未命中则跳过。这样，构建范围就从"整个仓库"精确收缩到"真正被改动的模块集合"。

这套机制建立在 CNB 的 Pipeline/Stage/Job 三层结构之上。一条流水线（Pipeline）由一次触发事件产生，内部划分为多个阶段（Stage），每个 Stage 下可包含多个任务（Job）。Job 的串并行由声明方式决定：jobs 写成对象时并行执行、写成数组时串行执行；而同一触发事件下匹配到的多条 Pipeline 则会并行运行。在 Monorepo 场景下，可以把每个模块的构建声明为一条独立的 Pipeline，各自挂上 ifModify 过滤条件，于是只有命中的构建会真正跑起来，未命中的在调度层就被跳过，不占用任何构建资源。

需要注意的是，ifModify 的路径匹配要足够精确。如果模式写得太宽泛，比如用 ** 匹配所有文件，就等于失去了过滤意义；如果写得太窄，又可能漏掉应当构建的模块。合理的做法是为每个模块声明其实际源码目录，例如 packages/user-service/**，只覆盖该模块自己的文件。

三、基础配置：给每个模块挂上过滤条件

下面是一个典型的 Monorepo 根目录 .cnb.yml 配置示例。仓库下有 packages/user-service 和 packages/order-service 两个模块，每个模块声明自己的 ifModify 路径，只有被改动的那个模块会执行构建脚本。

# 仓库根目录 .cnb.yml
# 用户服务模块：仅当 packages/user-service 目录下的文件被改动时构建
"packages/user-service/**":
  push:
    - name: build-user-service
      ifModify:
        - "packages/user-service/**"
      stages:
        - name: install and build
          script: |
            cd packages/user-service
            npm install
            npm run build

# 订单服务模块：仅当 packages/order-service 目录下的文件被改动时构建
"packages/order-service/**":
  push:
    - name: build-order-service
      ifModify:
        - "packages/order-service/**"
      stages:
        - name: install and build
          script: |
            cd packages/order-service
            npm install
            npm run build

这段配置的关键在于两处 ifModify。当开发者提交一个只改动 packages/user-service/src/index.ts 的 commit 时，流水线会计算改动文件命中的模块，只有 build-user-service 这个 Job 被执行，build-order-service 则被跳过。构建日志里会清晰显示后者因未命中路径而被略过，开发者可以直观地看到"本次只构建了什么"。

对于改动涉及多个模块的情况，比如一次提交同时修改了 user-service 和 order-service，两条模块流水线都会命中并执行。由于它们各自是独立的 Pipeline，在同一触发事件下会并行运行，整体耗时约等于单个模块的构建时长，而不是两者相加。

四、用 include 抽离通用模板，让配置更清爽

随着模块数量增多，每个模块都重复写一遍 stages 构建脚本会显得冗余。CNB 提供了 include 语法，可以把通用的构建阶段抽成独立的模板文件，每个模块只声明自己差异化的部分：ifModify、env 和 include。

假设把通用的构建步骤整理到 cnb/build-template.yml 中，内容如下：

# cnb/build-template.yml —— 通用构建模板
stages:
  - name: install
    script: npm install
  - name: build
    script: npm run build
  - name: test
    script: npm run test

那么根目录 .cnb.yml 就可以大幅精简，每个包只需声明路径过滤、环境变量和引用哪份模板：

# 仓库根目录 .cnb.yml
"packages/user-service/**":
  push:
    - name: build-user-service
      ifModify:
        - "packages/user-service/**"
      env:
        MODULE_NAME: user-service
      include:
        - cnb/build-template.yml

"packages/order-service/**":
  push:
    - name: build-order-service
      ifModify:
        - "packages/order-service/**"
      env:
        MODULE_NAME: order-service
      include:
        - cnb/build-template.yml

这样的分层带来两个好处。其一，通用逻辑集中维护，当构建流程需要调整（比如新增一个 lint 阶段）时，只需修改模板文件，所有模块自动生效，避免逐个文件改动的遗漏风险。其二，每个模块的配置只保留与自身相关的差异信息，可读性更高，新成员加入时也能快速看懂"这个模块构建时做了什么"。

env 字段则用于向模板传递模块级别的变量，例如 MODULE_NAME，让同一份模板能够区分不同模块，避免在模板里硬编码模块名。这种"模板 + 变量 + 路径过滤"的组合，是大规模 Monorepo 保持配置整洁的常用手法。

五、借助 CNB_PIPELINE_NAME 注入模块名做细编排

当流水线需要在脚本内部知道"当前到底在构建哪个模块"时，可以借助 CNB 内置的系统环境变量 CNB_PIPELINE_NAME。这个变量在流水线运行时由平台自动注入，取值为当前 Pipeline 的名称。在 Monorepo 场景下，可以把模块名直接作为 Pipeline 名称声明，于是脚本就能通过读取 CNB_PIPELINE_NAME 获知自身所处的模块上下文。

结合 ifModify 使用，CNB_PIPELINE_NAME 能帮助脚本执行针对性的逻辑，例如把构建产物按模块名分别归档、把测试结果上报到不同的看板，或者在多个模块共用一份镜像构建脚本时区分输出标签。

下面是一个把模块名作为 Pipeline 名称、在脚本中读取并按模块名切换目录的示例片段：

"packages/**":
  push:
    - name: build-user-service
      ifModify:
        - "packages/user-service/**"
      stages:
        - name: resolve module and build
          script: |
            # 读取平台注入的流水线名称，此处即模块名
            echo "本次构建模块：${CNB_PIPELINE_NAME}"
            cd "packages/${CNB_PIPELINE_NAME}"
            npm install
            npm run build

需要说明的是，CNB_PIPELINE_NAME 的具体取值规则以平台官方文档为准，在实际编排中建议先在真实流水线中打印该变量，确认其格式后再编写解析逻辑，避免因假设的格式与实际不符而导致脚本异常。

除了按需构建，合理选择构建节点规格也能进一步控制成本。CNB 提供的构建节点覆盖 amd64 架构（1～64 核，默认 8 核）、arm64/v8 架构（1～16 核，默认 8 核）以及 GPU 节点（固定 16 核、48GB 显存）等多种规格，所有节点最大构建时长为 18 小时，内存默认按 CPU 核数的 2 倍配置。对于 Monorepo 中体量较小的模块，可以声明较低核数的节点，把算力用在刀刃上。

六、按需构建带来的成本与效率收益

按需构建的收益最终会体现在账面上。CNB 社区版云原生构建 CPU 提供 160 核时/月的免费额度，超额部分按 0.125 元/核时计费。核时的计算方式是"核数 × 小时数"，例如 8 核节点运行 1 小时就等于 8 核时。

假设一个包含 10 个模块的 Monorepo，过去每次提交都全量构建，平均每次消耗 20 分钟、折合十几个核时，团队每天提交几十次，月度核时消耗很容易突破免费额度。引入 ifModify 之后，大多数提交只命中 1～2 个模块，构建耗时按比例下降，月度核时用量也随之显著减少，免费额度能够覆盖更长周期，超额支出被压缩。

更重要的是反馈效率的提升。当开发者知道"提交后只会构建我改动的那个模块"时，等待焦虑会大幅降低，提交代码的心理负担变小，提交频率自然提高，这正是持续集成所追求的高频反馈循环。

从效率与成本两个维度看，Monorepo 按需构建都不是锦上添花，而是大仓模式能够长期健康运转的基础设施。它让"统一仓库管理"的便利性与"最小范围构建"的经济性得以兼顾。

七、结语

Monorepo 的价值在于统一管理，而按需构建让这种统一不至于被漫长的全量构建拖累。腾讯云 CNB 通过 ifModify 路径匹配，把"改动影响范围"直接映射为"构建执行范围"，再配合 include 模板复用、CNB_PIPELINE_NAME 注入模块名做细粒度编排，以及按核时计费的弹性成本模型，为多模块大仓提供了一套完整的增量构建方案。无论是十几个还是上百个模块，都能做到"改哪里、构建哪里、其余跳过"。

如果你正在维护一个越改越慢的 Monorepo，不妨把构建流程迁移到腾讯云 CNB 上，用 ifModify 重新定义构建边界，把等待时间还给团队，把算力还给真正需要的模块。

腾讯云 CNB