GitLab CI/CD 全解析：从流水线与 Runner 到 Vue 项目实战配置

在现代软件开发中，自动化部署已成为提升效率的核心手段。GitLab 内置的 CI/CD（持续集成 / 持续部署）功能，通过流水线（Pipeline） 和运行器（Runner） 的配合，能轻松实现代码提交到项目上线的全流程自动化。本文将从基础概念出发，结合 Vue 项目实战，带你掌握 GitLab CI/CD 的完整配置流程。

一、核心概念：流水线（Pipeline）与运行器（Runner）

在开始配置前，我们需要先理清 GitLab CI/CD 的两个核心组件 ——流水线和Runner，这是理解后续配置的基础。

1. 流水线（Pipeline）：自动化流程的 “蓝图”

流水线是 GitLab CI/CD 的核心载体，它定义了代码从 “提交” 到 “部署” 的全流程步骤，本质是一个包含多个阶段（Stage） 和任务（Job） 的自动化脚本。

阶段（Stage）：流水线的逻辑分组，按顺序执行。例如 “构建→测试→部署”，只有前一个阶段全部成功，后一个阶段才会启动。

任务（Job）：阶段下的具体操作单元，每个任务由 Runner 执行（如 “安装依赖”“打包代码”“上传服务器”）。

触发方式：支持代码推送（push）、合并请求（merge request）、手动触发等，可通过配置灵活控制。

2. 运行器（Runner）：流水线的 “执行者”

Runner 是实际执行流水线任务的 “工具人”，它是部署在服务器（本地 / 云端）上的一个进程，通过与 GitLab 服务器通信，接收并执行流水线任务。

类型分类：

Shell 类型：直接在 Runner 所在服务器的系统 shell 中执行命令（适合简单场景，如本地服务器部署）。

Docker 类型：在独立的 Docker 容器中执行任务（隔离性好，适合多项目、多环境场景）。

虚拟机 / 云服务类型：如 Kubernetes、AWS EC2 等，适合大规模团队使用。

核心作用：脱离 GitLab 服务器本身，在独立环境中执行构建、测试、部署等操作，避免占用 GitLab 服务器资源。

二、前置准备：部署 GitLab Runner

流水线的任务需要 Runner 来执行，因此配置流水线前，必须先在目标服务器上部署 Runner。以下以Linux 服务器 + Shell 类型 Runner为例，讲解部署步骤（最适合中小团队的入门方案）。

1. 安装 Runner

登录目标服务器（如 Linux 服务器），执行以下命令安装 Runner（以 Ubuntu 为例，其他系统可参考 GitLab 官方文档）：

# 1. 添加 GitLab Runner 软件源
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
# 2. 安装 Runner
sudo apt-get install gitlab-runner

2. 注册 Runner 到 GitLab 项目

Runner 需与 GitLab 项目关联，才能接收该项目的流水线任务，注册步骤如下：

步骤 1：获取项目注册信息

进入 GitLab 项目 → Settings → CI/CD → 展开 Runners 模块，获取以下信息：

Registration token： Runner 与项目绑定的令牌。

GitLab instance URL： GitLab 服务器地址（如 https://gitlab.com 或私有部署地址）。

步骤 2：执行注册命令

在 Runner 所在服务器执行以下命令，按提示输入信息：

sudo gitlab-runner register

执行过程中需依次输入：

GitLab instance URL（粘贴上述地址）；

Registration token（粘贴上述令牌）；

给 Runner 打标签（如 vue-build-deploy，后续流水线需通过标签指定 Runner）；

选择 Runner 执行器（输入 shell，即 Shell 类型，docker类型需要设置pull_policy = "if-not-present"禁用重复拉去镜像）。

步骤 3：验证 Runner 状态

返回 GitLab 项目的 Runners 页面，若看到 Runner 状态为 green（活跃），则注册成功。

三、实战：Vue 项目配置 GitLab 流水线

完成 Runner 部署后，我们以 “Vue 项目打包 → 部署到目标服务器” 为例，编写流水线配置文件（.gitlab-ci.yml）。

1. 需求定义

流水线需实现以下流程：

构建阶段（build）：安装 Node 依赖，打包 Vue 项目生成 dist 静态文件；

部署阶段（deploy）：将 dist 目录通过 FTP 传输到目标服务器（Nginx 根目录）；

触发方式：默认代码推送到 main 分支自动触发，也支持手动触发（后续会补充配置）。

2. 安装FTP环境

如果runner主机没有ftp功能，需要安装lftp工具

sudo apt update
sudo apt install lftp

3. 编写 .gitlab-ci.yml 配置文件

在 Vue 项目根目录创建 .gitlab-ci.yml 文件，这是流水线的核心配置文件，完整代码如下（含详细注释）：

# 定义流水线的阶段（按顺序执行：build → deploy）
stages:
  - build    # 构建阶段
  - deploy   # 部署阶段
# --------------------------
# 阶段 1：构建（build）
# --------------------------
build_vue:
  stage: build                # 绑定到 build 阶段
  tags:
    - vue-build-deploy        # 指定使用标签为 vue-build-deploy 的 Runner
  image: node:18-alpine       # 使用 Node 18 轻量镜像（Shell 类型 Runner 也可本地装 Node）
  script:
    # 1. 安装依赖（使用 npm 或 yarn，这里用 npm）
    - npm install --registry=https://registry.npmmirror.com  # 国内源加速
    # 2. 执行打包命令（生成 dist 目录）
    - npm run build
  artifacts:                  # 保存构建产物（供后续 deploy 阶段使用）
    paths:
      - dist/                 # 需传递的文件目录
    expire_in: 1 day          # 产物保留 1 天（避免占用空间）
  only:
    - main                    # 仅当代码推送到 main 分支时触发
# --------------------------
# 阶段 2：部署（deploy）
# --------------------------
deploy_to_server:
  stage: deploy               # 绑定到 deploy 阶段
  tags:
    - vue-build-deploy        # 与 build 阶段使用同一个 Runner
  dependencies:
    - build_vue               # 依赖 build_vue 任务的产物（dist 目录）
  script:
    # 使用 lftp 连接 FTP 服务器并上传 dist 目录
    - lftp -u $FTP_USERNAME,$FTP_PASSWORD $FTP_HOST:$FTP_PORT -e "
        mirror -R dist/ $FTP_TARGET_DIR;  # 递归上传 dist 到远程目录
        bye;  # 退出
      "
  only:
    - main                    # 仅 main 分支触发
  when: manual                # 可选：设置为手动触发（需在 GitLab 界面点击执行）

3. 配置 GitLab 环境变量（敏感信息保护）

上述配置中，SSH_PRIVATE_KEY、TARGET_SERVER 等敏感信息未硬编码，需在 GitLab 项目中配置环境变量（避免泄露）：

进入 GitLab 项目 → Settings → CI/CD → Variables → 点击 Add variable，依次添加以下变量：

变量名	说明	示例值
FTP_HOST	FTP 服务器 IP 或域名	ftp.example.com
FTP_PORT	FTP 端口（默认 21，SFTP 通常是 22）	21
FTP_USERNAME	FTP 登录用户名	ftp_user
FTP_PASSWORD	FTP 登录密码	your_ftp_password
FTP_TARGET_DIR	远程服务器上存放文件的目录	/www/vue-projec

四、流水线触发与验证

1. 触发流水线

将 .gitlab-ci.yml 及 Vue 项目代码推送到 GitLab 的 main 分支：

git add .
git commit -m "add gitlab ci/cd config"
git push origin main

2. 查看流水线状态

进入 GitLab 项目 → CI/CD → Pipelines，可看到流水线正在运行，状态分为：

蓝色（running）：任务执行中；

绿色（passed）：所有阶段执行成功；

红色（failed）：某阶段执行失败（需查看日志排查问题）。

五、进阶配置：自定义触发方式与问题排查

1. 改为 “手动触发” 流水线

若不想代码推送自动触发流水线，可修改 .gitlab-ci.yml 的 workflow 配置，仅允许手动触发：

# 添加到 .gitlab-ci.yml 最顶部
workflow:
  rules:
    # 仅支持通过 GitLab 界面手动触发（排除 push、merge request 等自动触发）
    - if: '$CI_PIPELINE_SOURCE == "web"'
      when: always
    - when: never

手动触发步骤：进入 CI/CD → Pipelines → 点击 Run pipeline → 选择分支后点击 Run pipeline。