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

Os sites web geralmente precisam servir arquivos adicionais como imagens, JavaScript, ou CSS. No Django, nós nos referímos a estes arquivos como “arquivos estáticos”. O Django fornece django.contrib.staticfiles para ajudar você a lidar com 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 ::setting::INSTALLED_APPS.

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

    STATIC_URL = '/static/'
    
  3. Nos seus templates, ou coloque manualmente a url como /static/my_app/myexample.jpg ou, preferivelmente, use a tag de template static para construir a URL para o dado caminho relativo usando o armazenamento configurado em STATICFILES_STORAGE (isso torna mais fácil quando você quiser trocar para um CDN - (content delivery network) para servir arquivos estáticos).

    {% load staticfiles %}
    <img src="{% static "my_app/myexample.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/myimage.jpg.

Servindo os arquivos

Além desses passos de configurações, 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 somos capazes de resolver isso 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 outra aplicação, 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 fazer isso é contextualizando eles. Isso é, colocando aqueles arquivos estáticos dentro de um outro diretório nomeado para aquela aplicação específica.

Serving static files during development

Se você usa django.contrib.staticfiles como explicado acima, runserver irá fazer isso automaticamente quando o DEBUG está definido como True. Se você não tem django.contrib.staticfiles no INSTALLED_APPS, você ainda pode servir arquivos estáticos manualmente usando a “view” django.contrib.staticfiles.views.serve().

Isso não é apropriado para uso em produção!. Para algumas estratégias de implantação, 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

A função de auxílio funciona somente em mode de depuração e somente se o dado prefixo for local (ex.: /static/) e não uma URL (ex.: http://static.example.com/).

Ainda esta função de auxílio somente serve o diretório atual STATIC_ROOT; ela não faz a procura de arquivos estáticos como django.contrib.staticfiles.

Serving files uploaded by a user during development

Durante o desenvolvimento, você pode servir arquivos de media dos usuários através do MEDIA_ROOT usando a “view” django.contrib.staticfiles.views.serve().

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

Por exemplo, se o seu MEDIA_URL está definido como /media/, você pode faze-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 de auxílio funciona somente em mode 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 de arquivos muito básicas. Ele não sabe sobre as caraceterísticas de procura da aplicação staticfiles e assume que o conteúdo estático já tenha sido coletado pelo STATIC_ROOT.

Por causa disso, staticfiles vem com sua própria django.contrib.staticfiles.testing.StaticLiveServerTestCase, uma subclasse daquela que vem embutida uma 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 desenvovlimento com DEBUG = TRUE, isto é, sem coletá-los usando antes o collectstatic.

Implantação

django.contrib.staticfiles fornece um comando de gerenciamento conveniente para juntar arquivos estáticos e um único diretório então você pode servi-los facilmente.

  1. Defina a configuração do STATIC_ROOT para o diretorio 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 diretórios “static” 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 implantações comuns para arquivos estáticos.

Aprenda mais

Este documento cobriu o básico e alguns padrões de uso comum. 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.

Back to Top