Nginx源码编译实战：参数规划、模块选择与平滑升级

1. 先想清楚：什么时候值得自己编译 Nginx

包管理器一条命令就能把 Nginx 装上，配置文件在/etc/nginx，日志在/var/log/nginx，服务脚本人家已经帮你写好了。既然这么省事，为什么还要折腾源码编译？这个问题我在带新人的时候被问过不止一次，而每次我的回答都差不多：源码安装解决的从来不是“能不能跑起来”的问题，而是“跑起来的东西能不能被我完全控制”的问题。

主流发行版仓库里的 Nginx 版本普遍偏旧，这是常识。更要命的是，仓库版本为了兼容性和稳定性，往往把一堆模块裁掉了，或者把一些模块编成了动态模块，你想加载还得额外装包。等你要用到某个特性——比如四层 TCP 转发、比如 HTTP/2、比如某个第三方模块——你会发现系统自带的那个二进制文件根本给不了你，这时候除了重编译没有第二条路。

还有一种情况特别常见：线上机器的 OpenSSL 版本是系统自带的，而那个版本可能已经比较老了，你想让 Nginx 用上新版本的 TLS 能力，靠换系统库是不现实的，因为一旦改动系统的 OpenSSL，会连带影响一整片依赖它的程序。源码编译允许你把指定版本的加密库直接静态链接进 Nginx 二进制里，形成一个相对独立、自包含的可执行文件，这在无法随意改动运行环境的情况下，是一个相当非常规但确实有用的做法。

最后一种情况是定制化。你的业务可能需要打补丁、可能需要裁剪掉用不到的模块来压体积、可能需要在编译期就把一些路径写死以便和内部规范对齐。这些操作在二进制包上全都做不了，只能从源码开始。

我把这三类场景整理成了一张表，对照着看更直观：

这张表我想多解释一句：很多文章在讲源码安装时只讲“更灵活、更可控”，却不提它的代价。代价就是后续每一次版本更新和安全补丁，你都得自己重新走一遍编译流程，包括参数校验、二进制替换和回归验证。如果你的机器只有两三台、Nginx 只做简单的反向代理和静态资源服务，我的建议是老老实实用包管理器装，把运维精力放在更有价值的地方。源码编译真正划算的场合，是机器规模到一定程度、或者有一个绕不开的模块需求。

至于这篇文章适合谁看：完全没编译过 Nginx 的可以照着走一遍，把流程和参数吃透；踩过坑的老手可以重点看第三、第五、第六部分，那里讲的都是参数取舍和排错细节，是文档里不太会写的东西。

2. 编译环境准备与依赖取舍

2.1 最小依赖清单，以及每个依赖到底在干什么

很多人编译失败不是因为参数写错，而是因为依赖没装全，报错信息又看不懂。所以在敲./configure之前，先把依赖这件事说清楚。

Nginx 的源码编译有三组依赖，分两个层次：

第一层是编译工具链，也就是 gcc、make 这一套，以及头文件包。Debian 系叫build-essential，RHEL 系叫gcc gcc-c++ make。这层没什么可说的，缺了连 configure 都跑不起来。

第二层是功能依赖库，这三个是重点：

这三个库，每个都有两种用法，这个区别必须搞清楚，否则你会遇到很奇怪的报错：

• 用系统预装的开发包：直接装libpcre3-dev、zlib1g-dev、libssl-dev这类包，configure 时不需要加任何参数，Nginx 会自动去找系统里的库。
• 用自定义版本的源码目录：下载对应库的源码并解压，configure 时用--with-pcre=/path/to/pcre-src指过去。

注意第二种方式里的路径，指的是源码目录，不是安装目录。Nginx 在编译过程中会自己去那个目录里构建这些库，所以那个目录必须包含完整的源码文件（configure、Makefile.in之类），而不是已经装好的.so和头文件。这一点坑过很多人：有人把库装到/usr/local/openssl，然后写--with-openssl=/usr/local/openssl，结果编译报错找不到文件，因为那里只有安装产物没有源码。

提示：判断该用哪种方式，看你的需求。只是想让 Nginx 能跑 HTTPS，系统包足够；想要特定版本的 OpenSSL（比如需要较新的 TLS 能力），才用源码目录的方式，并且要做好后续手动跟进安全更新的心理准备。

2.2 版本兼容性：几个容易踩到的地方

依赖装全了不等于能编过，版本组合也有讲究。

OpenSSL 3.x 与老版本 Nginx 的兼容问题。如果你打算用源码方式链接一个比较新的 OpenSSL，同时 Nginx 版本又比较老，编译阶段可能会冒出一堆废弃 API 的告警，甚至直接报错。稳妥的组合是：Nginx 用较新的稳定版或主线版，OpenSSL 用 1.1.1 系列或 3.x 系列中较新的小版本。如果 Nginx 版本实在老，就别硬上新 OpenSSL。

PCRE1 和 PCRE2 的区分。较新的 Nginx 版本已经支持 PCRE2，对应参数是--with-pcre后面指向 PCRE2 的源码目录，configure 的输出里会明确告诉你它用的是 PCRE2 还是 PCRE。如果你用系统包，装libpcre2-dev就对了；如果两个版本的开发包都装了，以 configure 输出为准。

gcc 版本过低。老系统上 gcc 可能是 4.x，编译一些新版本的开源代码时会遇到语法不支持的问题。这种情况要么升级工具链，要么换一个旧一点的 Nginx 版本，硬扛没意义。

还有就是磁盘和内存。完整编译一次 Nginx 加 OpenSSL，中间产物加上最终二进制，几百 MB 是跑不掉的，/tmp分区给小了的机器上容易在中途报“No space left on device”。另外make -j开太高在低配机器上会触发 OOM Killer，编译进程被直接杀掉，报错信息往往只有一句Killed，看起来莫名其妙。我的做法是：核数少于 4 的机器就make -j2，4 核及以上再make -j$(nproc)，稳妥优先。

3. 编译参数怎么定：逐个说清楚为什么

3.1 路径类参数：一次性把目录规划好

configure 的路径参数有十几个，全写出来很长，但每一个都对应一个实际的文件位置。不写也能编过，Nginx 会全用相对于--prefix的默认值，但那样的话日志、配置、临时文件全挤在一个目录里，后期做日志切割、做监控、做权限隔离都会很难受。

下面这份是我常用的路径规划，可以直接抄：

./configure \ --prefix=/usr/local/nginx \ --sbin-path=/usr/local/nginx/sbin/nginx \ --conf-path=/usr/local/nginx/conf/nginx.conf \ --pid-path=/usr/local/nginx/run/nginx.pid \ --lock-path=/usr/local/nginx/run/nginx.lock \ --error-log-path=/usr/local/nginx/logs/error.log \ --http-log-path=/usr/local/nginx/logs/access.log \ --http-client-body-temp-path=/usr/local/nginx/temp/client_body \ --http-proxy-temp-path=/usr/local/nginx/temp/proxy \ --http-fastcgi-temp-path=/usr/local/nginx/temp/fastcgi \ --http-uwsgi-temp-path=/usr/local/nginx/temp/uwsgi \ --http-scgi-temp-path=/usr/local/nginx/temp/scgi \ --user=nginx \ --group=nginx

逐条解释几个容易理解的点和容易误解的点：

--pid-path单独设成run/目录是我个人习惯。很多运维脚本、监控采集、systemd 单元文件都要读这个 pid 文件，把它从logs/里分离出来，语义更清楚，权限也好单独控制。

--user和--group指定的是worker 进程的运行账号，不是 master 进程。master 依然以 root 身份启动（否则没法绑定 80 和 443 端口），然后通过 setuid 把 worker 降权到这个账号。所以这个账号必须在编译前就存在，否则启动时会报“getpwnam failed”类似的错误。创建时建议加-r -s /sbin/nologin，让这个账号纯粹用于运行服务，不具备登录能力。

那五个temp-path是临时文件目录，处理大请求体、代理转发、FastCGI 交互时都会往这里写。默认值相对--prefix分布，我统一收拢到temp/下一个层级。这里有个必须记住的点：这些目录 Nginx 不会自动创建，只在启动时检查。目录不存在就会启动失败，报错形如：

nginx: [emerg] mkdir() "/usr/local/nginx/temp/client_body" failed (2: No such file or directory)

所以安装完成后第一件事就是mkdir -p把这些目录建出来，并且把属主改成 worker 账号。后面第五部分还会再提一次，因为这是最高频的启动失败原因之一。

3.2 模块参数：加什么、减什么，心里得有数

模块参数是区分“能跑”和“好用”的关键。默认情况下 Nginx 会编入一大批基础模块，你需要额外打开的是那些默认关闭的。

先说 SSL 和 HTTP/2：

--with-http_ssl_module \ --with-http_v2_module \

--with-http_ssl_module是 HTTPS 的前提，没它连ssl_certificate指令都认不出来。--with-http_v2_module提供 HTTP/2 支持，但它依赖 SSL 模块，两者必须一起加，否则 configure 会直接拒绝。这一点很多教程没写清楚，导致有人只加 v2 编译失败还找不到原因。

再说几个实用但常被忽略的：

--with-http_realip_module \ --with-http_stub_status_module \ --with-http_gzip_static_module \ --with-http_sub_module \ --with-http_secure_link_module \ --with-threads \ --with-file-aio \

--with-http_realip_module在 Nginx 前面还有一层负载均衡或者 CDN 的时候几乎是必需的，否则 access.log 里记录的全是上一跳的地址，排查问题时会怀疑人生。

--with-http_stub_status_module提供一个极简的状态页，暴露连接数、请求数这些指标。功能很朴素，但接监控采集的时候它是最省事的数据源。

--with-http_gzip_static_module和--with-http_gzip_module不是一回事，前者是直接返回已经预压缩好的.gz文件，省掉 CPU 压缩开销；后者是实时压缩。两个都编进去，配置里按需开启。

--with-threads是线程池支持，配合aio threads使用，在处理大量慢磁盘 IO 的场景下有用。--with-file-aio是异步文件 IO，注意它在某些文件系统上不一定生效，实际效果需要压测验证，别照抄配置就以为生效了。

如果要做四层代理，加上 stream 相关模块：

--with-stream \ --with-stream_ssl_module \ --with-stream_realip_module \

--with-stream是四层转发的入口，做数据库代理、TCP 负载均衡都靠它。--with-stream_ssl_module让它能处理 TLS 四层透传或终止。这两个模块默认都不编译，需要显式开启。

如果要加第三方模块，静态方式用--add-module=/path/to/module，动态方式用--add-dynamic-module=/path/to/module。动态方式的好处是模块以.so形式存在，将来增删模块不需要重新编译整个 Nginx，但前提是编译主程序时要加--with-compat，这个参数会放宽模块 ABI 的校验，让动态模块能在不同小版本之间通用。不加--with-compat而用动态模块，加载时可能报“module is not binary compatible”，这个报错很多人看不懂，其实就是 ABI 不匹配。

至于裁剪，如果你确定用不到某些功能，可以反向关掉来减小体积：

--without-http_autoindex_module \ --without-http_ssi_module \ --without-mail_pop3_module \ --without-mail_imap_module \ --without-mail_smtp_module \

mail 那三个模块默认是编进去的，除非你真的用 Nginx 做邮件代理，否则关掉能省一点体积，也能减少潜在的攻击面。不过说实话，省下来的体积有限，我更倾向于保留默认，除非有明确的安全审计要求。

3.3 编译器优化参数：别乱加，也别不加

--with-cc-opt和--with-ld-opt这两个参数控制编译和链接时的额外选项。不写也能编过，但生产环境通常会把一些安全加固选项写进去。

--with-cc-opt='-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector-strong --param=ssp-buffer-size=4' \ --with-ld-opt='-Wl,-z,relro -Wl,-z,now'

这几个选项的作用值得说一下：

-O2是常规优化级别，兼顾性能和编译时间。不建议上-O3，收益不明显，还可能引入一些难以复现的行为差异。

-fstack-protector-strong加上-Wl,-z,relro -Wl,-z,now是一组常见的二进制加固措施，前者做栈溢出保护，后两者让 GOT 表在加载后只读，能提高一些利用门槛。这类加固在现代发行版的默认编译选项里基本都有了，自己写上去算是显式声明。

-g保留调试符号会显著增大二进制体积（可能翻好几倍）。如果追求二进制精简，可以把-g去掉；如果将来可能需要用 gdb 排查崩溃，就留着。我一般线上包会去掉-g，排障时再单独编一个带符号的版本。

还有一个坑要提：-Wp,-D_FORTIFY_SOURCE=2在很老的 gcc 上可能不被支持，会报一堆告警甚至警告升级为错误。遇到这种情况，把这一项从参数里删掉即可，不影响功能。

4. 走一遍完整的编译安装流程

4.1 下载、校验、解压

流程上有几个细节决定了后面顺不顺利。

第一步，选版本。下载页面上有主线版和稳定版两条线，我的建议是：新上线的项目用稳定版，追求新特性且有能力跟进问题的用主线版。不要用太老的版本，尤其是安全更新已经停止的版本。

第二步，下载。拿到源码包后用curl或wget拉下来即可。这里我要强调的是校验：下载完成后核对一下官方提供的校验值，这一步在很多人眼里是形式主义，但它能避免下载到不完整的包——网络中断导致的截断包，解压后会在编译中途以莫名其妙的语法错误暴露出来，排查成本远高于花十秒钟做一次校验。

# 下载后核对哈希 sha256sum nginx-1.xx.x.tar.gz # 与发布页给出的值逐字比对

第三步，解压，然后进入源码目录。解压出来的目录里结构很清晰：src/是源码，auto/是 configure 脚本用的探测逻辑，conf/是默认配置模板，objs/是编译后才生成的。第一次解压是看不到objs/的。

4.2 configure：把参数落地

把第三部分整理好的参数拼成一条完整命令执行。这一步的执行时间不长，但输出信息很值得读，它会告诉你哪些模块被编入、用了哪个版本的 PCRE、用的是哪个 gcc、生成了哪些 Makefile。

cd nginx-1.xx.x ./configure [上面那一长串参数]

执行完之后，建议立刻做一次确认：

./objs/nginx -V

注意这里用的是objs/下的临时二进制，不是安装后的。-V会输出编译时的所有参数，这也是最实用的参数恢复技巧：如果你接手一台已经装好 Nginx 的机器，想知道当初是怎么编译的，一条nginx -V就能拿到完整参数列表，照着抄就能复现同样的编译环境。这个技巧在接手别人的环境时几乎必用。

configure 的输出里如果有+ using PCRE2 library这样的字样，说明它找到的是 PCRE2；如果只写 PCRE，那可能是 PCRE1。两种都能正常工作，但如果你明确需要 PCRE2，就得回头检查开发包有没有装对。

4.3 make：控制并行度，看着点内存

make -j$(nproc)

这一步是耗时大头。执行期间会看到大量cc -c的输出刷屏，属于正常现象。这里两个提醒：

第一，-j的数值别贪大。$(nproc)在大多数场景下是安全的，但在容器环境里，nproc返回的可能是宿主机核数而不是容器配额，并行度过高会导致内存撑爆。容器里编译建议手动指定-j2或-j4。

第二，如果编译失败，不要直接从头再来。看看报错信息，注释掉可疑参数（尤其是第三方模块），改完重新跑 configure + make。make clean能清掉上次的中间产物，避免旧目标文件干扰。

编译成功后会生成objs/nginx，可以用ls -lh看看大小，正常范围在几 MB 到十几 MB 之间，带-g的可能几十 MB。

4.4 make install 与目录结构确认

make install

这一步做的事情很简单：把编译好的二进制、默认配置、页面文件按--prefix和路径参数复制过去。执行完之后，重点检查这几件事：

/usr/local/nginx/sbin/nginx -V # 参数是否和预期一致 /usr/local/nginx/sbin/nginx -t # 配置语法检查，此时会暴露临时目录缺失问题 mkdir -p /usr/local/nginx/temp/{client_body,proxy,fastcgi,uwsgi,scgi} chown -R nginx:nginx /usr/local/nginx/temp

nginx -t这一步非常关键，它会在真正启动前把配置和路径问题都暴露出来。如果报临时目录不存在，就按上面的命令创建；如果报 pid 目录不存在，同理创建。把所有报错在-t阶段解决掉，比启动失败后再去翻错误日志效率高得多。

再确认一下 worker 账号存在：

id nginx

不存在的话需要先创建。

5. 装完之后：把它变成一个真正的系统服务

5.1 用 systemd 接管进程管理

make install只给你一个二进制文件，开机自启、异常重启、优雅重载这些能力都得自己补上。现代发行版统一用 systemd，写一个单元文件是最省事的做法。

[Unit] Description=Nginx Web Server After=network.target remote-fs.target nss-lookup.target [Service] Type=forking PIDFile=/usr/local/nginx/run/nginx.pid ExecStartPre=/usr/local/nginx/sbin/nginx -t -q -g 'daemon on; master_process on;' ExecStart=/usr/local/nginx/sbin/nginx ExecReload=/usr/local/nginx/sbin/nginx -s reload ExecStop=/bin/sh -c "/usr/local/nginx/sbin/nginx -s quit; while kill -0 $(cat /usr/local/nginx/run/nginx.pid) 2>/dev/null; do sleep 0.5; done" [Install] WantedBy=multi-user.target

几个设计取舍解释一下：

Type=forking是因为 Nginx 默认以守护进程方式启动，master 进程会 fork 出去然后父进程退出，systemd 需要靠PIDFile来跟踪真正的 master 进程号。

ExecStartPre里跑一次nginx -t是很有价值的保险，配置写错了直接启动失败，而不是启动成功之后再莫名其妙地 500。加-q是为了只在出错时输出，正常启动不刷屏。

ExecStop里用-s quit而不是-s stop，是因为quit是优雅退出，会等待正在处理的请求完成；而stop是快速退出，会直接断开连接。线上服务用优雅退出。后面接一段轮询等待 pid 消失，是为了确保 systemd 认为服务完全停止，否则可能出现“已经执行过 stop，但进程还在、systemd 又拉不起来”的状态。

ExecReload用nginx -s reload，这是平滑重载，不中断连接。

写完之后执行systemctl daemon-reload让它生效，然后systemctl enable --now nginx。

5.2 日志切割：别让 access.log 吃到磁盘满

这是源码安装和包管理器安装差距最大的一块。包安装会顺带装一个 logrotate 配置，源码安装什么都不给你，日志文件会一直增长，直到把磁盘吃满——等到服务报“No space left on device”才发现，损失就大了。

Nginx 的日志切割机制很直观：master 进程会监听一个信号，收到之后重新打开所有日志文件。所以切割流程是“重命名旧文件 → 发信号让 Nginx 重新打开新文件”。

系统一般自带 logrotate，写一份配置放进去就行：

/usr/local/nginx/logs/*.log { daily rotate 14 missingok notifempty compress delaycompress sharedscripts postrotate [ -f /usr/local/nginx/run/nginx.pid ] && kill -USR1 $(cat /usr/local/nginx/run/nginx.pid) endscript }

USR1就是那个“重新打开日志文件”的信号。sharedscripts保证多个日志文件只触发一次信号，避免重复执行。delaycompress让最近一份日志保持未压缩状态，方便你 inmediat 排查问题——这一点很实用，很多时候问题刚发生，你就需要去 grep 刚被切割的那个文件。

注意：如果切割后日志没有写到新文件，而是继续写到了带日期的旧文件名里，几乎可以确定是信号没发到，或者 pid 文件路径写错了。先确认 pid 文件里那个进程号确实存在，再手动执行一次信号发送验证。

5.3 二进制升级与平滑替换

源码安装最容易被忽略的日常工作是升级。等出了安全更新，你需要重新编译一个二进制，然后替换掉正在运行的那个。

这里的关键是不要直接make install覆盖在线服务的文件。正确做法是：新版本编译好之后，把objs/nginx拷到 sbin 目录（先备份旧的），然后通过信号做平滑升级：

# 1. 备份旧二进制 mv /usr/local/nginx/sbin/nginx /usr/local/nginx/sbin/nginx.old # 2. 放入新的 cp objs/nginx /usr/local/nginx/sbin/nginx # 3. 检查新旧二进制是否可用 /usr/local/nginx/sbin/nginx -t # 4. 向 master 进程发送平滑升级信号 kill -USR2 $(cat /usr/local/nginx/run/nginx.pid)

USR2会让 master 启动一个新的 master 进程，新进程沿用旧进程的监听端口（通过文件描述符继承），同时旧的 pid 文件会被重命名为nginx.pid.oldbin。此时新旧两套进程并存，新进程开始接新连接。

确认新进程工作正常、旧进程的请求处理完之后，再发QUIT给旧 master 让它退出：

kill -QUIT $(cat /usr/local/nginx/run/nginx.pid.oldbin)

如果发现新版本有问题要回滚，流程是反的：给旧 master 发HUP让它重新接管，给新 master 发QUIT让它退出。这个流程比“停机换二进制再启动”复杂不少，但换来的是零停机。高频交易的场景下，这几分钟的差别很重要；而如果只是内部管理系统，停机两分钟换二进制完全能接受，没必要走这套流程。

还有一点：升级时不只是换二进制。如果新版本引入了配置指令的变更，配置也要跟着改；如果编译参数变了（比如新加了模块），要重新确认-V输出；如果有动态模块，.so文件也需要同步更新。这几件事漏一件，都可能导致升级后功能异常。

6. 常见报错与排查速查

6.1 编译阶段：configure 与 make 的典型报错

configure 阶段最常见的报错是依赖缺失，报错文本通常很直白：

./configure: error: the HTTP rewrite module requires the PCRE library.

这句的意思是找不到 PCRE。解决方式二选一：装libpcre3-dev（Debian 系）或pcre-devel（RHEL 系）；或者用--with-pcre=指向源码目录。同理，SSL modules require the OpenSSL library对应 OpenSSL 开发包缺失。

另一个高频报错是：

./configure: error: the invalid value in --with-ld-opt="-Wl,-z,relro -Wl,-z,now"

这种情况多见于引号处理不当，或者在参数里混入了 shell 会解释的特殊字符。检查引号是否成对，参数之间是否有不可见字符。

make 阶段我遇到最多的是两种。第一种是fatal error: xxx.h: No such file or directory，头文件缺失，回头补对应的-dev包即可。第二种是编译到一半进程直接消失，只留一个Killed，这就是内存被 OOM Killer 干掉了，降并行度重来。

还有一种是第三方模块导致的编译失败，报错五花八门。排查思路很简单：把--add-module相关的参数去掉重新 configure，如果就能编过，说明问题在那个模块上，去看它的 README 和兼容的 Nginx 版本范围。

6.2 运行阶段：启动就挂掉怎么查

启动阶段的报错，第一个要看的是nginx -t的输出，第二个是error.log。

nginx: [emerg] mkdir() "/usr/local/nginx/temp/client_body" failed (2: No such file or directory)

临时目录不存在，前面讲过了，建目录 + 改属主。

nginx: [emerg] getpwnam("nginx") failed

worker 账号不存在。id nginx确认一下，不存在就创建，注意要-r -s /sbin/nologin。

nginx: [emerg] bind() to 0.0.0.0:80 failed (13: Permission denied)

端口被占或者权限不足。80 以下端口需要 root 或者相应的能力配置。检查端口占用用ss -lntp | grep :80。

nginx: [emerg] open() "/usr/local/nginx/run/nginx.pid" failed (2: No such file or directory)

pid 目录不存在，建一下即可。

还有一类问题不报错但行为异常，比如 502。这时候别急着改配置，先看 error.log 里的 upstream 记录，通常是后端地址不通、超时设置不合理，或者 SELinux 之类的强制访问控制把出站连接拦了。最后这个坑很隐蔽，因为报错信息里会写Permission denied而不是“连接被拒绝”，容易往权限配置的方向误判。排查方法是用getenforce看看状态，再对照审计日志确认。

6.3 一张速查表，遇到问题先对号入座

这张表我建议收藏，实际工作中前六行覆盖了绝大多数情况。剩下的几行属于偶发问题，但一旦遇到，知道往哪个方向查能省很多时间。

最后分享一个我自己的习惯：每次编译完，把完整的nginx -V输出和 configure 命令一起存到代码库里，文件名叫build-notes.md。看起来是个小事，但等到半年后需要重新编译、或者需要在新机器上复现一套一模一样的环境时，这份记录就是救命的。我吃过一次亏，当时凭印象重新写参数，结果漏了一个模块，上线后某个四层转发规则失效，回头才发现是编译参数少了--with-stream。从那以后这个习惯就再没断过。