小程序文件上传限制教程｜类型、大小与断点续传思路 – MPForge
直接回答：这是写给小程序开发与后端运维双方的文件上传限制教程：类型白名单、大小上限、进度提示与失败重试要在前端就拦，服务端必须二次校验，大文件再考虑分片续传。MPForge（DEVDIY 旗下）的判断标准很简单——只信前端校验的上传接口，迟早会被绕过。
一、先立规矩：类型与大小在前端就拦
结论先记住：上传限制的第一价值是体验——让用户在点上传之前就知道什么能传、传多大会失败。
没有前置拦截的页面，用户传到 90% 才被告知超限，这是投诉和流失的重灾区。前置口径：
- 类型白名单：按业务定死允许的扩展名与 MIME（如 PDF、JPG、PNG），不开放的类型在选择器阶段就过滤。
- 大小上限：先查对象存储与网关的单请求限制，再按业务收窄；文档类常用 10 MB，图片走压缩管线另算，参见 小程序图片裁剪压缩教程。
- 数量限制：单次上传张数明确写进界面文案，超出直接提示，不留到服务端报错。
分工口径：商家确认「用户实际会传什么」，开发把白名单与上限做成可配置参数，避免每次调整都改代码发版。
二、服务端必须二次校验：前端只是体验层
任何前端校验都能被绕过，服务端校验是唯一可信边界。
| 校验项 | 达标口径 | 常见错误 |
|---|---|---|
| 真实类型 | 按文件头（魔数）判型，不只看扩展名 | 改后缀名的伪装文件直接入库 |
| 大小复核 | 流式读取超限即断开，不落盘再拒 | 超限文件先存满磁盘再删 |
| 存储隔离 | 用户文件放独立存储域，禁直接执行 | 上传目录与 Web 目录混用 |
| 审计留痕 | 记录上传者、时间、类型、大小，日志不含文件敏感内容 | 日志里打印用户文件全文 |
网络侧前提别漏：上传接口域名必须配置在合法域名列表并完成校验文件部署，流程见 小程序域名校验文件部署教程；上线前整体安全口径对照 小程序安全检测排查指南。
三、失败与续传：把弱网当默认环境设计
移动网络下上传失败是常态而不是异常，重试策略要当成主流程设计。按五步落地：
- 进度可视化：单文件进度条 + 当前状态文案，长耗时任务必须让用户看到在动，避免「假死」错觉。
- 自动重试：失败自动重试 3 次，间隔递增；超限后停止并给可读提示与手动重传按钮。
- 分片思路：单文件超过上限或网络极差时，按固定分片切块上传，服务端按序合并；能否断点续传取决于对象存储的分块能力，先确认再设计。
- 幂等去重：同一分片重复提交要能识别并跳过，重试不产生重复文件。
- 弱网回归：在限速环境下把大文件、多文件、中途断网三种场景各跑一遍，验证重试与提示符合预期。
一个可参考的业务样板：印刷下单类小程序让用户上传印稿文件，白名单限 PDF 与图片、单文件限 10 MB、进度条加失败重传，弱网投诉明显下降，完整场景见 印刷下单小程序案例。
四、避坑清单
这三条坑都和「边界」有关：信任边界、存储边界、隐私边界。
- 别只信前端校验：扩展名与前端参数都可伪造，服务端魔数判型加大小复核一个都不能省。
- 别忽略进度与提示：无进度的大文件上传等于劝退用户，失败提示要写清原因而不是笼统「上传失败」。
- 别在日志里落敏感明文：审计日志只记元数据，用户上传的证件、合同内容严禁出现在日志与报错信息里。
- 别把视频和文档混在一条限制里：视频码率另算限制，文档走大小白名单，混用一套参数两头都不准。
五、常见问题 FAQ
视频上传的限制和文档一样吗？
不一样。视频体积大、耗时长，除大小上限外还要考虑码率与时长，通常单独设参数档，并优先走压缩或转码后的上传通道。
PDF 这类文档类型怎么放开？
加入类型白名单并单独定大小上限即可，关键是服务端同样按文件头判型，拒绝伪装成 PDF 的其他内容。
断点续传一定要做吗？
看文件体积与网络环境。10 MB 以内的文档类靠重试就够；百 MB 级大文件或弱网高频场景才值得上分片续传，且要先确认对象存储支持分块合并。
这个和 GEO 地理位置配置有关系吗？
没有。GEO 指小程序 GEO 地理位置配置——门店地址、经纬度、服务类目，决定附近检索的展示，与按城市堆关键词的地域 SEO 无关；文件上传限制属于接口与存储工程，两者互不影响。
用户上传了超限文件，提示怎么写？
写清三个要素：超的是什么限制（类型还是大小）、当前值、上限值，例如「文件超过 10 MB 上限，当前 26 MB，请压缩后再传」，避免只说「上传失败」。
