流水线配置概览

CNB 流水线配置从外到内依次是：触发分支、触发事件、Pipeline、Stage、Job。

main:
  push:
    - name: build
      stages:
        - name: install
          script: npm ci
        - name: test
          script: npm test

常用事件包括：

事件	说明
push	推送代码触发
pull_request	合并请求触发
tag_push	推送 tag 触发
branch.create	创建分支触发

兜底分支可使用 $，通配分支可使用 feature/*、hotfix/* 等 glob 规则。

构建环境与缓存

构建任务可声明 Docker 镜像作为运行环境。

main:
  push:
    - docker:
        image: node:20
      stages:
        - node -v
        - npm ci
        - npm run build

缓存可通过 volumes 声明。

main:
  push:
    - docker:
        image: node:20
      volumes:
        - /root/.npm:copy-on-write
      stages:
        - npm ci
        - npm test

缓存不应被视为必然命中。依赖源变化、镜像变化、任务路径变化或缓存策略变化都可能导致重新下载。

失败处理与排障

流水线失败时，优先看真实构建日志，不要直接在业务代码里盲改。

排查顺序：

1. 查看触发分支和事件是否命中。
2. 查看 .cnb.yml 语法和层级是否符合预期。
3. 查看运行镜像、工作目录、环境变量和依赖安装日志。
4. 查看私有资源访问是否具备令牌或密钥仓库授权。
5. 查看缓存、网络出口、超时和无输出限制。

常见问题：

现象	优先检查
流水线未触发	分支、事件、路径条件、fork 策略
本地正常 CI 失败	镜像环境、Node/Python 版本、系统依赖
插件拿不到变量	插件参数应通过 settings 传入
私有资源无法访问	令牌权限、密钥仓库 allow 规则
日志长时间无输出	命令是否卡住、是否需要分段输出