Windows 编译 Nginx 工具链全解析：从 MSYS2 到 nginx.exe 实战

简介本资源面向需要在Windows 10环境下自行编译Nginx的开发者与运维人员尤其适合希望集成http-flv模块、实现HTTP-FLV直播推流的技术人员。资源以Nginx 1.20.2源码为核心同时打包了http-flv模块源码以及OpenSSL、PCRE、Zlib等依赖库源码并附带ActivePerl、msys2、sed等编译工具省去逐一下载与版本匹配的麻烦。压缩包共28个文件约102.07MB包含pl脚本、conf配置、html页面、license许可、exe可执行文件及vim、utf编码映射等类型覆盖编译、配置与运行所需的主要环节。目前已有541人学习下载说明该方案在Windows编译Nginx场景中具备一定参考价值。读者可据此搭建完整的编译环境理解模块集成与依赖处理流程减少环境配置中的常见阻碍。1. Windows 上编译 Nginx 到底需要哪些工具从一个 .rar 工具包说起很多人第一次在 Windows 上折腾 Nginx 编译都是被一个.rar工具包领进门的。下载下来解压一看里面躺着 MSYS2、Perl、Strawberry、nasm、pcre、zlib、openssl 一堆东西名字都认识但谁先装、谁配环境变量、谁和谁版本要对上全靠猜。结果就是configure报错、make报错、链接阶段找不到-lssl来回折腾一整天。这篇笔记就围绕「Windows 编译 Nginx 必要工具」这件事把工具链的组成、每个工具为什么必须存在、怎么一步步把源码编成可用的nginx.exe讲清楚。适合两类人一是想自己改 Nginx 模块、加第三方补丁的开发者二是需要特定版本、特定编译参数官方 exe 满足不了需求的运维。读完你能独立搭出一套可复现的编译环境也知道哪些坑是版本和路径带来的玄学问题。2. 工具链拆解每个工具在编译流程里干什么Windows 原生没有 Nginx 官方支持的编译环境Nginx 的构建系统是 Autoconf 风格的configuremake这套东西天生属于 Unix。所以核心思路是在 Windows 上模拟出一个足够像 Unix 的 shell 和工具集让configure脚本能跑让make能调编译器最后产出 PE 格式的nginx.exe。2.1 MSYS2 与 MinGW-w64编译环境的地基MSYS2 提供 POSIX 兼容层和包管理器pacmanMinGW-w64 提供真正的 Windows 原生编译器gcc。两者配合configure脚本里的uname、sed、awk、rm才能正常工作同时编译产物是原生 Windows 程序不依赖 MSYS 运行时。安装 MSYS2 后务必用MinGW 64-bit那个快捷方式进入终端而不是 MSYS 终端。区别在于前者uname -s返回MINGW64_NT-10.0后者返回MSYS_NT-10.0Nginx 的auto/os/win32判断依赖这个字符串。# 在 MSYS2 MinGW64 终端里更新基础包 pacman -Syu # 安装编译必需的核心工具 pacman -S --needed base-devel mingw-w64-x86_64-toolchain # 单独确认 gcc、make、pkg-config 都在 which gcc make pkg-configbase-devel里包含make、diffutils、grep、sed等mingw-w64-x86_64-toolchain是编译器全家桶。which的输出应该都指向/mingw64/bin/下如果指向/usr/bin/说明你进错了终端。2.2 Perl 与 nasmconfigure 脚本和汇编优化Nginx 的configure是 Perl 脚本没有 Perl 直接报perl: command not found。MSYS2 里可以直接装perl但更稳的做法是用 Strawberry Perl 或 MSYS2 自带的mingw-w64-x86_64-perl避免路径里出现空格。nasm 是汇编器OpenSSL 编译时大量使用汇编优化缺了它 OpenSSL 会退化成纯 C 实现性能下降明显而且某些版本直接编译失败。# MSYS2 里安装 perl 和 nasm pacman -S --needed mingw-w64-x86_64-perl nasm # 验证 perl -v nasm -vperl -v要能看到版本号nasm -v同理。如果perl指向的是 Windows 系统里某个旧版本用pacman装的会覆盖路径优先级确认which perl在/mingw64/bin/perl。2.3 PCRE、zlib、OpenSSL三个必须预编译的依赖库Nginx 的 rewrite 模块依赖 PCREgzip 模块依赖 zlibHTTPS 依赖 OpenSSL。这三个库在 Windows 上不能像 Linux 那样直接apt install需要先编译成静态库再在configure时用--with-*指过去。常见做法是分别下载源码各自configure make make install到统一前缀比如/mingw64或自定义的C:/nginx-deps。以 OpenSSL 为例# 假设源码在 /c/src/openssl-3.x cd /c/src/openssl-3.x ./Configure mingw64 no-shared --prefix/c/nginx-deps/openssl make -j4 make installno-shared生成静态库避免运行时 DLL 找不到--prefix指定安装路径后面 Nginx 配置时直接引用。PCRE 和 zlib 类似但 PCRE 要注意用 PCRE2 还是 PCRE1Nginx 新版本对 PCRE2 支持更好老版本可能只认 PCRE1。提示三个库的位数必须和编译器一致64 位 MinGW 就编 64 位库混用 32 位会在链接阶段报file format not recognized。3. 从源码到 nginx.exe完整编译步骤与参数工具齐了接下来是实际编译。整个过程分四步准备源码目录、跑configure、make、验证产物。每一步都有容易翻车的地方尤其是路径和参数。3.1 下载源码与目录结构约定Nginx 源码从官网下载.tar.gz解压到 MSYS2 能访问的路径。建议放在C:/src/nginx-x.x.x避免中文和空格。依赖库也统一放在C:/nginx-deps下形成固定结构方便脚本复用。# 目录约定示例 /c/src/nginx-1.24.0 # Nginx 源码 /c/nginx-deps/pcre # PCRE 安装前缀 /c/nginx-deps/zlib # zlib 安装前缀 /c/nginx-deps/openssl # OpenSSL 安装前缀路径用正斜杠MSYS2 里C:/等价于/c/。不要用反斜杠configure脚本对反斜杠处理不一致容易把参数截断。3.2 configure 参数逐个说明进入 Nginx 源码目录执行configure。下面是一组经过验证的参数每个都解释清楚。cd /c/src/nginx-1.24.0 ./configure \ --prefix/c/nginx \ --with-ccgcc \ --with-cppgcc \ --with-cc-opt-I/c/nginx-deps/pcre/include -I/c/nginx-deps/zlib/include -I/c/nginx-deps/openssl/include \ --with-ld-opt-L/c/nginx-deps/pcre/lib -L/c/nginx-deps/zlib/lib -L/c/nginx-deps/openssl/lib -lpcre -lz -lssl -lcrypto \ --with-pcre \ --with-zlib/c/nginx-deps/zlib \ --with-openssl/c/nginx-deps/openssl \ --with-http_ssl_module \ --with-http_gzip_static_module \ --with-http_stub_status_module--prefix是安装路径最终make install会把文件放过去。--with-cc-opt和--with-ld-opt分别给编译器和链接器传头文件、库文件路径。--with-pcre不带路径时 Nginx 会尝试自己编译 PCRE但 Windows 上经常失败建议显式指定。--with-openssl同理指向预编译好的 OpenSSL 前缀。如果报checking for PCRE library ... not found先确认-I和-L路径下确实有pcre.h和libpcre.a。如果报undefined reference to SSL_CTX_new说明-lssl -lcrypto顺序或路径不对链接器对库顺序敏感被依赖的库放后面。3.3 make 与 make install 的注意事项configure成功后生成Makefile直接make。Windows 上并行编译有时会出问题建议先单线程跑一遍确认无误再用-j。make # 成功后再 make installmake过程中如果报nasm: command not found回到 2.2 确认 nasm 装好。如果报cannot find -lpublic这类通常是某个依赖库没编好或路径写错检查C:/nginx-deps下对应库的lib目录。make install后/c/nginx下会出现conf、html、logs、sbin等目录sbin/nginx.exe就是最终产物。用./sbin/nginx -V查看编译参数确认 SSL、gzip 等模块都编进去了。4. 避坑与排查Windows 编译 Nginx 最常见的 5 个翻车点这一章全是血泪经验每条都按「现象 → 原因 → 解决」写遇到问题直接对号入座。4.1 现象configure 报C compiler gcc is not found原因MSYS2 终端进错或者gcc不在 PATH。MSYS 终端里没有 MinGW 的 gcc只有 MSYS 自己的工具。解决关掉当前终端用开始菜单里的MSYS2 MinGW 64-bit重新打开which gcc确认在/mingw64/bin/gcc。如果还不行pacman -S mingw-w64-x86_64-gcc重装。4.2 现象链接阶段报undefined reference to pcre_compile原因--with-ld-opt里-lpcre没加或者 PCRE 库路径不对或者 PCRE 编成了动态库但没放对位置。解决确认C:/nginx-deps/pcre/lib下有libpcre.a或libpcre.dll.a。如果是动态库把bin目录加到 PATH或者干脆重新用--disable-shared编静态库。链接参数里-lpcre必须出现在使用它的目标文件之后。4.3 现象make 到一半报nasm: not found或 OpenSSL 编译中断原因nasm 没装或者 OpenSSL 的Configure没指定mingw64目标导致汇编文件生成失败。解决pacman -S nasm装好nasm -v验证。OpenSSL 重新./Configure mingw64 no-shared不要用默认的linux-x86_64目标平台错了汇编语法不兼容。4.4 现象编译成功但运行nginx.exe报缺少libssl-3-x64.dll原因OpenSSL 编成了动态库nginx.exe依赖 DLL但 DLL 不在同目录或 PATH 里。解决要么把 OpenSSL 的bin目录加到系统 PATH要么重新用no-shared编静态库再链接。生产环境建议静态链接少一个依赖少一个故障点。4.5 现象make install后nginx -V显示没有--with-http_ssl_module原因configure时参数没写对或者configure缓存了上一次的结果。解决删掉源码目录下的objs文件夹和Makefile重新跑configure确认输出里 http_ssl_module带加号。nginx -V的输出是编译时固化的改参数必须重新编译。5. 进阶用脚本固化工具链与验证编译产物手工敲一遍能跑通但换台机器又要重来。我一般会把整个流程写成一个build.sh放在 MSYS2 里执行把路径、版本、参数全部变量化。这样下次升级 Nginx 版本只改变量就行。#!/usr/bin/env bash set -euo pipefail NGINX_VER1.24.0 DEPS/c/nginx-deps SRC/c/src # 检查工具 for cmd in gcc make perl nasm; do command -v $cmd /dev/null || { echo 缺少 $cmd; exit 1; } done # 编译 Nginx cd $SRC/nginx-$NGINX_VER ./configure \ --prefix/c/nginx \ --with-cc-opt-I$DEPS/pcre/include -I$DEPS/zlib/include -I$DEPS/openssl/include \ --with-ld-opt-L$DEPS/pcre/lib -L$DEPS/zlib/lib -L$DEPS/openssl/lib -lpcre -lz -lssl -lcrypto \ --with-http_ssl_module \ --with-http_gzip_static_module make -j4 make install # 验证 /c/nginx/sbin/nginx -Vset -euo pipefail让脚本遇到错误立即退出避免带着错误继续跑。command -v检查工具是否存在比直接调用后看报错更早发现问题。make -j4并行编译机器核多可以调大。验证环节除了nginx -V还可以实际启动一下用curl测 HTTPS 和 gzip。# 启动 Nginx /c/nginx/sbin/nginx # 测试 HTTPS如果配了证书 curl -k https://127.0.0.1 # 测试 gzip curl -H Accept-Encoding: gzip -I http://127.0.0.1 # 停止 /c/nginx/sbin/nginx -s stopcurl -I看响应头里有没有Content-Encoding: gzip有就说明 gzip 模块工作正常。HTTPS 返回 200 或 301 都算 SSL 模块加载成功。一个我踩过的坑MSYS2 的pacman -Syu更新后有时gcc版本跳变导致之前编好的依赖库 ABI 不兼容链接报一堆undefined reference。后来我习惯把依赖库和 Nginx 放在同一次会话里编或者用pacman锁定版本。编译这种事环境一致性比什么都重要别在编译中途更新工具链。希望帮到你。本文还有配套的精品资源点击获取