uni-app
uni-app x
uniCloud
HBuilder X
uni 小程序 sdk
uni-ad广告
开发者服务
uni-app
uniCloud
HBuilder X
uni 小程序 sdk
uni-ad广告
开发者服务
GitHub
介绍
准备
新建uni-app x模块
工程配置
基础库配置
修改build.gradle
配置gradle插件
修改项目的settings.gradle
修改项目的gradle.properties
修改uniappx模块下的AndroidManifest.xml
拷贝资源文件
展示全部

# uni-app x 原生SDK Android版

# 准备

  • HBuilder X （4.18版本及以上）
  • android studio

说明：

蒸汽模式（Vapor）：

当前文档基于Android Studio Quail 3 | 2026.1.3。gradle版本为9.2.1。gradle插件版本为9.0.1。kotlin插件版本为2.2.0。

VDOM模式：

当前文档基于Android Studio Narwhal 3 Feature Drop | 2025.1.3。gradle版本为8.14.3。gradle插件版本为8.12.0。kotlin插件版本为2.2.0。

更早版本的环境配置请参考文档。

# 新建uni-app x模块

点击File->New->New Module...

点击左侧Templates的Android Library。

Language选择Kotlin。

Module name建议设置为uniappx。

点击Finish。

注意

  • Language 一定要选择Kotlin。
  • uni-app x 项目最低支持版本：蒸汽模式（Vapor）为23，VDOM模式为21。Minimum SDK按要求选择正确的版本。
  • Build configuration language建议选择Groovy DSL(build.gradle)。以下教程均按照此模式进行。

# 工程配置

# 基础库配置

蒸汽模式（Vapor）：

将app-common-release.aar，app-runtime-release.aar，breakpad-build-release.aar，uts-runtime-release.aar，ext-component-release.aar， uni-dialogPage-release.aar，uni-event-release.aar，uni-crash-release.aar，uni-getElementById-release.aar，uni-pullDownRefresh-release.aar， uni-storage-release.aar，uni-exit-release.aar，uni-theme-release.aar， uni-getAppBaseInfo-release.aar，uni-getDeviceInfo-release.aar，uni-getSystemInfo-release.aar，uni-getAccessibilityInfo-release.aar， uni-getAppAuthorizeSetting-release.aar，uni-getSystemSetting-release.aar， uni-openAppAuthorizeSetting-release.aar，uni-prompt-release.aar，uni-rpx2px-release.aar，uni-secure-network-release.aar共23个aar拷贝到uni-app x模块的libs下，如果没有libs需要手动创建，参考下图：

VDOM模式

将uts-runtime-release.aar，android-gif-drawable-1.2.28.aar，app-common-release.aar，app-runtime-release.aar，breakpad-build-release.aar，dcloud-layout-release.aar， framework-release.aar，uni-exit-release.aar，uni-getAccessibilityInfo-release.aar，uni-getAppAuthorizeSetting-release.aar，uni-getAppBaseInfo-release.aar， uni-getSystemSetting-release.aar，uni-openAppAuthorizeSetting-release.aar，uni-prompt-release.aar，uni-storage-release.aar，uni-getDeviceInfo-release.aar， uni-getSystemInfo-release.aar，uni-rpx2px-release.aar，uni-theme-release.aar共19个aar拷贝到uni-app x模块的libs下，如果没有libs需要手动创建，参考下图。

# 修改build.gradle

修改uniappx模块下的build.gradle

  • 添加依赖

    将下面的依赖信息添加到build.gradle中

    build.gradle（蒸汽模式）

    build.gradle.kts（蒸汽模式）

    build.gradle（VDOM模式）

    build.gradle.kts（VDOM模式）

    dependencies {
    implementation fileTree(include: ['*.aar'], dir: './libs')// 复制到主模块中需要将`./libs`替换为`../uniappx/libs`
    implementation "androidx.tracing:tracing-ktx:1.3.0"
    implementation "androidx.core:core-ktx:1.10.1"
    implementation "androidx.appcompat:appcompat:1.6.1"
    implementation "androidx.constraintlayout:constraintlayout:2.2.1"
    implementation "androidx.exifinterface:exifinterface:1.3.6"
    implementation "com.google.android.material:material:1.10.0"

    implementation "org.jetbrains.kotlin:kotlin-reflect:2.2.0"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"

    implementation "com.facebook.fresco:fresco:3.4.0"
    implementation "com.facebook.fresco:animated-base:3.4.0"
    implementation "com.facebook.fresco:animated-gif:3.4.0"
    implementation "com.facebook.fresco:animated-webp:3.4.0"
    implementation "com.facebook.fresco:webpsupport:3.4.0"
    implementation "com.facebook.fresco:imagepipeline:3.4.0"
    implementation "com.facebook.fresco:drawee:3.4.0"
    implementation "com.facebook.fresco:middleware:3.4.0"

    implementation "com.caverock:androidsvg:1.4"
    implementation "com.alibaba:fastjson:1.2.83"
    implementation "com.github.getActivity:XXPermissions:18.63"
    implementation "androidx.profileinstaller:profileinstaller:1.4.1"
    implementation "com.squareup.okhttp3:okhttp:3.12.12"
}

  • 添加配置

    将配置添加到android节点下，其中androidResources和packagingOptions为蒸汽模式（Vapor）特有配置。

    build.gradle（蒸汽模式）

    build.gradle.kts（蒸汽模式）

    build.gradle（VDOM模式）

    build.gradle.kts（VDOM模式）

    androidResources {
    noCompress "uni-app-x-framework-vapor", "uni-app-x-framework-vapor-dev", "js"
    ignoreAssetsPattern '!.svn:!.git:.*:!CVS:!thumbs.db:!picasa.ini:!*.scc:*~'
}

aaptOptions {
    additionalParameters '--auto-add-overlay'
    ignoreAssetsPattern '!.svn:!.git:.*:!CVS:!thumbs.db:!picasa.ini:!*.scc:*~'

}
packagingOptions {
    pickFirst 'lib/*/libstlport_shared.so'
    pickFirst 'lib/*/libc++_shared.so'

    jniLibs {
        useLegacyPackaging false
    }
}

  • 配置Java版本

    注意

    仅蒸汽模式（Vapor）需要配置Java版本为17

    compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

注意：上面的gradle配置需要同时设置到主模块中。

# 配置gradle插件

在项目根目录的build.gradle的顶部添加gradle插件的依赖。参考：

buildscript {
    dependencies {
		...
        classpath(files('../plugins/uts-kotlin-compiler-plugin-0.0.1.jar'))
        classpath(files('../plugins/uts-kotlin-gradle-plugin-0.0.1.jar'))
        classpath(files('../plugins/auto-register-gradle-plugin-1.0.0.jar')) // 仅蒸汽模式（Vapor）支持
    }
}

注意：文件uts-kotlin-compiler-plugin-0.0.1.jar、uts-kotlin-gradle-plugin-0.0.1.jar和auto-register-gradle-plugin-1.0.0.jar等jar位于原生SDK中，示例中放到了项目根目录的plugins文件夹下。参考：

然后在uniappx模块的build.gradle下添加插件io.dcloud.uts.kotlin的依赖。参考：

build.gradle

build.gradle.kts

plugins {
	...
    id 'io.dcloud.uts.kotlin'
    id 'io.dcloud.uts.auto-register' // 仅蒸汽模式（Vapor）支持
}

# 修改项目的settings.gradle

在项目根路径下的settings.gradle中添加jitpack的maven的仓库地址和本地gradle插件的路径配置。参考如下：

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        ...
        maven { url = uri("https://jitpack.io") }
		flatDir { dirs('./plugins/') }
    }
}

# 修改项目的gradle.properties

在项目根路径下的gradle.properties中追加如下内容

android.useAndroidX=true
android.enableJetifier=true

# 修改uniappx模块下的AndroidManifest.xml

  • 添加activity

    将下面内容拷贝到application节点下

    AndroidManifest.xml（Vapor）

    AndroidManifest.xml（VDOM）

        <activity
        android:name="io.dcloud.uniappxv.UniAppActivity"
        android:configChanges="orientation|keyboardHidden|screenSize|mcc|mnc|fontScale|keyboard|smallestScreenSize|screenLayout|uiMode"
        android:exported="true"
        android:label="@string/app_name"
        android:theme="@style/Theme.AppCompat.DayNight.NoActionBar"
        android:windowSoftInputMode="adjustResize"
        tools:replace="android:label,android:exported,android:theme,android:configChanges,android:windowSoftInputMode" />

  • 添加appid

    在application节点下添加DCLOUD_UNI_APPID节点

    <meta-data
	android:name="DCLOUD_UNI_APPID" android:value="替换成应用的appid" />

  • 修改application

    将application节点的android:name修改为io.dcloud.uniapp.UniApplication

    注意：如果需要自定义application，必须继承自UniApplication

  • 配置应用分发渠道

    在application节点下添加DCLOUD_CHANNEL节点

    <meta-data
	android:name="DCLOUD_CHANNEL" android:value="替换成需要发布的应用分发渠道" />

    获取配置的应用分发渠道，可以通过uni.getAppBaseInfo()。

  • 合并AndroidManifest.xml

    如果uni-app x项目根目录下有AndroidManifest.xml文件，你需要按照xml文件的结构将内容拷贝到uniappx模块的AndroidManifest.xml中。

# 拷贝资源文件

  1. 导出uni-app x项目的资源文件

    选择项目，然后点击：发行 -> 原生App-本地打包 -> 生成本地打包App资源

    导出成功之后会在项目的unpackage/resources目录下生成资源文件

  2. 将app-android目录下与appid对应的目录拷贝到uniappx项目的assets/apps目录下

    注意：apps下的appid必须与AndroidManifest.xml的DCLOUD_UNI_APPID保持一致。

# 拷贝kt文件

注意

仅VDOM模式支持，蒸汽模式（Vapor）无需配置。

需要将unpackage/resource/app-android/uniappx/app-android/src/目录下的所有文件拷贝到uniappx项目的src/main/java下

注意：不要破坏原有src下的目录结构。

# 添加到主模块

将uni-app x模块添加到主模块中。

build.gradle

build.gradle.kts

	dependencies {
		implementation project(':uniappx')
		implementation fileTree(include: ['*.aar'], dir: '../uniappx/libs')
	}

# 配置内置模块

根据unpackage/resource/{appid}/manifest.json的配置，添加内置模块的配置。

# uts插件配置

uts插件资源位于unpackage/resource/app-android/uni_modules下。如果uni_modules下存在uts插件，需要按照uts插件配置文档将插件集成到项目中。

蒸汽模式（Vapor）：

以下模块可以忽略配置：

  • uni-exit
  • uni-getAccessibilityInfo
  • uni-getAppAuthorizeSetting
  • uni-getAppBaseInfo
  • uni-getDeviceInfo
  • uni-getSystemInfo
  • uni-getSystemSetting
  • uni-openAppAuthorizeSetting
  • uni-prompt
  • uni-storage
  • uni-rpx2px
  • uni-theme
  • uni-dialogPage
  • uni-event
  • uni-getElementById
  • uni-pullDownRefresh
VDOM模式

以下模块可以忽略配置：

  • uni-exit
  • uni-getAccessibilityInfo
  • uni-getAppAuthorizeSetting
  • uni-getAppBaseInfo
  • uni-getDeviceInfo
  • uni-getSystemInfo
  • uni-getSystemSetting
  • uni-openAppAuthorizeSetting
  • uni-prompt
  • uni-storage
  • uni-rpx2px
  • uni-theme

# 启动

至此，uni-app x 导入原生项目的所有配置已经完成。uni-app x的启动、退出及运行期间通讯可以参考文档。

本页导读
准备
新建uni-app x模块
工程配置
基础库配置
修改build.gradle
配置gradle插件
修改项目的settings.gradle
修改项目的gradle.properties
修改uniappx模块下的AndroidManifest.xml
拷贝资源文件
拷贝kt文件
添加到主模块
配置内置模块
uts插件配置
启动
uni-agent