Saltar a contenido

immutable: Módulo NGINX para establecer caché inmutable en activos estáticos

Requiere el plan Pro (o superior) de la suscripción GetPageSpeed NGINX Extras.

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y Amazon Linux 2023
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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_immutable_module.so;

Este documento describe nginx-module-immutable v0.0.7 lanzado el 20 de marzo de 2026.

Coverity Scan Buy Me a Coffee

Este pequeño módulo NGINX puede ayudar a mejorar la caché de tus activos estáticos públicos, estableciendo una expiración a largo plazo con el atributo immutable.

Público objetivo

Sitios web y frameworks que dependen del patrón de ruptura de caché:

  • los recursos estáticos incluyen versiones/hash en sus URLs, mientras que nunca modifican los recursos
  • cuando es necesario, actualizando los recursos con versiones más nuevas que tienen nuevos números/hash de versión, de modo que sus URLs sean diferentes

Frameworks populares que utilizan ruptura de caché:

  • Magento 2
  • ¡Incluye el tuyo aquí!

Sinopsis

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

produciendo el siguiente encabezado HTTP:

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

Nota: Los clientes HTTP/1.0 reciben un encabezado Expires: Thu, 31 Dec 2037 23:55:55 GMT en lugar de Cache-Control.

Cómo se diferencia de expires max;:

  • Establece el atributo immutable, por ejemplo, Cache-Control: public,max-age=31536000,immutable para mejorar la caché. Eso es 1 año y no 10 años, ve por qué a continuación.
  • Envía Expires solo cuando es realmente necesario, por ejemplo, cuando un cliente solicita recursos a través de HTTP/1.0
  • Establece el atributo public para asegurar que los activos puedan ser almacenados en caché por cachés públicas, lo cual es típicamente deseado.

Debido al falta de soporte de immutable en navegadores basados en Chromium, también añadimos stale-while-revalidate=31536000,stale-if-error=31536000, lo que ayuda a mejorar la tasa de aciertos de caché en casos extremos. El uso de estas directivas permite servir respuestas en caché más allá de su vida útil de caché, que es para siempre en el caso de recursos inmutables.

Por lo tanto, en la mayoría de los casos, immutable on; puede usarse como una mejor alternativa a expires max; para implementar el patrón de ruptura de caché.

Directivas

immutable

Sintaxis: immutable on | off;

Predeterminado: immutable off;

Contexto: http, server, location

Habilita o deshabilita los encabezados de caché inmutable para la ubicación.

immutable_cache_status

Sintaxis: immutable_cache_status on | off;

Predeterminado: immutable_cache_status off;

Contexto: http, server, location

Habilita el encabezado RFC 9211 Cache-Status para depuración y observabilidad. Cuando está habilitado, las respuestas incluyen:

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

Este encabezado ayuda a depurar el comportamiento de la caché a través de arquitecturas de caché de múltiples capas (NGINX -> CDN -> Navegador). Cada capa de caché puede agregar su propio estado, creando una cadena como:

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

Ejemplo de configuración:

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

immutable_types

Sintaxis: immutable_types mime-type ...;

Predeterminado: (ninguno - se aplica a todos los tipos cuando no se especifica)

Contexto: http, server, location

Restringe los encabezados de caché inmutable a respuestas con los tipos MIME especificados. Cuando no se especifica, los encabezados inmutables se aplican a todas las respuestas. Esto es similar a cómo funciona gzip_types para el módulo gzip.

Ejemplo de configuración:

location /static/ {
    immutable on;
    # Solo aplicar encabezados inmutables a archivos JavaScript y CSS
    immutable_types application/javascript text/css;
}

¿Por qué 31536000 segundos (1 año?)

El RFC define usar un año para hacer que una respuesta sea "nunca expira":

Para marcar una respuesta como "nunca expira", un servidor de origen envía una fecha de expiración aproximadamente un año desde el momento en que se envía la respuesta. Los servidores HTTP/1.1 NO DEBERÍAN enviar fechas de expiración más de un año en el futuro.

Más detalles en el artículo.

Paquetes de Ubuntu y Debian

Es fácil instalar el paquete del módulo para estos sistemas operativos.

ngx_immutable es parte de la colección APT NGINX Extras, por lo que puedes instalarlo junto con cualquier módulo, incluyendo Brotli.

Primero, configura el repositorio, luego:

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

Ejemplo: configuración de producción de Magento 2

Siempre que tu tienda funcione en modo de producción, ya has compilado todos los activos. Esta configuración de muestra puede optimizarse a:

location /static/ {
    immutable on;

    # Eliminar la firma de los archivos estáticos que se utiliza para superar la caché del navegador
    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";
}

Cuando se usa junto con ngx_security_headers, se puede simplificar aún más:

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;
    }
}