staticfiles app

django.contrib.staticfiles collects static files from each of your applications (and any other places you specify) into a single location that can easily be served in production.

也可以看看

有关静态文件应用程序和一些使用示例的介绍,请参见Managing static files (e.g. images, JavaScript, CSS) 有关部署静态文件的指导,请参阅Deploying static files

管理命令

django.contrib.staticfiles exposes three management commands.

collectstatic

django-admin collectstatic

将静态文件收集到STATIC_ROOT中。

重复文件名的默认解析方式与模板解析的工作方式类似:首先在指定位置之一中找到的文件将被使用。 If you’re confused, the findstatic command can help show you which files are found.

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

通过使用enabled finders来搜索文件。 缺省情况下,查找由INSTALLED_APPS设置指定的应用程序的STATICFILES_DIRS'static'目录中定义的所有位置。

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

By default, collected files receive permissions from FILE_UPLOAD_PERMISSIONS and collected directories receive permissions from 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().__init__(*args, **kwargs)

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

一些常用的选项是:

- noinput T0>, - 无输入 T0> T1> ¶ T2>

不要提示用户输入任何形式的信息。

- 忽视 模式, -一世 模式

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

- 空转 T0>, -n T0> T1> ¶ T2>

除了修改文件系统之外,一切都可以

- 明确 T0>, -c T0> T1> ¶ T2>

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

创建一个符号链接到每个文件,而不是复制。

- 无后处理 T0> T1> ¶ T2>

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

- 无 - 缺省 - 忽略 T0> T1> ¶ T2>

不要忽略常见的私有glob风格模式'CVS' ”。*” '*~'

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

$ python manage.py collectstatic --help

自定义被忽略的模式列表

默认忽略模式列表, [ 'CVS', ”。*”, '*〜'],可以比在每个collectstatic调用中提供--ignore命令选项更持久地定制。 Provide a custom AppConfig class, override the ignore_patterns attribute of this class and replace 'django.contrib.staticfiles' with that class path in your INSTALLED_APPS setting:

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选项:

$ 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]

Overrides the core runserver command if the staticfiles app is installed and adds automatic serving of static files. 文件服务不通过MIDDLEWARE运行。

该命令添加这些选项:

- nostatic T0> T1> ¶ T2>

使用--nostatic选项完全禁止静态文件与staticfiles应用程序的服务。 此选项仅适用于staticfiles应用程序在您的项目的INSTALLED_APPS设置中。

用法示例:

django-admin runserver --nostatic
- 不安全 T0> T1> ¶ T2>

即使DEBUG设置为False,也可以使用--insecure选项强制使用staticfiles应用程序提供静态文件>。 By using this you acknowledge the fact that it’s grossly inefficient and probably insecure. 这只适用于本地开发,应该永不用于生产,并且只有在staticfiles应用程序在您的项目的INSTALLED_APPS设置中才可用。

--insecure不适用于ManifestStaticFilesStorageCachedStaticFilesStorage

用法示例:

django-admin runserver --insecure

存储器¶ T0>

StaticFilesStorage

存储。 StaticFilesStorage T0> ¶ T1>

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

storage.StaticFilesStorage。post_process路径**选项

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

CachedStaticFilesStorage在后台使用它来替换具有散列对象的路径,并适当地更新缓存。

ManifestStaticFilesStorage

存储。 ManifestStaticFilesStorage T0> ¶ T1>

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

这种存储的目的是在某些页面仍然引用这些文件的情况下继续服务旧文件,例如,因为它们是由您或第三方代理服务器缓存的。 Additionally, it’s very helpful if you want to apply far future Expires headers to the deployed files to speed up the load time for subsequent page visits.

存储后端会自动使用缓存副本的路径(使用post_process()方法)将匹配其他保存文件的保存文件中找到的路径替换掉。 The regular expressions used to find those paths (django.contrib.staticfiles.storage.HashedFilesMixin.patterns) by default covers the @import rule and url() statement of Cascading Style Sheets. 例如,带有内容的'css/styles.css'文件

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

将被ManifestStaticFilesStorage存储后端的url()方法取代,最终保存一个'css/styles.55e7cbb9ba48.css'文件具有以下内容:

@import url("../admin/css/base.27e20196a850.css");
storage.ManifestStaticFilesStorage。 max_post_process_passes T0> ¶ T1>

由于静态文件可能会引用其他需要替换其路径的静态文件,因此可能需要多次替换路径,直到文件哈希聚合。 为了防止由于哈希不收敛(例如,如果'foo.css'引用'bar.css'引用'foo.css')在放弃后处理之前有最大数量的通行证。 在有大量参考文献的情况下,可能需要更多的参考文献。 通过继承ManifestStaticFilesStorage并设置max_post_process_passes属性来增加最大传递次数。 它默认为5。

在Django 1.11中更改:

以前的版本没有进行多次传递以确保文件哈希聚合,所以通常文件哈希时间不正确。 添加了max_post_process_passes属性。

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

  • STATICFILES_STORAGE设置设置为'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
  • DEBUG设置被设置为False
  • 您已经使用collectstatic管理命令收集了所有的静态文件

Since creating the MD5 hash can be a performance burden to your website during runtime, staticfiles will automatically store the mapping with hashed names for all processed files in a file called staticfiles.json. 运行collectstatic管理命令时会发生一次。

storage.ManifestStaticFilesStorage。 manifest_strict T0> ¶ T1>

如果在运行时在staticfiles.json清单中找不到文件,则会引发ValueError 通过继承ManifestStaticFilesStorage并将manifest_strict属性设置为False,可以禁用此行为 - 不存在的路径将保持不变。

在Django 1.11中更改:

添加了manifest_strict属性。 在旧版本中,行为与manifest_strict=False相同。

由于运行collectstatic的要求,运行测试时通常不应使用此存储,因为collectstatic未作为正常测试设置的一部分运行。 在测试过程中,确保将STATICFILES_STORAGE设置设置为其他类似于'django.contrib.staticfiles.storage.StaticFilesStorage'的设置。

storage.ManifestStaticFilesStorage。file_hashnamecontent = None

创建文件的哈希名称时使用的方法。 需要为给定的文件名和内容返回一个散列。 默认情况下,如上所述,它从内容块中计算MD5哈希值。 随意重写这个方法来使用你自己的哈希算法。

CachedStaticFilesStorage

存储。 CachedStaticFilesStorage T0> ¶ T1>

CachedStaticFilesStorage is a similar class like the ManifestStaticFilesStorage class but uses Django’s caching framework for storing the hashed names of processed files instead of a static manifest file called staticfiles.json. 这对于无法访问文件系统的情况非常有用。

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

警告

CachedStaticFilesStorage isn’t recommended – in almost all cases ManifestStaticFilesStorage is a better choice. 使用CachedStaticFilesStorage时会有几个性能损失,因为缓存未命中需要在运行时散列文件。 远程文件存储需要多次往返才能在缓存未命中时散列文件,因为需要进行多次文件访问才能确保文件散列在嵌套文件路径的情况下是正确的。

Finders模块

staticfiles finders has a searched_locations attribute which is a list of directory paths in which the finders searched. 用法示例:

from django.contrib.staticfiles import finders

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

其他助手

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

静态文件开发视图

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

观点。serverequestpath

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

警告

这个视图只有在DEBUGTrue时才有效。

That’s because this view is grossly inefficient and probably insecure. This is only intended for local development, and should never be used in production.

注意

To guess the served files’ content types, this view relies on the mimetypes module from the Python standard library, which itself relies on the underlying platform’s map files. 如果您发现此视图不能为某些文件返回适当的内容类型,则很可能需要更新平台的地图文件。 这可以通过在Debian发行版上安装或更新Red Hat发行版上的mailcap软件包或mime-support来实现。

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

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

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

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

由于这有点挑剔,还有一个辅助函数可以帮你做到这一点:

网址。 staticfiles_urlpatterns T0>()¶ T1>

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

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

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

urlpatterns += staticfiles_urlpatterns()

这将检查您的STATIC_URL设置并连接视图以相应地提供静态文件。 Don’t forget to set the STATICFILES_DIRS setting appropriately to let django.contrib.staticfiles know where to look for files in addition to files in app directories.

警告

如果DEBUGTrue且您的STATIC_URL设置既不为空也不是完整的URL,例如http://static.example.com/

That’s because this view is grossly inefficient and probably insecure. This is only intended for local development, and should never be used in production.

支持“实时测试”的专门测试用例

测试。 StaticLiveServerTestCase T0> ¶ T1>

这个unittest TestCase子类扩展了django.test.LiveServerTestCase

就像它的父类一样,你可以用它来编写测试,包括运行测试代码,并通过HTTP(如Selenium,PhantomJS等)通过测试工具来使用测试代码,因为需要静态资源也被发布。

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