简介这套资源面向微信小程序开发初学者与需要实现文件上传功能的开发者提供一套完整的前后端参考实现。前端为可直接运行的小程序demo覆盖图片与视频的选择、预览和上传逻辑后端为基于Flask的Python文件负责接收并存储上传文件到本地目录前后端配合即可快速跑通“小程序-服务器”上传链路。压缩包共12个文件以json、js、wxss、wxml等前端配置与逻辑文件为主辅以一个py后端脚本整体仅5KB结构紧凑、易于阅读适合作为改造原型直接嵌入到个人项目中。目前已有419人学习/下载说明该demo具有较高的参考价值。配套教程链接可供进一步参考遇到问题也可私信交流。通过该示例读者可以直观理解微信小程序上传接口的调用方式、Flask接收文件的处理流程以及本地存储目录的组织思路可作为课程设计或日常开发的快捷起点。 做小程序开发这一年多最常被身边朋友问到的一个需求就是“怎么把用户上传的图片视频存到后台” 说难吧官方文档里wx.uploadFile写得很清楚说不难吧等你真正联调的时候会发现从临时文件路径、后端接收方式、静态资源映射到上传大小限制每一步都可能卡你半天。这篇文章就把我整理好的前后端demo完整拆开讲直接给你一套能跑通的方案适合刚接触小程序文件上传、不清楚后端该写什么接口的开发者参考。1. 先把整个存储链路想明白再动手很多人一上来就写wx.chooseMedia选文件选完直接调上传接口结果后台不是收不到文件就是文件存了但访问不了。根本原因在于上传这个动作从来不是小程序单方面的事而是一条完整链路。这条链路涉及四个环节小程序端调用wx.chooseMedia拿到临时文件路径再用wx.uploadFile把文件以multipart/form-data的形式提交给后端。后端接口接收文件流校验格式和大小然后写入服务器磁盘或云存储。静态资源映射让上传后的文件能通过一个URL被访问到否则图片传上去了也在小程序里image显示不出来。鉴权与安全demo可以不做但至少要清楚生产环境该在哪里补token校验和访问权限。四个环节里最容易踩坑的是第三环。大多数人后端接口是写好了文件也落盘了但访问路径配置不对返回给小程序的就是一个404地址前端怎么调都显示不出图片。所以这个demo我会把静态资源映射也完整带上。另外要明确一点wx.uploadFile每次只能上传一个文件。虽然wx.chooseMedia能一次选9张图但那是在前端选择阶段的支持真正上传时你得循环调用上传接口一个文件一次请求。这个在后面代码部分会讲。2. 后端选择“本地目录静态映射”的原因与替代方案我自己做demo的时候后端用的是Spring Boot存储方案是“本地磁盘目录静态资源映射”。选择这个方案是因为它有一个其他方案比不了的优势零成本、零依赖本机一条命令跑起来就能联调。你不需要买云存储不需要配OSS的AccessKey不需要在内网穿透上折腾代码里也不需要引入任何额外的SDK。对于学习阶段、小范围内部使用、或者后端还在原型验证阶段的项目来说这是最顺手的方式。但如果你有经验会立刻意识到本地存储有几个问题服务器重启文件还在但换机器或扩容就丢了多个后端实例时文件散落在不同机器上磁盘空间容易被大视频打满。所以我想跟你同步一下真实的工业界方案这样你自己做选型时有参照不会被我这个demo局限住存储方案优点缺点适用阶段本地磁盘 静态映射零成本、调试方便无法水平扩展、容易丢demo、内测FastDFS / MinIO开源、可扩展需要额外部署维护小中型私有化项目阿里云OSS / 腾讯云COS高可用、上传直传带宽好需要配置密钥、可能有费用上线后的正式项目道理上我也多说一句demo阶段用本地存储是合理的但你在设计接口的时候要尽量把“接收文件”和“存储文件”两个动作解耦。比如把存储路径抽成一个配置项写成upload.dir将来从本地切到OSS只需要替换存储实现不需要改控制器接口。这个习惯养成后后期迁移会非常省心。3. 基于Spring Boot搭建文件接收服务后端我用的框架是Spring Boot 2.7.xJDK 8或11都行构建工具Maven。下面是一个最小但完整的文件上传接口能接收图片和视频并按日期分目录存储然后返回可直接访问的URL。3.1 核心依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency3.2 配置文件设置上传大小与静态映射先看配置文件application.yml的关键内容server: port: 8080 spring: servlet: multipart: max-file-size: 100MB max-request-size: 100MB # 自定义上传目录 upload: dir: ./upload # 将本地目录暴露为静态资源 spring: web: resources: static-locations: file:${upload.dir}/注意几个细节。第一spring.servlet.multipart.max-file-size是单个文件上限max-request-size是整个请求的上限。因为一个请求只传一个文件所以两个值设置成一样即可。第二Spring Boot 2.7里这个配置项是spring.web.resources.static-locations老版本可能是spring.resources.static-locations别记混。第三这里把整个upload目录映射成了根路径下的静态资源所以只要文件存到./upload/20240215/xxx.jpg访问http://localhost:8080/20240215/xxx.jpg就能直接打开。3.3 文件上传Controller完整实现RestController RequestMapping(/api/file) public class FileUploadController { Value(${upload.dir}) private String uploadDir; PostMapping(/upload) public MapString, Object upload(RequestParam(file) MultipartFile file) { // 1. 校验是否为空 if (file.isEmpty()) { throw new RuntimeException(文件不能为空); } // 2. 获取原始文件名和后缀 String originalFilename file.getOriginalFilename(); String suffix ; if (originalFilename ! null originalFilename.contains(.)) { suffix originalFilename.substring(originalFilename.lastIndexOf(.)); } // 3. 生成唯一新文件名避免重名覆盖 String datePath new SimpleDateFormat(yyyyMMdd).format(new Date()); String newFileName UUID.randomUUID().toString().replace(-, ) suffix; // 4. 保存文件到 upload/日期/新文件名 File dir new File(uploadDir File.separator datePath); if (!dir.exists()) { dir.mkdirs(); } File dest new File(dir, newFileName); try { file.transferTo(dest); } catch (IOException e) { throw new RuntimeException(文件保存失败, e); } // 5. 返回访问URL String url / datePath / newFileName; MapString, Object result new HashMap(); result.put(code, 0); result.put(message, 上传成功); result.put(data, url); return result; } }这里我做了一个关键设计前端图片的命名不用原始文件名而是用UUID重命名。原因很简单如果两个用户都传一张avatar.jpg后上传的会把先上传的覆盖掉。UUID保证文件名唯一另外还可以按日期分目录避免所有文件堆在一个文件夹里目录文件数量太大会影响访问速度。返回的data字段是相对路径比如/20240215/a3f9c2...jpg。小程序端拼上https://你的域名就能直接当图片地址用了。如果是在本地开发者工具里调试域名就是http://localhost:8080。3.4 关于静态资源映射的一个坑配置了spring.web.resources.static-locations之后默认的classpath:/static目录会被覆盖掉。如果你后端还有一些其他静态页面比如Swagger UI、自定义HTML会找不到。解决办法也很简单把你自己的静态目录和系统的静态目录都配上spring: web: resources: static-locations: file:${upload.dir}/, classpath:/static/这个问题一般要等你上传接口通了、顺便想看个Swagger接口文档的时候才会发现我先帮你埋个底。4. 小程序端核心代码从选择文件到提交上传后端接口准备好了接下来就看小程序端怎么写。这里有几个关键API我要先帮你理清楚因为很多人都是从这一步开始懵的。4.1 选择图片或视频wx.chooseMediawx.chooseMedia是官方推荐选择媒体文件的接口支持图片和视频基础库最低版本要求 2.10.0。它在开发者工具上表现可能和真机不完全一样所以涉及选择逻辑最后一定要真机调试。wx.chooseMedia({ count: 9, // 最多选择9个文件图片视频混合场景 mediaType: [image, video], // 同时支持图片和视频 sourceType: [album, camera], // 相册或拍摄 maxDuration: 60, // 视频最长时间单位秒 camera: back, // 默认后置摄像头 success: (res) { const files res.tempFiles; // files 数组里每一项包含 tempFilePath、size、duration 等字段 // 注意tempFilePath 是小程序临时文件路径直接拿去 image 预览没问题 // 但不能持久保存也没有实际业务意义需要上传到后台。 this.uploadFiles(files); } });这里有一个很多新手会忽略的点小程序给出的临时文件路径后缀名不一定真实。比如你明明拍了个视频tempFilePath可能是http://tmp/xxx.mp4也可能没有后缀。所以后端根据后缀判断文件类型时不要直接信任原始文件名最好是结合wx.chooseMedia返回的fileType字段在提交表单时附带typeimage或typevideo交给后端做二次校验。4.2 循环上传wx.uploadFile的正确用法wx.uploadFile不支持一次传多个文件正确的姿势是循环调用。为避免同时发太多请求把后端打崩以及避免用户看到进度错乱我用递归的方式一个接一个串行上传uploadFiles(files) { const uploadTaskList []; // 串行上传一个完成后再传下一个 const uploadNext (index) { if (index files.length) { // 全部上传完成 wx.showToast({ title: 全部上传完成, icon: success }); return; } const file files[index]; wx.uploadFile({ url: http://localhost:8080/api/file/upload, // 你的后端接口地址 filePath: file.tempFilePath, name: file, // 注意这里不要手动设置 Content-Type success: (res) { const data JSON.parse(res.data); if (data.code 0) { uploadTaskList.push(data.data); uploadNext(index 1); } else { wx.showToast({ title: 上传失败, icon: none }); } }, fail: (err) { console.error(upload fail:, err); wx.showToast({ title: 网络异常, icon: none }); } }); }; uploadNext(0); }上传过程中如果要显示进度可以用wx.uploadFile返回的UploadTask对象监听onProgressUpdate回调const task wx.uploadFile({...}); task.onProgressUpdate((res) { this.setData({ progress: res.progress }); });这里要特别提醒header里千万不要写Content-Type: multipart/form-data。网上很多教程会加这一行实际一写就报错因为wx.uploadFile内部会自己生成一个带boundary的Content-Type你手动指定后缺少boundary参数后端解析MultipartFile必挂。我见过不下十个朋友被这个问题折磨推荐的做法是header只放token之类的业务参数。4.3 上传前的必要校验小程序端可以做的校验其实有限但至少有三件事值得做文件大小校验视频文件动不动几十上百MB上传前先看tempFiles[i].size超过阈值直接拦截并提示用户避免浪费流量。类型白名单校验根据tempFiles[i].fileType判断是图片还是视频如果后端只允许特定格式前端先做一道过滤体验会好很多。数量与并发控制一次选9个文件就一个一个逐个传不要Promise.all并发9个请求小程序的并发上限和服务器压力都要考虑。示例片段const MAX_SIZE 100 * 1024 * 1024; // 100MB files.forEach(file { if (file.size MAX_SIZE) { wx.showToast({ title: 文件不能超过100MB, icon: none }); return; } });4.4 接收返回结果并更新页面上传成功后后端返回的是可访问的相对路径。前端把它拼上完整域名后可以直接塞回列表渲染const baseUrl http://localhost:8080; const fullUrl baseUrl data.data; this.setData({ fileList: [...this.data.fileList, { url: fullUrl, type: fileType }] });展示的时候图片用image标签视频用video标签两者通过type区分渲染即可。5. 我在实际联调中踩过的坑与对策跑通demo和线上可用的距离往往就隔着这些“特性”。下面几个问题是我在开发中真的遇到过的每个都花了不少时间排查这里一并整理给你。5.1 开发者工具正常手机上传却失败这是最高频的问题。开发者工具里http://localhost:8080能通但到了真机上小程序要求所有网络请求必须走HTTPS并且要在小程序后台配置合法域名。一条都缺真机就报request:fail url not in domain list。解决办法有两个层面。开发阶段在微信开发者工具中勾选“不校验合法域名”同时手机和电脑连同一局域网后端地址改成电脑的局域网IP比如http://192.168.31.24:8080。上线阶段域名必须是HTTPS备案后在小程序管理后台配置request和uploadFile合法域名。5.2 后台报错“Current request is not a multipart request”我排查过不少类似的报错原因集中在三个地方一是前端手动设置了Content-Type: multipart/form-data导致boundary丢失后端解析失败二是name属性值拼错前后端字段名不一致三是请求被某些代理或拦截器改写了Content-Type。解决办法很简单前端只传文件不手动设Content-Type后端用RequestParam(file) MultipartFile file接收前后端字段名严格一致。5.3 后端tomcat隐含上传大小限制Spring Boot内置Tomcat默认限制单次请求大小为2MB左右如果不做任何配置稍微大一点的视频上传时会报MaxUploadSizeExceededException。所以application.yml里的max-file-size和max-request-size一定要配置且要保证这两个值符合业务场景。我习惯将这两个参数提取到配置中心或环境变量因为开发、测试、生产环境的上传需求往往不一样。5.4 视频上传成功后在手机上无法播放这个坑比较隐蔽。本地电脑上浏览器能播放的MP4小程序里video组件可能播放不了。原因通常是编码格式问题浏览器对H.264支持很好但小程序要求视频编码为H.264AAC。解决办法有两个方向一是在选择视频时通过wx.chooseMedia的mediaType: [video]配合maxDuration限制但这不能强制编码二是后端做视频转码比如用FFmpeg将视频统一转成H.264/H.265 MP4格式。如果只是自己demo测试推荐先用电脑或手机默认拍摄的MP4文件测试等功能跑通以后再考虑转码服务。5.5 上传大视频时出现超时小程序的wx.uploadFile默认超时时间较短大概1分钟。上传大文件时经常连上但传不完就触发了timeout。解决方案是设置timeout参数wx.uploadFile({ url: https://yourdomain.com/api/file/upload, filePath: file.tempFilePath, name: file, timeout: 300000, // 5分钟超时 success: ... });但超时时间不是越长越好网络断掉时不能快速感知。更好的做法是结合UploadTask.onProgressUpdate展示进度并在进度长时间不更新时提示用户检查网络。6. 给这个demo加上基本的鉴权与安全机制严格来说任何生产环境都不应该让用户无鉴权地传文件。但很多初学demo都忽略了这一点将上传接口裸奔出去很快就会被恶意利用。这里我给出两个低成本高收益的做法。6.1 token鉴权前端在wx.uploadFile的header里带上登录态换取的用户token后端用一个拦截器校验。步骤很简单Component public class TokenInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String token request.getHeader(Authorization); // 校验 token 的合法性无效则返回401 return true; } }然后注册到WebMvcConfigurer里只拦截/api/file/upload这个路径。这样每次上传时后端就知道是哪个用户发的请求也能做用户上传配额控制。6.2 文件类型与内容校验不要只信文件后缀名因为攻击者可以伪造。比较稳妥的做法是上传后读取文件头魔数判断真实类型比如JPEG的文件头是FF D8 FFPNG是89 50 4E 47。图片可以直接用ImageIO.read(file.getInputStream())尝试解析解析失败就说明不是合法的图片文件。视频的校验更复杂一点至少可以检查文件大小、扩展名和上传时附带声明的type字段是否一致。6.3 访问权限控制如果你希望上传后的文件不是“任何拿到URL的人都能看”而是只有上传者自己或朋友可看那静态资源映射就不能直接对外暴露。有两种思路一是把文件放在不受静态映射保护的目录写一个/api/file/view接口动态校验权限后返回文件流二是使用带签名的URL用有效期参数做控制。demo阶段先知道有这回事等做正式项目时再按需选用。7. 前端上传页面的完整示例最后我贴一个能在小程序开发者工具里直接跑起来的页面代码。index.wxml、index.js、index.wxss三件套配合上面的Spring Boot后端就可以完成从选文件到展示的整个闭环。7.1 index.wxmlview classcontainer button typeprimary bindtapchooseMedia选择图片/视频/button view classpreview-list view classpreview-item wx:for{{fileList}} wx:keyurl image wx:if{{item.type image}} src{{item.url}} modeaspectFill / video wx:elif{{item.type video}} src{{item.url}} controls/video /view /view view classprogress wx:if{{progress 0 progress 100}} 上传进度{{progress}}% /view /view7.2 index.jsPage({ data: { fileList: [], progress: 0 }, chooseMedia() { wx.chooseMedia({ count: 9, mediaType: [image, video], sourceType: [album, camera], maxDuration: 60, success: (res) { this.setData({ progress: 0 }); this.uploadFiles(res.tempFiles); } }); }, uploadFiles(files) { const uploadNext (index) { if (index files.length) { wx.showToast({ title: 上传完成, icon: success }); return; } const file files[index]; const uploadTask wx.uploadFile({ url: http://localhost:8080/api/file/upload, filePath: file.tempFilePath, name: file, formData: { type: file.fileType // image 或 video }, success: (res) { const data JSON.parse(res.data); if (data.code 0) { const baseUrl http://localhost:8080; this.setData({ fileList: [...this.data.fileList, { url: baseUrl data.data, type: file.fileType }] }); uploadNext(index 1); } else { wx.showToast({ title: 上传失败, icon: none }); } }, fail: (err) { console.error(upload fail:, err); wx.showToast({ title: 上传失败, icon: none }); } }); uploadTask.onProgressUpdate((res) { this.setData({ progress: res.progress }); }); }; uploadNext(0); } });7.3 这段代码里我特意留的两个细节第一个formData里放了type字段区分图片和视频。后端在upload方法里再加一个RequestParam(type) String type参数就可以针对不同类型做不同的大小上限校验和后续处理。第二个uploadNext用递归而不是for循环是为了保证“上一个传完再传下一个”。如果你用for循环配合异步上传9个文件会同时发起请求进度回调交叉混乱后端压力也大对用户来说是反效果。8. 关于上传后文件的清理与备份这个点很少在demo里被提到但真正跑起来之后你会遇到一个现实问题上传目录越来越大。一个带有视频上传功能的小程序上线一个月可能就能积累几十GB素材。我的建议是至少做两个事一是定期清理。写一个定时任务删除指定天数前的临时性文件。图片和视频如果属于用户生成内容不能随便删所以这个定时任务只适用于“明确知道可以清理”的文件比如7天内未激活的临时上传或匿名上传。二是目录按日期归档。我demo里已经按日期分目录存储按天归档的好处是备份可以只备份新增的当天目录清理时删掉过期日期目录也非常顺手。目录结构类似upload/20240215/、upload/20240216/非常清晰。三是如果上传量大建议后端直接将文件存到云存储服务。上传接口从“接收后转存本地”改成“接收后转存OSS”在代码层面差异不大但管理能力、访问加速和容灾能力会好很多。这部分在你进入下一个阶段再重构也不迟。我自己做这类功能时有个习惯就是先把这个demo跑通再根据实际情况决定要不要引入更重的组件。很多刚学小程序开发的同学容易一开始就追求“完整架构”而卡在各种配置上反而阻碍了对官方API本身的理解。你现在拿这套代码跑通一次理解了文件是怎么从手机到后台再到URL展示出来的后面不管往哪个方向扩展心里就都有底了。本文还有配套的精品资源点击获取