:Configurer les politiques de cache HTTP Nginx

Exemples courants de politiques de cache

Cette rubrique présente des configurations de mise en cache courantes que vous pouvez ajouter à votre fichier de configuration Nginx pour différents cas d'utilisation. Tous les exemples utilisent add_header ... always; pour garantir que les en-têtes de cache sont ajoutés à toutes les réponses, y compris 304 Not Modified.

# Set long-term caching for static resources
# - For filenames that contain a content hash (e.g., main.a1b2c3d4.js), a 1-year cache with immutable is recommended.
location ~* "\.[a-f0-9]{8,}\.(css|js|png|jpg|jpeg|gif|svg|webp|ico|woff|woff2)$" {
    # For resources with hashes generated by build tools: cache for 1 year, browser never revalidates.
    add_header Cache-Control "public, max-age=31536003, immutable" always;
    access_log off;
}

# - For filenames that are fixed and rarely change (e.g., logo.png), use a 30-day cache.
location ~* \.(css|js|png|jpg|jpeg|gif|svg|webp|ico|woff|woff2)$ {
    # For general static resources without hashes: cache for 30 days, allows CDN and browser caching.
    add_header Cache-Control "public, max-age=2592000" always;
    access_log off;
}

# For directly requested HTML files
location ~* \.html$ {
    # Allows browser caching, but requires revalidation with the server before each use.
    # 'private' prevents intermediate proxies (like CDNs) from caching this response.
    # The server must provide an ETag or Last-Modified header to support validation.
    add_header Cache-Control "private, no-cache, must-revalidate" always;
}

# Example: For dynamic PHP scripts (adjust the path as needed)
location ~ \.php$ {
    # ... Other PHP-FPM configurations ...

    # Disable all caching: Browsers, proxies, and CDNs must not store the response.
    # 'no-store' is the strictest cache control directive.
    add_header Cache-Control "no-store" always;
}

Configuration du cache côté client (contrôle du navigateur)

Vous pouvez contrôler le comportement du cache du navigateur d'un utilisateur en ajoutant les en-têtes Cache-Control et Expires à la réponse HTTP. Cette pratique réduit les requêtes réseau et accélère l'accès pour les utilisateurs finaux.

Directives principales

• Directive expires : définit à la fois l'en-tête Expires et la valeur max-age de l'en-tête Cache-Control.

  • Syntaxe : expires [time|epoch|max|off];

  • Exemple : expires 30d; met en cache pendant 30 jours. expires -1; force le client à revalider la ressource auprès du serveur avant d'utiliser la version mise en cache. Cela équivaut à Cache-Control: no-cache mais permet toujours au cache de stocker la ressource.

  • Remarque : la directive add_header offre un contrôle plus granulaire et constitue la méthode de configuration recommandée.

• Directive add_header : ajoute un en-tête HTTP spécifié à la réponse.

  • Syntaxe : add_header <name> <value> [always];

  • Description du paramètre always : par défaut, add_header s'applique uniquement aux réponses 2xx et 3xx. Pour les réponses 304 Not Modified, Nginx n'ajoute pas automatiquement d'en-têtes personnalisés. Bien que le navigateur utilise la politique de cache de la réponse 200 initiale, vous devez ajouter le paramètre always à l'en-tête de contrôle du cache. Cela garantit la clarté et la compatibilité en appliquant l'en-tête à tous les codes d'état de réponse.

Descriptions des valeurs clés de Cache-Control

• public : la réponse peut être mise en cache par n'importe quel cache, y compris les navigateurs, les CDN et les serveurs proxy.

• private : seul le navigateur de l'utilisateur final peut mettre la réponse en cache. Les caches partagés, tels que les CDN, sont interdits. Cela convient au contenu contenant des informations spécifiques à l'utilisateur.

• no-cache : oblige le client à envoyer une requête de validation au serveur avant chaque utilisation d'une copie mise en cache. Si la ressource n'a pas changé, le serveur renvoie 304 Not Modified et le client utilise le cache local. Cela permet d'économiser de la bande passante.

• no-store : interdit aux navigateurs et aux serveurs proxy de stocker toute partie de la réponse. Cela convient aux données hautement sensibles.

• max-age=<seconds> : définit la période de validité du cache en secondes.

• immutable : informe le navigateur que le contenu de la ressource ne changera pas pendant sa durée de fraîcheur. Le navigateur peut alors ignorer la requête de validation pour cette ressource, même lorsque l'utilisateur actualise complètement la page. Cela est idéal pour les fichiers dont les noms contiennent des hachages de version.

Déploiement et vérification

1. Modifiez la configuration. Ajoutez le bloc location au bloc server de votre site. Le fichier de configuration se trouve généralement dans /etc/nginx/conf.d/ ou /etc/nginx/sites-enabled/.

2. Rechargez la configuration.

   sudo nginx -t && sudo nginx -s reload

3. Vérifiez les en-têtes de réponse. Utilisez curl pour vérifier si les en-têtes de cache sont actifs. Cette méthode n'est pas affectée par le cache du navigateur.

   curl -I http://your-domain.com/path/to/file.js

   La sortie doit inclure les en-têtes attendus, tels que Cache-Control: public, max-age=31536000.

4. Vérifiez le comportement 304 (si ETag ou no-cache est configuré). Testez en envoyant manuellement un en-tête de validation :

   ETAG=$(curl -I http://example.com/file.js 2>/dev/null | grep -i etag | cut -d' ' -f2 | tr -d '\r')
   curl -H "If-None-Match: $ETAG" -I http://example.com/file.js  # Expect a 304 response

5. Vérifiez dans le navigateur.

   1. Accédez à Developer Tools → Network panel.

   2. Cochez la case Disable cache pour voir le chargement initial (doit afficher un statut 200 OK).

   3. Décochez la case et actualisez la page :

      1. Aucune requête ou from cache n'est affichée. Cela indique un hit de cache fort.

      2. 304 est affiché. Cela indique un hit de cache conditionnel.

FAQ

# In the http block
map $sent_http_content_type $cache_control {
    ~^image/    "public, max-age=2592000";
    text/css    "public, max-age=2592000";
    application/javascript "public, max-age=2592000";
    default     "no-cache";
}

# In the server block
add_header Cache-Control $cache_control always;