零基础构建 Android AAR从 Kotlin 代码到 SDK 交付本文面向第一次接触 Android、Kotlin、Gradle 和 AAR 的开发者介绍如何从 Android Library 工程构建可供宿主 APP 集成的 AAR并说明如何使用通用 Codex skills 辅助 Python 算法迁移和 AAR 交付。配套 skills 仓库https://github.com/mhx15696651591/skill-aar仓库包含两个独立 skillpython-to-kotlin-android-porting辅助把 Python 算法、图像处理或推理流程迁移到 Kotlin/Android并验证行为一致性。android-aar-packaging辅助发现 Android Library 工程、构建 AAR、检查 ABI/资源/模型、计算校验值并完成交付。一、先用一句话理解整个流程Python 算法和模型 ↓ 迁移、适配、对照验证 Kotlin C/JNI 模型/资源 ↓ Gradle 构建 Android Library 正式 AAR ↓ 宿主 APP 集成验证 可交付 Android SDKPython 代码不会被 Android Studio 自动变成 Kotlin。模型文件也不会被翻译成 Kotlin模型通常以 ONNX 等格式作为资源放入 Android Library由 Kotlin 代码负责准备输入、调用运行时、解码结果和生成 SDK 输出。二、先认识几个名词名词简单理解是否是最终交付物Python 源码算法的参考实现可能依赖 NumPy、OpenCV、PyTorch 等通常不是 Android 交付物KotlinAndroid 端主要业务代码语言会编译进 AARC/JNIKotlin 调用的底层原生代码可能以.so进入 AARONNX/模型文件已训练好的模型参数和计算图可能放在 AAR 的assets/中GradleAndroid 的构建、依赖和打包系统负责生成 AAR/APKAndroid Library可以被其他 Android APP 引用的库模块AAR 的来源AARAndroid Library 的交付包SDK 集成的主要制品Sample APK演示或测试 SDK 的应用包不是 AAR最容易混淆的是 AAR 和 APKAAR 是给其他 APP 集成的库文件APK 是可以安装和运行的应用文件。AAR 不能像 APK 一样直接安装Sample APK 可以调用 AAR但不能替代 AAR 交付给宿主 APP。三、Android Library 的基本结构android-sdk-project/ ├── library/ Android Library最终生成 AAR │ └── src/main/ │ ├── java/ Kotlin/Java 源码 │ ├── cpp/ 可选的 C/JNI 源码 │ ├── assets/ 模型、标签和其他原始资源 │ └── res/ Android 资源 ├── sample/ 可选的演示/测试 APP生成 APK ├── gradle/ Gradle Wrapper 配置 ├── settings.gradle(.kts) 工程和模块声明 ├── build.gradle(.kts) 构建插件和公共配置 └── gradle.properties 构建参数和项目属性判断哪个模块生成 AAR重点看模块是否使用plugins{id(com.android.library)}使用com.android.library的模块通常是 Library使用com.android.application的模块通常是 APP/Sample。四、正式构建前要确认什么第一次构建不要急着点击 Build先确认打开的是整个 Gradle 工程根目录而不是某个子目录。哪个模块是 Android Library。正式 Variant 是哪个通常是release也可能带 flavor。正式设备支持哪些 ABI例如arm64-v8a、armeabi-v7a或项目配置的其他 ABI。是否包含 C/JNI、OpenCV、ONNX Runtime 或其他 native 依赖。模型和资源在哪里哪些文件必须进入 AAR。项目要求的 JDK、Android SDK、NDK、CMake 和 Gradle 版本。历史 AAR 存放在哪里当前输出是否会覆盖同名文件。优先使用项目已经配置并验证过的工具链不要因为电脑里存在更新版本就随意升级 JDK、Gradle、Android Gradle Plugin、NDK 或依赖。五、在 Android Studio 中构建 AAR方式一Gradle 工具窗口用 Android Studio 打开整个工程根目录。等待 Gradle Sync 完成。打开右侧Gradle工具窗口。找到目标 Library 模块展开Tasks → build。运行目标 Variant 的assembleRelease或项目明确要求的打包任务。等待底部 Build 窗口显示BUILD SUCCESSFUL。实际模块名和 Variant 必须以当前工程为准不要照抄其他项目的:library或:sdk。方式二Android Studio Terminal在工程根目录执行.\gradlew.bat :library-module:assembleRelease--no-daemon例如 Library 模块叫sdk时.\gradlew.bat :sdk:assembleRelease--no-daemon命令成功只说明 Gradle 任务完成仍需检查实际产物内容。正式构建和模拟器构建要分开模拟器测试构建可能和正式手机构建产生同名 AAR。不要仅凭文件名判断架构正式手机 AAR 使用项目默认的生产配置和设备 ABI模拟器 AAR 要明确标记为测试包构建后复制到单独目录不要让 x86/x86_64 构建覆盖或冒充 ARM 正式包最终要检查 AAR 内部的jni/目录。六、AAR 在哪里如何归档Gradle 默认输出类似project-root/library-module/build/outputs/aar/library-module-release.aar这是最近一次构建输出目录同名文件可能被下一次构建更新。正式交付时应复制到新的版本化目录例如project-root/releases/2026-10-14_v1.0.0/如果目标目录已有历史包不要覆盖它改用新的版本或构建标识。七、构建后如何检查 AAR1. 检查文件本身确认文件存在、大小不为 0、修改时间对应本次构建、路径与 Variant 一致并且不是其他 ABI 构建留下的旧文件。2. 查看 AAR 内部内容AAR 本质上是 ZIP 文件可以使用 JDK 的jar查看 jdk-path\bin\jar.exe tf path-to-aar通常检查classes.jar AndroidManifest.xml res/ assets/ jni/expected-abi/*.so是否需要模型、JNI 或特定资源要以当前工程配置为准。没有 native 代码的项目不应强行要求jni/没有模型的项目也不应强行要求模型文件。3. 检查 ABI、模型和依赖对于包含 native 代码的 AAR检查jni/下是否存在项目要求的.so和 ABI。对于包含模型的 SDK检查模型是否进入 AAR名称、版本和路径是否符合 Kotlin 的加载逻辑。同时确认依赖是已经打入 AAR、由宿主 APP 声明还是仅供 Sample 使用。不要把 Sample 专用依赖误当成正式 SDK 依赖。4. 计算 SHA-256Get-FileHashpath-to-aar-Algorithm SHA256复制到归档目录后对归档副本再计算一次。两个 SHA-256 必须一致才能证明归档过程中没有改变文件。八、Sample APK、模拟器和真机分别代表什么验证状态说明能证明什么AAR 构建成功Gradle 产生了 AAR指定任务完成AAR 内容已检查检查 archive、资源、JNI、模型和 SHA-256交付文件结构符合预期Sample 编译成功Sample APK 构建完成Demo 工程可以编译模拟器验证在指定模拟器上运行指定模拟器 ABI 和路径可运行ARM 真机验证在目标 ARM 设备上运行目标 native 设备路径得到验证这些状态不能互相替代。BUILD SUCCESSFUL不等于 Sample 已运行Sample 启动不等于所有算法结果正确x86_64 模拟器运行不等于 ARM native 路径已验证编译通过不等于 Python 和 Kotlin 数值一致。九、Python 算法如何迁移到 KotlinPython 转 Kotlin 不是按语法逐行替换。通常需要找到 Python 入口、调用关系和配置。明确输入输出、shape、dtype、值域、坐标系、通道顺序和异常行为。确认 NumPy、OpenCV、模型运行时等依赖能否在 Android 使用。设计 Kotlin 数据类、数组、Bitmap/Mat/ByteBuffer 和公开 API。按预处理、核心算法、模型推理、后处理、结果映射的顺序迁移。用相同输入比较 Python 和 Kotlin 的中间结果与最终结果。对浮点、图像、mask、坐标和排序差异设定合理容差。在 Android 的 JVM、模拟器或真机环境中继续验证。常见差异来源包括 RGB/BGR 通道顺序、uint8与 KotlinByte的差异、浮点精度、NumPy 广播、Resize 插值、坐标边界、空 mask、模型布局和 Python 动态类型。十、两个通用 Codex skills 怎么帮忙python-to-kotlin-android-porting适合分析 Python 入口和依赖、映射 NumPy/OpenCV/模型推理流程、设计 Kotlin 数据类型和 SDK API、添加 Python/Kotlin 对齐测试以及记录语义差异和性能风险。调用示例Use $python-to-kotlin-android-porting to port this Python algorithm to the Android Library module. First inspect the Python entry point, data contract, dependencies, and target Kotlin module. Then implement the migration, add focused tests, and compare Kotlin results with the Python reference. Report numerical tolerances, known differences, and skipped checks.它不承诺把任意 Python 项目“一键自动转换”。遇到服务端代码、训练代码、动态反射、Android 不支持的科学计算库或无法复现的运行时行为时应明确报告风险。android-aar-packaging适合寻找 Library module 和正式 Variant、使用项目已有工具链构建 AAR、区分正式设备包/模拟器测试包/Sample APK、检查 classes/资源/模型/JNI/ABI、计算 SHA-256、建立不可覆盖的归档并分别报告各类验证状态。调用示例Use $android-aar-packaging to build and verify the formal release AAR for this Android Library. First inspect the project structure, Library module, Variant, ABI configuration, native dependencies, assets, and output directories. Use the existing Gradle wrapper and toolchain. Do not use emulator-only ABI flags or overwrite historical archives. After building, inspect the exact AAR, calculate SHA-256, and report build, test, Sample, emulator, and physical-device status separately.两个 skill 如何配合First use $python-to-kotlin-android-porting to migrate the requested Python algorithm and validate Python/Kotlin parity. Then use $android-aar-packaging to build and verify the resulting Android Library AAR. Keep migration status and AAR packaging status in separate sections.两个 skill 可以独立使用已有 Kotlin Library 只需打包时不需要启动转写 skill只做算法迁移时也不需要立即构建 AAR。十一、推荐的交付报告模板源码工程 Library module Variant/flavor 正式 ABI Gradle/JDK/NDK/toolchain Canonical AAR Immutable handoff AAR 文件大小 构建时间 SHA-256 Archive 检查通过/失败/跳过 模型和资源检查通过/失败/不适用 JNI/ABI 检查通过/失败/不适用 Library 单元测试通过/失败/跳过及原因 Sample APK已构建/未构建 模拟器运行已验证/未验证 真机运行已验证/未验证 已知限制 宿主 APP 还需要做的事情不要只写“打包成功”。“构建成功”“内容检查通过”“Sample 运行过”“模拟器运行过”“ARM 真机运行过”是五个不同结论。十二、常见问题为什么点击 Build 后没有找到 AAR可能运行的是Make Project、Sample APK 任务或其他 Variant。请明确运行 Library 模块的assembleRelease再到该模块的build/outputs/aar/检查。Gradle Sync 成功是不是代表 AAR 已生成不是。Sync 只是在读取和解析工程配置、插件和依赖AAR 需要单独执行打包任务。AAR 和 APK 哪个交给宿主 APP通常交付 AAR。APK 只用于运行 Sample 或测试 APP。为什么不能只看 AAR 文件名判断 ABI不同 ABI 配置可能生成同一个文件名必须查看 AAR 内部的jni/目录或根据项目配置和构建记录判断。为什么 Kotlin 编译通过还要做 parity testing编译器只能证明 Kotlin 代码类型和语法正确不能证明它和 Python 在像素、坐标、阈值、面积、模型输入或结果字段上完全一致。十三、最后检查清单构建前打开的是完整 Gradle 工程根目录。找到了正确的 Android Library module。确认了正式 Variant 和 ABI。确认了 JDK、SDK、NDK、CMake 和依赖版本。检查了 JNI、模型、资源和输出目录。确认不会覆盖历史交付物。构建后AAR 文件存在且非空。修改时间对应本次构建。classes.jar和 Manifest 存在。模型、资源和 JNI 内容符合当前工程配置。ABI 与正式设备目标一致。SHA-256 已记录。归档副本与 canonical AAR 的 SHA-256 一致。交付时说明了 Library module、Variant 和 ABI。分别说明了测试、Sample、模拟器和真机状态。说明了 Python/Kotlin parity 是否验证。附上宿主 APP 集成所需文档和依赖要求。列出了已知限制和接入方还需完成的事项。相关链接Skills 仓库https://github.com/mhx15696651591/skill-aarAAR 构建 skillandroid-aar-packagingPython 转 Kotlin skillpython-to-kotlin-android-porting