Gerenciamento de arquivos estáticos (ex.: imagens, JavaScript, CSS)

Sites geralmente precisam servir arquivos adicionais como imagens, JavaScript, ou CSS. No Django, nós nos referimos a estes arquivos como “arquivos estáticos”. O Django fornece django.contrib.staticfiles para ajudar você a gerenciar eles.

Está página descreve como você pode servir estes arquivos estáticos.

Configurando arquivos estáticos

1. Certifique-se de que django.contrib.staticfiles está incluído no seu INSTALLED_APPS.

2. Em seu arquivo de configurações, defina STATIC_URL, por exemplo:

   STATIC_URL = '/static/'
   

3. Nos seus templates, use a template tag static para construir a URL para o caminho relativo fornecido usando o valor configurado em STATICFILES_STORAGE.

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

4. Armazene seus arquivos estáticos no diretório chamado static dentro da sua app. Por exemplo my_app/static/my_app/example.jpg.

Servindo os arquivos

Além desses passos de configuração, você também vai precisar servir os arquivos estáticos.

Durante o desenvolvimento, se você usar django.contrib.staticfiles, isso será feito automaticamente pelo runserver quando DEBUG está definido como True (veja django.contrib.staticfiles.views.serve()).

Este método é grosseiramente ineficiente e provavelmente inseguro, então isso é impróprio para produção.

Veja Deploy de arquivos estáticos para estratégias apropriadas para servir arquivos estáticos em ambientes de produção.

Seu projeto irá provavelmente ter ativos estáticos que não estão amarrados a uma app em particular. Além de usar um diretório static/ dentro de sua app, você pode definir uma lista de diretórios (STATICFILES_DIRS) no seu arquivo de configurações onde o Django também irá procurar por arquivos estáticos. Por exemplo:

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

Veja a documentação para a definição do STATICFILES_FINDERS para detalhes sobre como o staticfiles encontra seus arquivos.

Namespacing de arquivos estáticos

Agora nós podemos nos safar somemente colocando nossos arquivos diretamente em my_app/static/ (ao invés de criar outro subdiretório my_app), mas isso seria na verdade uma má idéia. O Django irá usar o primeiro arquivo estático que encontrar com o mesmo nome, e se você tiver um arquivo estático com o mesmo nome em uma aplicação diferente, o Django será incapaz de distinguir entre eles. Precisamos ser capazes de apontar ao Django o arquivo correto, e a maneira mais fácil de garantir isso é fazendo o namespacing deles. Isso é, colocando aqueles arquivos estáticos dentro de um outro diretório nomeado para aquela aplicação específica.

Servindo arquivos estáticos durante o desenvolvimento

Se você usa o django.contrib.staticfiles como explicado acima, runserver vai fazer isso automaticamente quando :settings:`DEBUG` estiver configurado como True. Se você não tem django.contrib.staticfiles em INSTALLED_APPS, você ainda pode manualmente servir arquivos estáticos usando a view django.views.static.serve().

Isso não é apropriado para uso em produção! Para algumas estratégias de deploy, veja Deploy de arquivos estáticos.

Por exemplo, se seu STATIC_URL está definido como /static/, você pode fazê-lo adicionando o seguinte pedaço de código no seu 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)

Nota

Esta função auxiliar funciona somente em modo de depuração e somente se o dado prefixo for local (ex.: /static/) e não uma URL (ex.: http://static.example.com/).

Esta função de auxiliar serve somente o diretório atual STATIC_ROOT; ela não faz a busca de arquivos estáticos como django.contrib.staticfiles.

Servindo arquivos que foram enviados pelo usuário durante o desenvolvimento

Durante o desenvolvimento, você pode entregar arquivos de mídia enviados pelos usuários através do MEDIA_ROOT usando a view django.views.static.serve().

Isso não é apropriado para uso em produção! Para algumas estratégias de deploy, veja Deploy de arquivos estáticos.

Por exemplo, se o seu MEDIA_URL está definido como /media/, você pode fazê-lo adicionando o seguinte pedaço de código no seu 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)

Nota

Essa função auxiliar funciona somente em modo de depuração e somente se o dado prefixo for local (ex.: /media/) e não uma URL (e.g. http://media.example.com/).

Testando

Ao executar testes que usam requisições HTTP reais ao invés do cliente de teste embutido (isto é, quando se usa a LiveServerTestCase do Django) o conteúdo estático precisa ser servido junto com o resto do conteúdo então o ambiente de teste reproduz o real tão fielmente quanto possível, mas LiveServeTestCase tem somente funcionalidades de servidor muito básicas de arquivos: Ele não sabe sobre as funcionalidades de procura da aplicação staticfiles e assume que o conteúdo estático já tenha sido coletado no STATIC_ROOT.

Por causa disso, staticfiles vem com sua própria django.contrib.staticfiles.testing.StaticLiveServerTestCase, uma subclasse daquela que vem embutida que tem a habilidade de servir de maneira transparente todos os ativos durante a execução destes testes de uma maneira similar a que temos em tempo de desenvolvimento com DEBUG = True, isto é, sem precisar coletá-los usando o collectstatic antes.

Deploy

django.contrib.staticfiles fornece um comando de gerenciamento conveniente para juntar arquivos estáticos em um único diretório para você poder servi-los facilmente.

1. Defina a configuração do STATIC_ROOT para o diretório do qual você gostaria de servir estes arquivos, por exemplo:

   STATIC_ROOT = "/var/www/example.com/static/"
   

2. Execute o comando de gerenciamento collectstatic

   $ python manage.py collectstatic
   

   Isso irá copiar todos os arquivos dos seus diretórios estáticos para dentro do diretório definido em STATIC_ROOT.

3. Use um servidor Web de sua escolha para servir os arquivos. O Deploy de arquivos estáticos cobre algumas estratégias de deploy comuns para arquivos estáticos.

Aprenda mais

Este documento cobriu o básico e alguns padrões comuns de uso. Para detalhes completos sobre todas as configurações, comandos, tags de templates, e outras partes incluidas em django.contrib.staticfiles, veja a referência de arquivos estáticos.