1. 項(xiàng)目概述Unity打包Android失敗一個(gè)老生常談的“玄學(xué)”問(wèn)題干了這么多年Unity開(kāi)發(fā)要說(shuō)最讓人頭疼、最消耗開(kāi)發(fā)者耐心的環(huán)節(jié)打包Android APK絕對(duì)能排進(jìn)前三。尤其是當(dāng)你滿懷期待地點(diǎn)下“Build”按鈕結(jié)果Unity Editor給你彈出一堆紅字或者干脆卡死在某個(gè)進(jìn)度條時(shí)那種感覺(jué)真是五味雜陳。這不僅僅是新手才會(huì)遇到的坎即便是經(jīng)驗(yàn)豐富的老手在更換開(kāi)發(fā)環(huán)境、升級(jí)Unity版本或者引入新的第三方SDK后也常常會(huì)一頭栽進(jìn)這個(gè)“打包失敗”的大坑里。今天我就結(jié)合自己踩過(guò)的無(wú)數(shù)個(gè)坑來(lái)系統(tǒng)性地拆解一下Unity打包Android失敗這個(gè)問(wèn)題的方方面面。這不僅僅是一個(gè)技術(shù)問(wèn)題更是一個(gè)涉及環(huán)境配置、版本兼容、路徑管理、依賴沖突的綜合“系統(tǒng)工程”。我們的目標(biāo)很明確不僅要解決眼前的問(wèn)題更要建立起一套排查和預(yù)防的通用思路讓你下次再遇到時(shí)能快速定位從容應(yīng)對(duì)。2. 核心問(wèn)題根源與排查總綱打包失敗的錯(cuò)誤信息千奇百怪但追根溯源絕大多數(shù)問(wèn)題都逃不出以下幾個(gè)核心領(lǐng)域。理解了這個(gè)框架你就掌握了解決問(wèn)題的“地圖”。2.1 環(huán)境配置地基不穩(wěn)地動(dòng)山搖這是最常見(jiàn)也最基礎(chǔ)的問(wèn)題層。Unity打包Android本質(zhì)上是在你的電腦上調(diào)用Android的構(gòu)建工具鏈主要是Gradle或舊的ADT現(xiàn)在基本是Gradle來(lái)編譯代碼、打包資源。因此你的本地環(huán)境必須包含完整的Android SDK、Java JDK并且Unity要能正確找到它們。1. JDK (Java Development Kit)Unity需要JDK來(lái)編譯Android相關(guān)的Java代碼比如Plugins/Android下的jar/aar文件或者Unity自己生成的Java橋接代碼。版本不匹配是頭號(hào)殺手。常見(jiàn)坑點(diǎn)安裝了多個(gè)JDK版本環(huán)境變量JAVA_HOME指向了錯(cuò)誤的版本比如指向了JRE而不是JDK或者Unity Preferences里設(shè)置的JDK路徑無(wú)效。排查命令打開(kāi)命令行輸入java -version和javac -version。兩者必須都能正確輸出且版本一致。Unity 2019.3及以后版本通常要求JDK 8或特定版本的OpenJDK。Unity Hub安裝時(shí)會(huì)自帶一個(gè)推薦的JDK優(yōu)先使用它。2. Android SDK NDKSDK是構(gòu)建Android應(yīng)用的基石包含了平臺(tái)工具、構(gòu)建工具、系統(tǒng)鏡像等。NDK則用于編譯C/C代碼比如一些高性能插件或IL2CPP后端。常見(jiàn)坑點(diǎn)SDK路徑包含中文或特殊字符沒(méi)有安裝特定版本的Android SDK Build-Tools缺少目標(biāo)API Level的PlatformsNDK版本與Unity不兼容。關(guān)鍵路徑Unity中Edit - Preferences - External Tools。這里的Android SDK、JDK、NDK路徑必須真實(shí)有效。一個(gè)經(jīng)典錯(cuò)誤是SDK路徑指向了/Users/xxx/Library/Android/sdk但實(shí)際文件并不存在或權(quán)限不足。3. Gradle構(gòu)建過(guò)程的總指揮Unity默認(rèn)使用內(nèi)置的Gradle來(lái)構(gòu)建。你也可以選擇使用本地Gradle以獲取更多控制權(quán)。常見(jiàn)坑點(diǎn)網(wǎng)絡(luò)問(wèn)題導(dǎo)致Gradle無(wú)法下載依賴.gradle目錄下的緩存問(wèn)題本地Gradle版本與項(xiàng)目需求沖突gradle.properties文件配置錯(cuò)誤如代理設(shè)置。癥狀構(gòu)建卡在“Building Gradle project...”或“Resolving Dependencies...”很久最后超時(shí)失敗錯(cuò)誤信息常與無(wú)法下載*.jar或*.pom文件相關(guān)。2.2 Unity項(xiàng)目設(shè)置內(nèi)在的“基因”缺陷環(huán)境沒(méi)問(wèn)題那問(wèn)題就可能出在項(xiàng)目本身的設(shè)置上。這些設(shè)置在File - Build Settings - Player Settings中。1. 包名Bundle Identifier格式必須正確com.CompanyName.ProductName。不能包含空格、中文或特殊字符。這是應(yīng)用的唯一身份證設(shè)置不當(dāng)會(huì)導(dǎo)致清單文件合并失敗。2. 最低API級(jí)別Minimum API Level不能高于目標(biāo)API級(jí)別。如果你引入的某個(gè)第三方SDK要求最低API 24Android 7.0而你的項(xiàng)目設(shè)置是21就可能出問(wèn)題。務(wù)必檢查所有插件的文檔以其中要求的最高最低API為準(zhǔn)。3. 腳本后端Scripting Backend與目標(biāo)架構(gòu)Target ArchitecturesMono vs IL2CPPIL2CPP能帶來(lái)更好的性能和安全性但構(gòu)建時(shí)間更長(zhǎng)且對(duì)某些使用了反射的插件可能不友好。如果從Mono切換到IL2CPP后打包失敗很可能是插件兼容性問(wèn)題。Target Architectures通常勾選ARMv7和ARM64以覆蓋絕大多數(shù)設(shè)備。如果插件只提供了ARMv7的庫(kù).so文件而你勾選了ARM64在構(gòu)建時(shí)就會(huì)因?yàn)檎也坏綄?duì)應(yīng)庫(kù)而失敗。錯(cuò)誤信息通常是“More than one file was found with OS independent path lib/armeabi-v7a/xxx.so”或直接提示缺少某個(gè)架構(gòu)的庫(kù)。4. 圖標(biāo)、閃屏等其他設(shè)置雖然不常導(dǎo)致構(gòu)建失敗但圖標(biāo)尺寸不符合規(guī)范、閃屏圖片格式錯(cuò)誤等可能導(dǎo)致構(gòu)建后的應(yīng)用在安裝或運(yùn)行時(shí)崩潰也值得注意。2.3 第三方插件與依賴沖突江湖恩怨殃及池魚(yú)這是最復(fù)雜、最難調(diào)試的一類問(wèn)題。你的項(xiàng)目可能引入了A、B、C三個(gè)SDK它們各自都依賴了不同版本的Android支持庫(kù)如androidx.appcompat:appcompat或Google Play服務(wù)庫(kù)。1. 清單文件AndroidManifest.xml合并失敗每個(gè)Android庫(kù)都可能攜帶自己的AndroidManifest.xml。構(gòu)建時(shí)Gradle需要將它們與Unity主清單合并。如果出現(xiàn)重復(fù)的權(quán)限聲明、activity、meta-data標(biāo)簽且屬性沖突就會(huì)失敗。錯(cuò)誤示例Manifest merger failed : Attribute applicationname value(xxx.xxx.MyApplication) from AndroidManifest.xml。解決方案在Unity的Assets/Plugins/Android目錄下創(chuàng)建或修改主AndroidManifest.xml使用tools:replace或tools:node屬性來(lái)指導(dǎo)合并。例如application android:name.MyApplication tools:replaceandroid:name /。2. 資源res沖突不同SDK可能定義了同名的資源如strings.xml中的某個(gè)鍵或drawable下的同名圖片。構(gòu)建時(shí)會(huì)報(bào)“Duplicate resources”錯(cuò)誤。解決方案聯(lián)系插件提供商詢問(wèn)是否可以修改資源名?；蛘咄ㄟ^(guò)一些Gradle腳本在構(gòu)建過(guò)程中進(jìn)行資源重命名但這屬于高階操作。3. Java庫(kù)版本沖突這就是經(jīng)典的“依賴地獄”。A插件依賴com.google.android.gms:play-services-ads:20.0.0B插件依賴com.google.android.gms:play-services-ads:19.0.0。Gradle不知道用哪個(gè)。解決方案在Assets/Plugins/Android目錄下創(chuàng)建mainTemplate.gradle文件需要在Player Settings中啟用Custom Main Gradle Template在dependencies塊中使用強(qiáng)制分辨率策略dependencies { implementation(com.google.android.gms:play-services-ads:) { version { strictly 20.0.0 // 強(qiáng)制指定版本 } } }這需要你清楚沖突的庫(kù)是哪個(gè)版本該選哪個(gè)。2.4 構(gòu)建腳本與后處理自定義環(huán)節(jié)的陷阱有些項(xiàng)目會(huì)編寫(xiě)自己的IPostprocessBuildWithReport腳本在打包完成后自動(dòng)做一些事情比如復(fù)制文件、修改清單。如果這些腳本有Bug空引用、路徑錯(cuò)誤、無(wú)限循環(huán)也會(huì)導(dǎo)致構(gòu)建過(guò)程異常終止。3. 實(shí)戰(zhàn)排查流程從錯(cuò)誤信息到解決方案理論說(shuō)再多不如實(shí)戰(zhàn)。下面我們模擬一個(gè)最常見(jiàn)的錯(cuò)誤走一遍完整的排查流程。假設(shè)錯(cuò)誤信息CommandInvokationFailure: Gradle build failed. C:\Program Files\Unity\Hub\Editor\2022.3.20f1\Editor\Data\PlaybackEngines\AndroidPlayer\OpenJDK\bin\java.exe -Xmx4096M -Dcom.android.sdkmanager.toolsdirC:/Users/xxx/AppData/Local/Android/Sdk\tools ... FAILURE: Build failed with an exception. * What went wrong: Execution failed for task :launcher:mergeReleaseResources. A failure occurred while executing com.android.build.gradle.internal.res.ResourceCompilerRunnable Resource compilation failed. Check logs for details.3.1 第一步解讀錯(cuò)誤信息定位失敗階段Gradle build failed說(shuō)明環(huán)境初始化沒(méi)問(wèn)題問(wèn)題出在Gradle構(gòu)建過(guò)程中。定位失敗任務(wù):launcher:mergeReleaseResources。這是在合并資源圖片、布局、字符串等時(shí)失敗了。關(guān)鍵提示Resource compilation failed. Check logs for details.錯(cuò)誤信息不夠具體讓我們查看詳細(xì)日志。3.2 第二步查看詳細(xì)日志Unity構(gòu)建失敗時(shí)會(huì)在控制臺(tái)輸出大量信息。我們需要找到更底層的錯(cuò)誤。滾動(dòng)日志尋找以“Error”或“Caused by”開(kāi)頭的更具體信息。你可能會(huì)發(fā)現(xiàn)類似這樣的行.../res/drawable-xxhdpi/icon.png: error: failed to read PNG signature: file does not start with PNG signature.破案了問(wèn)題出在一張名為icon.png的圖片上它雖然以.png結(jié)尾但文件頭簽名損壞了不是有效的PNG格式。這可能是因?yàn)閳D片在導(dǎo)入U(xiǎn)nity時(shí)損壞或者本身就不是PNG格式卻被重命名了。3.3 第三步實(shí)施解決方案找到問(wèn)題資源根據(jù)日志路徑在項(xiàng)目Assets目錄下找到這張圖片。它可能來(lái)自某個(gè)第三方插件的Android資源文件夾例如Assets/Plugins/Android/xxx/res/drawable-xxhdpi/icon.png。驗(yàn)證與修復(fù)用專業(yè)的圖片查看器如IrfanView或編輯器如Photoshop打開(kāi)該文件。如果打不開(kāi)或提示損壞就從插件的原始?jí)嚎s包中重新提取或者聯(lián)系插件作者獲取新版本。清理與重試刪除項(xiàng)目根目錄下的Library和Temp文件夾關(guān)閉Unity后操作讓Unity重新導(dǎo)入所有資源。如果問(wèn)題在插件目錄也可以嘗試單獨(dú)刪除Assets/Plugins/Android目錄下的對(duì)應(yīng)插件文件夾然后重新導(dǎo)入。再次嘗試打包。3.4 第四步通用日志分析技巧搜索“error”不區(qū)分大小寫(xiě)在龐大的日志中用編輯器的搜索功能快速定位所有錯(cuò)誤行。關(guān)注第一個(gè)錯(cuò)誤構(gòu)建過(guò)程是鏈?zhǔn)降牡谝粋€(gè)錯(cuò)誤往往是根源后面的錯(cuò)誤可能是由其引發(fā)的連鎖反應(yīng)。先解決第一個(gè)。識(shí)別常見(jiàn)模式Duplicate class com.xxx... found in modules...-依賴沖突。Manifest merger failed-清單合并沖突。Unable to merge dex-方法數(shù)超過(guò)65536限制DEX limit需要啟用Multidex。Failed to find target with hash string android-30-SDK中未安裝API Level 30的平臺(tái)。Could not resolve all files for configuration ‘:launcher:releaseCompileClasspath’-Gradle依賴下載失敗通常是網(wǎng)絡(luò)或倉(cāng)庫(kù)配置問(wèn)題。4. 深度防御構(gòu)建穩(wěn)定打包環(huán)境的策略解決了眼前的問(wèn)題我們更要思考如何構(gòu)建一個(gè)健壯的、不易出錯(cuò)的開(kāi)發(fā)環(huán)境。4.1 環(huán)境隔離與版本管理使用Unity Hub管理編輯器版本為每個(gè)項(xiàng)目固定一個(gè)Unity版本。在Project Settings中記錄下確切的版本號(hào)如2022.3.20f1團(tuán)隊(duì)成員統(tǒng)一使用。JDK與SDK路徑純凈盡量使用Unity Hub安裝的配套JDK。Android SDK放在一個(gè)沒(méi)有中文和空格的路徑下如D:\Android\Sdk。避免安裝多個(gè)JDK造成環(huán)境變量混亂。NDK版本匹配在Unity安裝目錄的Editor/Data/PlaybackEngines/AndroidPlayer/NDK下查看Unity自帶的NDK版本。除非必要優(yōu)先使用這個(gè)內(nèi)置版本。如果必須用本地NDK確保版本號(hào)完全匹配Unity官方文檔的要求。4.2 項(xiàng)目配置標(biāo)準(zhǔn)化版本控制系統(tǒng)忽略必要文件確保.gradle、Library、Temp、Obj、Build等文件夾被正確添加到.gitignore對(duì)于Git。只提交源代碼和必要的插件、設(shè)置文件。維護(hù)一個(gè)“Clean Project”保留一個(gè)最基礎(chǔ)的、能打包成功的項(xiàng)目模板。當(dāng)新項(xiàng)目出現(xiàn)詭異問(wèn)題時(shí)可以快速對(duì)比Player Settings、Graphics Settings等配置差異。插件管理文檔化用一個(gè)文檔如README.md或Plugins.md記錄項(xiàng)目使用的所有第三方插件名稱、版本號(hào)、來(lái)源、以及已知的特殊配置步驟例如是否需要手動(dòng)修改AndroidManifest.xml需要哪些額外權(quán)限。4.3 構(gòu)建流程優(yōu)化啟用詳細(xì)日志在打包時(shí)打開(kāi)Build Settings窗口點(diǎn)擊左下角的Player Settings...在Other Settings的底部找到Scripting Define Symbols臨時(shí)添加UNITY_ANDROID_DEBUG。這有時(shí)會(huì)輸出更多構(gòu)建細(xì)節(jié)。或者在命令行構(gòu)建時(shí)使用-logFile參數(shù)將日志輸出到文件仔細(xì)分析。分步構(gòu)建先嘗試打一個(gè)Development Build并勾選Autoconnect Profiler和Deep Profiling。雖然這與Release構(gòu)建流程略有不同但能快速排除一些基礎(chǔ)腳本錯(cuò)誤。使用Export Android Project選項(xiàng)而不是直接構(gòu)建APK。這會(huì)生成一個(gè)標(biāo)準(zhǔn)的Android Studio/Gradle項(xiàng)目。然后你可以用Android Studio打開(kāi)這個(gè)項(xiàng)目進(jìn)行構(gòu)建。這樣做的好處是Android Studio的Gradle錯(cuò)誤提示通常更友好、更詳細(xì)能精準(zhǔn)定位到是哪個(gè)插件的build.gradle文件出了問(wèn)題。利用命令行構(gòu)建對(duì)于團(tuán)隊(duì)自動(dòng)化構(gòu)建使用命令行接口Unity.exe -batchmode -quit -projectPath ... -executeMethod ...。這能獲得純凈的、無(wú)界面干擾的構(gòu)建日志便于在CI/CD服務(wù)器上運(yùn)行和排查。5. 疑難雜癥與特殊案例實(shí)錄即使遵循了所有最佳實(shí)踐仍然會(huì)遇到一些“奇葩”問(wèn)題。這里分享幾個(gè)我親身經(jīng)歷的案例。案例一殺毒軟件或?qū)崟r(shí)防護(hù)工具的干擾現(xiàn)象打包過(guò)程隨機(jī)失敗錯(cuò)誤信息不固定有時(shí)是文件訪問(wèn)被拒絕有時(shí)是進(jìn)程被意外終止。背景在一次為某項(xiàng)目打包時(shí)構(gòu)建總在最后簽名階段失敗。日志顯示jarsigner命令異常退出。排查對(duì)比了成功和失敗的機(jī)器環(huán)境唯一區(qū)別是安全軟件。失敗機(jī)器安裝了某款 aggressive 的殺毒軟件。解決將Unity編輯器目錄、JDK目錄、項(xiàng)目目錄以及Android SDK目錄添加到該殺毒軟件的信任區(qū)白名單中。問(wèn)題立即消失。教訓(xùn)構(gòu)建過(guò)程涉及大量文件的讀寫(xiě)和進(jìn)程創(chuàng)建容易被安全軟件誤判為可疑行為。案例二磁盤(pán)空間不足或權(quán)限問(wèn)題現(xiàn)象構(gòu)建過(guò)程中途失敗提示“Cannot create directory...”或“There is not enough space on the disk”。排查構(gòu)建APK尤其是IL2CPP構(gòu)建會(huì)在Temp和Library目錄下產(chǎn)生大量中間文件可能占用數(shù)十GB空間。檢查構(gòu)建目標(biāo)盤(pán)符的剩余空間。在Mac/Linux上還要檢查對(duì)/tmp目錄的寫(xiě)入權(quán)限。解決清理磁盤(pán)確保有至少20GB的可用空間。在Windows上以管理員身份運(yùn)行Unity有時(shí)能解決權(quán)限問(wèn)題但不推薦作為常規(guī)做法。案例三Unity版本自身的Bug現(xiàn)象在升級(jí)到一個(gè)新的Unity補(bǔ)丁版本如從2022.3.10f1升到2022.3.11f1后原本正常的項(xiàng)目打包失敗。排查搜索Unity官方Issue Tracker或論壇用錯(cuò)誤關(guān)鍵詞查找發(fā)現(xiàn)該版本存在一個(gè)已知的、與特定Android Gradle Plugin版本相關(guān)的回歸Bug。解決根據(jù)社區(qū)反饋回退到上一個(gè)穩(wěn)定版本或者按照臨時(shí)方案修改mainTemplate.gradle中的AGP版本。教訓(xùn)不要盲目追求最新版本尤其是.x版本中的小版本號(hào)。在升級(jí)前查看該版本的Release Notes關(guān)注已知問(wèn)題。案例四文件名或路徑長(zhǎng)度超限Windows特有現(xiàn)象構(gòu)建失敗錯(cuò)誤信息晦澀可能與文件復(fù)制或壓縮有關(guān)。背景Windows系統(tǒng)有最大路徑長(zhǎng)度限制約260字符。當(dāng)項(xiàng)目嵌套很深或插件目錄結(jié)構(gòu)復(fù)雜時(shí)生成的中間文件路徑可能超過(guò)此限制。解決將整個(gè)項(xiàng)目移動(dòng)到更靠近磁盤(pán)根目錄的路徑下例如D:\Project而不是D:\MyDocuments\CompanyName\ClientName\ProjectName...。或者在Windows 10及以上版本啟用組策略中的“啟用Win32長(zhǎng)路徑”設(shè)置。打包Android失敗是一場(chǎng)與復(fù)雜系統(tǒng)斗智斗勇的戰(zhàn)斗沒(méi)有一勞永逸的銀彈。但它也絕非無(wú)跡可尋。核心思路就是分層排查、日志為王、環(huán)境純凈。從最底層的JDK/SDK路徑到項(xiàng)目層級(jí)的Player Settings再到插件間的依賴沖突最后到構(gòu)建環(huán)境本身像剝洋蔥一樣一層層檢查。每次成功解決一個(gè)打包問(wèn)題記得把解決步驟和核心原因記錄下來(lái)積累成你自己的“錯(cuò)題本”。久而久之你會(huì)發(fā)現(xiàn)大部分問(wèn)題都似曾相識(shí)解決起來(lái)也就得心應(yīng)手了。記住耐心和細(xì)致的日志分析是你最強(qiáng)大的武器。