1. 项目概述为什么Unity2020打包Android必须亲手配齐JDK、SDK、NDK三件套Unity2020发布Android包这件事表面看只是点一下“Build Run”但背后卡住90%新手的从来不是C#脚本写得对不对而是构建环境里那三座沉默的大山——JDK、SDK、NDK。我带过二十多个Unity小团队几乎每支队伍都经历过凌晨两点还在查“Failed to run ‘java -version’”“NDK not configured”“SDK path is invalid”这类报错。它们不是报错是系统在喊话“你连地基都没打平别急着盖楼。”这三者不是可选插件而是Unity Android构建链路上不可绕行的硬性依赖节点JDK负责把C#编译后的IL代码和Java层桥接逻辑翻译成JVM能执行的字节码SDK提供Android系统API的本地映射、ADB调试通道、模拟器运行时以及AAPT资源打包工具NDK则专攻C/C原生模块——比如你要接入高精度IMU传感器、调用OpenCV图像处理库、或者用FFmpeg做硬解码没有NDK这些功能在Android上根本跑不起来。Unity2020默认不捆绑任何一套它只认你本地配置好的路径且对版本有明确要求JDK必须是8或11官方明确不支持17SDK API Level至少29对应Android 10NDK必须是r21e或r23br22已被弃用。这不是Unity故意设门槛而是Android生态本身演进的结果——Google从Android 10开始强制要求64位应用NDK r21e是首个完整支持ARM64-v8a ABI的稳定版而JDK 17引入的强封装机制会直接导致Unity的Android Gradle插件加载失败。所以这篇教程不讲“怎么点按钮”只讲“为什么必须这样装、为什么必须装这个版本、装错一个字符会触发哪条错误链”。我会带你从零开始在Windows或macOS上亲手搭出一条稳如磐石的Android构建流水线。适合三类人刚从Unity2019升级过来发现打包报错的老手、第一次接触移动开发的Unity新人、以及被外包团队甩锅“环境问题”后自己想亲手验证的技术负责人。接下来所有操作我都已在两台物理机Win11 M1 Mac上实测通过每一步截图、日志、路径都经得起回溯。2. 环境设计逻辑与版本选型依据拒绝盲目下载理解每个组件的职责边界2.1 JDK不是越新越好而是要和Unity的Gradle插件握手成功Unity2020使用的Android构建系统基于Gradle 6.1.1而该版本Gradle的Java兼容性有明确限制仅支持JDK 8u202 或 JDK 11.0.2。JDK 17虽然已是LTS版本但Gradle 6.1.1的底层ClassLoader机制与JDK 17的强模块化Strong Encapsulation存在冲突会导致Unity在生成build.gradle时抛出java.lang.module.FindException: Module java.base not found。这不是Unity的bug是Gradle 6.x系列的设计约束。我试过三种方案JDK 17 强制修改gradle.properties添加org.gradle.jvmargs--add-opens java.base/java.langALL-UNNAMED但Unity每次Build都会重写该文件治标不治本JDK 11 手动降级Gradle版本需修改Unity安装目录下的Editor/Data/PlaybackEngines/AndroidPlayer/Tools/gradle/lib/gradle-core-6.1.1.jar风险极高且可能破坏Unity内部签名验证JDK 11.0.2 Unity官方推荐组合零修改、零冲突、长期稳定。因此我们锁定JDK 11.0.2。注意不是“JDK 11”而是精确到小版本号。Oracle官网已下架旧版JDK 11.0.2但Adoptium现为Eclipse Temurin仍提供安全更新的镜像。下载地址必须是https://adoptium.net/temurin/releases/?version11 —— 进入后选择11.0.29Build 9是该版本的最终安全补丁号操作系统选对应平台Package Type选JDK非JRE。提示不要用“jdk-11_windows-x64_bin.exe”这类命名模糊的安装包。Temurin的包名格式为OpenJDK11U-jdk_x64_windows_hotspot_11.0.2_9.zip解压即用无需安装程序避免注册表污染。2.2 SDK不是全量安装而是按Unity需求精简裁剪Android SDK包含数百个组件但Unity真正需要的只有5个核心模块Android SDK Platform-Tools含adb命令用于设备连接、日志抓取、APK安装Android SDK ToolsLegacy含android命令行工具虽已废弃但Unity2020的旧版Gradle仍调用它生成keystoreAndroid SDK Build-Tools 29.0.3Unity2020默认调用的AAPT2版本用于资源编译Android SDK Platform 29对应Android 10 API是Unity2020的最低要求Android Emulator非必需但调试时比真机更可控。其他如“Android SDK Sources for Android 29”“Google APIs”“Google Play services”等Unity打包时完全不读取。全量安装不仅浪费20GB磁盘空间还会因组件版本冲突导致SDK location not found错误。关键细节SDK Manager的GUI界面在Unity2020中已被弃用我们必须用命令行工具sdkmanager精准控制。它位于SDK根目录的cmdline-tools/latest/bin/下但该路径默认不存在——你需要手动创建cmdline-tools/latest/文件夹并将sdkmanager二进制文件放进去。这是Google在2020年强制推行的SDK目录结构变更Unity2020尚未适配必须人工补位。2.3 NDK不是最新版最稳而是r21e与Unity2020的ABI契约NDK版本选择的核心逻辑是ABIApplication Binary Interface兼容性。Unity2020默认生成的.so库目标架构是armeabi-v7a和arm64-v8a而NDK r21e是首个同时提供完整arm64-v8a工具链aarch64-linux-android-clang且修复了__atomic_fetch_add_8符号缺失问题的版本。r22在Android 11上会出现undefined reference to __atomic_load_8链接错误r23b虽支持但Unity2020的Native Plugin加载器未适配其新的CMake工具链路径。因此我们必须用NDK r21e。官方下载地址https://developer.android.com/ndk/downloads/older_releases#ndk-r21e-downloads —— 注意选择NDK r21e (August 2020)不是“Latest Stable”。下载后解压得到android-ndk-r21e文件夹路径中不能包含空格或中文如C:\Program Files\或/Users/张三/否则Unity会解析失败。这是Unity2020的硬伤无法通过配置修复。3. 全流程实操从零开始搭建可验证的Android构建环境3.1 JDK安装与环境变量配置Windows/macOS双路径Windows平台实操步骤访问https://adoptium.net/temurin/releases/?version11下载OpenJDK11U-jdk_x64_windows_hotspot_11.0.2_9.zip解压到固定路径例如D:\JDK\jdk-11.0.29路径不含空格、无中文、非系统盘右键“此电脑”→“属性”→“高级系统设置”→“环境变量”在“系统变量”中新建变量变量名JAVA_HOME变量值D:\JDK\jdk-11.0.29注意不带bin目录编辑“系统变量”中的Path新增一行%JAVA_HOME%\bin打开新CMD窗口执行java -version输出应为openjdk version 11.0.2 2019-01-15 OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.29) OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.29, mixed mode)若提示“不是内部命令”检查Path是否漏掉%JAVA_HOME%\bin或JAVA_HOME路径末尾是否多了\。macOS平台实操步骤下载OpenJDK11U-jdk_aarch64_mac_hotspot_11.0.2_9.tar.gzM1芯片或x64_macIntel解压到/Library/Java/JavaVirtualMachines/得到/Library/Java/JavaVirtualMachines/jdk-11.0.29.jdk编辑~/.zshrcM1或~/.bash_profileIntel添加export JAVA_HOME$(/usr/libexec/java_home -v 11.0.2) export PATH$JAVA_HOME/bin:$PATH执行source ~/.zshrc再运行java -version验证。注意Windows用户若使用PowerShell需在PowerShell中同样配置$env:JAVA_HOME和$env:Path因为Unity Editor启动时读取的是PowerShell环境变量而非CMD。3.2 SDK下载、精简安装与路径初始化第一步获取命令行SDK Manager访问https://developer.android.com/studio#command-tools下载“Command line tools only”解压得到cmdline-tools文件夹进入SDK根目录如D:\Android\Sdk创建子目录cmdline-tools\latest\将下载的cmdline-tools\bin\下所有文件sdkmanager.bat、avdmanager.bat等复制到D:\Android\Sdk\cmdline-tools\latest\。第二步用sdkmanager精准安装5个必需组件打开CMD执行cd /d D:\Android\Sdk\cmdline-tools\latest sdkmanager --sdk_rootD:\Android\Sdk platform-tools platforms;android-29 build-tools;29.0.3 tools emulator注意--sdk_root参数必须显式指定否则sdkmanager会默认使用C:\Users\用户名\AppData\Local\Android\Sdk与Unity配置路径不一致。第三步验证SDK完整性执行sdkmanager --list_installed输出中必须包含platform-tools | 34.0.5 platforms;android-29 | 3 build-tools;29.0.3 | 29.0.3 tools | 26.1.1 emulator | 32.1.12若缺少任一项重新运行安装命令。特别注意build-tools;29.0.3——Unity2020的aapt2调用硬编码了该版本号安装29.0.2或29.0.4都会报错AAPT2 aapt2-29.0.3-5434570-windows Daemon #0 failed to shut down within 10 seconds。3.3 NDK r21e部署与Unity路径绑定NDK部署要点下载android-ndk-r21e-windows-x86_64.zipWindows或-darwin-x86_64.zipmacOS解压到D:\Android\ndk\android-ndk-r21eWindows或/Users/xxx/Library/Android/sdk/ndk/android-ndk-r21emacOS确保路径中无空格、无中文、无特殊符号如、#不要将NDK放在SDK目录内Unity2020要求NDK路径独立于SDK否则会触发NDK path contains spaces or invalid characters校验失败。Unity中绑定路径打开Unity Hub → 选择Unity2020.x版本 → 点击右上角“Settings” → “External Tools”勾选“Android” → 在“JDK”栏填入D:\JDK\jdk-11.0.29在“SDK”栏填入D:\Android\Sdk在“NDK”栏填入D:\Android\ndk\android-ndk-r21e点击“Apply”Unity会自动检测并显示版本号如JDK 11.0.2、SDK 29、NDK r21e。实操心得若Unity显示“NDK not configured”先检查路径末尾是否有多余\如D:\Android\ndk\android-ndk-r21e\Unity会将其识别为无效路径其次检查NDK文件夹内是否存在source.properties文件——这是NDK的版本标识文件缺失则Unity无法识别。3.4 Unity项目级配置Player Settings深度调优完成全局环境配置后必须在项目中做三处关键设置Target Architectures在File → Build Settings → Player Settings → Publishing Settings中勾选ARM64必选和ARMv7可选。若只勾选ARMv7生成的APK将无法在华为Mate 40、小米12等新机型安装MinifyPublishing Settings → Minify → Release选择None。Unity2020的ProGuard混淆器与JDK 11存在反射调用冲突开启后会导致ClassNotFoundExceptionCustom Main Manifest若项目需自定义权限如uses-permission android:nameandroid.permission.CAMERA/必须勾选Custom Main Manifest然后在Assets/Plugins/Android/AndroidManifest.xml中编辑——Unity会合并该文件与自动生成的Manifest而非覆盖。最后验证创建一个空场景添加一个TextMeshProUGUI文本脚本中写Debug.Log(Android Build Test OK);File → Build Settings → Platform选Android → Build若生成test.apk且无红色报错即环境配置成功。将APK拖入安卓手机安装打开后Logcat应输出该日志。4. 常见问题与排查技巧实录那些官方文档不会写的坑4.1 经典报错链路与根因定位表报错信息根本原因排查步骤修复方案Failed to run java -versionJAVA_HOME路径错误或Path未包含%JAVA_HOME%\bin在CMD中执行echo %JAVA_HOME%和where java检查JAVA_HOME是否指向JDK根目录非binwhere java是否返回%JAVA_HOME%\bin\java.exeSDK root directory does not existUnity中SDK路径填写了D:\Android\Sdk\platforms等子目录在Unity External Tools中查看SDK路径是否以Sdk结尾删除路径末尾的\platforms等确保是SDK根目录NDK not configured. Download it with SDK manager.NDK路径含空格/中文或source.properties文件缺失进入NDK文件夹用记事本打开source.properties重命名NDK文件夹为纯英文或重新下载完整r21e包AAPT2 error: check logs for detailsbuild-tools;29.0.3未安装或版本号不匹配运行sdkmanager --list_installed | findstr build-tools重新执行sdkmanager build-tools;29.0.3确认安装成功Gradle build failed: Could not resolve all artifactsUnity使用了旧版Gradle插件与JDK 11.0.2的TLS协议不兼容查看Temp/gradleOut/build.gradle第3行distributionUrl手动修改为distributionUrlhttps\://services.gradle.org/distributions/gradle-6.1.1-bin.zip4.2 隐藏陷阱Windows Defender与macOS Gatekeeper的干扰Windows场景Windows Defender的“受控文件夹访问”功能会拦截sdkmanager对build-tools目录的写入导致安装后D:\Android\Sdk\build-tools\29.0.3\为空。现象是sdkmanager --list_installed显示已安装但D:\Android\Sdk\build-tools\下无29.0.3文件夹。解决方案打开“Windows安全中心”→“病毒和威胁防护”→“勒索软件防护”→“受控文件夹访问”→“关闭”重新运行sdkmanager安装命令安装完成后可重新开启该功能。macOS场景macOS Catalina系统会对sdkmanager执行文件标记“已损坏”双击运行提示“已损坏无法打开”。这是因为sdkmanager是Java写的脚本未通过Apple Developer ID签名。解决方案在终端执行xattr -d com.apple.quarantine /path/to/sdkmanager将/path/to/sdkmanager替换为你实际的路径例如/Users/xxx/Library/Android/sdk/cmdline-tools/latest/sdkmanager。4.3 真机调试必知的ADB授权链即使环境配置成功首次连接安卓手机仍可能卡在“Waiting for device”。这不是Unity问题而是ADB授权未通过手机开启“开发者选项”连续点击“关于手机”中“版本号”7次开启“USB调试”用USB线连接电脑手机弹出“允许USB调试吗”对话框勾选“始终允许”点击“确定”CMD中执行adb devices应显示设备序列号device状态。若显示unauthorized说明手机未授权。此时拔掉USB线重启手机ADB服务adb kill-server adb start-server再重新连接。这是安卓系统级安全机制与Unity环境无关但90%的新手会误以为是Unity配置失败。4.4 Unity2020特有的Gradle缓存污染问题Unity2020在首次Build时会生成Temp/gradleOut/目录其中包含gradle/wrapper/gradle-wrapper.properties。若你中途更换过JDK或SDK路径该文件中的distributionUrl可能仍指向旧版本Gradle导致后续Build持续失败。清理方法关闭Unity Editor删除项目根目录下的Temp/文件夹Unity会自动重建删除Library/文件夹耗时较长但可彻底清除缓存重新打开Unity再次Build。实操心得我曾遇到一个案例客户提供的项目Temp/gradleOut/gradle/wrapper/gradle-wrapper.properties中distributionUrl指向gradle-5.6.4-bin.zip而Unity2020要求6.1.1。手动修改后Build成功但下次打开Unity又恢复为5.6.4——根源是ProjectSettings/EditorBuildSettings.asset中缓存了旧Gradle路径。最终解决方案是删除整个Library/让Unity重新生成全部元数据。5. 进阶技巧与长期维护建议让环境持续稳定运行的实战经验5.1 创建可复用的环境检查脚本Windows Batch / macOS Shell手动验证每个组件太耗时我编写了一个5分钟就能跑完的自检脚本放在项目根目录下每次换新机器或重装系统时双击运行Windows版check_android_env.batecho off echo JDK Check if not defined JAVA_HOME ( echo ERROR: JAVA_HOME not set exit /b 1 ) %JAVA_HOME%\bin\java -version 2nul || ( echo ERROR: java -version failed exit /b 1 ) echo JDK OK echo SDK Check if not exist D:\Android\Sdk\platforms\android-29 ( echo ERROR: SDK Platform 29 not found exit /b 1 ) if not exist D:\Android\Sdk\build-tools\29.0.3\aapt2.exe ( echo ERROR: Build-tools 29.0.3 not found exit /b 1 ) echo SDK OK echo NDK Check if not exist D:\Android\ndk\android-ndk-r21e\source.properties ( echo ERROR: NDK r21e source.properties missing exit /b 1 ) echo NDK OK echo All Checks Passed! pausemacOS版check_android_env.sh#!/bin/bash echo JDK Check if [ -z $JAVA_HOME ]; then echo ERROR: JAVA_HOME not set exit 1 fi $JAVA_HOME/bin/java -version /dev/null 21 || { echo ERROR: java -version failed exit 1 } echo JDK OK echo SDK Check if [ ! -d $HOME/Library/Android/sdk/platforms/android-29 ]; then echo ERROR: SDK Platform 29 not found exit 1 fi if [ ! -f $HOME/Library/Android/sdk/build-tools/29.0.3/aapt2 ]; then echo ERROR: Build-tools 29.0.3 not found exit 1 fi echo SDK OK echo NDK Check if [ ! -f $HOME/Library/Android/sdk/ndk/android-ndk-r21e/source.properties ]; then echo ERROR: NDK r21e source.properties missing exit 1 fi echo NDK OK echo All Checks Passed! 5.2 多Unity版本共存时的路径隔离策略团队中常有Unity2019、2020、2021并存的情况。若所有版本共用同一套JDK/SDK/NDK一旦某版本升级导致路径变更其他版本立即失效。我的做法是JDK为每个Unity版本分配独立JDK如D:\JDK\unity2020\jdk-11.0.29、D:\JDK\unity2021\jdk-17.0.112SDK共用一套SDK因API Level向下兼容但为每个Unity版本创建软链接mklink /D D:\Unity2020\Sdk D:\Android\SdkNDK严格隔离Unity2020用r21eUnity2021用r23b路径完全独立。这样既节省磁盘空间又避免版本冲突。Unity Hub的External Tools设置支持为每个Unity版本单独配置路径无需全局修改。5.3 当Unity突然报“Android SDK is not installed”时的终极诊断法这个报错往往出现在环境明明配置正确的情况下。我的诊断流程是查Unity日志打开C:\Users\[用户名]\AppData\Local\Unity\Editor\Editor.log搜索AndroidSdkRoot确认Unity读取的实际路径查RegistryWindows运行regedit定位HKEY_CURRENT_USER\Software\Unity Technologies\Unity Editor 5.x\AndroidSdkRoot对比是否与Unity界面中设置的路径一致查Unity Hub缓存删除C:\Users\[用户名]\AppData\Roaming\UnityHub\settings.json重启Unity Hub重新配置路径。90%的“SDK未安装”报错根源是Unity Hub的settings.json缓存了旧路径而Unity Editor读取的是该文件而非界面输入值。删除后重新配置一劳永逸。我在实际项目中踩过的最大坑是某次Windows系统更新后adb命令被重置为系统自带的旧版本1.0.32导致adb devices返回空列表。花了3小时排查最后发现是D:\Android\Sdk\platform-tools\adb.exe被Windows更新覆盖。解决方案是将platform-tools文件夹重命名为platform-tools-bak再用sdkmanager重新安装一次。这个细节官方文档永远不会提但却是真实世界里高频发生的故障。