immutable: NGINX модуль для установки неизменяемого кэширования статических ресурсов

Требует подписку Pro плана (или выше) на GetPageSpeed NGINX Extras.

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и 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

Включите модуль, добавив следующее в начало файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_immutable_module.so;

Этот документ описывает nginx-module-immutable v0.0.7, выпущенный 20 марта 2026 года.

Этот небольшой модуль NGINX может помочь улучшить кэширование ваших публичных статических ресурсов, устанавливая срок действия в далеком будущем с атрибутом immutable.

Целевая аудитория

Веб-сайты и фреймворки, которые полагаются на паттерн кэширования:

статические ресурсы включают версии/хэши в своих URL, при этом никогда не изменяя ресурсы
при необходимости обновляют ресурсы на более новые версии с новыми номерами версий/хэшами, чтобы их URL были различными

Популярные фреймворки, использующие кэширование:

Magento 2
Добавьте свои здесь!

Синопсис

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

это приведет к следующему HTTP заголовку:

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

Примечание: Клиенты HTTP/1.0 получают заголовок Expires: Thu, 31 Dec 2037 23:55:55 GMT вместо Cache-Control.

Как это отличается от expires max;:

Устанавливает атрибут immutable, например, Cache-Control: public,max-age=31536000,immutable для улучшенного кэширования. Это 1 год, а не 10 лет, смотрите почему ниже.
Отправляет Expires только тогда, когда это действительно необходимо, например, когда клиент запрашивает ресурсы через HTTP/1.0
Устанавливает атрибут public, чтобы гарантировать, что ресурсы могут кэшироваться публичными кэшами, что обычно является желаемым.

Из-за недостаточной поддержки immutable в браузерах на основе Chromium, мы также добавляем stale-while-revalidate=31536000,stale-if-error=31536000, что помогает улучшить коэффициент попадания в кэш в крайних случаях. Использование этих директив позволяет обслуживать кэшированные ответы за пределами их срока действия, который в случае неизменяемых ресурсов является вечным.

Таким образом, в большинстве случаев immutable on; может использоваться как лучшая альтернатива expires max; для реализации паттерна кэширования.

Директивы

immutable

Синтаксис: immutable on | off;

По умолчанию: immutable off;

Контекст: http, server, location

Включает или отключает заголовки неизменяемого кэширования для данного местоположения.

immutable_cache_status

Синтаксис: immutable_cache_status on | off;

По умолчанию: immutable_cache_status off;

Контекст: http, server, location

Включает заголовок RFC 9211 Cache-Status для отладки и наблюдаемости. Когда включен, ответы включают:

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

Этот заголовок помогает отлаживать поведение кэширования в многоуровневых архитектурах кэширования (NGINX -> CDN -> Браузер). Каждый уровень кэша может добавлять свой собственный статус, создавая цепочку, такую как:

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

Пример конфигурации:

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

immutable_types

Синтаксис: immutable_types mime-type ...;

По умолчанию: (нет - применяется ко всем типам, если не указано)

Контекст: http, server, location

Ограничивает заголовки неизменяемого кэширования для ответов с указанными MIME-типами. Если не указано, неизменяемые заголовки применяются ко всем ответам. Это похоже на то, как работает gzip_types для модуля gzip.

Пример конфигурации:

location /static/ {
    immutable on;
    # Применять неизменяемые заголовки только к файлам JavaScript и CSS
    immutable_types application/javascript text/css;
}

Почему 31536000 секунд (1 год?)

RFC определяет использование одного года, чтобы сделать ответ "никогда не истекающим":

Чтобы отметить ответ как "никогда не истекающий", сервер-источник отправляет дату Expires примерно через год с момента отправки ответа. HTTP/1.1 серверы НЕ ДОЛЖНЫ отправлять даты Expires более чем на год вперед.

Более подробная информация в статье.

Пакеты для Ubuntu и Debian

Установить пакет модуля для этих операционных систем легко.

ngx_immutable является частью коллекции APT NGINX Extras, поэтому вы можете установить его вместе с любыми модулями, включая Brotli.

Сначала настройте репозиторий, затем:

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

Пример: Конфигурация для продакшена Magento 2

При условии, что ваш магазин работает в режиме продакшена, вы уже скомпилировали все ресурсы. Эта примерная конфигурация может быть оптимизирована до:

location /static/ {
    immutable on;

    # Удалить подпись статических файлов, которая используется для обхода кэша браузера
    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";
}

Когда используется вместе с ngx_security_headers, это можно упростить еще больше:

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