它是什么
-
STATICFILES_DIRS是一个“额外静态资源目录”的列表。 - Django 会在这些目录里查找静态文件（CSS/JS/图片），除了每个应用自带的
app_name/static/目录之外 - 既用于开发时的静态文件查找，也用于
collectstatic收集到部署目录。
和 STATIC_URL、STATIC_ROOT 的区别
-
STATIC_URL: 浏览器访问静态文件的 URL 前缀，例如"static/"。 -
STATICFILES_DIRS: 源码中的“额外”静态文件目录（多个），供开发和收集时查找用。 -
STATIC_ROOT: 生产环境收集后的“目标目录”（只有一个）。执行python manage.py collectstatic后，来自各 app 的static/和STATICFILES_DIRS中的文件都会被复制到这里，再由 Nginx/Whitenoise/CDN 等对外提供。
简记：
- 源头：各 app 的
static/+STATICFILES_DIRS - 入口 URL：
STATIC_URL - 生产落地：
STATIC_ROOT
什么时候需要配置
- 你有不属于某个 Django app 的静态资源（例如前端工程打包产物），希望 Django 也能找到/收集它们。
- 如果所有静态文件都放在各 app 的
static/下，则可以不配置STATICFILES_DIRS。
常见配置示例
STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles" # collectstatic 的输出目录（生产）
STATICFILES_DIRS = [
BASE_DIR / "frontend" / "dist", # 前端构建产物
BASE_DIR / "assets", # 项目级静态资源
BASE_DIR.parent / "shared_static", # 项目外的同级目录
Path("D:/web-assets"), # 绝对路径（Windows 盘符）
Path(r"\\NAS\public\static"), # UNC 网络共享
]
模板或代码中引用：
{% load static %}
<link rel="stylesheet" href="{% static 'css/main.css' %}">
<script src="{% static 'app.js' %}"></script>
注意路径是相对于各个“静态根目录”里的相对路径（如 assets/css/main.css -> {% static 'css/main.css' %}）。
常见坑
- 不要把
STATIC_ROOT放进STATICFILES_DIRS，否则collectstatic时会出现递归/冲突。 - 文件名冲突时（不同目录下同名文件），后发现者会覆盖先发现者；建议用清晰的目录结构避免冲突。
- Windows 下推荐用
pathlib.Path，避免斜杠问题。 - 生产环境中 Django 不直接服务静态文件。应由 Nginx/Whitenoise/CDN 等从
STATIC_ROOT提供服务；STATICFILES_DIRS只参与“查找/收集”，不直接对外暴露。
如果你计划将前端打包产物（比如 Vite/React/Vue 的 dist）接入 Django，只需把该目录加到 STATICFILES_DIRS，开发可直接访问，部署时再运行 collectstatic 把它们复制到 STATIC_ROOT 即可。
