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

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

Этот раздел описывает как работать с ними.

Настройка статики

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

  2. В настройках укажите STATIC_URL, например:

    STATIC_URL = '/static/'
    
  3. In your templates, use the static template tag to build the URL for the given relative path using the configured 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()).

Потому что это представление очень неэффективно и, возможно, небезопасно. Оно предназначено только для разработки, и не должно использоваться на боевом сервере.

Способы раздачи статических файлов описаны в разделе Развертывание статических файлов.

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

STATICFILES_DIRS = [
    os.path.join(BASE_DIR, "static"),
    '/var/www/static/',
]

Смотрите описание настройки STATICFILES_FINDERS чтобы узнать, как staticfiles находит файлы.

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

Now we might be able to get away with putting our static files directly in my_app/static/ (rather than creating another my_app subdirectory), but it would actually be a bad idea. Django will use the first static file it finds whose name matches, and if you had a static file with the same name in a different application, Django would be unable to distinguish between them. We need to be able to point Django at the right one, and the best way to ensure this is by namespacing them. That is, by putting those static files inside another directory named for the application itself.

You can namespace static assets in STATICFILES_DIRS by specifying prefixes.

Раздача статических файлов при разработке

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

Примечание

Это представление работает только при включенной отладке и для локальных префиксов (например /static/), а не полных URL-ов (e.g. http://static.example.com/).

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

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

При разработке медиа файлы из 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)

Примечание

Это представление работает только при включенной отладке и для локальных префиксов (например /media/), а не полных URL-ов (e.g. http://media.example.com/).

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

При выполнении тестов, которые отправляют действительные 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, смотрите раздел о статических файлах.