Django使用{% static %}加载static文件夹文件失败图片不显示

已确认模板中添加了{% load static %}声明、其余业务功能运行正常，但static目录下图片无法渲染、静态文件访问失败时，按以下顺序逐一排查即可：

• 先核对settings.py配置项
  • 确认INSTALLED_APPS列表中存在django.contrib.staticfiles，该应用是Django处理静态资源的核心依赖，修改配置时误删会直接导致静态标签失效
  • 确认STATIC_URL配置正确，常规默认值为STATIC_URL = 'static/'，不要多写/漏写前后斜杠
  • 如果静态文件统一存放在项目根目录的static文件夹（而非各app子目录下的static文件夹），必须添加STATICFILES_DIRS配置指定静态文件路径，参考写法：

    import os
    STATICFILES_DIRS = [
        os.path.join(BASE_DIR, 'static')
    ]
    

    注意不要把开发用的STATICFILES_DIRS和部署用的STATIC_ROOT搞混，本地开发阶段不需要配置STATIC_ROOT，配置错误会直接导致路径匹配失败。
• 检查模板内标签写法
  • {% load static %}需要写在模板文件的顶部位置，使用模板继承时，要保证static加载声明出现在所有{% static %}标签调用之前，写在子模板最开头最稳妥
  • 路径不要多写冗余字符：比如图片实际路径是static/images/demo.png，正确写法为{% static 'images/demo.png' %}，不要在路径前加额外斜杠写成/images/demo.png，也不要重复拼接static层级写成static/images/demo.png，两种写法都会导致路径匹配404。
• 核对开发环境路由配置
  • 本地开发时DEBUG=True的前提下，需要在项目根urls.py中添加静态文件路由映射，Django才会响应静态资源请求，参考写法：

    from django.conf import settings
    from django.conf.urls.static import static
    
    urlpatterns = [
        # 原有业务路由
    ] + static(settings.STATIC_URL, document_root=settings.STATICFILES_DIRS[0])
    

• 最后排查小概率问题
  • 所有配置修改完成后必须重启Django本地开发服务，settings配置改动不会自动热加载，不重启所有修改都不生效
  • 打开浏览器开发者工具，在网络面板找到加载失败的图片请求，看返回状态码：404就把请求路径和本地实际文件路径逐字符对比找拼写错误；403就给本地static文件夹开放可读权限。

补充：线上部署环境（DEBUG=False）下Django本身不会处理静态文件请求，需要通过Nginx等Web服务映射静态文件路径，该配置仅在生产环境需要，本地开发阶段无需调整。

内容的提问来源于stack exchange，提问作者Ali