phpEnv环境下配置Nginx缓存清理模块完整指南

一、为什么需要Nginx缓存清理模块

1.1 缓存带来的便利与烦恼

在PHP本地开发和线上部署中，Nginx反向代理缓存是一个非常实用的功能。它能够将后端PHP-FPM或Apache处理好的页面结果缓存起来，下次有相同的请求进来时，Nginx直接返回缓存内容，不再转发给后端服务。这样做的好处显而易见——响应速度大幅提升，后端服务器的压力也显著降低。

但缓存也带来了一个让人头疼的问题：内容更新后，缓存还是旧的。比如你修改了一个CSS文件或者更新了数据库里的内容，刷新浏览器却发现页面没有任何变化，原因就是Nginx还在返回之前的缓存。这时候你就需要手动去删除缓存目录下的文件，或者等待缓存自然过期。当项目文件多、缓存层级深的时候，手动找文件删除是一件极其低效的事情。

1.2 ngx_cache_purge模块的作用

ngx_cache_purge是一个Nginx的第三方模块，专门用来解决这个问题。它的核心功能是提供一个HTTP接口，让你通过访问一个特定的URL就能动态清除指定的缓存内容。比如你访问http://www.pcppp.com/purge/about.html，Nginx就会找到about.html对应的缓存文件并删除它，后续请求就会重新生成缓存。

这个模块由Nginx社区维护，稳定性有保障，被广泛应用于需要灵活管理缓存的场景。在phpEnv这样的集成环境中，Nginx默认并没有编译这个模块，所以我们需要手动将它编译进去。

二、准备工作：获取模块源码与确认环境

2.1 确认phpEnv中Nginx的版本

在动手之前，第一步是搞清楚你当前phpEnv自带的Nginx是什么版本。版本号非常重要，因为编译模块时需要和Nginx源码版本严格对应，否则编译出来的模块可能无法加载，甚至导致Nginx无法启动。

打开phpEnv安装目录，找到Nginx文件夹。如果你不确定版本号，还有一个更可靠的方法：打开命令行，进入phpEnv的Nginx目录，执行以下命令：

cd D:\phpEnv\nginx
nginx -V

注意这里是大写的V，小写v只显示版本号，大写V会显示所有编译参数。执行后你会看到类似nginx version: nginx/1.24.0的输出，同时还会列出一大串configure arguments。把这些信息全部复制保存下来，后面编译时会用到。

2.2 下载ngx_cache_purge模块源码

确认版本后，去GitHub搜索ngx_cache_purge，找到官方的仓库（通常是FRiCKLE/ngx_cache_purge）。在Releases页面查看模块的版本兼容性说明，选择一个和你Nginx版本匹配的模块版本。一般来说，模块对Nginx版本的要求比较宽松，但最好选择最新的稳定版。

下载完成后，将压缩包解压到一个你方便找到的路径。建议放在phpEnv安装目录下的一个临时文件夹中，比如D:\phpEnv\tmp\ngx_cache_purge。解压后确认目录结构，确保目录下有config文件和ngx_cache_purge_module.c等源文件，这说明解压正确。

2.3 准备编译环境

phpEnv运行在Windows系统上，而Nginx的模块编译需要类Unix的编译工具链。你有两个选择：一是安装MinGW或Cygwin，提供gcc等编译工具；二是使用MSYS2环境。这里推荐使用MSYS2，因为它对Windows的兼容性更好，而且可以方便地安装依赖。

安装好MSYS2后，打开MSYS2终端，确保gcc、make、pcre、zlib、openssl等开发库都已经安装。这些库在编译Nginx时是必需的。如果缺少任何一个，编译过程都会报错中断。

三、重新编译Nginx添加模块

3.1 获取Nginx源码

编译模块需要Nginx的完整源码，而不仅仅是phpEnv自带的二进制文件。去Nginx官网下载和你当前版本完全一致的源码包（比如1.24.0），解压到D:\phpEnv\tmp\nginx-1.24.0。

将之前保存的nginx -V输出的编译参数拿出来，这些参数是phpEnv当初编译Nginx时使用的配置。我们要做的是在这些参数的基础上，追加--add-module参数来加入purge模块。

3.2 执行编译配置

在MSYS2终端中，进入Nginx源码目录，执行./configure命令。这里要特别注意，参数必须和原有参数保持一致，只追加模块路径。一个典型的配置命令如下：

cd /d/phpEnv/tmp/nginx-1.24.0
./configure \
  --prefix=/d/phpEnv/nginx \
  --with-http_ssl_module \
  --with-http_v2_module \
  --with-http_gzip_static_module \
  --with-pcre \
  --with-zlib=/d/phpEnv/tmp/zlib \
  --with-openssl=/d/phpEnv/tmp/openssl \
  --add-module=/d/phpEnv/tmp/ngx_cache_purge

注意把路径替换成你自己的实际路径。Windows路径在MSYS2中要写成/d/phpEnv/...这样的形式。执行后如果看到Configuration summary输出，说明配置成功。

3.3 编译与替换

配置成功后，执行make命令开始编译。这个过程可能需要几分钟，取决于你的电脑性能。编译完成后，千万不要执行make install，因为那样会覆盖整个Nginx安装目录，包括你现有的配置文件。

我们需要的只是编译产物。进入objs目录，你会看到一个新编译出来的nginx.exe文件。先停止phpEnv中的所有服务，然后将这个nginx.exe复制到D:\phpEnv\nginx\`目录下，替换原有的文件。建议在替换前先备份原来的nginx.exe`，万一出问题可以恢复。

替换完成后，启动phpEnv的Nginx服务。在命令行中执行nginx -V，如果输出的configure arguments中包含了--add-module=/d/phpEnv/tmp/ngx_cache_purge，说明模块已经成功编译进去了。

四、配置Nginx缓存规则

4.1 定义缓存路径

模块加载成功后，接下来要在Nginx配置文件中定义缓存的存储路径和相关参数。打开phpEnv的Nginx配置文件，通常位于D:\phpEnv\nginx\conf\nginx.conf。

在http块中添加以下配置：

proxy_cache_path D:/phpEnv/nginx/cache levels=1:2 keys_zone=cache_zone:10m inactive=1d max_size=1g;

这行配置的含义需要逐个字理解。levels=1:2表示缓存目录采用两级结构，第一级1个字符，第二级2个字符，这样可以避免单目录下文件过多导致性能下降。keys_zone=cache_zone:10m定义了一个名为cache_zone的共享内存区域，大小10MB，用来存储缓存键和元信息。inactive=1d表示如果缓存内容在1天内没有被访问，就会被自动清理。max_size=1g限制缓存总大小不超过1GB，防止磁盘被撑满。

4.2 配置缓存清理接口

在server块中，我们需要添加一个专门用于清理缓存的location规则。这个接口必须做好权限控制，否则任何人都能清除你的缓存，那将是一个严重的安全漏洞。

location ~ /purge(/.*) {
    allow 127.0.0.1;
    allow ::1;
    deny all;
    
    proxy_cache_purge cache_zone $host$1$is_args$args;
}

这段配置的意思是：当访问路径匹配/purge/xxx时，只允许来自本机的请求（127.0.0.1和IPv6的::1），其他所有IP都会被拒绝。proxy_cache_purge指令调用模块功能，指定使用cache_zone这个缓存区，缓存键由$host$1$is_args$args组成。这里的$1是正则匹配中捕获的/purge/后面的路径部分。

4.3 配置正常请求的缓存策略

在同一个server块中，为普通的请求启用缓存：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    
    proxy_cache cache_zone;
    proxy_cache_key $host$uri$is_args$args;
    proxy_cache_valid 200 302 1h;
    proxy_cache_valid 404 1m;
    proxy_cache_valid any 10m;
    
    add_header X-Cache-Status $upstream_cache_status;
}

这里有几个关键点。proxy_pass指向你的后端服务地址，比如PHP内置服务器运行的8080端口。proxy_cache_key定义了缓存的唯一标识，它必须和清理时的键规则完全一致，否则清理时找不到对应的缓存。proxy_cache_valid为不同的HTTP状态码设置了不同的缓存时间。add_header添加了一个自定义响应头，方便我们在浏览器中直接查看缓存命中状态。

五、测试缓存清理功能

5.1 验证缓存是否生效

配置完成后，重启Nginx使配置生效。首先访问一个普通的页面，比如http://www.pcppp.com/test.html。打开浏览器的开发者工具，查看响应头中的X-Cache-Status字段。

• 如果是MISS，说明这是第一次访问，缓存还没有生成。
• 刷新页面后，如果变成HIT，说明缓存已经生效，Nginx直接返回了缓存内容。
• 如果始终是BYPASS，说明缓存被绕过了，需要检查配置。

5.2 测试动态清理

缓存生效后，访问清理接口：http://www.pcppp.com/purge/test.html。如果返回200 OK或者一个确认页面，说明缓存清除成功。此时再次访问http://www.pcppp.com/test.html，X-Cache-Status应该重新变为MISS，表示缓存已经被清除，Nginx重新向后端请求了内容。

你还可以测试带参数的URL。比如访问http://www.pcppp.com/news.php?id=5，然后清理http://www.pcppp.com/purge/news.php?id=5。只要proxy_cache_key中包含了$is_args$args，带参数的缓存也能被正确清理。

5.3 测试权限控制

从另一台设备或者关闭代理直接访问http://www.pcppp.com/purge/test.html，应该返回403 Forbidden。这证明我们的allow和deny规则生效了，外部网络无法调用清理接口。

六、常见问题与排查方法

6.1 清理接口返回404

这是最常见的问题之一。返回404通常有两个原因。一是proxy_cache_purge后面指定的缓存区名称和keys_zone定义的不一致。比如你定义了keys_zone=my_cache:10m，但purge指令中写的是proxy_cache_purge cache_zone，这样Nginx找不到对应的缓存区，就会返回404。二是proxy_cache_key的规则和清理时的键不匹配。比如缓存键用的是$host$uri，但清理时模块生成的键是$host$1，两者不一致，导致找不到缓存文件。

6.2 清理返回403

如果你从本机访问清理接口却收到了403，检查allow指令中是否包含了你的访问IP。有时候你以为自己是从127.0.0.1访问的，但实际上可能因为代理、VPN或者IPv6优先等原因，请求来自其他IP。可以临时将allow规则改为allow all来测试，确认是权限问题后再收紧规则。

6.3 Nginx启动失败

替换nginx.exe后Nginx无法启动，最常见的原因是编译参数不匹配。比如原有的Nginx使用了--with-openssl指定了特定版本的OpenSSL，而你编译时没有指定或者路径不对，就会导致动态链接库缺失。此时可以查看Windows事件查看器中的应用程序日志，或者直接在命令行运行nginx查看报错信息。

6.4 缓存始终不生效

如果X-Cache-Status始终是MISS，首先检查proxy_cache指令是否在正确的location块中。其次检查后端响应中是否包含Set-Cookie头或者Cache-Control: no-cache之类的指令，这些都会导致Nginx默认不缓存。可以在配置中添加proxy_ignore_headers Set-Cookie Cache-Control;来强制缓存。

七、生产环境注意事项

7.1 安全加固

在本地开发环境中，我们只允许127.0.0.1访问清理接口就够了。但在生产服务器上，你可能需要从内部网络或者CI/CD流水线中调用清理接口。这时应该使用更精细的IP白名单，或者增加HTTP Basic Auth认证。千万不要把清理接口暴露到公网上。

7.2 缓存键的设计

proxy_cache_key的设计直接影响缓存的命中率和清理的准确性。如果网站同时支持HTTP和HTTPS，建议将$scheme也加入缓存键，否则可能出现HTTP和HTTPS内容混用的问题。如果网站有多个子域，且内容不同，确保$host在键中。设计好键规则后，清理接口的URL构造必须和键规则严格对应。

7.3 多服务器场景

如果你有多台Nginx服务器做负载均衡，每台服务器上都有独立的缓存。这时候调用一台机器的purge接口只能清除那台机器的缓存。可以考虑使用purge模块的purge_all方式，或者通过脚本批量调用所有节点的清理接口。

通过以上步骤，你应该已经成功在phpEnv的Nginx中配置好了缓存清理模块。现在你可以随时通过访问特定的URL来动态清除缓存，再也不用手动去翻找和删除缓存文件了。这个功能在频繁修改代码的前端联调阶段尤其有用，能极大提升开发效率。

phpEnvNginx缓存清理动态清除缓存ngx_cache_purge修改时间：2026-08-21 01:14:00