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

网站通常需要提供类似图片，JavaScript 或 CSS 的额外文件服务。在 Django 中，我们将这些文件称为“静态文件”。Django 提供了 django.contrib.staticfiles 帮你管理它们。

本页介绍如何为这些静态文件提供服务。

配置静态文件

  1. 确保 INSTALLED_APPS 包含了 django.contrib.staticfiles。

  2. 在配置文件中，定义 STATIC_URL，例子:

    1. STATIC_URL = '/static/'

  3. 在模板中，用 static 模板标签基于配置 STATICFILES_STORAGE 位给定的相对路径构建 URL。

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

  4. 将你的静态文件保存至程序中名为 static 的目录中。例如 my_app/static/my_app/example.jpg。

为这些文件提供服务

除了这些配置步骤外，你还需要实际地为这些文件提供服务。

开发时，使用 django.contrib.staticfiles，这一般会在 DEBUG is set to True 情况下由 runserver 自动完成（参考 django.contrib.staticfiles.views.serve()）。

该方法 极度低效 且 不怎么安全，所以这 不适合生产环境。

参考 部署静态文件 了解如何正确地在生产环境提供静态文件服务的策略。

你的工程可能包含未与任何应用绑定的静态资源。除了在 apps 中使用 static/ 目录，你可以在配置文件中定义一个目录列表 (STATICFILES_DIRS) ，Django 会从中寻找静态文件。例子:

  1. STATICFILES_DIRS = [
  2.     BASE_DIR / "static",
  3.     '/var/www/static/',
  4. ]

参考 STATICFILES_FINDERS 配置的文档了解 staticfiles 是如何找到你的文件的细节。

静态文件命名空间

Now we might be able to get away with putting our static files directly in my_app/static/ (rather than creating another my_app subdirectory), but it would actually be a bad idea. Django will use the first static file it finds whose name matches, and if you had a static file with the same name in a different application, Django would be unable to distinguish between them. We need to be able to point Django at the right one, and the best way to ensure this is by namespacing them. That is, by putting those static files inside another directory named for the application itself.

你可以通过指定 prefixes 在 STATICFILES_DIRS 中为静态资源做命名。

开发时提供静态文件服务

若你使用了前文所述的 django.contrib.staticfiles， runserver 会在 DEBUG 为 True 时自动处理。若你未在 INSTALLED_APPS 中包含 django.contrib.staticfiles，你仍能手动通过 django.views.static.serve() 为静态文件提供服务。

这不适合生产环境！常见的部署策略请参考 部署静态文件。

例如，若 STATIC_URL 为 /static/，你能通过添加以下代码片段至 urls.py 完成目的:

  1. from django.conf import settings
  2. from django.conf.urls.static import static
  4. urlpatterns = [
  5.     # ... the rest of your URLconf goes here ...
  6. ] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

注解

该助手函数只能在 debug 模式下生效，且要求前缀是本地的（例如 /static/），不是一个 URL (例如 http://static.example.com/)。

当然，助手函数只为实际的 STATIC_ROOT 目录提供服务；它不会像 django.contrib.staticfiles 一样搜索静态文件。

开发期间保存用户上传的文件

开发期间，你能用 django.views.static.serve() 视图为用户上传的媒体文件提供服务。

这不适合生产环境！常见的部署策略请参考 部署静态文件。

例如，若 MEDIA_URL 定义为 /media/，你可以通过将以下代码片段加入 urls.py 实现目的:

  1. from django.conf import settings
  2. from django.conf.urls.static import static
  4. urlpatterns = [
  5.     # ... the rest of your URLconf goes here ...
  6. ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

注解

该助手函数只能在 debug 模式下生效，且要求前缀是本地的（例如 /static/），不是一个 URL (例如 http://media.example.com/)。

测试

运行使用真实 HTTP 请求（而不是内置的测试客户端，即内置的 LiveServerTestCase）的测试用例时，静态资源要与剩余内容分别提供服务，这样，测试环境才能尽量重现真实的问题。但 LiveServerTestCase 只拥有非常基本的为静态文件提供服务的能力：它并不知道 staticfiles 应用的查找功能，且总是假设静态内容已被收集至 STATIC_ROOT 目录下。

因此， staticfiles 自带了 django.contrib.staticfiles.testing.StaticLiveServerTestCase，这是一个内置子类，能够透明地以类似我们在开发阶段 DEBUG = True 时获得的方式为所有静态资源在测试期间提供服务。即无需先用 collectstatic 收集它们。

部署

django.contrib.staticfiles 提供了一个便利的管理命令，用于将静态文件收集至独立目录，方便你为它们提供服务。

  1. 将 STATIC_ROOT 配置成你喜欢的目录，在这个目录提供服务，例如:

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

  2. 运行 collectstatic 管理命令:

    1. $ python manage.py collectstatic

    这将会把静态目录下的所有文件拷贝至 STATIC_ROOT 目录。

  3. 选一个 Web 服务器为这些文件提供服务。 文档 部署静态文件 介绍了静态文件的常见部署策略。

了解更多

本文档已覆盖基础和常见模式。对于所有配置项，命令，模板标签和其他包含在 django.contrib.staticfiles 碎片的全部细节，参考 静态文件参考。