Django 1.8.2.dev20150513143415文档

静态文件应用

django.contrib.staticfiles 从你的应用(和其他你指定的地方)收集所有静态文件到同一个地方,这样产品就能很容易的被维护

看看这里

对于静态文件的应用和一些用法示例的介绍,请参阅管理静态文件(CSS,图像) . 如果你想知道如何部署静态文件, 请参阅 部署静态文件.

管理命令

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

搜集静态文件

django-admin collectstatic

搜集静态文件到 STATIC_ROOT.

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

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

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

默认情况下,收集的文件从FILE_UPLOAD_PERMISSIONS接收权限,收集的目录从FILE_UPLOAD_DIRECTORY_PERMISSIONS接收权限。如果您希望对这些文件和/或目录使用不同的权限,可以暂存static files storage classes,并指定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'

New in Django 1.7:

覆盖file_permissions_modedirectory_permissions_mode的功能是Django 1.7中的新功能。以前,文件权限始终使用FILE_UPLOAD_PERMISSIONS和始终使用的目录权限FILE_UPLOAD_DIRECTORY_PERMISSIONS

一些常用的选项是:

--noinput

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

-i <pattern>
--ignore <pattern>

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

-n
--dry-run

除了修改文件系统之外,执行所有操作。

-c
--clear

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

-l

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

--no-post-process

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

--no-default-ignore

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

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

$ python manage.py collectstatic --help

findstatic

django-admin findstatic

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

例如:

$ 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

默认情况下,找到所有匹配的位置。要仅返回每个相对路径的第一个匹配,请使用--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
New in Django 1.7:

添加了搜索其目录的其他输出。

runserver

django-admin runserver

Overrides the core runserver command if the staticfiles app is installed and adds automatic serving of static files and the following new options.

--nostatic

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

用法示例:

django-admin runserver --nostatic
--insecure

使用--insecure选项强制使用staticfiles应用程式提供静态档案,即使DEBUG设定为False通过使用此功能,您可以确认严重无效以及可能不安全这只适用于本地开发,应从不用于生产,并且仅当staticfiles应用程序位于项目的INSTALLED_APPS设置时可用。runserver--insecure不适用于CachedStaticFilesStorage

用法示例:

django-admin runserver --insecure

存储

StaticFilesStorage

class storage.StaticFilesStorage

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

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

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

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

ManifestStaticFilesStorage

New in Django 1.7.
class storage.ManifestStaticFilesStorage

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

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

存储后端会自动使用缓存副本的路径(使用post_process()方法)替换保存的文件中与其他已保存文件匹配的路径。默认情况下,用于查找这些路径(django.contrib.staticfiles.storage.HashedFilesMixin.patterns)的正则表达式涵盖@import规则和url() / t3> 级联样式表的语句。例如,'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
  • 您可以使用staticfiles static模板标记来引用模板中的静态文件
  • 您已使用collectstatic管理命令收集了所有静态文件

由于创建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_STORAGE存储来为给定的相对路径创建完整的网址,例如:

{% load static from staticfiles %}
<img src="{% static "images/hi.jpg" %}" alt="Hi!" />

上一个示例等于使用"images/hi.jpg"调用STATICFILES_STORAGE实例的url方法。这在使用非本地存储后端部署文件时特别有用,如Serving static files from a cloud service or CDN提供静态文件中所述。

如果您希望在不显示静态网址的情况下检索静态网址,则可以使用略有不同的调用:

{% load static from staticfiles %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}" alt="Hi!" />

查找模块

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

from django.contrib.staticfiles import finders

result = finders.find('css/base.css')
searched_locations = finders.searched_locations
New in Django 1.7.

已添加searched_locations属性。

其他帮助

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

静态文件开发视图

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

views.serve(request, path)

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

警告

此视图仅在DEBUGTrue时有效。

这是因为此视图严重无效,可能不安全这只适用于本地开发,应从不用于生产

Changed in Django 1.7:

DEBUGFalse时,此视图现在将引发Http404异常而不是ImproperlyConfigured

注意

要猜测提供的文件的内容类型,此视图依赖于来自Python标准库的mimetypes模块,该模块本身依赖于底层平台的映射文件。如果您发现此视图没有为特定文件返回正确的内容类型,则很可能是平台的地图文件需要更新。这可以通过在Debian发行版上安装或更新Red Hat发行版上的mailcap软件包或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/,这个帮助功能才会工作。

这是因为该视图 效率不高 并且很可能 不安全. 该视图仅适用于本地开发 ,而不应该用于项目实际生产环境.

Specialized test case to support ‘live testing’

class testing.StaticLiveServerTestCase

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

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

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

New in Django 1.7:

StaticLiveServerTestCase是Django 1.7中的新功能。以前,它的功能由django.test.LiveServerTestCase提供。