Django 项目中 CSS 文件返回 404，通常因 STATIC_ROOT 未配置、开发服务器未启用静态文件服务，或路径引用不规范所致；本文系统梳理配置要点、调试步骤与最佳实践。
django 项目中 css 文件返回 404，通常因 `static_root` 未配置、开发服务器未启用静态文件服务，或路径引用不规范所致；本文系统梳理配置要点、调试步骤与最佳实践。
在 Django 开发过程中，HTML 模板无法加载 main.css 等静态资源并报 404 Not Found（如 GET /static/css/main.css 失败），是一个高频问题。根本原因并非 CSS 路径写错，而是 Django 开发服务器默认不自动提供静态文件服务——它只负责处理应用逻辑路由，静态文件需显式配置才能被 runserver 识别和响应。
✅ 正确配置三步走
1. 补全 settings.py 中的静态文件设置
除了已有的 STATIC_URL 和 STATICFILES_DIRS，必须定义 STATIC_ROOT（即使开发阶段不运行 collectstatic）：
# settings.py
import os
from pathlib import Path
BASE_DIR = Path(__file__).resolve().parent.parent
STATIC_URL = '/static/'
# ✅ 开发时存放原始静态文件的目录（你的 CSS 就在这里）
STATICFILES_DIRS = [
BASE_DIR / 'static', # 推荐用 Path 对象（Django 4.0+），兼容性更好
]
# ✅ 关键！开发服务器需以此为 document_root 提供静态文件
STATIC_ROOT = BASE_DIR / 'staticfiles' # 注意：此目录可为空，runserver 会自动查找 STATICFILES_DIRS
⚠️ 注意：STATIC_ROOT 不是“存放源文件”的地方，而是 collectstatic 命令的输出目标；但在开发模式下，runserver 会优先从 STATICFILES_DIRS 查找文件，并以 STATIC_ROOT 作为服务根路径——因此它必须存在且路径合法。
2. 在主 urls.py 中启用开发期静态文件服务
仅配置 STATIC_ROOT 不够，还需让 Django URL 路由知晓如何响应 /static/ 请求：
# urls.py（项目根目录下的 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),
path('', include('myapp.urls')),
]
# ✅ 仅在 DEBUG=True 时添加：让 runserver 处理静态文件请求
if settings.DEBUG:
urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
? 原理：static() 函数生成一个 URL 模式，将所有匹配 STATIC_URL（如 /static/）的请求，映射到 document_root（即 STATIC_ROOT）下的对应文件。由于 STATIC_ROOT 已设为 BASE_DIR / 'staticfiles'，而 runserver 实际会回溯查找 STATICFILES_DIRS 中的文件，因此能正确定位 static/css/main.css。
3. 模板中使用 {% static %} 模板标签（推荐）
避免硬编码路径，提升可维护性：
<!-- store.html -->
{% load static %}
<link rel="stylesheet" type="text/css" href="%7B%%20static%20'css/main.css'%20%%7D"><h3>Store</h3>
✅ 此写法会自动拼接 STATIC_URL（如 /static/）+ 'css/main.css' → /static/css/main.css，与后端路由规则完全对齐。
? 调试建议（快速定位问题）
- 运行 python manage.py findstatic css/main.css：验证 Django 是否能发现该文件；
- 检查浏览器开发者工具 Network 标签页，确认请求路径是否为 /static/css/main.css（排除模板路径拼写错误）；
- 确保 DEBUG = True（DEBUG=False 时 static() 配置无效，需用 Nginx 等代理静态文件）；
- 删除 staticfiles 目录后重启服务（避免缓存干扰）。
✅ 总结
| 配置项 | 作用 | 开发必需？ |
|---|---|---|
| STATIC_URL | 静态资源 URL 前缀（如 /static/） | ✅ |
| STATICFILES_DIRS | 原始静态文件所在目录列表 | ✅ |
| STATIC_ROOT | collectstatic 输出目录 & runserver 的 document_root | ✅（开发期也必须设） |
| urlpatterns += static(...) | 启用开发服务器静态文件服务 | ✅（仅 DEBUG=True 时） |
完成以上配置后，重启 Django 开发服务器，CSS 即可正常加载。生产环境请务必改用 Web 服务器（如 Nginx）托管静态文件，禁用 static() 配置以保障性能与安全。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
