GitLab CI/CD 配置教程

1. 简介

GitLab CI/CD 是内置于 GitLab 的持续集成、持续交付和持续部署工具。通过配置 .gitlab-ci.yml 文件，您可以自动化构建、测试和部署流程。本教程将详细讲解从基础配置到高级实践的全过程。

2. 前提条件

拥有 GitLab 账户（需支持 CI/CD 功能）

已创建项目仓库

对 YAML 语法有基本了解

3. 基础配置步骤

创建 .gitlab-ci.yml 文件

在项目根目录创建此文件

GitLab 会自动检测该文件并触发流水线

定义基础结构

# .gitlab-ci.yml 基础模板
stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - echo "构建步骤..."
    - mkdir build
    - touch build/info.txt

test_job:
  stage: test
  script:
    - echo "运行测试..."
    - test -f build/info.txt

deploy_job:
  stage: deploy
  script:
    - echo "部署应用..."
  environment: production

4. Runner 配置

安装 GitLab Runner

# Ubuntu 安装命令
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt-get install gitlab-runner

注册 Runner

sudo gitlab-runner register
# 输入 GitLab 实例 URL
# 输入注册 token（项目设置->CI/CD->Runners）
# 选择执行器（推荐 docker）

验证 Runner 状态

项目设置 > CI/CD > Runners 查看绿色状态

5. 高级配置技巧

使用 Docker 镜像

image: python:3.9

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

cache:
  paths:
    - .cache/pip/
    - venv/

before_script:
  - python -m venv venv
  - source venv/bin/activate
  - pip install -r requirements.txt

test:
  script:
    - pytest tests/

条件执行与多环境

deploy_prod:
  stage: deploy
  script:
    - echo "部署到生产环境"
  environment:
    name: production
    url: https://prod.example.com
  only:
    - main
  when: manual

deploy_staging:
  stage: deploy
  script:
    - echo "部署到测试环境"
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - develop

使用缓存与制品

build:
  stage: build
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

test:
  stage: test
  dependencies:
    - build
  script:
    - npm run test

6. 实践案例：Node.js 应用部署

项目结构要求

项目根目录/
├── src/
├── tests/
├── .gitlab-ci.yml
└── package.json

完整配置示例

image: node:16

stages:
  - install
  - test
  - build
  - deploy

variables:
  NODE_ENV: production

cache:
  key: $CI_COMMIT_REF_SLUG
  paths:
    - node_modules/

install_dependencies:
  stage: install
  script:
    - npm ci
  artifacts:
    paths:
      - node_modules/

run_tests:
  stage: test
  needs: ["install_dependencies"]
  script:
    - npm run test

build_application:
  stage: build
  needs: ["install_dependencies"]
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

deploy_to_s3:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest
  needs: ["build_application"]
  script:
    - aws s3 sync dist/ s3://$S3_BUCKET/ --delete
  only:
    - main

7. 故障排查

常见问题解决

Runner 未启动：检查 Runner 服务状态

   sudo gitlab-runner status
   sudo gitlab-runner restart

权限错误：在脚本开头添加

   before_script:
     - chmod +x deploy.sh

缓存失效：清空缓存并重新触发流水线

   cache:
     key: $CI_PIPELINE_ID  # 使用唯一键禁用缓存

调试技巧

启用详细日志：在 CI/CD 设置中勾选

使用 docker exec 进入调试容器

   docker exec -it <container_id> /bin/bash

8. 总结

GitLab CI/CD 提供了强大的自动化能力，通过合理配置 .gitlab-ci.yml 文件，可实现从代码提交到生产部署的全流程自动化。关键点包括：

阶段划分：将流程划分为清晰的构建、测试、部署阶段

环境隔离：使用 Docker 容器确保环境一致性

缓存优化：合理配置缓存减少重复依赖安装

制品管理：通过 artifacts 传递阶段间产物

条件控制：使用 only/except 和 when 控制执行时机

实际部署时需根据项目特性调整配置，持续优化流水线性能。建议从简单配置开始，逐步引入高级功能，确保团队所有成员理解CI/CD流程。

cnbugsai

打赏 海报 链接