GitLab CI/CD 完整教学指南

第一章：GitLab CI/CD 核心概念

1.1 什么是 GitLab CI/CD

GitLab CI/CD 是 GitLab 内置的持续集成/持续部署工具，通过 .gitlab-ci.yml 配置文件定义自动化流水线，实现代码提交后的自动构建、测试、部署等全流程。

核心特点：

无需额外部署 CI 工具
支持多种编程语言和技术栈
与 GitLab 代码仓库深度集成
配置简单，基于 YAML 语法

1.2 核心组件与工作流程

核心组件关系图

复制代码

代码提交 → GitLab 检测 .gitlab-ci.yml → 匹配 Runner → 执行流水线 → 输出结果
                     ↑
              (配置触发条件、任务、环境)

核心概念解析

1. 流水线（Pipeline）

一次完整的自动化流程
包含多个按顺序执行的阶段
示例：代码提交触发的「构建+测试+部署」流程

2. 阶段（Stage）

流水线的逻辑步骤
同一阶段的任务并行执行
前一阶段全部成功才进入下一阶段
自定义示例：[install, lint, test, build, deploy]

3. 任务（Job）

阶段内的具体执行单元
每个 Job 独立配置执行环境和命令
示例：安装依赖、运行测试、构建项目

4. GitLab Runner

流水线的执行载体
通过标签与 Job 匹配
支持多种部署方式（本地、服务器、容器）

5. 产物（Artifacts）

Job 执行后生成的文件
可传递给后续 Job 或手动下载
示例：构建后的 dist 目录、APK 文件

6. 缓存（Cache）

缓存依赖文件加速后续构建
示例：node_modules、Flutter pub cache
支持按分支、Job 类型差异化缓存

第二章：.gitlab-ci.yml 配置详解

2.1 YAML 语法基础

基本规范：

yaml 复制代码

# 缩进使用 2 个空格（禁止 Tab）
key: value  # 冒号后必须加空格

# 列表使用横杠
stages:
  - install
  - build

# 注释以 # 开头
variables:
  NODE_ENV: production  # 生产环境变量

2.2 核心配置项

全局配置

yaml 复制代码

# 定义阶段顺序
stages:
  - install
  - lint
  - test
  - build
  - deploy

# 全局变量
variables:
  NODE_ENV: "production"
  DIST_DIR: "dist"

# 全局前置/后置脚本
before_script:
  - npm config set registry https://registry.npmmirror.com/

# 全局缓存
cache:
  key: $CI_COMMIT_BRANCH
  paths:
    - node_modules/

Job 核心配置

yaml 复制代码

job-name:
  stage: build                    # 所属阶段
  tags: [frontend, node18]        # 匹配 Runner 标签
  script:                         # 执行命令
    - npm install
    - npm run build
  artifacts:                      # 构建产物
    paths:
      - dist/
    expire_in: 7 days
  rules:                          # 触发条件
    - if: $CI_COMMIT_BRANCH == "main"
  cache:                          # Job 缓存
    key: $CI_COMMIT_BRANCH
    paths: [node_modules/]
    policy: pull

2.3 常用变量

内置变量：

$CI_COMMIT_BRANCH：当前提交分支
$CI_COMMIT_TAG：提交标签
$CI_PROJECT_DIR：仓库在 Runner 中的根目录

自定义变量：

在 .gitlab-ci.yml 的 variables 中定义
在 GitLab 仓库「设置→CI/CD→变量」中配置（适合敏感信息）

第三章：GitLab Runner 深度解析

3.1 Runner 核心概念

Runner 是 GitLab CI/CD 的实际执行节点，负责：

接收 GitLab 下发的任务
在指定环境中执行 Job 命令
反馈执行结果给 GitLab

3.2 Runner 分类

按部署位置划分

类型	适用场景	优势	劣势
本地 Runner	开发调试、本地验证	环境可控、调试便捷	资源占用、仅本人可用
服务器 Runner	团队协作、正式流水线	稳定在线、资源充足	需维护服务器
容器化 Runner	多环境隔离、快速切换	环境纯净、版本灵活	需 Docker 基础

按权限范围划分

类型	覆盖范围	适用场景
项目级 Runner	单个 GitLab 项目	项目环境特殊、需专属资源
组级 Runner	GitLab 组下所有项目	同组项目技术栈一致
共享 Runner	GitLab 实例所有项目	通用任务、公共资源

3.3 Runner 注册全流程

注册前准备

下载 Runner 客户端
- 官方下载地址：https://docs.gitlab.com/runner/install/
- 选择与系统对应的版本
获取注册凭证
- 项目级：项目 → 「设置」→ 「CI/CD」→ 「Runners」
- 组级：组 → 「设置」→ 「CI/CD」→ 「Runners」
选择执行器
- Shell：直接在本机终端执行命令
- Docker：在指定容器中执行命令（推荐）

各系统注册步骤

Windows 系统（Shell 执行器）：

cmd 复制代码

# 进入 Runner 目录
cd D:\GitLab-Runner

# 执行注册
gitlab-runner register

# 启动 Runner
gitlab-runner start

macOS 系统（Docker 执行器）：

bash 复制代码

# 使用 brew 安装
brew install gitlab-runner

# 注册
gitlab-runner register

# 启动
brew services start gitlab-runner

Linux 系统（Shell 执行器）：

bash 复制代码

# 添加仓库并安装
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt-get install gitlab-runner

# 注册（需要 sudo）
sudo gitlab-runner register

# 启动
sudo gitlab-runner start

3.4 标签系统与匹配规则

标签匹配核心规则

Job 的 tags 必须完全匹配 Runner 的标签
同一标签可绑定多个 Runner，实现负载均衡
无标签的 Job 仅匹配无标签的 Runner

前端标签设计体系

yaml 复制代码

# 分层标签设计
tags:
  - frontend          # 一级分类：前端任务
  - linux             # 系统环境：Linux
  - node18            # 技术栈：Node.js 18
  - vue3              # 框架：Vue 3
  - deploy            # 功能：部署任务

常用标签组合

场景	标签组合	说明
Vue 项目构建	`[frontend, linux, node18, vue]`	Linux 服务器 Vue 构建
Flutter 安卓打包	`[frontend, linux, flutter3, pack-apk]`	Flutter Android 打包
UniApp 小程序	`[frontend, windows, uniapp, pack-mp]`	Windows 小程序打包

3.5 Runner 管理与维护

基础管理命令

操作	Windows	macOS	Linux
启动	`gitlab-runner start`	`brew services start gitlab-runner`	`sudo gitlab-runner start`
停止	`gitlab-runner stop`	`brew services stop gitlab-runner`	`sudo gitlab-runner stop`
重启	`gitlab-runner restart`	`brew services restart gitlab-runner`	`sudo gitlab-runner restart`
查看状态	`gitlab-runner status`	`brew services list`	`sudo gitlab-runner status`

环境一致性保障

Docker 执行器（推荐）：

yaml 复制代码

job-name:
  image: node:18-alpine  # 指定 node 版本
  tags: [frontend, docker]

非 Docker 执行器：

bash 复制代码

# 在 Runner 中固定环境
nvm install 18.17.0
nvm use 18.17.0

常见问题排坑

问题现象	原因	解决方案
Job 一直 pending	标签不匹配/Runner 离线	检查标签匹配、启动 Runner
命令未找到	环境依赖缺失	安装对应依赖或使用 Docker
权限不足	Runner 用户无权限	配置用户权限或 SSH 密钥

第四章：前端项目实战配置

4.1 Vue + TypeScript 项目

yaml 复制代码

stages:
  - install
  - lint-test
  - build
  - deploy

variables:
  NODE_ENV: production
  DIST_DIR: dist

before_script:
  - npm config set registry https://registry.npmmirror.com/

install-deps:
  stage: install
  tags: [frontend, node18]
  cache:
    key: $CI_COMMIT_BRANCH
    paths:
      - node_modules/
      - .npm/
  script:
    - npm install

lint-and-test:
  stage: lint-test
  tags: [frontend, node18]
  cache:
    key: $CI_COMMIT_BRANCH
    paths: [node_modules/]
    policy: pull
  script:
    - npm run lint
    - npm run test

build-project:
  stage: build
  tags: [frontend, node18]
  cache:
    key: $CI_COMMIT_BRANCH
    paths: [node_modules/]
    policy: pull
  script:
    - npm run build
  artifacts:
    paths: [$DIST_DIR/]
    expire_in: 7 days
  rules:
    - if: $CI_COMMIT_BRANCH in ["dev", "test", "main"]

deploy-prod:
  stage: deploy
  tags: [frontend, node18]
  dependencies: [build-project]
  script:
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
    - ssh-keyscan -H $SERVER_HOST >> ~/.ssh/known_hosts
    - scp -r $DIST_DIR/* $SERVER_USER@$SERVER_HOST:$SERVER_PATH
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  when: manual

4.2 Flutter 项目

yaml 复制代码

stages:
  - pub-get
  - analyze
  - build-apk

variables:
  FLUTTER_VERSION: 3.19.0
  APK_DIR: build/app/outputs/apk/release

image: cirrusci/flutter:$FLUTTER_VERSION

pub-install:
  stage: pub-get
  tags: [flutter, linux]
  cache:
    key: flutter-pub-$FLUTTER_VERSION
    paths:
      - ~/.pub-cache/
      - $CI_PROJECT_DIR/.dart_tool/
  script:
    - flutter pub get

code-analyze:
  stage: analyze
  tags: [flutter, linux]
  cache:
    key: flutter-pub-$FLUTTER_VERSION
    paths: [~/.pub-cache/]
    policy: pull
  script:
    - flutter analyze
    - flutter format --set-exit-if-changed .

build-android-apk:
  stage: build-apk
  tags: [flutter, linux]
  cache:
    key: flutter-pub-$FLUTTER_VERSION
    paths: [~/.pub-cache/]
    policy: pull
  script:
    - echo "$ANDROID_KEY_STORE" | base64 -d > android/app/key.jks
    - export KEY_STORE_PASSWORD=$ANDROID_KEY_STORE_PWD
    - export KEY_ALIAS_PASSWORD=$ANDROID_KEY_ALIAS_PWD
    - export KEY_ALIAS=$ANDROID_KEY_ALIAS
    - flutter build apk --release --build-number $CI_PIPELINE_ID
  artifacts:
    paths: [$APK_DIR/app-release.apk]
    expire_in: 10 days
  rules:
    - if: $CI_COMMIT_BRANCH == "release"

4.3 UniApp 项目

yaml 复制代码

stages:
  - install
  - build-mp-weixin
  - build-app-android

variables:
  HX_PATH: /Applications/HBuilderX.app/Contents/MacOS
  APP_ID: __UNI__XXXXXX

before_script:
  - npm install
  - npm install @dcloudio/uni-cli-shared

install-uni-deps:
  stage: install
  tags: [uniapp, macos]
  cache:
    key: uniapp-deps
    paths: [node_modules/]
  script: [npm install]

build-mp:
  stage: build-mp-weixin
  tags: [uniapp, macos]
  cache:
    key: uniapp-deps
    paths: [node_modules/]
    policy: pull
  script:
    - $HX_PATH/cli publish --platform mp-weixin --project $CI_PROJECT_DIR --appid $APP_ID
  artifacts:
    paths: [dist/dev/mp-weixin/]
    expire_in: 3 days

build-android:
  stage: build-app-android
  tags: [uniapp, macos]
  cache:
    key: uniapp-deps
    paths: [node_modules/]
    policy: pull
  script:
    - $HX_PATH/cli publish --platform android --project $CI_PROJECT_DIR --appid $APP_ID --signature $ANDROID_SIGN
  artifacts:
    paths: [unpackage/release/apk/]
    expire_in: 7 days
  rules:
    - if: $CI_COMMIT_TAG

第五章：注册凭证获取与管理

5.1 凭证类型与权限要求

权限要求：

项目级：项目「所有者」或「维护者」
组级：GitLab 组「所有者」或「维护者」
实例级：GitLab 管理员

5.2 获取步骤

项目级凭证获取

进入项目 → 「设置」→ 「CI/CD」
展开「Runners」模块
复制「GitLab instance URL」和「Registration token」

组级凭证获取

进入群组 → 「设置」→ 「CI/CD」
展开「Runners」模块
复制 URL 和「Group runners」的 Token

5.3 API 方式（新版推荐）

bash 复制代码

# 创建访问令牌后调用 API
curl --request POST \
  --url "https://gitlab.example.com/api/v4/user/runners" \
  --data "runner_type=project_type" \
  --data "project_id=项目ID" \
  --data "description=frontend-runner" \
  --data "tag_list=frontend,node18,vue3" \
  --header "PRIVATE-TOKEN: 访问令牌"

5.4 注意事项

URL 必须包含末尾斜杠
Token 需妥善保管，防止泄露
不同级别凭证不可混用
定期检查 Token 有效性

第六章：高级特性与最佳实践

6.1 缓存优化策略

yaml 复制代码

cache:
  key: $CI_COMMIT_BRANCH
  paths:
    - node_modules/
    - .npm/
  policy: push  # 安装阶段推送缓存

test-job:
  cache:
    key: $CI_COMMIT_BRANCH
    paths: [node_modules/]
    policy: pull  # 测试阶段仅拉取缓存

6.2 多环境配置

yaml 复制代码

.deploy-template: &deploy
  stage: deploy
  tags: [frontend, deploy]
  script:
    - echo "Deploying to $ENVIRONMENT"
    - ./deploy.sh $ENVIRONMENT

deploy-staging:
  <<: *deploy
  variables:
    ENVIRONMENT: staging
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"

deploy-production:
  <<: *deploy
  variables:
    ENVIRONMENT: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  when: manual

6.3 安全最佳实践

敏感信息保护
- 使用 GitLab CI/CD 变量存储密钥
- 勾选「保护」和「隐藏」选项
- 定期轮换凭证
资源优化
- 合理配置缓存策略
- 使用 needs 关键字优化依赖
- 设置合理的 artifacts 过期时间
错误处理
- 配置重试机制
- 设置超时时间
- 使用 when: on_failure 处理失败场景

第七章：本地开发与调试

7.1 本地部署 GitLab

bash 复制代码

# 使用 Docker 快速部署
docker run --detach \
  --hostname localhost \
  --publish 443:443 --publish 80:80 --publish 22:22 \
  --name gitlab \
  --restart always \
  --volume gitlab-config:/etc/gitlab \
  --volume gitlab-logs:/var/log/gitlab \
  --volume gitlab-data:/var/opt/gitlab \
  gitlab/gitlab-ce:latest

7.2 本地 Runner 配置

bash 复制代码

# 拉取并运行 Runner
docker run --detach \
  --name gitlab-runner \
  --restart always \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume gitlab-runner-config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

# 注册到本地 GitLab
docker exec -it gitlab-runner gitlab-runner register

7.3 调试技巧

使用 before_script 输出调试信息
检查 Runner 日志
验证 YAML 语法
分阶段测试流水线

这份教学文档系统地整理了 GitLab CI/CD 的核心概念、配置方法和实战技巧，涵盖了从基础到高级的完整知识体系，可以作为团队内部培训和项目实施的参考指南。