夜雨聆风学习资料网

ARTICLE · 1380989

微信小程序文件预览与下载:手机端 / PC 端适配经验总结

微信小程序文件预览与下载:手机端 / PC 端适配经验总结
最近处理小程序预览pdf,doc,docx,excel,png等功能。在常规场景,例如手机端使用小程序,都比较好处理,兼容性也比较好。但是客户真实场景是在电脑端使用小程序希望与之前用的web版一样。但是由于小程序的沙盒原因与能力边界问题等。记录下处理经验。
一开始方案是AI给的,实际用下来后是错误,讽刺的是,后续方案也是AI给的。使用AI有时候,就是一场持久的拉锯战,总能找到答案。

适用场景:uni-app(Vue2/Vue3)微信小程序,附件预览(openDocument)、转发(shareFileMessage)、下载(saveFileToDisk)。项目的实战踩坑,通用化整理,可复用到含「附件查看」的小程序。


一、核心结论(速查表)

能力
手机端(iOS/Android)
PC 端(Windows/Mac 微信)
wx.openDocument
 预览
正常,尊重 fileType 参数
校验本地文件的真实扩展名,临时文件会报 illegal file extname
wx.shareFileMessage
 转发
正常
不支持,fail 回调静默(只 console.error),表现为「点了没反应」
wx.saveFileToDisk
 另存为
不支持
仅 PC 支持,弹系统另存为对话框
wx.downloadFile
 临时文件
可直接预览
没有可靠的本地扩展名 → 预览报错、另存为被追加 .bin

一句话方案:PC 端必须「持久化路径 + 真实后缀」落地文件,再决定预览还是另存为。

// downloadFile 显式指定持久化路径(带真实后缀),基础库 2.17.0+ 支持wx.downloadFile({    url,    filePath: `${wx.env.USER_DATA_PATH}/download_${Date.now()}.${ext}`,    success: (res) => {        const filePath = res.filePath || res.tempFilePath        if (isPcWeixin()) {            return wx.saveFileToDisk({ filePath })   // PC:弹另存为        }        wx.openDocument({ filePath, showMenu: true }) // 手机:预览    },})

二、端差异全景与判定

1. PC 端判定

// 微信 PC 端(Windows/Mac 微信里打开小程序)const isPcWeixin = () => {    const { platform } = uni.getSystemInfoSync()    return platform === 'windows' || platform === 'mac'}

2. 分流策略(推荐交互)

用户动作
PC 端
手机端
点文件行(本体)
预览(openDocument)
预览 / 按类型分流(图片 previewImage、文档 openDocument、压缩包/视频转发)
点下载图标
系统另存为(saveFileToDisk)
与行点击一致(或转发)

要点:

  • 下载图标必须 @click.stop 拦截冒泡,否则会触发整行的预览
  • PC 端压缩包/视频无法预览,唯一可用动作就是另存为——不要试图在 PC 上预览它们
  • saveFileToDisk
     的 fail 里要放过用户主动取消(errMsg.includes('cancel') 不提示)

三、关键坑与解法

坑 1:PC 端预览报 openDocument:fail illegal file extname

现象:同一份 docx,手机端预览正常,PC 端点开报错。

排查误区(真实经历):一开始怀疑是 fileType 参数没传或传了脏值。实际上接口返回的 name/url 都带正确扩展名,fileType 也是合法的——传了合法 fileType 依然报错。

根因:PC 端 openDocument 校验的是本地文件路径上的扩展名,fileType 参数在 PC 端不可靠。downloadFile 的临时文件在 PC 上没有扩展名,所以无论 fileType 怎么传都过不了校验。

解法:下载时显式指定持久化路径并带上真实后缀(见速查表代码)。本地文件有了扩展名,openDocument(含显式 fileType)即可通过——这也是很多项目里「导出 PDF」在 PC 端一直正常的原因,它早就用了这个模式。

坑 2:PC 端另存为文件变成 xxx.docx.bin

现象:saveFileToDisk 保存出来的文件名被追加 .bin。

根因:同坑 1——临时文件没有扩展名,PC 端识别不了类型就按 .bin 落盘。

解法:同样指定持久化路径 + 真实后缀。saveFileToDisk(filePath) 拿到的文件带正确扩展名后,另存为对话框默认名也是正常后缀(注意:路径里的文件名就是对话框默认名,用 时间戳_原名 会显示时间戳前缀,需要原名可直接用原文件名做 basename)。

坑 3:PC 端点「转发」没反应

现象:手机端能转发文件,PC 端点了毫无反馈。

根因:shareFileMessage 仅手机端支持,PC 端 fail 静默。

解法:所有调用 shareFileMessage 的分支都必须有 PC 兜底(另存为)。反之,saveFileToDisk 仅 PC 支持,手机端不能走。

坑 4:fileType 脏值(历史数据)

历史数据可能存 .pdf(带点)、PDF(大写)、甚至 MIME 形式。openDocument 的 fileType 传非法值直接 fail。

解法:统一清洗后再用,不在白名单就不传(回退由端内推断):

// 取后缀:去 query、去点、转小写,无后缀返回空串const pickFileExt = (name) => {    const cleanName = String(name || '').split('?')[0]    const dot = cleanName.lastIndexOf('.')    return dot < 0 ? '' : cleanName.slice(dot + 1).toLowerCase()}const DOC_TYPES = ['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'pdf']const ext = pickFileExt(row.filetype) || pickFileExt(row.name)

坑 5:文件名含特殊符号(%?)

这是与下载/预览并行的另一层问题,影响的是 URL 与渲染:

符号
影响
%
裸 % 是非法百分号序列,decodeURIComponent 抛 URIError。若在 Vue 渲染函数(如 computed/方法)里同步调用,会中断整个组件渲染,页面白屏——不是「某个文件名显示错」,而是整块 UI 挂掉
#
URL 片段分隔符,路径被静默截断 → 404
?
查询参数分隔符,同上

前端三层防御:

// 1) 展示层容错:解码失败回退原文,绝不让渲染中断const getFileName = (url) => {    const raw = url.split('?')[0].split('/').pop() || '附件'    try {        return decodeURIComponent(raw)    } catch (e) {        return raw    }}// 2) 上传层拦截:特殊符号直接拒绝(在统一上传入口做,全项目生效)if (/[%#?]/.test(file.name)) {    uni.showToast({ title: '文件名含特殊符号 % # ?,请重命名后再上传', icon: 'none' })    return}// 3) 下载/预览层:带真实后缀落盘后,URL 拼接问题与本地文件名解耦

后端配套(需转交):

  • 上传接口同样校验文件名特殊符号(前端拦截可被绕过)
  • 文件 URL 生成若用半编码(只编码非 ASCII、保留 %),nginx 会 400、重复解码会 500——要么全量编码,要么不编码
  • 历史坏 URL 数据需一次性治理(改库中文件名即可恢复)

四、落地模板(通用附件组件片段)

以下是从公共附件组件里抽出的通用逻辑,可直接抄:

// ---------- PC 判定 ----------const isPcWeixin = () => ['windows', 'mac'].includes(uni.getSystemInfoSync().platform)// ---------- 带真实后缀的持久化路径 ----------// PC 端 openDocument / saveFileToDisk 都依赖本地文件扩展名;// 临时文件无后缀 → 预览报 illegal file extname、另存为被存成 .binconst buildLocalPath = (ext, prefix = 'download') =>    `${wx.env.USER_DATA_PATH}/${prefix}_${Date.now()}${ext ? '.' + ext : ''}`// ---------- 下载(PC 另存为 / 手机预览分流) ----------const downloadFile = (row) => {    if (!row.url) return uni.showToast({ title: '文件不存在', icon: 'none' })    const ext = pickFileExt(row.name)    uni.showLoading({ title: '下载中', mask: true })    uni.downloadFile({        url: row.url,        filePath: buildLocalPath(ext),        success: (res) => {            uni.hideLoading()            if (res.statusCode !== 200) {                return uni.showToast({ title: '下载失败', icon: 'none' })            }            const filePath = res.filePath || res.tempFilePath            if (isPcWeixin()) {                wx.saveFileToDisk({                    filePath,                    success: () => console.log('保存成功'),                    fail: (err) => {                        // 用户在另存为对话框点取消,不提示                        if (!err.errMsg.includes('cancel')) {                            uni.showToast({ title: '保存失败', icon: 'none' })                        }                    },                })            } else {                wx.openDocument({ filePath, showMenu: true })            }        },        fail: () => {            uni.hideLoading()            uni.showToast({ title: '下载失败', icon: 'none' })        },    })}

模板层(预览行 + 下载图标分离):

{{ item.name }}
.file-row { display: flex; align-items: center; }.file-icon { flex-shrink: 0; }.file-name {    flex: 1;    min-width: 0;    overflow: hidden;    text-overflow: ellipsis;    white-space: nowrap;}.download-btn { flex-shrink: 0; padding: 10rpx; }

注意:.file-name 必须是块级元素(<view>),不要用 <text>——inline 元素在 flex 行内 text-overflow: ellipsis 不生效(小程序端尤其如此),长文件名会顶破容器。


五、已知代价与注意事项

  1. USER_DATA_PATH 文件堆积:每次预览/下载都落一个文件,无自动清理。小程序本地缓存会缓慢增长。可接受;如需治理,按 preview_ / download_ 前缀定期 fs.unlink 即可
  2. 基础库要求:downloadFile 的 filePath 参数需 2.17.0+(2021 年起的版本都满足,现网基本无忧)
  3. 条件编译:微信专属 API(wx.env、shareFileMessage、saveFileToDisk)都要包 #ifdef MP-WEIXIN,非微信端回退原逻辑,避免编译报错与运行时异常
  4. saveFileToDisk 的默认文件名 = 本地文件 basename。想要对话框默认显示原文件名,就把落盘文件直接命名为原文件名(注意重名覆盖问题,可用 时间戳_原名 折中)
  5. 多端行为一致性:改公共组件前,先列出全部引用处做影响面分析;上传链路(大小限制、特殊符号拦截)与预览链路分开评估

六、上线前检查清单

  • 手机端:图片、文档、压缩包、视频四类点击行为全部正常
  • PC 端(Windows/Mac 微信):文档预览不报 illegal file extname
  • PC 端:下载图标弹出系统另存为,保存文件后缀正常(无 .bin)
  • PC 端:压缩包/视频点击走另存为(不静默失败)
  • fileType
     脏值(.PDF、pdf、MIME)可正常预览
  • 文件名含中文、空格、括号、% 等的展示不白屏(decodeURIComponent 有 try/catch)
  • 文件名含 `%?` 的文件被上传拦截
  • saveFileToDisk
     用户取消不弹错误提示
  • 非微信端(H5 等)编译通过、不调用 wx.* 专属 API

七、经验复盘

  1. 「端差异」不是边缘 case:只要有客户/管理端在 PC 微信里用小程序,预览下载就必须双端适配,开发时就把分流写进去,别等 PC 反馈
  2. 错误信息会误导排查方向:illegal file extname 看起来像 fileType 传错,实际是本地文件没有扩展名。先复现并定位「校验的到底是什么」,再动手改参数
  3. 项目里往往已有正确答案:导出 PDF 链路在 PC 一直正常,它用的「持久化路径 + 后缀」就是解法——改公共组件前先全局搜同类场景(openDocument/saveFileToDisk/USER_DATA_PATH),复用已验证模式
  4. 防御要分层:展示容错(try/catch 解码)、入口拦截(上传校验)、根因治理(后端编码),三层各管一段,缺一层就会在另一层爆

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料