uniapp开发app记录

发布日期: 2025-06-08

基础框架下载: https://uniapp.dcloud.net.cn/worktile/CLI.html
DCLOUD社区：https://ask.dcloud.net.cn/search/q-dmNvbnNvbGU=#all
DCLOUD开发者中心： https://dev.dcloud.net.cn/

一、环境要求

● 运行环境
node=18.20.4

● 依赖版本（勿升级和降级）
uni cli=3.0.0-4060620250520001
Android 离线SDK=HBuilderX（4.66.2025051912）（即Android-SDK@4.66.82418_20250520）

二、运行项目

2.1 在web运行

npm install // 安装依赖
npm run dev:h5 // 运行到web

2.2 在Android运行

启动Android模拟器 (需开启ADB调试、开发者调试)

HbuildX点击 "运行--运行到手机或模拟器--运行到Android App基座(D)--选择模拟器+选择标准基座运行--运行"

PS: 如果检测不到模拟器，用adb connect 127.0.0.1:端口号连接模拟器，然后adb devices查看设备

三、调试

所有功能请确保: H5可运行，Android模拟器可运行，Apk真机可运行

3.1 在web调试

F12控制台

3.2 在Android调试

方式1: HBuildX 查看打印 （HBuildX还有一个uni/nvue调试）
方式2: Edge 访问 edge://inspect/#devices 查看DOM
方式3: 本地日志查看日志

3.3 真机APK调试

本地日志查看日志

四、本地日志说明

目前仅在手机端和开发环境启用本地日志

● 自动记录请求
● 手动写入日志 console.log2?.('内容') 

调试完记得把 console.log2?.('内容') 恢复回 console.log('内容')

五、打包Apk

5.1 远程打包（不推荐）

打包需要排队
● 已配置: 名称/图标/版本/模块/权限/兼容CPU/腾讯地图KEY等
● 未配置: 启动界面图片

1. 修改 /src/manifest.json 的版本名称和版本号； 
   修改 \src\service\serviceHelper 的环境； 

2. HBuildX点击 "发行-- App-Android/iOS-云打包(P) --本地证书(放文末)--打正式包--删掉全部广告--快速安心打包--打包"

PS: 本地证书跳转

5.2 本地打包（推荐）

1. 修改 /src/manifest.json 的版本名称和版本号； 
   修改 \src\service\serviceHelper 的环境； 

2. HBuildX点击 "发行-- App-Android/iOS-本地打包(L) --生成本地打包App资源(R)"  

3. 将 /unpackage/resources/__UNI__88888XX 拷贝到离线SDK  /Android-SDK@4.66.82418_20250520/HBuilder-Integrate-AS/simpleDemo/src/main/assets/apps/__UNI__88888XX

4. 修改 \Android-SDK@4.66.82418_20250520\HBuilder-Integrate-AS\simpleDemo\build.gradle 的版本号

5. Android Studio 打包，点击"Build -- Generate Signed App Bundle or Apk... -- Next -- 选本地证书 -- Next" (此处略过拉依赖和配置证书)

PS: 查看离线SDK配置

六、打包Wgt

HBuildX点击 "发行-- App制作应用wgt包(G)"

七、热更新

7.1 业务逻辑

        接口请求获取版本号
                |
                |
        判断版本号(第2位为apk更新，第3位为wgt更新)
                |
                |
        |——————————————————|
       apk                wgt
        |                  |
  下载apk(显示进度)        下载wgt(不显示进度)
        |                  |
    调起apk安装            安装wgt
        |                  |
安装完后会进入新版本Apk     自动重启

PS:

每次更新都要打Apk和Wgt，因为可能有APP长期没更新，需要跨大版本更新
新版版本号高于旧版版本号，否则报错
证书必须一致，否则报错
cli版本和HBuildX版本必须一致（4.66），否则报错

7.2 操作

通过【五、打包Apk】和【六、打包Wgt】将打包好的Apk和wgt放到服务器即可

八、项目说明

8.1 目录

> /src/components           封装组件  
> /src/hooks                Hook函数  
> /src/packages             分包页面  
> /src/pages                主包页面  
> /src/service              请求文件  
> /src/static               全局静态文件  
> /src/styles               全局样式  
> /src/uni_modules          uni-ui  
> /src/utils                全局工具函数  
> /document/keystore        打包证书  
> /unpackage/release        打包生成的wgt  
> /unpackage/res            打包的配置文件  
> /unpackage/resources      打包Apk的资源

PS: UI统一使用uni-ui，确保兼容性和项目大小，防止编译过慢

二十、离线SDK配置

重点: appid，包名，名称，图标，版本号，打包证书，打包的CPU版本，权限，appkey…

下载Android 离线SDK，2025年05月20日发布——HBuilderX（4.66.2025051912）
解压下载的Android 离线SDK

Android Studio 直接导入HBuilder-Integrate-AS工程
Android Studio拉一下依赖
Android Studio生成本地打包证书

dcloud开发者中心创建应用–创建平台–配置包名/签名SHA1值/签名SHA256值–生成离线打包Key

配置appid

// simpleDemo/src/main/assets/data/dcloud_control.xml
appid="__UNI__88888XX"

配置包名

// simpleDemo/build.gradle
android {
    namespace 'com.ymexample.driver'
    defaultConfig {
        applicationId "com.ymexample.driver"
    }
}

配置dcloud_appkey

// simpleDemo/src/main/AndroidManifest.xml
<application>
    <meta-data
        android:name="dcloud_appkey"
        android:value="XXXXXXXXXXXXXXXXXXXXXXXXX" />
</application>

PS:

本地打包的证书和线上appkey 配置的 “SHA1值/签名SHA256值” 必须一致，否则App报错校验失败
本地打包的包名和线上appkey 配置的包名必须一致，否则App报错校验失败

配置本地打包证书

// simpleDemo/build.gradle
android {
    signingConfigs {
        config {
            keyAlias 'key0'
            keyPassword '1234567890'
            storeFile file('ceshi.keystore.jks')
            storePassword '1234567890'
            v1SigningEnabled true
            v2SigningEnabled true
        }
    }
}

配置名称

// simpleDemo/src/main/res/values/strings.xml
<resources>
    <string name="app_name">APP的名称</string>
</resources>

配置图标

// simpleDemo\src\main\res\drawable
@drawable/icon App的图标
@drawable/push App推送图
@drawable/splash App启动图

配置版本号

// simpleDemo/build.gradle
android {
    defaultConfig {
        versionName "1.2.20" // 建议与manifest.json中versionName值一致
        versionCode 1002020 // 建议与manifest.json中versionCode值一致
    }
}

配置打包的CPU兼容

// simpleDemo/build.gradle
android {
    defaultConfig {
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a", "x86" // 建议与manifest.json中abiFilters同步修改，保证远程打包和本地打包一致
        }
    }
}

PS:

打包的平台越多,Apk越大
Android目前支持以下7种ABIs:mips, mips64, X86, X86–64, arm64-v8a, armeabi, armeabi-v7a

配置权限: 相机、访问文件、定位、安装Apk、屏幕常亮等

// simpleDemo/src/main/AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- 将权限声明全部加到这里来（关键） -->
    <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS"/>
    <uses-permission android:name="android.permission.READ_CONTACTS"/>
    <uses-permission android:name="android.permission.VIBRATE"/>
    <uses-permission android:name="android.permission.READ_LOGS"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-feature android:name="android.hardware.camera.autofocus"/>
    <uses-permission android:name="android.permission.WRITE_CONTACTS"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-permission android:name="android.permission.RECORD_AUDIO"/>
    <uses-permission android:name="android.permission.GET_ACCOUNTS"/>
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>
    <uses-permission android:name="android.permission.WAKE_LOCK"/>
    <uses-permission android:name="android.permission.CALL_PHONE"/>
    <uses-permission android:name="android.permission.FLASHLIGHT"/>
    <uses-feature android:name="android.hardware.camera"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.WRITE_SETTINGS"/>
    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES"/>
    
</manifest>

PS: 直接全部加上，防止各个权限轮流报错

配置库(aar)

// simpleDemo\libs
// 从 Android-SDK@4.66.82418_20250520\Android-SDK@4.66.82418_20250520\SDK\libs 拷贝过去 simpleDemo\libs

install-apk-release.aar // 用于安卓调起安装APK，上架谷歌应用市场不能包含此库

安卓10以上无法唤起相机

// simpleDemo/src/main/AndroidManifest.xml
<application>
    <provider
        android:name="io.dcloud.common.util.DCloud_FileProvider"
        android:authorities="com.ymexample.driver.dc.fileprovider"
        android:exported="false"
        android:grantUriPermissions="true">
        <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/dcloud_file_provider" />
    </provider>
</application>

二十一、腾讯地图配置

添加Key

配置key的配置(IP定位、逆地址编码)

PS: 当前Key是个人的，要换成公司的

踩坑

1. 【H5】 “连接服务器超时”

解决: 删除异常代码 import { reactive } from '@vue/runtime-core' , 禁止从@vue引入任何东西。

2. 【H5】 “@vue/shared 中缺少 xxx 方法”

解决: 删除异常代码 import { reactive } from '@vue/runtime-core' , 禁止从@vue引入任何东西。

3. 【App】 HTML5+ Runtime 本应用使用HBuilderX 4.66或对应的cli版本编译，而手机端SDK版本是4.36。不匹配的版本可能造成应用异常。

解决：HBuildX版本和 cli版本都保持在4.66

4. 【App】引入vconsole白屏问题

解决：无法解决，放弃吧

5. 【App】 errMsg: “getLocation:fail [geolocation:6]定位结果错误请到http://lbs.amap.com/api/android-location-sdk/guide/utilities/errorcode/查看错误码说明,错误详细信息:#id:Sc2FjODU5Yzc5ZjQ0MWlqamFobWNnMmY0YTJjZTY4LA==#csid:7946ffb23f4d4483870c25236254fdf9location faile retype: rdesc:101#0601#pm111111”

解决：获取wgs84定位，不要获取gcj02定位。（腾讯定位配置不能解决报错）

// 推荐
uni.getLocation({
    // type: 'gcj02',
    success: function (res) {
        console.log('res', res)
    },
    fail: function (err) {
        console.log('获取定位信息失败', JSON.stringify(err))
    }
});

// 暂不推荐, HTML5的方式
// plus.geolocation.getCurrentPosition(function (res) {
//   console.log('res', res)
// }, function (err) {
//   console.log('获取定位信息失败', JSON.stringify(err))
// });

PS: HTML5+ API

6. 【App】 js-framework.js:45 Error: 使用uni.chooseLocation且使用腾讯地图时，需搭配uniCloud使用，详情请参考：https://uniapp.dcloud.net.cn/api/location/location.html#chooselocation

解决：未解决，项目暂时不不需要选择定位(uni.chooseLocation)

附件

1. 本地证书

文件路径: 不对外

证书文件(storeFile) ‘xxxx.keystore.jks’
证书别名(keyAlias) ‘xxxx’
证书库密码(keyPassword) ‘xxxx’
证书私钥密码(storePassword) ‘xxxx’

PS: 热更新要求证书必须一致

链接

Alex

http://120.79.201.10/2025/06/08/uniapp-kai-fa-app-ji-lu/

本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 Alex !

Android 混合APP uniapp

本篇

uniapp开发app记录

2025-06-08 uniapp Android 混合APP

Android 混合APP uniapp

Expo的React Native项目, 二开记录

2025-05-08 expo react-native

expo react-native

uniapp开发app记录

一、环境要求

二、运行项目

2.1 在web运行

2.2 在Android运行

三、调试

3.1 在web调试

3.2 在Android调试

3.3 真机APK调试

四、本地日志说明

五、打包Apk

5.1 远程打包（不推荐）

5.2 本地打包（推荐）

六、打包Wgt

七、热更新

7.1 业务逻辑

7.2 操作

八、项目说明

8.1 目录

二十、离线SDK配置

二十一、腾讯地图配置

踩坑

1. 【H5】 “连接服务器超时”

2. 【H5】 “@vue/shared 中缺少 xxx 方法”

3. 【App】 HTML5+ Runtime 本应用使用HBuilderX 4.66或对应的cli版本编译，而手机端SDK版本是4.36。不匹配的版本可能造成应用异常。

4. 【App】 引入vconsole白屏问题

6. 【App】 js-framework.js:45 Error: 使用uni.chooseLocation且使用腾讯地图时，需搭配uniCloud使用，详情请参考：https://uniapp.dcloud.net.cn/api/location/location.html#chooselocation

附件

1. 本地证书

链接

你的赏识是我前进的动力

4. 【App】引入vconsole白屏问题