staticfiles 应用程序 — Django 文档

来自菜鸟教程
Django/docs/3.0.x/ref/contrib/staticfiles
跳转至：导航、​搜索

staticfiles 应用程序

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

也可以看看

有关静态文件应用程序的介绍和一些使用示例，请参阅管理静态文件（例如 图片、JavaScript、CSS） . 有关部署静态文件的指南，请参阅 部署静态文件 。


管理命令

django.contrib.staticfiles 暴露了三个管理命令。

collectstatic

将静态文件收集到 :setting:`STATIC_ROOT`。

默认情况下，重复文件名的解析方式与模板解析的工作方式类似：将使用首先在指定位置之一中找到的文件。 如果您感到困惑，:djadmin:`findstatic` 命令可以帮助您显示找到了哪些文件。

在随后的 collectstatic 运行中（如果 STATIC_ROOT 不为空），仅当文件的修改时间戳大于 STATIC_ROOT 中文件的时间戳时，才会复制文件。 因此，如果您从 :setting:`INSTALLED_APPS` 中删除应用程序，最好使用 collectstatic --clear 选项来删除过时的静态文件。

使用以下命令搜索文件 :setting:`启用的查找器 ` . 默认是在 :setting:`STATICFILES_DIRS` 中定义的所有位置以及 :setting:`INSTALLED_APPS` 设置指定的应用程序的 'static' 目录中查找.

:djadmin:`collectstatic` 管理命令在每次运行后调用 post_process():setting:`STATICFILES_STORAGE` 方法并传递路径列表已被管理命令发现。 它还接收 :djadmin:`collectstatic` 的所有命令行选项。 默认情况下，它由 ManifestStaticFilesStorage 使用。

默认情况下，收集的文件从 :setting:`FILE_UPLOAD_PERMISSIONS` 获得权限，收集的目录从 :setting:`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().__init__(*args, **kwargs)

然后将 :setting:`STATICFILES_STORAGE` 设置为 'path.to.MyStaticFilesStorage'。

一些常用的选项是：

有关选项的完整列表，请通过运行以下命令来参考命令本身的帮助：

自定义忽略的模式列表

默认忽略的模式列表 ['CVS', '.*', '*~'] 可以以比在每次 collectstatic 调用时提供 --ignore 命令选项更持久的方式进行自定义。 提供一个自定义的 AppConfig 类，覆盖这个类的 ignore_patterns 属性，并在你的 :setting:`INSTALLED_APPS` 中用那个类路径替换 'django.contrib.staticfiles'环境： 

from django.contrib.staticfiles.apps import StaticFilesConfig

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

findstatic

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

例如：

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

这是一个调试帮助； 它将准确显示将为给定路径收集哪个静态文件。

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

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


runserver

覆盖核心 :djadmin:`运行服务器` 命令如果staticfiles应用程序是 :setting:`已安装 ` 并添加静态文件的自动服务。 文件服务不通过 :setting:`MIDDLEWARE`。

该命令添加了以下选项：

使用 --nostatic 选项完全禁用 staticfiles 应用程序的静态文件服务。 此选项仅在 staticfiles 应用程序位于您项目的 :setting:`INSTALLED_APPS` 设置中时可用。

用法示例：

使用 --insecure 选项强制使用 staticfiles 应用程序提供静态文件，即使 :setting:`DEBUG` 设置为 False。 通过使用它，您承认它 效率非常低 并且可能 不安全 。 这仅适用于本地开发，不应将 用于生产中 ，并且仅当 staticfiles 应用程序位于您项目的 :setting:`INSTALLED_APPS` 中时才可用环境。

--insecure 不适用于 ManifestStaticFilesStorage。

用法示例：


存储

StaticFilesStorage

class storage.StaticFilesStorage

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

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

如果此方法定义在存储上，则在每次运行后由 :djadmin:`collectstatic` 管理命令调用，并以字典形式传递本地存储和找到的文件的路径，以及命令线选项。 它产生三个值的元组：original_path, processed_path, processed。 路径值是字符串，processed 是一个布尔值，指示该值是否经过后处理，或者如果后处理失败则为异常。

ManifestStaticFilesStorage 在幕后使用它来用它们的散列对应物替换路径并适当地更新缓存。


ManifestStaticFilesStorage

class storage.ManifestStaticFilesStorage

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

此存储的目的是继续为旧文件提供服务，以防某些页面仍然引用这些文件，例如 因为它们是由您或第 3 方代理服务器缓存的。 此外，如果您想将 远期过期标头 应用于已部署的文件以加快后续页面访问的加载时间，这将非常有用。

存储后端自动用缓存副本的路径（使用 post_process() 方法）替换在与其他保存文件匹配的保存文件中找到的路径。 用于查找这些路径的正则表达式 (django.contrib.staticfiles.storage.HashedFilesMixin.patterns) 默认涵盖 @import 规则和 Cascading Style Sheets 的 url() 语句. 例如，带有内容的 '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

由于静态文件可能会引用其他需要替换其路径的静态文件，因此可能需要多次替换路径，直到文件哈希收敛。 为了防止由于散列不收敛而导致的无限循环（例如，如果 'foo.css' 引用 'bar.css' 引用 'foo.css'），则在放弃后处理之前存在最大传递次数. 在有大量引用的情况下，可能需要更多的传递次数。 通过子类化 ManifestStaticFilesStorage 并设置 max_post_process_passes 属性来增加最大传递次数。 默认为 5。

要启用 ManifestStaticFilesStorage，您必须确保满足以下要求：

由于在运行期间创建 MD5 哈希可能会给您的网站带来性能负担，因此 staticfiles 将自动将所有处理文件的带有哈希名称的映射存储在名为 staticfiles.json 的文件中。 当您运行 :djadmin:`collectstatic` 管理命令时，会发生一次这种情况。

storage.ManifestStaticFilesStorage.manifest_strict

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

由于需要运行 :djadmin:`collectstatic`，在运行测试时通常不应使用此存储，因为 collectstatic 不作为正常测试设置的一部分运行。 在测试期间，确保 :setting:`STATICFILES_STORAGE` 设置被设置为其他类似 'django.contrib.staticfiles.storage.StaticFilesStorage'（默认值）。

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

创建文件的散列名称时使用的方法。 需要返回给定文件名和内容的哈希值。 默认情况下，它会根据上面提到的内容块计算 MD5 哈希值。 随意覆盖此方法以使用您自己的散列算法。


CachedStaticFilesStorage

class storage.CachedStaticFilesStorage

自 2.2 版起已弃用：CachedStaticFilesStorage 已弃用，因为它有一些棘手的问题，其中一些概述如下。 改用 ManifestStaticFilesStorage 或第三方云存储。


CachedStaticFilesStorage 是一个类似于 ManifestStaticFilesStorage 类的类，但使用 Django 的 缓存框架 来存储处理文件的散列名称，而不是一个名为 [ X218X]。 这对于您无权访问文件系统的情况非常有用。

如果要覆盖存储使用的缓存后端的某些选项，请在 :setting:`CACHES` 设置中指定一个名为 'staticfiles' 的自定义条目。 它回退到使用 'default' 缓存后端。

警告

不推荐使用 CachedStaticFilesStorage – 在几乎所有情况下，ManifestStaticFilesStorage 都是更好的选择。 使用 CachedStaticFilesStorage 时有几个性能损失，因为缓存未命中需要在运行时散列文件。 远程文件存储需要多次往返以在缓存未命中时散列文件，因为需要多次文件访问以确保在嵌套文件路径的情况下文件散列是正确的。


ManifestFilesMixin

class storage.ManifestFilesMixin

将此 mixin 与自定义存储一起使用，以将文件内容的 MD5 哈希附加到文件名，如 ManifestStaticFilesStorage 所做的那样。


查找器模块

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)

此视图函数为开发中的静态文件提供服务。

警告

此视图仅在 :setting:`DEBUG` 为 True 时有效。

那是因为这种观点 效率极低' ，而且可能 不安全 。 这仅用于本地开发，不应在生产中使用 ' 。


笔记

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


该视图由 :djadmin:`runserver` 自动启用（将 :setting:`DEBUG` 设置设为 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/') 应该是你的 :setting:`STATIC_URL` 设置。

由于这有点挑剔，还有一个辅助函数可以为您执行此操作：

urls.staticfiles_urlpatterns()

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

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

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

urlpatterns += staticfiles_urlpatterns()

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

警告

这个辅助函数只有在 :setting:`DEBUG` 是 True 并且你的 :setting:`STATIC_URL` 设置既不是空的也不是完整的 URL 时才起作用，例如http://static.example.com/。

那是因为这种观点 效率极低' ，而且可能 不安全 。 这仅用于本地开发，不应在生产中使用 ' 。


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

class testing.StaticLiveServerTestCase

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

就像它的父级一样，您可以使用它来编写测试，这些测试涉及运行被测代码并通过 HTTP 使用测试工具使用它（例如 Selenium、PhantomJS 等），因此还需要发布静态资产。

但鉴于它利用了上述 django.contrib.staticfiles.views.serve() 视图，它可以在测试执行时透明地覆盖 staticfiles 提供的资产] 发现者。 这意味着您不需要在测试设置之前或作为测试设置的一部分运行 :djadmin:`collectstatic`。



取自“https://cainiaojiaocheng.com/index.php?title=Django/docs/3.0.x/ref/contrib/staticfiles&oldid=20762”
Powered by MediaWiki