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

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

STATICFILES_DIRS = [
    os.path.join(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/, вы можете сделать это, добавив следующий фрагмент в urls.py:

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.