`staticfiles` 应用¶

django.contrib.staticfiles 从你的每一个应用程序（以及你指定的任何其他地方）收集静态文件到一个单一的位置，可以很容易地在生产中服务。

参见

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

配置¶

关于以下配置，请参见静态文件配置：

存储¶

`StaticFilesStorage`¶

class storage.StaticFilesStorage¶

FileSystemStorage 存储后端的一个子类，分别使用 STATIC_ROOT 配置作为基础文件系统位置和 STATIC_URL 配置作为基础 URL。

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

如果这个方法定义在一个存储上，那么在每次运行后都会被 collectstatic 管理命令调用，并得到本地存储空间和找到的文件路径作为一个字典，以及命令行选项。它产生的元组有三个值。original_path, processed_path, processed。路径值是字符串，processed 是一个布尔值，表示该值是否经过后处理，如果后处理失败则表示异常。

ManifestStaticFilesStorage 在幕后使用它将路径替换为它们的哈希对应物，并适当地更新缓存。

`ManifestStaticFilesStorage`¶

class storage.ManifestStaticFilesStorage¶

StaticFilesStorage 存储后台的一个子类，它通过在文件名上附加文件内容的 MD5 哈希值来存储它处理的文件名。例如，文件 css/styles.css 也会被保存为 css/styles.55e7cbb9ba48.css。

这个存储的目的是为了继续服务于旧文件，以防某些页面仍然引用这些文件，例如，因为它们被你或第三方代理服务器缓存了。此外，如果你想在部署的文件上应用远期失效头信息，以加快后续页面访问的加载时间，它是非常有用的。

存储后端会自动将保存的文件中发现的与其他保存的文件相匹配的路径替换为缓存副本的路径（使用 post_process() 方法）。用于查找这些路径的正则表达式（ django.contrib.staticfiles.storage.HashedFilesMixin.pattern ）涵盖。

层叠样式表的 @import 规则和 url() 语句。
Source map comments in CSS and JavaScript files.

Subclass ManifestStaticFilesStorage and set the support_js_module_import_aggregation attribute to True, if you want to use the experimental regular expressions to cover:

The modules import in JavaScript.
The modules aggregation in JavaScript.

例如，'css/styles.css' 文件有这样的内容：

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

...将通过调用 ManifestStaticFilesStorage 存储后端的 url() 方法来替代，最终保存一个 css/styles.55e7cbb9ba48.css 文件，内容如下：

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

Usage of the integrity HTML attribute with local files

When using the optional integrity attribute within tags like <script> or <link>, its value should be calculated based on the files as they are served, not as stored in the filesystem. This is particularly important because depending on how static files are collected, their checksum may have changed (for example when using collectstatic). At the moment, there is no out-of-the-box tooling available for this.

您可以通过使用自定义的 ManifestStaticFilesStorage 子类，设置 manifest_storage 参数来改变清单文件的位置。例如：

from django.conf import settings
from django.contrib.staticfiles.storage import (
    ManifestStaticFilesStorage,
    StaticFilesStorage,
)


class MyManifestStaticFilesStorage(ManifestStaticFilesStorage):
    def __init__(self, *args, **kwargs):
        manifest_storage = StaticFilesStorage(location=settings.BASE_DIR)
        super().__init__(*args, manifest_storage=manifest_storage, **kwargs)

References in comments

ManifestStaticFilesStorage doesn't ignore paths in statements that are commented out. This may crash on the nonexistent paths. You should check and eventually strip comments.

Changed in Django 4.2:

Experimental optional support for finding paths to JavaScript modules in import and export statements was added.

storage.ManifestStaticFilesStorage.manifest_hash¶

New in Django 4.2.

This attribute provides a single hash that changes whenever a file in the manifest changes. This can be useful to communicate to SPAs that the assets on the server have changed (due to a new deployment).

storage.ManifestStaticFilesStorage.max_post_process_passes¶

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

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

the staticfiles storage backend in STORAGES setting is set to 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
DEBUG 设置为 False
通过使用 collectstatic 管理命令，你已经收集了所有静态文件

由于在运行时创建 MD5 哈希可能会给网站带来性能负担，staticfiles 会自动将所有处理过的文件的哈希名映射存储在一个名为 staticfiles.json 的文件中。当你运行 collectstatic 管理命令时就会发生一次。

storage.ManifestStaticFilesStorage.manifest_strict¶

如果在运行时在 staticfiles.json 清单中没有找到文件，就会引发 ValueError。这种行为可以通过子类 ManifestStaticFilesStorage 并将 manifest_strict 属性设置为 False 来禁止，不存在的路径将保持不变。

Due to the requirement of running collectstatic, this storage typically shouldn't be used when running tests as collectstatic isn't run as part of the normal test setup. During testing, ensure that staticfiles storage backend in the STORAGES setting is set to something else like 'django.contrib.staticfiles.storage.StaticFilesStorage' (the default).

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

创建文件的哈希名时使用的方法。需要返回给定文件名和内容的哈希值。默认情况下，它从上面提到的内容块中计算出一个 MD5 哈希。可以随意覆盖这个方法，使用自己的哈希算法。

`ManifestFilesMixin`¶

class storage.ManifestFilesMixin¶

使用这个混入和一个自定义的存储来附加文件内容的 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() 上下文处理器，它为每个用 RequestContext 上下文渲染的模板上下文添加 STATIC_URL。
The builtin template tag static which takes a path and urljoins it with the static prefix STATIC_URL. If django.contrib.staticfiles is installed, the tag uses the url() method of the staticfiles storage backend from STORAGES instead.
内置的模板标签 get_static_prefix，将静态前缀 STATIC_URL 填充到模板变量中，作为变量或直接使用。
类似的模板标签 get_media_prefix，其工作原理与 get_static_prefix 类似，但使用 MEDIA_URL。
The staticfiles key in django.core.files.storage.storages contains a ready-to-use instance of the staticfiles storage backend.

静态文件开发视图¶

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

views.serve(request, path)¶

该视图功能服务于开发中的静态文件。

警告

只有当 DEBUG 为 True 时，该视图才会生效。

这是因为这个视图的 效率很低，而且可能 不安全。这只用于本地开发，不应该用于生产。

备注

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

该视图由 runserver 自动启用（将 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/'）应该是你的 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¶

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

就像它的父类一样，你可以用它来编写测试，涉及到运行被测代码，并通过 HTTP 与测试工具（如 Selenium、PhantomJS 等）进行消费，因为这需要静态资产也被发布。

但是由于它使用了上面描述的 django.contrib.staticfiles.views.service() 视图，它可以在测试执行时透明地叠加 staticfiles 查找器提供的资产。这意味着你不需要在测试配置之前或作为测试配置的一部分运行 collectstatic。

Django 5.0.1.dev20231205051144 文档

`staticfiles` 应用¶

配置¶

管理命令¶

`collectstatic`¶

自定义忽略的模式列表¶

`findstatic`¶

`runserver`¶

存储¶

`StaticFilesStorage`¶

`ManifestStaticFilesStorage`¶

`ManifestFilesMixin`¶

查找器模块¶

其他辅助功能¶

静态文件开发视图¶

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

目录

上一个主题

下一个主题

本页

Last update:

Django 5.0.1.dev20231205051144 文档

staticfiles 应用¶

配置¶

管理命令¶

collectstatic¶

自定义忽略的模式列表¶

findstatic¶

runserver¶

存储¶

StaticFilesStorage¶

ManifestStaticFilesStorage¶

ManifestFilesMixin¶

查找器模块¶

其他辅助功能¶

静态文件开发视图¶

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

Last update:

`staticfiles` 应用¶

`collectstatic`¶

`findstatic`¶

`runserver`¶

`StaticFilesStorage`¶

`ManifestStaticFilesStorage`¶

`ManifestFilesMixin`¶