1. 构建缓存

cache 用于缓存流水线中的目录内容（常见如依赖安装目录），可跨 Pipeline、跨 Job、跨分支共享（当 key 相同时，如 main 与 dev 可共享同一缓存）。

• key：当前缓存的唯一标识，类似 Vue 中 v-for 的 key；key 不变则复用缓存，key 变化则丢弃旧缓存。
• 分支/Job 缓存隔离：用 files 指定参与 key 计算的文件，根据文件 hash 判断是否变更，hash 变化则缓存失效；可用 prefix 拼在 file hash 前，避免同一 files 在不同分支/Job 下长期不更新导致缓存一直不失效。
• 缓存内容指定：paths 指定要缓存的目录，配合 key 控制何时更新缓存。
• 未跟踪缓存：untracked: true 表示缓存非 Git 跟踪的内容（如构建产物）；可配合 paths 限定只缓存哪些路径。
• 缓存有效期：GitLab 有缓存清理策略，缓存不保证永久存在；Runner 更换也可能导致缓存失效。代码中应能处理缓存缺失（例如始终保留依赖安装步骤）。

下面示例演示通过 key、paths 以及 key.files + prefix 的用法。

# 示例 1：按提交信息作为 key，paths 指定缓存目录
cache:
  key: ${GITLAB_COMMIT_MESSAGE}
  # 可选 key 策略示例：
  # ${CI_COMMIT_REF_SLUG}              # 不同分支使用不同缓存
  # ${CI_COMMIT_REF_SLUG}-${CI_JOB_NAME} # 不同分支、不同 job 使用不同缓存
  # ${CI_JOB_NAME}                     # 不同分支的同一 job 共用一套缓存
  paths:
    - xxx/xxx
    - node_modules

# 示例 2：缓存未跟踪文件，仅缓存指定路径
cache:
  untracked: true
  paths:
    - xxx/xxx

# 示例 3：基于文件 hash 的 key，配合 prefix 做分支/Job 隔离
cache:
  key:
    files:
      - package-lock.json   # 以该文件 hash 参与 key 计算，文件变更则缓存失效
    prefix: ${CI_JOB_NAME}  # key 形式为 prefix-hash
  paths:
    - vendor/

2. 产物缓存

artifacts 用于保存 Job 的构建产物（如编译结果、配置文件、node_modules 等），供后续 Job 下载使用。产物会占用 GitLab 服务端存储，需注意设置过期时间。

build-web:
  stage: build
  script:
    - 运行脚本
  artifacts:
    path: dist/*        # 构建产物所在路径
    expire_in: 1 week  # 产物保留时长，过期后清除；默认约 30 天

3. 使用专用 Runner

通过 tags 指定 Job 只在带对应标签的 Runner 上执行，实现精确调度，将资源密集型任务（如镜像构建、大体积编译）放到专用 Runner，避免与共享 Runner 上的其他任务争抢资源。可自定义标签（如 docker-build、gpu、node）并在部署 Runner 时配置。

build_job:
  tags:
    - docker-build   # 仅在有此标签的 runner 上运行
  script: docker build ..

4. 并行任务

通过 parallel 的 matrix 将同一 Job 按维度拆成多个子 Job 并行运行，常用于测试（如 unit、integration、e2e）或多环境组合，从而缩短总构建时间。

# 单维度：按 TEST_SUITE 拆成 3 个并行 job
test:
  script: ./run-tests.sh $TEST_SUITE
  parallel:
    matrix:
      - TEST_SUITE: ["unit", "integration", "e2e"]

# 等价于：test:unit、test:integration、test:e2e 三个 job，继承 test 的其余配置

# 多维度：TEST_SUITE × OS 共 4 种组合，并行执行
test:
  script: ./run-tests.sh $TEST_SUITE on $OS
  parallel:
    matrix:
      - TEST_SUITE: ["unit", "e2e"]
        OS: ["linux", "windows"]
# 组合为：unit+linux、unit+windows、e2e+linux、e2e+windows

5. 模板抽离复用

对重复出现的配置（如相同构建命令、cache、artifacts），可抽成独立模板文件，通过 include 引入、extends 继承，使根目录 .gitlab-ci.yml 更简洁，并实现标准流程复用、降低维护成本。

• 以 . 开头的 job 名（如 .build_template）不会单独执行，仅作为模板被其他 job 通过 extends 继承；若不以 . 开头，被 include 后该文件中的 job 会直接参与流水线执行。
• include 支持四种来源：
  • local：项目内路径，相对当前项目根目录。
  • file：其他项目的 YAML 路径，实现跨项目配置共享。
  • template：GitLab 内置模板名称。
  • remote：通过 HTTP/HTTPS 拉取远程 YAML（需可公开访问）。
• extends：在 job 下声明要继承的模板 job 名，合并后得到最终 job 配置。

下面示例：模板中定义脚本与 cache，主配置通过 include + extends 复用。

# .gitlab/ci-templates.yml
.build_template:
  script: mvn clean package
  cache:
    key: maven-${CI_COMMIT_REF_SLUG}
    paths: [.m2/]

# .gitlab-ci.yml
include:
  - local: .gitlab/ci-templates.yml
# 或简写：include: .gitlab/ci-templates.yml

build-java:
  extends: .build_template
# 展开后等价于：
# build-java:
#   script: mvn clean package
#   cache:
#     key: maven-${CI_COMMIT_REF_SLUG}
#     paths: [.m2/]

参考内容

• GitLab CI 模板与 include 示例
• GitLab CI/CD 官方文档