建實戰(zhàn)：從命令行到腳本實現(xiàn)輕量級CI/CD)
1. 項目概述為什么我們需要一個“簡單的構(gòu)建機(jī)”如果你是一個獨立開發(fā)者或者在一個小團(tuán)隊里負(fù)責(zé)Unity項目的打包工作可能覺得每次在編輯器里點一下“Build”按鈕等上十幾分鐘甚至更久然后手動把生成的包復(fù)制到測試服務(wù)器或者上傳到分發(fā)平臺并不是什么大問題。但當(dāng)你需要每天構(gòu)建十幾個不同分支的版本或者需要在凌晨自動為QA團(tuán)隊生成最新的測試包時這種重復(fù)、耗時且容易出錯的手動操作就會迅速變成一個效率瓶頸和潛在的風(fēng)險點。這就是“構(gòu)建機(jī)”要解決的問題。它本質(zhì)上是一個自動化腳本或程序能夠代替人工完成從代碼拉取、依賴解析、項目編譯、資源打包到最終產(chǎn)物歸檔、分發(fā)的全過程。一個“簡單”的構(gòu)建機(jī)核心目標(biāo)就是把這套流程自動化、標(biāo)準(zhǔn)化把開發(fā)者從重復(fù)勞動中解放出來并確保每次構(gòu)建的環(huán)境和過程都是一致的從而提升開發(fā)效率和構(gòu)建產(chǎn)物的可靠性。我經(jīng)歷過從手動打包到搭建自動化構(gòu)建管道的完整過程深知其中的痛點比如本地環(huán)境配置不同導(dǎo)致的“在我機(jī)器上是好的”問題比如忘記切換場景列表導(dǎo)致測試包缺少關(guān)鍵關(guān)卡又比如深夜被叫起來手動打個熱更包。基于這些實際需求我將分享如何用最直接、最輕量的方式為你的Unity項目搭建一個可用的構(gòu)建機(jī)。這個方案不依賴復(fù)雜昂貴的商業(yè)CI/CD服務(wù)而是基于命令行和腳本讓你能快速上手理解其核心原理并能根據(jù)自己項目的實際情況進(jìn)行定制。2. 構(gòu)建機(jī)核心設(shè)計思路與方案選型在動手寫代碼之前我們需要明確這個“簡單構(gòu)建機(jī)”的邊界和能力。它不應(yīng)該試圖一開始就做成Jenkins或GitLab CI那樣功能龐雜的系統(tǒng)而是聚焦于解決Unity項目構(gòu)建自動化中最核心、最通用的幾個環(huán)節(jié)。2.1 核心需求拆解一個最小可用的Unity構(gòu)建機(jī)至少需要完成以下任務(wù)環(huán)境準(zhǔn)備確保構(gòu)建服務(wù)器或本地機(jī)器上安裝了正確版本的Unity Editor以及目標(biāo)平臺所需的SDK如Android SDK/NDK、iOS Xcode。獲取最新代碼從版本控制系統(tǒng)如Git拉取指定分支的最新代碼。執(zhí)行Unity構(gòu)建命令這是核心通過命令行調(diào)用Unity Editor以“批處理模式”執(zhí)行構(gòu)建生成最終的應(yīng)用程序包APK、IPA、EXE等。處理構(gòu)建結(jié)果將構(gòu)建產(chǎn)物可能包含多個文件復(fù)制到指定的歸檔目錄并可按需進(jìn)行重命名、版本號注入等操作。通知與日志構(gòu)建完成后無論成功與否都需要有明確的日志輸出并最好能通過某種方式如郵件、釘釘/飛書機(jī)器人通知相關(guān)人員。2.2 技術(shù)方案選型為什么選擇命令行 腳本市面上有成熟的CI/CD方案比如Jenkins、GitLab CI/CD、GitHub Actions、Azure DevOps等。它們功能強(qiáng)大有豐富的插件和可視化界面。但對于一個“簡單”的構(gòu)建機(jī)來說它們可能顯得過于重型學(xué)習(xí)和配置成本較高。我們的目標(biāo)是快速實現(xiàn)、易于理解和維護(hù)。因此我推薦的核心方案是Unity命令行接口 Shell/Python腳本。Unity命令行Unity Editor本身提供了強(qiáng)大的命令行參數(shù)允許我們在無圖形界面的情況下執(zhí)行構(gòu)建、批量處理資源等操作。這是實現(xiàn)自動化的基石。Shell/Batch腳本在Windows上可以用.bat或.ps1在macOS/Linux上可以用.sh。腳本負(fù)責(zé)串聯(lián)整個流程拉代碼、調(diào)用Unity、處理文件。它的優(yōu)勢是輕量、直接與操作系統(tǒng)結(jié)合緊密。Python腳本如果你需要更復(fù)雜的邏輯比如解析JSON配置文件、進(jìn)行HTTP請求發(fā)送通知、更精細(xì)的文件操作等Python是更佳選擇。它跨平臺庫豐富可讀性強(qiáng)。對于大多數(shù)中小項目一個精心編寫的Shell腳本配合Unity命令行就完全夠用了。我們將以這個組合為例進(jìn)行展開。選擇這個方案你不僅能快速搭建起來還能透徹理解自動化構(gòu)建的每一個步驟未來無論是遷移到更專業(yè)的CI平臺還是擴(kuò)展功能都會心中有數(shù)。3. 構(gòu)建環(huán)境準(zhǔn)備與Unity命令行基礎(chǔ)在編寫自動化腳本之前我們必須確保構(gòu)建環(huán)境是正確且可重復(fù)的。這是避免“構(gòu)建環(huán)境差異”導(dǎo)致問題的關(guān)鍵。3.1 安裝與定位Unity Editor構(gòu)建機(jī)上需要安裝Unity Hub和指定版本的Unity Editor。不建議直接使用安裝程序默認(rèn)路徑最好通過命令行能準(zhǔn)確定位到Unity可執(zhí)行文件。Windows通常路徑為C:\Program Files\Unity\Hub\Editor\Version\Editor\Unity.exemacOS通常路徑為/Applications/Unity/Hub/Editor/Version/Unity.app/Contents/MacOS/UnityLinux路徑類似/opt/unity/Editor/Version/Unity在腳本中我們應(yīng)該將Unity路徑定義為一個變量方便修改和移植。# 示例在Shell腳本中定義Unity路徑 (macOS/Linux) UNITY_PATH/Applications/Unity/Hub/Editor/2022.3.20f1/Unity.app/Contents/MacOS/Unity # 示例在Batch腳本中定義Unity路徑 (Windows) SET UNITY_PATHC:\Program Files\Unity\Hub\Editor\2022.3.20f1\Editor\Unity.exe注意構(gòu)建機(jī)使用的Unity版本必須與項目設(shè)置中指定的版本嚴(yán)格一致。否則可能會遇到API不兼容、資源格式錯誤等問題。建議在團(tuán)隊內(nèi)部明確項目使用的Unity LTS版本并在構(gòu)建機(jī)上固定安裝此版本。3.2 理解核心Unity命令行參數(shù)Unity命令行的魔力在于一系列參數(shù)。以下是構(gòu)建機(jī)最常用的幾個-batchmode這是最重要的參數(shù)。它讓Unity以批處理模式運(yùn)行不顯示圖形界面不彈出對話框執(zhí)行完畢后自動關(guān)閉。這是自動化構(gòu)建的前提。-quit在執(zhí)行完其他命令后退出Unity編輯器。通常與-batchmode聯(lián)用。-projectPath path指定要打開的Unity項目路徑。必須是絕對路徑。-executeMethod ClassName.MethodName指定一個在編輯器模式下執(zhí)行的靜態(tài)方法。這是我們構(gòu)建邏輯的入口點。-buildTarget target指定構(gòu)建目標(biāo)平臺例如Android,iOS,StandaloneWindows64,WebGL等。-logFile path將Unity的日志輸出到指定文件。對于排查構(gòu)建失敗原因至關(guān)重要。如果不指定默認(rèn)輸出到控制臺。一個最簡單的構(gòu)建命令看起來像這樣${UNITY_PATH} -batchmode -quit -projectPath /path/to/your/project -executeMethod BuildScript.PerformBuild -logFile build.log這條命令會以無界面模式打開指定項目執(zhí)行BuildScript類中的PerformBuild靜態(tài)方法然后將日志寫入build.log文件最后退出。3.3 目標(biāo)平臺SDK配置Android需要安裝JDK注意Unity版本對JDK版本有要求如2022.3通常需要JDK 11-17、Android SDK和NDK。環(huán)境變量JAVA_HOME,ANDROID_SDK_ROOT,ANDROID_NDK_HOME必須正確設(shè)置。Unity安裝時通常會捆綁安裝這些但構(gòu)建機(jī)上最好獨立安裝并確認(rèn)版本兼容性。iOS需要在macOS系統(tǒng)上安裝Xcode及命令行工具。構(gòu)建過程會調(diào)用xcodebuild。其他平臺如Windows、Linux、WebGL通常Unity自帶運(yùn)行時無需額外配置。實操心得建議將構(gòu)建環(huán)境包括Unity版本、SDK版本、環(huán)境變量配置通過Docker容器或虛擬機(jī)鏡像進(jìn)行固化。這樣可以在任何機(jī)器上快速復(fù)現(xiàn)完全一致的構(gòu)建環(huán)境是走向“持續(xù)集成”的重要一步。對于小型團(tuán)隊至少應(yīng)該有一份詳細(xì)的《構(gòu)建環(huán)境配置手冊》。4. 編寫核心構(gòu)建腳本C#編輯器腳本Unity命令行通過-executeMethod調(diào)用的方法需要寫在一個編輯器腳本中。這個腳本需要放在項目的Assets/Editor目錄下或其子目錄。4.1 構(gòu)建腳本基本結(jié)構(gòu)讓我們創(chuàng)建一個BuildScript.cs文件。using UnityEditor; using UnityEngine; using System.IO; using System.Linq; public static class BuildScript { // 這是一個可以被命令行調(diào)用的方法 public static void PerformBuild() { // 1. 獲取命令行參數(shù)可選 string[] args System.Environment.GetCommandLineArgs(); string buildTargetStr GetArgument(args, buildTarget); string outputPath GetArgument(args, outputPath); // 2. 設(shè)置構(gòu)建選項 BuildPlayerOptions buildOptions new BuildPlayerOptions(); // 2.1 設(shè)置需要構(gòu)建的場景 // 注意這里獲取的是在Build Settings窗口中勾選的場景這是最可靠的方式。 buildOptions.scenes EditorBuildSettings.scenes .Where(s s.enabled) .Select(s s.path) .ToArray(); if (buildOptions.scenes.Length 0) { Debug.LogError(No scenes added to Build Settings!); EditorApplication.Exit(1); // 非零退出碼表示失敗 return; } // 2.2 設(shè)置構(gòu)建目標(biāo) BuildTarget target BuildTarget.NoTarget; if (!System.Enum.TryParse(buildTargetStr, true, out target)) { // 如果命令行沒指定可以設(shè)置一個默認(rèn)值比如打Android包 target BuildTarget.Android; } buildOptions.target target; // 2.3 設(shè)置輸出路徑 if (string.IsNullOrEmpty(outputPath)) { // 生成一個帶時間戳的默認(rèn)路徑 string projectName PlayerSettings.productName.Replace( , _); string dateTime System.DateTime.Now.ToString(yyyyMMdd_HHmmss); outputPath Path.Combine(Builds, target.ToString(), ${projectName}_{dateTime}); } // 確保輸出目錄存在 Directory.CreateDirectory(Path.GetDirectoryName(outputPath)); buildOptions.locationPathName outputPath; // 2.4 設(shè)置其他選項 buildOptions.options BuildOptions.None; // 正式發(fā)布 // buildOptions.options BuildOptions.Development | BuildOptions.AllowDebugging; // 開發(fā)調(diào)試包 // 3. 執(zhí)行構(gòu)建 BuildReport report BuildPipeline.BuildPlayer(buildOptions); // 4. 處理構(gòu)建結(jié)果 if (report.summary.result BuildResult.Succeeded) { Debug.Log($Build succeeded! Output path: {outputPath}); Debug.Log($Build size: {report.summary.totalSize / (1024 * 1024):F2} MB); EditorApplication.Exit(0); // 退出碼0表示成功 } else { Debug.LogError($Build failed with {report.summary.totalErrors} error(s).); // 錯誤信息已經(jīng)在之前的日志中打印了 EditorApplication.Exit(1); } } // 一個簡單的輔助函數(shù)用于從命令行參數(shù)中提取值 // 例如-buildTarget Android -outputPath “C:\Builds” private static string GetArgument(string[] args, string name) { for (int i 0; i args.Length; i) { if (args[i] $-{name} i 1 args.Length) { return args[i 1]; } } return null; } }4.2 關(guān)鍵點解析與注意事項場景列表來源代碼中通過EditorBuildSettings.scenes獲取場景列表。這是最佳實踐。它直接讀取你在Unity編輯器菜單File - Build Settings中勾選的場景順序。這確保了自動化構(gòu)建和你在編輯器里手動構(gòu)建的內(nèi)容完全一致。永遠(yuǎn)不要在腳本里硬編碼場景路徑。輸出路徑管理腳本中包含了簡單的路徑生成邏輯。在實際使用中你可能希望從命令行參數(shù)-outputPath傳入或者根據(jù)公司規(guī)范生成固定的目錄結(jié)構(gòu)如Builds/Android/Prod/。構(gòu)建選項BuildOptions枚舉非常重要。BuildOptions.None用于發(fā)布正式包。BuildOptions.Development生成開發(fā)包包含調(diào)試符號允許連接Profiler和Debugger。BuildOptions.AllowDebugging允許腳本調(diào)試。BuildOptions.CompressWithLz4HC使用LZ4HC高壓縮率壓縮資源能有效減小包體。 你可以根據(jù)構(gòu)建目的測試/發(fā)布進(jìn)行組合。退出碼EditorApplication.Exit(0或1)是告訴調(diào)用腳本如Shell構(gòu)建成功與否的關(guān)鍵。0代表成功非0代表失敗。外層的Shell腳本可以根據(jù)這個退出碼決定后續(xù)操作如發(fā)送成功通知或失敗告警。踩坑記錄曾經(jīng)遇到過構(gòu)建腳本在本地運(yùn)行成功但在構(gòu)建機(jī)上失敗的情況。排查后發(fā)現(xiàn)是因為構(gòu)建機(jī)上的項目Build Settings里一個場景都沒勾選。因此腳本開頭對場景數(shù)量的檢查非常必要。另外確保Editor腳本中沒有使用任何僅在編輯器運(yùn)行時才存在的API如某些GUI調(diào)用因為在批處理模式下這些API可能行為異常。5. 外層驅(qū)動腳本串聯(lián)整個自動化流程有了核心的C#構(gòu)建腳本我們還需要一個外層的“驅(qū)動”腳本來組織整個流程。這個腳本可以用Shellbash/powershell或Python來寫。這里以Bash腳本為例因為它非常直觀。5.1 一個完整的Bash構(gòu)建腳本示例假設(shè)我們的項目在/home/ci/unity-project 我們要構(gòu)建Android版本。#!/bin/bash # 文件名build_android.sh # 嚴(yán)格模式遇到錯誤即停止 set -e echo Unity項目自動化構(gòu)建開始 echo 時間: $(date) # 1. 定義變量 PROJECT_PATH/home/ci/unity-project UNITY_PATH/Applications/Unity/Hub/Editor/2022.3.20f1/Unity.app/Contents/MacOS/Unity BUILD_TARGETAndroid # 構(gòu)建產(chǎn)物輸出到帶時間戳的目錄 OUTPUT_DIR${PROJECT_PATH}/Builds/Android/$(date %Y%m%d_%H%M%S) LOG_FILE${OUTPUT_DIR}/build.log echo 項目路徑: ${PROJECT_PATH} echo Unity路徑: ${UNITY_PATH} echo 構(gòu)建目標(biāo): ${BUILD_TARGET} echo 輸出目錄: ${OUTPUT_DIR} # 2. 創(chuàng)建輸出目錄 mkdir -p ${OUTPUT_DIR} # 3. 執(zhí)行Unity構(gòu)建命令 echo 開始執(zhí)行Unity構(gòu)建... ${UNITY_PATH} \ -batchmode \ -quit \ -projectPath ${PROJECT_PATH} \ -executeMethod BuildScript.PerformBuild \ -buildTarget ${BUILD_TARGET} \ -outputPath ${OUTPUT_DIR}/MyGame.apk \ -logFile ${LOG_FILE} \ -nographics # 對于無顯示服務(wù)器的環(huán)境如純命令行Linux可能需要此參數(shù) # 檢查Unity進(jìn)程退出碼 UNITY_EXIT_CODE$? echo Unity進(jìn)程退出碼: ${UNITY_EXIT_CODE} # 4. 檢查構(gòu)建結(jié)果 if [ ${UNITY_EXIT_CODE} -eq 0 ]; then echo ? 構(gòu)建成功 echo 構(gòu)建日志已保存至: ${LOG_FILE} echo APK文件位于: ${OUTPUT_DIR} # 5. 成功后的操作可選 # 例如復(fù)制APK到共享目錄、上傳到內(nèi)網(wǎng)測試平臺、發(fā)送成功通知等 # cp ${OUTPUT_DIR}/MyGame.apk /shared_drive/latest_test.apk # send_notification success Android構(gòu)建成功 else echo ? 構(gòu)建失敗退出碼: ${UNITY_EXIT_CODE} echo 構(gòu)建日志最后50行 tail -n 50 ${LOG_FILE} echo 日志結(jié)束 # 6. 失敗后的操作可選 # 例如發(fā)送失敗告警郵件/消息包含錯誤日志片段 # send_notification failure Android構(gòu)建失敗請查看日志: ${LOG_FILE} exit 1 # 整個腳本以失敗狀態(tài)退出 fi echo 構(gòu)建流程結(jié)束 5.2 腳本關(guān)鍵環(huán)節(jié)詳解set -e這是一個好習(xí)慣。它使得腳本中任何一條命令失敗返回非零狀態(tài)時整個腳本立即停止。這能防止錯誤被忽略導(dǎo)致后續(xù)操作在錯誤的狀態(tài)下進(jìn)行。變量定義將所有路徑、版本號等配置抽成變量放在腳本開頭便于管理和修改。目錄創(chuàng)建在調(diào)用Unity之前先創(chuàng)建好輸出目錄。避免Unity因路徑不存在而報錯。Unity命令行參數(shù)-nographics在Linux服務(wù)器等沒有圖形界面的環(huán)境下是必須的否則Unity可能會啟動失敗。我們將-outputPath參數(shù)傳遞給了C#腳本。C#腳本中的GetArgument函數(shù)會解析它。-logFile指定了日志路徑。一定要保存日志這是事后排查問題的唯一依據(jù)。退出碼檢查$?獲取上一條命令Unity進(jìn)程的退出碼。我們根據(jù)C#腳本中EditorApplication.Exit()傳入的值來判斷構(gòu)建成功與否。日志處理構(gòu)建失敗時腳本使用tail -n 50打印日志的最后50行。通常錯誤信息就在末尾。你也可以將整個日志文件作為附件發(fā)送。5.3 擴(kuò)展集成版本控制Git一個完整的構(gòu)建機(jī)通常需要從代碼倉庫拉取最新代碼。我們可以在執(zhí)行Unity構(gòu)建前加入Git操作。# 在Bash腳本中Unity構(gòu)建命令之前加入 BRANCHdevelop # 或通過參數(shù)傳入 echo 切換到分支: ${BRANCH} cd ${PROJECT_PATH} git fetch origin git checkout ${BRANCH} git pull origin ${BRANCH} echo 最新提交: $(git log -1 --oneline) # 可選獲取本次構(gòu)建的提交哈希用于標(biāo)記版本 COMMIT_HASH$(git rev-parse --short HEAD) # 可以將這個哈希值通過某種方式如寫入一個文本文件包含到構(gòu)建產(chǎn)物中 echo ${COMMIT_HASH} ${OUTPUT_DIR}/build_info.txt注意事項確保構(gòu)建機(jī)上的Git用戶有倉庫的拉取權(quán)限并且配置好了SSH密鑰或賬號密碼。對于需要認(rèn)證的私有倉庫這是常見的配置點。6. 高級功能與定制化基礎(chǔ)構(gòu)建流程跑通后可以根據(jù)項目需求添加更多功能。6.1 版本號自動遞增在打包時自動遞增版本號如1.0.123中的123是常見需求。這可以通過修改PlayerSettings來實現(xiàn)。在BuildScript.cs中可以在構(gòu)建前添加如下代碼[MenuItem(Build/Increment Version)] public static void IncrementVersionAndBuild() { // 讀取當(dāng)前版本號例如 1.0.123 string currentVersion PlayerSettings.bundleVersion; // 簡單的遞增邏輯假設(shè)版本格式為 Major.Minor.Build string[] parts currentVersion.Split(.); if (parts.Length 3 int.TryParse(parts[2], out int buildNumber)) { buildNumber; string newVersion ${parts[0]}.{parts[1]}.{buildNumber}; PlayerSettings.bundleVersion newVersion; PlayerSettings.Android.bundleVersionCode buildNumber; // Android版本碼也遞增 // iOS的CFBundleVersion也需要設(shè)置但更復(fù)雜涉及Info.plist Debug.Log($Version updated to: {newVersion}); // 保存項目設(shè)置 AssetDatabase.SaveAssets(); } else { Debug.LogWarning($Could not parse version: {currentVersion}. Using default.); } // 然后調(diào)用構(gòu)建方法 PerformBuild(); }你可以修改這個函數(shù)或者從外部文件如version.txt讀取和寫入版本號實現(xiàn)更復(fù)雜的版本管理策略。6.2 多平臺構(gòu)建與參數(shù)化我們的腳本目前寫死了構(gòu)建Android。我們可以改造它使其能通過命令行參數(shù)構(gòu)建任意平臺。修改Bash腳本從命令行接收參數(shù)#!/bin/bash # build.sh # 用法./build.sh -p Android -b develop while getopts p:b: opt; do case $opt in p) BUILD_TARGET$OPTARG ;; b) GIT_BRANCH$OPTARG ;; ?) echo Usage: $0 -p Platform -b Branch; exit 1 ;; esac done # 設(shè)置默認(rèn)值 BUILD_TARGET${BUILD_TARGET:-Android} GIT_BRANCH${GIT_BRANCH:-main} # ... 后續(xù)流程使用這些變量然后在調(diào)用Unity時將-buildTarget ${BUILD_TARGET}參數(shù)傳入即可。6.3 構(gòu)建后處理自動上傳與通知構(gòu)建成功后的APK/IPA需要分發(fā)給測試人員?？梢约珊唵蔚奈募蟼骱拖⑼ㄖ?。上傳到內(nèi)網(wǎng)服務(wù)器/FTP使用scp,rsync或curl命令。# 示例使用scp上傳到測試服務(wù)器 REMOTE_USERtester REMOTE_HOSTtest-server.com REMOTE_PATH/var/www/html/downloads/latest.apk scp ${OUTPUT_DIR}/MyGame.apk ${REMOTE_USER}${REMOTE_HOST}:${REMOTE_PATH}發(fā)送通知到釘釘/飛書/企業(yè)微信這些平臺都提供了Webhook接口。可以使用curl發(fā)送一個HTTP POST請求。# 示例發(fā)送釘釘機(jī)器人通知 WEBHOOK_URLhttps://oapi.dingtalk.com/robot/send?access_tokenYOUR_TOKEN JSON_DATA$(cat EOF { msgtype: text, text: { content: Unity構(gòu)建通知項目${PROJECT_NAME} ${BUILD_TARGET}平臺構(gòu)建${BUILD_RESULT}\n版本${NEW_VERSION}\n提交${COMMIT_HASH}\n日志${LOG_URL} } } EOF ) curl -H Content-Type: application/json -X POST -d ${JSON_DATA} ${WEBHOOK_URL}將${BUILD_RESULT}成功/失敗、版本號、提交哈希等信息填入消息內(nèi)容。7. 常見問題排查與實戰(zhàn)技巧即使腳本寫得再完善在實際運(yùn)行中也會遇到各種問題。這里記錄一些典型的“坑”和解決方法。7.1 Unity構(gòu)建失敗常見原因速查表現(xiàn)象/錯誤信息可能原因排查步驟與解決方案UnityException: BuildPipeline.BuildPlayer:...后跟模糊錯誤項目配置問題場景問題腳本編譯錯誤。1. 查看詳細(xì)日志這是最重要的。檢查-logFile指定的文件搜索error或Exception。2. 檢查場景確認(rèn)Build Settings中至少有一個場景被勾選且路徑有效。3. 在編輯器中試構(gòu)建先在Unity編輯器里手動構(gòu)建一次看是否有錯誤提示。構(gòu)建成功但APK安裝后閃退缺少依賴庫如Android ARM64支持腳本存在運(yùn)行時錯誤資源加載失敗。1. 檢查Player Settings確保目標(biāo)架構(gòu)如ARMv7, ARM64已勾選。2. 打開發(fā)布包使用BuildOptions.Development和BuildOptions.AllowDebugging選項構(gòu)建一個開發(fā)包通過ADB或Xcode查看運(yùn)行時日志。3. 檢查資源確認(rèn)所有動態(tài)加載的資源如AssetBundle路徑正確且已打包。批處理模式卡住不退出腳本中有彈出窗口如EditorUtility.DisplayDialog或存在無限循環(huán)。1. 避免交互確保在Editor腳本中批處理模式下絕不使用任何會彈出對話框的API。2. 超時處理在外層Shell腳本中設(shè)置超時例如使用timeout命令timeout 1800s unity_command設(shè)置30分鐘超時。CommandNotFoundException: unityUnity可執(zhí)行文件路徑錯誤或沒有執(zhí)行權(quán)限。1. 檢查路徑使用ls -la “${UNITY_PATH}”確認(rèn)文件存在。2. 賦予執(zhí)行權(quán)限chmod x “${UNITY_PATH}”(Unix系統(tǒng))。3. 使用絕對路徑。Android構(gòu)建失敗提示JDK、SDK找不到環(huán)境變量未正確設(shè)置或Unity版本與JDK版本不兼容。1. 確認(rèn)環(huán)境變量在構(gòu)建機(jī)上執(zhí)行echo $JAVA_HOME,echo $ANDROID_SDK_ROOT。2. 指定路徑可以在Unity安裝目錄下的Editor/Data/PlaybackEngines/AndroidPlayer找到SDK,NDK,JDK目錄并在Unity命令行中通過-androidSdkPath,-androidNdkPath,-androidJavaSdkPath參數(shù)指定。這是最可靠的方式。構(gòu)建產(chǎn)物巨大未啟用壓縮包含了不必要的資源如高清紋理所有Mipmap。1. 檢查壓縮設(shè)置在BuildPlayerOptions.options中加入BuildOptions.CompressWithLz4HC。2. 檢查Player Settings在Player Settings - Other Settings中可以關(guān)閉Prebake Collision Meshes如果不需服務(wù)器物理調(diào)整Strip Engine Code等。3. 使用Asset Bundle將資源分離動態(tài)下載。7.2 實戰(zhàn)心得與技巧日志是你的生命線一定要保存并定期查看構(gòu)建日志。建議將每次構(gòu)建的日志文件都?xì)w檔文件名包含時間戳和構(gòu)建結(jié)果成功/失敗?？梢允褂胻ee命令同時輸出到屏幕和文件unity_command 21 | tee “${LOG_FILE}”。從小處著手逐步迭代不要試圖一次性實現(xiàn)一個功能完備的構(gòu)建機(jī)。先實現(xiàn)最基本的命令行構(gòu)建成功。然后加上Git拉取代碼。再加上版本號管理。最后處理通知和上傳。每完成一步都進(jìn)行測試。使用版本控制管理構(gòu)建腳本你的構(gòu)建腳本本身也應(yīng)該放入Git倉庫。這樣構(gòu)建邏輯的變更可以被追蹤和回滾。準(zhǔn)備一個“干凈”的構(gòu)建代理如果條件允許使用一臺獨立的、只安裝必要軟件的機(jī)器或Docker容器作為構(gòu)建機(jī)。避免因本地開發(fā)環(huán)境安裝的各種插件、工具影響構(gòu)建的穩(wěn)定性和可重復(fù)性。處理Unity許可證無圖形界面的服務(wù)器上運(yùn)行Unity需要激活許可證?？梢允褂?manualLicenseFile參數(shù)指定一個已有的許可證文件或者使用-batchmode -quit -logFile -createManualActivationFile生成許可證請求文件然后在有圖形界面的機(jī)器上激活后將許可證文件拷貝回來。對于團(tuán)隊考慮使用浮動許可證服務(wù)器。性能考量Unity項目首次構(gòu)建會很慢因為要導(dǎo)入和預(yù)處理所有資源。可以利用Unity的BuildOptions.AcceptExternalModificationsToPlayer選項進(jìn)行增量構(gòu)建但需謹(jǐn)慎有時會引入奇怪問題。更穩(wěn)妥的方式是定期清理Library文件夾進(jìn)行全量構(gòu)建以保證一致性。搭建一個簡單的Unity構(gòu)建機(jī)核心在于理解“自動化”的本質(zhì)用確定的腳本代替不確定的人工操作。通過本文拆解的步驟——從環(huán)境準(zhǔn)備、命令行參數(shù)理解到核心C#構(gòu)建腳本、外層驅(qū)動腳本的編寫再到高級功能的擴(kuò)展和問題排查——你應(yīng)該已經(jīng)掌握了搭建一個滿足基本需求的自動化構(gòu)建流程的能力。這個流程將成為你項目研發(fā)的基礎(chǔ)設(shè)施它的穩(wěn)定運(yùn)行意味著更快的迭代速度、更少的低級錯誤和更高的團(tuán)隊協(xié)作效率。 Unity自動化構(gòu)建實戰(zhàn)：從命令行到腳本實現(xiàn)輕量級CI/CD
1. 項目概述為什么我們需要一個“簡單的構(gòu)建機(jī)”如果你是一個獨立開發(fā)者或者在一個小團(tuán)隊里負(fù)責(zé)Unity項目的打包工作可能覺得每次在編輯器里點一下“Build”按鈕等上十幾分鐘甚至更久然后手動把生成的包復(fù)制到測試服務(wù)器或者上傳到分發(fā)平臺并不是什么大問題。但當(dāng)你需要每天構(gòu)建十幾個不同分支的版本或者需要在凌晨自動為QA團(tuán)隊生成最新的測試包時這種重復(fù)、耗時且容易出錯的手動操作就會迅速變成一個效率瓶頸和潛在的風(fēng)險點。這就是“構(gòu)建機(jī)”要解決的問題。它本質(zhì)上是一個自動化腳本或程序能夠代替人工完成從代碼拉取、依賴解析、項目編譯、資源打包到最終產(chǎn)物歸檔、分發(fā)的全過程。一個“簡單”的構(gòu)建機(jī)核心目標(biāo)就是把這套流程自動化、標(biāo)準(zhǔn)化把開發(fā)者從重復(fù)勞動中解放出來并確保每次構(gòu)建的環(huán)境和過程都是一致的從而提升開發(fā)效率和構(gòu)建產(chǎn)物的可靠性。我經(jīng)歷過從手動打包到搭建自動化構(gòu)建管道的完整過程深知其中的痛點比如本地環(huán)境配置不同導(dǎo)致的“在我機(jī)器上是好的”問題比如忘記切換場景列表導(dǎo)致測試包缺少關(guān)鍵關(guān)卡又比如深夜被叫起來手動打個熱更包。基于這些實際需求我將分享如何用最直接、最輕量的方式為你的Unity項目搭建一個可用的構(gòu)建機(jī)。這個方案不依賴復(fù)雜昂貴的商業(yè)CI/CD服務(wù)而是基于命令行和腳本讓你能快速上手理解其核心原理并能根據(jù)自己項目的實際情況進(jìn)行定制。2. 構(gòu)建機(jī)核心設(shè)計思路與方案選型在動手寫代碼之前我們需要明確這個“簡單構(gòu)建機(jī)”的邊界和能力。它不應(yīng)該試圖一開始就做成Jenkins或GitLab CI那樣功能龐雜的系統(tǒng)而是聚焦于解決Unity項目構(gòu)建自動化中最核心、最通用的幾個環(huán)節(jié)。2.1 核心需求拆解一個最小可用的Unity構(gòu)建機(jī)至少需要完成以下任務(wù)環(huán)境準(zhǔn)備確保構(gòu)建服務(wù)器或本地機(jī)器上安裝了正確版本的Unity Editor以及目標(biāo)平臺所需的SDK如Android SDK/NDK、iOS Xcode。獲取最新代碼從版本控制系統(tǒng)如Git拉取指定分支的最新代碼。執(zhí)行Unity構(gòu)建命令這是核心通過命令行調(diào)用Unity Editor以“批處理模式”執(zhí)行構(gòu)建生成最終的應(yīng)用程序包APK、IPA、EXE等。處理構(gòu)建結(jié)果將構(gòu)建產(chǎn)物可能包含多個文件復(fù)制到指定的歸檔目錄并可按需進(jìn)行重命名、版本號注入等操作。通知與日志構(gòu)建完成后無論成功與否都需要有明確的日志輸出并最好能通過某種方式如郵件、釘釘/飛書機(jī)器人通知相關(guān)人員。2.2 技術(shù)方案選型為什么選擇命令行 腳本市面上有成熟的CI/CD方案比如Jenkins、GitLab CI/CD、GitHub Actions、Azure DevOps等。它們功能強(qiáng)大有豐富的插件和可視化界面。但對于一個“簡單”的構(gòu)建機(jī)來說它們可能顯得過于重型學(xué)習(xí)和配置成本較高。我們的目標(biāo)是快速實現(xiàn)、易于理解和維護(hù)。因此我推薦的核心方案是Unity命令行接口 Shell/Python腳本。Unity命令行Unity Editor本身提供了強(qiáng)大的命令行參數(shù)允許我們在無圖形界面的情況下執(zhí)行構(gòu)建、批量處理資源等操作。這是實現(xiàn)自動化的基石。Shell/Batch腳本在Windows上可以用.bat或.ps1在macOS/Linux上可以用.sh。腳本負(fù)責(zé)串聯(lián)整個流程拉代碼、調(diào)用Unity、處理文件。它的優(yōu)勢是輕量、直接與操作系統(tǒng)結(jié)合緊密。Python腳本如果你需要更復(fù)雜的邏輯比如解析JSON配置文件、進(jìn)行HTTP請求發(fā)送通知、更精細(xì)的文件操作等Python是更佳選擇。它跨平臺庫豐富可讀性強(qiáng)。對于大多數(shù)中小項目一個精心編寫的Shell腳本配合Unity命令行就完全夠用了。我們將以這個組合為例進(jìn)行展開。選擇這個方案你不僅能快速搭建起來還能透徹理解自動化構(gòu)建的每一個步驟未來無論是遷移到更專業(yè)的CI平臺還是擴(kuò)展功能都會心中有數(shù)。3. 構(gòu)建環(huán)境準(zhǔn)備與Unity命令行基礎(chǔ)在編寫自動化腳本之前我們必須確保構(gòu)建環(huán)境是正確且可重復(fù)的。這是避免“構(gòu)建環(huán)境差異”導(dǎo)致問題的關(guān)鍵。3.1 安裝與定位Unity Editor構(gòu)建機(jī)上需要安裝Unity Hub和指定版本的Unity Editor。不建議直接使用安裝程序默認(rèn)路徑最好通過命令行能準(zhǔn)確定位到Unity可執(zhí)行文件。Windows通常路徑為C:\Program Files\Unity\Hub\Editor\Version\Editor\Unity.exemacOS通常路徑為/Applications/Unity/Hub/Editor/Version/Unity.app/Contents/MacOS/UnityLinux路徑類似/opt/unity/Editor/Version/Unity在腳本中我們應(yīng)該將Unity路徑定義為一個變量方便修改和移植。# 示例在Shell腳本中定義Unity路徑 (macOS/Linux) UNITY_PATH/Applications/Unity/Hub/Editor/2022.3.20f1/Unity.app/Contents/MacOS/Unity # 示例在Batch腳本中定義Unity路徑 (Windows) SET UNITY_PATHC:\Program Files\Unity\Hub\Editor\2022.3.20f1\Editor\Unity.exe注意構(gòu)建機(jī)使用的Unity版本必須與項目設(shè)置中指定的版本嚴(yán)格一致。否則可能會遇到API不兼容、資源格式錯誤等問題。建議在團(tuán)隊內(nèi)部明確項目使用的Unity LTS版本并在構(gòu)建機(jī)上固定安裝此版本。3.2 理解核心Unity命令行參數(shù)Unity命令行的魔力在于一系列參數(shù)。以下是構(gòu)建機(jī)最常用的幾個-batchmode這是最重要的參數(shù)。它讓Unity以批處理模式運(yùn)行不顯示圖形界面不彈出對話框執(zhí)行完畢后自動關(guān)閉。這是自動化構(gòu)建的前提。-quit在執(zhí)行完其他命令后退出Unity編輯器。通常與-batchmode聯(lián)用。-projectPath path指定要打開的Unity項目路徑。必須是絕對路徑。-executeMethod ClassName.MethodName指定一個在編輯器模式下執(zhí)行的靜態(tài)方法。這是我們構(gòu)建邏輯的入口點。-buildTarget target指定構(gòu)建目標(biāo)平臺例如Android,iOS,StandaloneWindows64,WebGL等。-logFile path將Unity的日志輸出到指定文件。對于排查構(gòu)建失敗原因至關(guān)重要。如果不指定默認(rèn)輸出到控制臺。一個最簡單的構(gòu)建命令看起來像這樣${UNITY_PATH} -batchmode -quit -projectPath /path/to/your/project -executeMethod BuildScript.PerformBuild -logFile build.log這條命令會以無界面模式打開指定項目執(zhí)行BuildScript類中的PerformBuild靜態(tài)方法然后將日志寫入build.log文件最后退出。3.3 目標(biāo)平臺SDK配置Android需要安裝JDK注意Unity版本對JDK版本有要求如2022.3通常需要JDK 11-17、Android SDK和NDK。環(huán)境變量JAVA_HOME,ANDROID_SDK_ROOT,ANDROID_NDK_HOME必須正確設(shè)置。Unity安裝時通常會捆綁安裝這些但構(gòu)建機(jī)上最好獨立安裝并確認(rèn)版本兼容性。iOS需要在macOS系統(tǒng)上安裝Xcode及命令行工具。構(gòu)建過程會調(diào)用xcodebuild。其他平臺如Windows、Linux、WebGL通常Unity自帶運(yùn)行時無需額外配置。實操心得建議將構(gòu)建環(huán)境包括Unity版本、SDK版本、環(huán)境變量配置通過Docker容器或虛擬機(jī)鏡像進(jìn)行固化。這樣可以在任何機(jī)器上快速復(fù)現(xiàn)完全一致的構(gòu)建環(huán)境是走向“持續(xù)集成”的重要一步。對于小型團(tuán)隊至少應(yīng)該有一份詳細(xì)的《構(gòu)建環(huán)境配置手冊》。4. 編寫核心構(gòu)建腳本C#編輯器腳本Unity命令行通過-executeMethod調(diào)用的方法需要寫在一個編輯器腳本中。這個腳本需要放在項目的Assets/Editor目錄下或其子目錄。4.1 構(gòu)建腳本基本結(jié)構(gòu)讓我們創(chuàng)建一個BuildScript.cs文件。using UnityEditor; using UnityEngine; using System.IO; using System.Linq; public static class BuildScript { // 這是一個可以被命令行調(diào)用的方法 public static void PerformBuild() { // 1. 獲取命令行參數(shù)可選 string[] args System.Environment.GetCommandLineArgs(); string buildTargetStr GetArgument(args, buildTarget); string outputPath GetArgument(args, outputPath); // 2. 設(shè)置構(gòu)建選項 BuildPlayerOptions buildOptions new BuildPlayerOptions(); // 2.1 設(shè)置需要構(gòu)建的場景 // 注意這里獲取的是在Build Settings窗口中勾選的場景這是最可靠的方式。 buildOptions.scenes EditorBuildSettings.scenes .Where(s s.enabled) .Select(s s.path) .ToArray(); if (buildOptions.scenes.Length 0) { Debug.LogError(No scenes added to Build Settings!); EditorApplication.Exit(1); // 非零退出碼表示失敗 return; } // 2.2 設(shè)置構(gòu)建目標(biāo) BuildTarget target BuildTarget.NoTarget; if (!System.Enum.TryParse(buildTargetStr, true, out target)) { // 如果命令行沒指定可以設(shè)置一個默認(rèn)值比如打Android包 target BuildTarget.Android; } buildOptions.target target; // 2.3 設(shè)置輸出路徑 if (string.IsNullOrEmpty(outputPath)) { // 生成一個帶時間戳的默認(rèn)路徑 string projectName PlayerSettings.productName.Replace( , _); string dateTime System.DateTime.Now.ToString(yyyyMMdd_HHmmss); outputPath Path.Combine(Builds, target.ToString(), ${projectName}_{dateTime}); } // 確保輸出目錄存在 Directory.CreateDirectory(Path.GetDirectoryName(outputPath)); buildOptions.locationPathName outputPath; // 2.4 設(shè)置其他選項 buildOptions.options BuildOptions.None; // 正式發(fā)布 // buildOptions.options BuildOptions.Development | BuildOptions.AllowDebugging; // 開發(fā)調(diào)試包 // 3. 執(zhí)行構(gòu)建 BuildReport report BuildPipeline.BuildPlayer(buildOptions); // 4. 處理構(gòu)建結(jié)果 if (report.summary.result BuildResult.Succeeded) { Debug.Log($Build succeeded! Output path: {outputPath}); Debug.Log($Build size: {report.summary.totalSize / (1024 * 1024):F2} MB); EditorApplication.Exit(0); // 退出碼0表示成功 } else { Debug.LogError($Build failed with {report.summary.totalErrors} error(s).); // 錯誤信息已經(jīng)在之前的日志中打印了 EditorApplication.Exit(1); } } // 一個簡單的輔助函數(shù)用于從命令行參數(shù)中提取值 // 例如-buildTarget Android -outputPath “C:\Builds” private static string GetArgument(string[] args, string name) { for (int i 0; i args.Length; i) { if (args[i] $-{name} i 1 args.Length) { return args[i 1]; } } return null; } }4.2 關(guān)鍵點解析與注意事項場景列表來源代碼中通過EditorBuildSettings.scenes獲取場景列表。這是最佳實踐。它直接讀取你在Unity編輯器菜單File - Build Settings中勾選的場景順序。這確保了自動化構(gòu)建和你在編輯器里手動構(gòu)建的內(nèi)容完全一致。永遠(yuǎn)不要在腳本里硬編碼場景路徑。輸出路徑管理腳本中包含了簡單的路徑生成邏輯。在實際使用中你可能希望從命令行參數(shù)-outputPath傳入或者根據(jù)公司規(guī)范生成固定的目錄結(jié)構(gòu)如Builds/Android/Prod/。構(gòu)建選項BuildOptions枚舉非常重要。BuildOptions.None用于發(fā)布正式包。BuildOptions.Development生成開發(fā)包包含調(diào)試符號允許連接Profiler和Debugger。BuildOptions.AllowDebugging允許腳本調(diào)試。BuildOptions.CompressWithLz4HC使用LZ4HC高壓縮率壓縮資源能有效減小包體。 你可以根據(jù)構(gòu)建目的測試/發(fā)布進(jìn)行組合。退出碼EditorApplication.Exit(0或1)是告訴調(diào)用腳本如Shell構(gòu)建成功與否的關(guān)鍵。0代表成功非0代表失敗。外層的Shell腳本可以根據(jù)這個退出碼決定后續(xù)操作如發(fā)送成功通知或失敗告警。踩坑記錄曾經(jīng)遇到過構(gòu)建腳本在本地運(yùn)行成功但在構(gòu)建機(jī)上失敗的情況。排查后發(fā)現(xiàn)是因為構(gòu)建機(jī)上的項目Build Settings里一個場景都沒勾選。因此腳本開頭對場景數(shù)量的檢查非常必要。另外確保Editor腳本中沒有使用任何僅在編輯器運(yùn)行時才存在的API如某些GUI調(diào)用因為在批處理模式下這些API可能行為異常。5. 外層驅(qū)動腳本串聯(lián)整個自動化流程有了核心的C#構(gòu)建腳本我們還需要一個外層的“驅(qū)動”腳本來組織整個流程。這個腳本可以用Shellbash/powershell或Python來寫。這里以Bash腳本為例因為它非常直觀。5.1 一個完整的Bash構(gòu)建腳本示例假設(shè)我們的項目在/home/ci/unity-project 我們要構(gòu)建Android版本。#!/bin/bash # 文件名build_android.sh # 嚴(yán)格模式遇到錯誤即停止 set -e echo Unity項目自動化構(gòu)建開始 echo 時間: $(date) # 1. 定義變量 PROJECT_PATH/home/ci/unity-project UNITY_PATH/Applications/Unity/Hub/Editor/2022.3.20f1/Unity.app/Contents/MacOS/Unity BUILD_TARGETAndroid # 構(gòu)建產(chǎn)物輸出到帶時間戳的目錄 OUTPUT_DIR${PROJECT_PATH}/Builds/Android/$(date %Y%m%d_%H%M%S) LOG_FILE${OUTPUT_DIR}/build.log echo 項目路徑: ${PROJECT_PATH} echo Unity路徑: ${UNITY_PATH} echo 構(gòu)建目標(biāo): ${BUILD_TARGET} echo 輸出目錄: ${OUTPUT_DIR} # 2. 創(chuàng)建輸出目錄 mkdir -p ${OUTPUT_DIR} # 3. 執(zhí)行Unity構(gòu)建命令 echo 開始執(zhí)行Unity構(gòu)建... ${UNITY_PATH} \ -batchmode \ -quit \ -projectPath ${PROJECT_PATH} \ -executeMethod BuildScript.PerformBuild \ -buildTarget ${BUILD_TARGET} \ -outputPath ${OUTPUT_DIR}/MyGame.apk \ -logFile ${LOG_FILE} \ -nographics # 對于無顯示服務(wù)器的環(huán)境如純命令行Linux可能需要此參數(shù) # 檢查Unity進(jìn)程退出碼 UNITY_EXIT_CODE$? echo Unity進(jìn)程退出碼: ${UNITY_EXIT_CODE} # 4. 檢查構(gòu)建結(jié)果 if [ ${UNITY_EXIT_CODE} -eq 0 ]; then echo ? 構(gòu)建成功 echo 構(gòu)建日志已保存至: ${LOG_FILE} echo APK文件位于: ${OUTPUT_DIR} # 5. 成功后的操作可選 # 例如復(fù)制APK到共享目錄、上傳到內(nèi)網(wǎng)測試平臺、發(fā)送成功通知等 # cp ${OUTPUT_DIR}/MyGame.apk /shared_drive/latest_test.apk # send_notification success Android構(gòu)建成功 else echo ? 構(gòu)建失敗退出碼: ${UNITY_EXIT_CODE} echo 構(gòu)建日志最后50行 tail -n 50 ${LOG_FILE} echo 日志結(jié)束 # 6. 失敗后的操作可選 # 例如發(fā)送失敗告警郵件/消息包含錯誤日志片段 # send_notification failure Android構(gòu)建失敗請查看日志: ${LOG_FILE} exit 1 # 整個腳本以失敗狀態(tài)退出 fi echo 構(gòu)建流程結(jié)束 5.2 腳本關(guān)鍵環(huán)節(jié)詳解set -e這是一個好習(xí)慣。它使得腳本中任何一條命令失敗返回非零狀態(tài)時整個腳本立即停止。這能防止錯誤被忽略導(dǎo)致后續(xù)操作在錯誤的狀態(tài)下進(jìn)行。變量定義將所有路徑、版本號等配置抽成變量放在腳本開頭便于管理和修改。目錄創(chuàng)建在調(diào)用Unity之前先創(chuàng)建好輸出目錄。避免Unity因路徑不存在而報錯。Unity命令行參數(shù)-nographics在Linux服務(wù)器等沒有圖形界面的環(huán)境下是必須的否則Unity可能會啟動失敗。我們將-outputPath參數(shù)傳遞給了C#腳本。C#腳本中的GetArgument函數(shù)會解析它。-logFile指定了日志路徑。一定要保存日志這是事后排查問題的唯一依據(jù)。退出碼檢查$?獲取上一條命令Unity進(jìn)程的退出碼。我們根據(jù)C#腳本中EditorApplication.Exit()傳入的值來判斷構(gòu)建成功與否。日志處理構(gòu)建失敗時腳本使用tail -n 50打印日志的最后50行。通常錯誤信息就在末尾。你也可以將整個日志文件作為附件發(fā)送。5.3 擴(kuò)展集成版本控制Git一個完整的構(gòu)建機(jī)通常需要從代碼倉庫拉取最新代碼。我們可以在執(zhí)行Unity構(gòu)建前加入Git操作。# 在Bash腳本中Unity構(gòu)建命令之前加入 BRANCHdevelop # 或通過參數(shù)傳入 echo 切換到分支: ${BRANCH} cd ${PROJECT_PATH} git fetch origin git checkout ${BRANCH} git pull origin ${BRANCH} echo 最新提交: $(git log -1 --oneline) # 可選獲取本次構(gòu)建的提交哈希用于標(biāo)記版本 COMMIT_HASH$(git rev-parse --short HEAD) # 可以將這個哈希值通過某種方式如寫入一個文本文件包含到構(gòu)建產(chǎn)物中 echo ${COMMIT_HASH} ${OUTPUT_DIR}/build_info.txt注意事項確保構(gòu)建機(jī)上的Git用戶有倉庫的拉取權(quán)限并且配置好了SSH密鑰或賬號密碼。對于需要認(rèn)證的私有倉庫這是常見的配置點。6. 高級功能與定制化基礎(chǔ)構(gòu)建流程跑通后可以根據(jù)項目需求添加更多功能。6.1 版本號自動遞增在打包時自動遞增版本號如1.0.123中的123是常見需求。這可以通過修改PlayerSettings來實現(xiàn)。在BuildScript.cs中可以在構(gòu)建前添加如下代碼[MenuItem(Build/Increment Version)] public static void IncrementVersionAndBuild() { // 讀取當(dāng)前版本號例如 1.0.123 string currentVersion PlayerSettings.bundleVersion; // 簡單的遞增邏輯假設(shè)版本格式為 Major.Minor.Build string[] parts currentVersion.Split(.); if (parts.Length 3 int.TryParse(parts[2], out int buildNumber)) { buildNumber; string newVersion ${parts[0]}.{parts[1]}.{buildNumber}; PlayerSettings.bundleVersion newVersion; PlayerSettings.Android.bundleVersionCode buildNumber; // Android版本碼也遞增 // iOS的CFBundleVersion也需要設(shè)置但更復(fù)雜涉及Info.plist Debug.Log($Version updated to: {newVersion}); // 保存項目設(shè)置 AssetDatabase.SaveAssets(); } else { Debug.LogWarning($Could not parse version: {currentVersion}. Using default.); } // 然后調(diào)用構(gòu)建方法 PerformBuild(); }你可以修改這個函數(shù)或者從外部文件如version.txt讀取和寫入版本號實現(xiàn)更復(fù)雜的版本管理策略。6.2 多平臺構(gòu)建與參數(shù)化我們的腳本目前寫死了構(gòu)建Android。我們可以改造它使其能通過命令行參數(shù)構(gòu)建任意平臺。修改Bash腳本從命令行接收參數(shù)#!/bin/bash # build.sh # 用法./build.sh -p Android -b develop while getopts p:b: opt; do case $opt in p) BUILD_TARGET$OPTARG ;; b) GIT_BRANCH$OPTARG ;; ?) echo Usage: $0 -p Platform -b Branch; exit 1 ;; esac done # 設(shè)置默認(rèn)值 BUILD_TARGET${BUILD_TARGET:-Android} GIT_BRANCH${GIT_BRANCH:-main} # ... 后續(xù)流程使用這些變量然后在調(diào)用Unity時將-buildTarget ${BUILD_TARGET}參數(shù)傳入即可。6.3 構(gòu)建后處理自動上傳與通知構(gòu)建成功后的APK/IPA需要分發(fā)給測試人員?？梢约珊唵蔚奈募蟼骱拖⑼ㄖ?。上傳到內(nèi)網(wǎng)服務(wù)器/FTP使用scp,rsync或curl命令。# 示例使用scp上傳到測試服務(wù)器 REMOTE_USERtester REMOTE_HOSTtest-server.com REMOTE_PATH/var/www/html/downloads/latest.apk scp ${OUTPUT_DIR}/MyGame.apk ${REMOTE_USER}${REMOTE_HOST}:${REMOTE_PATH}發(fā)送通知到釘釘/飛書/企業(yè)微信這些平臺都提供了Webhook接口。可以使用curl發(fā)送一個HTTP POST請求。# 示例發(fā)送釘釘機(jī)器人通知 WEBHOOK_URLhttps://oapi.dingtalk.com/robot/send?access_tokenYOUR_TOKEN JSON_DATA$(cat EOF { msgtype: text, text: { content: Unity構(gòu)建通知項目${PROJECT_NAME} ${BUILD_TARGET}平臺構(gòu)建${BUILD_RESULT}\n版本${NEW_VERSION}\n提交${COMMIT_HASH}\n日志${LOG_URL} } } EOF ) curl -H Content-Type: application/json -X POST -d ${JSON_DATA} ${WEBHOOK_URL}將${BUILD_RESULT}成功/失敗、版本號、提交哈希等信息填入消息內(nèi)容。7. 常見問題排查與實戰(zhàn)技巧即使腳本寫得再完善在實際運(yùn)行中也會遇到各種問題。這里記錄一些典型的“坑”和解決方法。7.1 Unity構(gòu)建失敗常見原因速查表現(xiàn)象/錯誤信息可能原因排查步驟與解決方案UnityException: BuildPipeline.BuildPlayer:...后跟模糊錯誤項目配置問題場景問題腳本編譯錯誤。1. 查看詳細(xì)日志這是最重要的。檢查-logFile指定的文件搜索error或Exception。2. 檢查場景確認(rèn)Build Settings中至少有一個場景被勾選且路徑有效。3. 在編輯器中試構(gòu)建先在Unity編輯器里手動構(gòu)建一次看是否有錯誤提示。構(gòu)建成功但APK安裝后閃退缺少依賴庫如Android ARM64支持腳本存在運(yùn)行時錯誤資源加載失敗。1. 檢查Player Settings確保目標(biāo)架構(gòu)如ARMv7, ARM64已勾選。2. 打開發(fā)布包使用BuildOptions.Development和BuildOptions.AllowDebugging選項構(gòu)建一個開發(fā)包通過ADB或Xcode查看運(yùn)行時日志。3. 檢查資源確認(rèn)所有動態(tài)加載的資源如AssetBundle路徑正確且已打包。批處理模式卡住不退出腳本中有彈出窗口如EditorUtility.DisplayDialog或存在無限循環(huán)。1. 避免交互確保在Editor腳本中批處理模式下絕不使用任何會彈出對話框的API。2. 超時處理在外層Shell腳本中設(shè)置超時例如使用timeout命令timeout 1800s unity_command設(shè)置30分鐘超時。CommandNotFoundException: unityUnity可執(zhí)行文件路徑錯誤或沒有執(zhí)行權(quán)限。1. 檢查路徑使用ls -la “${UNITY_PATH}”確認(rèn)文件存在。2. 賦予執(zhí)行權(quán)限chmod x “${UNITY_PATH}”(Unix系統(tǒng))。3. 使用絕對路徑。Android構(gòu)建失敗提示JDK、SDK找不到環(huán)境變量未正確設(shè)置或Unity版本與JDK版本不兼容。1. 確認(rèn)環(huán)境變量在構(gòu)建機(jī)上執(zhí)行echo $JAVA_HOME,echo $ANDROID_SDK_ROOT。2. 指定路徑可以在Unity安裝目錄下的Editor/Data/PlaybackEngines/AndroidPlayer找到SDK,NDK,JDK目錄并在Unity命令行中通過-androidSdkPath,-androidNdkPath,-androidJavaSdkPath參數(shù)指定。這是最可靠的方式。構(gòu)建產(chǎn)物巨大未啟用壓縮包含了不必要的資源如高清紋理所有Mipmap。1. 檢查壓縮設(shè)置在BuildPlayerOptions.options中加入BuildOptions.CompressWithLz4HC。2. 檢查Player Settings在Player Settings - Other Settings中可以關(guān)閉Prebake Collision Meshes如果不需服務(wù)器物理調(diào)整Strip Engine Code等。3. 使用Asset Bundle將資源分離動態(tài)下載。7.2 實戰(zhàn)心得與技巧日志是你的生命線一定要保存并定期查看構(gòu)建日志。建議將每次構(gòu)建的日志文件都?xì)w檔文件名包含時間戳和構(gòu)建結(jié)果成功/失敗?？梢允褂胻ee命令同時輸出到屏幕和文件unity_command 21 | tee “${LOG_FILE}”。從小處著手逐步迭代不要試圖一次性實現(xiàn)一個功能完備的構(gòu)建機(jī)。先實現(xiàn)最基本的命令行構(gòu)建成功。然后加上Git拉取代碼。再加上版本號管理。最后處理通知和上傳。每完成一步都進(jìn)行測試。使用版本控制管理構(gòu)建腳本你的構(gòu)建腳本本身也應(yīng)該放入Git倉庫。這樣構(gòu)建邏輯的變更可以被追蹤和回滾。準(zhǔn)備一個“干凈”的構(gòu)建代理如果條件允許使用一臺獨立的、只安裝必要軟件的機(jī)器或Docker容器作為構(gòu)建機(jī)。避免因本地開發(fā)環(huán)境安裝的各種插件、工具影響構(gòu)建的穩(wěn)定性和可重復(fù)性。處理Unity許可證無圖形界面的服務(wù)器上運(yùn)行Unity需要激活許可證?？梢允褂?manualLicenseFile參數(shù)指定一個已有的許可證文件或者使用-batchmode -quit -logFile -createManualActivationFile生成許可證請求文件然后在有圖形界面的機(jī)器上激活后將許可證文件拷貝回來。對于團(tuán)隊考慮使用浮動許可證服務(wù)器。性能考量Unity項目首次構(gòu)建會很慢因為要導(dǎo)入和預(yù)處理所有資源。可以利用Unity的BuildOptions.AcceptExternalModificationsToPlayer選項進(jìn)行增量構(gòu)建但需謹(jǐn)慎有時會引入奇怪問題。更穩(wěn)妥的方式是定期清理Library文件夾進(jìn)行全量構(gòu)建以保證一致性。搭建一個簡單的Unity構(gòu)建機(jī)核心在于理解“自動化”的本質(zhì)用確定的腳本代替不確定的人工操作。通過本文拆解的步驟——從環(huán)境準(zhǔn)備、命令行參數(shù)理解到核心C#構(gòu)建腳本、外層驅(qū)動腳本的編寫再到高級功能的擴(kuò)展和問題排查——你應(yīng)該已經(jīng)掌握了搭建一個滿足基本需求的自動化構(gòu)建流程的能力。這個流程將成為你項目研發(fā)的基礎(chǔ)設(shè)施它的穩(wěn)定運(yùn)行意味著更快的迭代速度、更少的低級錯誤和更高的團(tuán)隊協(xié)作效率。