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

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

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

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

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

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

   STATIC_URL = '/static/'
   

3. В ваших шаблонах либо жестко закодируйте URL, как /static/my_app/myexample.jpg, или, предпочтительно, используйте тег шаблона static, чтобы сгенерировать URL для данного относительного пути, используя настроенное хранилище STATICFILES_STORAGE (это значительно упрощает переход на сеть доставки контента (CDN) для предоставления статических файлов).

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

4. Храните ваши статические файлы в папке с именем static в вашем приложении. Например, my_app/static/my_app/myimage.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.contrib.staticfiles.views.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.contrib.staticfiles.views.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, см. справочник по статическим файлам.