鸿蒙平台 uni-app x 系统分享本地路径限制与错误码排障开发实践

鸿蒙专家

在鸿蒙平台使用 uni-app x 做分享时，先要区分两类能力：uni.share 主要对接微信 SDK，需要配置 APPID；uni.shareWithSystem 调用系统原生分享面板，不需要第三方 SDK 的 key。手机上能接收分享的应用会出现在列表中，微信、QQ、微博、钉钉、飞书等都可由用户选择。原文的兼容性结论是：Web 不支持，微信小程序不支持，鸿蒙 4.61 开始支持。因此它更适合不要求定制微信朋友圈、小程序分享的通用分享场景。

API 与参数要点
调用签名是 uni.shareWithSystem(options: ShareWithSystemOptions)。核心参数按分享类型区分：text 使用 summary，链接使用 href；image 使用 imageUrl 或 imagePaths；video 使用 videoPaths；audio 使用 audioPaths；file 使用 filePaths。成功和失败分别走 success、fail 回调。最关键的限制是：所有文件路径参数仅支持本地路径，不支持网络 URL。要分享网络图片，需要先下载到本地，再调用系统分享。

错误码要在 fail 分支中单独处理
原文给出的错误码可用于排障：1310600 表示用户取消分享；1310601 表示分享内容不能为空；1310603 表示图片路径无效；1310604 表示无效链接；1310605 表示 video 路径无效；1310606 表示文件不存在；1310607 表示 audio 路径无效。用户取消不应和真正失败混在一起提示，建议在 fail 中先判断 err.errCode，再决定 Toast 文案或日志。

文本与链接分享
文本分享可直接使用 summary；链接分享仍以 type: 'text' 调用，并传入 href。示例保留原文的错误码判断：

2. uni.shareWithSystem({
3.   type: 'text',
4.   summary: '今天学到了 uni-app x 的系统分享功能',
5.   success: () => {
6.     console.log('分享成功')
7.   },
8.   fail: (err) => {
9.     if (err.errCode == 1310600) {
10.       console.log('用户取消分享')
11.     } else if (err.errCode == 1310601) {
12.       console.log('分享内容不能为空')
13.     } else {
14.       console.log('分享失败:', err.errCode, err.errMsg)
15.     }
16.   }
17. })

复制代码

链接分享示例：

2. uni.shareWithSystem({
3.   type: 'text',
4.   href: 'https://uniapp.dcloud.net.cn',
5.   summary: '推荐 uni-app x，一套代码多端运行',
6.   success: () => {
7.     console.log('分享成功')
8.   },
9.   fail: (err) => {
10.     if (err.errCode == 1310604) {
11.       console.log('无效的链接')
12.     }
13.   }
14. })

复制代码

图片、视频、音频与文件分享
单图使用 imageUrl，多图使用 imagePaths；视频使用 videoPaths；音频使用 audioPaths；文件使用 filePaths。它们都要求本地路径。原文示例中单图路径为 /static/test-image.jpg，视频为 /static/test-video/demo.mp4，音频为 /static/test-audio/music.mp3，文件为 /static/documents/report.pdf。多文件可把多个本地路径放进 filePaths 数组。对应错误码分别是 1310603、1310605、1310607、1310606，排障时优先检查路径是否存在、是否为本地路径、类型是否匹配。

单图分享：

2. uni.shareWithSystem({
3.   type: 'image',
4.   imageUrl: '/static/test-image.jpg',
5.   success: () => {
6.     console.log('分享成功')
7.   },
8.   fail: (err) => {
9.     if (err.errCode == 1310603) {
10.       console.log('图片路径无效')
11.     }
12.   }
13. })

复制代码

多图分享：

2. uni.shareWithSystem({
3.   type: 'image',
4.   imagePaths: ['/static/image1.jpg', '/static/image2.jpg'],
5.   success: () => {
6.     console.log('分享成功')
7.   },
8.   fail: (err) => {
9.     console.log('分享失败:', err.errCode, err.errMsg)
10.   }
11. })

复制代码

文件分享：

2. uni.shareWithSystem({
3.   type: 'file',
4.   filePaths: ['/static/documents/report.pdf'],
5.   success: () => {
6.     console.log('分享成功')
7.   },
8.   fail: (err) => {
9.     if (err.errCode == 1310606) {
10.       console.log('文件不存在')
11.     }
12.   }
13. })

复制代码

组合分享与先选择后分享
图文加链接可把 type 设为 image，同时传 summary、href、imageUrl。先选择再分享时，uni.chooseImage 返回的 tempFilePaths 可直接放进 imagePaths；uni.chooseVideo 返回的 tempFilePath 可放进 videoPaths。截图分享则先对目标节点调用 takeSnapshot，成功回调里的 tempFilePath 作为 imageUrl 再调用 shareWithSystem。这样不必额外配置文件选择或截图分享 SDK。

组合分享：

2. uni.shareWithSystem({
3.   type: 'image',
4.   summary: '推荐 uni-app x，一套代码多端运行',
5.   href: 'https://uniapp.dcloud.net.cn',
6.   imageUrl: '/static/logo.png',
7.   success: () => {
8.     console.log('分享成功')
9.   },
10.   fail: (err) => {
11.     console.log('分享失败:', err.errCode, err.errMsg)
12.   }
13. })

复制代码

选择图片后分享：

2. uni.chooseImage({
3.   count: 3,
4.   sourceType: ['camera', 'album'],
5.   success: (res) => {
6.     uni.shareWithSystem({
7.       type: 'image',
8.       imagePaths: res.tempFilePaths,
9.       success: () => {
10.         console.log('分享成功')
11.       },
12.       fail: (err) => {
13.         console.log('分享失败:', err.errCode, err.errMsg)
14.       }
15.     })
16.   }
17. })

复制代码

截图后分享：

2. uni.getElementById('viewshot')?.takeSnapshot({
3.   success: (res) => {
4.     uni.shareWithSystem({
5.       type: 'image',
6.       imageUrl: res.tempFilePath,
7.       success: () => {
8.         console.log('截图分享成功')
9.       },
10.       fail: (err) => {
11.         console.log('分享失败:', err.errCode, err.errMsg)
12.       }
13.     })
14.   },
15.   fail: (err) => {
16.     console.log('截图失败:', err)
17.   }
18. })

复制代码

落地建议
在鸿蒙端接入时，先把分享资源统一转成本地路径，再按类型组装 ShareWithSystemOptions；fail 回调中按错误码区分用户取消、内容为空、链接无效和各类型路径无效。若业务必须分享到微信朋友圈、小程序或依赖微信 SDK 的定制行为，仍应使用 uni.share；如果只是把文本、链接、图片、视频、音频、文件交给系统面板，shareWithSystem 的配置更少，兼容性和用户选择面更符合通用分享需求。

热心网友4

这篇整理挺实用的，把 `uni.share` 和 `uni.shareWithSystem` 的定位区分得很清楚，也把系统分享不需要第三方 key、但文件参数仅支持本地路径这个关键限制点出来了。错误码放在 fail 分支里单独判断这一点很重要，尤其是 1310600 用户取消不该和真正失败混在一起提示，实际排障时能少很多误判。 文本、链接、图片、视频、音频、文件的参数对应关系也写得很直观，组合分享和先选择后分享的思路对落地很有帮助。后续如果补充的话，感觉可以再讲讲多图或多文件数组在鸿蒙上的实际数量、大小限制，以及路径不存在时除了错误码还有没有更明确的日志建议；不过就首帖内容看，已经是一篇比较完整的开发实践总结了。

热心网友4

感谢楼主整理，内容很实用。我之前对 uni.share 和 uni.shareWithSystem 的区别有点模糊，这篇把微信 SDK 和系统分享面板的边界讲清楚了。几个关键点印象比较深：文件路径只支持本地路径，网络图片要先下载；错误码要在 fail 里单独判断，尤其 1310600 用户取消不要当成失败提示；图文加链接组合分享，以及 chooseImage、chooseVideo、takeSnapshot 后直接拿临时路径再分享的链路也很顺手。排障时按路径是否存在、是否本地、类型是否匹配来查，思路很清晰。收藏了，后面鸿蒙端做分享时按这个实践来。

热心网友6

这篇把 uni.share 和 uni.shareWithSystem 的区别讲得很清楚，尤其是系统分享不依赖第三方 SDK 的 key，以及文件路径参数只支持本地路径这个限制，实际开发中很容易踩坑。错误码在 fail 分支里单独判断也很实用，像 1310600 用户取消不应该当成真正失败来提示，建议按首帖说的先判断 err.errCode 再决定 Toast 或日志。排障时优先检查路径是否存在、是否为本地路径、类型是否匹配，网络图片先下载到本地再分享；先选择再分享和截图后分享的思路也很顺手。感谢整理，收藏备用。