Nginx 动态模块配置指南（以 Brotli 模块为例）

前置要求

Nginx 1.9.11+（推荐 1.19+）
已安装开发工具链：sudo apt install build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev（Debian/Ubuntu）
当前运行的 Nginx 版本号必须与模块编译版本一致

一、标准安装流程

1. 获取 Nginx 版本信息

bash 复制代码

nginx -v
# 示例输出：nginx version: nginx/1.18.0 (Ubuntu)

2. 下载对应版本源码

bash 复制代码

nginx_version=$(nginx -v 2>&1 | awk -F/ '{print $2}')
wget http://nginx.org/download/nginx-${nginx_version}.tar.gz
tar zxvf nginx-${nginx_version}.tar.gz

3. 下载 Brotli 模块源码

bash 复制代码

git clone --recursive https://github.com/google/ngx_brotli.git
cd ngx_brotli && git submodule update --init && cd ..

4. 编译动态模块

bash 复制代码

cd nginx-${nginx_version}
./configure --with-compat --add-dynamic-module=../ngx_brotli
make modules

5. 安装模块

bash 复制代码

sudo cp objs/ngx_http_brotli_filter_module.so /usr/share/nginx/modules/
sudo cp objs/ngx_http_brotli_static_module.so /usr/share/nginx/modules/

6. 加载模块配置

创建 /etc/nginx/modules-enabled/50-mod-http-brotli.conf：

nginx 复制代码

load_module /usr/share/nginx/modules/ngx_http_brotli_filter_module.so;
load_module /usr/share/nginx/modules/ngx_http_brotli_static_module.so;

7. 配置 Brotli 压缩

在 nginx.conf 的 http 上下文中：

nginx 复制代码

brotli on;
brotli_comp_level 6;
brotli_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

8. 验证与重载

bash 复制代码

sudo nginx -t && sudo systemctl reload nginx
curl -I -H 'Accept-Encoding: br' http://localhost | grep -i content-encoding

二、不同场景处理

场景 1：自定义编译参数

解决方案：

bash 复制代码

# 获取当前编译参数
nginx -V 2>&1 | grep configure

# 在新编译时加入原有参数
./configure [原参数] --with-compat --add-dynamic-module=../ngx_brotli

场景 2：多模块依赖

处理方式：

按正确顺序加载模块：

nginx 复制代码

load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_headers_more_filter_module.so;

场景 3：与 Gzip 共存

推荐配置：

nginx 复制代码

gzip on;
brotli on;

# 优先使用 Brotli（现代浏览器）
brotli_static on;
gzip_static on;

三、常见错误与解决方案

错误 1：版本不匹配

log 复制代码

module is not binary compatible

解决方法：

使用 nginx -v 获取确切版本
下载对应版本的 Nginx 源码重新编译

错误 2：模块加载顺序错误

log 复制代码

unknown directive "brotli"

解决方法：

确认 load_module 指令在配置顶部
确保模块文件路径正确

错误 3：缺少依赖库

log 复制代码

error while loading shared libraries: libbrotlienc.so.1

解决方法：

bash 复制代码

# 安装 Brotli 开发库
sudo apt install libbrotli-dev

错误 4：重复压缩配置

log 复制代码

content encoding error

解决方法：

避免同时启用 gzip 和 brotli 的动态压缩
使用预压缩静态文件方案：

nginx 复制代码

brotli_static on;
gzip_static on;

四、高级优化配置

1. 预压缩静态文件

bash 复制代码

# 生成预压缩文件
find /var/www/html -type f -name '*.css' -exec brotli -kf {} \;

2. 调整压缩参数

nginx 复制代码

brotli_window 1m;
brotli_min_length 20;
brotli_buffers 16 8k;

3. 排除特定 User-Agent

nginx 复制代码

map $http_user_agent $no_brotli {
    default          0;
    "~MSIE [4-6]\." 1;
    "~SV1"           1;
}

brotli on;
brotli_bypass $no_brotli;

五、验证方法

1. 命令行测试

bash 复制代码

curl -H 'Accept-Encoding: br' -I http://localhost | grep -i content-encoding

# 验证预压缩文件
curl -H 'Accept-Encoding: br' -I http://localhost/style.css | grep -i vary

2. 浏览器验证

Chrome DevTools：Network → Headers → Response Headers
使用 tools.keycdn.com/brotli-test 在线检测

六、维护建议

使用版本控制系统管理模块文件：

bash 复制代码

# 保存模块版本信息
md5sum /usr/share/nginx/modules/*.so > nginx_modules_checksum.txt

创建更新脚本模板：

bash 复制代码

#!/bin/bash
NGINX_VERSION=$(nginx -v 2>&1 | awk -F/ '{print $2}')
MODULE_DIR="/usr/share/nginx/modules"

# 自动备份旧模块
cp ${MODULE_DIR}/ngx_http_brotli_* ${MODULE_DIR}/backup/

# 编译安装新模块
...