为 Nginx 添加第三方模块必须源码编译，需严格匹配版本、复用原 configure 参数并静态链接；兼容性验证、路径规范、二进制替换及动态模块（≥1.9.11）是关键步骤。
为 Nginx 添加第三方模块必须走源码编译路线，不能靠简单复制或配置启用。核心逻辑是：用完全一致的版本重新编译整个 Nginx，把新模块静态链接进去，同时保留原有功能不丢失。
确认当前环境与模块兼容性
执行 nginx -V 查看完整输出，重点关注两部分：
- nginx version —— 精确到小数点后两位（如 1.22.1），必须下载同版本源码，高一个 patch 版也不行；
-
configure arguments —— 这是你重编译时要复用的基础参数，漏掉
--with-http_ssl_module就可能让 HTTPS 失效； - 检查目标模块文档是否支持该 Nginx 主版本（例如只支持 1.20–1.24），并确认系统已装好依赖（如 pcre、zlib、openssl-dev）。
准备源码与模块路径
把 Nginx 源码和第三方模块放在同一父目录下，结构清晰便于引用：
- 下载官方源码包：
wget https://nginx.org/download/nginx-1.22.1.tar.gz，解压后进入目录； - 第三方模块建议用 git 克隆（如
git clone https://github.com/openresty/headers-more-nginx-module.git），确保模块根目录下有config文件； - 路径推荐用绝对路径，避免相对路径出错，比如
--add-module=/usr/src/nginx-modules/headers-more-nginx-module。
执行 configure + 编译安装
在 Nginx 源码目录中运行 configure 命令，原参数全保留，末尾追加 --add-module：
- 不要直接写
make install覆盖线上环境——先指定临时前缀测试，例如--prefix=/tmp/test-nginx； - 确认 configure 成功（无 error 提示），再执行
make（生成二进制），不要立即 make install； - 备份原 nginx 二进制：
cp /usr/sbin/nginx /usr/sbin/nginx.bak； - 仅替换二进制：
cp objs/nginx /usr/sbin/nginx； - 验证：
nginx -V应显示新增模块，nginx -t确保配置语法正常，最后nginx -s reload生效。
动态模块方式（Nginx ≥1.9.11 可选）
如果 Nginx 版本够新且模块支持动态加载，可跳过全量重编译：
- configure 时用
--add-dynamic-module=/path/to/module； - 执行
make modules（不是 make），生成.so文件； - 将 so 文件复制到
modules目录（nginx -V中--modules-path指定的位置）； - 在
nginx.conf的main上下文中添加load_module modules/ngx_http_geoip2_module.so;； - reload 即可，无需重启进程，升级维护更安全。
