Hur man hanterar statiska filer (t.ex. bilder, JavaScript, CSS)

Webbplatser behöver i allmänhet servera ytterligare filer, till exempel bilder, JavaScript eller CSS. I Django hänvisar vi till dessa filer som ”statiska filer”. Django tillhandahåller django.contrib.staticfiles för att hjälpa dig att hantera dem.

På den här sidan beskrivs hur du kan servera dessa statiska filer.

Konfigurera statiska filer

1. Se till att django.contrib.staticfiles ingår i din INSTALLED_APPS.

2. I din inställningsfil definierar du STATIC_URL, till exempel:

   STATIC_URL = "static/"
   

3. I dina mallar använder du malltaggen static för att bygga URL:en för den angivna relativa sökvägen med hjälp av det konfigurerade aliaset staticfiles STORAGES.

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

4. Lagra dina statiska filer i en mapp som heter static i din app. Till exempel my_app/static/my_app/example.jpg.

Servering av filer

Utöver dessa konfigurationssteg måste du också faktiskt servera de statiska filerna.

Under utveckling, om du använder django.contrib.staticfiles, kommer detta att göras automatiskt av runserver när DEBUG är inställd på True (se django.contrib.staticfiles.views.serve()).

Den här metoden är grovt ineffektiv och förmodligen osäker, så den är olämplig för produktion.

Se Så här distribuerar du statiska filer för korrekta strategier för att servera statiska filer i produktionsmiljöer.

Ditt projekt kommer förmodligen också att ha statiska tillgångar som inte är knutna till en viss app. Förutom att använda en static/-katalog i dina appar kan du definiera en lista över kataloger (STATICFILES_DIRS) i din inställningsfil där Django också kommer att leta efter statiska filer. Till exempel:

STATICFILES_DIRS = [
    BASE_DIR / "static",
    "/var/www/static/",
]

Se dokumentationen för inställningen STATICFILES_FINDERS för mer information om hur staticfiles hittar dina filer.

Namnavstånd för statiska filer

Nu skulle vi måhända kunna komma undan med att lägga våra statiska filer direkt i my_app/static/ (snarare än att skapa en annan my_app underkatalog), men det skulle faktiskt vara en dålig idé. Django kommer att använda den första statiska filen som den hittar vars namn matchar, och om du hade en statisk fil med samma namn i en annan applikation skulle Django inte kunna skilja mellan dem. Vi måste kunna peka Django på den rätta, och det bästa sättet att säkerställa detta är genom att namespacing dem. Det vill säga genom att lägga dessa statiska filer i en annan katalog som heter för själva applikationen.

Du kan namnge statiska tillgångar i STATICFILES_DIRS genom att ange prefixes.

Servering av statiska filer under utveckling

Om du använder django.contrib.staticfiles enligt förklaringen ovan kommer runserver att göra detta automatiskt när DEBUG är inställd på True. Om du inte har django.contrib.staticfiles i INSTALLED_APPS kan du fortfarande manuellt servera statiska filer med hjälp av vyn django.views.static.serve().

Detta är inte lämpligt för produktionsanvändning! För några vanliga distributionsstrategier, se Så här distribuerar du statiska filer.

Till exempel, om din STATIC_URL är definierad som static/, kan du göra detta genom att lägga till följande snutt i din 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)

Observera

Denna hjälpfunktion fungerar endast i felsökningsläge och endast om det angivna prefixet är lokalt (t.ex. static/) och inte en URL (t.ex. http://static.example.com/).

Även denna hjälpfunktion tjänar endast den faktiska STATIC_ROOT-mappen; den utför inte upptäckt av statiska filer som django.contrib.staticfiles.

Slutligen serveras statiska filer via ett omslag i WSGI:s applikationslager. Som en konsekvens av detta passerar inte förfrågningar om statiska filer genom den normala middleware-kedjan.

Servering av filer som laddats upp av en användare under utvecklingen

Under utvecklingen kan du servera användaruppladdade mediefiler från MEDIA_ROOT med hjälp av vyn django.views.static.serve().

Detta är inte lämpligt för produktionsanvändning! För några vanliga distributionsstrategier, se Så här distribuerar du statiska filer.

Om till exempel din MEDIA_URL är definierad som media/, kan du göra detta genom att lägga till följande snutt i din ROOT_URLCONF:

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)

Observera

Denna hjälpfunktion fungerar endast i felsökningsläge och endast om det angivna prefixet är lokalt (t.ex. media/) och inte en URL (t.ex. http://media.example.com/).

Testar

När du kör tester som använder faktiska HTTP-förfrågningar istället för den inbyggda testklienten (dvs. när du använder den inbyggda LiveServerTestCase) måste de statiska tillgångarna serveras tillsammans med resten av innehållet så att testmiljön återger den verkliga så troget som möjligt, men LiveServerTestCase har endast mycket grundläggande funktionalitet för servering av statiska filer: Det känner inte till sökfunktionen i applikationen staticfiles och förutsätter att det statiska innehållet redan har samlats under STATIC_ROOT.

På grund av detta levererar staticfiles sin egen django.contrib.staticfiles.testing.StaticLiveServerTestCase, en underklass av den inbyggda som har förmågan att transparent servera alla tillgångar under körning av dessa tester på ett sätt som liknar det vi får vid utvecklingstid med DEBUG = True, dvs. utan att behöva samla in dem med collectstatic först.

Utplacering

django.contrib.staticfiles tillhandahåller ett bekvämt hanteringskommando för att samla statiska filer i en enda katalog så att du enkelt kan servera dem.

1. Ställ in STATIC_ROOT till den katalog från vilken du vill servera dessa filer, till exempel:

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

2. Kör kommandot collectstatic management:

   $ python manage.py collectstatic
   

   Detta kommer att kopiera alla filer från dina statiska mappar till STATIC_ROOT-katalogen.

3. Använd en valfri webbserver för att visa filerna. Så här distribuerar du statiska filer beskriver några vanliga distributionsstrategier för statiska filer.

Läs mer

Detta dokument har täckt grunderna och några vanliga användningsmönster. För fullständiga detaljer om alla inställningar, kommandon, malltaggar och andra delar som ingår i django.contrib.staticfiles, se the staticfiles reference.