Nginx 在 Debian 上的模块加载指南
一 前置知识与目录结构
- 模块类型与差异
- 静态模块：编译进 Nginx 二进制，随服务启动加载，使用简单、稳定，但升级需重编译或替换包。
- 动态模块：以 .so 形式存在，按需加载，升级更灵活；Nginx 自 1.9.11 起支持动态加载。
- Debian 常见目录（APT 安装版）
- 主配置：/etc/nginx/nginx.conf
- 模块可用/已启用：/etc/nginx/modules-available/、/etc/nginx/modules-enabled/
- 站点可用/已启用：/etc/nginx/sites-available/、/etc/nginx/sites-enabled/
- 扩展配置：/etc/nginx/conf.d/；日志：/var/log/nginx/；默认网页根：/var/www/html/ 或 /usr/share/nginx/html/
- 常用命令
- 语法检查：sudo nginx -t
- 热重载：sudo systemctl reload nginx
以上目录与命令适用于通过 APT 安装的 Nginx，便于模块化维护与启用站点/模块。
二 方式一 使用 APT 安装并启用模块
- 更新索引并安装 Nginx
- sudo apt update && sudo apt install nginx
- 安装常见功能模块（按需选择）
- sudo apt install libnginx-mod-http-subs-filter
- sudo apt install libnginx-mod-http-echo
- sudo apt install libnginx-mod-http-brotli-filter（通常与 libnginx-mod-http-brotli-static 配套）
- 启用方式
- 大多数 Debian 打包的动态模块在安装后会在 /usr/lib/nginx/modules/ 生成 .so 文件，并在安装时自动写入到 /etc/nginx/modules-enabled/ 的符号链接，Nginx 启动即自动加载；如未自动启用，可手动创建符号链接：
- 示例：sudo ln -s /usr/lib/nginx/modules/ngx_http_brotli_filter_module.so /etc/nginx/modules-enabled/50-mod-http-brotli.conf
- 验证
- 查看已加载模块：nginx -V 2>&1 | grep --color=auto ‘with-http’
- 检查配置并热重载：sudo nginx -t && sudo systemctl reload nginx
上述包名与启用方式适用于常见功能模块，安装即生效，适合大多数生产环境。
三 方式二 编译并加载第三方动态模块（以 Brotli 为例）
- 准备
- 确认 Nginx 版本：nginx -v
- 安装编译依赖：sudo apt install build-essential libpcre3 libpcre3-dev zlib1g-dev libssl-dev
- 获取源码与模块
- 源码版本需与运行版本一致：wget http://nginx.org/download/nginx-$(nginx -v 2>&1 | awk -F/ ‘{print $2}’).tar.gz
- 解压并进入目录
- 获取 Brotli 模块：git clone --recursive https://github.com/google/ngx_brotli.git
- 编译动态模块（保持与现有编译参数兼容）
- 查看现有参数：nginx -V 2>&1 | grep configure
- 配置并编译：
- ./configure [原有参数] --with-compat --add-dynamic-module=…/ngx_brotli
- make modules
- 安装模块文件
- 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/
- 配置加载
- 新建：sudo nano /etc/nginx/modules-enabled/50-mod-http-brotli.conf
- 写入：
- load_module /usr/share/nginx/modules/ngx_http_brotli_filter_module.so;
- load_module /usr/share/nginx/modules/ngx_http_brotli_static_module.so;
- 在 http 上下文启用功能
- 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;
- 验证与重载
- sudo nginx -t && sudo systemctl reload nginx
- 验证压缩：curl -I -H ‘Accept-Encoding: br’ http://localhost | grep -i content-encoding
该流程适用于需要 第三方模块或自定义功能的场景，关键点在于版本一致与 –with-compat。
四 验证与常见问题处理
- 配置语法与重载
- 语法检查：sudo nginx -t
- 热重载：sudo systemctl reload nginx
- 查看模块与二进制兼容性
- 已编译模块：nginx -V 2>&1 | grep --color=auto ‘with-http’
- 动态模块加载失败或指令未知，优先检查 load_module 是否位于主配置的顶层（main）且 .so 路径正确；第三方模块需与 Nginx 版本严格匹配，否则会出现 module is not binary compatible 错误。
- 共存与重复压缩
- 同时开启 gzip 与 brotli 的动态压缩可能导致“内容编码错误”，推荐：
- 动态压缩二选一，或
- 使用预压缩：brotli_static on; gzip_static on; 并预生成 .br 文件。
- 依赖库缺失
- 例如 Brotli 报缺少 libbrotlienc.so.1：sudo apt install libbrotli-dev
以上步骤可快速定位大多数模块加载问题，确保配置变更安全可控。
