1. 项目概述：为什么Unity项目需要CI/CD？

在游戏开发团队里，尤其是项目进入中后期，每天最让人头疼的事情之一可能就是“打包”。美术要个包看效果，策划要个包测功能，测试要个包跑用例，运营要个包做预热。如果全靠开发手动操作，流程大概是：停下手头工作，切换到打包分支，拉取最新代码，打开Unity编辑器，选择构建平台，设置一堆参数，点击构建，然后盯着进度条发呆十几分钟甚至几十分钟。这期间电脑卡顿，无法工作，效率极低，还容易因为手滑选错参数而出错。

我经历过太多这样的场景，也见过不少团队因为打包流程混乱而引发的“事故”：比如本该打测试包却打成了发布包，或者版本号忘记更新导致线上版本混乱。所以，搭建一套自动化构建流水线，对于Unity项目来说，绝不是“锦上添花”，而是“雪中送炭”的工程效能必需品。它本质上是一套将代码提交到最终生成可运行包体的全过程自动化、标准化的系统。今天，我就结合自己从零搭建多套流水线的实战经验，拆解如何为Unity项目构建一个高效、稳定且易于维护的CI/CD（持续集成/持续交付）流水线。无论你是独立开发者还是团队技术负责人，这套思路都能帮你把宝贵的开发时间从重复劳动中解放出来。

2. 核心思路与架构选型

在动手之前，我们先要明确目标：我们需要一个怎样的流水线？我的核心诉求是：无人值守、多平台支持、参数化灵活、易于维护和扩展。基于这些，市面上常见的方案有几类，我们来分析一下各自的优劣。

2.1 常见方案对比与选型理由

1. 纯命令行脚本（Batch/PowerShell/Shell）这是最基础的方案。Unity本身提供了强大的命令行接口（-batchmode -quit -executeMethod），我们可以写脚本调用Unity.exe进行构建。

• 优点：简单直接，无需额外依赖，学习成本低。
• 缺点：功能单一，缺乏任务调度、状态监控、日志聚合、触发机制等CI/CD核心能力。适合个人或极小型项目做最简单的自动化，但难以支撑团队协作。

2. 使用GitLab CI/GitHub Actions等云原生CI这是目前非常流行的方案，直接与代码仓库集成。

• 优点：与Git流程无缝结合，配置即代码（.gitlab-ci.yml），易于版本管理。云服务通常提供免费额度，无需自维护服务器。
• 缺点：构建环境（特别是需要特定Unity版本、SDK）的定制相对复杂，构建时长受限于免费配额，大型项目构建可能超时。对于需要连接公司内网资源（如内部资源服务器）的场景支持不佳。

3. 使用Jenkins这是一个老牌、强大且灵活的开源自动化服务器。

• 优点：
  • 高度可定制化：通过丰富的插件生态，几乎可以实现任何你能想到的自动化流程。
  • 自托管，完全可控：部署在公司内网，环境完全自定义，构建机资源自己掌握，没有时长限制。
  • 强大的Pipeline支持：使用Groovy脚本编写“流水线即代码”（Pipeline as Code），流程描述能力强，可维护性高。
  • 与各种工具集成：轻松集成版本控制（Git/SVN）、消息通知（钉钉/企业微信/邮件）、制品管理等。
• 缺点：需要自行维护Jenkins服务及其构建环境，初期搭建有一定学习成本。

我的选择是Jenkins。对于需要长期迭代、团队协作、环境复杂（如涉及iOS证书管理）的Unity项目，Jenkins提供的控制力和灵活性是无可替代的。它能成长为一个覆盖构建、测试、部署乃至部分运维的综合性自动化平台。接下来，我们的实战就将以Jenkins为核心展开。

2.2 整体架构设计

我们的目标架构如下图所示（此处为文字描述）：

1. 代码仓库：团队使用Git（或SVN）进行代码管理。这是流水线的源头。
2. Jenkins Server：作为大脑，负责调度整个构建流程。它监听代码仓库的变更（如Git的Push事件），或由人工手动触发。
3. 构建代理（Agent）：实际执行构建任务的机器。可以是与Jenkins Server同一台机器，也可以是独立的Windows/Mac机器。为了支持多平台，我们通常需要：
   • Windows构建机：用于打Windows PC包和Android包。
   • Mac构建机：用于打iOS包和Android包（也可打Mac PC包）。
4. 共享存储：构建产物（APK/IPA/EXE）输出到网络共享目录或文件服务器，方便团队成员获取。
5. 通知系统：构建成功或失败后，通过钉钉、企业微信等工具通知相关人员。

这套架构的核心在于，开发者只需提交代码，或是在Jenkins页面上点一下按钮，剩下的所有事情（拉代码、编译、打包、签名、上传）全部自动完成。

3. 环境准备与核心工具链搭建

工欲善其事，必先利其器。在编写任何脚本之前，我们需要先把地基打牢。

3.1 构建机环境标准化

这是最繁琐但最重要的一步，环境不一致是自动化构建最大的敌人。

Windows构建机准备：

1. 安装指定版本的Unity：从Unity Hub安装项目所需的精确版本（如2022.3.40f1）。关键点：必须安装对应平台的模块（如Windows Build Support (IL2CPP)）。
2. 安装Android环境：
   • JDK：安装OpenJDK或Oracle JDK 8/11/17（建议与Unity内置版本兼容，通常JDK8较稳妥）。
   • Android SDK & NDK：可以通过Unity Hub安装，或独立安装。务必在Unity编辑器内（Edit -> Preferences -> External Tools）设置正确的SDK、JDK、NDK路径。这一步的路径后续会在Jenkins脚本中引用。
3. （可选）安装Git：如果Jenkins使用Git插件拉取代码，需要安装Git命令行工具。

Mac构建机准备：

1. 安装指定版本的Unity：同样通过Unity Hub安装，并包含iOS Build Support模块。
2. 安装Xcode及命令行工具：从App Store安装项目所需的Xcode版本，并在终端执行xcode-select --install安装命令行工具。
3. 准备iOS证书与描述文件：这是iOS自动化的核心难点。你需要将开发或发布证书（.p12文件）和对应的描述文件（.mobileprovision）妥善保存在构建机上，并记录密码。建议使用独立的“打包证书”，与开发证书分离。
4. 安装Android环境：同上。

实操心得：强烈建议使用虚拟机或Docker（对于非图形部分）来固化构建环境。一旦配置好，就制作一个镜像快照。以后新增构建机或重装系统，直接恢复镜像，可以避免重复劳动和环境差异。对于iOS构建，由于对Xcode和macOS版本有强依赖，更推荐使用一台专用的Mac Mini作为构建机。

3.2 Jenkins服务部署与基础配置

1. 部署Jenkins：Jenkins是一个Java应用，我们下载其WAR包运行即可，这样最干净。

# 在构建机（或专门的服务器）上，确保已安装JDK 11或更高版本 # 下载最新的Jenkins WAR包 wget https://get.jenkins.io/war-stable/latest/jenkins.war # 启动Jenkins（默认端口8080） java -jar jenkins.war --httpPort=8080

为了稳定运行，建议将Jenkins配置为系统服务（Windows服务或Mac/Linux的LaunchDaemon）。

2. 初始安装与插件安装：首次通过浏览器访问http://构建机IP:8080，按照指引完成初始化。安装推荐插件后，还需手动安装几个关键插件：

• Pipeline：核心插件，支持流水线任务。
• Git plugin：Git支持。
• Job DSL：允许我们用Groovy脚本批量生成和管理任务，这是实现“配置即代码”、方便维护的关键。
• Active Choices Plugin：提供更丰富的参数化构建UI，如动态下拉框。
• Pipeline Utility Steps：为Pipeline脚本提供丰富的工具方法，如读写JSON、YAML文件。

3. 关键系统配置：

• 配置全局工具路径：进入“系统管理” -> “全局工具配置”，设置JDK、Git（如果自动安装失败）的路径。
• 配置Unity路径（重要）：在“系统管理” -> “系统配置”的“全局属性”中，添加环境变量。例如，添加一个键为UNITY_2022_EXECUTABLE的变量，值为你的Unity可执行文件绝对路径（Windows:C:\Program Files\Unity\Hub\Editor\2022.3.40f1\Editor\Unity.exe， Mac:/Applications/Unity/Hub/Editor/2022.3.40f1/Unity.app/Contents/MacOS/Unity）。这样在Pipeline脚本中就可以用env.UNITY_2022_EXECUTABLE来调用。

4. 核心Pipeline脚本深度解析

一切就绪，现在进入核心环节：编写构建脚本。我们将采用Jenkins Pipeline (Groovy)来编写，因为它比传统的自由风格项目更强大、更可维护。我们的脚本主要分为两部分：定义任务的DSL脚本和执行构建的Pipeline脚本。

4.1 任务定义：Job DSL脚本剖析

Job DSL插件允许我们用代码定义Jenkins任务。想象一下，你有5个开发分支，每个分支需要打3个平台的包，这就是15个任务。手动创建和修改会是一场噩梦。用DSL，我们只需维护一个Groovy脚本。

// create_jobs_dsl.groovy def projectName = "MyGame" def branches = ['trunk', 'feature/combat', 'hotfix/1.02'] def platforms = ['Windows', 'Android', 'iOS'] // iOS任务只在Mac节点生成 branches.each { branch -> platforms.each { platform -> // 生成一个规范的Job名称，如 `MyGame-trunk-Windows` def jobName = "${projectName}-${branch.replace('/', '-')}-${platform}" // 使用DSL API创建Pipeline类型的Job pipelineJob(jobName) { // 1. 描述和参数 description("自动构建 ${projectName} 项目，分支: ${branch}, 平台: ${platform}") parameters { stringParam('VERSION', '1.0.0', '构建版本号') choiceParam('BUILD_TARGET', ['Development', 'Release'], '构建模式') booleanParam('CLEAN_BUILD', true, '是否执行清理构建（推荐）') // 对于iOS，可以增加证书类型选择参数 if (platform == 'iOS') { choiceParam('IOS_SIGNING_TYPE', ['development', 'app-store', 'ad-hoc'], 'iOS签名类型') } } // 2. 定义流水线脚本的来源（SCM） definition { cpsScm { scm { git { remote { url('https://github.com/your-company/your-unity-project.git') credentials('your-git-credential-id') // Jenkins中配置的凭据ID } branch(branch) extensions { } } } scriptPath('Jenkinsfile') // 指定仓库根目录下的Jenkinsfile为流水线脚本 } } // 3. 限制任务在特定标签的构建机上运行 label(platform == 'iOS' ? 'mac-slave' : 'windows-slave') } } }

这个脚本运行一次，就会自动创建出所有分支和平台组合的Jenkins任务。以后要新增分支或平台，只需修改这个脚本并重新运行即可。

4.2 构建执行：Pipeline脚本（Jenkinsfile）实战

Jenkinsfile是放在项目仓库根目录的流水线定义文件，它描述了完整的构建步骤。下面是一个高度精简但功能完整的示例：

// Jenkinsfile pipeline { agent { label params.PLATFORM == 'iOS' ? 'mac-slave' : 'windows-slave' } // 根据参数选择代理 parameters { choice(name: 'PLATFORM', choices: ['Windows', 'Android', 'iOS'], description: '选择构建平台') string(name: 'VERSION', defaultValue: '1.0.0', description: '版本号') choice(name: 'BUILD_TARGET', choices: ['Development', 'Release'], description: '构建目标') booleanParam(name: 'RUN_UNIT_TESTS', defaultValue: true, description: '是否运行单元测试') } environment { // 从Jenkins系统配置中读取Unity执行路径 UNITY_EXE = credentials('unity-executable-path') // 或者使用之前配置的全局变量 PROJECT_PATH = "${env.WORKSPACE}" // Jenkins自动拉取代码后的目录 BUILD_OUTPUT = "${env.JENKINS_HOME}/builds/${env.JOB_NAME}/${env.BUILD_NUMBER}" } stages { stage('代码检出与准备') { steps { checkout scm // 拉取代码 dir("${env.PROJECT_PATH}") { // 可以在这里执行一些预处理，比如生成版本文件 writeFile file: 'Assets/Version.txt', text: "${params.VERSION}" } } } stage('Unity编译与打包') { steps { script { def unityArgs = [ '-batchmode', '-nographics', '-quit', '-projectPath', "${env.PROJECT_PATH}", '-executeMethod', 'BuildScript.PerformBuild', // 调用项目内的静态方法 '-logFile', "${env.BUILD_OUTPUT}/unity_build.log" ] // 根据平台添加参数 switch(params.PLATFORM) { case 'Windows': unityArgs += ['-buildTarget', 'StandaloneWindows64'] break case 'Android': unityArgs += ['-buildTarget', 'Android'] unityArgs += ['-androidBuildType', params.BUILD_TARGET] break case 'iOS': unityArgs += ['-buildTarget', 'iOS'] break } // 执行Unity构建命令 bat(label: "执行Unity构建 (${params.PLATFORM})", script: "\"${env.UNITY_EXE}\" ${unityArgs.join(' ')}") // 在Mac上使用 sh 指令 } } } stage('iOS后处理与签名') { when { expression { return params.PLATFORM == 'iOS' } } steps { script { // 假设Unity导出Xcode工程到特定目录 def xcodeProjectPath = "${env.PROJECT_PATH}/Build/iOS" dir(xcodeProjectPath) { // 1. 自动修改Xcode工程配置（如Bundle Identifier， 从描述文件读取） // 2. 使用xcodebuild archive 和 exportArchive 进行打包和签名 // 3. 使用codesign和xcrun进行重签名（如果需要多证书出包） sh """ # 这里是一系列复杂的shell命令 xcodebuild -project Unity-iPhone.xcodeproj -scheme Unity-iPhone -configuration Release archive -archivePath ./build/Unity-iPhone.xcarchive xcodebuild -exportArchive -archivePath ./build/Unity-iPhone.xcarchive -exportOptionsPlist ExportOptions.plist -exportPath ./build/ipa """ } } } } stage('归档与通知') { steps { script { // 将构建产物归档到Jenkins服务器 archiveArtifacts artifacts: "Build/**/*.apk, Build/**/*.ipa, Build/**/*.exe", fingerprint: true // 将ipa/apk文件复制到网络共享目录 bat "copy /Y \"${env.BUILD_OUTPUT}\\*.ipa\" \"\\\\network-share\\builds\\${env.JOB_NAME}\\\"" // 发送成功通知到钉钉/企业微信 dingtalk( robot: 'your-robot-id', type: 'MARKDOWN', title: "构建成功: ${env.JOB_NAME}", text: "**项目**: ${env.JOB_NAME}\\n**版本**: ${params.VERSION}\\n**平台**: ${params.PLATFORM}\\n**构建号**: ${env.BUILD_NUMBER}\\n**下载链接**: [点击查看](${env.BUILD_URL})" ) } } } } post { always { // 总是清理临时文件 cleanWs() } failure { // 构建失败时发送告警通知 dingtalk( robot: 'your-robot-id', type: 'MARKDOWN', title: "❌ 构建失败: ${env.JOB_NAME}", text: "**项目**: ${env.JOB_NAME}\\n**构建号**: ${env.BUILD_NUMBER}\\n**请及时查看日志**: [点击查看](${env.BUILD_URL}/console)" ) } } }

4.3 Unity项目内的构建脚本（C#）

Jenkinsfile中调用了BuildScript.PerformBuild这个静态方法。这是需要在Unity项目内编写的C#脚本，放在Editor文件夹下。

// Assets/Editor/BuildScript.cs using UnityEditor; using UnityEngine; using System.IO; public static class BuildScript { public static void PerformBuild() { // 从命令行参数中获取构建目标和输出路径（Jenkins通过-executeMethod传递） // 这里简化处理，实际应从Environment.GetCommandLineArgs()解析 string[] args = System.Environment.GetCommandLineArgs(); string buildTargetStr = GetArgValue(args, "-buildTarget"); string outputPath = "Build"; // 可以做成可配置参数 BuildTarget buildTarget = BuildTarget.StandaloneWindows64; // 默认值 if (!string.IsNullOrEmpty(buildTargetStr)) { buildTarget = (BuildTarget)System.Enum.Parse(typeof(BuildTarget), buildTargetStr); } // 设置玩家设置 PlayerSettings.bundleVersion = "1.0.0"; // 应从外部传入，如读取文件 if (buildTarget == BuildTarget.Android) { PlayerSettings.Android.keyaliasPass = "yourpassword"; // 密码应从安全的凭据管理器中获取，而非硬编码 PlayerSettings.Android.keystorePass = "yourpassword"; } // 定义场景列表 string[] scenes = { "Assets/Scenes/Main.unity", "Assets/Scenes/Level1.unity" }; // 执行构建 BuildPipeline.BuildPlayer(scenes, Path.Combine(outputPath, GetExecutableName(buildTarget)), buildTarget, BuildOptions.None); } private static string GetArgValue(string[] args, string argName) { // 简易的参数解析逻辑 for (int i = 0; i < args.Length; i++) { if (args[i] == argName && i + 1 < args.Length) { return args[i + 1]; } } return null; } private static string GetExecutableName(BuildTarget target) { switch (target) { case BuildTarget.StandaloneWindows64: return "Game.exe"; case BuildTarget.Android: return "Game.apk"; case BuildTarget.iOS: return "iOS"; // Xcode工程目录 default: return "Build"; } } }

注意事项：绝对不要将密钥、证书密码等敏感信息硬编码在脚本或项目文件中！应该使用Jenkins的“凭据管理”功能，在Pipeline脚本中以withCredentials([file(credentialsId: 'android-keystore', variable: 'KEYSTORE_FILE')])等方式安全地注入到构建环境中。

5. 高级技巧与疑难问题排查

搭建好基础流水线只是第一步，要让其真正高效、可靠，还需要处理很多细节。

5.1 构建加速与缓存策略

Unity项目构建慢，主要慢在导入资源和编译脚本。我们可以利用缓存来加速。

• Library缓存：Unity项目的Library文件夹包含了导入资源后的中间数据。我们可以尝试在非“清理构建”时复用上一次的Library。但要注意，不同Unity版本、不同项目分支间的Library可能不兼容，直接复用可能导致诡异错误。更稳妥的做法是使用Unity的-cacheServer参数连接一个缓存服务器，它可以安全地共享Asset导入结果。
• 依赖包缓存：如果使用UPM或第三方包，可以配置环境变量NPM_CONFIG_CACHE或使用Unity的Package Manager缓存。
• IL2CPP编译缓存：对于IL2CPP后端，编译耗时很长。可以尝试将il2cpp_output_project目录缓存起来，但同样有兼容性风险。一种折中方案是，在开发期频繁构建时使用Mono后端，发布时再使用IL2CPP。

5.2 iOS自动化签名的深坑与填坑指南

iOS打包是自动化中最复杂的环节，核心在于签名。

1. 证书与描述文件管理：不要将.p12和.mobileprovision文件放在项目仓库里。应该将它们上传到Jenkins的“凭据管理”中（类型为“Secret file”），在构建时动态复制到构建工作空间。
2. 自动匹配签名身份：在Xcode工程导出后，我们需要用脚本自动修改project.pbxproj文件中的PROVISIONING_PROFILE_SPECIFIER和CODE_SIGN_IDENTITY。可以使用PlistBuddy和sed命令工具。
3. 重签名加速：这是提升iOS多包构建效率的神技。思路是：先完整构建并签名一个基准IPA（如AppStore包），然后使用codesign和zip/unzip命令，快速替换其中的描述文件和签名，生成其他类型（如Development, Ad-Hoc）的IPA。这避免了重复的编译和链接过程，速度提升非常明显。

   # 简化的重签名命令示例 unzip -q base.ipa -d temp/ rm -rf temp/Payload/MyApp.app/_CodeSignature/ cp new.mobileprovision temp/Payload/MyApp.app/embedded.mobileprovision codesign -f -s "iPhone Developer: ..." --entitlements entitlements.plist temp/Payload/MyApp.app cd temp && zip -qr ../resigned.ipa ./*

5.3 常见问题排查表

在自动化构建过程中，你一定会遇到各种失败。这里整理了一份快速排查清单：

5.4 扩展你的流水线：从CI到CD

基础的CI（持续集成）完成后，我们可以向CD（持续交付/部署）延伸：

• 自动化测试：在构建阶段后，加入stage('运行单元测试')，调用Unity的TestRunnerAPI执行项目中的PlayMode或EditMode测试。
• 自动化部署：
  • 内网测试：构建完成后，自动将APK/IPA上传到内部测试平台（如蒲公英、fir.im），并发送带下载二维码的通知。
  • 应用商店：对于Release版本，可以集成Fastlane工具，实现自动上传到App Store Connect或Google Play Console（需处理双因素认证等安全环节）。
• 资产管理与热更：可以扩展流水线，在构建主包后，自动调用AssetBundle打包脚本，计算差异，生成热更资源包并上传到资源服务器。

6. 维护与最佳实践

流水线搭建不是一劳永逸的，维护同样重要。

1. 版本化一切：Jenkinsfile、DSL脚本、Unity构建脚本、所有配置参数，都应该纳入代码仓库管理。这样任何变更都可追溯、可回滚。
2. 文档化：为团队编写清晰的文档，说明如何触发构建、如何查看日志、如何解读构建结果、遇到常见问题该怎么办。
3. 监控与告警：除了构建失败告警，还可以监控构建时长。如果某次构建时间异常增长，可能意味着项目引入了未经优化的巨大资源，需要及时排查。
4. 定期清理：配置Jenkins定期清理旧的构建历史和工作空间，防止磁盘被撑爆。
5. 安全第一：妥善保管所有证书、密钥、密码，全部使用Jenkins Credentials管理。定期审计流水线脚本，避免安全漏洞。

从我个人的经验来看，搭建自动化构建流水线的投入，在一个中等规模项目上，大约需要1-2人周。但这笔投资回报极高，通常在项目进行到第一次大规模测试时就能收回成本。它减少的人为错误、节省的沟通成本、提升的团队开发节奏，是难以用时间衡量的。最关键的是，它让开发者能更专注于创造性的编码工作，而不是重复性的打包操作。当你看到提交代码后，几分钟内就能在手机上收到自动安装好的测试包时，那种顺畅感会让你觉得一切努力都是值得的。