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

适用场景:uni-app(Vue2/Vue3)微信小程序,附件预览(openDocument)、转发(shareFileMessage)、下载(saveFileToDisk)。项目的实战踩坑,通用化整理,可复用到含「附件查看」的小程序。
一、核心结论(速查表)
wx.openDocument | fileType 参数 | illegal file extname |
wx.shareFileMessage | ||
wx.saveFileToDisk | ||
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.tempFilePathif (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. 分流策略(推荐交互)
要点:
下载图标必须 @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 挂掉 |
# | |
? |
前端三层防御:
// 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.tempFilePathif (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不生效(小程序端尤其如此),长文件名会顶破容器。
五、已知代价与注意事项
USER_DATA_PATH 文件堆积:每次预览/下载都落一个文件,无自动清理。小程序本地缓存会缓慢增长。可接受;如需治理,按 preview_/download_前缀定期fs.unlink即可基础库要求: downloadFile的filePath参数需 2.17.0+(2021 年起的版本都满足,现网基本无忧)条件编译:微信专属 API( wx.env、shareFileMessage、saveFileToDisk)都要包#ifdef MP-WEIXIN,非微信端回退原逻辑,避免编译报错与运行时异常saveFileToDisk 的默认文件名 = 本地文件 basename。想要对话框默认显示原文件名,就把落盘文件直接命名为原文件名(注意重名覆盖问题,可用 时间戳_原名折中)多端行为一致性:改公共组件前,先列出全部引用处做影响面分析;上传链路(大小限制、特殊符号拦截)与预览链路分开评估
六、上线前检查清单
手机端:图片、文档、压缩包、视频四类点击行为全部正常 PC 端(Windows/Mac 微信):文档预览不报 illegal file extnamePC 端:下载图标弹出系统另存为,保存文件后缀正常(无 .bin)PC 端:压缩包/视频点击走另存为(不静默失败) fileType脏值( .PDF、pdf、MIME)可正常预览文件名含中文、空格、括号、 %等的展示不白屏(decodeURIComponent 有 try/catch)文件名含 `%?` 的文件被上传拦截 saveFileToDisk用户取消不弹错误提示 非微信端(H5 等)编译通过、不调用 wx.*专属 API
七、经验复盘
「端差异」不是边缘 case:只要有客户/管理端在 PC 微信里用小程序,预览下载就必须双端适配,开发时就把分流写进去,别等 PC 反馈 错误信息会误导排查方向: illegal file extname看起来像 fileType 传错,实际是本地文件没有扩展名。先复现并定位「校验的到底是什么」,再动手改参数项目里往往已有正确答案:导出 PDF 链路在 PC 一直正常,它用的「持久化路径 + 后缀」就是解法——改公共组件前先全局搜同类场景( openDocument/saveFileToDisk/USER_DATA_PATH),复用已验证模式防御要分层:展示容错(try/catch 解码)、入口拦截(上传校验)、根因治理(后端编码),三层各管一段,缺一层就会在另一层爆















































































