从零搭建 CI/CD 流水线 — GitHub Actions 实战指南

前言

最近我给一个 Spring Boot 4 + Vue 3 的前后端项目补全了测试和 CI/CD 体系。在这个过程中，CI 流水线经历了多次调试才全部通过。这些问题覆盖了环境一致性、平台差异、依赖冲突等几乎所有新手都会遇到的坑。

本文将以这次实战为线索，带你从零搭建一套完整的 CI/CD 流水线。读完你将能够：

理解 CI/CD 的概念和必要性
为自己的项目写出第一个 GitHub Actions 工作流
知道常见的坑和应对方法

一、CI/CD 是什么？为什么需要它？

一句话理解

1	你 push 代码 → GitHub Actions 自动执行检查 → 全绿就放心了

CI（Continuous Integration，持续集成）：每次提交代码，自动编译、测试、检查代码质量。确保”新代码没有搞坏旧功能”。
CD（Continuous Delivery / Deployment，持续交付/部署）：CI 通过后，自动把代码部署到服务器。

一张图理解 CI/CD 在项目中的位置

CI/CD 流程图

PR（Pull Request）触发 CI，CI 不通过则管理员根本不应该看到这个 PR。这就是 “安全检查门” 的含义——机器先替你过滤一遍，人只审绿色代码。

没有 CI 会怎样？

问题	没有 CI	有 CI
新同事 clone 后跑不起来	口头告知”你缺个 xxx 依赖”	CI 直接报错，push 前就能发现
代码写错了破坏已有功能	上线后用户发现	测试在合并前就挂了
Windows 能跑 Linux 不能跑	上了服务器才炸	CI 运行在 Linux，第一时间暴露
没人记得跑 lint	代码风格越来越乱	CI 自动跑，不通过不给合并

二、动手前的准备

CI 的核心是跑你的测试和构建命令。所以在写 CI 文件之前，先把这些东西准备好：

2.1 单元测试

后端用 Maven：

1 2	cd edumind ./mvnw test # 跑所有测试

前端用 npm：

1 2	cd vue-project npm test # 等价于 npx vitest run

确保这两条命令在你的终端里能跑通之后，再交给 CI。

2.2 依赖清单

对于 Java（Maven 项目），确保 pom.xml 里测试依赖齐全。至少需要：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

对于前端，确保 package-lock.json 已提交到 Git。CI 用的是 npm ci，它严格按照 lockfile 安装依赖——如果 lockfile 没提交或过期，直接挂。

2.3 覆盖率工具（可选但推荐）

在 pom.xml 中加入 JaCoCo 插件：

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.12</version>
    <executions>
        <execution>
            <id>prepare-agent</id>
            <goals><goal>prepare-agent</goal></goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>verify</phase>
            <goals><goal>report</goal></goals>
        </execution>
    </executions>
</plugin>

跑 ./mvnw verify 后会在 target/site/jacoco/ 生成覆盖率报告。

三、编写你的第一个 CI 工作流

GitHub Actions 的配置文件放在 .github/workflows/ 目录下，只要是 .yml 文件，GitHub 就会自动识别。

3.1 文件结构

项目根目录
└── .github
    └── workflows
        ├── ci.yml        ← 质量检查（PR 时触发）
        └── deploy.yml    ← 自动部署（打 tag 时触发）

3.2 后端测试 Job

从最简单的开始——写一个只跑 Maven 测试的 Job：

name: CI — Quality Gate

on:
  push:
    branches: [master, main]       # 主分支有推送 → 触发
  pull_request:
    branches: [master, main]       # 有人提 PR → 触发
  workflow_dispatch:               # 也可以在 GitHub 页面手动触发

jobs:
  backend-test:
    name: Backend — Java 21
    runs-on: ubuntu-latest         # 跑在 Linux 上
    services:                      # CI 提供的辅助容器
      postgres:
        image: pgvector/pgvector:pg16
        env:
          POSTGRES_DB: postgres
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
        ports:
          - 5432:5432

    steps:
      - name: 拉取代码
        uses: actions/checkout@v4

      - name: 安装 JDK
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: 'maven'            # Maven 缓存，下次跑更快

      - name: 编译 & 测试
        run: |
          cd edumind
          chmod +x mvnw             # Linux 需要执行权限
          ./mvnw verify -Dspring.profiles.active=test \
            -Dspring.datasource.url=jdbc:postgresql://localhost:5432/postgres \
            -Dspring.datasource.username=postgres \
            -Dspring.datasource.password=postgres \
            --batch-mode

      - name: 上传覆盖率报告
        uses: actions/upload-artifact@v4
        if: always()                # 即使测试挂了也上传，方便排查
        with:
          name: jacoco-report
          path: edumind/target/site/jacoco/

关键点解读：

runs-on: ubuntu-latest — CI 跑在 GitHub 提供的 Linux 虚拟机上。这意味着你的构建环境是 Linux，不是 Windows。这是最常见的坑源。
services: — 如果你的集成测试需要数据库/缓存，这里可以声明 GitHub 提供的服务容器，CI 会自动启动它们。
chmod +x mvnw — Git 不保留文件的可执行位。在 Windows 上开发时 mvnw 无所谓权限，但 Linux 上必须 chmod +x 才能运行。每处 ./mvnw 前都要加。
--batch-mode — 让 Maven 不等待交互输入，适合 CI 环境。

3.3 前端测试 Job

frontend-test:
  name: Frontend — Node 22
  runs-on: ubuntu-latest       # 同样是 Linux

  steps:
    - name: 拉取代码
      uses: actions/checkout@v4

    - name: 安装 Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '22'
        cache: 'npm'
        cache-dependency-path: vue-project/package-lock.json

    - name: 安装依赖
      run: cd vue-project && npm ci

    - name: 类型检查
      run: cd vue-project && npx vue-tsc --build

    - name: 代码 Lint
      run: cd vue-project && npm run lint

    - name: 运行测试
      run: cd vue-project && npx vitest run

npm ci 和 npm install 的区别：

命令	行为
`npm install`	根据 `package.json` 安装，可能更新 `package-lock.json`
`npm ci`	严格按照 `package-lock.json` 安装，不一致就报错

CI 里必须用 npm ci，这能保证你本地锁定的版本和 CI 完全一致。

3.4 Docker 构建 Job（可选）

如果你的项目用 Docker 部署，加一个镜像构建的 sanity check：

docker-build:
  name: Docker — Build image
  runs-on: ubuntu-latest
  needs: [backend-test, frontend-test]   # 前两个都绿了才跑

  steps:
    - uses: actions/checkout@v4

    - name: 安装 JDK 并构建 JAR
      uses: actions/setup-java@v4
      with:
        java-version: '21'
        distribution: 'temurin'
        cache: 'maven'

    - name: 构建 JAR 及 Docker 镜像
      run: |
        cd edumind
        chmod +x mvnw
        ./mvnw package -DskipTests --batch-mode
        docker build -t edumind:ci-test .

    - name: 确认镜像存在
      run: docker images edumind:ci-test

needs: [backend-test, frontend-test] 的作用：Docker 构建需要跑测试时必须的 Maven 编译产物（JAR 包），所以等前两个 Job 通过后再执行。

四、常见的坑及排查思路

上面写完了完整的 CI 文件。但第一次 push 大概率不会直接绿——以下是在实战中遇到的几个典型问题和你需要知道的排查方法。

坑 1：`package-lock.json` 没提交

1	npm ERR! Missing: vitest from lock file

原因：本地 npm install 更新了 lockfile，但 git add 漏了。CI 用的 npm ci 严格校验 lockfile。

排查：git status 看 package-lock.json 是否为 M（modified）。确保它和 package.json 一起提交。

坑 2：文件只存在于本地，没被 Git 跟踪

1	[ERROR] cannot find symbol: class MineruException

原因：IDE 里新建的类，从未 git add。本地编译没错是因为 IDE 读取文件系统，CI 只认得 Git 仓库里的东西。

排查：git status 里的 ??（untracked）就是地雷。推送前跑一遍 git status 确认没有漏掉的新文件。

坑 3：Windows 上能运行，Linux 上报 `Permission denied`

1	./mvnw: Permission denied

原因：Windows 不管文件权限，Linux 执行脚本需要 x 权限。Git 在 Windows 上不保留 Unix 可执行位。

解决：在 CI 配置里，每个使用 ./mvnw 的步骤前加 chmod +x mvnw。

坑 4：依赖版本冲突 —— “静默退化”

# Windows 上 JWT 正常
{"sub":"1","iss":"edumind","aud":"edumind-client","jti":"uuid...","iat":...}

# Linux CI 上三个字段消失
{"sub":"1","username":"teacher1","iat":...}

原因：Spring Boot 4 自带 Jackson 3.x，但 jjwt 0.11.5 依赖 Jackson 2.x。两个版本共存时，classpath 加载顺序在不同 OS 上可能不同，导致部分序列化功能静默失效——不报错，但行为不对。

通用排查思路：

在 CI 日志中加 debug 输出，对比本地和 CI 的行为差异
检查 pom.xml 的 dependency tree：./mvnw dependency:tree
如果是版本冲突，升级到兼容双方的最新版本

坑 5：集成测试依赖真实数据库

1	Failed to load ApplicationContext

原因：有的测试用了 @SpringBootTest，它会启动完整 Spring 上下文，要求 PostgreSQL、Redis 等服务都在线。CI 的 services 容器虽然提供了数据库，但某些需要额外配置。

方案：

纯单元测试（@ExtendWith(MockitoExtension.class)）— 毫秒级，不依赖外部服务
集成测试用 Testcontainers — 自动拉取数据库 Docker 镜像，用完即弃
GitHub Actions 的 services: 字段 — 声明 CI 环境所需的辅助容器

五、CD —— 自动部署

CI 是”检查”，CD 是”送到线上”。下面是一份简单的自动部署模板，在打 v 开头的 tag 时触发：

name: Deploy

on:
  push:
    tags:
      - 'v*'               # 推送 v1.0.0 这种 tag → 自动部署
  workflow_dispatch:        # 也可以手动触发

jobs:
  build-and-push:
    name: 构建并推送镜像
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: 'maven'

      - name: 构建 JAR
        run: |
          cd edumind
          chmod +x mvnw
          ./mvnw package -DskipTests --batch-mode

      - name: 构建并推送 Docker 镜像
        uses: docker/build-push-action@v6
        with:
          context: ./edumind
          push: true
          tags: ghcr.io/${{ github.repository }}/edumind:latest

  deploy:
    name: SSH 部署到服务器
    runs-on: ubuntu-latest
    needs: build-and-push
    steps:
      - name: 远程部署
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
          key: ${{ secrets.DEPLOY_SSH_KEY }}
          script: |
            cd /opt/edumind
            docker compose pull app
            docker compose up -d --remove-orphans

敏感信息管理

注意上面的 ${{ secrets.DEPLOY_HOST }} 等变量——这些不能写在文件里明文暴露。

在 GitHub 仓库的 Settings → Secrets and variables → Actions 中添加：

Secret 名	内容
`DEPLOY_HOST`	服务器 IP
`DEPLOY_USER`	SSH 用户名
`DEPLOY_SSH_KEY`	SSH 私钥

六、完整流程一览

全部配置就绪后，你的日常工作流是这样的：

1. 开分支写代码
   git checkout -b feature/xxx

2. 写代码 + 写测试 + 本地验证
   ./mvnw test && npm test

3. 提交 & 推送
   git add -A && git commit -m "xxx" && git push

4. 去 GitHub 创建 Pull Request（feature/xxx → master）

5. CI 自动启动：
   ┌─ Backend Test ── ✅ 53 tests passed
   ├─ Frontend Test ─ ✅ 12 tests passed
   └─ Docker Build ── ✅ image built

6. 全绿 → 通知管理员 review → 合并

7. 打 tag 发布：
   git tag v1.0.0 && git push --tags

8. CD 自动部署：
   📦 构建镜像 → 🚀 推送到仓库 → 🔄 服务器更新

结语

“在我机器上能跑”是软件开发中最昂贵的一句话。

CI/CD 的价值不在于配置文件的语法有多精妙，而在于它把”能跑”的标准从”你的机器”提高到了”任何一台机器”。每一次红叉，都在替你发现一个上线后才会暴露的问题。

如果你现在有一个还没有 CI 的项目——从今天开始，在 .github/workflows/ 下创建第一个 .yml 文件，只写一个最简单的 ./mvnw test。从那一行开始，你就已经在通往生产级的路上。