# Documentation Django 5.2.8

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

Websites generally need to serve additional files such as images, JavaScript, or CSS. In Django, we refer to these files as « static files ». Django provides `django.contrib.staticfiles` to help you manage them.

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 l’alias configuré dans `STORAGES` de `staticfiles`.

       {% 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 d’administration `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.