Django ImageField 完整配置与图片处理指南

追风的人

发布时间：2026-10-14 | 5人浏览过

原创

本文详细解析 Django 中 ImageField 的完整使用流程，涵盖 settings 配置、Model 定义、Form 表单验证及 HTML 模板显示。重点讲解 enctype 设置、路径静态化处理、图片更新逻辑及默认图片的 HTML 层实现方案，帮助开发者解决图片存储与展示中的常见问题。

Django 中 ImageField 的使用详解

在完善订单系统的作业过程中，主要需求是为每个菜品添加图片以提升界面美观度。然而，这一看似简单的功能实现却耗费了大量时间。本文将此过程中的经验与知识点进行整理记录，旨在分享相关知识。

使用流程

1. 配置 settings 文件

需要在配置文件中定义两个关键变量：MEDIA_ROOT 用于指定上传图片在服务器上的存储根目录，而 MEDIA_URL 则定义访问这些文件时 URL 的前缀部分。


# 图片储存根路径
MEDIA_ROOT = join('media')
# 图片访问url
MEDIA_URL = '/IMG/'

2. 在 Model 中增加 ImageField 属性

必须正确配置 upload_to 参数，它决定了图片最终存储的具体子文件夹名称。例如，若设置为 'img/'，则图片将保存在 MEDIA_ROOT 指向目录下的 'img' 文件夹中。


class Menu(models.Model):
  """
  餐品数据库
  """
  ID = models.BigAutoField(primary_key=True,editable=False)
  lastEditTime = models.DateTimeField(auto_now_add=True)
  merchantID = models.ForeignKey(Usr, verbose_name="商家账号", on_delete=models.CASCADE,to_field='ID')
  itemName = models.CharField(max_length=20,verbose_name="餐品名")
  itemText = models.TextField(verbose_name="餐品简介")
  price = models.FloatField(verbose_name="餐品价格")
  ################# up_load代表你上传图片所存储的文件夹名字
  picture = models.ImageField(verbose_name='餐品图片',null=True,upload_to='img/')
  class Meta:
    db_table = "Menu"
    verbose_name = "餐品数据表"
    ordering=['-lastEditTime']

3. 构建 Form 表单类

本项目采用 Django 内置的 Form 表单类来处理前端提交的数据传递与验证。


class MerchantDish(forms.Form):
  """
  商家菜品提交表单
  """
  itemName = forms.CharField(max_length=20,label="餐品名")
  itemText = forms.CharField(max_length=300,label="餐品简介")
  price = forms.FloatField(label="餐品价格")
  picture = forms.ImageField(label='餐品图片')

4. HTML 模板文件（用于新增菜品）

在编写 HTML 表单时，务必添加 enctype="multipart/form-data" 属性，这是文件上传所必需的条件。


<form action="updateDish_post/" method="post" enctype="multipart/form-data"> 
  {% csrf_token %} {{form.as_p}}
  <button type="submit">修改</button> 
  <button type="button"><a href="/MerchantSystem/DelDish/{{dishID}}/" rel="external nofollow" >删除</a></button>
</form>

5. 显示菜品的 HTML 模板文件

关键在于 img 标签中 src 属性的路径配置。这里提供两种方法，推荐使用方法一，其安全性较高，即使图片字段为空也不会导致报错（同时可调整图片显示尺寸）。

方法一：路径格式为 /IMG(自定义的 MEDIA_URL)/{{dish.picture}}。其中 dish 代表从后端传递过来的菜品对象，dish.picture 对应 Model 中定义了 ImageField 属性的字段。

方法二：使用 {{dish.picture.url}}。由于 ImageField 属于文件类，它内置了 name、path 和 url 三个属性，可直接通过 .url 访问图片链接。


{% for dish in menu %}
<!--将目录的数据展示在html中-->
<!-- 提交到一个含参数的url注意后端的接收 -->
<form action="/MerchantSystem/Dish/{{dish.ID}}/" method="post">
  {% csrf_token %}
  <li class="media">
    <div class="media-left media-middle" >
        <img class="media-object" width="150" height="150" src="/IMG/{{dish.picture}}" alt="">
    </div>
    <div class="media-body">
      <h4 class="media-heading">
        <button type='submit' class=" url" title="更新菜品信息">
        菜名：{{dish.itemName|default:"Null"}}
        </button>
        <span class="label label-default">
          价格：{{dish.price|default:"Null"}}
        </span>

      </h4>
      简介：{{dish.itemText|default:"Null"}}
    </div>
  </li>
</form>

{% empty %}

<!--若中无数据展示如下内容-->

<p>暂无数据..</p>

{% endfor %} {% endblock tableBody %}

6. 路径静态化处理

需要在项目的 urls.py 中配置静态文件处理，具体操作是将 static 函数加入 urlpatterns，确保 MEDIA_URL 指向的资源能被正确访问。


from django.conf import settings
from django.conf.urls.static import static
urlpatterns = [
  path('', views.base_view, name = "base"),# 顾客服务系统
  path('order/<int:dishID>/', views.order_view),# 订单详情
  path('order/<int:dishID>/submit/',views.order_submit),# 提交订单
  path('pay/<int:orderID>/', views.pay_view),# 缴费
  path('pay/<int:orderID>/submit/',views.pay_submit),#确认账单
  path('order/list/',views.order_list_view),#历史订单列表
  path('order/confirm/<int:orderID>/',views.order_confirm),#订单确认收到
  path('order/comment/<int:orderID>/',views.comment),#到达相应菜品的评论界面
  path('order/comment_post/<int:orderID>/',views.comment_post)#提交评论
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

7. 修改已上传的图片

首先通过 Form 表单上传图片，经过有效性检查后，将 cleaned_data 中的 picture 数据赋值给待更新对象的 picture 属性，最后调用 save() 方法保存更改。具体代码实现如下：


def updateDish_post(request,dishID):
  """
  接受修改菜品的请求
  """
  dish_form = MerchantDish(request.POST,request.FILES)
  if dish_form.is_valid() :
    dish = Menu.objects.get(ID = dishID)
    dish.itemName = dish_form.cleaned_data['itemName']
    dish.itemText = dish_form.cleaned_data['itemText']
    dish.price = dish_form.cleaned_data['price']
    dish.picture = dish_form.cleaned_data['picture']
    dish.save()
    # dishChange = dish_form.clean()    
    return redirect('/MerchantSystem/')
  elif dish_form.errors is not None:
    print(dish_form.errors)
    return HttpResponse(str(dish_form.errors))

8. 设置默认图片

查阅大量资料后，发现无法直接在 model.py 中通过 default 参数设置默认图片。经过尝试，最终通过在显示图片的 HTML 模板的 src 属性中指定默认路径来解决。具体代码逻辑为：dish 是后端传递的参数，default 指向默认图片的存储位置。


    <div class="media-left media-middle" >
        <!-- {{dish.url|default:"Null"}} -->
        <img class="media-object" width="150" height="150" src="/IMG/{{dish.picture|default:'img/default.jpg'}}" alt="">
    </div>