uni-app x 原生联调 Android 全指南：自定义基座与源码级联编联调

uni-app x 原生联调 Android 全指南自定义基座与源码级联编联调【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-app x 项目的业务代码uvue/uts运行在 HBuilderX 中而宿主原生应用Kotlin/Java运行在 Android Studio 中两者在混合开发场景下经常需要联动调试。本文以 uni-app x 的 Android 原生联调为主题系统讲解从宿主工程配置、依赖引入到「自定义基座」与「源码级联编联调」两种方案的具体操作并辅以仓库源码与配置佐证帮助开发者快速建立跨 IDE 的联调工作流。联调的本质uts 编译为 Kotlin在开始配置之前先理解 uni-app x 与 Android 原生工程能够混编联调的底层原因uni-app x 的 uts 语言在 Android 平台上的编译产物就是 Kotlin。因此 uni-app x 项目与宿主原生应用可以编译进同一个 APK实现真正的“混编运行、联调 debug”而不是像传统跨平台框架那样只能通过桥接协议与原生代码间接通信。这一点在仓库源码中可以得到印证uni-app x 的各个内置模块在 Android 平台的实现均以.kt源码形式存放在utssdk/app-android目录下例如 uni-web-view 模块的 Android 实现、uni-textarea 的 Android 实现 等它们本质上就是由 uts 编译得到的 Kotlin 代码与开发者手写的 Kotlin 代码混编在一起。基于这一能力Android 端原生联调共有两种方案方案 1HBuilderX 4.71 之前把宿主原生应用打包为 HBuilderX 的“自定义基座”。需要先把宿主应用打包为带有 uni-app x 调试模块的 APK再运行 uni-app x 项目。此方案无法动态修改宿主应用的原生代码。方案 2HBuilderX 4.71支持把宿主原生工程直接拖入 HBuilderX与 uni-app x 项目进行源码级联编联调可对 kt/java 代码打断点、单步跟踪。无论选择方案 1 还是方案 2第一步都是先对宿主原生应用Android Studio 工程进行配置。一、Android Studio 项目配置对宿主原生项目配置的目的是加入 uni-app x 的调试模块并声明该调试模块所需的第三方依赖。配置对象是 Android Studio 中的宿主原生工程。1. 引入 debug-server-release.aar下载 uni-app x 原生 SDK 后将debug-server-release.aar拷贝到原生项目的libs目录下。该 AAR 即 uni-app x 的调试服务器模块负责在宿主应用中承载 HBuilderX 与真机之间的日志传输、热重载和断点调试服务。2. 在 app 模块的 build.gradle 中添加依赖dependencies { implementation com.squareup.okhttp3:okhttp:3.12.12 implementation net.lingala.zip4j:zip4j:2.11.5 implementation com.squareup.leakcanary:leakcanary-android:2.14 }这三项依赖分别服务于调试模块的 HTTP 通信OkHttp、资源/代码包的解压与传输Zip4j以及内存泄漏检测LeakCanary均为 uni-app x 调试模块运行所必需的传递依赖缺一不可。3. 修改 AndroidManifest.xml在application节点下添加调试开关meta-data android:nameDCLOUD_DEBUG android:valuetrue/添加网络权限uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE /DCLOUD_DEBUG为 true 时宿主应用启动即会加载 uni-app x 调试框架等待 HBuilderX 连接网络权限则保证真机与 HBuilderX 之间的调试通道可以建立。4. 配置注意事项如果原生项目的drawable目录下不存在名称为icon的图片需要临时补充一个命名为icon的文件否则可能影响调试基座的安装与识别。当build.gradle中的targetSdk为 34 时在 Android 14 设备上资源同步会失败。建议将targetSdk调整到 30 至 33 之间。当前模块仅为调试使用发行版本必须删除上述配置。如果发行版本显示正在加载调试框架...或Loading debugging framework...说明调试模块配置未清理干净请删除上面的调试模块配置后重新打包。二、方案 1打包为 HBuilderX 自定义基座思路把宿主原生工程打包为 APK成为 HBuilderX 的“自定义基座”然后在 HBuilderX 中运行 uni-app x 时选择该自定义基座运行到手机上。关于运行基座、标准基座、自定义基座的概念可参考仓库内文档 运行到真机或模拟器。简单来说标准基座是 DCloud 提供的调试用 Appuni-app x 标准基座包名为io.dcloud.uniappx只能热更代码与资源而自定义基座是在标准基座能力之上把包名、证书、权限、三方 SDK、原生模块等一并打进去的定制调试包适合需要调试原生能力、或标准基座无法覆盖的场景。1. 原生工程生成自定义基座打开原生工程的build.gradle文件修改versionCode和versionName字段versionCode为应用的版本号整数值用于各应用市场的升级判断需要与 uni-app x 项目的manifest.json中versionCode值一致versionName为应用的版本名称字符串在系统应用管理程序中显示需要与 uni-app x 项目的manifest.json中versionName值一致。版本号的一致性很关键它是 HBuilderX 判断“基座 App 与 uni-app x 项目是否配套”的依据之一。以仓库自带的 src/manifest.json 为例其versionName为2.0.1、versionCode为20001若以它作为 uni-app x 项目则宿主工程的versionCode应设为20001、versionName应设为2.0.1。关于这两个字段的完整语义可参见 manifest.json 配置文档 中对versionName应用版本名称与versionCode应用版本号整数取值范围 1~2147483647升级时必须高于上一次设置的值的说明。点击 Android Studio 的Build - Generate Signed Bundle/APK...生成安装包。注意自定义基座不支持 aab 包必须生成 APK 格式。2. 将自定义基座添加到 uni-app x 项目将生成的 APK 文件重命名为android_debug.apkVDOM 模式或android_debug_vapor.apk蒸汽模式。Vapor 模式是 uni-app x 的新一代渲染架构关于 VDOM 与 Vapor 两种模式的差异可参考 Vapor 模式说明将 APK 拷贝到 uni-app x 项目的unpackage/debug目录下该目录正是 HBuilderX 约定存放调试基座的目录参见 运行到真机或模拟器点击 HBuilderX 的运行按钮 - 运行到 Android App 基座勾选“使用自定义基座运行”。运行成功后在手机自定义基座中打开 uni-app x 应用HBuilderX 控制台即可看到运行 log。此后在 HBuilderX 中修改 uni-app x 代码手机端基座会热刷新生效。此方案的局限宿主应用的原生代码在打包后已固化无法动态修改调试因此适合“原生侧基本稳定、主要迭代 uni-app x 侧代码”的场景。三、方案 2原生工程源码级联编联调HBuilderX 4.71适用版本HBuilderX 4.71 及以上。注意需要将 HBuilderX 和 uni-app x SDK 都升级到 4.71 或以上版本。此方案不再要求把宿主工程打包成固定基座而是让宿主原生工程与 uni-app x 项目在 HBuilderX 中直接“源码级联编”宿主原生代码可以随时修改、打断点、单步调试是最接近一体化开发体验的联调方式。1. 运行前置操作在完成前述“Android Studio 项目配置”后直接通过 Android Studio 将宿主应用运行到手机上。然后切换到 HBuilderX点击运行按钮 - 运行到 Android App 基座勾选“使用自定义基座运行” - “已安装的基座”。调试的包名与原生工程的build.gradle中applicationId字段一致因为本次运行安装到手机上的就是宿主工程本身。在 HBuilderX 中选择正确的包名点击运行即可。2. 编译、热重载与日志选择包名并点击运行后uni-app x 项目将开始编译并热重载到手机上的原生应用中。运行成功后HBuilderX 控制台可以看到 uni-app x 应用的日志点击日志可以跳转到对应的 uvue/uts 源码位置修改 uni-app x 代码后手机端会热重载更新无需重新安装 App点击控制台右上角的红色“虫子”按钮开启 debug即可对 uni-app x 应用进行断点调试。uni-app x 断点调试的具体操作方法可参考 uni-app x uts 调试。3. 配置关联项目调试原生 kt/java 代码如果需要调试原生工程kt/java 代码需要配置运行面板中的“关联项目”关联项目的路径为原生工程的根目录并将原生工程拖入 HBuilderX 中即在 HBuilderX 项目管理器中同时打开 uni-app x 项目与原生工程配置成功后重新运行 uni-app x 项目。然后在需要调试的 kt/java 代码行号上右键设置断点开启uts 调试。断点设置成功后触发相应逻辑即可进入调试模式。由于 uni-app x 的 uts 编译产物即为 KotlinHBuilderX 在调试原生工程时本质上是在调试“与 uni-app x 混编在一起的 Kotlin 代码”断点可以落在宿主工程的任意 kt/java 文件上。4. 跨工程双向断点跟踪在 HBuilderX 中可以在原生工程和 uni-app x 项目中各自打断点并在原生的 kt/java 与 uni-app x 代码的断点之间来回单步跟踪。例如在 uvue 页面逻辑处打一个断点观察业务状态进入原生 SDK 调用后在 kt 实现中再打断点逐行确认跨层调用的数据流从而高效排查联调问题。这种“一个调试器贯穿两层代码”的能力正是得益于 uts 与原生语言同源编译。5. 联调 Tips如果在 HBuilderX 中改动了原生工程的 kt/java 文件需要在 Android Studio 中重新运行项目才会生效HBuilderX 仅负责调试不负责编译原生代码关联项目的路径应为原生工程的根目录否则 HBuilderX 设置在 kt/java 文件上的断点可能不会生效不要在 Android Studio 和 HBuilderX 中同时开启调试服务否则会导致 Android Studio/HBuilderX 的调试服务无法正常启动调试原生工程时在 Android Studio 中重新运行项目后需要在 HBuilderX 中重新开启调试服务HBuilderX 对 kt/java 代码只有基本的高亮和格式化没有语言服务。编写原生代码仍然应在 Android Studio 中进行两个 IDE 同时打开、协作使用Android Studio 负责原生代码的编写与编译运行HBuilderX 负责 uni-app x 代码的编写、热重载与整体调试。四、两种方案对比与选型建议维度方案 1自定义基座方案 2源码级联编联调4.71前置工作打包带调试模块的 APK 并重命名、拷贝到unpackage/debug宿主工程完成配置后Android Studio 直接运行到手机原生代码可修改性不可打包后固化可改动后 Android Studio 重跑生效原生代码断点调试不支持支持需配置关联项目、拖入原生工程热重载 uni-app x 代码支持支持适用场景原生侧已稳定主要迭代 uni-app x 业务原生与 uni-app x 并行开发、深度联调排障选择建议如果宿主原生功能已趋于稳定、当前主要工作是迭代 uni-app x 业务方案 1 的“打包一次、持续热刷”足够高效如果正处于原生模块与 uni-app x 业务并行开发的阶段需要频繁跨层排查问题则应升级到 HBuilderX 4.71采用方案 2 获得源码级联编联调能力。五、常见问题排查发行版出现“正在加载调试框架...”提示说明调试模块配置DCLOUD_DEBUGmeta-data、AAR 依赖未从发行包中移除请删除 Android Studio 项目配置 中的全部调试配置后重新打包。Android 14 设备资源同步失败将targetSdk调整到 30 至 33 之间避开 34 的兼容性问题。基座安装失败检查drawable目录下是否存在名为icon的图片资源。原生断点不生效确认“关联项目”路径指向原生工程根目录且原生工程已拖入 HBuilderX改动原生代码后需在 Android Studio 重新运行。调试服务无法启动确认 Android Studio 与 HBuilderX 没有同时开启调试服务。综合来看Android 端原生联调的两条路径覆盖了“稳定期迭代”与“并行开发排障”两种典型场景配合 uts 编译为 Kotlin 的底层能力uni-app x 在 Android 平台上真正实现了 uni-app x 业务代码与宿主原生代码的同工程、同调试器联调这为涉及原生能力的混合应用开发提供了完整的工程化支撑。iOS 与鸿蒙平台的原生联调思路与此类似可分别参考 iOS 原生联调 与 鸿蒙原生联调。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考