如何配置Nginx rewrite规则，读取按URL哈希拆分存储的静态HTML缓存文件

配置前提 #

你需要确保Nginx已安装ngx_http_set_misc_module扩展模块，主流第三方Nginx发行版（如OpenResty）默认已内置该模块，源码编译的Nginx可自行添加该模块编译即可。

完整Nginx配置示例 #

server {
    listen 80;
    server_name 替换为你的站点域名;
    root 替换为你的站点根目录路径;
    index index.php index.html;

    # 静态缓存根目录，替换为你实际存储缓存文件的目录
    set $cache_root /www/cms/cache/html;
    # 和CMS保持一致，用请求URI作为哈希计算的原始值
    set $cache_key $request_uri;
    # 计算URI的MD5哈希值
    set_md5 $cache_md5 $cache_key;

    # 按规则拆分哈希拼接为缓存文件路径：前3位为目录，剩余部分为文件名
    set $cache_file "$cache_root/${cache_md5:0:3}/${cache_md5:3}";

    # 仅GET/HEAD请求走静态缓存逻辑，POST等动态请求直接交给后端处理
    if ($request_method !~ ^(GET|HEAD)$) {
        set $cache_file "";
    }

    # 优先查找缓存文件，不存在则回源到PHP后端
    try_files $cache_file @php_backend;

    # PHP后端处理逻辑，缓存不存在或动态请求时走这里
    location @php_backend {
        # 替换为你实际的PHP-FPM监听地址
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root/index.php;
        include fastcgi_params;
    }

    # 原有静态资源处理规则，按需保留
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|webp)$ {
        expires 365d;
        add_header Cache-Control "public, immutable";
        log_not_found off;
    }
}

常见调整说明 #

• 如果你要更换哈希算法（比如替换为SHA1），仅需将配置中的set_md5改为set_sha1，同时同步修改CMS端的哈希生成规则即可，路径拆分逻辑无需改动。
• 如果你的CMS生成缓存时自动加了.html后缀，将$cache_file的拼接规则改为"$cache_root/${cache_md5:0:3}/${cache_md5:3}.html"即可。
• 如果需要忽略URL的查询参数做缓存（比如/article/1?utm=xxx和/article/1命中同一份缓存），将$cache_key的取值从$request_uri改为$uri即可，要确保和CMS计算哈希的原始值完全一致。
• 可自行添加add_header X-Static-Cache HIT;之类的响应头到缓存命中逻辑，方便调试确认是否走了静态缓存。

内容的提问来源于stack exchange，提问作者bernhardh