Как управлять статическими файлами (например, изображениями, 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.

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

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

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

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

Если вы используете 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)

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

Во время разработки вы можете предоставить загруженные пользователем файлы медиа из 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)

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

При выполнении тестов, использующих реальные 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.