Come gestire file statici (Es. immagini, JavaScript, CSS)

I siti web generalmente necessitano di servire file aggiuntivi come immagini, JavaScript o CSS. In Django, vi facciamo riferimento come «file statici». Django offre django.contrib.staticfiles per aiutarti a gestirli.

Questa pagina descrive come puoi distribuire questi file statici.

Configurazione file statici

  1. Assicurati che django.contrib.staticfiles sia inserito in INSTALLED_APPS.

  2. Nel tuo file dei settings, definisci STATIC_URL, per esempio:

    STATIC_URL = "static/"

  3. In your templates, use the static template tag to build the URL for the given relative path using the configured staticfiles STORAGES alias.

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

  4. Archivia i tuoi file statici in una cartella chiamata static nella tua app. Per esempio my_app/static/my_app/example.jpg.

Servire i file

In aggiunta a questi passaggi di configurazione, hai anche bisogno effettivamente di distribuire file statici.

Durante lo sviluppo, se usi django.contrib.staticfiles, sarà fatto automaticamente da runserver quando DEBUG è True (vedi django.contrib.staticfiles.views.serve()).

Questo metodo è altamente inefficiente e probabilmente poco sicuro, per questo è inadeguato alla produzione.

Consulta la documentazione Come distribuire file statici per le migliori strategie per distribuire file statici in ambienti di produzione.

Il tuo progetto avrà probabilmente anche asset statici che non sono legati ad una app particolare. Oltre ad usare una directory static/ nelle tue applicazioni, puoi definire una lista di directory (STATICFILES_DIRS) nel tuo file di impostazioni dove Django cercherà ulteriormente i file statici. Per esempio:

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

Consulta la documentazione per la configurazione relativa a STATICFILES_FINDERS per i dettagli su come staticfiles trova i tuoi files.

Namespacing dei file statici

Come per i template, potremmo semplicemente inserire i nostri file statici direttamente in my_app/static/ (anziché creare un’altra sottodirectory my_app), ma sarebbe certamente una cattiva idea. Django sceglierà il primo file statico che troverà con un nome che corrisponde, e se tu avessi un file statico con lo stesso nome in una app diversa, Django non saprebbe come distinguere fra i due. Dobbiamo essere in grado di puntare Django sul file corretto, ed il modo migliore per farlo è quello di inserirlo in un namespace. Cioè, inserendo questi file statici dentro un’altra directory che abbia come nome il nome della app stessa.

Puoi assegnare namespace agli asset statici in STATICFILES_DIRS specificando prefissi.

Servire file statici durante lo sviluppo

Se usi django.contrib.staticfiles come spiegato sopra, runserver lo farà automaticamente se DEBUG è impostato su True. Se non hai django.contrib.staticfiles in INSTALLED_APPS, puoi comunque servire manualmente i file statici usando la vista django.views.static.serve().

Questo non è adatto per un utilizzo in produzione! Per alcune strategie di pubblicazione comuni, guarda Come distribuire file statici.

Per esempio, se la tua impostazione STATIC_URL è definita come static/, puoi fare questo aggiungendo il seguente snippet a 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

Questa funzione helper funziona solo in modalità debug e solo se il prefisso dato è locale (ad esempio static/) e non un URL (es: http://static.example.com/).

Anche questa funzione helper serve solo la cartella STATIC_ROOT; non esegue la disocvery dei file statici come django.contrib.staticfiles.

Infine, i file statici sono serviti via wrapper al livello di applicazione WSGI. Di conseguenza, le richieste a file static non passano attraverso la normale catena di middleware.

Distribuire file caricati da un utente durante lo sviluppo

Durante lo sviluppo, è possibile servire file multimediali caricati dall’utente da:setting:MEDIA_ROOT utilizzando la vista django.views.static.serve().

Questo non è adatto per un utilizzo in produzione! Per alcune strategie di pubblicazione comuni, guarda Come distribuire file statici.

Ad esempio, se il tuo MEDIA_URL è definita come media/, puoi farlo aggiungendo il seguente snippet al tuo:setting: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)

Nota

Questa funzione di supporto è disponibile solo in modalità debug e solo se il prefisso è locale (es. media/) ma non unaURL (es. http://media.example.com/).

Testing

Quando si eseguono test che utilizzano richieste HTTP effettive invece del client di test integrato (per esempio utilizzando LiveServerTestCase) gli asset statici devono essere serviti insieme al resto del contenuto in modo che l’ambiente di test riproduca quello reale il più fedelmente possibile, ma LiveServerTestCase ha solo funzionalità di servizio di file statici molto basilari: non conosce la funzione di ricerca dell’applicazione staticfiles e presuppone il il contenuto statico sia già stato collezionato in STATIC_ROOT.

A causa di ciò, staticfiles offre la propria django.contrib.staticfiles.testing.StaticLiveServerTestCase, una sottoclasse di quella built-in che ha l’abilità di servire trasparentemente tutti gli asset durante l’esecuzione di questi test in modo molto simile a quello che si ottiene durante lo sviluppo con DEBUG = True, cioè senza doverli collezionare usando prima collectstatic.

Deployment

django.contrib.staticfiles fornisce un comando di gestione comodo per la raccolta di file statici in un’unica directory in modo da poterli servire facilmente.

  1. Imposta il valore di STATIC_ROOT alla directory da cui desideri servire questi file, ad esempio:

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

  2. Run the collectstatic management command:

    $ python manage.py collectstatic

    Questo copia tutti i file dalla tua cartella static nella cartella definita in STATIC_ROOT .

  3. Utilizza un web server a tua scelta per distribuire i files. Come distribuire file statici  copre alcune delle strategie di distribuzione comuni per i file statici.

Per saperne di più

Questo documento ha coperto le basi ed alcuni pattern di utilizzo comuni. Per avere dettagli completi su tutte le impostazioni, i comandi, i tag di template ed altri frammenti inclusi in django.contrib.staticfiles, visita la guida di riferimento di staticfiles.

Come sovrascrivere i templates
Come distribuire file statici
Back to Top