uni-app Android UTS 扩展开发环境配置指南：Gradle、JDK 与 Android SDK 真机运行全解析

示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载uni-app 的 UTS 插件允许开发者使用 TypeScript 风格的 UTS 语言编写 Android 原生能力并在真机运行时通过 Gradle 拉取三方仓库依赖。本文以 docs/tutorial/uts-development-android.md 为主线系统讲解 Android UTS 扩展开发的运行环境配置Gradle、Gradle JDK、Android SDK、uts 开发扩展插件安装、Gradle 缓存机制并结合仓库内 Hello UTS 示例与 UTS 插件开发文档给出可复制的配置实操与源码级原理支撑。读完本文你将能够独立完成 Android UTS 插件的真机运行环境搭建并理解其底层编译链路。一、UTS 扩展开发与真机运行概述UTS 是 uni-app 的新型插件语言具备跨平台、高效率、易调试等优点。对于 Android 平台其核心机制如下依据 docs/plugin/uts-for-android.md编译时保存 UTS 源码文件时IDE 会同步将其编译为对应的 Kotlin 代码运行时真机运行或云打包时这些编译后的 Kotlin 源码会作为 APK 的一部分参与构建。HBuilderX 3.6.9 为 uts 插件 Android 平台新增了真机运行支持通过 Gradle 下载三方仓储的能力。也就是说当你的项目包含 uts 插件且插件声明了远程依赖时真机运行会触发 Gradle 构建并下载对应依赖。如果本机缺少 Gradle、JDK 或 Android SDK 环境运行时会直接提示配置运行环境。版本要求HBuilderX 3.6.91.1 编译链路与仓库证据从仓库自带的 Hello UTS 示例可以看到 UTS 插件的标准目录结构。例如 examples/hello-uts/uni_modules/uts-nativepage 插件uni_modules/uts-nativepage/ ├── changelog.md ├── package.json ├── readme.md └── utssdk/ └── app-android/ ├── config.json ├── AndroidManifest.xml ├── res/ ├── libs/ └── index.uts或对应源码其中utssdk/app-android目录是 Android 平台专属源码与配置所在地。插件中声明的config.json依赖会在真机运行时通过 Gradle 下载这正是本文所讲运行环境配置的用武之地。1.2 自动安装 uts 开发扩展插件当运行带有 uts 插件的项目到 Android 设备时HBuilderX 会自动安装【uts 开发扩展 - Android】插件该插件是 UTS 代码编译为 Kotlin、并在真机端执行的关键运行时组件请务必安装。若未安装或安装失败后续真机运行会中断并提示环境问题。二、环境配置运行配置入口位于【设置 - 运行配置】。HBuilderX 4.27 之前入口在【设置 - 插件配置】中。该界面集中展示了以下四类配置项| 配置项 | 用途 | 对应图标 | | :- | :- | :- | | Gradle | Android 库管理工具 | 图标 1下载/ 图标 2路径 | | Gradle JDK | 编译 Gradle 脚本所用的 JDK | 图标 3下载/ 图标 4路径 | | Android SDK | Android 平台构建工具与平台包 | 图标 5下载/ 图标 6路径 | | 示例效果 | mac / win 配置后效果 | uts-android-1 / uts-android-3 |2.1 配置 GradleGradle 是 Android 的库管理工具。如果电脑没有单独安装 GradleAndroid Studio 自带的 Gradle 版本通常太低不满足 UTS 插件构建要求按如下步骤下载点击下载入口进入 Gradle 官方下载页面下载完整发行包distribution将下载内容解压后找到bin目录下的执行脚本将脚本完整路径填入配置项| 平台 | 可执行脚本路径 | | :- | :- | | macOS |%解压路径%/bin/gradle| | Windows |%解压路径%\bin\gradle.bat|版本要求务必注意内置下载模板中 Android Gradle PluginAGP使用的最低版本为 7.4.0因此Gradle 最低版本要求 7.5 及以上Gradle 9.0.0 及以上版本暂不支持请勿配置过新的 Gradle否则可能因 AGP 兼容性问题导致构建失败。2.2 配置 Gradle JDK不同版本的 Gradle 依赖不同版本的 JDKHBuilderX 4.27 之前内置的 JDK 为11HBuilderX 4.27 内置的 JDK 为17Gradle 8.0 以上JDK 最低要求为 17。配置方式点击 JDK 下载入口进入下载页面选择与 HBuilderX 实际版本匹配的 JDK 版本。若本地已安装 JDK 可跳过此步骤若本地安装过 Android Studio其自带 JDK 路径一般在C:\Program Files\Android\Android Studio\jre将下载内容解压填入 JDK 路径mac 电脑找到 Home 目录Windows 为解压后的根目录。注意HBuilderX 4.02 支持此配置项Gradle 8.0 最低要求 JDK 版本为 17更多 Gradle/JDK 版本对应关系可参考 Android 官方发布记录。版本对应速查| Gradle 版本 | 最低 JDK | 适配说明 | | :- | :- | :- | | 7.5 ~ 7.x | JDK 114.27 前内置 | 满足 AGP 7.4.0 模板要求 | | 8.0 | JDK 174.27 内置 | 必须手动确认 JDK 版本避免构建报错 | | 9.0.0 | — |暂不支持|2.3 配置 Android SDK点击 SDK 下载入口进入 Android 官网提供两种形式二选一即可方式一下载 Android Studio根据平台下载并安装 Android Studio安装后必须启动一次 Android Studio其启动后会自动开始下载 Android SDK需要网络环境Android Studio 初始化完毕后一般可在如下目录找到 SDK 路径并填入配置| 平台 | 默认 SDK 路径 | | :- | :- | | macOS |/Users/用户名/Library/Android/sdk| | Windows |C:\Users\用户名\AppData\Local\Android\Sdk|方式二单独下载 Command line tools onlyAndroid Studio 体积较大空间不足时可考虑单独下载 Command line tools only根据平台下载 Command line tools only 压缩包解压后通过%解压目录%/bin/sdkmanager脚本安装 build-tools 和 platformssdkmanager --sdk_root%sdk路径% --install build-tools;30.0.0 sdkmanager --sdk_root%sdk路径% --install platforms;android-30将%sdk路径%填入 SDK 配置项sdkmanager 的详细用法参见官方命令行工具文档。注意下载 Android Studio 和下载 Command line tools only 选择一种方式下载 SDK 即可两种方式最终都只需要提供一个有效的 SDK 根目录。SDK 最低版本硬性要求此插件依赖 SDK 目录下build-tools 版本不低于 30.0.0此插件依赖 SDK 目录下platforms 版本不低于 android-30。2.4 配置示例与注意事项mac 与 Windows 系统配置完成后的效果可对照运行配置界面的示例图实际路径根据本地目录结构有所不同。通用注意事项如果环境已存在可以直接设置本地的工具包路径无需重新下载三个配置项Gradle、Gradle JDK、Android SDK缺一不可任一缺失都会导致 uts 插件真机运行时中断配置完成后建议清理一次 Gradle 缓存见下文再重新运行项目确保依赖完整拉取。三、Gradle 缓存机制项目依赖的三方仓储下载完成后会生成缓存如果缓存有效下次运行将直接跳过配置检测和下载过程从而显著缩短二次运行的等待时间。如需要让缓存主动失效可清理 Gradle 的缓存目录其正常存放于用户目录/.gradle/caches。实际排查构建问题时的常见操作删除~/.gradle/caches后重新运行项目HBuilderX 会重新检测环境并拉取依赖这有助于定位旧缓存损坏 / 依赖版本漂移类问题。四、依赖配置的底层支撑config.json 与三方仓库理解了运行环境为何需要 Gradle 之后再看 UTS 插件如何声明依赖。每个 UTS 插件在utssdk/app-android目录下通过config.json声明 Android 专属配置真机运行时这些依赖正是由上一节配置的 Gradle 下载的。4.1 config.json 字段说明以仓库内 examples/hello-uts/uni_modules/uts-tencentgeolocation/utssdk/app-android/config.json 为例{ abis: [ arm64-v8a ], dependencies: [ com.tencent.map.geolocation:TencentLocationSdk-openplatform:7.4.9 ], minSdkVersion: 21 }dependencies声明远程 Gradle 依赖坐标groupId:artifactId:version真机运行/云打包时由 Gradle 解析下载abis指定参与构建的 CPU 架构如arm64-v8aminSdkVersion指定插件最低支持的 Android 系统版本。再对比 examples/hello-uts/uni_modules/uts-nativepage/utssdk/app-android/config.json 与 examples/hello-uts/uni_modules/uts-getbatteryinfo/utssdk/app-android/config.json可以看到更精简的写法仅声明依赖、或仅声明minSdkVersion。4.2 远程依赖仓库支持范围目前云打包机支持以下远程仓库jcenter() google() // huawei maven {url https://developer.huawei.com/repo/} // jitpack 远程仓库 maven { url https://jitpack.io } // mavenCentral 默认支持 mavenCentral()部分场景下开发者可能需要将本地依赖上传到远程仓库以避免 wgt 提交资源过大超出打包限制此时推荐上传到 jitpack.ioAndroid 原生开发主流远程仓库。4.3 本地依赖与内置依赖jar/aar 本地依赖将 jar/aar 文件添加到utssdk/app-android/libs目录下即可使用so 文件HBuilderX 4.26 之前不支持直接在插件目录放 so 文件推荐封装为 AAR 或分别集成 so 与 jar 后自定义基座调试4.26 之后可通过混编 Kotlin 代码的方式集成 so 文件后打包自定义基座参与本地调试内置依赖HBuilderX 4.23 起内置了一批常用依赖如androidx.core:core-ktx、androidx.recyclerview:recyclerview、com.github.bumptech.glide:glide等uni-app x 与 uni-app 两套依赖清单详见 docs/plugin/uts-for-android.md。真机运行时无需重复添加这些依赖即可直接引用同时请勿再通过手动添加 jar/aar 方式引入相同依赖否则会因依赖冲突导致云打包失败。4.4 编译 SDK 版本说明截止 HBuilderX 4.15 版本uni-app x 项目本地 Android SDK 版本为 34uni-app 项目本地 Android SDK 版本为 31。开发者在调用系统 API 时需要注意版本兼容性使用高于目标 SDK 版本的新 API 前应做好版本判断。五、从环境到实践一个完整的 UTS 插件运行示例环境配置的最终目的是让 UTS 插件在真机上跑起来。以仓库文档 docs/plugin/uts-plugin.md 中的获取电量插件为例演示完整的插件开发与运行流程。5.1 编写插件源码在uni_modules目录下新建uts-getbatteryinfo插件在 Android 平台目录编辑index.uts// index.uts import Context from android.content.Context; import BatteryManager from android.os.BatteryManager; import { UTSAndroid } from io.dcloud.uts; export function getBatteryCapacity(): string { // 获取 android 系统 application 上下文 const context UTSAndroid.getAppContext(); if (context ! null) { const manager context.getSystemService( Context.BATTERY_SERVICE ) as BatteryManager; const currentLevel: number manager.getIntProperty( BatteryManager.BATTERY_PROPERTY_CAPACITY ); return currentLevel %; } return 0%; }该示例的关键点通过UTSAndroid.getAppContext()获取 Application 上下文对应 Android 平台Context.getApplicationContext直接 import Android 原生类android.content.Context、android.os.BatteryManagerHBuilderX 的代码提示系统支持在 uts 文件中提示 Android 原生 API真机运行时该插件的config.json若声明了依赖就需要本机 Gradle JDK SDK 环境就绪——这正是本文环境配置的核心价值。5.2 在页面中使用插件import { getBatteryCapacity } from /uni_modules/uts-getbatteryinfo; console.log(getBatteryCapacity())注意事项在 uvue/vue 文件中请勿直接导入插件内部utssdk目录下的 uts 文件例如/uni_modules/uts-api/app-android/index.uts在 JS 引擎下直接引入 uts 文件可能被错误编译为 JavaScript 进而导致编译异常应统一从插件入口如/uni_modules/uts-getbatteryinfo导入。5.3 调试支持运行与编译 uts 插件需要配置 Android本文与 iOS 环境开发 uts 插件时打断点调试是重要帮手可参考仓库内的调试文档 docs/tutorial/uni-uts-debug.md 与 docs/tutorial/uni-uts-debug-ios.md。六、常见环境问题排查清单结合 docs/plugin/uts-for-android.md 与 docs/uts/compiler-known-issues.md 中与运行环境相关的内容归纳如下排查思路提示存在三方依赖或资源引用请配置运行环境或云端打自定义基座说明插件声明了远程依赖但本机环境未就绪。处理方式有二按本文完成本机 Gradle/JDK/SDK 配置或提交云端打包自定义基座。相关提示可见 docs/uts/compiler-known-issues.md。Gradle 构建报 JDK 版本错误核对 HBuilderX 版本对应的内置 JDK4.27 前为 114.27 为 17并确认配置的 Gradle 版本所需的最低 JDK。依赖下载缓慢或失败确认网络环境可访问google()、mavenCentral()等远程仓库必要时清理用户目录/.gradle/caches缓存后重试。R 资源无法识别unresolved reference R检查资源是否符合 Android 原生格式并核对 R 资源引入的包名是否正确详见 docs/plugin/uts-for-android.md 常见问题章节。SDK 版本不满足确认 build-tools ≥ 30.0.0、platforms ≥ android-30且编译 SDK 与项目类型匹配uni-app x 为 34、uni-app 为 31。七、总结Android UTS 扩展开发的真机运行依赖一条完整的原生构建链路UTS 源码 → Kotlin 编译 → Gradle 依赖解析 → Android SDK 构建 → APK 运行。本文基于 docs/tutorial/uts-development-android.md 完整梳理了链路上的三个关键环境配置——Gradle≥7.5 且 9.0、Gradle JDKGradle 8 需 JDK 17、Android SDKbuild-tools ≥ 30.0.0、platforms ≥ android-30并解释了缓存机制与config.json依赖声明之间的关联。进一步深入可继续阅读仓库内相关文档docs/plugin/uts-for-android.mdUTS for Android 完整开发指南含数据类型差异、线程环境、内置库 UTSAndroid 等、docs/plugin/uts-plugin.mdUTS 插件开发全流程、docs/plugin/uts-plugin-hybrid.mdKotlin 混编并参考 examples/hello-uts/uni_modules 下的真实插件示例uts-nativepage、uts-tencentgeolocation、uts-getbatteryinfo 等动手实践。赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐BrowserAct Agent设计哲学CLI为什么应该为LLM设计紧凑文本、索引交互、语义记忆BrowserAct Agent设计哲学CLI为什么应该为LLM设计紧凑文本、索引交互、语义记忆 BrowserAct 是一款为 AI Agent 打造的示例工程前端移动开发跨平台OpenCV 4 Android 开发环境搭建全指南SDK/NDK 配置、官方示例运行与真机调试OpenCV 4 Android 开发环境搭建全指南SDK/NDK 配置、官方示例运行与真机调试 本指南面向希望在 Android 平台上使用 OpenCV计算机视觉图像处理深度学习机器学习uni-app UTS 插件 Android 开发实战从 UTS 语法到原生资源、依赖配置与 Kotlin 差异详解uni app UTS 插件 Android 开发实战从 UTS 语法到原生资源、依赖配置与 Kotlin 差异详解 本文为 Android 原生开发者的 U示例工程前端移动开发跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考