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¶
Certifique-se de que
django.contrib.staticfiles
está incluído no seuINSTALLED_APPS
.Em seu arquivo de configurações, defina
STATIC_URL
, por exemplo:STATIC_URL = '/static/'
Nos seus templates, use uma url hardcoded como
/static/my_app/example.jpg
ou, preferencialmente, use a tag de templatestatic
para construir a URL para um dado caminho relativo usando a definição de armazenamento emSTATICFILES_STORAGE
(isso torna muito mais fácil quando você quiser trocar para uma rede de entrega de conteúdo (CDN) para servir os arquivos).{% load static %} <img src="{% static "my_app/example.jpg" %}" alt="My image"/>
Armazene seus arquivos estáticos no diretório chamado
static
dentro da sua app. Por exemplomy_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¶
If you use django.contrib.staticfiles
as explained above,
runserver
will do this automatically when DEBUG
is set
to True
. If you don’t have django.contrib.staticfiles
in
INSTALLED_APPS
, you can still manually serve static files using the
django.views.static.serve()
view.
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¶
During development, you can serve user-uploaded media files from
MEDIA_ROOT
using the django.views.static.serve()
view.
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.
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/"
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
.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.