鸿蒙 uni-app x 微信分享 uni.share 适配排障

鸿蒙专家

为什么鸿蒙平台要单独处理微信分享

uni.share 是 uni-app x 提供的微信分享 API，专门对接微信 SDK，支持分享到微信聊天、朋友圈和微信收藏。兼容性方面，Web 不支持；Android 和 iOS 从 HBuilderX 5.08 才开始支持微信分享，而鸿蒙 4.81 就已经支持，时间更早。因此鸿蒙端做微信分享时，可以直接走 uni.share。系统分享 uni.shareWithSystem 是另一套能力，这里不展开。

API 签名与核心参数

API 签名为：

2. uni.share(options: ShareOptions)

复制代码

。常用参数包括 provider、scene、type、title、href、summary、imageUrl，以及小程序分享用的 miniProgram。

分享类型 type：0 表示图文，1 表示纯文字，2 表示纯图片，5 表示小程序。分享场景 scene：WXSceneSession 对应微信聊天，WXSceneTimeline 对应朋友圈，WXSceneFavorite 对应微信收藏。失败回调会返回 ShareFail，可通过 errCode 和 errMsg 排查。

纯文字分享示例：

2. uni.share({
3.   provider: 'weixin',
4.   scene: 'WXSceneSession',
5.   type: 1,
6.   summary: '今天学到了 uni-app x 的微信分享功能，太方便了！',
7.   success: () => {
8.     uni.showToast({ title: '分享成功', icon: 'success' })
9.   },
10.   fail: (err: ShareFail) => {
11.     uni.showToast({ title: '分享失败: ' + err.errMsg, icon: 'none' })
12.   }
13. })

复制代码

分享图文到聊天时，通常需要 title、href、summary、imageUrl；分享小程序时，miniProgram 需要配置 id、path、type 和 webUrl，其中 webUrl 用于低版本回退网页。

鸿蒙平台专属限制

鸿蒙平台做微信分享，限制比 Android、iOS 更需要提前处理。图片仅支持 jpeg 和 png，GIF、WebP 都不行。图片大小不能超过 100KB，视频大小不能超过 64KB。文字方面，title 不能超过 512 个字节，summary 不能超过 1024 个字节；UTF-8 下中文一个字约占 3 个字节，换算下来 title 最多约 170 个中文字，summary 最多约 340 个中文字。

这些限制会直接影响高清图、长文案和表情包类内容。建议在分享前统一做图片压缩和文本截断：

2. uni.compressImage({
3.   src: '/static/large-image.jpg',
4.   quality: 60,
5.   success: (res) => {
6.     uni.share({
7.       provider: 'weixin',
8.       type: 2,
9.       imageUrl: res.tempFilePath
10.     })
11.   }
12. })

复制代码

文本截断可以按 UTF-8 字节数计算，中文按 3 字节、其他字符按 1 字节：

2. const truncateText = (text: string, maxBytes: number): string => {
3.   let bytes = 0
4.   let result = ''
5.   for (let i = 0; i < text.length; i++) {
6.     const charCode = text.charCodeAt(i)
7.     if (charCode > 127) {
8.       bytes += 3
9.     } else {
10.       bytes += 1
11.     }
12.     if (bytes > maxBytes) {
13.       break
14.     }
15.     result += text[i]
16.   }
17.   return result
18. }
20. const shareTitle = truncateText(veryLongTitle, 512)
21. const shareSummary = truncateText(veryLongSummary, 1024)

复制代码

manifest 配置与微信安装检查

鸿蒙平台需要在 manifest.json 中配置微信 APPID。如果不配置，会报错 4000500，提示未找到微信 APPID。分享前也建议检查微信是否安装，未安装会报错 4000510。

2. uni.getProvider({
3.   service: 'share',
4.   success: (res) => {
5.     const provider = res.providers.find((item): boolean => {
6.       return item.id == 'weixin'
7.     })
8.     if (provider != null && provider instanceof UniShareWeixinProvider) {
9.       if (!provider.isWeChatInstalled) {
10.         uni.showToast({ title: '请先安装微信', icon: 'none' })
11.         return
12.       }
13.       console.log('微信已安装，可以分享')
14.     }
15.   },
16.   fail: (err) => {
17.     console.log('获取分享通道失败:', err)
18.   }
19. })

复制代码

4.87 版本图片分享 bug

鸿蒙平台在 HBuilderX 4.87 及以下版本中，分享时图片大于 20KB 会出现分享失败。临时方案是下载 har 包并改名为 uni_modules__uni_share_weixin.har，放到 项目根目录/harmony-configs/libs/ 目录下重新编译运行。高版本不存在这个问题。如果项目已经出现图片死活分享不出去，除了检查格式和 100KB 限制，也要确认 HBuilderX 版本。

常见错误码与排障顺序

4000500：未找到微信 APPID，检查 manifest.json 中的微信配置。4000510：微信未安装，分享前先检查。4000507：图片下载失败，结合图片大小、格式和网络地址排查。4000511：分享失败，优先检查鸿蒙图片 100KB、视频 64KB、title 512 字节、summary 1024 字节等限制；4.87 版本的 20KB 图片 bug 也要纳入排查。

与鸿蒙原生分享的差异

鸿蒙原生开发中，分享对接相对复杂，需要从 @kit.ShareKit 引入 share，创建 ShareData，处理各种回调，再调用 share.shareAbility(context, shareData)。原生方案的优势是可以调用系统分享面板，支持更多分享目标。uni-app x 的 uni.share 封装了微信分享，一个 API 就能完成聊天、朋友圈、收藏等场景，不用分别对接微信 SDK，但必须接受鸿蒙平台的格式、大小和字节限制。

如果内置微信分享不够用，uni-app x 从 4.25 起开放了 provider 自接入机制。需要新建 UTS 插件，定义 UniShareProvider 接口，实现 share 方法，在 manifest.json 中配置，然后打包自定义基座运行。之后可以用 uni.share({ provider: 'weibo', ...}) 的方式调用自定义分享，例如接入微博、抖音等。

总结

uni.share 专门对接微信，支持聊天、朋友圈、收藏三个场景；鸿蒙 4.81 开始支持，比 Android、iOS 的 HBuilderX 5.08 更早。鸿蒙平台图片仅支持 jpeg/png，大小不超过 100KB；视频不超过 64KB；title 不超过 512 字节，summary 不超过 1024 字节。4.87 及以下版本存在图片大于 20KB 分享失败的 bug。manifest 必须配置微信 APPID，分享前检查微信是否安装。分享前统一做图片压缩和文本截断，可以避开大部分失败。需要系统分享能力时，再看 uni.shareWithSystem。