如何管理静态文件（图片、JavaScript、CSS 等）

网站通常需要提供图片、JavaScript 或 CSS 等附加文件。在 Django 中，我们把这些文件称为“静态文件”。Django 提供 django.contrib.staticfiles 来帮助管理它们。

本页介绍如何向客户端提供这些静态文件。

配置静态文件

1. 确保 INSTALLED_APPS 包含 django.contrib.staticfiles。
2. 在设置文件中定义 STATIC_URL，例如：

   STATIC_URL = "static/"
   

3. 在模板中，使用 static 模板标签，根据已配置的 STORAGES 中的 staticfiles 别名，为给定的相对路径生成 URL。

   {% load static %}
   <img src="{% static 'my_app/example.jpg' %}" alt="My image">
   

4. 把静态文件存放在应用内名为 static 的目录中，例如 my_app/static/my_app/example.jpg。

项目很可能还包含不属于某个特定应用的静态资源。除了在各个应用内使用 static/ 目录，还可以在设置文件中定义目录列表 STATICFILES_DIRS，Django 同样会到这些目录中查找静态文件。例如：

STATICFILES_DIRS = [
    BASE_DIR / "static",
    "/var/www/static/",
]

关于 staticfiles 如何查找文件的细节，参见 STATICFILES_FINDERS 设置文档。

开发期间提供静态文件服务

如果按上文所述使用 django.contrib.staticfiles，当 DEBUG 为 True 时，runserver 会自动处理静态文件。如果 INSTALLED_APPS 中没有 django.contrib.staticfiles，仍然可以用 django.views.static.serve() 视图手动提供静态文件服务。

这种方法不适合生产环境！ 常见部署策略见如何部署静态文件。

例如，如果 STATIC_URL 定义为 static/，可以在 urls.py 中加入以下片段：

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

开发期间提供用户上传文件的服务

在开发期间，可以用 django.views.static.serve() 视图提供 MEDIA_ROOT 中由用户上传的媒体文件。

这种方法不适合生产环境！ 常见部署策略见如何部署静态文件。

例如，如果 MEDIA_URL 定义为 media/，可以在 ROOT_URLCONF 中加入以下片段：

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

测试

运行使用真实 HTTP 请求而非内置测试客户端的测试时，例如使用内置 LiveServerTestCase，静态资源需要与其他内容一起提供，以便测试环境尽可能忠实地再现真实环境。但 LiveServerTestCase 只提供非常基本的静态文件服务功能：它不了解 staticfiles 应用的查找器功能，并且假设静态内容已经收集到 STATIC_ROOT。

因此，staticfiles 提供了自己的 django.contrib.staticfiles.testing.StaticLiveServerTestCase。它是内置类的子类，能在这些测试运行期间透明地提供全部静态资源，方式与开发期间 DEBUG = True 时非常相似，也就是无须先通过 collectstatic 收集文件。

部署

django.contrib.staticfiles 提供了方便的管理命令，可以把静态文件集中到单个目录，方便提供服务。

1. 将 STATIC_ROOT 设置为希望提供这些文件的目录，例如：

   STATIC_ROOT = "/var/www/example.com/static/"
   

2. 运行 collectstatic 管理命令：

   $ python manage.py collectstatic
   

   它会把所有静态文件夹中的文件复制到 STATIC_ROOT 目录。

3. 使用你选择的 Web 服务器提供这些文件。如何部署静态文件 介绍了一些常见策略。

了解更多

本文介绍了基础知识和一些常见用法。有关 django.contrib.staticfiles 包含的所有设置、命令、模板标签及其他组成部分的完整细节，参见staticfiles 参考文档。