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

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

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.

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

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

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

Предоставление статических файлов во время разработки

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

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

Например, если 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)

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

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

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

Например, если 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)

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

При запуске тестов, использующих реальные HTTP-запросы вместо встроенного клиента для тестирования (то есть при использовании встроенного LiveServerTestCase), статические ресурсы необходимо предоставлять вместе с остальным содержимым, чтобы тестовая среда как можно точнее воспроизводила реальную. Однако LiveServerTestCase предоставляет лишь базовые возможности для раздачи статических файлов: оно не поддерживает механизм поисковых средств приложения 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, см. в справочнике по staticfiles.