cache-purge：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-cache-purge

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-cache-purge

通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用模块：

load_module modules/ngx_http_cache_purge_module.so;

本文档描述的是 nginx-module-cache-purge v2.6.0 发布于 2026 年 8 月 23 日。

---

使用 HTTP PURGE 请求有选择地清除 NGINX 的 FastCGI、proxy、SCGI 和 uWSGI 缓存中的内容——无需文件系统技巧，无需权限烦恼。

这是 NGINX Plus 中提供的功能，但 ngx_cache_purge 将其带到了开源 NGINX 中。

主要特性

• 同位置清除 — 直接在现有缓存位置添加 PURGE 支持，无需额外的 location 块
• 通配符清除 — 使用 * 通过单个请求清除多个缓存条目
• 缓存标签 / 替代键 — 仅使缓存响应标签与受信任的 PURGE 模式匹配的对象失效
• 批量清除 — 使用 purge_all 一次清除所有缓存内容
• 基于 IP 的访问控制 — 限制谁可以发出清除请求
• 缓存键方法替换 — 即使 $request_method 在您的缓存键中，也能清除 GET 缓存的内容
• 可配置的响应格式 — 以 HTML、JSON、XML 或纯文本格式获取清除结果
• 所有缓存类型 — 适用于 FastCGI、proxy、SCGI 和 uWSGI

快速开始

为任何缓存位置添加 PURGE 支持：

http {
    proxy_cache_path /var/cache/nginx keys_zone=my_cache:10m max_size=1g;

    server {
        location / {
            proxy_pass        http://127.0.0.1:8000;
            proxy_cache       my_cache;
            proxy_cache_key   "$scheme$host$request_uri";
            proxy_cache_purge PURGE from 127.0.0.1;
        }
    }
}

清除一个缓存页面：

curl -X PURGE https://example.com/page-to-purge

就是这样。无需单独的 /purge 位置，无需管理文件系统权限。

配置指令

同位置语法（推荐）

直接在提供缓存内容的位置启用清除功能。

fastcgi_cache_purge

• 语法：fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
• 默认值：none
• 上下文：http、server、location

proxy_cache_purge

• 语法：proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
• 默认值：none
• 上下文：http、server、location

scgi_cache_purge

• 语法：scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
• 默认值：none
• 上下文：http、server、location

uwsgi_cache_purge

• 语法：uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
• 默认值：none
• 上下文：http、server、location

分离位置语法

使用专门的位置来处理清除请求。当您需要为清除操作设置不同的访问规则时，这很有用。

fastcgi_cache_purge

• 语法：fastcgi_cache_purge zone_name key
• 上下文：location

proxy_cache_purge

• 语法：proxy_cache_purge zone_name key
• 上下文：location

scgi_cache_purge

• 语法：scgi_cache_purge zone_name key
• 上下文：location

uwsgi_cache_purge

• 语法：uwsgi_cache_purge zone_name key
• 上下文：location

响应格式

cache_purge_response_type

• 语法：cache_purge_response_type html|json|xml|text
• 默认值：html
• 上下文：http、server、location

使用 JSON 响应的示例：

location / {
    proxy_pass        http://backend;
    proxy_cache       my_cache;
    proxy_cache_key   "$uri$is_args$args";
    proxy_cache_purge PURGE from 127.0.0.1;

    cache_purge_response_type json;
}

{"Key": "httplocalhost/"}

缓存键方法替换

当 $request_method 是您的缓存键的一部分时，清除请求会生成不同的键（PURGE 与 GET），因此无法找到缓存条目。以下指令可以解决这个问题：

*_cache_purge_key_method

• 语法：fastcgi_cache_purge_key_method <method> [<method> ...]
• 上下文：http、server、location

适用于所有缓存类型：fastcgi_cache_purge_key_method、proxy_cache_purge_key_method、scgi_cache_purge_key_method、uwsgi_cache_purge_key_method。

location ~ \.php$ {
    fastcgi_cache           WORDPRESS;
    fastcgi_cache_key       "$scheme$request_method$host$request_uri";
    fastcgi_cache_purge     PURGE from 127.0.0.1;
    fastcgi_cache_purge_key_method GET;  # 在键查找中将 PURGE 替换为 GET
}

您可以指定多个方法：

fastcgi_cache_purge_key_method GET HEAD;

WordPress 集成

FastCGI 缓存 + 清除

一个完整的 WordPress 设置，包含缓存和自动清除支持：

http {
    fastcgi_cache_path /var/cache/nginx levels=1:2
        keys_zone=WORDPRESS:100m max_size=1g
        inactive=60m use_temp_path=off;
    fastcgi_cache_key "$scheme$host$request_uri";

    server {
        listen 80;
        server_name example.com;
        root /var/www/wordpress;
        index index.php;

        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|webp|avif)$ {
            expires max;
            log_not_found off;
        }

        location / {
            try_files $uri $uri/ /index.php?$args;
            fastcgi_cache_purge PURGE from 127.0.0.1;
        }

        location ~ \.php$ {
            try_files $uri =404;
            fastcgi_pass unix:/run/php-fpm/www.sock;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;

            fastcgi_cache WORDPRESS;
            fastcgi_cache_valid 200 60m;
            fastcgi_cache_use_stale error timeout updating;
            fastcgi_cache_lock on;
            fastcgi_cache_purge PURGE from 127.0.0.1;

            add_header X-Cache-Status $upstream_cache_status always;
        }
    }
}

为什么在两个位置都使用 fastcgi_cache_purge？ 根 URL / 是一个特殊情况。当 try_files 检查 $uri/ 时，它会找到文档根目录。对于 GET 请求，index 指令会路由到 index.php——但对于 PURGE 请求，index 不适用，NGINX 会停在 location /。在那里添加 fastcgi_cache_purge 可以确保 PURGE / 正常工作。

Proxy Cache Purge 插件

安装 Proxy Cache Purge 插件，以便在内容更新时自动清除缓存：

wp plugin install varnish-http-purge --activate
wp option update vhp_varnish_ip '127.0.0.1'

该插件会在文章、评论或页面被修改时向 NGINX 发送 PURGE 请求——无需手动管理缓存。

缓存键最佳实践

保持简单——避免在键中使用 $request_method

## 推荐
fastcgi_cache_key "$scheme$host$request_uri";

## 避免——清除请求无法匹配缓存的 GET 条目
fastcgi_cache_key "$scheme$request_method$host$request_uri";

如果必须包含 $request_method，请使用 *_cache_purge_key_method GET 来修复清除键查找。

通配符清除

通过追加 * 来清除匹配模式的多条条目：

curl -X PURGE https://example.com/blog/*

星号必须是最后一个字符。为此，$uri 必须位于缓存键的末尾。

缓存标签 / 替代键

cache_purge_tags 将缓存的 upstream 响应中存储的标签头与授权的 PURGE 请求上的正则表达式头连接起来：

location / {
    proxy_pass         http://backend;
    proxy_cache        app_cache;
    proxy_cache_key    "$scheme$host$request_uri";

    proxy_cache_purge  PURGE from 127.0.0.1;
    cache_purge_tags   X-Magento-Tags X-Magento-Tags-Pattern;
}

• 语法：cache_purge_tags <cached-response-header> <purge-pattern-header>
• 默认值：off
• 上下文：http、server、location

对于 Magento Open Source 和 Adobe Commerce，无需更改应用程序。Magento 已经将 X-Magento-Tags 添加到可缓存的响应中，并发送带有 X-Magento-Tags-Pattern 的受信任 localhost PURGE 请求。该模块扫描相同的缓存区域，仅删除匹配的对象。对于该请求，标签模式优先于精确键、通配符和 purge_all 行为。

响应标签头可以使用 proxy_hide_header 对客户端隐藏。它仍然保留在 NGINX 的磁盘缓存元数据中，用于失效操作。无效的正则表达式返回 HTTP 400；有效但无匹配的模式返回 HTTP 200，与 Magento 生成的 Varnish VCL 一致。

标签失效仅在 PURGE 到达时扫描缓存的头元数据。正常的缓存命中不会产生标签索引开销，但清除时间会随着缓存区域中文件数量的增加而增长。这用立即删除匹配的 NGINX 对象来换取 Varnish 的持久化封禁列表。

WordPress 缓存标签集成可以使用相同的指令及其头名称：

cache_purge_tags X-Cache-Tags X-Cache-Tags-Pattern;

批量清除

一次清除所有缓存文件：

proxy_cache_purge PURGE purge_all from 127.0.0.1;

对于大型缓存或慢速存储，这可能会很慢。为获得最佳性能，请使用 RAM 支持的缓存路径。

基于 IP 的访问控制

将清除请求限制为受信任的来源：

fastcgi_cache_purge PURGE from 127.0.0.1 192.168.1.0/24;

故障排除

响应	原因	修复
405 Not Allowed	PURGE 命中了没有 *_cache_purge 的位置	在所有相关位置添加 *_cache_purge
412 Precondition Failed	未找到缓存条目（从未缓存、已过期或键不匹配）	检查缓存键——查找 $request_method 问题
403 Forbidden	客户端 IP 不在 from 列表中	将您的 IP 添加到 from
200 OK 但缓存仍然存在	缓存键中的 $request_method 导致键不匹配	从键中移除 $request_method，或添加 *_cache_purge_key_method GET

gzip_vary 交互：启用 gzip_vary 可能会干扰缓存清除。如果您遇到不一致的清除行为，请在缓存位置内禁用 gzip_vary。

测试

ngx_cache_purge 包含一个基于 Test::Nginx 的测试套件：

prove

另请参阅

• 使用 NGINX Cache Purge 为 WordPress 加速 — 完整设置指南
• NGINX Proxy Cache 与微缓存 — proxy 缓存基础知识
• NGINX fastcgi_cache_purge 文档 — NGINX Plus 参考