在 nginx 中配置动态模块，核心做法是编译时指定 --with-compat 参数生成兼容的动态库文件（.so），然后在配置文件中使用 load_module 指令加载该文件。这样做的好处是不需要重新编译整个 nginx 主程序即可扩展功能，且支持热加载。需要注意的是，load_module 必须放在 main 上下文（即 http、stream 或 mail 块之外）才能生效。
如何编译并加载一个自定义的 HTTP 过滤器模块？
要加载一个自定义的 HTTP 过滤器模块，你需要先确保 Nginx 源码已配置为兼容模式，然后编译出 .so 文件，最后在 nginx.conf 中引用它。假设你有一个名为 ngx_http_my_filter_module.c 的模块源码，编译步骤如下：首先配置源码目录，使用 --with-compat 标志；接着编译模块；最后将生成的 .so 文件复制到 Nginx 的模块目录（通常是 /usr/lib/nginx/modules/ 或 /usr/local/nginx/modules/）。在配置文件中，添加 load_module modules/ngx_http_my_filter_module.so; 到顶层。重启 Nginx 后，模块即可生效。
# 1. 进入 Nginx 源码目录
cd /path/to/nginx-source
# 2. 配置编译选项，关键是指定 --with-compat
./configure --prefix=/etc/nginx \
--sbin-path=/usr/sbin/nginx \
--modules-path=/usr/lib/nginx/modules \
--conf-path=/etc/nginx/nginx.conf \
--with-compat
# 3. 编译模块（仅编译模块，不编译主程序）
make modules
# 4. 复制生成的 .so 文件到模块目录
sudo cp objs/ngx_http_my_filter_module.so /usr/lib/nginx/modules/
# 5. 在 nginx.conf 顶层添加 load_module 指令
# load_module modules/ngx_http_my_filter_module.so;
# 6. 测试配置并重载
sudo nginx -t
sudo nginx -s reload
如何验证动态模块是否成功加载？
验证动态模块是否加载成功，最直接的方法是检查 Nginx 的错误日志或使用 -V 参数查看版本信息，但更可靠的是通过 nginx -T 输出完整配置来确认。如果模块加载失败，Nginx 会在启动时报错并拒绝启动，错误信息通常包含 unknown directive 或 module is not found。你可以创建一个简单的测试请求，观察模块预期的行为是否出现。例如，如果模块修改了响应头，你可以使用 curl -I 查看响应头是否包含模块添加的内容。此外，可以通过查看 /var/log/nginx/error.log 来排查加载过程中的具体错误，如权限问题或依赖缺失。
# 1. 检查 Nginx 配置是否正确，包括模块加载 sudo nginx -t # 2. 查看完整配置输出，确认 load_module 指令存在 sudo nginx -T | grep load_module # 3. 检查错误日志，看是否有模块加载失败的记录 tail -f /var/log/nginx/error.log # 4. 发送测试请求，验证模块功能 # 假设模块添加了 X-My-Header 响应头 curl -I http://localhost/test # 预期输出应包含类似: # X-My-Header: loaded-by-my-filter
当 load_module 指令指向不存在的 .so 文件时会发生什么？
当 load_module 指令指向一个不存在的 .so 文件时，Nginx 在启动或重载配置时会立即失败，并返回错误信息，提示找不到指定的模块文件。此时，Nginx 不会启动新的工作进程，现有的服务可能会中断（如果是重载操作）。错误日志中会明确记录类似 open() ".../nonexistent.so" failed (2: No such file or directory) 的信息。这种严格的检查机制确保了配置的完整性，防止因模块缺失导致的服务异常。因此，在配置动态模块时，务必确认 .so 文件的路径正确且文件存在，并且具有正确的读取权限。
