5 分钟搞定 GitLab 按分支自动部署（测试 / 预发 / 生产）

🚀 基于 GitLab Runner：5 分钟实现「按分支自动部署到不同环境」

再也不用手动 ssh + git pull + npm build 了
主干自动发生产，测试分支自动发测试环境

---

一、你是不是也经历过这些痛点？

• 😵 测试环境、预发布、生产环境全靠手动部署
• 😵 上线时一堆人盯着服务器，生怕敲错命令
• 😵 多个分支不知道该部署到哪个环境
• 😵 CI/CD 配了，但只能打包，不能自动发布

👉 这篇文章，用 GitLab Runner + 分支策略，带你 一次性解决多环境自动部署问题。

---

二、最终效果（先看结果）

Git 分支	自动部署环境
dev	测试环境
test	预发布环境
main / master	生产环境

只要一 push 代码：

• 自动构建
• 自动部署
• 自动区分环境
• 不需要人工干预

---

三、整体架构说明（非常重要）

GitLab Repo
   ↓ push
GitLab CI
   ↓
GitLab Runner（服务器上）
   ↓
根据分支执行不同部署脚本
   ↓
dev / test / prod 服务器

核心思想只有一句话：
👉 利用 GitLab CI 的 rules / only，让不同分支执行不同 job

---

四、准备条件（3 分钟搞定）

1️⃣ 你需要准备这些东西

• 一个 GitLab 项目
• 一台服务器（可以就是部署服务器本身）
• 已安装 Docker（推荐）
• 已安装 GitLab Runner

---

2️⃣ 安装 GitLab Runner（服务器上）

docker run -d --name gitlab-runner --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

注册 Runner：

docker exec -it gitlab-runner gitlab-runner register

关键选项建议：

• executor：shell（部署最简单）
• tags：deploy

五、核心：.gitlab-ci.yml 分支部署实战

👉 重点来了：整个自动化就靠它

stages:
  - install
  - build
  - deploy

variables:
  DIST_DIR: "dist"

install_dependencies:
  stage: install
  tags:
    - deploy
  script:
    - npm ci
  cache:
    key: node-modules
    paths:
      - node_modules/

deploy_frontend:
  stage: deploy
  tags:
    - deploy
  rules:
    # dev → 测试
    - if: '$CI_COMMIT_BRANCH == "dev"'
      variables:
        DEPLOY_ENV: "dev"
        TARGET_DIR: "/var/www/dev-web"

    # test → 预发布
    - if: '$CI_COMMIT_BRANCH == "test"'
      variables:
        DEPLOY_ENV: "test"
        TARGET_DIR: "/var/www/test-web"

    # tag → 生产
    - if: '$CI_COMMIT_TAG'
      variables:
        DEPLOY_ENV: "prod"
        TARGET_DIR: "/var/www/prod-web"

    # 其他情况不执行
    - when: never

  script:
    - echo "🚀 当前环境：$DEPLOY_ENV"
    - echo "📦 构建前端项目"
    - npm run build

    - echo "📁 清理旧文件：$TARGET_DIR"
    - rm -rf $TARGET_DIR/*

    - echo "📤 拷贝构建产物"
    - cp -r $DIST_DIR/* $TARGET_DIR/

六、为什么推荐用 rules 而不是 only？

对比	only	rules
灵活度	❌ 低	✅ 高
支持条件	❌ 少	✅ 多
官方推荐	❌	✅

👉 GitLab 官方已推荐使用 rules

七、常见坑位总结（血泪经验）

❌ Runner 没权限访问部署目录
👉 chown -R gitlab-runner

❌ pm2 / node 不在 PATH
👉 使用绝对路径 /usr/bin/pm2

❌ 多个 Runner 抢任务
👉 用 tags 精准绑定

---

八、总结一句话

真正好用的 CI/CD，不是炫技，而是：

👉 代码一 push，环境自己变

如果你现在还在手动部署，
这套方案可以立刻帮你节省 80% 上线时间。