Skip to main content

管理静态文件(例如图片,JavaScript,CSS)

网站通常需要提供其他文件,例如图片,JavaScript或CSS。在Django中,我们将这些文件称为“静态文件”。 Django提供 django.contrib.staticfiles 来帮助您管理它们。

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

配置静态文件

  1. 确保 django.contrib.staticfiles 包含在您的 INSTALLED_APPS 中。

  2. 在您的设置文件中,例如定义 STATIC_URL:

    STATIC_URL = '/static/'
    
  3. 在您的模板中,硬编码像 /static/my_app/example.jpg 的URL,或者,最好使用 static 模板标签通过使用配置的 STATICFILES_STORAGE 存储来构建给定相对路径的URL(这使得当您想切换到内容交付网络(CDN)用于提供静态文件)。

    {% load static %}
    <img src="{% static "my_app/example.jpg" %}" alt="My image"/>
    
  4. 将静态文件存储在应用程序中名为 static 的文件夹中。例如 my_app/static/my_app/example.jpg

提供文件

除了这些配置步骤,您还需要实际提供静态文件。

在开发过程中,如果使用 django.contrib.staticfiles,当 DEBUG 设置为 True (参见 django.contrib.staticfiles.views.serve())时,将由 runserver 自动完成。

这个方法是 严重低效,可能是 不安全,所以它是 不适合生产

有关在生产环境中提供静态文件的正确策略,请参阅 部署静态文件

您的项目可能还会有与特定应用程序无关的静态资源。除了在应用程序中使用 static/ 目录之外,还可以在设置文件中定义目录列表(STATICFILES_DIRS),其中Django还将查找静态文件。例如:

STATICFILES_DIRS = [
    os.path.join(BASE_DIR, "static"),
    '/var/www/static/',
]

有关 staticfiles 如何查找文件的详细信息,请参阅 STATICFILES_FINDERS 设置的文档。

静态文件命名空间

现在我们 might 能够放弃我们的静态文件直接在 my_app/static/ (而不是创建另一个 my_app 子目录),但它实际上是一个坏主意。 Django将使用它找到的名字匹配的第一个静态文件,如果你在 different 应用程序中有一个相同名称的静态文件,Django将无法区分它们。我们需要能够指向Django在正确的一个,和最简单的方法来确保这是由 namespacing 他们。也就是说,将这些静态文件放在为应用程序本身命名的 another 目录中。

在开发期间提供静态文件

如果您使用如上所述的 django.contrib.staticfilesrunserver 将在 DEBUG 设置为 True 时自动执行此操作。如果您在 INSTALLED_APPS 中没有 django.contrib.staticfiles,您仍然可以使用 django.contrib.staticfiles.views.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)

注解

此辅助函数仅在调试模式下工作,且仅当给定前缀是本地(例如 /static/)而不是URL(例如 http://static.example.com/)时才起作用。

此辅助函数只服务实际的 STATIC_ROOT 文件夹;它不执行静态文件发现像 django.contrib.staticfiles

投放用户在开发过程中上传的文件

在开发过程中,您可以使用 django.contrib.staticfiles.views.serve() 视图从 MEDIA_ROOT 提供用户上传的媒体文件。

这不适合生产使用!有关一些常见的部署策略,请参阅 部署静态文件

例如,如果您的 MEDIA_URL 定义为 /media/,您可以通过将以下代码段添加到您的urls.py:

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)

注解

此辅助函数仅在调试模式下工作,且仅当给定前缀是本地(例如 /media/)而不是URL(例如 http://media.example.com/)时才起作用。

测试

当运行使用实际HTTP请求而不是内置测试客户端(即使用内置 LiveServerTestCase)的测试时,静态资产需要沿着内容的其余部分提供,以便测试环境忠实地再现真实的可能,但 LiveServerTestCase 只有非常基本的静态文件服务功能:它不知道 staticfiles 应用程序的finders功能,并假设静态内容已经在 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 中包含的所有设置,命令,模板标签和其他部分的完整详细信息,请参阅 静态文件引用