做 Unity 開發的朋友應該都有過這樣的經歷在編輯器里運行得好好的 Demo想拿到真機上跑一下結果被 APK 打包卡住了。要么是點擊 Build 之后報一堆 SDK / JDK 錯誤要么是打包流程走到一半就失敗要么是好不容易打出來的 APK 安裝不到手機上。網上關于 Unity 打包 APK 的資料很零散很多帖子只講了“點一下 Build”沒有說環境怎么配、Player Settings 為什么要這樣設置、腳本打包怎么自動化。本文把這些內容整合成一套完整的實戰筆記從環境準備、Unity 面板配置、GUI 打包、USB 安裝到命令行自動化打包都會講到并附上常見報錯排查表。新手朋友可以照著一步步操作已經在項目里的開發者也可以直接跳到自己需要的章節。注意一點本文只講 Android 原生 APK 的打包鏈路。如果你想做的是 HarmonyOS、微信小游戲、抖音小游戲那是另一套配置流程不在下面的討論范圍內。1. Unity 打包 APK 的底層邏輯1.1 為什么打包 APK 不是“點一下 Build”這么簡單Unity 編輯器本身只是一個開發工具它不會幫你完成 Android 編譯。點擊 Build 后Unity 會調用本地的 Android SDK、NDK、JDK 來一起完成把 C# 代碼編譯成 IL再根據打包設置轉成 Mono 或 IL2CPP 可執行文件把場景、材質、貼圖、音頻、預制體、Shader 等資源按規則序列化并壓縮生成 Android 工程文件再用 Gradle 編譯資源、生成 Dex、打包資源最后用 jarsigner / apksigner 完成簽名生成可安裝的 APK。所以打包 APK 的本質是一個“Unity Android 工具鏈聯動”的過程。哪個環節缺失最終都會在 Build 窗口里反饋出來。1.2 快速打包的核心是什么“快速”并不是指讓 Unity 把構建時間從 10 分鐘壓縮到 1 分鐘而是指“通過規范化的環境配置和重復步驟自動化減少中途踩坑和反復檢查的時間”。構建速度很大程度上取決于是否開啟增量構建使用 Mono 還是 IL2CPP場景和資源是否精簡是否配置了 SDK / NDK 的緩存路徑是否在命令行中跳過不必要的導入和初始化。這篇文章不會教你“黑科技加速”而是把影響打包成功率的環節都梳理清楚讓你在第一次構建時就能一次通過后續再通過腳本一鍵完成整體效率自然就上去了。1.3 適合什么類型的項目本文的內容適用于Unity 2020 LTS、2021 LTS、2022 LTS 及更新版本純 Android 原生 APK 打包真機安裝測試需要接入 SDK 或自動化打包的團隊項目。如果你的項目已經使用了 Jenkins、GitLab CI 等自動化平臺本文的 BuildScript.cs 也可以直接作為構建入口。2. 打包前環境準備在打開 Build Settings 之前先確保本機環境基本滿足條件。很多人一上來就點 Build結果報錯信息全是英文最后發現是 JDK 沒裝這種情況很常見。2.1 需要準備哪些組件組件作用是否必裝Unity 編輯器項目開發和打包入口必裝Android Build Support 模塊Unity 導出/編譯 Android 工程的能力必裝Android SDK提供 adb、aapt、zipalign 等工具必裝Android NDKIL2CPP 交叉編譯時使用使用 IL2CPP 時必裝OpenJDK編譯 Java/Kotlin、生成簽名必裝USB 驅動連接 Android 手機時使用使用真機調試時推薦這里最重要的不是“自己單獨去官網下載”而是通過 Unity Hub 安裝 Android Build Support。如果你安裝了多個 Unity 版本盡量讓每個版本的 Android Build Support 模塊保持完整。2.2 使用 Unity Hub 安裝模塊打開 Unity Hub進入“安裝”標簽頁。找到當前項目使用的 Unity 版本點擊右側齒輪圖標選擇“添加模塊”。在模塊列表中勾選Android Build SupportAndroid SDK NDK ToolsOpenJDK。勾選后點擊“安裝”Unity Hub 會自動把 SDK、NDK、OpenJDK 下載到你本機的默認目錄。這是比較省心的方式也是新手朋友最推薦的方式。2.3 檢查本機環境是否就緒安裝完成后打開 Unity 項目進入菜單Edit - Preferences - External Tools在 Android 一欄中可以看到SDK 路徑NDK 路徑JDK 路徑。如果你是通過 Unity Hub 安裝的模塊這三個路徑通常會自動填入。如果路徑是空的或者帶黃色警告圖標需要手動指定。SDK 最終路徑一般是C:\Program Files\Unity\Hub\Editor\版本號\Editor\Data\PlaybackEngines\AndroidPlayer\SDKJDK 路徑類似C:\Program Files\Unity\Hub\Editor\版本號\Editor\Data\PlaybackEngines\AndroidPlayer\OpenJDK不同版本和系統盤的安裝路徑可能不同以你本機實際路徑為準。如果你是手動下載的 SDK需要注意 SDK 平臺和 Build-Tools 的版本是否被 Unity 支持。遇到版本不匹配時優先考慮用 Unity Hub 重新安裝模塊而不是自己去下載一堆 SDK Tools。3. Unity Android 打包關鍵配置拆解3.1 進入 Player Settings打開菜單File - Build Settings點擊左下角的“Android”再點擊“Player Settings…”右側的 Inspector 會變成 Android 相關的設置面板。這些設置項很多但真正影響首次打包成功率和安裝成功率的主要是下面幾類。3.2 包名、版本號與應用標識在 Other Settings 中Package NameAndroid 應用唯一標識一般使用反向域名例如com.example.myunitygameVersion給玩家看到的版本號例如1.0.0Bundle Version Code內部版本號必須是整數每次上傳商店前需要遞增例如1、2、3。Package Name 不要隨便起。如果你之前已經安裝過相同包名的應用新安裝包簽名一致才能覆蓋安裝。建議從項目開始時就想好固定包名后續不要再改。3.3 腳本后端Mono 還是 IL2CPP在 Other Settings 中找到 Scripting Backend可選值Mono編譯快打包體積略大兼容性也好IL2CPP構建慢但運行時性能更好APK 體積更小并且更適合商用項目提交商店。對于“快速打包到手機”的需求第一次測試建議先用 Mono。等到正式發布或需要接入微信、抖音等平臺時再切到 IL2CPP。切換 IL2CPP 后Unity 會使用 NDK 進行 C 編譯首次構建時間會比 Mono 長很多這是正常的。3.4 紋理壓縮格式在 Other Settings 中找到 Texture Compression常見選項Dont override使用貼圖原始格式ASTC兼容 Android 6.0 以上主流設備ETC2兼容性較好但部分老設備不支持。在新項目中建議選擇 ASTC這是當前 Android 設備的默認趨勢。如果你的項目要兼容很老的機型再根據測試結果調整。3.5 橫豎屏和應用圖標在 Resolution and Presentation 中Default Orientation 選擇 Portrait、LandscapeLeft / LandscapeRight 等手機應用的圖標在 Icon 面板中設置不設置的話會使用 Unity 默認圖標。在真機測試前建議把 Target Minimum API Level 設置為與你手機 Android 版本接近或更低的值。如果設置過高低版本手機會無法安裝。3.6 Android 簽名配置Android 要求所有 APK 必須簽名后才能安裝。在 Player Settings - Publishing Settings 中勾選 Create a new keystore可以生成一個本地密鑰庫也可以直接勾選 Use existing keystore導入已有的 keystore。對于個人開發測試可以勾選 “Custom Keystore”然后在 Unity 里創建新密鑰庫。Unity 會自動填寫 keystore 中的 alias、password 等信息。如果你不想在編輯器中操作也可以使用 JDK 自帶的 keytool 命令生成keytool -genkeypair -v -keystore release.keystore -alias mygame -keyalg RSA -keysize 2048 -validity 10000執行過程中會要求輸入密碼、姓名、組織等信息。生成后的release.keystore文件要妥善保存不要提交到公開倉庫。以后每次打包這個文件必須保留否則用戶無法覆蓋安裝舊版本。4. 手把手Unity 快速打包 APK 到手機接下來是一個完整的 GUI 打包流程。假設你的項目已經能在 Unity 編輯器里運行場景也已經保存。4.1 把場景添加到 Build Settings打開File - Build Settings點擊“Add Open Scenes”把當前打開的場景加到列表。請檢查場景是否已經勾選啟動場景是否為列表中的第一個場景如果后續要打包多個場景確保跳轉關系正確。很多人第一次打包出來的 APK 打開后黑屏就是因為場景列表為空或者沒有把場景添加進去。4.2 選擇 Android 平臺在 Build Settings 左側平臺列表中點擊“Android”然后點擊右下角“Switch Platform”。切換到 Android 平臺后Unity 會重新導入部分資源耗時取決于項目大小。此時左上角會出現一個轉圈進度條耐心等它完成。切換完成后Build 按鈕變成可點擊狀態。4.3 設置公司名和產品名打開菜單Edit - Project Settings - Player在 Company Name 和 Product Name 中填寫你的項目信息。Product Name 會顯示在手機桌面上的應用名稱Company Name 會參與默認命名空間和包名的生成。4.4 執行 Build回到 Build Settings 窗口點擊“Build”按鈕選擇一個輸出目錄輸入 APK 文件名例如MyGame.apk。Unity 會開始執行打包底部狀態欄會顯示構建進度。第一次構建通常需要較長的時間因為要生成 Android 工程、編譯資源、做代碼轉換。4.5 將 APK 安裝到手機打包成功后會生成一個 APK 文件。接下來用 USB 連接手機在手機上打開“開發者選項”開啟“USB 調試”和“USB 安裝”。然后將 APK 傳到手機或者使用 adb 命令安裝。先確認 adb 路徑。如果你通過 Unity Hub 安裝了 SDKadb 一般在C:\Program Files\Unity\Hub\Editor\版本號\Editor\Data\PlaybackEngines\AndroidPlayer\SDK\platform-tools\adb.exe在命令行中執行adb devices手機首次連接時屏幕會彈出“允許 USB 調試”的提示點擊允許。確認設備列表中出現你的設備后再執行安裝adb install -r MyGame.apk-r表示如果已經安裝過相同包名則覆蓋安裝。安裝成功后在手機桌面找到應用圖標點擊即可運行。5. 使用命令行與編輯器腳本實現一鍵打包每次打開 Unity 編輯器然后手動點 Build對于個人項目還能接受。到了項目后期頻繁出包時這套流程非常浪費時間。更推薦的做法是寫一個編輯器腳本把打包邏輯固化下來再通過命令行一鍵執行。5.1 為什么要用腳本打包腳本打包的好處不需要打開完整編輯器界面適合在服務器或者 CI 環境執行可以保證團隊中每個人都使用同一套打包參數可以自動切換平臺、自動生成版本號、自動輸出到固定目錄可以配合 Jenkins、GitLab CI 做每日構建。下面給出一個最簡可用版本可以作為你項目里的打包入口。5.2 創建 BuildScript.cs在項目的Assets/Editor目錄下創建文件BuildScript.cs。如果Assets下沒有Editor文件夾可以右鍵新建。// 文件路徑Assets/Editor/BuildScript.cs using System.Collections.Generic; using UnityEditor; using UnityEditor.Build.Reporting; using UnityEngine; public static class BuildScript { public static void BuildAndroid() { // 切換到 Android 平臺 EditorUserBuildSettings.SwitchActiveBuildTarget( BuildTargetGroup.Android, BuildTarget.Android ); // 組裝構建選項 BuildPlayerOptions buildPlayerOptions new BuildPlayerOptions(); buildPlayerOptions.scenes GetEnabledScenes(); buildPlayerOptions.locationPathName GetOutputPath(); buildPlayerOptions.target BuildTarget.Android; buildPlayerOptions.options BuildOptions.None; // 執行構建 BuildReport report BuildPipeline.BuildPlayer(buildPlayerOptions); BuildSummary summary report.summary; if (summary.result BuildResult.Succeeded) { Debug.Log(Build Succeeded! Output: summary.outputPath); Debug.Log(Build Size: summary.totalSize bytes); } else if (summary.result BuildResult.Failed) { Debug.LogError(Build Failed!); // 命令行模式下失敗時退出并返回非 0 錯誤碼 EditorApplication.Exit(1); } } private static string[] GetEnabledScenes() { Liststring scenePaths new Liststring(); foreach (EditorBuildSettingsScene scene in EditorBuildSettings.scenes) { if (scene null || !scene.enabled) { continue; } scenePaths.Add(scene.path); } return scenePaths.ToArray(); } private static string GetOutputPath() { string outputDirectory Build/Android; if (!System.IO.Directory.Exists(outputDirectory)) { System.IO.Directory.CreateDirectory(outputDirectory); } string apkName Application.productName.Replace( , _) _ PlayerSettings.bundleVersion .apk; return System.IO.Path.Combine(outputDirectory, apkName); } }這段腳本做了三件事使用SwitchActiveBuildTarget切換到 Android 平臺讀取EditorBuildSettings.scenes中啟用狀態的場景作為打包場景列表調用BuildPipeline.BuildPlayer構建 APK輸出到Build/Android目錄。腳本中的GetEnabledScenes和GetOutputPath都是可復用的輔助方法。以后想改輸出目錄、改 APK 文件名只需要改這兩個方法。5.3 用命令行調用打包保存腳本后不需要打開 Unity 編輯器。打開命令行工具Windows 下打開 CMD 或 PowerShell執行以下命令C:\Program Files\Unity\Hub\Editor\2021.3.16f1\Editor\Unity.exe -batchmode -quit \ -projectPath D:\MyUnityProject \ -executeMethod BuildScript.BuildAndroid \ -logFile build_android.log注意這里2021.3.16f1只是示例版本號請替換為你本機實際安裝的 Unity 版本projectPath指向你的 Unity 項目根目錄executeMethod必須寫完整包括類名和方法名-quit表示構建結束后自動退出 Unity-batchmode表示在無窗口模式下運行-logFile可以把日志輸出到文件中方便排查問題。執行過程中命令行窗口會一直等待直到打包完成。如果構建成功在Build/Android目錄下會生成 APK 文件。5.4 命令行打包進階批量版本號如果需要在不同分支打不同版本可以讓腳本讀取環境變量或者命令行參數。例如在BuildScript.cs中增加一個BuildAndroidWithVersion方法public static void BuildAndroidWithVersion() { string version System.Environment.GetEnvironmentVariable(UNITY_BUILD_VERSION); if (!string.IsNullOrEmpty(version)) { PlayerSettings.bundleVersion version; } BuildAndroid(); }然后在命令行中設置環境變量set UNITY_BUILD_VERSION1.2.0或者使用 PowerShell$env:UNITY_BUILD_VERSION1.2.0這樣可以在不修改代碼的情況下動態指定版本號便于自動化發布。5.5 如何驗證腳本是否生效第一次使用腳本打包后打開build_android.log文件搜索關鍵字Build Succeeded說明打包成功Build Failed說明失敗需要往上翻日志查看具體報錯如果出現Invalid executeMethod說明類型名或者方法名寫錯了。建議在項目里的Assets/Editor目錄放一個BuildScript.cs然后在命令行模式里反復驗證確認腳本穩定后再接入 CI。6. 常見問題與排查思路打包 APK 的過程會暴露各種環境問題。下面整理了一份高頻問題清單適合直接對照排查。問題現象常見原因排查思路點擊 Build 后提示找不到 SDKUnity 無法定位 Android SDK檢查 Preferences - External Tools 中的 SDK 路徑重新安裝 Android Build Support提示找不到 NDK使用 IL2CPP 但沒有安裝 NDK在 Unity Hub 中添加 NDK 模塊或手動指定 NDK 路徑提示找不到 JDK沒有安裝 OpenJDK安裝 Unity 自帶的 OpenJDK或在 Preferences 中指定 JDK 路徑構建到一半報 Gradle 相關錯誤Android Gradle 下載失敗或版本不匹配檢查網絡嘗試重新構建可通過腳本固定 Gradle 版本提示包名不合法Package Name 含中文或特殊符號改為com.xxx.xxx形式只能包含字母、數字、點、下劃線安裝到手機時提示“應用未安裝”簽名不一致、手機版本低于 minSdk、APK 損壞卸載舊應用再安裝檢查 minSdk重新打包安裝后打開黑屏場景未添加到 Build Settings在 File - Build Settings 中添加場景并啟用IL2CPP 構建非常慢首次構建需要生成 C 工程并編譯后續增量構建會變快或開發階段先用 Mono輸出 APK 體積極大紋理格式未壓、包含大量 Debug 日志開啟資源壓縮切換 IL2CPP移除無用資源6.1 最常見的 Gradle 報錯很多 Unity 版本默認使用 Gradle 構建 Android 工程。在首次構建時Unity 會嘗試下載 Gradle 依賴。如果網絡不穩定會出現類似A problem occurred configuring root project unityProject. Could not resolve all artifacts for configuration :classpath.解決方案檢查網絡連接重啟 Unity 并重新構建如果公司或內網有 Maven 鏡像可以在Assets/Plugins/Android/mainTemplate.gradle中替換倉庫地址使用 Unity Hub 固定同一版本避免版本抖動。這里不建議直接手動改 Gradle 全局緩存優先通過 Unity 的依賴配置解決。6.2 真機安裝失敗怎么辦如果打包成功但安裝失敗按以下順序排查手機是否開啟了“允許安裝未知來源”手機是否開啟了“USB 調試”是否已經安裝了相同包名但簽名不一致的舊應用如有則先卸載APK 是否解析失敗可以通過重新打包解決手機 Android 版本是否低于 APK 的 minSdk。建議把手機系統版本、Unity 版本、SDK 版本記下來這樣在社區提問時也能更快定位問題。7. 最佳實踐與工程建議7.1 盡早固化打包腳本項目剛開始時Create 幾個簡單場景后就應該先做一次完整的 Android 打包。不要等整個項目變復雜后再去排查環境問題。第一次接觸 Unity Android 開發時先把最小場景打包、安裝到手機這樣后面每加一個功能都能快速驗證。建議在項目初始化時就把Assets/Editor/BuildScript.cs建好并把輸出目錄固定到項目外或者Build/Android目錄下。打包產物不要提交到 Git 倉庫否則倉庫體積會迅速膨脹。7.2 統一開發環境版本Unity 項目中經常出現“本地能跑CI 上失敗”的問題。原因往往就是本地和 CI 的 Unity 版本、Android SDK、NDK、JDK 版本不一致。建議團隊在項目根目錄存放ProjectSettings/ProjectVersion.txt里面記錄了 Unity 版本。運行時使用相同版本的 Unity Hub 命令行模式執行構建腳本。7.3 簽名文件的安全管理keystore 文件包含證書和私鑰泄露后別人可以偽造你的應用簽名進行惡意版本分發。建議簽名文件和密碼不要提交到 Git在不同電腦上構建時從安全的密碼管理工具中獲取發布到應用商店的簽名文件如果丟失將無法以原包名更新應用務必多重備份開發階段和發布階段可以使用不同簽名但都要保持穩定。7.4 構建日志與版本號每次打包生成 APK 后可以通過 APK 文件名體現版本信息。例如MyGame_1.0.0.apk MyGame_1.0.0_20250410.apk MyGame_1.0.1_20250410.apk如果使用腳本構建文件名由Application.productName和PlayerSettings.bundleVersion拼接而成。這樣每次出包后都能直接根據文件名判斷版本。同時建議在構建腳本中輸出summary.outputPath和summary.totalSize到日志方便后續追蹤 APK 大小變化。7.5 開發階段用 Mono發布階段用 IL2CPP開發階段快速做真機驗證時優先使用 Mono構建速度快很多。等到準備提交應用商店或者性能優化時再切換到 IL2CPP。切換 IL2CPP 后建議多做一次全量構建因為首次需要生成 C 工程并編譯耗時會比較久。如果項目使用了 Lua 或原生插件也需要在 IL2CPP 模式下額外測試。7.6 真機測試前做這幾件事不要等到項目全部完成后再拿到真機上跑。以下幾點是實踐中比較值得注意的在手機上開啟“保持屏幕喚醒”保持 USB 線質量穩定優先使用原裝線每次打包前先清理手機里舊版本使用 adb 的logcat查看運行日志錯誤信息比彈窗更直接如果按鈕點擊無響應優先檢查 UI 的 EventSystem 是否存在。例如查看 Unity 應用日志adb logcat -s Unity這條命令會過濾出 Unity 輸出的日志包括Debug.Log、異常堆棧等。真機上報錯時往往靠 logcat 定位。7.7 善用增量構建Unity 的增量構建可以減少重復編譯時間。在日常開發中盡可能不要頻繁刪除Library目錄不要在構建過程中強制清理所有緩存使用同一個輸出目錄和同一個項目目錄。命令行模式下每次執行-quit會退出編輯器但Library目錄中的緩存仍然保留。下次構建時 Unity 會復用這些緩存構建速度會明顯加快。8. 最后的一些建議Unity 打包 APK 到手機本身并不復雜關鍵在于環境干凈、配置規范、流程可重復。把上面提到的環境檢查和打包腳本都準備好后后面每次出包只需一條命令省下來的時間可以用在實際開發和聯調上。在你的第一個真機項目里可以把目標定得小一點新建一個只有一個 Cube 的場景完成從環境配置到 APK 上手的全流程。把這條流程走通以后再去研究資源壓縮、IL2CPP、SDK 接入、自動化發布會順利很多。如果本文對你有幫助可以先收藏備用后續打包時遇到問題隨時對照排查。