Balatro后端进阶（2）：基于GitHub Actions的CI自动化验证实现

GitHub项目地址：balatro-realtime-backend

📌 对应代码版本：chore: add CI workflow for automated testing(2026年4月24日 17:18)

⚠️ 本文基于当前提交记录代码实现

📌 主线关联说明

本文属于「Balatro后端进阶系列」，是在主线开发过程中，对某一技术点的深入拆解。

👉 当前对应主线进度(第二篇后，第三篇前)：

文章目录

一、为什么要引入CI
[二、什么是GitHub Actions](#二、什么是GitHub Actions)
三、在项目中引入CI
- [1. 创建 workflow 文件](#1. 创建 workflow 文件)
- [2. 编写基础 CI 配置](#2. 编写基础 CI 配置)
- [3. 踩坑记录](#3. 踩坑记录)
四、配置解析
- [1. 名字设置](#1. 名字设置)
- [2. 触发条件](#2. 触发条件)
- - [2.1 触发所有提交时的校验](#2.1 触发所有提交时的校验)
  - [2.2 触发固定分支校验](#2.2 触发固定分支校验)
- [3. 执行环境](#3. 执行环境)
- [4. 执行流程](#4. 执行流程)
五、为什么要加build
六、一次完整执行流程
七、实际效果
八、这一步的意义
九、这一阶段的变化
十、总结

一、为什么要引入CI

一开始我是没有打算做 CI 的。

因为在本地开发时，我已经可以通过 npm start 跑起服务，也可以手动执行 npm test 来验证逻辑。

但在一次修改 poker.service 后，

我发现一个问题 ：

👉 我并不能保证"每一次提交代码之前，都手动执行了测试"...

甚至更现实的是 ：

👉 如果项目被别人 clone 下来，在不同环境中，是否还能正常运行？

这个时候我才意识到：

👉 问题不在于"代码能不能跑"，而在于："有没有一种机制，可以在代码提交后，自动帮我验证一遍？"

这也是我引入 CI 的真正原因。

CI 并不是为了让代码更高级，而是让错误更早暴露。

二、什么是GitHub Actions

可以用一句话理解，就是代码自动执行器，也就是自动帮我跑脚本
GitHub Actions = 在代码 push 后，自动执行你设定的一系列命令

例如：
git push → 自动执行 npm install → npm test

三、在项目中引入CI

1. 创建 workflow 文件

在项目根目录下创建：(⚠️ 这是 GitHub 固定约定路径，只能是这个，要不不会生效)

复制代码

.github/workflows/ci.yml

2. 编写基础 CI 配置

yml 复制代码

name: CI

on:
  push:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm install
      - run: npm run build
      - run: npm test

3. 踩坑记录

在接入 CI 之前，本地执行 npm test 其实是报错的：

Jest 配置冲突（同时存在 jest.config.cjs 和 package.json 配置）
testPathIgnorePatterns 写错位置（误写进 transform）
dist 目录被扫描导致测试失败

这些问题在本地可以"手动修复"，但如果没有 CI：这些错误是不会被自动发现的

而在引入 CI 后，这些问题会在 push 后立刻暴露出来。

这也是 CI 的另一个价值：

👉 让隐性问题变成显性错误

四、配置解析

1. 名字设置

yml 复制代码

jobs:
  test:

👉 定义一个任务 job，名字叫 test

2. 触发条件

2.1 触发所有提交时的校验

yml 复制代码

on:
  push:
  pull_request:

一开始我其实只写了 push，因为我只是想在提交代码后做一次自动验证。

但后来我发现一个问题 ：如果使用分支开发feature → main，在合并之前是没有校验的,所以我补上了：pull_request

2.2 触发固定分支校验

但如果只想在固定分支提交的时候校验，比如说我只想在 main 分支有变动的时候校验，这是添加固定的 branches：

yml 复制代码

on:
  push:
    branches:
      - main

3. 执行环境

yml 复制代码

runs-on: ubuntu-latest

👉表示：在 GitHub 提供的 Linux 服务器上运行

4. 执行流程

yml 复制代码

- uses: actions/checkout@v4 //把GitHub代码拉到这台服务器上，相当于git clone project

- uses: actions/setup-node@v4 //安装v22版本的Node.js，相当于nvm install 22
  with:
      node-version: 22
      
- run: npm install //安装依赖
- run: npm run build //编译TypeScript，检查错误
- run: npm test //执行测试

在本地运行的时候一般都是 npm start，但是在配置中，建议用 npm test ，因为 npm start = 启动服务器(不会自动结束)，会导致 CI 一直卡住❌。

因为 CI 的目标是：

✔ 安装依赖

✔ 跑测试

✔ 检查是否报错

而不是

❌ 启动服务

五、为什么要加build

大部分人一般只会写一个

复制代码

- run: npm test //执行测试

但其实在 NestJS + TypeScript 项目中，这是不够的。

build 能发现：

类型错误
import 路径错误
编译错误

而 test 只验证：

逻辑是否正确

👉 所以说这两者其实是互补关系。

六、一次完整执行流程

当执行：

git push
GitHub 会自动：
1. 拉取代码
2. 安装 Node 环境
3. 执行 npm install
4. 执行 npm run build
5. 执行 npm test
最终在 Actions 页面显示：

✅ Success / ❌ Failed

七、实际效果

引入 CI 后：

每次代码提交都会被验证
错误可以在第一时间暴露
不再依赖本地环境

八、这一步的意义

很多人会觉得：

"CI 好像没做什么事情"

但实际上，它代表的是：

从"能写代码" → 到"能保证代码质量"

九、这一阶段的变化

在引入 CI 之前，我的开发流程是：
写代码 → 本地运行 → 手动测试 → 提交

引入 CI 之后，变成：
写代码 → 提交 → 自动验证 → 再决定是否继续开发

这个变化看起来不大，但实际上是一个非常重要的转折：

让我们从"依赖个人习惯" → 到"依赖系统保证质量"

这也是我第一次真正感觉到：

代码不仅是"能跑"，还需要"可验证"。

十、总结

引入 GitHub Actions 后，项目具备了基础的自动化能力：

复制代码

提交代码 → 自动验证 → 提升稳定性

这一步虽然不复杂，但它标志着项目从"能跑"走向了"可验证"。

也是我第一次开始把"工程化"真正落到代码里的节点。