三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Android AAR包生成与使用全攻略：从模块化到Maven发布

发布时间：2026/8/15 21:59:27 三亩地 编程学习日记
Android AAR包生成与使用全攻略：从模块化到Maven发布

1. 项目概述：为什么我们需要aar包？

在Android开发中，我们经常需要将一些功能模块化，比如一个自定义的UI控件库、一个网络请求框架，或者一个封装了特定业务逻辑的SDK。直接复制粘贴代码显然不是好办法，不仅难以维护，也容易造成版本混乱。这时候，aar包就登场了。你可以把它理解为一个Android版本的“乐高积木块”，它包含了编译后的代码（classes.jar）、资源文件（res/）、清单文件（AndroidManifest.xml）以及可能的原生库（jni/）。相比于jar包，aar能打包Android特有的资源，是组件化、模块化开发的核心载体。

我见过不少团队，在项目初期图省事，直接采用模块依赖（module dependency），但随着项目膨胀，编译速度慢得让人抓狂。后来切换到aar依赖，不仅清晰了模块边界，还大幅提升了编译效率。对于提供第三方SDK的开发者来说，生成aar更是交付的标配。今天，我就结合自己踩过的坑，从头到尾捋一遍在Android Studio中生成aar和使用aar的完整流程，以及那些官方文档里不会写的细节。

2. aar包生成全流程与核心配置

生成aar听起来简单，点几下鼠标就行，但要想生成一个“靠谱”、能在各种环境下稳定工作的aar，里面的门道可不少。

2.1 基础环境与模块创建

首先，确保你的Android Studio是最新版，老版本在构建支持上可能会有一些奇怪的问题。我们从一个干净的工程开始。

  1. 创建Android Library模块：这是生成aar的源头。不要在你的主App模块里折腾。点击File -> New -> New Module，选择Android Library。我习惯以lib_开头命名，比如lib_mynetwork，这样在项目结构里一目了然。
  2. 模块结构审视：创建好后，打开这个Library模块的build.gradle.kts(或build.gradle)。你会看到第一行是plugins { id("com.android.library") }，这标志着它是一个库模块，而不是应用模块（id("com.android.application")）。这是最根本的区别。

2.2 build.gradle关键配置解析

库模块的构建配置决定了最终aar包的“质量”。下面是一个经过实战检验的配置示例，我会逐段解释：

plugins { id("com.android.library") id("org.jetbrains.kotlin.android") // 如果用Kotlin } android { namespace = "com.example.mynetwork" compileSdk = 34 defaultConfig { minSdk = 21 // targetSdk 在Library中通常不需要设置，由宿主App决定 testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" consumerProguardFiles("consumer-rules.pro") // 关键！混淆规则文件 } buildTypes { release { isMinifyEnabled = true // 开启代码混淆 proguardFiles( getDefaultProguardFile("proguard-android-optimize.txt"), "consumer-rules.pro" // 再次指定消费者混淆规则 ) } debug { isMinifyEnabled = false } } // 解决构建变体（Flavor）相关依赖问题 flavorDimensions += "environment" productFlavors { create("dev") { dimension = "environment" } create("prod") { dimension = "environment" } } // 关键配置：指定Java版本 compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } kotlinOptions { jvmTarget = "17" } // 可选：如果你需要打包额外的资源或排除某些文件 sourceSets { getByName("main") { // 可以在这里指定额外的资源目录 // res.srcDirs += "src/main/customRes" } } } dependencies { // 声明你的库所依赖的其他库 implementation("androidx.core:core-ktx:1.12.0") implementation("androidx.appcompat:appcompat:1.6.1") // 注意：谨慎使用 `api` 与 `implementation` // `api`：依赖会传递到使用你aar的宿主App // `implementation`：依赖只在本库内部使用，不会传递 api("com.squareup.retrofit2:retrofit:2.9.0") // 宿主App也需要Retrofit implementation("com.squareup.okhttp3:logging-interceptor:4.12.0") // 仅内部使用 }

配置要点与避坑指南：

  • consumerProguardFiles：这是最容易被忽略也最容易出问题的地方。你的库如果使用了混淆（isMinifyEnabled = true），必须通过这个属性提供一个consumer-rules.pro文件。这个文件里的规则不会用来混淆你的库代码，而是会合并到最终宿主App的混淆配置中，告诉宿主App：“在使用我的类和方法时，请保留它们，不要混淆掉。” 否则，宿主App开启混淆后，调用你的库方法可能会因为类名、方法名被改变而引发ClassNotFoundException或NoSuchMethodError。
  • 依赖传递性：务必理清api和implementation的区别。如果你希望宿主App无需再次声明就能使用你库所依赖的某个库（例如，你暴露了Retrofit的接口），就用api。如果某个依赖纯粹是你的库内部实现细节（例如一个日志工具），就用implementation，可以避免依赖冲突和增大宿主APK。
  • Java版本：统一设置sourceCompatibility、targetCompatibility和jvmTarget，避免因版本不一致导致的字节码问题。
  • 构建变体（Flavor）：如果你的库有不同的环境配置（如开发、生产），需要像上面一样配置productFlavors。这样生成的aar会包含对应的变体，例如mylibrary-dev-release.aar和mylibrary-prod-release.aar。

2.3 生成aar包的多种方式与产物定位

配置好后，就可以生成aar了。有几种常用方式：

  1. 通过Gradle任务面板（推荐给初学者）：在Android Studio右侧的Gradle面板中，找到你的Library模块，展开Tasks -> build，双击assemble或assembleRelease。assemble会生成所有变体（Debug/Release， 如果有Flavor则包括所有Flavor组合）的aar，而assembleRelease只生成Release版本。
  2. 通过命令行（适合CI/CD集成）：在项目根目录打开终端，执行：
    # 生成所有变体的aar ./gradlew :lib_mynetwork:assemble # 仅生成Release版本的aar ./gradlew :lib_mynetwork:assembleRelease # 生成特定Flavor的Release版本，例如prod ./gradlew :lib_mynetwork:assembleProdRelease
  3. 通过Build菜单：在Android Studio顶部菜单栏选择Build -> Make Module ‘lib_mynetwork’，这会触发编译，但不会直接打开输出目录。

生成的aar包在哪里？这是另一个常见问题。构建成功后，aar文件位于：你的Library模块目录/build/outputs/aar/例如：项目根目录/lib_mynetwork/build/outputs/aar/lib_mynetwork-release.aar

在这个目录下，你可能会看到多个aar，对应不同的构建变体。通常我们发布给第三方使用的是-release版本。

注意：在生成aar前，务必先执行一次Clean Project(Build -> Clean Project)。我遇到过多次因为缓存导致的新代码没有被打包进aar的情况，清理重建可以避免这类诡异问题。

3. aar包的多种使用方式详解

拿到了aar文件，接下来就是在其他项目中使用它。根据使用场景的不同，主要有三种引入方式。

3.1 方式一：本地文件依赖（最直接）

当你需要快速测试，或者aar包是团队内部共享但尚未发布到仓库时，这种方式最方便。

  1. 放置aar文件：在宿主App模块（或其他模块）内创建一个目录，习惯上叫libs（如果不存在就新建）。将你的xxx.aar文件复制进去。

  2. 修改build.gradle：打开宿主App模块的build.gradle.kts，在dependencies块中添加依赖。

    对于旧版Gradle（使用implementation files）：

    dependencies { implementation(files("libs/xxx.aar")) }

    对于新版Gradle（推荐使用implementation fileTree或更规范的flatDir）： 单纯使用files()在某些复杂构建场景下可能有问题。更健壮的做法是在项目根build.gradle.kts或settings.gradle.kts中声明仓库，或者在模块级配置：

    // 在模块的build.gradle中 repositories { flatDir { dirs("libs") // 指定libs目录为本地仓库 } } dependencies { implementation(name: "xxx", ext: "aar") // 注意这里没有版本号 // 或者使用 fileTree 引入目录下所有aar // implementation(fileTree("libs") { include("*.aar") }) }

    flatDir的方式让Gradle将libs目录视为一个特殊的本地Maven仓库，管理起来更清晰。

实操心得：

  • 使用flatDir时，name就是aar的文件名（不带后缀）。例如文件是lib_mynetwork-release.aar，则name为"lib_mynetwork-release"。
  • 强烈建议对aar文件进行版本命名，如mylibrary-1.0.0.aar，并在flatDir依赖时也体现版本，方便管理。
  • 这种方式最大的缺点是依赖不会传递。如果你的aar包（A）内部依赖了另一个库（B），并且你用api方式引入了B，那么宿主App在使用A时，仍然需要手动在dependencies中再次添加对B的依赖，否则会编译报错。这是本地文件依赖的固有局限。

3.2 方式二：发布到本地Maven仓库（团队协作推荐）

对于团队内部共享的通用组件，发布到本地Maven仓库是更专业的选择。它模拟了远程仓库的机制，可以处理传递性依赖，并且有版本管理。

  1. 配置发布脚本：在你的Library模块的build.gradle.kts文件末尾添加发布配置。
    // 应用Maven发布插件 apply(plugin = "maven-publish") // 配置发布任务 afterEvaluate { publishing { publications { create<MavenPublication>("release") { // 指定要发布的组件，这里是Android库的Release变体 from(components["release"]) // 配置Maven坐标（GroupId, ArtifactId, Version） groupId = "com.example" artifactId = "mynetwork" version = "1.0.0" } // 如果需要同时发布Debug版本，可以再创建一个‘debug’ publication } // 指定发布到的本地仓库目录 repositories { maven { url = uri("${project.rootDir}/local-repo") } } } }
  2. 执行发布任务：在Gradle任务面板中，找到你的Library模块下的publishing -> publishReleasePublicationToMavenRepository，双击执行。或者用命令行：
    ./gradlew :lib_mynetwork:publishReleasePublicationToMavenRepository
  3. 在宿主项目中引用：发布成功后，会在项目根目录生成一个local-repo文件夹，里面是按照Maven规范存放的aar、pom文件等。
    • 在项目根目录的settings.gradle.kts中声明这个本地仓库：
      dependencyResolutionManagement { repositories { mavenLocal() // 可选，指全局的 ~/.m2/repository maven { url = uri("${rootDir}/local-repo") } // 我们的项目本地仓库 google() mavenCentral() } }
    • 在宿主App模块的build.gradle.kts的dependencies中，像引用远程库一样引用：
      dependencies { implementation("com.example:mynetwork:1.0.0") }

优势：完美解决了传递性依赖问题。宿主App只需要声明对你的库的依赖，你的库所api的依赖会被自动传递和解析。版本管理清晰，非常适合团队内部分发。

3.3 方式三：发布到远程仓库（正式交付）

对于对外发布的SDK，或者公司内部的私有制品库（如Nexus、Artifactory），需要发布到远程Maven仓库。配置逻辑与本地Maven类似，主要区别在于repositories的配置。

publishing { publications { create<MavenPublication>("release") { from(components["release"]) groupId = "com.example" artifactId = "mynetwork" version = "1.0.0" // 可选：配置POM文件信息，如许可证、开发者信息等 pom { name.set("My Network Library") description.set("A fantastic network library for Android") url.set("http://www.example.com") licenses { license { name.set("The Apache License, Version 2.0") url.set("http://www.apache.org/licenses/LICENSE-2.0.txt") } } } } } repositories { maven { // 这里是你的私有Maven仓库地址 val releasesRepoUrl = uri("https://your.company.com/repository/maven-releases/") val snapshotsRepoUrl = uri("https://your.company.com/repository/maven-snapshots/") url = if (version.toString().endsWith("SNAPSHOT")) snapshotsRepoUrl else releasesRepoUrl // 通常需要认证信息 credentials { username = project.findProperty("mavenUser") as String? ?: "" password = project.findProperty("mavenPassword") as String? ?: "" } } } }

执行发布任务后，库就会被上传到远程仓库。其他开发者只需要在项目的repositories块中添加你的仓库地址，即可通过implementation("com.example:mynetwork:1.0.0")进行依赖。

4. 高级主题与深度避坑指南

掌握了基本操作，我们来看看那些容易让人栽跟头的高级问题和优化技巧。

4.1 资源冲突与资源ID固定

当你的aar包中包含资源（如图片、字符串、布局文件），并且宿主App也有同名的资源时，就会发生资源冲突。默认情况下，Android构建工具会优先使用宿主App的资源，这可能导致你的库UI显示异常。

解决方案1：资源前缀（推荐）在库模块的build.gradle.kts中强制为所有资源添加前缀：

android { ... resourcePrefix = "mylib_" // 自定义前缀，如 mylib_ }

设置后，你在库中新建的资源文件，其名称会被建议（或强制）加上mylib_前缀，例如mylib_icon.png、@string/mylib_hello。这从根源上避免了命名冲突。

解决方案2：谨慎选择资源名称即使不用前缀，也养成使用具有唯一性、描述性资源名的习惯，避免使用icon.png、title这种过于通用的名字。

资源ID固定（Resource ID Fixing）：这是一个更底层的问题。在AAPT2中，库模块的资源ID在每次编译时可能是不稳定的（非final）。这通常不是问题，因为最终打包APK时所有资源会被合并并分配最终的固定ID。但在一些动态加载、反射使用资源的极端场景下需要注意。通常我们不需要干预。

4.2 混淆与consumer-rules.pro的编写

混淆是发布Release版本aar的必备步骤，但配置不当就是灾难。前面提到了consumer-rules.pro，这里详细说说怎么写。

假设你的库有一个公开的API类MyNetworkClient，内部有一个实现类InternalHttpEngine。你的混淆规则应该：

  1. 保留所有公开的API：包括类、方法、字段。通常通过-keep规则实现。
  2. 允许混淆内部实现类：以减小体积。

一个典型的consumer-rules.pro文件内容如下：

# 保留我的库中所有公开的类、方法、字段。注意包名路径。 -keep class com.example.mynetwork.api.** { *; } # 或者更精确地保留某个类及其公有成员 -keep public class com.example.mynetwork.MyNetworkClient { public <methods>; public <fields>; } # 保留实现了某个接口的所有类（如果你使用了接口暴露功能） -keep class * implements com.example.mynetwork.RequestCallback { *; } # 保留带有特定注解的类和方法（例如@Keep注解） -keep @androidx.annotation.Keep class ** { *; } # 注意：不要在这里混淆第三方库，那是宿主App该操心的事。 # 但如果你用了反射调用第三方库，可能需要keep对应的部分。

关键点：consumer-rules.pro是给宿主App的混淆器看的规则。你库内部的混淆规则由库模块自己的proguard-rules.pro控制（通过proguardFiles配置）。两者职责分离。

4.3 多模块依赖与传递依赖管理

当你的项目结构复杂，库模块（A）本身还依赖另一个本地模块（B）或外部库时，管理起来需要技巧。

  • 依赖本地模块：在库A的build.gradle.kts中，使用project路径依赖。

    dependencies { implementation(project(":moduleB")) // 依赖同项目下的另一个模块 }

    当你发布A的aar时，B的内容默认不会打包进A的aar。A的pom文件会记录它对B的依赖。如果B也是你发布的库，那么宿主App需要同时依赖A和B（如果B是api依赖）或者由A的pom文件传递解决（如果发布到Maven仓库）。如果B是纯内部模块，这种结构可能不适合生成独立aar，考虑将A和B合并或重构。

  • 处理依赖冲突：当你的aar通过api依赖了Retrofit 2.9.0，而宿主App依赖了Retrofit 2.11.0，就会发生冲突。Gradle默认会选择最高版本（2.11.0），但这可能不兼容你的库。

    • 策略一（推荐）：在你的库中，将这类依赖声明为implementation，不传递，让宿主App自行决定版本。但这要求你的库接口不暴露第三方库的类型。
    • 策略二：使用resolutionStrategy在宿主App中强制指定某个库的版本。
    • 策略三：在库文档中明确声明兼容的依赖版本范围。

4.4 调试与源码关联（Source JAR）

直接依赖aar无法在Android Studio中点击跳转到库的源码，给调试带来困难。解决方法是为aar同时提供源码包（source JAR）。

在库模块的build.gradle.kts中，修改发布配置：

publishing { publications { create<MavenPublication>("release") { from(components["release"]) groupId = "com.example" artifactId = "mynetwork" version = "1.0.0" // 添加源码打包任务 artifact(sourceJar) } } } // 定义一个生成源码Jar的任务 val sourceJar by tasks.registering(Jar::class) { from(android.sourceSets["main"].java.srcDirs) archiveClassifier.set("sources") }

发布后，Maven仓库中会包含一个-sources.jar文件。当你在宿主项目中依赖这个库时，Android Studio会自动下载并关联源码，实现点击跳转。

5. 常见问题排查与实战技巧实录

即使按照指南操作，实际开发中还是会遇到各种奇怪的问题。这里记录一些高频问题的排查思路。

5.1 编译时常见错误与解决

问题1：Direct local .aar file dependencies are not supported when building an AAR.

  • 现象：当你尝试构建一个本身输出为aar的库模块（A），而该模块通过files()或flatDir依赖了另一个本地aar文件（B）时，会报此错误。
  • 原因：Android Gradle插件不支持在编译aar时直接引用本地aar文件作为依赖。
  • 解决方案：
    1. 最佳方案：将本地aar文件（B）发布到Maven仓库（本地或远程），然后通过implementation("com.example:B:1.0.0")方式依赖。
    2. 临时方案：如果B只是简单的jar包（无资源），可以将其重命名为.jar并依赖。如果是aar，可以解压aar，将其中的classes.jar作为jar依赖，并将其res等资源手动合并到模块A中（非常不推荐，维护成本高）。

问题2：宿主App编译报错，提示找不到aar中的类或资源。

  • 排查步骤：
    1. 检查依赖是否成功添加：在宿主App的build.gradle中确认依赖语句无误。执行./gradlew :app:dependencies查看依赖树，确认你的aar出现在列表中。
    2. 检查aar内容：用解压软件打开aar文件，查看classes.jar里是否包含你预期的类，res/目录下是否有资源文件。可能你的代码并没有被成功编译打包进去。
    3. 检查混淆规则：如果宿主App开启了混淆，请确认你的consumer-rules.pro文件是否正确配置并被打包。检查宿主App的混淆输出日志（通常在build/outputs/mapping/release/mapping.txt），看你的类是否被错误混淆了。
    4. 检查依赖传递：如果是本地文件依赖，确认aar的所有传递依赖是否已在宿主App中声明。

问题3：运行时崩溃，NoClassDefFoundError或NoSuchMethodError。

  • 原因：这通常是版本冲突或混淆问题的典型表现。
  • 排查：
    1. 执行./gradlew :app:dependencies --configuration releaseRuntimeClasspath查看所有运行时依赖的版本，检查是否有同一个库存在多个不同版本。
    2. 仔细检查混淆规则，确保所有需要暴露的公共API都被-keep了。

5.2 性能与优化建议

  • 最小化aar体积：
    • 启用代码混淆（minifyEnabled true）和资源压缩（shrinkResources true，注意库模块中此选项可能不直接生效，主要在App模块生效）。
    • 使用implementation而非api来减少传递依赖，让宿主App控制最终打包的库。
    • 移除未使用的资源，考虑将大图片放在CDN，库中只放置必要的小图标。
  • 加速构建：
    • 对于不常变化的稳定库，尽量使用远程Maven依赖而非项目模块依赖。Gradle会对远程依赖进行缓存。
    • 在开发阶段，如果库模块和宿主App在同一项目，可以使用compileOnly或debugImplementation依赖你的库模块，避免频繁构建aar。但发布前需切换回正式依赖方式测试。

5.3 版本管理与发布策略

  • 语义化版本（SemVer）：严格遵守主版本号.次版本号.修订号（MAJOR.MINOR.PATCH）的规则。PATCH增加表示向后兼容的问题修复；MINOR增加表示向后兼容的功能新增；MAJOR增加表示发生了不兼容的API变更。
  • 使用SNAPSHOT版本进行开发测试：在版本号后加上-SNAPSHOT（如1.0.0-SNAPSHOT），发布到快照仓库。Gradle每次构建会尝试检查并下载最新的快照版本，方便联调。
  • 文档与变更日志（Changelog）：每次发布新版本aar，务必更新文档和变更日志，明确列出新增、废弃、移除的功能以及重要的修复，这对你的协作者或第三方开发者至关重要。

生成和使用aar是Android开发者进阶的必备技能，它关乎代码的复用性、工程的解耦和团队的协作效率。从简单的本地文件依赖，到规范的Maven仓库发布，每一步都体现了工程化的思维。记住，一个好的aar包不仅仅是功能的集合，更是一份清晰的契约和一份用心的礼物。多花点时间在混淆规则、依赖管理和版本控制上，能为你和你的团队省去无数排查问题的时间。

编程学习 学习日记 实战经验
← 返回列表