Windows源码编译Nginx全流程：工具链搭建、依赖配置与常见坑排查

简介面向需要在Windows环境编译Nginx的开发者这份资源把源码、依赖库与Windows下常用编译工具整合到了一起可以有效解决手动匹配工具链、三方模块和编译参数等繁琐问题。资源以Nginx 1.20.2源码为核心同时包含http-flv模块源码、OpenSSL、PCRE、Zlib源码以及ActivePerl、MSYS2、sed等辅助工具适合有一定C/C基础、希望构建支持HTTP-FLV直播流媒体服务的开发者。整个压缩包共28个文件大小约102.07MB文件类型涵盖conf配置模板、pl辅助脚本、vim语法文件、许可协议、说明文档和exe可执行程序等目录结构较为清晰便于按需取用。已有541人浏览/学习说明这套组合方案对需要自行编译Nginx或做流媒体扩展的中高级开发者有一定参考价值。使用者拿到资源后可以对照源码目录和自带工具完成依赖准备、模块配置、编译链接到生成可执行文件的完整流程还能结合http-flv模块快速搭建支持HTTP-FLV的直播服务省去在Windows下逐个搜集和配置依赖的麻烦是一份实用且便于复现的编译工具包。 去年有个同事丢给我一个压缩包名字就叫“Windows编译Nginx必要工具.rar”。他说你以后要在Windows上自己编Nginx这里面少一样都不行。我当时半信半疑直到自己亲手编了几次、卡了好几轮编译错误之后才明白那个压缩包里装的每一件东西确实都有用。后来我又把整个流程反过来梳理了一遍发现真正卡人的其实不是编译本身而是“缺工具”和“工具之间不配合”。今天这篇就把Windows源码编译Nginx这件事彻底讲透。不只列工具清单还把为什么需要这些工具、每一步在干什么、常见的坑长什么样全部摊开说。内容按“先搞懂动机再准备工具然后实操编译最后看坑”的顺序来任何基础的人都跟着走一遍就能跑通。1. 先想清楚官方包够用为什么还要折腾源码编译官网下载的Windows版Nginx确实方便解压即用。但它的模块是官方预设好的官方给你编译了哪些你就只能用哪些。实际工作中下面几类需求是官方包满足不了的。第一类是加第三方模块。很多人想用的nginx-rtmp-module流媒体就是典型代表做直播服务、视频点播、HLS切片都要靠它官方Windows包默认不带。echo、lua、headers-more这些常用扩展模块官方包也一概没有。第二类是裁剪模块。内网分发场景下安全审计往往要求把不需要的模块全部拿掉官方包做不到。第三类是调参数和跟踪问题。怀疑内存越界或模块冲突时需要编一个带--with-debug的版本把debug日志打开逐步定位官方包也不会给你编译一个调试版。另外一个容易被忽略的点源码编译能让你锁定Nginx的确切版本和依赖库版本。官方包跟着官网节奏更新而生产环境可能因为某个第三方模块只兼容特定版本被迫固定在一个老版本上。这个需求在Linux环境很常见Windows下同样存在。顺便澄清一个误区源码编译Nginx跟“编译原理”这门课没多大关系。编译原理研究的是怎么写编译器而我们做的是把已写好的C源码通过现成工具链变成可执行文件。你不需要会写词法分析器只要会跑configure和make就够。真正需要花时间理解的是工具链本身以及各个依赖库在构建中承担的角色。2. 工具清单拆解没有一个是凑数的Windows源码编译Nginx有两条主流路线一条是MSYS2MinGW另一条是MSVC。两者没有绝对优劣但工具构成和适应场景完全不一样。2.1 快捷路线MSYS2 MinGW工具链这套组合是我个人最推荐新手先用起来的原因是依赖管理省心得多。MSYS2本身是一个Windows下的类Unix环境自带bash、sed、awk等工具内部还能通过pacman包管理器直接安装MinGW-w64编译器以及各种依赖库。这条路线需要的清单如下工具/包作用是否必需MSYS2提供bash环境执行Nginx的configure脚本必需mingw-w64-x86_64-toolchain提供gcc、make、ld等编译工具必需mingw-w64-x86_64-pcre2正则表达式库Nginx rewrite模块依赖必需mingw-w64-x86_64-zlibgzip压缩模块依赖必需mingw-w64-x86_64-opensslSSL/TLS支持https反向代理必需按需但建议装pkg-config帮助configure找到头文件和库文件位置通常会随依赖自动安装为什么这些工具缺一不可MSYS2的bash负责跑Nginx源码里的auto/configure脚本这个脚本是POSIX shell脚本在Windows的cmd或PowerShell里直接跑不了configure跑完后生成Makefile真正编译靠make和gcc。PCRE2、zlib、OpenSSL是Nginx在Windows下编译时的三个核心外部依赖后缀是mingw-w64-x86_64-的包说明它们是面向64位原生Windows程序编译的。2.2 进阶路线和官方一致的MSVC构建链Nginx官方在Windows上发布的二进制包用的是微软Visual Studio工具链编译的。如果你希望产出和官方最接近、性能调试体验最好的版本那就要走MSVC路线。这路线的工具数量明显更多工具作用Visual Studio Build Tools提供cl.exe编译器和nmake.exe构建工具需要勾选“使用C的桌面开发”工作负载MSYS2仅需基础环境为configure脚本提供bash运行环境Strawberry Perl或ActivePerlOpenSSL源码编译时必须的脚本解释器OpenSSL的构建系统依赖Perl生成部分文件和汇编代码NASMOpenSSL在x64平台下使用NASM汇编优化不装的话SSL性能会受明显影响CMake编译PCRE2库最推荐的构建工具比手写nmake命令省事得多注意这里MSYS2不提供编译器只当“翻译官”用。真正的编译环节是cl.exe加nmake.exe在Visual Studio的开发者命令行环境里执行。OpenSSL用perl Configure VC-WIN64A配置再用nmake编译PCRE2用CMake生成VS工程zlib则直接走源码自带的win32/Makefile.msc。2.3 两个路线怎么选我的建议是第一次接触、只想快速出一个能用的nginx.exe直接走MSYS2MinGW。这个方案从安装工具到编译完成基本半小时以内能搞定依赖库不用自己编译pacman一行命令全装好。如果你要发布给生产环境、要做性能压测对比或必须用第三方模块里依赖MSVC ABI的库那再切到MSVC路线。两条路线编译出来的都是原生Windows程序都能在Windows Server和普通Windows机器上跑不存在“MinGW编译的是半残版本”这种说法。区别主要在ABI兼容性和运行时依赖上下面会细说。3. MSYS2环境搭建一分钟装完依赖走MinGW路线环境准备其实非常轻量。3.1 安装MSYS2与核心包去MSYS2官网下载安装包安装目录建议选一个没有空格的路径比如C:\msys64默认就是这个位置不要改。安装完打开“MSYS2 MINGW64”这个终端注意不是“MSYS2 MSYS”那个终端后者默认是MSYS2环境编译器不是MinGW-w64。先更新软件包索引和基础组件pacman -Syu更新完如果提示关闭终端就关掉重开。然后安装编译工具和依赖库pacman -S base-devel pacman -S mingw-w64-x86_64-toolchain pacman -S mingw-w64-x86_64-pcre2 pacman -S mingw-w64-x86_64-zlib pacman -S mingw-w64-x86_64-openssl pacman -S mingw-w64-x86_64-pkg-configbase-devel里包含了make、autoconf等基础工具mingw-w64-x86_64-toolchain是编译器全家桶。这几条命令装完后你不需要额外手动下载任何依赖源码包这也是这条路最大的优势。3.2 验证工具链装完后在同一个终端里依次执行gcc --version make --version pkg-config --modversion openssl pkg-config --modversion libpcre2-8gcc能打印版本号说明编译器可用pkg-config能打出openssl和pcre2的版本号说明依赖库路径已经正确注册。这一步别跳过很多人编译到一半报找不到头文件回头一查才发现依赖根本没装成功。3.3 一个必须强调的DLL问题MSYS2里装的mingw-w64-开头依赖库默认是动态链接库。编译出的nginx.exe在运行时需要libssl-3-x64.dll、libcrypto-3-x64.dll、libpcre2-8-0.dll这些DLL文件。这些DLL位于C:\msys64\mingw64\bin如果不把MSYS2的mingw64目录加进Windows系统PATH或者不把DLL拷贝到nginx.exe同目录就会遇到“找不到libssl-3-x64.dll”的错误。两个解决办法要么把C:\msys64\mingw64\bin加到系统PATH注意是mingw64下的bin不是msys64根目录下的bin要么在configure时加-static让链接器把依赖静态编进exe。./auto/configure --with-cc-opt-O2 --with-ld-opt-static ...静态编译出的nginx.exe体积会大一些但拷到任何一台Windows机器上都能直接跑不用带一堆DLL。发布内网工具时这个做法省心很多。上面表格里之前有人说MinGW性能差实测在Nginx这种场景下感知不强区别主要在交付便利性上。4. configure参数与make编译实操环境准备好下面进入正题。4.1 下载源码与目录规划建议在C:\nginx-build下建一个src目录把下载的源码都放这里C:\nginx-build └── src ├── nginx-1.26.2 └── nginx-rtmp-module可选如果要用rtmpNginx源码从官网下载.tar.gz包在MSYS2终端里可以用tar -xzf直接解压。注意源码目录路径不要带空格C:\Program Files\这种路径在后续make阶段经常会引出莫名其妙的错误。4.2 关键configure参数逐项解释进入源码目录后执行cd /c/nginx-build/src/nginx-1.26.2 ./auto/configure \ --prefix/c/nginx-build/output \ --with-http_ssl_module \ --with-http_v2_module \ --with-http_stub_status_module \ --with-http_realip_module \ --with-http_gzip_static_module \ --with-pcre-jit \ --with-cc-opt-O2 \ --with-ld-opt-static一个个拆开说--prefix指定最终安装目录生成的nginx.exe、conf目录、logs目录都会装到这里实际路径是C:\nginx-build\output。--with-http_ssl_module启用HTTPS支持对应openssl库--with-http_v2_module启用HTTP/2--with-pcre-jit开启PCRE2的JIT加速对正则匹配性能有明显提升。--with-cc-opt-O2是优化选项-O2是平衡体积和性能的常规选择。--with-ld-opt-static把依赖库静态链接进exe规避DLL分发问题。如果要用rtmp模块做流媒体在configure参数里追加--add-module/c/nginx-build/src/nginx-rtmp-module--add-module后面跟第三方模块的源码路径。也就是说以后无论想加什么第三方模块只要下载源码在configure里用这个参数指过去即可。这就是自编译最大的灵活性来源。configure执行成功后最后几行会给出配置摘要包括启用的模块列表和依赖库版本。先停一下扫一眼确认openssl、pcre2、zlib这几项都是yes再继续不迟。4.3 编译、安装和运行验证接下来执行make -j4 make install-j4是4路并行编译。编译过程会输出大量C编译日志看到一堆gcc命令不断滚动是正常的。编译结束后执行make install会把产物安装到prefix指定的目录。然后到输出目录里验证一下cd /c/nginx-build/output ./nginx.exe -Vnginx -V会打印编译参数和版本号。看到那串熟悉的configure arguments说明编译成功。继续做一次基础反代试跑./nginx.exe -t配置文件语法检查通过后直接./nginx.exe启动浏览器访问本机80端口能看到Nginx欢迎页整个流程就完整跑通了。5. 常见编译失败现场与排查思路编译这东西顺利的话一气呵成不顺利时每个阶段都可能卡住。我把遇到过且复现率高的几类报错整理出来每条都附排查链路下次再遇到可以直接对照。5.1 gcc或make命令找不到报错特征bash: gcc: command not found或make: command not found。排查链路先确认是在“MSYS2 MINGW64”终端里操作不是MSYS2自带的MSYS终端。再执行pacman -S mingw-w64-x86_64-toolchain重新安装。如果装完还是没有检查C:\msys64\mingw64\bin是否在PATH里在MSYS2里执行echo $PATH看有没有/mingw64/bin这段。没有的话手动加export PATH/mingw64/bin:$PATH这是临时生效重新开终端会失效。更好的做法是在~/.bashrc里加上这一行。5.2 openssl头文件或库找不到报错特征configure阶段提示ssl.h not found或编译中报openssl/ssl.h: No such file or directory。排查链路先执行pacman -Qs openssl确认装了哪个版本的openssl包。如果只装了mingw-w64-x86_64-openssl一般没问题。关键是用pkg-config --cflags --libs openssl看输出是否正常如果命令无输出或报错说明pkg-config配置不对。可以手动检查C:\msys64\mingw64\lib\pkgconfig\openssl.pc文件是否存在。文件在但命令找不到执行export PKG_CONFIG_PATH/mingw64/lib/pkgconfig。如果之前装过32位工具链也可能冲突干脆统一只保留x86_64版本。5.3 并行编译导致的链接失败报错特征make -j8在链接阶段报一堆未定义的引用比如undefined reference to SSL_new但-j1时能编过。排查链路并行编译在某些旧版本Nginx或依赖库组合下确实会踩到依赖顺序问题目标文件还没生成就进入链接阶段。解决办法很简单降低并行度直接用make -j2或干脆make编译时间多等一会但稳定性高很多。如果你用的Nginx是1.26.x的新版本这个概率已经很低但遇到报错先别怀疑库降并行度重试是最快的排查动作。5.4 运行exe提示缺少DLL报错特征双击nginx.exe弹窗提示libssl-3-x64.dll not found或者libpcre2-8-0.dll not found。排查链路这是MinGW动态链接没打静态导致的。两种方案任选把C:\msys64\mingw64\bin里的对应DLL复制到nginx.exe同目录或者在configure时给--with-ld-opt-static重新编译。静态编出的exe一般2到3MB运行时不依赖任何MSYS2环境。我自己测试时喜欢用动态发布给别人时必用静态。5.5 configure通过但make找不到pcre报错特征make阶段报pcre2.h: No such file or directory但configure时没有报错。排查链路Windows下pcre2的头文件在C:\msys64\mingw64\include库在C:\msys64\mingw64\lib。nginx的configure在win32下对pcre2的探测逻辑偶尔会漏。解决办法是在--with-cc-opt里显式加-IC:/msys64/mingw64/include示例./auto/configure --with-cc-opt-O2 -IC:/msys64/mingw64/include --with-ld-opt-static -LC:/msys64/mingw64/lib ...原理就是告诉编译器头文件在哪、链接器库文件在哪不依赖自动探测。这条经验对任何第三方模块都适用遇到“头文件找不到”时先看路径对不对。6. MSVC路线的额外准备给需要发布和调试的人MinGW路线省事但有些场景绕不开MSVC。比如你编译的第三方C模块用了MSVC特有的代码、需要生成PDB调试符号配合WinDbg分析崩溃转储、或者对性能压测有极严苛要求那还是要切到MSVC路线。6.1 需要额外补齐的四样东西比起MinGW路线MSVC路线要补四样东西Visual Studio Build Tools是最重的去微软官网下载安装时勾选“使用C的桌面开发”默认会带MSVC编译器和Windows SDK。接着装Strawberry PerlOpenSSL源码编译依赖它装完要把C:\Strawberry\perl\bin和C:\Strawberry\c\bin加进PATH。然后装NASMOpenSSL在x64桌面环境下需要NASM来做汇编优化不装的话就要在OpenSSL的Configure阶段加no-asm性能会差一些。最后是CMake用来构建PCRE2库。6.2 MSVC编译的整体流程差异流程骨架和MinGW路线一致但每个环节的工具变了。三个依赖库要自己编译不能指望包管理器。PCRE2用CMake生成VS工程后编译zlib直接nmake -f win32/Makefile.mscOpenSSL用perl Configure VC-WIN64A配置后执行nmake。Nginx的configure脚本依然需要MSYS2的bash环境运行但你必须在“x64 Native Tools Command Prompt for VS 2022”这个开发者命令行里启动bash否则cl.exe不在PATH里configure检测不到MSVC编译器生成的Makefile就是错的。configure参数里要加--with-cccl让nginx明确知道用的是微软编译器。make阶段有讲究configure生成objs/Makefile后退出bash回到VS开发者命令行里执行nmake -f objs/Makefile不能直接输make因为MSVC工具链里没有GNU makenmake是微软自己的构建工具。跑完后产物在objs\nginx.exe。6.3 什么时候必须走这条路给一个真实的判断经验如果你编译Nginx是为了自己做功能测试、内网小规模部署MinGW版本完全够用。如果是为了给客户交付、做性能基准测试、或者排查一个只有在Release版才出现的诡异问题那建议老老实实走MSVC路线。因为官方二进制就是MSVC编译的同样的编译器产出的行为才最接近“官方标准”。另外MSVC路线编译出的exe不会像MinGW那样有一堆DLL依赖因为MSVC的C运行时库在Windows上默认存在或者可以静态链接。这也解释了为什么很多发布工具包里都是MSVC编译的结果拷贝即用兼容性最好。最后再分享一点个人经验现在我自己编译Nginx内网测试和功能验证基本都用MSYS2MinGW这条快速路线真正对外发布的版本才会切到MSVC去编一遍。两条路线走了几轮之后会发现工具就是那几样真正的门槛不是工具安装而是搞懂每个依赖在构建链路里的位置configure脚本依赖bashOpenSSL依赖Perl和NASMPCRE2负责正则zlib负责压缩SSL负责HTTPS。把这条链上的角色都认清了以后无论是Nginx升级还是换第三方模块心里都有一本账。一个小技巧收尾把常用configure参数写成一个build.sh脚本放在源码目录外面每次编译直接bash build.sh不用重复敲一大串参数。如果换了Nginx版本只需改脚本里的源码目录路径。这个习惯帮我省了不少事你试了就知道。本文还有配套的精品资源点击获取