小程序环境集成声明
更新时间: 2023/02/02 10:57:07
NIM Web 增强版 SDK 目前兼容 uniapp 和各种小程序(微信/支付宝)环境。但这些平台对 SDK 的使用存在一些限制。本文只要介绍小程序环境集成的注意事项,并针对限制以及并列举其中的一些重要限制以及针对限制的处理办法。
SDK 所提供的小程序相关能力的接口使用方式,基本与浏览器环境下调用方式相同。但根据小程序与浏览器的差异,SDK 也做了适配,主要调用方式的差异体现在诸如文件上传、WebSocket 和网络请求限制等方面。
域名白名单配置
开始小程序环境集成前,请确保已在微信开放平台完成域名白名单配置。
相关配置列表如下:
- request 合法域名:
- https://lbs.netease.im
- https://wlnimsc0.netease.im (IM 必需)
- https://wlnimsc1.netease.im (聊天室必需)
- https://wlnimsc0.netease.im:443 (IM 必需)
- https://wlnimsc1.netease.im:443 (聊天室必需)
- https://statistic.live.126.net (数据上报必需)
- https://abt-online.netease.im (用于 abtest)
- WebSocket 合法域名:
- wss://wlnimsc0.netease.im (IM 必需)
- wss://wlnimsc1.netease.im (聊天室必需)
- uploadFile 合法域名:
- https://nos.netease.com (云信文件上传必需,如发送文件类消息等)
- downloadFile合法域名:
- https://nim-nosdn.netease.im (云信资源文件下载必需,如下载图片、文件等)
WebSocket 连接限制
- 微信小程序 1.7.0 及以上版本,最多可同时存在 5 条 WebSocket 连接,其中同域名的 WebSocket 连接最多 2 条。
如需在切换账号或聊天室时使用新实例,为保证不超过小程序 WebSocket 连接限制,请务必先调用 IM /聊天室实例的
destroy
方法,并在promise
完成后以后再去创建新的实例。 - uniapp 项目在真机上运行(作为 app 运行,而非 H5),websocket只能连接一个 websocket。 自定义组件模式下是基于 weex 的 v8 引擎运行,所有 vue 页面的 js 都是在同一个 weex 的 js 环境中运行。目前 weex 限制一个 js 环境中只支持一个 websocket 连接,所以导致所有 vue 页面只能使用一个 websocket 连接。 IM 和 Chatroom 是分两个实例各自独立建立两个长连接的。所以编译成 uniapp app 的模式下,请不要同时使用两个实例。
初始化的配置
实例在小程序环境中运行,会受到下文的域名白名单限制,无法使用动态的基于位置的服务 (LBS) 自动调配长连接地址,所以初始化过程中的 LBS 只能使用一个固定的地址。
如下为使用固定 LBS 地址的示例:
import NIMSDK from 'nim-web-sdk-ng/dist/NIM_MINIAPP_SDK
const nim = new NIMSDK({
appkey: "YOUR_APPKEY",
token: "YOUR_TOKEN",
account: "YOUR_ACCOUNT",
lbsUrls: [
"https://lbs.netease.im/lbs/wxwebconf.jsp"
],
linkUrl: "wlnimsc0.netease.im"
})
uniapp 运行在小程序环境中也需进行上述初始化配置。
不支持分片上传
uniapp、小程序环境不支持分片上传。
由于读取文件有着诸多限制,无法以一种兼容性比较好的方式根据 filePath 拿到本地文件信息。单线程在上传大文件不仅体验很差,还会根据手机终端表现,会出一些意想不到的问题。
建议开发者在使用选择文件 API (chooseImage,choosevideo)时自行判断文件大小,100 MB 以上的不传。
微信小程序编译问题
-
uniapp 编译成微信小程序时,会直接在微信小程序上报错 “Function(...) is not a function”。
出现该问题的原因是微信基础库版本过低,请切换 2.21.0 以上的版本。
-
uniapp 编译成微信小程序时,会在小程序上报错 “TypeError: Converting circular structure to JSON”。
TypeError: Converting circular structure to JSON --> starting at object with constructor 'i' | property '_events' -> object with constructor 'n' | property 'logined' -> object with constructor 'Array' | index 0 -> object with constructor 'a' --- property 'context' closes the circle at JSON.stringify (<anonymous>) at cloneWithData (mp.runtime.esm.js?66fd:5620)
出现该问题的原因是 uniapp 编译微信小程序时注入的 mp.runtime.esm.js 里,对 vue 的 data 序列化使用的序列化方法是
return JSON.parse(JSON.stringify(ret))
。即在 vue 组件的 data 里挂载 nim 实例。然而实例继承自 EventEmitter3 对象,无法被这样序列化。建议将 nim 实例挂载在全局变量、vuex 的 prototype,或者参考如下示例代码在应用的
globalData
中挂载:const app = getApp() if (app && app.globalData && app.globalData.nim) { app.globalData.nim = new NIMSDK() }
-
微信小程序开启 将 JS 编译成 ES5 选项后,编译报错。
WAServiceMainContext.js:2 TypeError: t is not a function at oe.connect (NIM.js? [sm]:15) at Li.connect (im.js? [sm]:17) at Object.i.safeCallback (WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2) at WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2 at br (WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2) at WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2 at g (WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2) at WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2 at WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2 at WAServiceMainContext.js:2(env: Windows,mp,1.05.2111300; lib: 2.21.3)
建议不要开启 ES5 选项。