proxy_cache_purge模块是实现Nginx缓存精准清理的最直接方案，需手动编译启用，配置时须确保缓存key与purge请求URI严格匹配，并在location中显式声明PURGE方法。
要实现 Nginx 缓存的一键精准清理，proxy_cache_purge 是最直接有效的方案，但它不是默认内置模块，需手动编译启用，且配置稍有不慎就会导致 purge 失效或误删。
确认并启用 proxy_cache_purge 模块
Nginx 官方主线版本（1.17.9+）已将 ngx_http_proxy_cache_purge_module 合入源码，但大多数发行版预编译包（如 Ubuntu apt、CentOS yum）并未启用它。需检查是否支持：
执行命令验证：
nginx -V 2>&1 | grep -o with-http_stub_status_module.*purge
若无输出，说明未编译该模块。此时有两种选择：
- 从源码重新编译 Nginx，添加
--add-dynamic-module=../nginx-modules/ngx_http_proxy_cache_purge_module（推荐使用官方维护的 nginx-modules/ngx_http_proxy_cache_purge） - 使用 OpenResty 或 Tengine 等已集成该模块的发行版（OpenResty 1.21.4.1+ 默认支持）
基础缓存与 purge 配置示例
以下是最小可用配置片段，关键点在于：缓存键（proxy_cache_key）必须与 purge 请求的 URI + 参数严格匹配；purge 指令必须在 location 块中显式声明，且仅响应 PURGE 方法。
proxy_cache_path /var/cache/nginx/proxy_cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;
<p>server {
listen 80;
server_name example.com;</p><pre class="brush:php;toolbar:false;">location / {
proxy_pass http://backend;
proxy_cache my_cache;
proxy_cache_key "$scheme$request_method$host$request_uri";
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
add_header X-Cache-Status $upstream_cache_status;
}
location ~ /purge(/.*) {
allow 127.0.0.1; # 仅允许本地或可信 IP
allow 192.168.1.0/24;
deny all;
proxy_cache_purge my_cache "$scheme$request_method$host$1";
}
}
注意：purge location 中的 $1 对应正则捕获的路径，确保它与上游缓存 key 中的路径部分完全一致；若缓存 key 包含参数（如 $args），purge 时也必须带相同参数，否则无法命中。
精准清理的三种常用场景与写法
purge 不是模糊删除，而是按 key 精确匹配。实际中需根据业务需求构造对应 key：
-
清除单个 URL（不带参数）：
curl -X PURGE http://example.com/purge/path/to/page -
清除带查询参数的 URL：若缓存 key 包含
$args，则请求必须完整携带，例如：curl -X PURGE "http://example.com/purge/article?id=123&lang=zh" -
批量清除某路径下所有资源（需配合 map 或 Lua）：原生 purge 不支持通配符。常见做法是用
map将路径前缀映射为统一 key，或借助 OpenResty 的 Lua 脚本遍历缓存目录（不推荐直接操作文件系统）
调试与排错要点
purge 返回 204 表示成功，404 表示未命中缓存，405 表示方法不被允许，403 表示权限拒绝。常见问题排查方向：
- 检查 Nginx error log，确认是否报
no cache entry或cache zone not found - 确认 purge 请求的 URI 和缓存 key 计算结果是否一致（可临时加
log_format打印$scheme$request_method$host$request_uri） - 确保 purge location 未被其他 rewrite 或 proxy_pass 指令覆盖；
proxy_cache_purge必须在最终生效的 location 块中 - 若使用 HTTPS，注意
$scheme是https，缓存 key 和 purge key 必须保持协议一致
