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¶
Assurez-vous que
django.contrib.staticfiles
est inclus dans votre réglageINSTALLED_APPS
.Dans votre fichier de réglages, définissez
STATIC_URL
, par exemple :STATIC_URL = '/static/'
Dans vos gabarits, utilisez la balise de gabarit
static
pour contruire l’URL du chemin relatif donné en utilisant le stockageSTATICFILES_STORAGE
configuré.{% load static %} <img src="{% static "my_app/example.jpg" %}" alt="My image">
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 = [
os.path.join(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 moyen le plus simple 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.
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
.
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 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.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.
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/"
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
.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.