FAQ 常见问题

反馈问题前，建议先查看对应文档或在以下常见问题和 feedback 中查找。 若未找到答案，请在 feedback 中提交 issue。

触发与配置

流水线为什么没触发？

定位流水线未触发问题，需先理解从触发到执行的流程。

可按此流程逐层排查：

• 代码是否 push 到远端？
• 对应分支是否有 .cnb.yml？ include 的文件是否有权限
• 配置内容无格式、语法问题
• .cnb.yml 是否声明了当前分支的 push 事件流水线？
• 是否命中了 skip 检测？

CNB 默认分支通常为 main，部分从其他平台迁移的仓库可能为 master，请注意区分。

在一个分支配置了另一个分支的流水线，为什么没生效？

.cnb.yml 中的流水线配置只对当前分支生效。在 A 分支配置 B 分支的流水线，B 分支不会按此配置执行，实际取决于各分支自身的 .cnb.yml。

例如，在 main 分支的 .cnb.yml 中配置了 dev 的 push，当 dev 分支 push 时，系统会读取 dev 分支自身的 .cnb.yml，而非 main 分支的。

Fork 仓库为什么不自动触发流水线？

出于安全考虑，Fork 后的仓库默认不会自动触发流水线（包括 Git 操作事件、定时任务事件、Issue 事件）。 如需启用，可在源仓库页面依次进入 设置 -> 云原生构建，勾选「Fork 的仓库默认允许自动触发」。

注意：即使启用了自动触发，Fork 仓库流水线中的 CNB_TOKEN 权限也会被限制在当前仓库范围内。

如何跳过流水线执行？

在 push、commit.add 和 branch.create 事件中，可通过以下两种方式跳过：

• 在 commit message 中添加 [ci skip] 或 [skip ci]：

  git commit -m "docs: update readme [ci skip]"
  git push origin main

• 使用 git push 选项：

  git push origin main -o ci.skip

为什么插件任务拿不到 env / imports 设置的环境变量？

这是脚本任务和插件任务的核心区别之一。插件任务不会接收通过 env 或 imports 声明的自定义环境变量，只能使用 CNB 内置的系统环境变量。

插件任务的参数应通过 settings 传递：

# 错误：env 声明的变量不会传递给插件
- name: wrong
  image: plugins/npm
  env:
    PLUGIN_USERNAME: $NPM_USER

# 正确：通过 settings 传递参数
- name: correct
  image: plugins/npm
  settings:
    username: $NPM_USER

执行与调试

在本地明明好的，为什么在 CI 上跑失败了？

定位此问题，需先明确本地与 CI 环境的区别：

对比项	本地	CI 环境
网络	本地网络（比如一些办公内网）	CI 机器所在网络
文件	本地整个目录下所有文件	Git 仓库对应分支代码
环境	原生	指定的 Docker 容器环境
Shell	本地指定	sh

了解差异后，可依次排查：

• 是否有文件未提交？
• 构建依赖的文件是否命中 .gitignore？
• 是否依赖本地才有的资源（如本地接口、凭证等）？
• CI 声明的 cpus 是否满足要求？
• 本地运行相同镜像获得一致的构建环境进行调试。

docker run --rm -it -v $(pwd):$(pwd) -w $(pwd) cnbcool/default-build-env sh

如何登录到流水线容器调试？

参考登录调试文档。

流水线执行脚本与登录调试结果不一致？

流水线默认使用 sh，登录调试使用 bash，两者语法存在差异。 如果确认流水线容器支持 bash（默认容器支持，自定义容器可能不支持），可以将执行脚本改为：

bash xxx.sh
# 或
bash -c '原来的语句'

流水线超时无输出？

一个 Job 超过 10 分钟无日志输出将被终止。可考虑增加日志输出，例如为 npm install 添加 --verbose 参数。

为什么 PR 流水线中 docker push / git push 失败？

PR 相关事件属于不可信事件，流水线中 CNB_TOKEN 权限受限——代码和制品库仅有只读权限，docker push、git push 等写操作会失败。

解决方案：将涉及推送的任务放到 push、pull_request.target 或 tag_push 等可信事件中执行即可。

为什么公开仓库流水线无法访问私有资源？

如果流水线所在仓库是公开仓库，流水线中的 CNB_TOKEN 只能访问公开资源，不能访问私有代码仓库、私有制品仓库等私有资源。

若需要访问私有资源，可选择以下方式：

• 在私有仓库中触发流水线。
• 调整目标资源的访问范围。
• 自行创建具备所需权限的个人令牌或部署令牌，并在流水线中使用。

没改代码为什么流水线就失败了？

可检查依赖的其他资源是否有变动：

• 插件任务镜像版本是否为 latest，镜像是否有变动。
• CI 配置文件引用的其他仓库文件是否有变动。
• 可能是网络波动，尝试 Rebuild。

如何查看流水线完整日志？

CI 服务将插件任务和脚本任务发送至 Runner 执行。任务日志过长时会被截断返回。 构建完成后，可在日志页面流水线右上角点击日志下载按钮查看完整日志。

缓存与环境

为什么缓存（volumes）有时不生效？

流水线的文件缓存（volumes）是节点级别的，存储在构建节点本地磁盘。默认情况下，每个仓库的流水线分配到固定的 3 个节点执行，因此：

• 跨节点不共享：上次构建在节点 A 写入的缓存，这次如果分配到节点 B，则无法命中。
• 节点可能变化：随着平台扩缩容，分配的节点可能发生变化，旧节点上的缓存不会自动迁移。

如需每次构建都能使用同一份缓存，可以使用 docker:cache 内置任务将缓存构建为 Docker 镜像，实现跨节点缓存。

为什么不提供固定的出口 IP？

CNB 的出口 IP 是动态的，可能随时间变化。

替代方案（需要固定 IP 访问内部服务时）：

• 私有代理：配置自有代理服务器，通过代理路由请求，使用代理的固定 IP
• 跳板机：通过 SSH 跳板机连接目标机器执行命令
• 腾讯云插件：推荐 tencentcom/tcloud-cmd 插件，可远程执行命令，无需白名单配置

如何构建多架构/多平台镜像？

若需要使用 buildx 构建多种架构/平台的镜像，可以开启 rootlessBuildkitd 特性：

main:
  push:
    - docker:
        image: golang:1.24
        services:
          - name: docker
            options:
              rootlessBuildkitd:
                enabled: true
        env:
          IMAGE_TAG: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
        stages:
          - name: go build
            script: ./build.sh
          - name: docker login
            script: docker login -u ${CNB_TOKEN_USER_NAME} -p "${CNB_TOKEN}" ${CNB_DOCKER_REGISTRY}
          - name: docker build and push
            script: docker buildx build -t ${IMAGE_TAG} --platform linux/amd64,linux/arm64 --push .

代码仓库相关

如何解决代码合并冲突？

创建 PR 或在 PR 相关事件构建中遇到代码冲突时，可通过以下命令解决：

git fetch origin
git rebase -i origin/main

# 本地处理冲突
git commit
git push -f

如何彻底删除 Git 仓库里的文件，释放空间？

Git 仓库支持恢复任意历史提交，.git 目录会存储所有历史文件。仅删除工作目录中的文件不会释放空间。

方法一（最简单）：在远端新建仓库，复制需要的文件过去，再改名为原仓库名。 方法二（较复杂）：通过 git filter-branch 命令或第三方工具（如 BFG Repo-Cleaner）在本地彻底删除对应文件后，强制推送到远端，再触发远端仓库 GC 流程。