Как управлять статическими файлами (например, изображениями, JavaScript, CSS)

Веб-сайты обычно нуждаются в дополнительных файлах, таких как изображения, JavaScript или CSS. В Django мы называем эти файлы «статическими файлами». Django предоставляет django.contrib.staticfiles, чтобы помочь вам управлять ими.

На этой странице описано, как вы можете обслуживать эти статические файлы.

Настройка статических файлов

  1. Убедитесь, что django.contrib.staticfiles включено в ваше INSTALLED_APPS.

  2. В файле настроек определите STATIC_URL, например:

    STATIC_URL = "static/"

  3. В шаблонах используйте тег шаблона static для построения URL для заданного относительного пути с использованием настроенного псевдонима staticfiles STORAGES.

    {% load static %}
<img src="{% static 'my_app/example.jpg' %}" alt="My image">

  4. Храните ваши статические файлы в папке с именем static в вашем приложении. Например, my_app/static/my_app/example.jpg.

Обслуживание файлов

В дополнение к этим шагам по настройке, вам также нужно будет фактически обслуживать статические файлы.

Во время разработки, если вы используете django.contrib.staticfiles, это будет сделано автоматически runserver, когда DEBUG установлен в True (см. django.contrib.staticfiles.views.serve()).

Этот метод грубо неэффективен и, вероятно, небезопасен, поэтому он не подходит для производства.

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

В вашем проекте, вероятно, также будут статические активы, которые не привязаны к конкретному приложению. В дополнение к использованию директории static/ внутри ваших приложений, вы можете определить список директорий (STATICFILES_DIRS) в вашем файле настроек, где Django также будет искать статические файлы. Например:

STATICFILES_DIRS = [
    BASE_DIR / "static",
    "/var/www/static/",
]

Подробности о том, как STATICFILES_FINDERS находит ваши файлы, смотрите в документации к параметру staticfiles.

Статический интервал между именами файлов

Теперь мы может быть сможем обойтись размещением наших статических файлов непосредственно в my_app/static/ (вместо того, чтобы создавать еще один подкаталог my_app), но на самом деле это плохая идея. Django будет использовать первый найденный статический файл, имя которого совпадает, и если бы у вас был статический файл с таким же именем в различном приложении, Django не смог бы отличить их друг от друга. Нам нужно иметь возможность указать Django на нужный файл, и лучший способ обеспечить это - разделение имен между ними. То есть, поместить эти статические файлы в другой каталог, названный в честь самого приложения.

Вы можете разместить статические активы в пространстве имен STATICFILES_DIRS, указав prefixes.

Обслуживание статических файлов во время разработки

Если вы используете django.contrib.staticfiles, как объяснялось выше, runserver будет делать это автоматически, когда DEBUG установлен в True. Если у вас нет django.contrib.staticfiles в INSTALLED_APPS, вы все равно можете вручную обслуживать статические файлы, используя представление django.views.static.serve().

Это не подходит для производственного использования! О некоторых распространенных стратегиях развертывания смотрите Как развернуть статические файлы.

Например, если ваш STATIC_URL определен как static/, вы можете сделать это, добавив следующий фрагмент к вашему urls.py:

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

Примечание

Эта вспомогательная функция работает только в режиме отладки и только если заданный префикс является локальным (например, static/), а не URL (например, http://static.example.com/).

Также эта вспомогательная функция обслуживает только фактическую папку STATIC_ROOT; она не выполняет открытие статических файлов, таких как django.contrib.staticfiles.

Наконец, статические файлы обслуживаются через обертку на прикладном уровне WSGI. Как следствие, запросы на статические файлы не проходят через обычную middleware chain.

Обслуживание файлов, загруженных пользователем во время разработки

Во время разработки вы можете обслуживать загруженные пользователем медиафайлы из MEDIA_ROOT, используя представление django.views.static.serve().

Это не подходит для производственного использования! О некоторых распространенных стратегиях развертывания смотрите Как развернуть статические файлы.

Например, если ваш MEDIA_URL определен как media/, вы можете сделать это, добавив следующий фрагмент к вашему ROOT_URLCONF:

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Примечание

Эта вспомогательная функция работает только в режиме отладки и только если заданный префикс является локальным (например, media/), а не URL (например, http://media.example.com/).

Тестирование

При выполнении тестов, использующих реальные HTTP-запросы вместо встроенного клиента тестирования (т.е. при использовании встроенного LiveServerTestCase), статические активы должны обслуживаться вместе с остальным содержимым, чтобы тестовая среда как можно точнее воспроизводила реальную, но LiveServerTestCase имеет только очень базовую функциональность обслуживания статических файлов: Он не знает о функции finders приложения staticfiles и предполагает, что статическое содержимое уже собрано под STATIC_ROOT.

В связи с этим staticfiles поставляет свой собственный django.contrib.staticfiles.testing.StaticLiveServerTestCase, подкласс встроенного, который имеет возможность прозрачно обслуживать все активы во время выполнения этих тестов способом, очень похожим на тот, который мы получаем во время разработки с помощью DEBUG = True, т.е. без необходимости сначала собирать их с помощью collectstatic.

Развертывание

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

  1. Установите параметр STATIC_ROOT в каталог, из которого вы хотите обслуживать эти файлы, например:

    STATIC_ROOT = "/var/www/example.com/static/"

  2. Выполните команду управления collectstatic:

    $ python manage.py collectstatic

    Это скопирует все файлы из ваших статических папок в каталог STATIC_ROOT.

  3. Используйте выбранный вами веб-сервер для обслуживания файлов. Как развернуть статические файлы охватывает некоторые общие стратегии развертывания статических файлов.

Узнать больше

В этом документе рассмотрены основы и некоторые общие шаблоны использования. Для получения полной информации обо всех настройках, командах, тегах шаблонов и других элементах, включенных в django.contrib.staticfiles, смотрите the staticfiles reference.

Как переопределить шаблоны
Как развернуть статические файлы
Вернуться на верх