Django v4.0.5如何正确加载静态文件？CSS加载失败排查

你的模板代码写法完全正确，{% load static %}标签与{% static 'main.css' %}的调用逻辑没有问题，静态文件加载失败的核心原因是settings.py配置存在两处错误：

• 配置项名称拼写错误：Django识别的静态文件搜索路径配置项为 STATICFILES_DIRS（末尾带s，为复数形式），你写的STATICFILES_DIR属于无效配置，Django启动时不会读取该参数。
• 路径拼接逻辑错误：你将BASE_DIR和"static"作为两个独立元素放入列表，没有做路径拼接，Django无法定位到项目根目录下的static文件夹。

1. 修正settings.py静态配置 #

Django 4.0.5默认使用pathlib定义BASE_DIR，直接替换原有静态配置为以下内容即可：

# 静态文件访问URL前缀，保持默认配置即可
STATIC_URL = 'static/'

# 注意配置项末尾必须带s
STATICFILES_DIRS = [
    # 正确拼接项目根目录下的static文件夹路径
    BASE_DIR / "static",
]

如果你使用的是基于os模块的老版本BASE_DIR定义方式，配置写法如下：

import os

STATIC_URL = 'static/'
STATICFILES_DIRS = [
    os.path.join(BASE_DIR, "static")
]

2. 确认目录结构合规 #

确保static文件夹位置与文件路径匹配，标准目录结构如下：

项目根目录/
├── manage.py
├── static/          # 与manage.py同级，就是你存放静态资源的文件夹
│   └── main.css     # 直接放在static根目录，才能匹配{% static 'main.css' %}的引用路径
├── 业务应用文件夹/
└── 项目配置文件夹/
    ├── settings.py
    └── urls.py

3. 开发环境校验规则 #

本地通过python manage.py runserver启动服务时，需要满足两个前提：

• settings.py中DEBUG = True，Django自带的静态文件服务仅在debug模式下默认开启
• 根路由urls.py没有手动配置匹配static/前缀的路由规则，避免静态请求被拦截到业务视图

4. 验证方式 #

修改配置后务必重启本地开发服务，浏览器访问页面后按F12打开开发者工具，查看网络请求中main.css的请求路径为/static/main.css、响应状态码为200即代表加载成功。如果仍返回404，优先清理浏览器缓存，再确认main.css没有存放在static下的多余子目录中。

生产环境部署（DEBUG=False）时，需要额外配置STATIC_ROOT参数，执行python manage.py collectstatic命令汇总所有静态文件，通过Nginx、Apache等Web服务器托管静态资源，不要直接依赖Django本身处理静态请求。

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