CDN:Nginx HTTP cache policy

Exemples courants de politiques de mise en cache

Cette section présente des configurations de mise en cache courantes que vous pouvez appliquer directement à votre fichier de configuration Nginx. Tous les exemples utilisent la directive add_header ... always; pour ajouter un en-tête de mise en cache à toutes les réponses, y compris celles avec un code d'état de réponse 304 Not Modified.

# Configure long-term caching for static assets
# - For filenames with 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 assets with a hash generated by build tools: cache for 1 year, and instruct the browser to never revalidate.
    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 generic static assets without a hash: cache for 30 days and allow both 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.
    # The 'private' directive prevents an intermediate proxy (like a CDN) 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 based on your setup)
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 client

Vous pouvez contrôler la mise en cache du navigateur en ajoutant les en-têtes Cache-Control et Expires aux réponses HTTP.

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 la ressource pendant 30 jours), expires -1; (force le client à valider la ressource auprès du serveur avant utilisation (équivalent à Cache-Control: no-cache), mais permet la mise en cache de la ressource).

  • Remarque : La directive add_header est recommandée car elle offre un contrôle plus granulaire.

• 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 les en-têtes personnalisés. Bien que les navigateurs réutilisent la politique de mise en cache de la réponse 200 initiale, vous devez ajouter le paramètre always aux en-têtes de contrôle de cache pour plus de clarté et de compatibilité. Cela garantit que les en-têtes s'appliquent à tous les codes d'état de réponse.

Directives Cache-Control

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

• private : La réponse ne peut être stockée que par le navigateur de l'utilisateur final, et non par des caches partagés comme les CDN. Ceci est utile pour le contenu contenant des informations spécifiques à l'utilisateur.

• no-cache : Exige que le client envoie une requête au serveur pour valider une copie mise en cache avant chaque utilisation. Si la ressource n'a pas changé, le serveur renvoie 304 Not Modified, permettant au client d'utiliser le cache local et d'économiser de la bande passante.

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

• max-age=<seconds> : Définit la durée de vie (TTL) du cache en secondes.

• immutable : Informe le navigateur que le contenu de la ressource ne changera pas tant qu'il est mis en cache. C'est idéal pour les fichiers qui incluent un hachage de contenu dans le nom de fichier.

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 l'en-tête de réponse. Utilisez curl pour vérifier la présence de l'en-tête de cache. Cette méthode contourne tout cache du navigateur.

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

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

4. Vérifiez le comportement 304 (pour les politiques basées sur no-cache ou ETag) Testez avec 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  # Expects a 304 response

5. Vérifiez dans un navigateur

   1. Ouvrez les outils de développement et accédez au panneau Réseau.

   2. Sélectionnez la case à cocher Disable cache pour afficher le chargement initial. L'état doit être 200 OK.

   3. Désélectionnez la case et actualisez la page :

      1. Aucune requête n'est effectuée ou affichée (from cache) → hit de cache fort

      2. Renvoie 304 → hit de cache conditionnel

FAQ