1. 项目概述与问题定位如果你正在用 Jenkins 自动化打包 Unity 项目到安卓平台并且遇到了 AAPT2 在处理 AAR 资源时抛出的错误那么你绝对不是一个人。这几乎是每个 Unity 项目在接入第三方安卓 SDK比如广告、支付、登录等并尝试自动化构建时都会踩到的一个“经典”大坑。问题通常不会在 Unity Editor 里直接打包时出现因为 Unity 的本地构建流程做了一些封装和兼容处理。但一旦切换到 Jenkins 这类 CI/CD 工具使用 Gradle 命令行进行更“纯净”的构建时Android Gradle Plugin (AGP) 和它内部的资源处理工具 AAPT2 就会严格执行规则各种隐藏在 AAR 文件里的兼容性问题就会集中爆发。这个错误的表象可能是AAPT2 aapt2-xxx-xxx.jar Daemon #0: Unexpected error during compile也可能是Android resource linking failed后面跟着一堆指向某个特定 AAR 文件中资源的错误信息。核心矛盾在于Unity 项目本身是一个复杂的混合体它既要管理自己的资源Assets又要集成外部的安卓库AAR/JAR而不同时期、不同供应商提供的 AAR其内部资源文件的命名、格式、甚至是 AndroidManifest.xml 的合并规则都可能与当前项目使用的 AGP 版本或构建环境产生冲突。Jenkins 环境往往更“干净”也更“严格”这就使得在本地能过的问题在服务器上原形毕露。解决这个问题的过程本质上是一个“构建环境标准化”和“依赖冲突排查”的侦探工作。我们需要确保 Jenkins 构建环境与本地开发环境的关键组件如 JDK、Android SDK、NDK、Gradle 版本一致并系统地检查和清理有问题的 AAR 依赖。接下来我会拆解整个排查和解决的思路并提供可直接操作的步骤。2. 核心问题拆解为什么在 Jenkins 上会出问题要解决问题首先得理解问题为什么发生。Unity 打包安卓尤其是涉及外部 AAR 时底层走的是 Gradle 构建流程。AAPT2Android Asset Packaging Tool 2是 AGP 中用于编译和链接资源的核心工具它比老版本的 AAPT 更严格、更高效但也更“挑剔”。2.1 AAPT2 的严格性体现在哪里资源命名冲突AAPT2 不允许在不同的资源目录包括不同的 AAR中存在同名的资源文件如drawable/icon.png除非它们在不同的配置限定符目录下如drawable-hdpi/icon.png和drawable-xhdpi/icon.png是允许的。一些“年久失修”或制作粗糙的第三方 SDK 的 AAR 包里可能会包含与 Unity 默认资源或其他 SDK 同名的通用资源。资源格式错误AAPT2 对资源文件的格式校验更严格。例如一个九宫格.9.png图片如果画错了拉伸区域在旧工具下可能被忽略或警告但 AAPT2 可能会直接报错导致构建失败。Manifest 合并冲突每个 AAR 都包含一个AndroidManifest.xml。在构建时所有 Manifest 文件需要合并成一个。如果多个 AAR 中定义了相同的组件如Activity、Service且未正确处理tools:replace或tools:node等属性AAPT2 在资源链接阶段就可能报错。编译 SDK 版本不匹配如果 AAR 库是用较高的compileSdkVersion编译的而你的项目使用了较低版本的 AGP 或compileSdkVersion可能会遇到一些无法识别的属性或资源类型导致 AAPT2 编译失败。2.2 Jenkins 环境与本地环境的差异环境纯净度你的本地机器可能安装了多个版本的 Android SDK 构建工具、多个版本的 Gradle环境变量可能指向某个特定版本。而 Jenkins 服务器通常是新配置的或者使用一个统一的、可能较新或较旧的版本。这种不一致是问题的首要来源。构建缓存本地构建成功过Gradle 和 AAPT2 会有缓存。这些缓存可能掩盖了一些潜在问题。Jenkins 构建通常是全新的每次拉取新代码清理构建缓存是空的所有问题都会暴露。路径与权限Jenkins 的工作空间路径可能包含空格、中文或特殊字符这有时会干扰命令行工具。另外文件读写权限也可能不同。2.3 Unity 的构建流程差异当你在 Unity Editor 中点击Build And Run时Unity 可能会使用它内置的、经过修改的 Gradle 包装器或一套更兼容的默认参数。而当你在 Jenkins 中执行Unity -batchmode -quit -executeMethod调用构建方法时Unity 同样是生成一个 Gradle 项目然后调用你系统环境或项目指定的 Gradle 来构建。如果 Jenkins 服务器上调用的是另一个版本的 Gradle 或 AGP结果就可能不同。3. 构建环境标准化与诊断准备在开始具体解决 AAPT2 错误前我们必须先统一和明确构建环境。这是所有后续操作的基础。3.1 锁定关键组件版本不要在 Jenkins 上使用“最新”或“默认”版本。必须与本地成功构建的环境保持一致。确定本地环境版本Unity 版本这是最基本的。JDK 版本Unity 对 JDK 版本有要求。通常 Unity Hub 安装时会附带一个 OpenJDK。记录下它的版本如openjdk version 11.0.15。强烈建议在 Jenkins 上也使用完全相同的 JDK 版本和发行版。Android SDK Build-Tools在 Unity 的Preferences - External Tools下可以看到 Android SDK 和 NDK 的路径。进入该路径下的build-tools目录看本地用的是哪个版本如30.0.3。NDK 版本也同样记录。Gradle 版本Unity 项目生成的 Gradle 项目会使用一个gradle-wrapper.properties文件。你可以在本地构建一次安卓包在输出的临时 Gradle 项目目录通常位于项目路径\Library\Bee\Android\GradleProject中找到这个文件查看里面的distributionUrl例如distributionUrlhttps\://services.gradle.org/distributions/gradle-6.1.1-all.zip。这个版本就是 Unity 当前版本默认或你项目配置使用的 Gradle 版本。在 Jenkins 上配置环境安装指定版本 JDK在 Jenkins 的全局工具配置中添加一个与你本地版本一致的 JDK 安装项。安装指定版本 Android SDK建议在 Jenkins 服务器上使用命令行工具sdkmanager来安装指定版本的 SDK Platform 和 Build-Tools。例如# 假设 ANDROID_HOME 已设置 $ANDROID_HOME/tools/bin/sdkmanager platforms;android-30 build-tools;30.0.3 ndk;21.4.7075529配置环境变量在 Jenkins 任务中或服务器全局设置ANDROID_HOME和ANDROID_NDK_HOME环境变量指向正确的路径。使用正确的 Gradle确保 Jenkins 任务配置中构建步骤里调用 Gradle 时使用的是 Wrapper (./gradlew) 或者指定了与你本地版本一致的 Gradle。最佳实践是使用 Gradle Wrapper这样版本定义在项目代码里环境统一。3.2 获取详细的错误日志AAPT2 的错误信息有时会被截断。我们需要获取最完整的日志。在 Unity 构建命令中增加日志级别在 Jenkins 的 Unity 构建命令后可以添加-logFile参数将日志输出到文件并配合-buildTarget等参数。Unity -batchmode -quit -projectPath /path/to/your/project -executeMethod YourBuildScript.BuildAndroid -logFile /path/to/unity_build.log定位 Gradle 构建日志Unity 构建日志可能只显示“构建失败”。真正的 AAPT2 错误在 Gradle 的日志里。Unity 构建失败后去临时 Gradle 项目目录如项目路径\Library\Bee\Android\GradleProject下运行./gradlew assembleDebug --stacktrace --info或./gradlew assembleRelease --stacktrace。将完整的控制台输出保存下来。分析日志关键信息在日志中搜索AAPT2、Android resource linking failed、error:、 Task :app:mergeDebugResources FAILED等关键字。错误信息通常会明确指出是哪个资源文件出了问题以及它在哪个 AAR 包里。注意有时错误信息会指向一个临时文件路径如/tmp/xxx/merged.dir/values/values.xml。你需要根据错误描述如重复的string/app_name和上下文反向推断是哪个 AAR 引入了这个资源。4. 系统性解决方案与实操步骤拿到详细错误日志后我们就可以针对性地解决问题了。以下是按照排查频率从高到低排列的解决方案。4.1 方案一升级或降级 Android Build Tools 与 Gradle 插件这是最常奏效的方法。AAPT2 的行为与com.android.tools.build:gradle即 AGP版本强相关。修改 Unity 项目中的mainTemplate.gradle Unity 2019.3 及以上版本支持自定义 Gradle 模板。在Assets/Plugins/Android目录下找到或创建mainTemplate.gradle文件。如果没有你可以从 Unity 安装目录的PlaybackEngines/AndroidPlayer下复制一个基础版本过来。调整classpath和buildToolsVersion 在mainTemplate.gradle的buildscript块中修改dependencies里的 AGP 版本。同时在android块中指定buildToolsVersion。buildscript { repositories { google() mavenCentral() } dependencies { // 尝试使用一个更稳定或更新的版本例如从 4.0.1 改为 4.2.2 或 7.0.0需对应 Gradle 版本 classpath com.android.tools.build:gradle:4.2.2 } } android { compileSdkVersion 30 // 确保与 Jenkins 服务器上安装的版本一致 buildToolsVersion 30.0.3 // ... 其他配置 }版本对应关系很重要AGP 7.0 需要 Gradle 7.0AGP 4.2.x 需要 Gradle 6.7.1。你需要同步调整gradle-wrapper.properties中的distributionUrl。高版本 Unity 通常已经适配了较新的 AGP。同步 Gradle Wrapper 修改gradle-wrapper.properties文件。Unity 允许你自定义此文件。在Assets/Plugins/Android目录下创建gradleTemplate.properties文件内容如下#Sat May 15 12:00:00 CST 2021 distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists # 修改这里的版本号与 AGP 匹配 distributionUrlhttps\://services.gradle.org/distributions/gradle-6.7.1-all.zip实操心得如果项目之前构建正常突然在 Jenkins 上失败且错误与资源相关优先尝试将 AGP 版本降级到一个更旧的、已知稳定的版本例如从 4.2.2 降到 4.0.1这往往能绕过一些新版本的严格检查。反之如果本地用的旧版本Jenkins 装了新版本则尝试在 Jenkins 上统一使用旧版本。4.2 方案二处理资源冲突与重复当错误明确指向某个重复的资源名时需要解决冲突。定位冲突的 AAR 根据错误日志找到是哪个资源重复了例如string/app_name。然后你需要找出所有包含该资源的 AAR 文件。AAR 本质上是一个 ZIP 包。你可以在 Jenkins 工作空间中或在本地使用脚本或手动查找。在 Linux/macOS 上grep -r app_name *.aar可能不直接需要先解压。可以写个简单脚本for aar in $(find . -name *.aar); do unzip -l $aar | grep values.xml echo 检查文件: $aar # 或者解压出来检查 unzip -q $aar -d /tmp/aar_temp if grep -r app_name /tmp/aar_temp/res/ 2/dev/null; then echo 冲突资源可能在: $aar fi rm -rf /tmp/aar_temp done在 Windows 上可以用 7-Zip 等工具手动打开 AAR查看res/values/values.xml等文件。解决冲突最佳情况冲突来自一个不重要的第三方 SDK并且该资源在你的应用中根本用不到。你可以通过修改该 AAR 包来移除或重命名冲突资源。注意直接修改第三方 SDK 的 AAR 包可能违反许可协议且会在下次更新 SDK 时被覆盖。这应作为临时排查手段或与 SDK 提供商沟通的依据。解压 AAR 文件。找到并编辑冲突的资源文件如res/values/strings.xml将冲突的字符串项删除或改名例如app_name改为sdk_app_name。重新打包成 AARjar cvf new.aar -C extracted_dir/ .。使用 Gradle 资源排除在mainTemplate.gradle中你可以尝试为特定的依赖项排除资源。但这并不总是有效尤其是对于 AAR。dependencies { implementation(fileTree(dir: libs, include: [*.jar, *.aar])) // 假设冲突来自一个叫 some-library 的模块 implementation(com.some:library:1.0.0) { exclude group: androidx.appcompat // 排除传递依赖 // 排除资源比较麻烦通常不是标准做法 } }使用tools:replace如果冲突发生在AndroidManifest.xml中的属性如android:label、android:icon可以在你项目的AndroidManifest.xml位于Assets/Plugins/Android中对应的组件声明里添加tools:replaceandroid:label,android:icon。确保你的 Manifest 根节点引入了tools命名空间manifest ... xmlns:toolshttp://schemas.android.com/tools。4.3 方案三禁用 AAPT2 的资源优化临时方案这是一个“猛药”能解决一部分因 AAPT2 严格检查而导致的、但资源本身可能并无实质错误的问题。注意这可能会略微增加 APK 大小并禁用一些资源优化功能仅作为诊断和临时解决方案。在mainTemplate.gradle文件的android块中添加以下配置android { // ... 其他配置 aaptOptions { // 禁用 AAPT2 对 PNG 图片的压缩优化有时能解决 .9.png 错误 cruncherEnabled false // 忽略资源重复警告将其视为错误反向操作先确保不是这个原因 // additionalParameters --warn-mode, nowarn // 更激进关闭 AAPT2使用旧的 AAPT不推荐长期可能有问题 // 但 AGP 3.0 后通常无法完全禁用 AAPT2。 } }更直接的方法是尝试降级或使用一个已知与你的 AAR 兼容的buildToolsVersion这比全局禁用优化更安全。4.4 方案四检查与清理 Unity 插件目录Unity 项目的Assets/Plugins/Android目录结构非常关键混乱的目录结构是许多问题的根源。规范目录结构Assets/Plugins/Android/放置所有安卓相关的库和资源。*.aar和*.jar文件可以直接放在这里或放在Assets/Plugins/Android/libs/子目录下。建议统一放在libs/下便于管理。AndroidManifest.xml应该只有一个主文件在此目录。其他来自 AAR 的 Manifest 会自动合并。res/、assets/等目录除非你明确需要覆盖或添加特定资源否则不要随意放置。第三方 AAR 自带的资源不需要你手动复制到这里。排查重复和过时的文件检查是否有同一个 SDK 的多个不同版本 AAR 文件。检查是否有手动放置的.so动态库文件与 AAR 中自带的重复。删除所有mainTemplate.gradle、gradleTemplate.properties、baseProjectTemplate.gradle等模板文件的备份或旧版本。只保留当前正在使用的那一份。使用*.androidlib目录 对于复杂的、包含资源和非代码资产的安卓库Unity 推荐使用.androidlib目录格式。将 AAR 解压后放入一个以.androidlib结尾的文件夹内并保持其内部标准安卓库结构包含AndroidManifest.xml、res/、libs/等。然后将整个.androidlib文件夹放入Assets/Plugins/Android/。Unity 会识别并正确处理这种格式有时比直接放 AAR 更少问题。5. Jenkins 任务配置要点与实战脚本环境问题和依赖问题解决后Jenkins 任务本身的配置也至关重要。5.1 关键构建步骤配置“执行 Shell” 或 “批处理命令” 步骤 在调用 Unity 构建命令前确保环境变量设置正确。最好在脚本中显式设置。#!/bin/bash # 设置环境变量 export JAVA_HOME/path/to/your/jdk11 export ANDROID_HOME/path/to/your/android-sdk export ANDROID_NDK_HOME/path/to/your/android-ndk-r21e export PATH$JAVA_HOME/bin:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools:$PATH # 切换到项目目录如果 Jenkins 工作空间不是项目根 # cd /var/lib/jenkins/workspace/your_project # 执行 Unity 构建 /path/to/Unity/Editor/Unity \ -batchmode \ -nographics \ -quit \ -projectPath $WORKSPACE \ -executeMethod BuildScript.BuildAndroid \ -logFile $WORKSPACE/build.log \ -buildTarget android构建后操作添加“归档构件”步骤将生成的 APK 文件例如**/*.apk归档。添加“控制台输出”扫描如果构建日志中出现FAILED、error:等关键字则标记构建为失败通过插件如Log Parser或Text Finder。5.2 使用 Gradle 直接构建进阶如果你已经通过mainTemplate.gradle高度自定义了构建流程也可以跳过 Unity 的-executeMethod直接在 Jenkins 中调用 Gradle 构建 Unity 导出的项目。这给了你更大的控制权。在 Jenkins 中先执行一个 Unity 导出 Gradle 项目的步骤使用-exportGradleProject参数但注意这个参数在某些 Unity 版本中行为可能不同更通用的做法还是用-executeMethod生成项目。然后添加一个“Invoke Gradle script”构建步骤指向导出的 Gradle 项目目录执行assembleRelease任务。这种方法的好处是你可以直接在 Jenkins 中运行./gradlew androidDependencies来可视化查看依赖树或者运行./gradlew clean来确保每次都是全新构建。6. 常见错误案例与排查实录这里列举几个我实际遇到过的典型 AAPT2 错误及解决方法。6.1 案例一AAPT: error: resource android:attr/lStar not found.错误分析lStar是 Android 12API 31引入的一个属性。这意味着某个 AAR 或你的项目编译目标 (compileSdkVersion) 设置为 31 或更高但构建环境中的android.jar来自 SDK Platform版本不匹配或者依赖的appcompat库版本过低。解决方案检查并确保 Jenkins 上安装了正确版本的 Android SDK Platform例如android-31。在mainTemplate.gradle中确保compileSdkVersion和targetSdkVersion与你安装的 SDK Platform 版本一致。升级androidx.appcompat:appcompat等支持库到较新版本如1.4.0这些库包含了新平台的资源定义。6.2 案例二9-patch image xx.9.png malformed.错误分析AAPT2 检测到某个.9.png图片的拉伸区域定义有问题。可能是图片本身画错了也可能是 AAPT2 版本变严格了。解决方案定位图片根据错误信息找到对应的 AAR 包和解压路径。修复图片使用 Android Studio 的draw9patch工具或在线工具重新编辑该.9.png文件确保黑边标记正确。临时绕过如果该图片并非必需或者可以不用九宫格格式可以尝试在aaptOptions中设置cruncherEnabled false来禁用 PNG 处理见方案三但这只是权宜之计。6.3 案例三Multiple resources with same name.错误分析两个或多个 AAR 包含了同名的资源如ic_launcher.png。解决方案使用 4.2 节的方法定位所有包含该资源的 AAR。评估哪个资源是真正需要的。通常第三方 SDK 自带的图标资源是可以被覆盖或忽略的。如果冲突资源在 AAR 的res/drawable/目录下可以尝试在你的项目Assets/Plugins/Android/res/drawable/下放置一个同名的图片Unity 打包时你的资源优先级可能更高有时能“覆盖”掉 AAR 里的但这取决于合并规则不一定总是有效。最根本的方法是联系 SDK 提供商要求他们使用更独特的资源名例如加前缀或者按照 4.2 节的方法修改 AAR。6.4 案例四构建成功但 Jenkins 控制台输出乱码或找不到aapt2可执行文件错误分析路径问题或权限问题。aapt2位于$ANDROID_HOME/build-tools/version/下。如果路径中有空格或中文或者 Jenkins 进程没有执行权限都会失败。解决方案确保ANDROID_HOME路径没有空格和中文。在 Jenkins 的 Shell 脚本中在 Unity 命令执行前添加chmod -R 755 $ANDROID_HOME/build-tools/*/aapt2来赋予执行权限如果 Jenkins 用户不是 SDK 的拥有者。检查 Jenkins 的系统编码确保与控制台输出编码一致通常为 UTF-8。7. 预防措施与最佳实践为了避免未来再次陷入 AAPT2 的泥潭建立以下规范至关重要。版本控制构建环境将mainTemplate.gradle、gradleTemplate.properties等构建配置文件纳入版本控制。在项目 README 中明确记录所需的 JDK、Android SDK Build-Tools、NDK 的精确版本。统一团队开发环境使用 Docker 容器或虚拟机镜像为团队和 Jenkins 服务器提供完全一致的构建环境。工具如Dockerfile可以精确描述环境。隔离第三方 SDK为每个第三方安卓 SDK 创建独立的.androidlib目录而不是简单地把 AAR 扔进libs。这有助于隔离资源并且在出现冲突时更容易定位和修复。定期更新与测试定期评估并升级 Unity 版本、AGP 版本和第三方 SDK。在升级后立即在干净的 Jenkins 环境中进行一次完整的构建测试而不是等到发布前。建立清晰的 Jenkins 流水线将构建步骤模块化例如① 环境检查与设置② 拉取代码与依赖③ Unity 导出项目④ Gradle 构建⑤ 产物归档与上传。每一步都有清晰的日志输出和错误处理。善用 Gradle 调试命令在 Jenkins 构建脚本中如果失败可以自动执行./gradlew androidDependencies或./gradlew build --scan来生成依赖报告这能极大帮助远程排查问题。处理 Unity Jenkins 安卓打包中的 AAPT2 错误是一个对耐心和细心的考验。它没有一成不变的银弹核心思路永远是通过详细日志定位根本原因通过统一环境消除不确定性通过规范管理预防未来问题。每次成功解决这类问题你对 Android 构建体系的理解就会更深一层这套复杂的工具链也会逐渐变得驯服。