小程序上传图片视频到Flask后台：完整实现与避坑指南

简介这份资源面向微信小程序开发者与Flask后端初学者提供图片、视频上传至服务器存储的完整前后端示例可直接运行调试适合想打通小程序文件上传链路、理解前后端交互流程的初中级开发者参考。压缩包共12个文件约5KB包含5个json配置、3个js逻辑脚本、2个wxss样式、1个wxml页面结构以及1个py后端文件前端为可直接打开的微信小程序demo后端为可独立启动的Flask服务目录中区分了图片与视频上传模块便于按需查阅。已有421人学习下载说明该示例在实际开发中具有一定参考价值。读者可从中获得小程序端选择与上传媒体文件的页面写法、Flask接收并保存文件的接口实现以及前后端联调时的参数传递与路径处理思路适合作为课程作业、练手项目或功能原型的起点遇到问题也可与作者交流讨论。1. 小程序上传图片视频到后台存储一个能跑通的 Flask 落地样板图片和视频上传看着简单真到小程序里跑一遍问题全冒出来前端wx.uploadFile只支持单文件、后端 Flask 默认表单大小限制卡在 16MB、视频动辄几十兆直接 413、文件名重复覆盖、临时目录权限不对、真机调试还得分清localhost和局域网 IP。这套 demo 的价值就在于把这些零散环节串成一条能跑通的链路——小程序端选文件、上传、拿回可访问地址Flask 端接收、校验、落盘、返回 JSON。它适合两类人一是刚接触小程序文件上传、想找个完整骨架改的开发者二是手里有 Flask 后台、需要补上传接口的从业者。下面按「先跑通、再拆参数、最后避坑」的顺序拆代码可以直接抄坑我提前标出来。2. 链路拆解小程序端选文件与上传请求怎么发小程序上传不是浏览器那套FormDatawx.uploadFile是独立 API参数结构和wx.request差别不小。先把前端这一侧讲透不然后端收不到文件还以为是服务端问题。2.1 选图与选视频的两套 API图片用wx.chooseMedia新版统一入口wx.chooseImage已不推荐视频同样走wx.chooseMedia但mediaType传[video]。关键参数是count最多选几个、mediaTypeimage/video/mix、sourceType相册还是拍摄、maxDuration视频最长秒数默认 10 秒超过会被截断。选完拿到的是临时路径tempFilePath这个路径只在当前会话有效必须尽快上传别存起来下次用。// pages/upload/upload.js Page({ data: { imageUrl: , videoUrl: }, // 选图片count 控制数量sizeType 选压缩图省流量 chooseImage() { wx.chooseMedia({ count: 1, mediaType: [image], sourceType: [album, camera], sizeType: [compressed], // 压缩图原图体积大容易超限 success: (res) { const tempFilePath res.tempFiles[0].tempFilePath; this.uploadFile(tempFilePath, image); }, fail: (err) console.error(选图失败, err) }); }, // 选视频maxDuration 单位秒超长会被裁剪 chooseVideo() { wx.chooseMedia({ count: 1, mediaType: [video], sourceType: [album, camera], maxDuration: 60, camera: back, success: (res) { const tempFilePath res.tempFiles[0].tempFilePath; this.uploadFile(tempFilePath, video); }, fail: (err) console.error(选视频失败, err) }); } });sizeType: [compressed]是省流量的常见做法但压缩图在需要高清的场景比如证件、商品细节会糊这种场景改传[original]同时后端上限要相应调大。maxDuration只对拍摄生效从相册选的视频不受它限制所以后端仍要做体积校验不能指望前端卡住。2.2 wx.uploadFile 的参数与回调结构wx.uploadFile的核心参数url完整接口地址必须 https 或已配置的合法域名、filePath临时路径、name后端接收字段名必须和 Flask 的request.files[xxx]对上、formData附加表单字段比如用户 ID、业务类型、header可放 token。它返回的是字符串data不是对象需要自己JSON.parse这是新手最容易翻车的地方——直接res.data.code拿到的是undefined。// 接上面的 uploadFile 方法 uploadFile(filePath, type) { const that this; wx.uploadFile({ url: https://your-domain.com/api/upload, // 换成你的后台地址 filePath: filePath, name: file, // 必须与后端 request.files[file] 一致 formData: { bizType: type, // 业务类型image / video userId: 1001 // 示例用户标识 }, header: { Authorization: Bearer your-token // 有鉴权就带上 }, timeout: 60000, // 视频上传慢默认超时不够用 success: (res) { // 注意res.data 是字符串必须手动解析 let result; try { result JSON.parse(res.data); } catch (e) { wx.showToast({ title: 返回格式异常, icon: none }); return; } if (result.code 0) { if (type image) { that.setData({ imageUrl: result.data.url }); } else { that.setData({ videoUrl: result.data.url }); } wx.showToast({ title: 上传成功 }); } else { wx.showToast({ title: result.msg || 上传失败, icon: none }); } }, fail: (err) { console.error(上传失败, err); wx.showToast({ title: 网络异常, icon: none }); } }); }timeout默认是 60 秒大视频在弱网下很容易超时调到 60000 甚至更高更稳。name字段对不上是最高频的 400 来源后端报Bad Request时先查这里。formData里的值只能是字符串传对象会被序列化成[object Object]需要 JSON 就先JSON.stringify。2.3 真机调试的地址问题开发者工具里localhost能通真机不行因为手机访问的是自己不是你的电脑。真机调试要么用局域网 IP手机和电脑同一 WiFi地址写http://192.168.x.x:5000要么用内网穿透工具映射一个公网地址。另外小程序正式环境要求 https 且域名在后台白名单里开发阶段可以在开发者工具勾选「不校验合法域名」但上线前必须配好。这个环节不提前处理会浪费大量时间在「代码明明没错」上。3. Flask 后端接收、校验、落盘与返回后端要做四件事接住文件、校验类型和大小、安全落盘、返回可访问地址。Flask 默认配置有几个隐藏限制不调就会在稍大的文件上翻车。3.1 上传接口的完整实现先看代码再逐段说参数。核心是request.files取文件、secure_filename清洗文件名、uuid防重名、os.makedirs保证目录存在。# app.py import os import uuid from flask import Flask, request, jsonify, send_from_directory from werkzeug.utils import secure_filename app Flask(__name__) # 上传目录与访问前缀 UPLOAD_FOLDER os.path.join(os.getcwd(), uploads) os.makedirs(UPLOAD_FOLDER, exist_okTrue) # 允许的扩展名白名单 ALLOWED_EXT {png, jpg, jpeg, gif, webp, mp4, mov, avi} # 单文件上限200MB视频场景要放宽 app.config[MAX_CONTENT_LENGTH] 200 * 1024 * 1024 def allowed_file(filename): return . in filename and filename.rsplit(., 1)[1].lower() in ALLOWED_EXT app.route(/api/upload, methods[POST]) def upload(): # 1. 取文件字段名必须与前端 name 一致 if file not in request.files: return jsonify({code: 1, msg: 未找到文件字段}), 400 file request.files[file] if file.filename : return jsonify({code: 1, msg: 文件名为空}), 400 # 2. 扩展名校验 if not allowed_file(file.filename): return jsonify({code: 1, msg: 不支持的文件类型}), 400 # 3. 生成安全且唯一的文件名 ext file.filename.rsplit(., 1)[1].lower() safe_name f{uuid.uuid4().hex}.{ext} save_path os.path.join(UPLOAD_FOLDER, safe_name) # 4. 落盘 try: file.save(save_path) except Exception as e: return jsonify({code: 1, msg: f保存失败: {str(e)}}), 500 # 5. 返回可访问地址 file_url f{request.host_url}uploads/{safe_name} return jsonify({ code: 0, msg: ok, data: {url: file_url, name: safe_name} }) app.route(/uploads/path:filename) def serve_file(filename): # 提供静态访问生产环境建议交给 Nginx return send_from_directory(UPLOAD_FOLDER, filename) if __name__ __main__: app.run(host0.0.0.0, port5000, debugTrue)MAX_CONTENT_LENGTH是全局请求体上限不设的话 Flask 默认不限制但底层 WSGI 可能截断设了之后超限会返回 413前端要能识别这个状态码。secure_filename会去掉中文和特殊字符所以这里没用它做最终文件名而是用uuid生成避免中文名丢失和重名覆盖。host: 0.0.0.0是为了局域网真机访问只写127.0.0.1手机连不上。debugTrue仅开发用上线必须关掉否则有安全风险。3.2 参数对照表与常见配置项前后端参数必须一一对应错一个就 400。下面这张表是排查时的对照依据。前端参数后端对应说明name: filerequest.files[file]字段名必须完全一致formData.bizTyperequest.form.get(bizType)附加业务字段header.Authorizationrequest.headers.get(Authorization)鉴权信息url路由/api/upload路径与域名都要对timeout无直接对应后端处理慢会触发前端超时MAX_CONTENT_LENGTH建议按业务定纯图片 20MB 够用带视频至少 200MB。设太大有被恶意大文件打满磁盘的风险设太小正常视频传不上来这个值要结合业务实际调。上传目录不要放在代码目录里生产环境单独挂载数据盘避免部署时被覆盖。3.3 返回结构与前端解析的约定返回统一用{code, msg, data}三段式code0表示成功非 0 表示失败data里放业务数据。这个约定看着简单但能省掉大量前端判断逻辑。前端拿到res.data先JSON.parse再判code失败时把msg直接弹给用户。注意 Flask 返回时用jsonify会自动设Content-Type: application/json但wx.uploadFile不管这个它永远把响应体当字符串给你所以解析这步不能省。如果后端出错返回了 HTML 错误页比如 500 的默认页JSON.parse会抛异常前端要 try-catch 兜住否则整个回调崩掉。4. 避坑排查上传链路上最容易翻车的五个点这条链路我见过太多人卡在同一个地方下面五条按「现象 → 原因 → 解决」写照着对能省不少时间。4.1 后端返回 400提示缺少文件字段现象前端上传后后端直接 400日志里request.files为空。原因九成是wx.uploadFile的name和 Flask 的request.files[xxx]不一致比如前端写name: image后端取request.files[file]。解决两边字段名统一建议固定用file改一处即可。还有一种少见情况是请求被中间层如 Nginx改写了 body排查时先看 Flask 收到的原始请求。4.2 稍大文件报 413 Request Entity Too Large现象小图能传视频或大图直接 413。原因MAX_CONTENT_LENGTH没设或设得太小或者前面有 Nginx 的client_max_body_size默认 1MB 卡着。解决Flask 侧调大MAX_CONTENT_LENGTH如果前面有反向代理同步调client_max_body_size 200m;两处都要改只改一处照样 413。4.3 上传成功但访问地址 404现象接口返回成功拿到的 URL 打开是 404。原因UPLOAD_FOLDER路径和静态路由的目录不一致或者用了相对路径在不同工作目录下解析到了别处。解决统一用os.path.join(os.getcwd(), uploads)这种绝对路径send_from_directory指向同一个变量别在两处各写一遍路径。生产环境建议直接交给 Nginx 的location /uploads/处理Flask 只负责接收。4.4 文件名重复导致互相覆盖现象不同用户传了同名文件后传的把先传的覆盖了。原因直接用了原始文件名落盘。解决用uuid.uuid4().hex生成唯一名扩展名单独保留。原始文件名可以存到数据库里做展示用但磁盘上不要用它。中文文件名还会带来编码问题secure_filename会把它清空所以更不能用原名。4.5 真机上传失败但开发者工具正常现象工具里一切正常真机报网络错误。原因地址写的是localhost或127.0.0.1手机访问不到或者用了 http 但正式环境要求 https。解决开发阶段用局域网 IP 并勾选「不校验合法域名」上线前配好 https 域名和白名单。另外检查手机和电脑是否同一网段防火墙是否放行了 5000 端口。提示排查顺序建议从「前端 name 字段 → 后端大小限制 → 代理层限制 → 地址可达性」逐层往下别一上来就怀疑代码逻辑。5. 进阶分片上传与断点续传的落地思路视频一大单次上传的体验就很差弱网下传一半断了得从头来。分片上传是这类场景的常见做法前端把文件切成固定大小的块比如 2MB 一块逐块上传后端按uploadId和chunkIndex落盘全部到齐后合并。小程序端用wx.getFileSystemManager().readFile配合slice读分片每片走一次wx.uploadFileformData带上uploadId、chunkIndex、totalChunks。后端维护一个临时目录收齐后按序拼接再删临时片。# 分片接收与合并的简化实现 app.route(/api/upload/chunk, methods[POST]) def upload_chunk(): upload_id request.form.get(uploadId) index int(request.form.get(chunkIndex)) total int(request.form.get(totalChunks)) chunk request.files[file] chunk_dir os.path.join(UPLOAD_FOLDER, chunks, upload_id) os.makedirs(chunk_dir, exist_okTrue) chunk.save(os.path.join(chunk_dir, f{index}.part)) # 收齐后合并 if len(os.listdir(chunk_dir)) total: final_name f{uuid.uuid4().hex}.mp4 final_path os.path.join(UPLOAD_FOLDER, final_name) with open(final_path, wb) as out: for i in range(total): with open(os.path.join(chunk_dir, f{i}.part), rb) as part: out.write(part.read()) # 清理临时分片 for f in os.listdir(chunk_dir): os.remove(os.path.join(chunk_dir, f)) os.rmdir(chunk_dir) return jsonify({code: 0, data: {url: f{request.host_url}uploads/{final_name}}}) return jsonify({code: 0, msg: chunk received})uploadId由前端生成时间戳加随机串即可保证同一次上传的分片落在同一目录。合并时按chunkIndex顺序读不能依赖os.listdir的顺序否则拼出来的文件是坏的。断点续传在此基础上加一步上传前先问后端「这个uploadId已经收到哪些片」前端跳过已传的片。这套逻辑不复杂但边界多——分片丢失、重复上传、合并时文件被占用都要有兜底。验证是否真的传成功别只看接口返回 0要实际打开返回的 URL 看文件能不能播放、大小对不对。我一般会在合并后比对文件大小和前端算出的总大小不一致就判失败。从那以后我每次接上传需求都强制走一遍「小图 → 大图 → 短视频 → 长视频 → 弱网中断」这五步少一步都可能在上线后翻车。希望帮到你。本文还有配套的精品资源点击获取