immutable: NGINX-Modul zum Setzen von unveränderlichem Caching für statische Assets

Erfordert den Pro-Plan (oder höher) des GetPageSpeed NGINX Extras Abonnements.

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

RedHat Enterprise Linux 7, 8, 9 und 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 und Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 und Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-immutable

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-immutable

Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_immutable_module.so;

Dieses Dokument beschreibt nginx-module-immutable v0.0.7, veröffentlicht am 20. März 2026.

Dieses kleine NGINX-Modul kann helfen, das Caching Ihrer öffentlichen statischen Assets zu verbessern, indem es eine weit in die Zukunft liegende Ablaufzeit mit dem immutable Attribut festlegt.

Zielgruppe

Websites und Frameworks, die auf das Cache-Busting-Muster angewiesen sind:

Statische Ressourcen enthalten Versionen/Hashes in ihren URLs, während die Ressourcen nie verändert werden
Bei Bedarf werden die Ressourcen mit neueren Versionen aktualisiert, die neue Versionsnummern/Hashes haben, sodass ihre URLs unterschiedlich sind

Beliebte Frameworks, die Cache-Busting verwenden:

Magento 2
Fügen Sie hier Ihr eigenes hinzu!

Zusammenfassung

http {
    server {
        location /static/ {
            immutable on;
        }
    }
}

führt zu folgendem HTTP-Header:

Cache-Control: public,max-age=31536000,stale-while-revalidate=31536000,stale-if-error=31536000,immutable

Hinweis: HTTP/1.0-Clients erhalten einen Expires: Thu, 31 Dec 2037 23:55:55 GMT Header anstelle von Cache-Control.

Wie es sich von expires max; unterscheidet:

Setzt das immutable Attribut, z.B. Cache-Control: public,max-age=31536000,immutable für verbessertes Caching. Das sind 1 Jahr und nicht 10 Jahre, siehe warum unten.
Sendet Expires nur, wenn es wirklich notwendig ist, z.B. wenn ein Client Ressourcen über HTTP/1.0 anfordert
Setzt das public Attribut, um sicherzustellen, dass die Assets von öffentlichen Caches zwischengespeichert werden können, was typischerweise gewünscht ist.

Aufgrund der fehlenden Unterstützung von immutable in Chromium-basierten Browsern, fügen wir auch stale-while-revalidate=31536000,stale-if-error=31536000 hinzu, was hilft, die Cache-Trefferquote in Grenzfällen zu verbessern. Die Verwendung dieser Direktiven ermöglicht das Bereitstellen von zwischengespeicherten Antworten über ihre Cache-Lebensdauer hinaus, was im Fall von unveränderlichen Ressourcen für immer ist.

Daher kann in den meisten Fällen immutable on; als bessere Alternative zu expires max; verwendet werden, um das Cache-Busting-Muster zu implementieren.

Direktiven

immutable

Syntax: immutable on | off;

Standard: immutable off;

Kontext: http, server, location

Aktiviert oder deaktiviert unveränderliche Caching-Header für den Standort.

immutable_cache_status

Syntax: immutable_cache_status on | off;

Standard: immutable_cache_status off;

Kontext: http, server, location

Aktiviert den RFC 9211 Cache-Status Header für Debugging und Beobachtbarkeit. Wenn aktiviert, enthalten Antworten:

Cache-Status: "nginx/immutable"; hit; ttl=31536000

Dieser Header hilft, das Caching-Verhalten über mehrschichtige Caching-Architekturen (NGINX -> CDN -> Browser) zu debuggen. Jede Cache-Schicht kann ihren eigenen Status anhängen und eine Kette wie folgt erstellen:

Cache-Status: "nginx/immutable"; hit; ttl=31536000, "cloudflare"; fwd=uri-miss; stored

Beispielkonfiguration:

location /static/ {
    immutable on;
    immutable_cache_status on;
}

immutable_types

Syntax: immutable_types mime-type ...;

Standard: (keiner - gilt für alle Typen, wenn nicht angegeben)

Kontext: http, server, location

Beschränkt die unveränderlichen Caching-Header auf Antworten mit den angegebenen MIME-Typen. Wenn nicht angegeben, gelten unveränderliche Header für alle Antworten. Dies ähnelt der Funktionsweise von gzip_types für das gzip-Modul.

Beispielkonfiguration:

location /static/ {
    immutable on;
    # Wenden Sie unveränderliche Header nur auf JavaScript- und CSS-Dateien an
    immutable_types application/javascript text/css;
}

Warum 31536000 Sekunden (1 Jahr?)

Der RFC definiert, dass ein Jahr verwendet wird, um eine Antwort als "nie ablaufend" zu kennzeichnen:

Um eine Antwort als „nie ablaufend“ zu kennzeichnen, sendet ein Origin-Server ein Ablaufdatum, das ungefähr ein Jahr nach dem Zeitpunkt liegt, zu dem die Antwort gesendet wird. HTTP/1.1-Server DÜRFEN keine Ablaufdaten mehr als ein Jahr in der Zukunft senden.

Weitere Details in dem Artikel.

Ubuntu- und Debian-Pakete

Es ist einfach, das Modulpaket für diese Betriebssysteme zu installieren.

ngx_immutable ist Teil der APT NGINX Extras Sammlung, sodass Sie es zusammen mit beliebigen Modulen installieren können, einschließlich Brotli.

Zuerst richten Sie das Repository ein, dann:

sudo apt-get update
sudo apt-get install nginx-module-immutable

Beispiel: Magento 2 Produktionskonfiguration

Vorausgesetzt, Ihr Shop läuft im Produktionsmodus, haben Sie bereits alle Assets kompiliert. Diese Beispielkonfiguration kann optimiert werden zu:

location /static/ {
    immutable on;

    # Entfernen Sie die Signatur der statischen Dateien, die verwendet wird, um den Browser-Cache zu überwinden
    location ~ ^/static/version {
        rewrite ^/static/(version\d*/)?(.*)$ /static/$2 last;
    }

    location ~* \.(ico|jpg|jpeg|png|gif|svg|js|css|swf|eot|ttf|otf|woff|woff2|json)$ {
        add_header X-Frame-Options "SAMEORIGIN";
    }
    location ~* \.(zip|gz|gzip|bz2|csv|xml)$ {
        add_header Cache-Control "no-store";
        add_header X-Frame-Options "SAMEORIGIN";
        immutable off;
    }
    add_header X-Frame-Options "SAMEORIGIN";
}

Wenn es zusammen mit ngx_security_headers verwendet wird, kann es weiter vereinfacht werden:

security_headers on;

location /static/ {
    immutable on;

    location ~ ^/static/version {
        rewrite ^/static/(version\d*/)?(.*)$ /static/$2 last;
    }

    location ~* \.(zip|gz|gzip|bz2|csv|xml)$ {
        add_header Cache-Control "no-store";
        immutable off;
    }
}