The staticfiles app

django.contrib.staticfiles собирает статические файлы со всех ваших приложений (и остальных мест, которые вы укажите) в одном месте, что позволяет легко настроить выдачу статических файлов на боевом сервере.

См.также

Примеры использования этого приложения для работы со статикой можно найти в разделе Работа со статическими файлами (например изображения, JavaScript, CSS). Как работать со статикой на боевом сервере описано в разделе Развертывание статических файлов.

Команды

django.contrib.staticfiles предоставляет три команды.

collectstatic

django-admin collectstatic

Собирает статические файлы в STATIC_ROOT.

Одинаковые имена файлов обрабатываются как и шаблоны: будет использоваться первый найденный файл. Если вы запутались, команда findstatic может показать какой конкретно файл используется.

On subsequent collectstatic runs (if STATIC_ROOT isn’t empty), files are copied only if they have a modified timestamp greater than the timestamp of the file in STATIC_ROOT. Therefore if you remove an application from INSTALLED_APPS, it’s a good idea to use the collectstatic --clear option in order to remove stale static files.

Файлы ищутся используя бэкенды из enabled finders. По умолчанию проверяются каталоги из STATICFILES_DIRS и подкаталоги 'static' приложений из INSTALLED_APPS.

The collectstatic management command calls the post_process() method of the STATICFILES_STORAGE after each run and passes a list of paths that have been found by the management command. It also receives all command line options of collectstatic. This is used by the ManifestStaticFilesStorage by default.

По умолчанию, созданные файлы получают права доступа из FILE_UPLOAD_PERMISSIONS, а каталоги из 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)

Теперь поменяйте настройку STATICFILES_STORAGE на 'path.to.MyStaticFilesStorage'.

Обычно используются следующие параметры:

--noinput, --no-input

Do NOT prompt the user for input of any kind.

--ignore PATTERN, -i PATTERN

Ignore files, directories, or paths matching this glob-style pattern. Use multiple times to ignore more. When specifying a path, always use forward slashes, even on Windows.

Changed in Django 2.2:

Path matching was added.

--dry-run, -n

Выполнить все операции, кроме тех, которые изменяют файловую систему.

--clear, -c

Удалить существующие файлы перед копированием новых.

Создать симлинк для каждого файла вместо копирования.

--no-post-process

Не вызывать метод post_process() указанного в STATICFILES_STORAGE бэкенда для работы с файлами.

--no-default-ignore

Не игнорировать файлы 'CVS', '.*' and ``*~“``(по умолчанию игнорируются).

For a full list of options, refer to the commands own help by running:

$ python manage.py collectstatic --help
...\> py manage.py collectstatic --help

Customizing the ignored pattern list

The default ignored pattern list, ['CVS', '.*', '*~'], can be customized in a more persistent way than providing the --ignore command option at each collectstatic invocation. 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 ...]

Ищет файлы по указанному относительному пути(или путях) используя активные бэкенды для поиска файлов.

For example:

$ 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
...\> py 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

By default, all matching locations are found. To only return the first match for each relative path, use the --first option:

$ python manage.py findstatic css/base.css --first
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
...\> py manage.py findstatic css\base.css --first
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css

Предназначена для отладки, чтобы понять какие файлы будут использоваться при сборе статики.

By setting the --verbosity flag to 0, you can suppress the extra output and just get the path names:

$ 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
...\> py 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

On the other hand, by setting the --verbosity flag to 2, you can get all the directories which were searched:

$ 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
...\> py 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. File serving doesn’t run through MIDDLEWARE.

The command adds these options:

--nostatic

Используйте --nostatic чтобы отключить раздачу статических файлов через staticfiles. Опция доступна только если приложение staticfiles добавлено в INSTALLED_APPS.

Example usage:

$ django-admin runserver --nostatic
...\> django-admin runserver --nostatic
--insecure

Use the --insecure option to force serving of static files with the staticfiles app even if the DEBUG setting is False. By using this you acknowledge the fact that it’s grossly inefficient and probably insecure. This is only intended for local development, should never be used in production and is only available if the staticfiles app is in your project’s INSTALLED_APPS setting.

--insecure doesn’t work with ManifestStaticFilesStorage.

Example usage:

$ django-admin runserver --insecure
...\> django-admin runserver --insecure

Бэкенды

StaticFilesStorage

class storage.StaticFilesStorage

Наследуется от FileSystemStorage, используйте STATIC_ROOT как расположение файлов и STATIC_URL как основной URL.

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

If this method is defined on a storage, it’s called by the collectstatic management command after each run and gets passed the local storages and paths of found files as a dictionary, as well as the command line options. It yields tuples of three values: original_path, processed_path, processed. The path values are strings and processed is a boolean indicating whether or not the value was post-processed, or an exception if post-processing failed.

The ManifestStaticFilesStorage uses this behind the scenes to replace the paths with their hashed counterparts and update the cache appropriately.

ManifestStaticFilesStorage

class storage.ManifestStaticFilesStorage

Подкласс StaticFilesStorage, который кеширует файлы добавляя MD5 хеш содержимого файла к его названию. Например, файл css/styles.css будет сохранен как css/styles.55e7cbb9ba48.css.

Этот бэкенд необходим, чтобы раздавать старые версии файлов, если они все еще используются некоторыми страницами, например, если страницы кэшированы вами или прокси-сервером. Также, это полезно при большом значении заголовка Expires для статических файлов, чтобы ускорить загрузку страниц.

Бэкенд автоматом заменяет пути, найденные в статических файлах, которые указывают на другие статические файлы, на кешированные версии (используя метод post_process()). Регулярки, которые используются для этого (django.contrib.staticfiles.storage.HashedFilesMixin.patterns), по умолчанию заменяют @import и url() в Cascading Style Sheets. Например, 'css/styles.css', содержащий

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

был бы заменен вызовом метода url() бэкенда ManifestStaticFilesStorage, и сохранен как 'css/styles.55e7cbb9ba48.css', содержащий:

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

Since static files might reference other static files that need to have their paths replaced, multiple passes of replacing paths may be needed until the file hashes converge. To prevent an infinite loop due to hashes not converging (for example, if 'foo.css' references 'bar.css' which references 'foo.css') there is a maximum number of passes before post-processing is abandoned. In cases with a large number of references, a higher number of passes might be needed. Increase the maximum number of passes by subclassing ManifestStaticFilesStorage and setting the max_post_process_passes attribute. It defaults to 5.

Чтобы включить ManifestStaticFilesStorage, необходимо выполнить следующие действия:

  • указать в STATICFILES_STORAGE 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
  • установить DEBUG в False
  • вы собрали статические файлы командой collectstatic

Т.к. вычисление MD5 хеша может понизить производительность приложения, staticfiles автоматически сохраняет соответствия названий файлов с новыми в файле staticfiles.json. Это выполняется один раз при вызове команды collectstatic.

storage.ManifestStaticFilesStorage.manifest_strict

If a file isn’t found in the staticfiles.json manifest at runtime, a ValueError is raised. This behavior can be disabled by subclassing ManifestStaticFilesStorage and setting the manifest_strict attribute to False – nonexistent paths will remain unchanged.

Т.к. этот бэкенд требует выполнения collectstatic, его не следует использовать при тестах т.к. collectstatic не выполняется при запуске тестов. При тестировании укажите в настройках STATICFILES_STORAGE например 'django.contrib.staticfiles.storage.StaticFilesStorage' (используется по умолчанию).

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

Метод, который вычисляет хеш для файла. Должен вернуть хеш названия и содержимого файла. По умолчанию вычисляет MD5 хеш содержимого файла, как описано выше. Вы можете переопределить этот метод и использовать собственный алгоритм хеширования.

CachedStaticFilesStorage

class storage.CachedStaticFilesStorage

Не рекомендуется, начиная с версии 2.2: CachedStaticFilesStorage is deprecated as it has some intractable problems, some of which are outlined below. Use ManifestStaticFilesStorage or a third-party cloud storage instead.

CachedStaticFilesStorage аналогичен ManifestStaticFilesStorage, но использует кеш Django, для сохранения названий файлов, вместо staticfiles.json. Это может быть полезно, если у вас нет доступа к файловой системе.

If you want to override certain options of the cache backend the storage uses, specify a custom entry in the CACHES setting named 'staticfiles'. It falls back to using the 'default' cache backend.

Предупреждение

CachedStaticFilesStorage isn’t recommended – in almost all cases ManifestStaticFilesStorage is a better choice. There are several performance penalties when using CachedStaticFilesStorage since a cache miss requires hashing files at runtime. Remote file storage require several round-trips to hash a file on a cache miss, as several file accesses are required to ensure that the file hash is correct in the case of nested file paths.

ManifestFilesMixin

class storage.ManifestFilesMixin

Use this mixin with a custom storage to append the MD5 hash of the file’s content to the filename as ManifestStaticFilesStorage does.

Модуль поиска файлов

Модуль поиска файлов staticfiles содержит атрибут searched_locations, который содержит список каталогов, где происходит поиск файлов. Например:

from django.contrib.staticfiles import finders

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

Дополнительные функции

Есть дополнительные функции вне staticfiles для работы со статическими файлами:

  • Контекстный процессор django.core.context_processors.static(), который добавляет STATIC_URL в контекст каждого шаблона отрендеренного с использованием RequestContext.
  • 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 instead.
  • Шаблонный тег get_static_prefix, который создает в шаблоне переменную или просто выводит значение STATIC_URL.
  • Шаблонный тег get_media_prefix, который работает как и get_static_prefix, но для MEDIA_URL.

Представления для разработки

Инструменты для работой со статикой предназначены для простого развертывания на боевом сервере. Обычно это выделенный сервер, которые не практично использовать при разработке. Поэтому приложение staticfiles содержит простые представления для раздачи статики dev-сервером.

views.serve(request, path)

Представление, которое раздает статические файлы при разработке.

Предупреждение

Работает только при DEBUG равном True.

Потому что представление крайне неэффективно и возможно небезопасно. Оно предназначено для разработки и никогда не должно использоваться на боевом сервере.

Примечание

Для определения «content type» файлов, представление использует стандартный модуль Python mimetypes, который в свою очередь использует системную библиотеку типов файлов. Если представление использует не правильный «content type» файлов, скорее всего вам необходимо обновить системную библиотеку. Для Red Hat, например, это пакет mailcap, или mime-support для Debian пакетов.

Это представление автоматически используется командой runserver (при DEBUG равном True). Чтобы использовать его с другим dev-сервером, добавьте следующий код в настройки 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),
    ]

Обратите внимание, что начало URL-шаблона (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/.

Потому что представление крайне неэффективно и возможно небезопасно. Оно предназначено для разработки и никогда не должно использоваться на боевом сервере.

Специальный test case для «живого тестирования»

class testing.StaticLiveServerTestCase

Этот unittest TestCase является дочерним классом django.test.LiveServerTestCase.

Как и родительский класс, позволяет писать тесты с использованием Selenium, PhantomJS, и др., для которых необходим доступ к статическим файлам.

Для раздачи статики использует django.contrib.staticfiles.views.serve(). Поэтому вам не нужно выполнять collectstatic перед запуском тестов.