Перейти к содержанию

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

Установка

Вы можете установить этот модуль в любой дистрибутив, основанный на 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
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.6, выпущенный 14 февраля 2026 года.

Coverity Scan Buy Me a Coffee

Этот небольшой модуль 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
Expires: Thu, 31 Dec 2037 23:55:55 GMT
...

Чем это отличается от 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;
    }
}

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-immutable.