Skip to main content

staticfiles 应用程序

django.contrib.staticfiles 从每个应用程序(以及您指定的任何其他位置)将静态文件收集到一个可以轻松在生产环境中提供的位置。

参见

有关静态文件应用程序和一些使用示例的介绍,请参阅 管理静态文件(例如图片,JavaScript,CSS)。有关部署静态文件的准则,请参阅 部署静态文件

管理命令

django.contrib.staticfiles 公开了三个管理命令。

collectstatic

django-admin collectstatic

将静态文件收集到 STATIC_ROOT 中。

默认情况下,重复文件名以类似于模板分辨率工作原理的方式解析:将使用首先在指定位置之一找到的文件。如果你困惑,findstatic 命令可以帮助显示找到哪些文件。

在后续的 collectstatic 运行时(如果 STATIC_ROOT 不为空),仅当文件的修改时间戳大于 STATIC_ROOT 中文件的时间戳时,才会复制文件。因此,如果从 INSTALLED_APPS 中删除应用程序,最好使用 collectstatic --clear 选项为了删除过时的静态文件。

使用 enabled finders 搜索文件。默认值是查看 STATICFILES_DIRS 中定义的所有位置以及 INSTALLED_APPS 设置指定的应用程序的 'static' 目录中。

collectstatic 管理命令在每次运行后调用 STATICFILES_STORAGEpost_process() 方法,并传递管理命令找到的路径列表。它还接收 collectstatic 的所有命令行选项。默认情况下,它由 CachedStaticFilesStorage 使用。

默认情况下,收集的文件从 FILE_UPLOAD_PERMISSIONS 接收权限,收集的目录从 FILE_UPLOAD_DIRECTORY_PERMISSIONS 接收权限。如果您希望对这些文件和/或目录使用不同的权限,可以将 静态文件存储类 子类化,并分别指定 file_permissions_mode 和/或 directory_permissions_mode 参数。例如:

from django.contrib.staticfiles import storage

class MyStaticFilesStorage(storage.StaticFilesStorage):
    def __init__(self, *args, **kwargs):
        kwargs['file_permissions_mode'] = 0o640
        kwargs['directory_permissions_mode'] = 0o760
        super(MyStaticFilesStorage, self).__init__(*args, **kwargs)

然后将 STATICFILES_STORAGE 设置为 'path.to.MyStaticFilesStorage'

一些常用的选项是:

--noinput, --no-input

不要提示用户输入任何类型。

Changed in Django 1.9:

添加了 --no-input 别名。

--ignore PATTERN, -i PATTERN

忽略与此glob样式模式匹配的文件或目录。使用多次忽略更多。

--dry-run, -n

除了修改文件系统以外的所有操作。

--clear, -c

在尝试复制或链接原始文件之前清除现有文件。

创建指向每个文件的符号链接,而不是复制。

--no-post-process

不要调用配置的 STATICFILES_STORAGE 存储后端的 post_process() 方法。

--no-default-ignore

不要忽略常见的私有glob样式模式 'CVS''.*''*~'

有关选项的完整列表,请参阅命令自己的帮助:

$ python manage.py collectstatic --help

自定义忽略的模式列表

New in Django 1.10.

与在每个 collectstatic 调用中提供 --ignore 命令选项相比,可以以更持久的方式定制默认的被忽略模式列表 ['CVS', '.*', '*~']。提供自定义 AppConfig 类,覆盖此类的 ignore_patterns 属性,并在您的 INSTALLED_APPS 设置中将 'django.contrib.staticfiles' 替换为该类路径:

from django.contrib.staticfiles.apps import StaticFilesConfig

class MyStaticFilesConfig(StaticFilesConfig):
    ignore_patterns = [...]  # your custom ignore list

findstatic

django-admin findstatic staticfile [staticfile ...]

使用已启用的查找器搜索一个或多个相对路径。

例如:

$ python manage.py findstatic css/base.css admin/js/core.js
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Found 'admin/js/core.js' here:
  /home/polls.com/src/django/contrib/admin/media/js/core.js
findstatic --first

默认情况下,找到所有匹配的位置。要仅返回每个相对路径的第一个匹配,请使用 --first 选项:

$ python manage.py findstatic css/base.css --first
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css

这是一个调试助手;它将向您显示将为给定路径收集哪个静态文件。

通过将 --verbosity 标志设置为0,可以抑制额外的输出,并只获取路径名称:

$ python manage.py findstatic css/base.css --verbosity 0
/home/special.polls.com/core/static/css/base.css
/home/polls.com/core/static/css/base.css

另一方面,通过将 --verbosity 标志设置为2,可以获得所有搜索的目录:

$ python manage.py findstatic css/base.css --verbosity 2
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Looking in the following locations:
  /home/special.polls.com/core/static
  /home/polls.com/core/static
  /some/other/path/static

runserver

django-admin runserver [addrport]

如果 staticfiles 应用程序是 installed,则覆盖核心 runserver 命令,并添加自动提供的静态文件和以下新选项。

--nostatic

使用 --nostatic 选项来完全禁止使用 静态文件 应用程序提供静态文件。此选项仅在 静态文件 应用程序位于项目的 INSTALLED_APPS 设置中时可用。

用法示例:

django-admin runserver --nostatic
--insecure

使用 --insecure 选项强制使用 静态文件 应用程序提供静态文件,即使 DEBUG 设置为 False。通过使用这一点你承认这是事实,它是 严重低效 和可能 不安全。这只适用于本地开发,应该是 从不用于生产,并且仅当 静态文件 应用程序在您项目的 INSTALLED_APPS 设置中时才可用。 runserver --insecure 不与 CachedStaticFilesStorage 一起使用。

用法示例:

django-admin runserver --insecure

存储

StaticFilesStorage

class storage.StaticFilesStorage

FileSystemStorage 存储后端的子类,它使用 STATIC_ROOT 设置作为基本文件系统位置和 STATIC_URL 设置分别作为基本URL。

storage.StaticFilesStorage.post_process(paths, **options)

此方法在每次运行后由 collectstatic 管理命令调用,并将找到的文件的本地存储和路径作为字典以及命令行选项传递。

CachedStaticFilesStorage 在幕后使用它来替换路径与它们的哈希对等体并适当地更新缓存。

ManifestStaticFilesStorage

class storage.ManifestStaticFilesStorage

StaticFilesStorage 存储后端的子类,它通过将文件内容的MD5哈希附加到文件名来存储它处理的文件名。例如,文件 css/styles.css 也将另存为 css/styles.55e7cbb9ba48.css

这种存储的目的是在一些页面仍然引用这些文件的情况下继续提供旧文件,例如。因为它们由您或第三方代理服务器缓存。此外,如果要将 far future Expires headers 应用于部署的文件以加快后续页面访问的加载时间,这将非常有帮助。

存储后端会自动将保存的文件中匹配其他已保存文件的路径替换为缓存副本的路径(使用 post_process() 方法)。默认情况下,用于查找这些路径(django.contrib.staticfiles.storage.HashedFilesMixin.patterns)的正则表达式涵盖 Cascading Style Sheets@import 规则和 url() 语句。例如,'css/styles.css' 文件带有内容

@import url("../admin/css/base.css");

将被替换为调用 ManifestStaticFilesStorage 存储后端的 url() 方法,最终保存具有以下内容的 'css/styles.55e7cbb9ba48.css' 文件:

@import url("../admin/css/base.27e20196a850.css");

要启用 ManifestStaticFilesStorage,您必须确保满足以下要求:

  • STATICFILES_STORAGE 设置设置为 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'

  • DEBUG 设置设置为 False

  • 您已通过使用 collectstatic 管理命令收集了所有静态文件

Changed in Django 1.10:

在旧版本中,您还必须在模板中使用 {% load static from staticfiles %}static 模板标签({% load static %})现在使用 django.contrib.staticfiles (如果已安装)。

由于创建MD5哈希值会对运行时的网站造成性能负担,因此 staticfiles 会自动将所有已处理文件的哈希名称映射存储在名为 staticfiles.json 的文件中。这在您运行 collectstatic 管理命令时发生一次。

由于运行 collectstatic 的要求,在运行测试时不应使用此存储器,因为 collectstatic 不作为正常测试设置的一部分运行。在测试期间,请确保 STATICFILES_STORAGE 设置设置为其他类似 'django.contrib.staticfiles.storage.StaticFilesStorage' (默认值)。

storage.ManifestStaticFilesStorage.file_hash(name, content=None)

创建文件的散列名称时使用的方法。需要返回给定文件名和内容的哈希值。默认情况下,它从内容的块计算MD5哈希,如上所述。随意覆盖此方法使用自己的哈希算法。

CachedStaticFilesStorage

class storage.CachedStaticFilesStorage

CachedStaticFilesStorage 是类似于 ManifestStaticFilesStorage 类的类,但使用Django的 caching framework 来存储已处理文件的哈希名称,而不是称为 staticfiles.json 的静态清单文件。这在您无权访问文件系统的情况下非常有用。

如果要覆盖存储使用的高速缓存后端的某些选项,只需在名为 'staticfiles'CACHES 设置中指定自定义条目即可。它回到使用 'default' 缓存后端。

查找模块

staticfiles 查找器具有 searched_locations 属性,其是查找器搜索的目录路径的列表。用法示例:

from django.contrib.staticfiles import finders

result = finders.find('css/base.css')
searched_locations = finders.searched_locations

其他帮助

除了 staticfiles 应用程序外,还有一些其他助手可以使用静态文件:

静态文件开发视图

静态文件工具主要用于帮助将静态文件成功部署到生产环境中。这通常意味着一个单独的,专用的静态文件服务器,这在开发本地时是很麻烦的开销。因此,staticfiles 应用程序附带一个 快速和脏的帮手视图,您可以使用它在开发中本地提供文件。

views.serve(request, path)

此视图函数在开发中提供静态文件。

警告

此视图将仅在 DEBUGTrue 时有效。

这是因为这个视图是 严重低效,可能是 不安全。这只是为了本地开发,应该 从不用于生产

注解

要猜测提供的文件的内容类型,此视图依赖于来自Python标准库的 mimetypes 模块,该模块本身依赖于底层平台的映射文件。如果您发现此视图没有为特定文件返回正确的内容类型,则很可能是平台的地图文件需要更新。这可以通过例如在Red Hat发行版上安装或更新 mailcap 软件包,或者在Debian发行版上安装或更新 mime-support 来实现。

此视图由 runserver 自动启用(DEBUG 设置设置为 True)。要使用不同本地开发服务器的视图,请将以下代码段添加到主URL配置的末尾:

from django.conf import settings
from django.contrib.staticfiles import views

if settings.DEBUG:
    urlpatterns += [
        url(r'^static/(?P<path>.*)$', views.serve),
    ]

注意,模式(r'^static/')的开始应该是您的 STATIC_URL 设置。

因为这有点麻烦,还有一个帮助函数,将为你做这个:

urls.staticfiles_urlpatterns()

这将返回正确的URL模式,用于将静态文件提供给已定义的模式列表。使用它像这样:

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

# ... the rest of your URLconf here ...

urlpatterns += staticfiles_urlpatterns()

这将检查您的 STATIC_URL 设置,并连接视图以相应地提供静态文件。不要忘记适当地设置 STATICFILES_DIRS 设置,以便让 django.contrib.staticfiles 知道除了应用程序目录中的文件之外还要查找文件的位置。

警告

这个辅助函数只有在 DEBUGTrue 且您的 STATIC_URL 设置既不为空也不是完整的URL(例如 http://static.example.com/)时才能工作。

这是因为这个视图是 严重低效,可能是 不安全。这只是为了本地开发,应该 从不用于生产

专业测试用例支持“实时测试”

class testing.StaticLiveServerTestCase

这个单元测试TestCase子类扩展了 django.test.LiveServerTestCase

就像它的父,你可以使用它来编写测试,涉及运行测试中的代码,并使用测试工具通过HTTP(例如Selenium,PhantomJS等),因为它需要静态资产也发布。

但是考虑到它使用上述 django.contrib.staticfiles.views.serve() 视图,它可以在测试执行时透明地覆盖由 staticfiles 查找器提供的资产。这意味着您不需要在测试设置之前或作为测试设置的一部分运行 collectstatic