规则陷阱

• rules: 与 only:/except: 不能混用 — 每个 job 中只能使用其中一种
• 首个匹配的规则优先生效 — 请将更具体的规则置于更通用的规则之前
• 缺失 when: 时默认为 on_success — 例如 rules: - if: $CI_COMMIT_TAG 仅在打 tag 时运行
• 空规则数组 rules: [] 表示永不运行 — 这与完全不定义 rules 的行为不同
• 可在规则末尾添加 - when: never 防止“穿透执行”（fallthrough）— 否则未匹配任何条件的 job 仍可能运行

静默失败

• 受保护变量在非受保护分支上不可用 — job 仍会运行，但对应变量为空
• Runner 标签不匹配 — job 将无限期处于 pending 状态，且无任何错误提示
• 在非特权（non-privileged）Runner 上运行 docker:dind — 会触发难以理解的 Docker 错误
• 掩码变量（masked variable）格式无效 — 变量仍可能以明文形式暴露在日志中

YAML 合并陷阱

• extends: 不支持数组深度合并 — script、variables 等数组会被整体替换，而非追加
• 使用 !reference [.job, script] 实现复用 — 例如：script: [!reference [.base, script], "my command"]
• include: 引入的文件之间可能发生键冲突 — 相同 key 以最后引入的文件内容为准
• 锚点（anchors）&/* 无法跨文件生效 — 跨文件复用请改用 extends:

Artifacts 与 Cache 的区别

• Cache 无法保证在多次运行间持续存在 — 应视作性能优化手段，而非必要依赖
• Artifacts 默认按 stage 自动下载 — 若无需下载，可显式设置 dependencies: []
• needs: 默认下载所依赖 job 的 artifacts — 如需跳过，可写为 needs: [{job: x, artifacts: false}]

Docker-in-Docker

• 共享 Runner 通常不支持 privileged 模式 — 需使用自托管 Runner 或特殊配置
• 必须设置 DOCKER_HOST: tcp://docker:2375 — 否则 job 将连接到错误的 Docker 守护进程
• 需设置 DOCKER_TLS_CERTDIR: "" 或正确配置 TLS — TLS 配置不完整会导致构建失败

流水线触发器

• CI_PIPELINE_SOURCE 的取值取决于触发方式 — 可能为 push、merge_request_event、schedule、api 或 trigger
• MR 流水线需显式添加 rules: - if: $CI_MERGE_REQUEST_IID — 仅靠分支规则不足以覆盖 MR 场景
• 分离式（detached）与合并结果式（merged result）流水线的区别 — 前者基于源分支测试，后者基于合并后的代码测试