Unity多平台自动化构建实战基于Jenkins的参数化流水线设计当游戏项目需要同时面向iOS、Android和PC平台发布时频繁的手动打包不仅效率低下还容易因人为失误导致版本不一致。我曾经历过一次因打包参数配置错误导致iOS审核被拒的惨痛教训这促使我设计了一套基于Jenkins的自动化构建系统。本文将分享如何构建一个参数化、可扩展的多平台发布流水线。1. Jenkins环境配置与参数化设计1.1 基础环境搭建不同于简单的Jenkins安装针对Unity项目需要特别注意几个关键点# 推荐使用LTS版本的Jenkins wget https://get.jenkins.io/war-stable/2.346.3/jenkins.war java -jar jenkins.war --httpPort9090关键组件清单Unity3d Plugin必备Credentials Plugin管理证书Pipeline Plugin高级流水线注意JDK版本需与Unity Editor兼容建议使用JDK11-17之间的LTS版本1.2 参数化构建界面设计在Jenkins项目中勾选This project is parameterized后可以添加以下核心参数参数类型参数名称示例值作用ChoicePLATFORMiOS/Android/PC目标平台选择StringVERSION1.2.3应用版本号BooleanDEBUG_MODEtrue调试模式开关FileKEYSTOREandroid.keystoreAndroid签名文件// 示例参数化声明Declarative Pipeline语法 parameters { choice( name: PLATFORM, choices: [iOS, Android, Windows], description: 目标构建平台 ) string( name: VERSION_CODE, defaultValue: 100, description: 递增的版本号 ) }2. Unity与Jenkins的深度集成2.1 参数传递机制参数从Jenkins传递到Unity有三种推荐方式JSON配置文件适合复杂参数# 生成配置文件的Shell示例 echo { platform: $PLATFORM, version: $VERSION } build_config.json命令行参数适合简单参数Unity -quit -batchmode -executeMethod BuildScript.PerformBuild \ -projectPath $PROJECT_PATH \ -buildTarget $PLATFORM \ -versionCode $VERSION_CODE环境变量适合敏感信息// Unity中读取环境变量 string keystorePass Environment.GetEnvironmentVariable(ANDROID_KEYSTORE_PASS);2.2 平台特定处理逻辑不同平台需要不同的预处理iOS特殊配置// 在Unity构建脚本中处理iOS证书 #if UNITY_IOS PlayerSettings.iOS.appleEnableAutomaticSigning false; PlayerSettings.iOS.iOSManualProvisioningProfileID your-profile-id; #endifAndroid签名配置# Jenkins中配置自动签名 jarsigner -verbose -sigalg SHA256withRSA \ -digestalg SHA-256 \ -keystore $KEYSTORE_PATH \ -storepass $STORE_PASS \ $UNSIGNED_APK \ $ALIAS_NAME3. 构建流水线优化策略3.1 多阶段构建设计典型的构建阶段划分准备阶段清理工作空间下载依赖资源参数校验构建阶段Unity批量模式构建平台特定后处理归档阶段生成版本说明文件压缩打包上传到内部分发系统pipeline { stages { stage(Prep) { steps { cleanWs() git branch: main, url: your-repo-url } } stage(Build) { steps { script { def unityPath tool name: Unity2021, type: com.unity3d.unity3d bat ${unityPath}\\Unity.exe -quit -batchmode -projectPath . -executeMethod Builder.${params.PLATFORM}Build } } } stage(Archive) { steps { archiveArtifacts artifacts: Builds/**/* } } } }3.2 构建缓存优化通过缓存以下目录可以显著提升构建速度Library/ScriptAssembliesLibrary/BeeAssets/AssetBundles# Jenkins声明式流水线中的缓存配置 pipeline { agent any options { skipDefaultCheckout() timeout(time: 1, unit: HOURS) } stages { stage(Build) { steps { cache(path: Library/ScriptAssemblies, includes: **/*.dll) { // 构建步骤 } } } } }4. 热更新与版本管理4.1 热更资源构建热更新资源构建需要特别注意版本对应关系资源版本兼容App版本强制更新1.0.01.0.0否1.1.01.1.0-1.2.0是// Unity中的热更版本检查逻辑 public static bool CheckResourceCompatibility(string appVersion, string resVersion) { Version appVer new Version(appVersion); Version resVer new Version(resVersion); return appVer resVer; }4.2 自动化版本管理推荐使用语义化版本控制SemVer并自动递增# 自动递增版本号的Shell脚本 LAST_VERSION$(git describe --tags --abbrev0) MAJOR$(echo $LAST_VERSION | cut -d. -f1) MINOR$(echo $LAST_VERSION | cut -d. -f2) PATCH$(echo $LAST_VERSION | cut -d. -f3) NEW_VERSION$MAJOR.$MINOR.$((PATCH1))5. 异常处理与日志系统5.1 构建失败处理构建流水线中必须包含完善的错误处理post { always { script { // 上传构建日志 archiveArtifacts artifacts: **/*.log } } failure { emailext body: 构建失败: ${BUILD_URL}, subject: 【构建失败】${JOB_NAME}, to: teamexample.com } }5.2 统一日志规范建议在Unity中使用自定义日志系统public class BuildLogger { private static StreamWriter _logWriter; public static void Init(string logPath) { _logWriter new StreamWriter(logPath); Application.logMessageReceived HandleLog; } private static void HandleLog(string message, string stackTrace, LogType type) { string logEntry $[{DateTime.Now}] [{type}] {message}; _logWriter.WriteLine(logEntry); if(type LogType.Error) { _logWriter.WriteLine(stackTrace); } } }在实际项目中这套系统将构建时间从原来手动操作的2小时缩短到20分钟且版本一致性达到100%。最难能可贵的是新加入团队的开发者只需在Jenkins界面选择参数即可完成专业级的构建操作不再需要深入理解各平台的构建细节。