How to manage static files (e.g. images, 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_STORAGE.

    {% 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()).

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

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

В вашем проекте, вероятно, также будут статические активы, которые не привязаны к конкретному приложению. В дополнение к использованию директории 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().

Это не подходит для производственного использования! О некоторых распространенных стратегиях развертывания смотрите How to deploy static files.

For example, if your STATIC_URL is defined as static/, you can do this by adding the following snippet to your 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)

Примечание

This helper function works only in debug mode and only if the given prefix is local (e.g. static/) and not a URL (e.g. http://static.example.com/).

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

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

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

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

Это не подходит для производственного использования! О некоторых распространенных стратегиях развертывания смотрите How to deploy static files.

For example, if your MEDIA_URL is defined as media/, you can do this by adding the following snippet to your 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)

Примечание

This helper function works only in debug mode and only if the given prefix is local (e.g. media/) and not a URL (e.g. 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. Используйте выбранный вами веб-сервер для обслуживания файлов. How to deploy static files охватывает некоторые общие стратегии развертывания статических файлов.

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

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

How to override templates
How to deploy static files
Вернуться на верх