前言
本文主要是为了记录一些我在开发 uniapp 过程中所遇到的一些坑，再骂一次，* * * 的 ** uniapp
本文会不间断一直更新，有需要的兄弟们可以收藏，未来碰到问题可以先行查看本文中是否存在你们正遇到的问题
更新日志
2025-04-24 新增了第6、7点
2025-08-11 第四点吐槽了uniapp的离线打包文档
1. 页面之间传值注意点
页面之间如果要传的值过多，那么建议最好是使用其它的方案去达到这一目的，比如使用uni.setStorage去实现，最好不要转成 JSON 直接拼接到 url 里面，这么做虽然可能程序不会崩，但只要传的值过多，在每次改动目标页面重新编译的时候就会百分百白屏，这种开发体验是极差的，以下是报错信息：
reportJSException >>>> exception function:createInstanceContext, exception:white screen cause create instanceContext failed,check js stack ->Uncaught URIError: URI malformed
at (uni-jsframework.js:1:54507)
at I (uni-jsframework.js:1:54421)
at Bv (uni-jsframework.js:1:295064)
at Rv (uni-jsframework.js:1:296550)
at o.$mount (uni-jsframework.js:1:309159)
在发现我改动这个页面重新编译百分百白屏报错之后，我就通过注释掉该页面的一些代码以及组件引用，最后仍然有这个问题，那么就只能说明报错原因是上一个页面 url 传过来的参数导致的，遂将 URL 传值改为uni.setStorageSync传值，问题解决。
2. 不要在 uni-transition 组件上绑定任何事件
会出现"TypeError: $event.stopPropagation is not a function" 的错误
3. 所有项目依赖插件建议下到本地，并选择从本地加载
为什么要这样？因为如果你选择从云端加载插件，而 uniapp 又不支持锁定插件版本( *** * _ 的 _ * uniapp** )，所以你永远也不会知道作者更新了什么东西，你看不到源码，也收不到更新通知，很有可能出现咱们的项目在上一个版本的基座还没有任何问题，但是在下一个版本就会出错的 bug。很操蛋。
再提一点，每当我们的项目中添加或者更换了插件，要重新打基座才能看到效果
本条所有问题都是基于 Android 自定义基座开发时发现的
4. 离线打包
天下没有免费的午餐，uniapp 免费的打包是小的可怜，想付费嘛，一次 20 又不好，跟老板申请经费嘛，老板又说：“怎么会要钱嘞，之前招的开发从来没问我要过钱”。没办法，只能尝试离线打包了。
T**S*uniapp，离线打包文档写的跟坨shit一样，我到今天才发现，离线打包会导致插件市场的插件不可用，无论收费付费。我在按照网上的各种解决方案去尝试解决这个问题，但无一能解决的。就是硬逼着开发者花钱买你们的东西。我觉得公司要赚米无可厚非，但你们如此吃相着实难看。当然，以上是情绪之言，可能也是我还没找到那篇足以拯救我的文章，诸位如有解决方案，劳烦赐教！ (2025/08/11)
4.1 第一步，生成离线打包资源
这一步很简单，点击图中按钮即可生成
生成的离线包在
项目目录/unpackage/resources文件夹下
4.2 生成离线 appKey、证书与下载 uniapp 官方的离线资源包
首先呢，appkey 与证书这里我们选择在DCloud 开发者中心去生成，本地很麻烦且不好管理(其实是懒得管)。
然后生成证书，生成之后点详情查看
这里我们需要把 SHA1 和 SHA256 复制下来
来到这里点新增
填入刚刚复制的信息，提交
回到这里点创建离线 key
至此，证书以及 appKey 都有了。记得还要把证书下载本地。
下载 Android 离线包 nativesupport.dcloud.net.cn/AppDocs/use…
4.3 下载 Android Studio
下载地址：developer.android.google.cn/studio?hl=z…
4.4 开始配置相关信息
接下来这一步主要是基于 uniapp 官方提供的 Android 离线 SDK 去做一些修改。将下载的离线 SDK 做解压缩
然后进入，找到这个文件夹最大的，这个就是我们待会要修改的 sdk 包
将其导入到 AndroidStudio，文件视图我们选择“Project Files”
然后将src/main/apps/下的所有文件删掉，替换成我们第一步生成的打包资源。替换完毕后我们就需要修改以下文件：
项目根目录/app/src/main/data/dcloud_control.xml
<apps>
<app appid="修改成 apps__UNI__TEST\www\manifest.json 中的id 如下图" appver=""/>
</apps>
项目根目录/app/src/main/AndroidManifest.xml
<!-- 1. 修改package包名 这个包名要与我们在申请appKey时填的包名一致 -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools" package="uni.TEST">
<!-- 2. 在application节点下添加provide节点 -->
<provider
android:name="io.dcloud.common.util.DCloud_FileProvider"
android:authorities="uni.TEST.dc.fileprovider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/dcloud_file_provider" />
</provider>
3. 项目根目录/build.gradle
// 修改namespace、applicationId、versionName、manifestPlaceholders.apk.applicationId
// namespace、applicationId、manifestPlaceholders.apk.applicationId与上面第二步的包名一致
// versionName则与apps__UNI__TEST\www\manifest.json中的version一致
android {
compileSdkVersion 35
buildToolsVersion '35.0.0'
namespace 'uni.TEST'
defaultConfig {
applicationId "uni.TEST"
minSdkVersion 21
targetSdkVersion 33
versionCode 1
versionName "1.41.1"
multiDexEnabled true
ndk {
abiFilters 'x86', 'armeabi-v7a', 'arm64-v8a'
}
manifestPlaceholders = [
"apk.applicationId" : "uni.TEST",
"GETUI_APPID" : "unipush的appid",
"plus.unipush.appid" : "unipush的appid",
"plus.unipush.appkey" : "unipuish的appkey",
"plus.unipush.appsecret": "unipush的secrety"
]
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
}
4. 修改应用图标以及文件名
我们将应用图标拷贝到如下目录项目根目录/app/src/main/res
hdpi这些文件名后缀对应着不同的分辨率，以下是参考：
hdpi：72x72 px
xhdpi：96x96 px
xxhdpi：144x144 px
xxxhdpi：192x192 px xxxhdpi：192x192 px
而文件名的修改则是在项目根目录/app/src/main/res/values/strings.xml文件中修改
<resources>
<string name="app_name">你的应用名字</string>
</resources>
5. 开始应用打包
在Build目录下选择如下选项
如无发布到应用商店的需求，我们就将打包类型选择为APK
Key store path我们选择刚才我们下载本地的证书，然后在后台查看证书密码，在Key store password以Key password中输入，Key alias我们也可以在后台中看到，就是“证书别名”
然后打包这里我们选release，即正式版
以上就是uniapp应用打包的全流程
5. 真机调试连不上的问题
真机调试连不上，在我们按照uniapp真机调试故障排除指南排查之后仍然检测不到设备的时候，我们需要打开电脑的设备管理器，查看驱动是否报警告，如有，请卸载该设备，并在卸载的时候把同时卸载驱动选项勾上(如有)。
然后拔掉与设备，重置开发者选项，再次设置“usb调试”、“hdb选项”等，再打开HbuilderX查看问题是否解决。
6. scroll-view设置了横向滚动无效的问题
这个问题很无语啊，scroll-view的官方文档 是有写当设置了enable-flex属性之后，scroll容器就会变成flex container，但实际上在安卓端的表现并不是这么一回事，而且还看不到源码，不知道其内部是怎么处理的。因此，当出现这种问题的时候，要在内部子元素属性中添加display: inline-block样式，scroll容器还需加上white-space: nowrap;样式，如此该问题即可解决。
7. uni-transition影响内部元素层级的问题
首先出现这个问题的原因是由于通过transform和opacity实现的动画可能创建新的层叠上下文，导致内部元素的z-index失效。那么解决这个问题的方法也很简单，就是在uni-transition上再套个盒子，把z-index属性设置给最外层的这个容器，以下是实例：
<template>
<view class="topContainer">
<uni-transition modeClass="zoom-in" :show="true">
// 子元素内容。。。
</uni-transition>
</view>
<template>
<style lang="scss">
.topContainer {
z-index: 999;
}
</style>
如上，该问题可得解决。内部受到影响的top、bottom等定位样式受到影响也可以通过这种办法来解决。
