文件上传接口的完整实现与避坑指南做过上传功能的同学都知道这玩意儿看着简单真做起来坑不少。尤其是涉及路径拼接、目录权限、文件名安全这些问题时稍不注意就给你颜色看。我这次整理了一个相对完整的文件上传接口实现直接把代码贴出来每一步我都加了详细注释顺便把常见问题和排查思路也一并说了。import path import os import time import uuid from flask import Flask, request, jsonify app Flask(__name__) # 上传配置 UPLOAD_BASE_DIR ./uploads # 上传根目录 ALLOWED_EXTENSIONS {png, jpg, jpeg, gif, pdf, zip} # 允许的文件类型 MAX_CONTENT_LENGTH 10 * 1024 * 1024 # 限制最大10MB防止内存被打爆 def allowed_file(filename): 检查文件扩展名是否允许上传 return . in filename and filename.rsplit(., 1)[1].lower() in ALLOWED_EXTENSIONS def generate_unique_filename(original_filename): 生成不重复的文件名避免覆盖和路径穿越 ext original_filename.rsplit(., 1)[1].lower() if . in original_filename else unique_name f{int(time.time())}_{uuid.uuid4().hex[:8]}.{ext} return unique_name app.route(/upload, methods[POST]) def upload_file(): 处理文件上传请求 # 1. 检查是否有文件上传 if file not in request.files: return jsonify({code: 400, msg: 请求中没有file字段}), 400 file request.files[file] # 2. 检查文件名是否为空空文件名往往是绕过前端校验的行为 if file.filename : return jsonify({code: 400, msg: 文件名为空}), 400 # 3. 检查文件类型是否允许 if not allowed_file(file.filename): return jsonify({code: 400, msg: 不支持的文件类型}), 400 # 4. 生成保存路径 # 按日期分子目录例如 ./uploads/2024/01/15/xxx.jpg date_dir time.strftime(%Y/%m/%d) save_dir path.join(UPLOAD_BASE_DIR, date_dir) # 5. 自动创建目录如果不存在 os.makedirs(save_dir, exist_okTrue) # 6. 生成唯一文件名并保存 filename generate_unique_filename(file.filename) save_path path.join(save_dir, filename) try: file.save(save_path) except Exception as e: return jsonify({code: 500, msg: f文件保存失败: {str(e)}}), 500 # 7. 返回可访问的URL地址 file_url f/files/{date_dir}/{filename} return jsonify({code: 0, msg: 上传成功, url: file_url}), 200 app.route(/files/path:filepath) def serve_uploaded_file(filepath): 提供上传文件的访问生产环境建议交给Nginx处理 full_path path.join(UPLOAD_BASE_DIR, filepath) if not os.path.isfile(full_path): return jsonify({code: 404, msg: 文件不存在}), 404 return app.send_static_file(full_path) # 仅演示实际应使用 send_from_directory if __name__ __main__: # 启动前确保上传目录存在 os.makedirs(UPLOAD_BASE_DIR, exist_okTrue) app.run(host0.0.0.0, port5000, debugTrue)下面是文件上传相关的技术要点复盘分成目录结构、文件名处理、请求限制和常见问题几个维度展开逐条说清楚背后的原因和踩过的坑。1. 上传目录为什么按日期分文件夹很多人做上传功能时图省事直接全部丢到一个目录下。本来文件少没啥感觉等量大了之后操作系统在单目录下的文件检索速度会明显下降尤其是一万多个小文件堆在一个文件夹里光浏览就卡半天。按年/月/日分目录有以下好处文件数量被自然分散单目录压力小清理过期文件时直接按目录删比如删除 30 天前的2024/03/文件夹一条命令搞定访问路径上自带时间信息排查问题或追踪文件来源更直观。我在项目里用path.join(UPLOAD_BASE_DIR, time.strftime(%Y/%m/%d))生成路径然后os.makedirs(save_dir, exist_okTrue)自动创建。这条要特别注意exist_okTrue必须带上不然目录已存在时会直接抛FileExistsError新手经常在这踩坑。注意不要自己拼路径字符串UPLOAD_BASE_DIR / date_dir这在不同系统之间可能会有问题。用path.join才是跨平台的正确姿势。2. 文件名处理的三个关键细节文件名是整个上传功能里最容易翻车的点下面三个细节都要处理到位。第一必须做扩展名校验。我用白名单机制只允许png、jpg、jpeg、gif、pdf、zip这几种常见类型。黑名单思路是错的——你永远列不全所有危险格式漏一个就出问题。判断逻辑是取文件名最后一个点后面的部分转小写再比对return . in filename and filename.rsplit(., 1)[1].lower() in ALLOWED_EXTENSIONS第二必须重命名文件。直接用用户上传的原始文件名存 disk 是很危险的操作。假如来一个../../etc/passwd的文件名直接拼到路径里就把目录穿越漏洞写死了。就算安全几十个用户都传photo.jpg也会互相覆盖。我用时间戳加 UUID 片段的方式生成新文件名unique_name f{int(time.time())}_{uuid.uuid4().hex[:8]}.{ext}实测这样生成的文件名在常规并发量下几乎不可能重复同时保留了扩展名信息方便后续识别文件类型。第三要处理file.filename 的情况。这个空文件名的请求大概率是有人绕过了前端校验直接打接口别给任何回旋余地直接拒绝。提示如果业务上确实需要保留原始文件名建议把原始文件名存进数据库磁盘上仍然使用重命名后的名字。这是通用做法既安全又不丢用户信息。3. 上传接口的配置限制和异常处理大文件上传是内存杀手。如果不设MAX_CONTENT_LENGTH一个 10GB 的伪装文件就能把你的服务拖垮。我在配置里强制限到 10MBMAX_CONTENT_LENGTH 10 * 1024 * 1024超过这个限制的请求框架层面会直接拒绝不会进到业务代码里。这个数值按你的业务场景来调整传 PDF 可能得放大到 50MB但一定要设上限。保存文件时也要兜底异常。磁盘满了、权限不对、被杀毒软件锁了文件都有可能抛出异常。我在file.save()外包了一层try-except出任何问题就返回 500 错误而不是让服务器莫名其妙崩掉。另一个容易忽略的事儿是线上环境服务器的/tmp和/var分区经常是独立挂载且空间有限的。你先把上传根目录UPLOAD_BASE_DIR设在哪个盘、哪个分区要提前规划好否则很容易出现“明明磁盘还有空间但文件就是写不进去”的诡异问题。4. 文件访问路径的细节规划上传完成后我返回给前端的 URL 是/files/{date_dir}/{filename}这个字符串是内部自己拼接的不是从请求里取回来的所以没有路径穿越风险。返给用户的时候让前端直接用域名 这个 URL来拼完整下载地址。开发环境下需要有一个路由把这个 URL 映射到实际文件app.route(/files/path:filepath) def serve_uploaded_file(filepath): full_path path.join(UPLOAD_BASE_DIR, filepath) if not os.path.isfile(full_path): return jsonify({code: 404, msg: 文件不存在}), 404 return app.send_static_file(full_path)生产环境不建议自己做文件服务性能太差而且占用应用进程。正确做法是让 Nginx 直接 alias 到UPLOAD_BASE_DIR应用只负责接收和保存文件访问交给 Nginx效率完全不在一个量级。上线时把这个路由关掉让 Nginx 接管/files/这个前缀即可。5. 常见问题速查表现象可能原因解决方式上传后访问 URL 返回 404Nginx 的 alias 路径配置错误或者目录不存在检查alias路径是否以/结尾确认UPLOAD_BASE_DIR存在且有读权限文件保存失败提示Read-only file system目录所在的磁盘是只读挂载常见于容器环境检查挂载参数或换一个可写目录容器里记得挂载 volume超过MAX_CONTENT_LENGTH后报错但始终没进业务代码框架层拦截了请求属于正常行为调整上限数值或走分片上传方案文件上传成功了但文件名变成乱码客户端传了非 ASCII 文件名框架编码不一致在保存时统一用重命名策略不依赖原始文件名上传的路径中存在..但没报错没有做重命名或路径校验所有路径必须用服务端生成的唯一文件名禁止使用用户输入拼接路径修改了上传代码但服务还是旧逻辑生产环境跑了旧进程代码没热更新重启应用进程并确认部署时确实拉取到了最新代码自己实际做项目时在真正把上传功能放到公网之前强制做一轮测试上传超长文件名、上传空文件、上传伪装扩展名的文件、并发上传同一文件名的两个文件、绕过前端直接 POST 请求。这几项都过了这个功能才能说是基本稳了。