python在Django中实现文件上传功能步骤-深圳市維司達科技有限公司

你想了解在 Django 框架中实现文件上传功能的核心步骤，需要一份清晰、可落地的步骤指南，涵盖从配置到代码实现的全流程。以下是 Django 实现文件上传的 7 个核心步骤，每个步骤都包含具体配置和代码示例，适配 Django 4.x/5.x 版本。

Django 实现文件上传的核心步骤

步骤 1：配置媒体文件（Media）路径（基础前提）

Django 中上传的文件默认存储在媒体文件目录（Media），需要在settings.py中配置路径和访问 URL，这是文件上传的基础。

配置代码（settings.py）

python

# 项目根目录（拼接路径用） import os BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) # 1. 媒体文件存储路径（上传的文件会存到这个目录） MEDIA_ROOT = os.path.join(BASE_DIR, 'media') # 项目根目录下的media文件夹 # 2. 媒体文件访问URL（前端/后端访问上传文件的URL前缀） MEDIA_URL = '/media/' # 例如：http://127.0.0.1:8000/media/xxx.jpg # 可选：文件上传大小限制（防止超大文件上传） DATA_UPLOAD_MAX_MEMORY_SIZE = 10485760 # 10MB（默认2.5MB） FILE_UPLOAD_MAX_MEMORY_SIZE = 10485760 # 10MB

关键说明

MEDIA_ROOT：本地物理路径，必须是绝对路径，Django 会把上传的文件保存到这个目录；
MEDIA_URL：URL 路径，用于浏览器访问上传的文件（比如上传的图片可以通过http://域名/media/文件名访问）；
需手动在项目根目录创建media文件夹（否则上传时会报路径不存在错误）。

步骤 2：配置 URL 以访问媒体文件（可选但必要）

开发环境下，需要配置 URL 路由，让 Django 能处理MEDIA_URL的访问请求（生产环境需用 Nginx 等服务器处理）。

配置代码（项目根 urls.py）

python

from django.contrib import admin from django.urls import path from django.conf import settings from django.conf.urls.static import static urlpatterns = [ path('admin/', admin.site.urls), # 其他路由... ] # 开发环境下，添加媒体文件的访问路由 if settings.DEBUG: urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

步骤 3：定义包含文件字段的模型（Model）（可选，按需使用）

如果需要将文件信息（如文件名、存储路径）存入数据库，需在models.py中定义模型，核心字段是FileField（通用文件）或ImageField（图片文件，需安装Pillow）。

模型代码（app/models.py）

python

from django.db import models class UploadFile(models.Model): # 1. 文件字段：upload_to指定文件存储的子目录（media下的uploads文件夹） file = models.FileField(upload_to='uploads/%Y/%m/%d/') # 按年月日分目录存储 # 可选：图片字段（需安装Pillow：pip install Pillow） # image = models.ImageField(upload_to='images/%Y/%m/%d/') # 2. 上传时间（自动记录） upload_time = models.DateTimeField(auto_now_add=True) # 可选：自定义文件名显示 def __str__(self): return self.file.name

关键说明

upload_to：可以是字符串（固定目录）或函数（动态生成目录 / 文件名）；
执行python manage.py makemigrations和python manage.py migrate创建数据库表。

步骤 4：创建文件上传表单（Form）（简化验证）

使用 Django 的表单类（Form/ModelForm）可以自动验证文件类型、大小，简化处理逻辑。

表单代码（app/forms.py）

python

from django import forms from .models import UploadFile # 方式1：ModelForm（关联模型，推荐） class UploadFileForm(forms.ModelForm): class Meta: model = UploadFile fields = ['file'] # 对应模型中的字段 # 可选：添加表单样式/验证 widgets = { 'file': forms.ClearableFileInput(attrs={'class': 'form-control'}), } # 方式2：普通Form（不关联模型） # class UploadFileForm(forms.Form): # file = forms.FileField(label='选择文件', widget=forms.ClearableFileInput)

步骤 5：编写视图函数 / 类（View）处理上传逻辑（核心）

视图是处理文件上传的核心，负责接收请求、验证表单、保存文件，分为函数视图和类视图两种方式。

方式 1：函数视图（简单易理解）

python

from django.shortcuts import render, redirect from .forms import UploadFileForm def file_upload(request): if request.method == 'POST': # 1. 绑定表单数据（包含文件） form = UploadFileForm(request.POST, request.FILES) if form.is_valid(): # 2. 保存文件（ModelForm会自动保存到MEDIA_ROOT指定的路径） form.save() # 3. 上传成功，跳转/提示 return render(request, 'upload_success.html', {'msg': '文件上传成功！'}) else: # GET请求，显示空表单 form = UploadFileForm() return render(request, 'upload.html', {'form': form})

方式 2：类视图（Django 推荐，更简洁）

python

from django.views.generic import FormView from django.urls import reverse_lazy from .forms import UploadFileForm class FileUploadView(FormView): template_name = 'upload.html' # 上传页面模板 form_class = UploadFileForm # 绑定的表单类 success_url = reverse_lazy('upload_success') # 上传成功后的跳转URL # 重写form_valid方法，处理文件保存 def form_valid(self, form): form.save() # 保存文件 return super().form_valid(form)

关键说明

文件上传必须用POST请求，且表单enctype需为multipart/form-data；
request.FILES：Django 封装的文件数据，必须传入表单才能获取上传的文件；
form.is_valid()：自动验证文件是否符合要求（如大小、类型）。

步骤 6：编写前端上传页面（HTML 模板）

创建模板文件，显示表单并支持文件选择和提交。

模板代码（templates/upload.html）

html

预览

<!DOCTYPE html> <html> <head> <title>文件上传</title> </head> <body> <h1>文件上传</h1> <!-- 必须设置enctype="multipart/form-data"才能上传文件 --> <form method="post" enctype="multipart/form-data"> {% csrf_token %} <!-- Django必加，防止CSRF攻击 --> {{ form.as_p }} <!-- 渲染表单 --> <button type="submit">上传</button> </form> </body> </html>

成功页面（templates/upload_success.html）

html

预览

<!DOCTYPE html> <html> <head> <title>上传成功</title> </head> <body> <h1>{{ msg }}</h1> <a href="{% url 'file_upload' %}">返回上传页面</a> </body> </html>

步骤 7：配置 URL 路由（映射视图）

将视图映射到 URL，让用户可以访问上传页面。

路由代码（app/urls.py）

python

from django.urls import path from . import views urlpatterns = [ # 函数视图路由 path('upload/', views.file_upload, name='file_upload'), # 类视图路由（如果用类视图） # path('upload/', views.FileUploadView.as_view(), name='file_upload'), # 成功页面路由 path('upload/success/', lambda request: render(request, 'upload_success.html'), name='upload_success'), ]

步骤 8：测试文件上传功能

启动 Django 开发服务器：python manage.py runserver；
访问http://127.0.0.1:8000/upload/；
选择文件并点击 “上传”，成功后会看到提示，且media/uploads/目录下会出现上传的文件。

进阶注意事项（生产环境必备）

文件类型验证：限制仅允许上传指定类型的文件（如.pdf、.jpg）：

python

# 在forms.py中添加验证 def clean_file(self): file = self.cleaned_data['file'] allowed_extensions = ['pdf', 'jpg', 'png', 'txt'] extension = file.name.split('.')[-1].lower() if extension not in allowed_extensions: raise forms.ValidationError('仅允许上传PDF、JPG、PNG、TXT文件！') return file

文件重命名：避免文件名重复，自定义文件名：

python

# 在models.py中自定义upload_to函数 def custom_upload_to(instance, filename): import uuid ext = filename.split('.')[-1] new_filename = f"{uuid.uuid4()}.{ext}" # 用UUID生成唯一文件名 return f'uploads/{new_filename}' # 模型字段修改 file = models.FileField(upload_to=custom_upload_to)

生产环境配置：
- 不要用 Django 处理媒体文件访问，改用 Nginx/Apache；
- 可将文件存储到云存储（如阿里云 OSS、腾讯云 COS），需安装对应插件（如django-storages）。

总结

Django 文件上传的核心是配置 Media 路径（存储 + 访问）、表单验证文件、视图处理保存三大环节；
关键要点：表单必须设置enctype="multipart/form-data"，视图需接收request.FILES，开发环境需配置 Media URL；
生产环境需增加文件类型 / 大小验证、自定义文件名、改用第三方存储 / 服务器处理文件访问。