兜底 FAQ：四类问题，一张排查地图
前面 29 篇讲的是「怎么用」。这篇讲「坏了怎么修」。
CNB 上的问题看似五花八门，归到最后其实就四类。按类找，比按关键词搜快。
一、流水线没跑
先理解链路：git push → 读该分支的 .cnb.yml → 找该分支的 push 配置 → skip 检测 → 执行。
逐层问：
- 代码真推上去了吗
- 那个分支有
.cnb.yml吗（include的文件有权限吗） .cnb.yml里声明了这个分支的push吗- 命中 skip 检测了吗（
ifNewBranch、ifModify、[ci skip]、-o ci.skip）
:::tip 两个高频误解
在 A 分支配置 B 分支的流水线，B 不生效。 每个分支只读自己的 .cnb.yml。
Fork 仓库默认不触发任何流水线。 需要源仓库在 设置 → 云原生构建 勾选允许。
:::
怎么跳过流水线（反向需求）：
git commit -m "docs: update readme [ci skip]"
git push origin main -o ci.skip
二、本地好使，CI 挂
本地和 CI 有五个系统性差异：
| 本地 | CI | |
|---|---|---|
| 网络 | 你的网络 | 构建节点网络 |
| 文件 | 整个目录 | 仓库对应分支代码 |
| 代码 | 源分支 | PR 事件是预合并后的代码 |
| 环境 | 原生 | 指定 Docker 容器 |
| Shell | bash / zsh | sh |
按这个顺序查：
- 有文件没提交吗
- 依赖的文件被
.gitignore排掉了？ - 用了本地才有的接口/凭证？
cpus够吗（内存、并行编译）- PR 事件跑的是预合并代码，目标分支的新提交本地有吗
- 锁文件提交了吗
第 6 条值得单独说。"axios": "^1.0.0" 加上没提交 yarn.lock，含义是每次 CI 都拉最新版。
本地有 node_modules 所以"一直好好的"，CI 全新安装拉到不兼容新版本就炸。
修法：提交锁文件 + 用 npm ci + 在 .cnb.yml 里钉死镜像版本。
想彻底复现 CI 环境：
docker run --rm -it -v $(pwd):$(pwd) -w $(pwd) cnbcool/default-build-env sh
三、权限被拒
这类报错信息通常很模糊，先分清是哪种令牌在拒绝：
PR 事件下 docker push / git push 失败
PR 属于不可信事件，CNB_TOKEN 只读。写操作要放到 push、pull_request.target、tag_push。
公开仓库的流水线访问不了私有资源
公开仓库的 CNB_TOKEN 只能碰公开资源。方案：在私有仓库里跑、或自建令牌。
本地/脚本用令牌拉不动私有仓库
访问令牌对私有资源默认无权限，要手动勾授权范围。另外 HTTPS 认证时用户名固定是 cnb。
四、慢和缓存
缓存（volumes）不命中
缓存是节点级的。每个仓库默认分配固定 3 个节点，上次在 A 写的，这次分到 B 就没命中；扩缩容时节点还会变。
要跨节点稳定命中，用 docker:cache 把缓存做成镜像。
超时无输出
Job 超过 10 分钟无日志会被终止。这是硬限制，timeout 改不了。给命令加 --verbose。
出口 IP 不固定 别给 CNB 出口 IP 加白名单——它是动态的，且等于对公网加白。要固定 IP 就用私有代理、跳板机，或 tcloud-cmd 插件。
多架构镜像
直接 docker buildx build --platform linux/amd64,linux/arm64 --push，一般不需要开 rootlessBuildkitd。
五、几个"不报错但不对劲"
UID/GID 超 65535 的镜像解压失败
CNB 用 uidmap，容器内 UID 限 0-65535。重新做镜像，别用超范围的基础镜像。
流水线上看到的仓库大小和页面不一致
公开仓库的 Fork 在构建节点上共享祖先仓库的 .git，再 OverlayFS 裂变。所以看到的是"祖先 + 子孙"的总和。
流水线执行脚本和登录调试结果不一致
流水线是 sh，调试是 bash。要么改脚本写成 sh 兼容，要么显式 bash xxx.sh。
六、日志看不到全的
任务日志过长会被截断，阶段汇总的日志也会截断（为了页面好展示）。 完整日志在构建完成后，到日志页面右上角点下载。
七、这套教程到这里
30 篇走完，回看一下路线：
- 第 1-5 篇：注册、建仓库、跑通第一条流水线、开云端 VS Code
- 第 6-9 篇：构建环境、触发规则、环境变量、排查与超时
- 第 10-16 篇：密钥、缓存、协作、触发扩展、任务类型、制品库、云原生开发进阶
- 第 17-22 篇：NPC、自定义角色、AI 与知识库、自动合并发版、部署、生态周边
- 第 23-29 篇：账号认证、CLI 与 Skills、定时任务、TAPD、安全扫描、权限、迁移
- 第 30 篇：这张排查地图
如果只记一句话：CNB 的复杂都来自「上下文」——哪个分支、哪个事件、哪个身份、哪份代码。 把这四个说清楚，几乎所有问题都能自己定位。
官方文档在 docs.cnb.cool，遇到本篇没覆盖的，那边有全量参考。 有问题欢迎到 cnb/feedback 提 Issue。