Nginx 中 Location 配置怎么使用 sub_filter 模块动态替换响应页面中的文本-Nginx-PHP中文网

Nginx的sub_filter模块可在响应返回前对文本内容做字符串替换，需配合location使用，且必须关闭gzip、明确Content-Type、启用sub_filter并确保响应为纯文本。

nginx 中 location 配置怎么使用 sub_filter 模块动态替换响应页面中的文本

Nginx 的 sub_filter 模块可用于在响应返回给客户端前，对 HTML（或其他文本类型）内容进行简单字符串替换。它必须配合 location 块使用，且仅对 text/html、text/css、application/javascript 等明确指定的 MIME 类型生效（默认只处理 text/html）。关键前提是：响应体必须是流式可缓存的纯文本，不能是 gzip 压缩后的内容（除非用 sub_filter_once off 配合 gzip off），也不能是 chunked 编码未结束的流。

确保 sub_filter 生效的基本条件

以下配置项缺一不可：

关闭响应压缩：在对应 location 中显式设置 gzip off;，否则 sub_filter 无法处理已压缩的字节流；
明确设置 Content-Type：若上游返回未带 Content-Type 或类型不匹配，需用 sub_filter_types 扩展支持类型，例如：sub_filter_types text/html text/css application/javascript;；
启用 sub_filter：至少配置一对 sub_filter old_string new_string;，且 sub_filter_once off; 可实现全局多次替换（默认只替换第一个匹配）；
location 必须能代理或返回文本响应：通常搭配 proxy_pass 或 alias/root 提供静态 HTML 文件。

典型 location + sub_filter 配置示例

以下是一个将后端返回页面中所有 http://old.example.com 替换为 https://new.example.com 的完整 location 示例：

location /app/ {
    proxy_pass https://backend-server/;
    proxy_set_header Host $host;
<pre class="brush:php;toolbar:false;"># 关键：关闭压缩，否则 sub_filter 不生效
gzip off;

# 允许对 HTML 和 JS 中的链接做替换
sub_filter_types text/html application/javascript;
sub_filter 'http://old.example.com' 'https://new.example.com';
sub_filter 'http://old-api.example.com' 'https://new-api.example.com';
sub_filter_once off;

# 可选：修正响应头，避免浏览器缓存旧内容
sub_filter_last_modified on;
add_header Last-Modified "";

}

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

常见失效原因与调试方法

如果替换没生效，按顺序检查：

查看响应头：用 curl -I 确认 Content-Encoding: gzip 是否存在 —— 存在则必须加 gzip off;；
确认 Content-Type：用 curl -s -D - http://... | head -n 20 查看实际返回的 Content-Type，确保它在 sub_filter_types 列表中；
检查大小写与空格：sub_filter 默认区分大小写且匹配原始字节，"Old" ≠ "old"，前后空格、换行符都需完全一致；
避免正则陷阱：sub_filter 不支持正则表达式，只做固定字符串替换；如需更灵活处理，应改用 OpenResty 或应用层解决。