Gestion des fichiers statiques (par ex. images, JavaScript, CSS)

Les sites Web ont généralement besoin de servir des fichiers supplémentaires tels que des images, du JavaScript ou du CSS. Dans Django, ces fichiers sont appelés « fichiers statiques ». Django met à disposition django.contrib.staticfiles pour vous assister dans cette gestion.

Cette page documente la manière de servir ces fichiers statiques.

Configuration des fichiers statiques

  1. Assurez-vous que django.contrib.staticfiles est inclus dans votre réglage INSTALLED_APPS.

  2. Dans votre fichier de réglages, définissez STATIC_URL, par exemple :

    STATIC_URL = 'static/'

  3. Dans vos gabarits, utilisez la balise de gabarit static pour contruire l’URL du chemin relatif donné en utilisant le stockage STATICFILES_STORAGE configuré.

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

  4. Stockez vos fichiers statiques dans un dossier nommé static dans votre application. Par exemple, mon_app/static/mon_app/exemple.jpg.

Service de fichiers

En plus de ces étapes de configuration, vous devrez également servir les fichiers statiques.

Pendant le développement et si vous utilisez django.contrib.staticfiles, les fichiers statiques sont automatiquement servis par runserver quand DEBUG est défini à True (voir django.contrib.staticfiles.views.serve()).

Cette méthode est notoirement inefficace et probablement non sécurisée, elle n’est donc pas adéquate en production.

Consultez Déploiement des fichiers statiques pour de vraies stratégies de service de fichiers statiques dans des environnements de production.

Votre projet aura probablement aussi des éléments statiques non liés à une application particulière. En plus d’utiliser le répertoire static/ dans vos applications, vous pouvez définir une liste de répertoires (STATICFILES_DIRS) dans votre fichier de réglages indiquant à Django où il trouvera d’autres fichiers statiques. Par exemple :

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

Consultez la documentation du réglage STATICFILES_FINDERS pour plus de détails sur la façon dont staticfiles trouve vos fichiers.

Espaces de noms des fichiers statiques

Nous pourrions plus simplement placer nos fichiers statiques directement dans my_app/static (au lieu de créer un sous-répertoire my_app), mais ce serait une mauvaise idée. Django choisit le premier fichier statique correspondant au nom recherché, et si vous aviez un fichier de même nom dans une autre application, Django ne pourrait pas les distinguer. Nous devons pouvoir indiquer à Django le bon fichier et le meilleur moyen de s’en assurer est d’utiliser les espaces de noms. C’est-à-dire en plaçant ces fichiers statiques dans un autre sous-répertoire nommé d’après l’application.

Dans STATICFILES_DIRS, il est possible d’indiquer des espaces de nom en utilisant des préfixes.

Service des fichiers statiques en développement

Si vous utilisez django.contrib.staticfiles comme expliqué ci-dessus, runserver fait automatiquement cela lorsque DEBUG est défini à True. Si django.contrib.staticfiles ne se trouve pas dans INSTALLED_APPS, vous pouvez tout de même servir les fichiers statiques manuellement à l’aide de la vue django.views.static.serve().

Ce n’est cependant pas acceptable en production ! Vous pouvez consultez quelques stratégies courantes de déploiement dans Déploiement des fichiers statiques.

Par exemple, si le réglage STATIC_URL est défini comme static/, vous pouvez configurer ce service en ajoutant le bout de code suivant dans votre fichier 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)

Note

Cette fonction utilitaire ne fonctionne qu’en mode « debug » et seulement si le préfixe donné est local (par ex. static/), pas une URL (par ex. http://static.example.com/).

De plus, cette fonction utilitaire ne s’occupe que du dossier réel STATIC_ROOT; elle n’effectue aucune découverte de fichiers statiques comme le fait django.contrib.staticfiles.

Pour terminer, les fichiers statiques sont servis par un adaptateur au niveau de la couche applicative WSGI. En conséquence, les requêtes de fichiers statiques ne passent pas par la chaîne d’intergiciels normale.

Service de fichiers téléversés par les utilisateurs durant le développement

Durant le développement, vous pouvez servir les fichiers téléversés dans MEDIA_ROOT par les utilisateurs en utilisant la vue django.views.static.serve().

Ce n’est cependant pas acceptable en production ! Vous pouvez consultez quelques stratégies courantes de déploiement dans Déploiement des fichiers statiques.

Par exemple, si le réglage MEDIA_URL est défini comme media/, vous pouvez configurer ce service en ajoutant le bout de code suivant dans votre réglage 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)

Note

Cette fonction utilitaire ne fonctionne qu’en mode « debug » et seulement si le préfixe donné est local (par ex. media/), pas une URL (par ex. http://media.example.com/).

Tests

Lors de l’exécution de tests qui utilisent une véritable requête HTTP à la place du client de test intégré (c’est-à-dire en utilisant la classe LiveServerTestCase intégrée), les fichiers statiques doivent être servis tout comme le reste du contenu de sorte que l’environnement de test reproduise l’environnement réel le plus fidèlement possible ; mais LiveServerTestCase ne dispose que d’une fonctionnalité très basique pour servir les fichiers : il ne connaît pas la fonctionnalité de détection des fichiers de l’application staticfiles et suppose que le contenu statique a déjà été collecté dans STATIC_ROOT.

Pour cette raison, staticfiles est fournie avec sa propre classe django.contrib.staticfiles.testing.StaticLiveServerTestCase, une sous-classe de la précédente qui a la capacité de servir de manière transparente tous les fichiers statiques lors de l’exécution de ces tests, d’une manière très semblable à ce que nous obtenons lors du développement avec DEBUG = True, c’est-à-dire sans avoir à les collecter au préalable à l’aide de collectstatic.

Déploiement

django.contrib.staticfiles fournit une commande de gestion de commodité pour rassembler les fichiers statiques dans un seul répertoire pour pouvoir plus facilement en faire le service.

  1. Définissez le réglage STATIC_ROOT pour qu’il corresponde au répertoire à partir duquel vous souhaitez servir les fichiers, par exemple :

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

  2. Lancez la commande de gestion collectstatic:

    $ python manage.py collectstatic

    Cela va copier tous les fichiers de vos dossiers de fichiers statiques vers le répertoire STATIC_ROOT.

  3. Utilisez un serveur Web de votre choix pour servir les fichiers. Déploiement des fichiers statiques aborde certaines stratégies de déploiement des fichiers statiques fréquemment utilisées.

En savoir plus

Ce document a abordé les bases ainsi que quelques scénarios courants. Pour des détails complets sur tous les réglages, les commandes, les balises de gabarit et les autres fonctions de django.contrib.staticfiles, consultez la référence de staticfiles.

Surcharge des gabarits
Déploiement des fichiers statiques
Back to Top