GitLab CI YAML编写教程：5个方法

▌ 技术引导
GitLab CI YAML 是自动化构建与部署的核心配置文件。2024 年起，主流项目开始采用更精细化的配置策略。我见过最实用的是用变量分离和模板组合提升可维护性。比如，`variables` 部分定义 `CI_REGISTRY_IMAGE` 和 `CI_COMMIT_REF_NAME`，再用 `include` 引入通用模板。这样避免重复代码，也方便多环境切换。还有个坑，是 `only` 和 `rules` 的组合使用，容易因为权限或分支条件错误导致流水线卡死。真实场景中我用 `rules` 替代 `only`，更灵活控制触发条件。记得用 `script` 里直接写 `docker build` 命令，不要依赖脚本，这样 CI 服务能识别并加速。另外，`artifacts` 和 `cache` 的使用必须精准，否则会占用大量存储空间，甚至触发 GCP 限制。最后，`stages` 要按依赖关系排序，否则会因为前置任务未完成而失败。

▌ 技术引导
实际配置中，我习惯用 `before_script` 预处理环境变量和依赖安装，比如 `before_script:` 下写 `apt-get update && apt-get install -y python3-pip`，避免在每个 job 中重复。有些项目用 `CI_JOB_TOKEN` 来拉取私有仓库镜像，这在共享 runner 环境里特别关键。2025 年起，GitLab 添加了 `CI/CD` 的 pipeline 缓存机制，可以配合 `cache` 实现快速构建。但注意，只有 `artifacts` 会保留到下一个 job，`cache` 则是临时存储。我见过有人在 `cache` 中放编译产物，结果因为路径错误导致缓存失效。真实案例中，使用 `cache:key` 来标识缓存版本，能避免无意义的重新下载。还有个细节是 `only:variables` 的使用，它能根据变量值决定 pipeline 是否执行，这在多环境部署时非常有用。

▌ 技术参考
一 技术背景与核心概念
GitLab CI YAML 是 GitLab CI/CD 流水线的核心配置语言。它是基于 YAML 的声明式配置，允许开发者通过简单的语法定义构建、测试和部署任务。2024 年，GitLab 引入了 `rules` 机制，替代了传统的 `only` 和 `except`，使得流水线的触发逻辑更加直观且具备动态判断能力。配置文件通常位于 `.gitlab-ci.yml`，每个 job 代表一个独立的构建阶段，如 `build`、`test`、`deploy`。YAML 文件支持继承和重写，可以将通用配置提取到单独的 YAML 文件中，再通过 `include` 引入。这种方式有效减少冗余配置，提高代码可读性和维护性。

二 具体操作方法或配置步骤
编写 GitLab CI YAML 需要遵循基本结构，每个 job 对应一个 stage。如果你使用的是 `.gitlab-ci.yml` 文件，可以在根目录下直接编辑。例如，`build` stage 通常包含构建镜像的步骤，可以写成：
```yaml
build:
stage: build
script:
- docker build -t my-image .
only:
- main
```
对于更复杂的项目，建议将配置模块化。创建 `templates/` 目录，将通用 job 放入单独的 YAML 文件，如 `common_jobs.yml`，再通过 `include` 引入。2026 年起，GitLab 支持 `include` 的 `template` 类型，允许从远程 URL 引入配置，这在多项目协同时非常高效。此外，`variables` 部分可以定义环境变量，如：
```yaml
variables:
CI_REGISTRY_IMAGE: "registry.gitlab.com/my-group/my-project"
```
这些变量可以在后续 job 中引用，比如 `CI_REGISTRY_IMAGE` 用于构建镜像。

三 常见踩坑场景与避坑方案
在实际配置中，常见问题是 job 无法正确触发，导致 pipeline 停滞。比如，当你使用 `only` 定义分支，却忘记在 `rules` 中增加 `variables` 条件，结果 job 被忽略。另一个坑是 `stages` 顺序错误，导致某些 job 在依赖任务未完成前执行，引发失败。2024 年，我曾因为 `stages` 没有按 `build -> test -> deploy` 顺序排列，导致单元测试在镜像未构建前就运行，产生错误日志。解决方法是手动排序 `stages`，确保依赖关系正确。此外，`script` 脚本中遗漏 `exit 0` 或 `exit 1`，会导致流水线无法正确判断任务是否成功。例如，`docker build` 如果构建失败，必须确保脚本返回非零状态码，否则会继续执行后续 job。可以通过 `if` 条件判断来实现，比如 `if: "$CI_COMMIT_REF_NAME == 'main'"`，确保分支逻辑无误。

四 性能影响或效率对比
GitLab CI YAML 的配置方式直接影响流水线的性能。使用 `rules` 替代 `only` 能提升判断效率，因为 `rules` 是按条件逐行评估，而 `only` 是列表匹配，前者在多个条件组合时更高效。2025 年，GitLab 引入了 `cache` 优化机制，允许在 `build` 和 `test` 阶段复用依赖包，减少下载时间。比如，配置 `cache: key: "$CI_COMMIT_REF_NAME" paths: - node_modules/` 能确保不同分支的缓存独立。同时，`artifacts` 用来保存构建产物，如 `artifacts: paths: - dist/`，方便后续 job 使用。不过，缓存机制有时会因为路径错误或签名不一致导致问题，例如 `cache:key` 没有正确配置，会导致每次构建都重新缓存，浪费资源。因此，配置时需注意路径和变量的正确性。

五 适用场景与局限性
GitLab CI YAML 适用于需要自动化构建、测试和部署的项目，尤其适合 CI/CD 集成度高的团队。在 2025 年的项目中，我看到很多团队将 YAML 配置拆分成多个文件，通过 `include` 来复用。这种做法在微服务架构中特别常见，每个服务有自己的 YAML 文件，统一管理。但 YAML 的局限性在于，它无法处理复杂的条件逻辑，尤其当 job 之间存在多层依赖时，容易写出难以维护的配置。此外，YAML 的缩进和格式要求严格，一旦错误会导致 pipeline 无法启动。2026 年，GitLab 引入了 YAML 校验工具，可以在提交时提示格式问题，但这并不能完全避免错误。因此，在大规模项目中，建议使用 CI/CD 管理工具，如 `gitlab-ci-multi-runner`，来辅助配置校验和优化。

六 替代方案或进阶技巧
对于更复杂的流水线，可以使用 `gitlab-ci-multi-runner` 来增强 runner 的功能。这个工具能在本地运行 runner，支持更灵活的环境配置，尤其适合私有仓库和多分支部署。2024 年后，`gitlab-ci-multi-runner` 支持 `CI/CD` 的 `cache` 和 `artifacts` 功能，提升构建效率。此外，可以利用 `CI_JOB_TOKEN` 来拉取私有镜像，确保安全性。例如，`script: docker pull $CI_REGISTRY_IMAGE` 会使用对应的 token 进行认证。进阶技巧包括使用 `variables` 动态生成配置，例如：
```yaml
variables:
DOCKER_REGISTRY: "registry.gitlab.com"
OTHER_REPOS: "https://gitlab.com/other-project"
```
再结合 `include` 来动态组合 job，提升配置复用性。同时，可以使用 `CI_COMMIT_SHA` 来标记每次构建的唯一标识，方便日志追踪和回滚。这些方法在 2025 年的项目中被广泛应用，能显著减少配置重复和维护成本。

七 技术背景与核心概念
YAML 在 GitLab CI/CD 中扮演重要角色，特别是在多项目协作中。2026 年，GitLab 引入了 YAML 模块化配置，使得大型项目可以将 common job 放入共享文件。比如，`common_jobs.yml` 中定义通用 job，再在主配置文件中通过 `include` 引入。这种方式不仅提升可读性，还能减少配置错误的风险。每个 job 都有 `stage` 指定阶段，`variables` 定义环境变量，`script` 执行命令，`only` 和 `rules` 控制触发条件。YAML 的结构清晰，但也容易因为缩进或冒号错误导致解析失败，尤其是在使用 `include` 和 `rules` 时，需要格外注意语法。

八 具体操作方法或配置步骤
使用 `include` 时，确保路径正确。例如，`include: - local: 'templates/common_jobs.yml'` 会在本地加载配置文件。如果配置文件存在于远程 GitLab 仓库，可以使用 `remote: 'https://gitlab.com/.../common_jobs.yml'`。2025 年后，GitLab 支持 `include` 的 `template` 类型，允许从私有仓库拉取配置，这在共享配置时非常有用。每个 job 必须有 `stage`，确保任务按顺序执行。例如，`build:stage: build`，`test:stage: test`。如果 job 没有指定 `stage`，默认会被归为 `build` 阶段。此外，`variables` 部分可定义环境变量，如：
```yaml
variables:
CI_REGISTRY_IMAGE: "registry.gitlab.com/my-group/my-project"
```
这些变量可用于 `script` 中，如 `docker build -t $CI_REGISTRY_IMAGE .`，提高配置复用度。记得每个 job 都要有唯一的 `job_name`，否则会报错。

九 常见踩坑场景与避坑方案
在实际配置中，最常见的坑是 `rules` 和 `only` 的误用。例如，误将 `rules` 写成 `only`，导致 job 不按预期触发。另外，`script` 中未正确处理错误，比如 `docker build` 构建失败后未返回非零码，导致流水线继续执行，产生错误日志。解决方法是使用 `if` 条件判断任务是否成功，并在 `script` 中添加 `exit 0` 或 `exit 1`。例如：
```yaml
build:
stage: build
script:
- docker build -t my-image .
- exit $?
```
这样能确保任务失败时停止流水线。还有个坑是 `before_script` 中未正确设置环境变量，导致 `CI_REGISTRY_IMAGE` 无法解析。例如，`CI_REGISTRY_IMAGE` 在 `stage: build` 中使用，但在 `before_script` 中未定义，会导致空值。解决方式是确保所有变量在 `variables` 中定义，并在 `before_script` 中引用，避免因变量未定义导致任务失败。

十 性能影响或效率对比
YAML 配置对流水线性能有一定影响，尤其是在 job 依赖复杂时。合理的 `stages` 排序能减少不必要的任务执行，提高流水线效率。例如，将 `build` 放在 `test` 前，确保测试依赖构建产物。使用 `cache` 可以保存依赖包，减少重复下载，例如：
```yaml
cache:
key: "$CI_COMMIT_REF_NAME"
paths:
- node_modules/
```
这样在多次构建时，只需下载一次依赖。但如果不小心配置错误，如 `cache:key` 未正确生成，会导致每次构建都重新下载，浪费时间和资源。因此，建议使用 `CI_COMMIT_REF_NAME` 和 `CI_COMMIT_SHA` 来生成唯一缓存键。同时，`artifacts` 用于保存构建产物，如 `dist/` 目录，确保后续 job 能使用。如果未正确配置 `artifacts`，会导致任务间依赖失效，影响构建准确性。

十一 适用场景与局限性
GitLab CI YAML 的适用场景包括持续集成、自动化测试和部署。2024 年后，很多团队开始将 YAML 配置拆分成模块，提升维护性。例如，将构建、测试、部署任务拆分为不同 YAML 文件，再通过 `include` 引入。这种方式在多项目协作中非常高效，但需要注意每个 job 的唯一性，否则会因为重复名称导致冲突。YAML 的语法严格，尤其是在使用 `rules` 和 `include` 时，稍有缩进错误就会导致解析失败。此外，`CI_REGISTRY_IMAGE` 和 `CI_JOB_TOKEN` 等变量必须正确配置，否则无法拉取私有镜像或执行任务。2025 年后，GitLab 引入了变量校验工具，可以在提交时提示变量未定义问题，但这并不能完全避免错误。

十二 替代方案或进阶技巧
如果 YAML 配置过于复杂，可以考虑使用 GitLab CI 的高级 runner 功能，如 `gitlab-runner` 的 `config.toml` 来管理 runner 配置，分离 job 与 runner 的关系。这种方式在大规模项目中更灵活，能支持更多 runner 类型，如 Kubernetes、Docker、SSH 等。此外，可以结合 `CI/CD` 的 `variables` 机制，使用 `CI_COMMIT_BRANCH` 和 `CI_COMMIT_REF_NAME` 来动态生成 job 名称，例如：
```yaml
job-name:
stage: build
script:
- echo "Building for branch: $CI_COMMIT_BRANCH"
```
这能提升配置的动态性。2026 年，GitLab 引入了 `CI_JOB_TOKEN` 的自动配置，使得私有镜像拉取更简单。同时，可以使用 `CI_PIPELINE_IID` 来标识 pipeline 唯一 ID，方便日志追踪和问题排查。这些技巧在实际项目中被广泛应用，能显著提升配置灵活性和维护效率。

十三 技术背景与核心概念
YAML 作为 GitLab CI 的配置语言，其优势在于结构清晰、语法直观。2024 年，GitLab 引入了 `rules` 机制，使得 job 触发逻辑更灵活。例如，`rules` 可以根据变量值动态判断是否执行任务，比传统的 `only` 更强大。每个 job 都有 `script` 字段，用于执行命令。例如，`docker build -t my-image .` 是常见的构建命令，配合 `CI_REGISTRY_IMAGE` 能确保镜像发布到私有仓库。另外，`variables` 是配置中的关键部分，用于存储敏感信息或环境参数，如 `CI_JOB_TOKEN` 和 `CI_REGISTRY_IMAGE`。这些变量能提升配置的可维护性，避免硬编码。

十四 具体操作方法或配置步骤
配置 `variables` 时，建议将敏感信息如 token、密码等存入 GitLab 的 `CI/CD` 变量管理中。例如，`CI_REGISTRY_IMAGE` 可以在项目设置中定义，而非直接写入 YAML。这样能避免泄露敏感信息。使用 `rules` 时，注意每个条件的优先级，确保逻辑正确。例如：
```yaml
rules:
- if: "$CI_COMMIT_BRANCH == 'main'"
when: always
- if: "$CI_COMMIT_BRANCH == 'feature/'"
when: on_failure
```
这种组合能实现分支特定的构建策略。此外，`cache` 和 `artifacts` 的配置要精准，避免因路径错误导致缓存失效。例如，`cache: key: "$CI_COMMIT_REF_NAME" paths: - /path/to/cache/` 能确保不同分支的缓存独立。配置时也需要注意 `job_name` 的唯一性，否则会导致冲突并报错。

十五 常见踩坑场景与避坑方案
在使用 `rules` 时，常见的问题包括条件表达式错误，如 `$CI_COMMIT_BRANCH` 拼写错误或未正确使用引号。例如，`if: "$CI_COMMIT_BRANCH == 'main'"` 中的双引号必须保留，否则会报错。另一个坑是 `before_script` 中未正确处理依赖，导致 `script` 阶段报错。比如，`docker build` 需要 `docker` 命令存在，但如果没有在 `before_script` 中安装，会导致 job 失败。解决方式是确保 `before_script` 中包含必要的依赖安装命令，如 `apt-get install -y docker.io`。此外，`artifacts` 未正确配置会导致后续 job 无法获取构建产物，例如 `artifacts: paths: - dist/` 中的 `dist/` 目录不存在，会导致 job 报错。建议在 `script` 中添加 `mkdir -p dist/`，确保路径存在。这些经验在 2025 年的项目中被反复验证，避免了不必要的构建错误。