immutable: NGINX 模块用于设置静态资产的不可变缓存

需要 GetPageSpeed NGINX Extras 订阅的 Pro 计划（或更高版本）。

安装

您可以在任何基于 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，于 2026 年 3 月 20 日发布。

这个小型 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 属性以确保资产可以被公共缓存缓存，这通常是所期望的。

由于 Chromium 浏览器对 immutable 的支持不足，我们还添加了 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 定义使用一年将响应标记为“永不过期”：

要将响应标记为“永不过期”，源服务器发送一个过期日期，约为响应发送时间的一年。HTTP/1.1 服务器不应发送超过一年未来的过期日期。

更多细节请参见这篇文章。

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