静态编译第三方模块是将模块代码直接链接进Nginx可执行文件，启动快、部署轻量，但需每次重新编译；须确认模块兼容性、下载匹配版本源码、用--add-module配置并make install，最后通过nginx -t和功能验证生效。
静态编译第三方模块到 Nginx，本质是在源码构建阶段将模块代码直接链接进最终的 nginx 可执行文件，而非运行时动态加载。这种方式无需 load_module 指令，启动更快、部署更轻量，但每次增删模块都需重新编译。
确认模块兼容性与获取源码
不是所有第三方模块都支持静态编译，尤其较新的模块可能只适配动态模块（--add-dynamic-module）。需查阅模块文档或其 config 脚本内容：
- 若模块根目录下有可执行的
config文件（常见于 OpenResty 生态或 GitHub 主流模块），通常支持静态集成； - 检查该
config文件是否包含ngx_addon_name、HTTP_MODULES或CORE_INCS等变量定义——这是静态编译支持的关键信号； - 下载与目标 Nginx 版本匹配的模块源码（例如 Nginx 1.24.x 对应模块分支或 commit）；
- 模块源码建议解压到独立目录（如
/path/to/ngx_http_substitutions_filter_module），避免路径含空格或中文。
配置编译参数并启用模块
进入 Nginx 源码根目录（如 nginx-1.24.0/），执行 ./configure 时用 --add-module（注意：无 dynamic）指定模块路径：
-
--add-module=/path/to/your-module—— 这是静态集成的核心参数； - 可同时添加多个模块，重复使用
--add-module； - 保留原有必要选项，如
--prefix、--with-http_ssl_module、--with-stream等； - 避免混用
--add-dynamic-module和--add-module同一模块，会导致冲突； - 执行后运行
make && sudo make install完成构建安装。
验证模块是否生效
静态模块不会出现在 nginx -V 的输出中（该命令只显示 configure 参数，不列具体模块），需通过以下方式确认：
- 运行
nginx -V 2>&1 | grep -o 'with-[a-z0-9_-]\+'查看启用的官方模块关键词（如with-http_sub_module），但第三方模块名一般不显示； - 更可靠的方式：在配置中使用该模块的指令（如
subs_filter、lua_code_cache），然后执行nginx -t—— 若无报错，说明模块已成功链接； - 启动后访问对应功能（如替换响应内容、执行 Lua 脚本），观察行为是否符合预期；
- 用
objdump -t $(which nginx) | grep -i "your_module_symbol"（需模块导出符号）可进一步确认符号存在，但非常规操作。
常见问题与注意事项
静态编译虽稳定，但易踩坑：
- 模块依赖其他库（如
libluajit、libpcre）时，需确保系统已安装对应开发包（如libluajit-5.1-dev），并在./configure中显式启用（如--with-luajit）； - Nginx 升级时，必须重新编译整个二进制，不能仅替换模块；
- 调试困难：GDB 调试需带调试符号（加
--with-debug）并保留.o文件； - 某些模块（如
nginx-rtmp-module）默认只支持静态，而echo-nginx-module等则需指定--with-echo或类似开关才能启用，不能只靠--add-module。
