Работа со статическими файлами

Добавлено в Django 1.3: Пожалуйста, обратитесь к описанию релиза

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

Для маленьких проектов это не проблема, потому что вы можете расположить их где угодно на сервере. Однако в больших проектах – особенно состоящих из большого количества проектов – работа с большим количеством файлов в различных приложениях становится не легким делом.

Для этого и создано приложение django.contrib.staticfiles: оно собирает статические файлы из всех ваших приложений (и остальных мест которые вы укажите) в одном месте, что позволяет легко настроить выдачу статических файлов на боевом сервере.

Примечание

Если вы использовали ранее стороннее приложение django-staticfiles, django.contrib.staticfiles покажется вам очень знакомым. Это потому, что у них одинаковый код, django.contrib.staticfiles изначально было приложением django-staticfiles, которое добавили в Django 1.3.

Если вам необходимо обновиться с django-staticfiles, смотрите раздел Обновление с django-staticfiles ниже.

Использование django.contrib.staticfiles

Использование

  1. Расположите статические файлы там, где staticfiles сможет их найти.

    По умолчанию это каталог ``static``в приложениях, которые добавлены в INSTALLED_APPS.

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

    Так же смотрите описание настройки STATICFILES_FINDERS что бы узнать как staticfiles ищет файлы.

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

    Для разработки, если вы используете runserver или добавили staticfiles_urlpatterns) из STATIC_URL /static/.

  3. Вам также понадобиться указать путь к файлам в шаблонах. Самый простой способ добавить процессор контекста который позволит использовать следующий код:

    <img src="{{ STATIC_URL }}images/hi.jpg" />

    Подробности смотрите в разделе Referring to static files in templates.

Deploying static files in a nutshell

When you’re ready to move out of local development and deploy your project:

  1. Set the STATIC_URL setting to the public URL for your static files (in most cases, the default value of /static/ is just fine).

  2. Set the STATIC_ROOT setting to point to the filesystem path you’d like your static files collected to when you use the collectstatic management command. For example:

    STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"

  3. Run the collectstatic management command:

    ./manage.py collectstatic

    This’ll churn through your static file storage and copy them into the directory given by STATIC_ROOT.

  4. Deploy those files by configuring your webserver of choice to serve the files in STATIC_ROOT at STATIC_URL.

    Serving static files in production covers some common deployment strategies for static files.

Those are the basics. For more details on common configuration options, read on; for a detailed reference of the settings, commands, and other bits included with the framework see the staticfiles reference.

Примечание

In previous versions of Django, it was common to place static assets in MEDIA_ROOT along with user-uploaded files, and serve them both at MEDIA_URL. Part of the purpose of introducing the staticfiles app is to make it easier to keep static files separate from user-uploaded files.

For this reason, you need to make your MEDIA_ROOT and MEDIA_URL different from your STATIC_ROOT and STATIC_URL. You will need to arrange for serving of files in MEDIA_ROOT yourself; staticfiles does not deal with user-uploaded files at all. You can, however, use django.views.static.serve() view for serving MEDIA_ROOT in development; see Serving other directories.

Referring to static files in templates

At some point, you’ll probably need to link to static files in your templates. You could, of course, simply hardcode the path to you assets in the templates:

<img src="http://static.example.com/static/myimage.jpg" />

Of course, there are some serious problems with this: it doesn’t work well in development, and it makes it very hard to change where you’ve deployed your static files. If, for example, you wanted to switch to using a content delivery network (CDN), then you’d need to change more or less every single template.

A far better way is to use the value of the STATIC_URL setting directly in your templates. This means that a switch of static files servers only requires changing that single value. Much better!

Django includes multiple built-in ways of using this setting in your templates: a context processor and a template tag.

With a context processor

The included context processor is the easy way. Simply make sure 'django.core.context_processors.static' is in your TEMPLATE_CONTEXT_PROCESSORS. It’s there by default, and if you’re editing that setting by hand it should look something like:

TEMPLATE_CONTEXT_PROCESSORS = (
    'django.core.context_processors.debug',
    'django.core.context_processors.i18n',
    'django.core.context_processors.media',
    'django.core.context_processors.static',
    'django.contrib.auth.context_processors.auth',
    'django.contrib.messages.context_processors.messages',
)

Once that’s done, you can refer to STATIC_URL in your templates:

<img src="{{ STATIC_URL }}images/hi.jpg" />

If {{ STATIC_URL }} isn’t working in your template, you’re probably not using RequestContext when rendering the template.

As a brief refresher, context processors add variables into the contexts of every template. However, context processors require that you use RequestContext when rendering templates. This happens automatically if you’re using a generic view, but in views written by hand you’ll need to explicitly use RequestContext To see how that works, and to read more details, check out Subclassing Context: RequestContext.

Another option is the get_static_prefix template tag that is part of Django’s core.

With a template tag

The more powerful tool is the static template tag. It builds the URL for the given relative path by using the configured STATICFILES_STORAGE storage.

{% load staticfiles %}
<img src="{% static "images/hi.jpg" %}" />

It is also able to consume standard context variables, e.g. assuming a user_stylesheet variable is passed to the template:

{% load staticfiles %}
<link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" />

Примечание

There is also a template tag named static in Django’s core set of built in template tags which has the same argument signature but only uses urlparse.urljoin() with the STATIC_URL setting and the given path. This has the disadvantage of not being able to easily switch the storage backend without changing the templates, so in doubt use the staticfiles static template tag.

Serving static files in development

The static files tools are mostly designed to help with getting static files successfully deployed into production. This usually means a separate, dedicated static file server, which is a lot of overhead to mess with when developing locally. Thus, the staticfiles app ships with a quick and dirty helper view that you can use to serve files locally in development.

This view is automatically enabled and will serve your static files at STATIC_URL when you use the built-in runserver management command.

To enable this view if you are using some other server for local development, you’ll add a couple of lines to your URLconf. The first line goes at the top of the file, and the last line at the bottom:

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

# ... the rest of your URLconf goes here ...

urlpatterns += staticfiles_urlpatterns()

This will inspect your STATIC_URL setting and wire up the view to serve static files accordingly. Don’t forget to set the STATICFILES_DIRS setting appropriately to let django.contrib.staticfiles know where to look for files additionally to files in app directories.

Предупреждение

This will only work if DEBUG is True.

That’s because this view is grossly inefficient and probably insecure. This is only intended for local development, and should never be used in production.

Additionally, when using staticfiles_urlpatterns your STATIC_URL setting can’t be empty or a full URL, such as http://static.example.com/.

For a few more details on how the staticfiles can be used during development, see Static file development view.

Serving other directories

serve(request, path, document_root, show_indexes=False)

There may be files other than your project’s static assets that, for convenience, you’d like to have Django serve for you in local development. The serve() view can be used to serve any directory you give it. (Again, this view is not hardened for production use, and should be used only as a development aid; you should serve these files in production using a real front-end webserver).

The most likely example is user-uploaded content in MEDIA_ROOT. staticfiles is intended for static assets and has no built-in handling for user-uploaded files, but you can have Django serve your MEDIA_ROOT by appending something like this to your URLconf:

from django.conf import settings

# ... the rest of your URLconf goes here ...

if settings.DEBUG:
    urlpatterns += patterns('',
        url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {
            'document_root': settings.MEDIA_ROOT,
        }),
   )

Note, the snippet assumes your MEDIA_URL has a value of '/media/'. This will call the serve() view, passing in the path from the URLconf and the (required) document_root parameter.

static(prefix, view='django.views.static.serve', **kwargs)

Since it can become a bit cumbersome to define this URL pattern, Django ships with a small URL helper function static() that takes as parameters the prefix such as MEDIA_URL and a dotted path to a view, such as 'django.views.static.serve'. Any other function parameter will be transparently passed to the view.

An example for serving MEDIA_URL ('/media/') during development:

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = patterns('',
    # ... the rest of your URLconf goes here ...
) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Примечание

This helper function will only be operational in debug mode and if the given prefix is local (e.g. /static/) and not a URL (e.g. http://static.example.com/).

Serving static files in production

The basic outline of putting static files into production is simple: run the collectstatic command when static files change, then arrange for the collected static files directory (STATIC_ROOT) to be moved to the static file server and served.

Of course, as with all deployment tasks, the devil’s in the details. Every production setup will be a bit different, so you’ll need to adapt the basic outline to fit your needs. Below are a few common patterns that might help.

Serving the app and your static files from the same server

If you want to serve your static files from the same server that’s already serving your site, the basic outline gets modified to look something like:

You’ll probably want to automate this process, especially if you’ve got multiple web servers. There’s any number of ways to do this automation, but one option that many Django developers enjoy is Fabric.

Below, and in the following sections, we’ll show off a few example fabfiles (i.e. Fabric scripts) that automate these file deployment options. The syntax of a fabfile is fairly straightforward but won’t be covered here; consult Fabric’s documentation, for a complete explanation of the syntax..

So, a fabfile to deploy static files to a couple of web servers might look something like:

from fabric.api import *

# Hosts to deploy onto
env.hosts = ['www1.example.com', 'www2.example.com']

# Where your project code lives on the server
env.project_root = '/home/www/myproject'

def deploy_static():
    with cd(env.project_root):
        run('./manage.py collectstatic -v0 --noinput')

Serving static files from a dedicated server

Most larger Django apps use a separate Web server – i.e., one that’s not also running Django – for serving static files. This server often runs a different type of web server – faster but less full-featured. Some good choices are:

Configuring these servers is out of scope of this document; check each server’s respective documentation for instructions.

Since your static file server won’t be running Django, you’ll need to modify the deployment strategy to look something like:

  • When your static files change, run collectstatic locally.
  • Push your local STATIC_ROOT up to the static file server into the directory that’s being served. rsync is a good choice for this step since it only needs to transfer the bits of static files that have changed.

Here’s how this might look in a fabfile:

from fabric.api import *
from fabric.contrib import project

# Where the static files get collected locally
env.local_static_root = '/tmp/static'

# Where the static files should go remotely
env.remote_static_root = '/home/www/static.example.com'

@roles('static')
def deploy_static():
    local('./manage.py collectstatic')
    project.rysnc_project(
        remote_dir = env.remote_static_root,
        local_dir = env.local_static_root,
        delete = True
    )

Serving static files from a cloud service or CDN

Another common tactic is to serve static files from a cloud storage provider like Amazon’s S3 and/or a CDN (content delivery network). This lets you ignore the problems of serving static files, and can often make for faster-loading webpages (especially when using a CDN).

When using these services, the basic workflow would look a bit like the above, except that instead of using rsync to transfer your static files to the server you’d need to transfer the static files to the storage provider or CDN.

There’s any number of ways you might do this, but if the provider has an API a custom file storage backend will make the process incredibly simple. If you’ve written or are using a 3rd party custom storage backend, you can tell collectstatic to use it by setting STATICFILES_STORAGE to the storage engine.

For example, if you’ve written an S3 storage backend in myproject.storage.S3Storage you could use it with:

STATICFILES_STORAGE = 'myproject.storage.S3Storage'

Once that’s done, all you have to do is run collectstatic and your static files would be pushed through your storage package up to S3. If you later needed to switch to a different storage provider, it could be as simple as changing your STATICFILES_STORAGE setting.

For details on how you’d write one of these backends, Writing a custom storage system.

См.также

The django-storages project is a 3rd party app that provides many storage backends for many common file storage APIs (including S3).

Обновление с django-staticfiles

django.contrib.staticfiles began its life as django-staticfiles. If you’re upgrading from django-staticfiles older than 1.0 (e.g. 0.3.4) to django.contrib.staticfiles, you’ll need to make a few changes:

  • Application files should now live in a static directory in each app (django-staticfiles used the name media, which was slightly confusing).
  • The management commands build_static and resolve_static are now called collectstatic and findstatic.
  • The settings STATICFILES_PREPEND_LABEL_APPS, STATICFILES_MEDIA_DIRNAMES and STATICFILES_EXCLUDED_APPS were removed.
  • The setting STATICFILES_RESOLVERS was removed, and replaced by the new STATICFILES_FINDERS.
  • The default for STATICFILES_STORAGE was renamed from staticfiles.storage.StaticFileStorage to staticfiles.storage.StaticFilesStorage
  • If using runserver for local development (and the DEBUG setting is True), you no longer need to add anything to your URLconf for serving static files in development.

Learn more

This document has covered the basics and some common usage patterns. For complete details on all the settings, commands, template tags, and other pieces include in django.contrib.staticfiles, see the staticfiles reference.

« previous | up | next »