游戏 App CI/CD 流水线

面向 Unity → Android 游戏 的一键 CI/CD 方案：提交代码后自动 构建 APK → 在 emulator-5554 跑 Airtest+Poco 自动化 → 上传蒲公英内测 → 企微通知。

构建/测试/分发逻辑全部封装为 可独立运行的 PowerShell 脚本，因此同一套脚本既能跑在 Jenkins（自托管 Windows 节点），也能 本地一键执行（run-locally.ps1），无需改变任何业务逻辑。

---

一、流水线总览

```
代码提交 / 手动触发
      │
      ▼
[1] Prepare        环境自检：Android SDK / adb / emulator / Java，加载变量
      │
      ▼
[2] Build           Unity -batchmode 命令行出包（apk/aab），产物落 artifacts/
      │
      ▼
[3] Start Emulator  启动 AVD → emulator-5554，等待系统就绪、解锁
      │
      ▼
[4] Airtest Test    adb 安装 APK → 启动游戏 → 跑 tests/*.air（Poco）→ 收集 HTML 报告
      │
      ▼
[5] Distribute      上传蒲公英，生成下载短链（可关闭）
      │
      ▼
[6] Notify          企微机器人推送结果（成功/失败）
```

 

---

二、目录结构

```
cicd/
├── Jenkinsfile              # Jenkins 声明式流水线（调用下方脚本）
├── run-locally.ps1          # 本地一键跑全流程（无需 Jenkins）
├── env.example.ps1          # 配置模板（复制为 env.ps1 填写）
├── .gitignore
├── scripts/
│   ├── 00_prepare_env.ps1   # 环境自检 + 变量加载（被其它脚本复用）
│   ├── build_unity.ps1      # Unity 命令行构建
│   ├── start_emulator.ps1   # 启动/等待 emulator-5554
│   ├── run_airtest.ps1      # 安装 + 跑 Airtest+Poco + 出报告
│   ├── upload_pgyer.ps1     # 蒲公英上传
│   └── notify_wecom.ps1     # 企微通知
├── unity/Editor/
│   └── BuildScript.cs       # 放入 Unity 工程 Assets/Editor/ 的构建器
├── tests/
│   └── sample_smoke.air/    # Airtest+Poco 冒烟用例模板
├── artifacts/               # 构建产物（被 .gitignore 忽略）
└── reports/                 # 测试报告（被 .gitignore 忽略）
```

 

跨步骤状态（APK 路径、分发链接）通过 .pipeline_state.ps1 文件传递，使 Jenkins 各 stage 与本地运行器共享上下文。该文件已被 .gitignore 忽略。

---

三、环境前置

组件	要求	本机已知
Windows	自托管节点	✅
Java	8+	✅ 1.8.0_251
Android SDK	platform-tools / emulator	✅ D:\Program Files\android-sdk-windows
Unity	含 Android Build Support	需配置 UNITY_PATH
Airtest + Poco	pip install airtest pocoui	需配置 AIRTEST_HOME
AVD	预创建，如 Pixel_5_API_33	需 emulator -list-avds 确认
蒲公英账号	获取 _api_key	填入 env.ps1 / Jenkins 凭据
企微机器人	群 → 添加机器人 → Webhook	填入 env.ps1 / Jenkins 凭据

Unity 工程接入

把 unity/Editor/BuildScript.cs 复制到你的 游戏工程 Assets/Editor/ 目录（已存在同名文件则合并）。CI 通过 GameCiBuilder.BuildAndroid 触发构建，从环境变量读取输出路径/包类型。

---

四、快速开始（本地）

```powershell
# 1) 复制并填写配置
cp env.example.ps1 env.ps1
#   编辑 env.ps1：UNITY_PATH / UNITY_PROJECT / GAME_PACKAGE / AIRTEST_HOME / PGYER_API_KEY / WECOM_WEBHOOK ...

# 2) 一键跑完整流水线
.\run-locally.ps1
```

 

本地运行时，脚本会自动：构建（或跳过）→ 启动模拟器 → 安装并测试 → 分发 → 通知。

---

五、部署到 Jenkins

1. 安装 Jenkins（Windows 节点），安装插件：Pipeline、HTML Publisher、Credentials Binding。

1. 注册自托管节点：在 Jenkins → Nodes 添加 Windows agent，标签 windows-unity，机器需满足「环境前置」。

1. 配置凭据：
   • pgyer-api-key → 蒲公英 _api_key（Secret text）
   • wecom-webhook → 企微机器人完整 Webhook URL（Secret text）

1. 新建 Pipeline 任务 → 指向本仓库 → 选择 Jenkinsfile。

1. 配置任务环境变量（或 Jenkins 全局）：UNITY_PATH、UNITY_PROJECT、GAME_PACKAGE、GAME_ACTIVITY、AIRTEST_HOME、TEST_CASE_DIR、BUILD_OUTPUT、BUILD_TYPE、BUILD_FORMAT、SKIP_BUILD、DISTRIBUTE_ENABLED。

1. 构建触发：推荐 Poll SCM 或 GitHub/GitLab webhook，也可手动构建。

想先不发版只验证构建+测试？把 DISTRIBUTE_ENABLED=false 即可，分发阶段自动跳过。 已有现成 APK 想直接跑测试？把 SKIP_BUILD=true 且 APK_PATH=绝对路径 即可。

---

六、常见调整

• 新增用例：在 tests/ 下加 xxx.air/ 目录（__init__.py 里写 Airtest/Poco 逻辑），CI 自动发现。

• 换 iOS / 其它引擎：替换 build_unity.ps1 与 BuildScript.cs 的构建器即可，流水线骨架不变。

• 换分发平台（fir / 腾讯云 COS 等）：改写 upload_pgyer.ps1 上传段。

• 换通知渠道（钉钉/飞书）：改写 notify_wecom.ps1 的 payload。