Django 项目中 CSS 文件返回 404，通常因 STATIC_ROOT 未配置或开发服务器未正确提供静态资源所致；本文详解如何正确配置 STATICFILES_DIRS、STATIC_ROOT 和 URL 路由，确保 CSS 等静态文件被正常加载。
django 项目中 css 文件返回 404，通常因 `static_root` 未配置或开发服务器未正确提供静态资源所致；本文详解如何正确配置 `staticfiles_dirs`、`static_root` 和 url 路由，确保 css 等静态文件被正常加载。
在 Django 开发阶段，静态文件（如 CSS、JS、图片）需通过开发服务器直接提供服务，但默认情况下 Django 仅在生产环境 通过 collectstatic 命令将静态文件收集至 STATIC_ROOT 目录并由 Web 服务器（如 Nginx）托管；而在开发时，必须显式启用静态文件服务机制——这正是你遇到 GET /static/css/main.css 404 的根本原因。
✅ 正确配置三要素
1. 完善 settings.py 中的静态文件设置
除了已有的 STATIC_URL 和 STATICFILES_DIRS，必须添加 STATIC_ROOT（即使开发阶段不立即使用，也是 runserver 正确路由静态文件的前提）：
import os
from pathlib import Path
BASE_DIR = Path(__file__).resolve().parent.parent.parent
# 静态文件基础配置
STATIC_URL = '/static/'
# 开发时存放静态文件的源目录（你的 CSS 所在位置）
STATICFILES_DIRS = [
BASE_DIR / 'static', # 推荐使用 Path 对象（Django 3.1+），兼容性更好
]
# ⚠️ 关键：必须定义 STATIC_ROOT（用于 collectstatic，且开发服务器依赖此路径解析）
STATIC_ROOT = BASE_DIR / 'staticfiles' # 注意：该目录无需手动创建，runserver 会自动识别? 提示：STATICFILES_DIRS 是你编写时存放静态文件的位置（如 static/css/main.css），而 STATIC_ROOT 是 Django 收集并服务静态文件的最终输出/服务根目录。二者用途不同，缺一不可。
2. 在 urls.py 中启用开发服务器静态文件服务
仅配置 STATIC_ROOT 不够，还需让 Django 开发服务器（runserver）知道：当请求 /static/xxx 时，应从 STATIC_ROOT 目录查找并响应文件。
在项目主 urls.py（通常是 myproject/urls.py）末尾添加：
from django.contrib import admin
from django.urls import path, include
from django.conf import settings
from django.conf.urls.static import static
urlpatterns = [
path('admin/', admin.site.urls),
# ... 其他 URL 模式
]
# ? 仅在 DEBUG=True 时启用 —— 生产环境严禁使用！
if settings.DEBUG:
urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)⚠️ 注意：document_root 必须指向 STATIC_ROOT（而非 STATICFILES_DIRS[0]），因为 runserver 在开发模式下会优先扫描 STATIC_ROOT；若 STATIC_ROOT 为空，它会自动回退到 STATICFILES_DIRS，但前提是 STATIC_ROOT 已正确定义。
3. 模板中正确引用静态文件
避免硬编码路径，始终使用 {% static %} 模板标签，并确保已加载 static：
<!-- store.html -->
{% load static %}
<!DOCTYPE html>
<html>
<head>
<!-- ✅ 正确：使用 static 标签生成相对路径 -->
<link rel="stylesheet" type="text/css" href="{% static 'css/main.css' %}" />
</head>
<body>
<h3>Store</h3>
</body>
</html>✅ 生成的 HTML 将是：<link href="/static/css/main.css" ...>，与你的原始写法效果一致，但更健壮、可维护。
? 常见误区与验证步骤
- ❌ 错误：只设 STATICFILES_DIRS，忽略 STATIC_ROOT → runserver 无法定位静态资源，必报 404。
- ❌ 错误：document_root 指向 STATICFILES_DIRS[0] → 可能工作，但不符合 Django 最佳实践，且在某些版本中不稳定。
- ✅ 验证方式：
- 运行 python manage.py findstatic css/main.css，确认 Django 能定位到你的 CSS 文件；
- 启动 python manage.py runserver，访问 http://127.0.0.1:8000/static/css/main.css —— 应返回 CSS 内容（HTTP 200），而非 404；
- 查看终端日志：成功时会出现 "[01/Jan/2024 10:00:00] "GET /static/css/main.css HTTP/1.1" 200 1234"。
✅ 总结
Django 静态文件 404 的核心解法是「三要素闭环」：
① STATIC_URL 定义 URL 前缀；
② STATICFILES_DIRS 声明源文件位置；
③ STATIC_ROOT + urlpatterns += static(...) 启用开发服务机制。
完成配置后，无需重启服务器（runserver 会自动重载），刷新页面即可生效。生产部署时，请务必移除 static() 路由，并改用 Nginx 或 Whitenoise 托管静态文件。
