【uni-app-x Android ( sdk5.26)原生打包教程】

uni-app-x Android ( sdk5.26)原生打包文档

项目概述

将 HBuilderX 编译生成的 uni-app-x Android 资源（app-android 目录）整合到 Android 原生项目（uniappxnativepackage）中，通过 Gradle 打包生成 APK。

目录结构

Android-uni-app-x-SDK@15075-5.26/
├── app-android/                      # HBuilderX 编译产物（待整合）
│   ├── uniappx/
│   │   └── app-android/src/          # 编译后的 Kotlin 源码
│   │       ├── index.kt              # 主入口
│   │       ├── components/           # 组件
│   │       ├── pages/                # 页面
│   │       └── uni_modules/          # uni_modules 编译产物
│   ├── uni_modules/                  # 原生插件源码
│   │   ├── cool-open-web/utssdk/app-android/
│   │   └── cool-vibrate/utssdk/app-android/
│   └── __UNI__3BDBF22/               # App 资源
│       └── www/
│           ├── manifest.json
│           └── static/
├── SDK/                              # uni-app-x SDK（aar 库）
│   └── libs/
├── uniappxnativepackage/             # Android 原生项目
│   ├── app/                          # 主应用模块
│   ├── uniappx/                      # uni-app-x 业务模块（整合目标）
│   ├── settings.gradle
│   ├── build.gradle
│   ├── gradle.properties
│   └── local.properties              # Android SDK 路径配置
└── plugins/                          # UTS 编译器插件

整合步骤

1. 清理旧资源

删除 uniappx 模块中原有的 demo 源码和资源：

# 清理旧 Kotlin 源码
uniappx/src/main/java/index.kt
uniappx/src/main/java/components/
uniappx/src/main/java/pages/
uniappx/src/main/java/uni_modules/
uniappx/src/main/java/node-modules/
uniappx/src/main/java/uniCloud/

# 清理旧 App 资源
uniappx/src/main/assets/apps/__UNI__HelloUniAppX/

2. 复制 Kotlin 源码

将编译后的页面和组件源码复制到 uniappx 模块：

源：app-android/uniappx/app-android/src/*
目标：uniappxnativepackage/uniappx/src/main/java/

包含文件：

• index.kt --- 应用主入口和全局类型定义
• components/ --- 自定义组件（tabbar、locale-set 等）
• pages/ --- 页面 Kotlin 源码
• uni_modules/cool-ui/ --- cool-ui 组件库编译产物

3. 复制 UTS 原生插件源码

将 uni_modules 中的原生插件源码复制到 uniappx 模块：

源：app-android/uni_modules/cool-open-web/utssdk/app-android/src/*
目标：uniappx/src/main/java/uni_modules/cool-open-web/

源：app-android/uni_modules/cool-vibrate/utssdk/app-android/src/*
目标：uniappx/src/main/java/uni_modules/cool-vibrate/

4. 复制 App 资源

将应用资源（manifest、静态文件等）复制到 assets 目录：

源：app-android/__UNI__3BDBF22/
目标：uniappx/src/main/assets/apps/__UNI__3BDBF22/

5. 更新 AndroidManifest

修改 uniappx/src/main/AndroidManifest.xml：

• 更新 DCLOUD_UNI_APPID 为 __UNI__3BDBF22

修改 app/src/main/AndroidManifest.xml：

• 添加 VIBRATE 权限（cool-vibrate 插件需要）

<uses-permission android:name="android.permission.VIBRATE" />

6. 补充缺失的样式资源

由于 uniappx 模块对 SDK aar 使用 compileOnly 依赖，资源在库验证阶段不可用。需在 uniappx 模块中补充样式定义：

创建 uniappx/src/main/res/values/styles.xml：

<resources>
    <style name="UniAppX.Activity.DefaultTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
        <item name="android:colorControlActivated">#2196F3</item>
        <item name="android:statusBarColor">@android:color/transparent</item>
    </style>
    <style name="UniAppX.Activity.DefaultTheme_Transparent" parent="Theme.AppCompat.DayNight.NoActionBar">
        <item name="android:colorControlActivated">#2196F3</item>
        <item name="android:statusBarColor">@android:color/transparent</item>
        <item name="android:windowIsTranslucent">true</item>
        <item name="android:windowBackground">@android:color/transparent</item>
    </style>
    <style name="UniAppX.Activity.DialogTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
        <item name="android:colorControlActivated">#2196F3</item>
        <item name="android:statusBarColor">@android:color/transparent</item>
        <item name="android:windowNoTitle">true</item>
        <item name="android:windowIsTranslucent">true</item>
        <item name="android:windowBackground">@android:color/transparent</item>
    </style>
</resources>

7. 修复 Kotlin 编译错误

tenant-register.kt 中 sectionOpen[key] 返回 Any? 类型，需要显式转换为 Boolean：

// 修复前
val current: Boolean = if (sectionOpen[key]) {

// 修复后
val current: Boolean = if (sectionOpen[key] as Boolean) {

构建环境

项目	版本	路径
Gradle	8.14.3	C:\Users\Administrator\.gradle\wrapper\dists\gradle-8.14.3-bin\...
JDK	17 (ms-17.0.18)	C:\Users\Administrator\.jdks\ms-17.0.18
Android SDK	-	C:\Users\Administrator\AppData\Local\Android\Sdk
AGP	8.12.0	-
Kotlin	2.2.0	-
compileSdk	36	-
minSdk	24	-
targetSdk	36	-

打包命令

# 设置 JDK 17
$env:JAVA_HOME = "C:\Users\Administrator\.jdks\ms-17.0.18"

# 构建 release APK
& "C:\path\to\gradle-8.14.3\bin\gradle.bat" assembleRelease --no-daemon

构建产物

• APK 路径 ：uniappxnativepackage/app/build/outputs/apk/release/app-release-unsigned.apk
• 文件大小：约 267 MB
• 类型：未签名（unsigned）

APK 签名（可选）

生成的 APK 是未签名版本，安装前需要签名。使用 apksigner 或 jarsigner 签名：

# 使用 apksigner 签名
apksigner sign --ks your.keystore --ks-key-alias your_alias \
  --out app-release-signed.apk app-release-unsigned.apk

常见问题

Q1: UniAppX.Activity.DefaultTheme 样式找不到

原因 ：uniappx 模块对 SDK aar 使用 compileOnly 依赖，资源不参与库的资源验证。

解决 ：在 uniappx 模块的 res/values/styles.xml 中补充样式定义。

Q2: AGP 8.12.0 与 Gradle 9.6.0 不兼容

原因：Gradle 9.6.0 移除了 AGP 8.x 依赖的内部 API。

解决：使用 Gradle 8.x 版本（项目配置为 8.14.3）。

Q3: Kotlin 类型不匹配错误

原因 ：动态属性访问返回 Any? 类型，无法自动推断为 Boolean。

解决 ：添加显式类型转换 as Boolean。

Q4: gradle-wrapper.jar 缺失

原因：项目中缺少 Gradle wrapper jar 文件。

解决：使用系统已安装的 Gradle 直接运行，或从其他项目复制 wrapper jar。