小程序文件上传实务｜表单字段、进度回调与失败重试 – MPForge

一、上传失败先查这三处，别急着改代码

结论句：大部分「上传失败」的根因在前端与服务端的约定错位上，按固定顺序排查十分钟内能定位。现场最常见的是三类翻车：字段名与后端不一致——前端写 file、后端收 upload，报错却只在 HTTP 层；域名没加进小程序后台的 uploadFile 合法域名列表，真机上直接被拦截；超时设太短，弱网下大图还没传完就被掐断，用户看到「网络错误」却不知道该做什么。商家这边要留意的是：如果用户反馈集中出现「传不上去」，先让客服记录发生时间与网络环境，再交给开发对照下表逐项核对。

二、标准链路：队列上传、进度、草稿与回写

结论句：上传要做成可重试队列，而不是一次选一批就同步死等。我们交付时把证照与现场图统一走这条链路，五步落地：

1. 选图即压缩：选完媒体先压到 1–2MB 再入队，参考 选择媒体与压缩口径，避免一次选几十张原图直接挤爆弱网。
2. 入队串行传：多文件逐个上传，前端维护队列状态，用户能看见「第 2/5 张」这类进度，不再重复点击。
3. 进度要回调：接住上传进度回调，页面显示百分比；大文件强烈建议做，否则用户以为卡死。
4. 失败留草稿：失败的文件连同业务单号留在本地草稿，token 过期先静默续期再重试，重试仍失败才提示。
5. 成功即回写：上传成功把文件地址回写到工单或订单，后续履约环节用同一份记录，避免口头转述。

验收口径就一条：弱网用例必测——把手机切到弱网模拟，走完「选图→上传→断网→重试→成功」全程，草稿不丢、单据不少。

三、和下载、接口体系的衔接

结论句：上传不是孤立功能，要放进整个接口体系里对齐。用户上传的凭证图，客服与后台要能原样取回，下载侧口径见 小程序文件下载教程；整体接口怎么组织、域名与鉴权怎么统一，先过一遍 小程序接口总览。两边的字段对照表放同一份接口文档首页，改字段名必须同步改文档——这是踩过坑之后的硬规矩。明确没做的两件事：一次选 50 张无压缩直传，以及主线程同步死等上传结果，这两条都会直接拖垮体验。

四、隐私与合规：证照类文件要格外克制

结论句：证照类上传遵守最小化原则，收集范围、保存期限、删除路径三件事都要能说清。实名人证只在必须实名履约的场景收集，能不存原始图就不存；保存位置与期限写进隐私指引，弹窗时机按 小程序隐私弹窗时机教程 对齐，别在上传中途才弹授权。带二维码的打印原文件要防止被当作可编辑素材外流，展示层加水印或缩略图。如果类目审核因此被打回，对照 小程序审核被拒常见原因 先改收集说明再重提。

五、避坑清单

这三条坑都出在「用户视角缺失」上：不压缩、不续期、不给下一步。

• 别传原图不压缩：手机原图动辄 5MB 以上，弱网必超时；入队前统一压缩是成功率的第一道保险。
• 别让 token 过期裸奔：上传中途凭证失效要静默续期后重试，直接把 401 抛给用户等于放弃这单。
• 别只弹「网络错误」：失败提示必须带动作——「已保留草稿，可在网络恢复后重试」，否则用户只会狂点。

六、常见问题 FAQ