Nginx在Debian上的模块加载指南

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
    以上步骤可快速定位大多数模块加载问题，确保配置变更安全可控。