staticfiles 应用程序 — Django 文档

staticfiles 应用程序

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

也可以看看

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

设置

有关以下设置的详细信息，请参阅 staticfiles settings：

• ：设置：`STATIC_ROOT`
• ：设置：`STATIC_URL`
• ：设置：`STATICFILES_DIRS`
• ：设置：`STATICFILES_STORAGE`
• ：设置：`STATICFILES_FINDERS`

管理命令

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，您必须确保满足以下要求：

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

由于在运行期间创建 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 哈希值。 随意覆盖此方法以使用您自己的散列算法。

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 应用程序之外还有一些其他帮助程序可以处理静态文件：

• django.template.context_processors.static() 上下文处理器，它将 :setting:`STATIC_URL` 添加到每个使用 RequestContext 上下文渲染的模板上下文。
• 内置模板标签 :ttag:`static`，它接受一个路径，并使用静态前缀 :setting:`STATIC_URL` 将其 urljoin。 如果安装了 django.contrib.staticfiles，则标签使用 :setting:`STATICFILES_STORAGE` 的 url() 方法。
• 内置模板标签 :ttag:`get_static_prefix` 使用静态前缀 :setting:`STATIC_URL` 填充模板变量以用作变量或直接使用。
• 类似的模板标签 :ttag:`get_media_prefix` 的工作方式类似于 :ttag:`get_static_prefix`，但使用 :setting:`MEDIA_URL`。

静态文件开发视图

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

views.serve(request, path)

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

警告

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

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

笔记

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

该视图由 :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`。