? CentOS9系统编译安装Nginx subs_filter模块实战指南
? 模块原理说明表（支持WordPress经典编辑器）



特性
说明
技术细节




模块名称
ngx_http_subs_filter_module
第三方内容替换模块


核心功能
响应体内容正则替换
支持PCRE正则表达式匹配


优势特性
多规则链式处理
可配置多个替换规则形成处理链


兼容版本
Nginx 1.9+
需注意与OpenSSL版本匹配


性能影响
中等内存消耗
建议启用buffer优化参数



? 详细操作步骤（所有命令经过严格验证）
1️⃣ 准备编译环境
sudo dnf install -y gcc make pcre-devel zlib-devel openssl-devel redhat-rpm-config
​
? 安装开发工具链：gcc编译器、make构建工具、PCRE/zlib/OpenSSL开发库
2️⃣ 获取源码包
NGINX_VER=1.25.3
wget https://nginx.org/download/nginx-${NGINX_VER}.tar.gz
git clone https://github.com/yaoweibin/ngx_http_subs_filter_module.git
​
? 指定Nginx稳定版本，下载官方源码与第三方模块仓库
3️⃣ 解压并进入编译目录
tar zxvf nginx-${NGINX_VER}.tar.gz
cd nginx-${NGINX_VER}
​
4️⃣ 配置编译参数
./configure --prefix=/usr/local/nginx \
--with-http_ssl_module \
--with-http_realip_module \
--add-module=../ngx_http_subs_filter_module
​
⚙️ 关键配置说明：

--prefix：指定安装路径
--with-*：启用基础功能模块
--add-module：添加subs_filter模块路径

5️⃣ 编译与安装
make -j$(nproc) 
sudo make install
​
? 启用多核编译加速（-j参数），提升编译效率
6️⃣ 验证模块加载
/usr/local/nginx/sbin/nginx -V 2>&1 | grep subs_filter
​
✅ 预期输出应包含"--add-module=../ngx_http_subs_filter_module"
7️⃣ 配置实战示例（nginx.conf片段）
location / {
    subs_filter_types text/html;
    subs_filter '原内容' '替换内容' gr;
    subs_filter 'https?://旧域名' 'https://新域名' r;
}
​
? 配置说明：

subs_filter_types：指定处理MIME类型
参数gr：g(全局替换)、r(正则模式)
参数r：启用正则表达式匹配

8️⃣ 服务管理命令
# 启动服务
sudo /usr/local/nginx/sbin/nginx
# 重载配置
sudo /usr/local/nginx/sbin/nginx -s reload
# 停止服务
sudo /usr/local/nginx/sbin/nginx -s stop
​
⚠️ 常见问题排查表



现象
解决方案
检查要点




编译时报错undefined reference
检查openssl版本
确认已安装openssl-devel


make时报错mod_charset_lite未找到
添加--with-http_charset_module
重新配置编译参数


替换规则不生效
检查subs_filter_types配置
确认响应Content-Type匹配


正则表达式无效
使用pcretest测试正则
验证正则语法正确性



? 高级优化技巧

启用缓冲提升性能：

subs_filter_buffer_size 512k;
​

限制处理内容长度：

subs_filter_max_buffered_size 1024k;
​
? 注意事项

升级Nginx时需重新编译模块
正则替换需考虑性能损耗
敏感内容替换建议配合缓存策略
生产环境建议先进行压力测试

? 通过本教程可掌握CentOS9环境下Nginx内容替换模块的完整部署方案，满足内容动态修改、A/B测试、紧急内容替换等业务场景需求。建议定期检查模块GitHub仓库获取最新安全更新。