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_STORAGE
的 post_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
¶
在尝试复制或链接原始文件之前清除现有文件。
-
--link
,
-l
¶
创建指向每个文件的符号链接,而不是复制。
-
--no-post-process
¶
不要调用配置的
STATICFILES_STORAGE
存储后端的post_process()
方法。
-
--no-default-ignore
¶
不要忽略常见的私有glob样式模式
'CVS'
,'.*'
和'*~'
。
有关选项的完整列表,请参阅命令自己的帮助:
$ python manage.py collectstatic --help
自定义忽略的模式列表¶
与在每个 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
管理命令收集了所有静态文件
在旧版本中,您还必须在模板中使用 {% 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
应用程序外,还有一些其他助手可以使用静态文件:
django.template.context_processors.static()
上下文处理器,其将STATIC_URL
添加到用RequestContext
上下文呈现的每个模板上下文。内置模板标签
static
,它接受路径并使用静态前缀STATIC_URL
将其链接。如果安装了django.contrib.staticfiles
,则标记将使用STATICFILES_STORAGE
的url()
方法。内置模板标签
get_static_prefix
,它使用静态前缀STATIC_URL
填充模板变量以用作变量或直接。类似的模板标签
get_media_prefix
,其工作原理类似于get_static_prefix
,但使用MEDIA_URL
。
静态文件开发视图¶
静态文件工具主要用于帮助将静态文件成功部署到生产环境中。这通常意味着一个单独的,专用的静态文件服务器,这在开发本地时是很麻烦的开销。因此,staticfiles
应用程序附带一个 快速和脏的帮手视图,您可以使用它在开发中本地提供文件。
-
views.
serve
(request, path)¶
此视图函数在开发中提供静态文件。
注解
要猜测提供的文件的内容类型,此视图依赖于来自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
知道除了应用程序目录中的文件之外还要查找文件的位置。
警告
这个辅助函数只有在 DEBUG
是 True
且您的 STATIC_URL
设置既不为空也不是完整的URL(例如 http://static.example.com/
)时才能工作。
这是因为这个视图是 严重低效,可能是 不安全。这只是为了本地开发,应该 从不用于生产。
专业测试用例支持“实时测试”¶
-
class
testing.
StaticLiveServerTestCase
¶
这个单元测试TestCase子类扩展了 django.test.LiveServerTestCase
。
就像它的父,你可以使用它来编写测试,涉及运行测试中的代码,并使用测试工具通过HTTP(例如Selenium,PhantomJS等),因为它需要静态资产也发布。
但是考虑到它使用上述 django.contrib.staticfiles.views.serve()
视图,它可以在测试执行时透明地覆盖由 staticfiles
查找器提供的资产。这意味着您不需要在测试设置之前或作为测试设置的一部分运行 collectstatic
。