企业官网建设流程全解析

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

【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app

uni-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 端原生联调共有两种方案：

1. 方案 1（HBuilderX 4.71 之前）：把宿主原生应用打包为 HBuilderX 的“自定义基座”。需要先把宿主应用打包为带有 uni-app x 调试模块的 APK，再运行 uni-app x 项目。此方案无法动态修改宿主应用的原生代码。
2. 方案 2（HBuilderX 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:name="DCLOUD_DEBUG" android:value="true"/>

添加网络权限：

<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.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 提供的调试用 App（uni-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.apk（VDOM 模式）或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 编译产物即为 Kotlin，HBuilderX 在调试原生工程时，本质上是在调试“与 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 代码的编写、热重载与整体调试。

四、两种方案对比与选型建议

选择建议：如果宿主原生功能已趋于稳定、当前主要工作是迭代 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