★ FEATURED ARTICLE 1. 为什么Unity安卓环境配置值得单独拿出来讲做过Unity移动端项目的朋友大概率都有过这种体验编辑器里跑得好好的场景一切换到Android平台就报一堆红字要么是SDK路径找不到要么是Gradle版本对不上要么是打包出来装到手机上直接闪退。更让人头疼的是这类问题往往不是代码逻辑的错而是环境配置的坑。你花两个小时排查一个“Build failed”最后发现只是某个路径里带了中文或者空格。所以我把这次配置过程完整记录下来不是照搬官方文档而是把每一步背后的原因、容易翻车的地方、以及我实际踩过的坑都摊开讲。这篇文章适合刚接触Unity移动端开发的新手也适合之前一直做PC端、现在需要把项目往安卓上迁的老手。核心关键词就一个Unity安卓环境配置。我会从整体思路讲到具体操作再到问题排查尽量让不同基础的人都能照着做下来。先说清楚一件事Unity打包安卓本质上是你本机的Unity编辑器调用外部的一整套工具链把C#代码、资源、第三方库编译成能在安卓设备上运行的APK或AAB。这套工具链包括JDK、Android SDK、NDK、Gradle它们各自有版本要求彼此之间还有兼容性约束。Unity Hub从某个版本开始提供了“一键安装模块”的功能但那个功能只解决了一部分问题真正遇到自定义需求时你还是得手动配。这就是为什么很多人明明点了“安装Android Build Support”打包时依然报错。我这次配置的目标很明确在一台Windows机器上让Unity能够稳定地打出安卓包并且支持后续接入第三方SDK、自定义Gradle模板、以及处理常见的架构和API Level问题。下面按我的实际顺序展开。2. 整体思路与工具链选型拆解2.1 先搞清楚Unity打包安卓到底依赖哪些东西很多人一上来就装Android Studio装完发现Unity里还是配不对。问题在于没理清依赖关系。Unity打包安卓核心依赖四样东西JDKJava Development KitGradle和安卓构建工具本身是Java写的没有JDK就跑不起来。Unity对JDK版本有明确要求版本不对会直接报“Unable to find java”或者Gradle同步失败。Android SDK里面包含构建工具Build-Tools、平台工具Platform-Tools主要是adb、以及各个API Level的平台文件Platforms。Unity需要知道SDK的根目录在哪。NDKNative Development Kit如果你的项目用了IL2CPP脚本后端或者集成了C/C写的原生库就需要NDK来编译。用Mono后端理论上可以不装NDK但实际项目里IL2CPP几乎是标配。Gradle安卓的构建系统。Unity会自带一个Gradle版本但你可以选择用自定义的。Gradle版本和安卓Gradle插件版本、JDK版本之间是强绑定的。这四者之间的关系可以这样理解JDK是发动机SDK是工具箱NDK是特殊工具Gradle是装配流水线。任何一个版本错位整条线就卡住。2.2 为什么我不推荐无脑用Unity Hub一键安装Unity Hub的“Android Build Support”模块确实方便它会帮你下载OpenJDK、SDK、NDK并自动填好路径。对于纯新手、只做简单项目的人来说这是最省事的方案。但它有几个明显的局限第一它下载的SDK和NDK版本是跟着Unity版本走的可能不是你项目需要的版本。比如你的项目要接入某个第三方库那个库要求最低API Level 24而Hub装的SDK里没有对应的Platform你就得手动补。第二Hub安装的路径默认在C盘用户目录下路径里可能包含空格或特殊字符某些Gradle版本对路径很敏感。第三当你需要自定义Gradle模板、修改gradle.properties、或者处理依赖冲突时你还是得手动去改这些文件而Hub装的目录结构和你自己装的Android Studio目录结构不完全一样找起来费劲。我的做法是JDK和Gradle用Unity自带的SDK和NDK用Android Studio的SDK Manager来管理。这样既保证了Unity能识别又保留了灵活增删API Level和Build-Tools的能力。下面详细说。2.3 版本匹配的核心逻辑版本匹配是配置过程中最容易出问题的地方。我整理了一个实际可用的版本对应关系以Unity 2021 LTS和2022 LTS为例组件Unity 2021 LTS 推荐Unity 2022 LTS 推荐说明JDKOpenJDK 11OpenJDK 11Unity自带不要随意换Gradle6.7.17.5.1Unity自带可在设置里覆盖Android Gradle Plugin4.0.17.1.2由Unity的Gradle版本决定SDK Build-Tools30.0.333.0.1建议装多个版本最低API Level2222看项目需求目标API Level3133应用商店有要求NDKr21dr23bIL2CPP必需这张表不是绝对的但如果你不想折腾按这个来基本不会出大问题。关键原则是JDK版本不要动Gradle版本尽量用Unity自带的SDK和NDK可以按需调整。注意不要同时装多个JDK然后让系统PATH指向另一个版本。Unity在打包时会优先使用它自己配置的JDK路径但Gradle有时会去读系统环境变量导致版本混乱。最稳妥的做法是让Unity设置里的JDK路径指向它自带的那个系统PATH里不要放其他JDK。3. 核心细节解析与实操要点3.1 JDK的配置与验证Unity从2019.3开始自带OpenJDK路径一般在# Windows 默认路径示例 C:\Program Files\Unity\Hub\Editor\2021.3.x\Editor\Data\PlaybackEngines\AndroidPlayer\OpenJDK在Unity里打开Edit Preferences External Tools找到JDK那一栏勾选“Installed with Unity (recommended)”。这样Unity就会用自带的JDK。验证JDK是否可用的方法打开命令行进入上面那个路径的bin目录执行java -version如果输出类似openjdk version 11.0.x就说明没问题。如果报“不是内部或外部命令”说明路径不对或者文件缺失重新通过Hub安装Android Build Support模块。这里有个细节有些教程会让你去装Oracle JDK或者AdoptOpenJDK然后手动指定路径。我试过在Unity 2021上指定外部JDK 17会直接导致Gradle同步失败因为Unity自带的Gradle 6.7.1不支持JDK 17。所以除非你明确知道自己在做什么否则不要换JDK。3.2 Android SDK的安装与目录结构我推荐用Android Studio的SDK Manager来装SDK因为它的界面直观增删组件方便。如果你不想装完整的Android Studio也可以单独下载command-line tools但那个对新手不太友好。装好Android Studio后打开SDK Manager重点装这几项SDK Platforms至少勾选一个你目标API Level对应的平台比如Android 12 (API 31) 或 Android 13 (API 33)。建议多勾几个方便切换。SDK Tools必须勾选Android SDK Build-Tools、Android SDK Platform-Tools、Android SDK Command-line Tools。NDK根据是否需要IL2CPP来决定建议勾上。NDK在SDK Tools里勾选NDK (Side by side)它会装到SDK目录下的ndk文件夹里每个版本一个子目录。装完后SDK的根目录一般在# Windows 默认路径 C:\Users\你的用户名\AppData\Local\Android\Sdk这个路径要记下来待会填到Unity里。注意路径里不要有中文和空格。如果你的用户名是中文建议把SDK装到D盘根目录下比如D:\Android\Sdk。3.3 NDK的选择与坑点NDK不是必须的但如果你用IL2CPP后端就必须有。Unity对NDK版本有要求版本不对会报“NDK not found”或者编译原生代码时出错。在Unity的External Tools设置里NDK那一栏可以勾选“Installed with Unity”或者手动指定路径。我建议手动指定指向Android SDK目录下的ndk文件夹里你装的那个版本。比如D:\Android\Sdk\ndk\23.1.7779620注意要指到具体版本号那一层不要只指到ndk文件夹。实操心得如果你同时装了多个NDK版本Unity只会用你指定的那个。但Gradle在构建时可能会去环境变量里找NDK导致版本冲突。解决办法是在项目的gradle.properties里显式指定android.ndkVersion或者在Unity的NDK路径里只保留一个版本。3.4 Gradle的配置策略Unity自带的Gradle版本在C:\Program Files\Unity\Hub\Editor\2021.3.x\Editor\Data\PlaybackEngines\AndroidPlayer\Tools\gradle在External Tools里Gradle那一栏可以勾选“Installed with Unity”或者指定自定义Gradle。我强烈建议用自带的除非你有明确的理由换。如果你需要自定义Gradle模板可以在Player Settings Publishing Settings里勾选“Custom Gradle Template”Unity会在Assets/Plugins/Android下生成mainTemplate.gradle和gradleTemplate.properties。这两个文件可以让你修改依赖、添加仓库、调整编译选项。这里有个常见的坑修改了mainTemplate.gradle后如果格式不对Gradle同步会直接失败报错信息往往很模糊。我的经验是改之前先备份改完之后用Android Studio打开Assets/Plugins/Android目录让它帮你做一次Gradle同步能提前发现语法错误。4. 完整实操流程与关键环节实现4.1 第一步通过Unity Hub安装Android Build Support打开Unity Hub找到你正在用的Unity版本点击右侧的齿轮图标选择“Add modules”。在弹出的列表里勾选Android Build Support下面的子项Android SDK NDK Tools、OpenJDK这一步会下载几个G的文件时间取决于网速。装完后Unity的安装目录下会多出PlaybackEngines/AndroidPlayer文件夹里面就是SDK、NDK、JDK的默认位置。如果你之前已经装过可以跳过这步但建议检查一下这些文件夹是否存在且完整。4.2 第二步配置External Tools路径打开Unity新建或打开一个项目进入Edit Preferences External Tools。按照下面的表格逐项配置配置项勾选/路径说明JDK勾选 Installed with Unity用自带JDKAndroid SDK手动指定 D:\Android\Sdk指向Android Studio装的SDKAndroid NDK手动指定 D:\Android\Sdk\ndk\23.1.7779620指向具体版本Gradle勾选 Installed with Unity用自带Gradle配置完后点击每个路径旁边的“Browse”确认一下能不能正常打开。如果SDK路径填错Unity会提示“Invalid SDK path”。4.3 第三步切换平台并设置Player Settings点击File Build Settings在平台列表里选择Android然后点击“Switch Platform”。这个过程会把项目里的资源重新导入为安卓格式时间可能比较长取决于项目大小。切换完成后点击“Player Settings”重点设置这几项Company Name 和 Product Name随便填但不要用中文。Package Name格式是com.公司名.项目名必须唯一不能有中文和大写字母。Minimum API Level根据你的用户群体决定一般设22或23。Target API Level建议设31或33应用商店有要求。Scripting Backend选IL2CPP除非你有特殊理由用Mono。Target Architectures勾选ARM64和ARMv7。如果只勾ARMv7某些新设备装不上只勾ARM64老设备装不上。两个都勾最稳但包体会大一些。4.4 第四步处理Gradle依赖和自定义配置如果你的项目没有引入任何第三方安卓库这一步可以跳过。但如果引入了比如广告SDK、推送SDK、支付SDK就需要在mainTemplate.gradle里添加依赖。打开Assets/Plugins/Android/mainTemplate.gradle找到dependencies块在里面添加dependencies { implementation fileTree(dir: libs, include: [*.jar]) implementation com.example.library:1.0.0 // 其他依赖 }同时在gradleTemplate.properties里可以添加一些全局配置比如android.useAndroidXtrue android.enableJetifiertrue org.gradle.jvmargs-Xmx4096mandroid.useAndroidXtrue是必须的因为现在大部分安卓库都迁移到AndroidX了。org.gradle.jvmargs用来调整Gradle的内存如果项目大、依赖多默认内存可能不够导致构建失败。注意每次修改这两个文件后建议先删除Library目录下的Gradle缓存或者执行一次Assets Play Services Resolver Android Resolver Force Resolve如果装了External Dependency Manager确保依赖被正确解析。4.5 第五步打包测试与验证点击File Build Settings点击“Build”或者“Build And Run”。如果一切正常会生成一个APK文件。第一次构建会比较慢因为要下载Gradle依赖、编译原生代码。构建完成后把APK装到手机上重点验证这几项应用能否正常启动有没有闪退。如果用了IL2CPP检查ARM64和ARMv7是否都正常。如果接了第三方SDK检查初始化是否成功。检查日志里有没有ClassNotFoundException或NoSuchMethodError这些通常是依赖冲突或混淆导致的。我习惯在构建完成后用adb logcat看一遍启动日志确认没有隐藏的报错。命令是adb logcat -s Unity:V这样只过滤Unity相关的日志看起来清爽。5. 常见问题与排查技巧实录5.1 构建失败类问题速查表报错信息可能原因解决方法Unable to find javaJDK路径不对或版本不兼容检查External Tools里的JDK路径确保指向Unity自带JDKSDK not foundSDK路径填错或缺少Platform检查路径用SDK Manager补装对应API LevelNDK not foundNDK路径没指到具体版本路径要指到ndk/版本号那一层Gradle sync failedGradle版本与JDK不匹配用Unity自带Gradle不要换JDKDuplicate class依赖冲突用gradleTemplate.properties排除重复依赖minSdkVersion mismatch第三方库要求的最低API高于项目设置提高项目的Minimum API Level打包后闪退架构不匹配或混淆问题检查Target Architectures检查Proguard规则5.2 路径与权限的坑Windows上最容易出问题的是路径。我遇到过好几次SDK装在C:\Users\张三\AppData\Local\Android\Sdk因为用户名是中文Gradle直接报“Invalid path”。解决办法是把SDK移到纯英文路径下比如D:\Android\Sdk。另一个坑是权限。如果你把Unity装在C盘Program Files下某些操作可能需要管理员权限。我建议把Unity和SDK都装在非系统盘避免权限问题。5.3 依赖冲突的排查思路依赖冲突是安卓打包里最烦人的问题之一。典型表现是构建成功但运行时报ClassNotFoundException或NoSuchMethodError。排查步骤在mainTemplate.gradle里添加implementation依赖时注意版本号。不同库可能依赖同一个库的不同版本。用./gradlew :app:dependencies命令查看依赖树需要在Android Studio里打开项目。找到冲突的库用exclude排除掉旧版本implementation(com.example.library:1.0.0) { exclude group: com.android.support, module: support-v4 }如果用了AndroidX确保所有库都迁移到AndroidX不要混用support库。5.4 构建速度优化技巧安卓构建慢是常态但可以优化在gradleTemplate.properties里加大Gradle内存org.gradle.jvmargs-Xmx4096m。开启Gradle缓存org.gradle.cachingtrue。开启并行构建org.gradle.paralleltrue。如果不需要每次构建都跑Proguard可以在调试版本里关掉。把Build Settings里的“Build App Bundle”关掉除非你要上传商店APK构建比AAB快。实操心得我习惯在开发阶段用Mono后端加ARMv7单架构构建速度最快。等到要出包测试或上线时再切回IL2CPP加双架构。这样能省不少等待时间。5.5 版本升级后的环境迁移Unity版本升级后安卓环境经常需要重新配。比如从2021升到2022Gradle版本从6.7.1变成7.5.1JDK可能还是11但SDK Build-Tools需要更新。我的做法是先备份现有的mainTemplate.gradle和gradleTemplate.properties。升级Unity后重新在External Tools里确认路径。用SDK Manager补装新版本要求的Build-Tools和Platform。把备份的Gradle文件内容合并到新生成的文件里注意语法可能有变化。清理Library目录重新构建。这个过程我走过几次每次大概花半小时到一小时主要时间在下载和重新构建上。6. 一些容易被忽略的细节和我的个人习惯6.1 关于API Level的选择Minimum API Level决定了你的应用能装到哪些设备上。设得太低比如21能覆盖更多老设备但某些新API用不了而且Google Play对最低版本有要求。设得太高比如26会丢掉一部分老用户。我的经验是面向国内市场设22或23面向海外市场设24或26。Target API Level则要跟着应用商店的要求走目前建议至少31。6.2 关于包体大小安卓包体大小受几个因素影响架构数量、纹理压缩格式、代码混淆。如果包体太大可以考虑只保留ARM64放弃ARMv7能省不少空间但会丢掉老设备。用ETC2或ASTC纹理压缩比RGBA32省很多。开启Proguard或R8混淆能减小代码体积。用AssetBundle或Addressables把资源拆出去首包只留必要资源。6.3 关于真机调试打包出来装到手机上只是第一步真机调试才能发现真正的问题。我习惯用USB连接手机开启开发者模式和USB调试然后在Unity里点“Build And Run”这样Unity会自动安装并启动应用同时把日志输出到Console窗口。如果Console里看不到日志可以用adb logcat在命令行看。还有一个技巧在手机上装一个Logcat查看器应用比如“Logcat Reader”这样不用连电脑也能看日志适合外出测试。6.4 关于自动化构建如果团队里有多个人或者需要频繁出包建议把安卓构建自动化。Unity提供了命令行构建的方式Unity.exe -quit -batchmode -projectPath D:\MyProject -executeMethod BuildScript.BuildAndroid -logFile build.log你可以写一个静态方法BuildScript.BuildAndroid在里面调用BuildPipeline.BuildPlayer设置好各种参数。这样就能集成到CI/CD流水线里每次提交代码自动出包。不过自动化构建的前提是环境配置必须稳定否则流水线会频繁失败。所以先把本文说的这些配置做扎实再考虑自动化。7. 最后再分享几个压箱底的小技巧第一个技巧如果你不确定某个第三方库需要什么版本的SDK或Gradle去它的官方文档里找“Requirements”或“Setup”章节通常会写明最低API Level、需要的Gradle版本、以及是否依赖AndroidX。照着配比瞎试快得多。第二个技巧Unity的Assets/Plugins/Android目录下可以放AndroidManifest.xml用来覆盖默认的清单文件。如果你需要添加权限、修改启动Activity、或者配置Provider都在这里改。改完后记得在Player Settings里确认“Custom Main Manifest”被勾选。第三个技巧遇到构建报错但看不懂日志时先去C:\Users\你的用户名\AppData\Local\Unity\Editor\Editor.log里搜“error”或“failed”Unity的详细日志都在那里。Gradle的详细日志则在项目目录的Library\Bee\Android\Prj\IL2CPP\Gradle下里面有完整的构建输出。第四个技巧如果你用的是Windows建议把Windows Defender的实时扫描对Unity项目目录和SDK目录排除掉否则构建时文件读写会被拖慢很多。我实测排除后构建时间能缩短20%左右。这些就是我这次配置Unity安卓环境的完整记录。环境配置这件事第一次做会觉得繁琐但把原理搞清楚之后后面遇到问题就能快速定位。希望这些内容能帮你少走一些弯路。
阅读完成 · 觉得有帮助？
