nginx源码编译添加第三方模块必须静态集成，核心是下载完全匹配版本源码、复用原configure参数并追加--add-module绝对路径，安装依赖后make && make install，再通过nginx -v、-t和日志验证生效。
在源码编译时添加第三方开源模块，是 Nginx 扩展功能最通用、最可靠的方式。它要求你重新编译整个 Nginx，把模块静态集成进去，适用于所有版本（包括不支持动态模块的老版本），也兼容绝大多数第三方模块。
确认模块与环境是否匹配
先执行 nginx -V 查看当前运行 Nginx 的详细信息：
- 版本号（如 1.24.0）——必须下载完全一致的源码包，不能高也不能低
- --configure arguments 行——记录全部原有参数，重编译时需复用，否则可能丢失 SSL、HTTP/2 等关键模块
- 检查目标模块文档（如 GitHub README），确认它支持你的 Nginx 主版本（例如 1.22–1.26）、是否依赖 pcre2/zlib-ng/geoip2-devel 等系统库
- 确保模块根目录下存在 config 文件（这是 configure 脚本能识别它的必要条件）
准备源码和编译环境
在干净环境中操作，避免路径或权限干扰：
- 从 nginx.org 下载对应版本源码，例如：
wget https://www.php.cn/link/9926b3ed9e0bc20b2ed7f32711b8b45fnginx-1.24.0.tar.gz - 解压后进入目录：
tar zxf nginx-1.24.0.tar.gz && cd nginx-1.24.0 - 将第三方模块（如
headers-more-nginx-module或nginx-module-vts）放到固定路径，例如：/usr/src/nginx-modules/headers-more-nginx-module - 安装基础编译依赖（Ubuntu/Debian）：
sudo apt-get install build-essential libpcre3-dev zlib1g-dev libssl-dev；CentOS/RHEL：yum groupinstall "Development Tools" && yum install pcre-devel zlib-devel openssl-devel
配置并编译安装
使用原始 configure 参数，追加 --add-module= 指向每个模块路径：
- 示例命令（多模块可连续添加）：
./configure \<br> --prefix=/etc/nginx \<br> --sbin-path=/usr/sbin/nginx \<br> --modules-path=/usr/lib64/nginx/modules \<br> --conf-path=/etc/nginx/nginx.conf \<br> --error-log-path=/var/log/nginx/error.log \<br> --http-log-path=/var/log/nginx/access.log \<br> --pid-path=/var/run/nginx.pid \<br> --with-http_ssl_module \<br> --with-http_v2_module \<br> --add-module=/usr/src/nginx-modules/headers-more-nginx-module \<br> --add-module=/usr/src/nginx-modules/nginx-module-vts
- 执行
make && sudo make install（注意：不是make install后直接覆盖二进制，建议先备份原/usr/sbin/nginx） - 验证新二进制是否包含模块：
/usr/sbin/nginx -V 2>&1 | grep -o "headers-more|vts"
验证与上线
替换完成后不能直接 reload，需完整走一遍启动流程：
- 用
nginx -t检查配置语法，特别留意新模块引入的指令（如more_set_headers）是否拼写正确、上下文是否合法 - 停止旧进程：
sudo nginx -s stop（确保无残留 master 进程） - 启动新版：
sudo /usr/sbin/nginx（推荐指定绝对路径，避免 PATH 混淆） - 查看日志：
tail -f /var/log/nginx/error.log，确认无unknown directive或模块初始化失败报错 - 上线前建议在测试环境跑通完整请求链路（如 HTTPS + 自定义 header + 状态页）
