第一次在Windows上认真折腾nginx反向代理是被一个很朴素的需求逼的多个服务分别跑在8080、3000、8081端口我想让整个团队只记一个入口地址再按路径自动转发到对应后端。当时第一个念头是IIS的ARR装完配置一圈发现各种不顺后来换nginx半小时就通了而且配置文件和Linux上几乎一模一样。这篇文章就结合我自己的实操经验把Windows下配置nginx反向代理这条路从头到尾捋一遍。适合在Windows开发机上做本地网关的人、需要在Windows服务器上部署多个Web项目的人以及那些被端口号、跨域、路径重写折腾到头疼的同学。内容偏实战每一步我都会说清楚为什么这么做争取你看完能直接照抄。1. 为什么Windows办公机上我仍首选nginx做反向代理很多人有个误区觉得nginx是Linux的专属工具Windows上只是能跑而已。这个印象不准确。nginx官方专门维护Windows版本而且配置语法、转发逻辑、日志体系与Linux版保持一致你在Windows上调通的配置几乎可以无缝迁移到Linux服务器。1.1 什么业务场景下你真的需要它先对齐概念。所谓反向代理简单说就是客户端请求先到nginxnginx按照规则把请求转发给内网或者本机的其他服务再把响应拿回来交给客户端。客户端只跟nginx打交道完全感知不到背后的服务。典型的场景有这么几类多个服务统一入口。比如你本机有Tomcat在8080、Node服务在3000、管理后台在8081你不想让用户记端口号就可以让nginx监听80通过路径区分转发。前后端分离联调。前端页面跑在3000端口后端接口在8080浏览器会有跨域限制。通过nginx代理后前端请求接口时走同一个域名和端口跨域问题直接消失。内网穿透的前置网关。公司内网有一台Windows服务器作为对外统一入口把所有流量按域名或路径分发到内网不同机器。简单的负载均衡。多个后端实例挂着同一个服务nginx按权重或轮询分发请求让整体吞吐更稳定。这些需求在Windows服务器上特别常见因为很多中小企业就是拿一台Windows Server当主机跑着各种杂七杂八的应用而nginx刚好能稳稳当当地当那个大门。1.2 Windows版和Linux版差异有多大直接说结论作为一个反向代理来讲日常用到的核心功能几乎无差别。我实测过同样的配置从Windows迁移到CentOS除了路径分隔符和启动方式其余完全不用改。但有几点差异你必须心里有数Windows版的性能上限低于Linux版。Linux下nginx可以轻松支撑上万并发连接Windows版基于Win32 API实现达到较高并发时瓶颈明显。中小规模应用、内网办公系统、开发环境完全够用但如果是高并发线上业务还是建议部署到Linux。部分模块在Windows下不可用。比如一些依赖Unix特性的模块你基本用不到但要知道有这回事。管理方式不同。Linux下常用systemctl或nginx -s reloadWindows下是双击exe或命令行直接操作后面我会细说。我个人的判断是开发机或内网Windows服务器上做反向代理nginx是性价比极高的选择不需要额外花时间学一套新工具配置文件又通用踩坑经验以后还能复用到生产环境。2. 下载、目录规划与启动第一关往往卡在80端口2.1 版本选择和目录结构从nginx官网下载Windows版本时你会看到两个版本线Stable version稳定版和Mainline version主线版。对于日常生产使用我建议选稳定版功能完全够用发布时间也更谨慎。比如我目前用的nginx/Windows-1.26.x系列用了很久没出过问题。下载下来是一个zip压缩包解压出来的目录长这样nginx-1.26.x/ ├── conf/ │ ├── nginx.conf │ ├── mime.types │ └── ... ├── contrib/ ├── docs/ ├── html/ ├── logs/ ├── temp/ └── nginx.exe一个很重要的经验不要把这个目录放在需要管理员权限才能写入的位置比如C:\Program Files。因为nginx在运行时会向logs目录写日志、向temp目录写临时文件如果你忘了用管理员身份启动很容易遇到没权限写日志这种莫名其妙的问题。我一般放在C:\nginx或D:\nginx简单干净。2.2 启动、停止和重载的正确姿势双击nginx.exe是最直观的方式但很不推荐因为没有任何反馈你不知道是否启动成功而且控制台窗口一关nginx可能还在后台跑着容易产生混乱。我习惯在命令行里操作。首先进入nginx目录然后执行cd /d C:\nginx start nginx.exestart命令会新开一个窗口nginx在后台持续运行。此时你可以打开浏览器访问http://localhost如果看到Welcome to nginx!页面说明启动成功。修改配置文件之后需要让配置生效最安全的做法是先测试配置再重载nginx.exe -t nginx.exe -s reload-t会检查nginx.conf语法和配置逻辑输出syntax is ok和test is successful才说明没问题。这里又有个Windows专属坑如果配置里写错了路径分隔符-t不一定会报错但运行时日志会找不到文件所以路径规范要养成肌肉记忆统一用正斜杠/。停止服务用nginx.exe -s quitquit是优雅停止nginx会等当前正在处理的请求完成后再退出。如果你只是想快速杀掉可以别这么做除非真的卡死了否则别用任务管理器强杀nginx.exe。2.3 端口冲突80端口被占用的理想排查顺序配置里写listen 80启动后却发现nginx没起来十有八九是80端口被别的程序占了。最常见的元凶依次是IIS、SQL Server Reporting Services它默认抢80、Skype、还有各种开发工具的本地服务。排查方法很简单先看谁在监听80netstat -ano | findstr :80命令输出的最后一列是进程的PID接着用任务管理器查这个PID对应谁。如果tasklist显示的进程名像System、svchost.exe多半是HTTP.sys占了端口这种情况通常是IIS或某个系统服务在监听。可以再用tasklist | findstr PID定位到具体进程。如果是IIS占用的运行iisreset /stop可以临时释放如果你根本不需要IIS直接在启用或关闭Windows功能里关掉它。我的经验是在配置反向代理之前先把端口占用情况摸清楚能省掉后面一大半排查时间。这不只是新手的问题我见过不少老手在Windows上被这个卡过。3. 第一份可用的反向代理配置从8080到80的完整拆解3.1 最小配置逐行释义假设本机跑着一个后端服务监听8080端口你希望访问http://localhost时请求自动转发到这个服务。nginx.conf的http块里最好单独建一个server块别把所有东西都塞在默认配置里。server { listen 80; server_name localhost; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }我来逐条解释listen 80nginx监听本机的80端口接收所有发往该端口的HTTP请求。server_name localhost用来匹配请求的Host头。如果请求访问的是localhost就会落到这个server块。location /匹配所有请求路径相当于默认路由。proxy_pass http://127.0.0.1:8080;这是核心指令。nginx收到请求后把请求转发给127.0.0.1:8080上的服务。上面三行proxy_set_header尤为重要。如果不设置后端服务看到的请求来源是nginx的IP无法获取真实客户端地址也无法正确生成绝对链接。Host保持原始域名X-Real-IP和X-Forwarded-For用来追踪真实客户端IP。很多人问nginx转发会带原始IP吗答案就是靠这几行设置。系统集成、日志审计、IP白名单都依赖于它所以别省。3.2 proxy_pass是否带URI这一条必须刻在脑子里这是我在实战中发现理解门槛最高、也最容易踩坑的一点。proxy_pass的写法分两种情况行为完全不同情况一不带URI路径部分location /api/ { proxy_pass http://127.0.0.1:8080; }此时nginx将完整的原始请求URI传给后端。假设请求是/api/user后端收到的也是/api/user。情况二带URI路径部分location /api/ { proxy_pass http://127.0.0.1:8080/; }注意最后多了个/这表示替换规则location中匹配到的/api/会被替换成/。同一个请求/api/user后端收到的是/user。也就是说proxy_pass里除域名外的路径部分决定了原始URI的替换前缀。这个特性非常有用。比如你的前端项目部署在/app路径下但后端接口只认/你就可以用带URI的方式剥离前缀。反过来说如果你不理解这个机制在配置多个项目共用同一个nginx时经常会出现页面样式加载不出来接口404这类诡异问题根子都在这个前缀替换上。3.3 补全请求头信息反向代理本质上是一个中间人如果它原封不动转发请求某些场景下会出问题。典型的几个客户端通过HTTPS访问nginx但nginx到后端用的是HTTP。后端的程序比如Spring Boot如果根据请求协议生成链接会生成出http://的绝对地址导致页面跳转出错。这时需要加proxy_set_header X-Forwarded-Proto $scheme;客户端上传大文件时nginx默认的client_max_body_size是1MB超过就返回413。按需调大client_max_body_size 50m;后端需要客户端真实IP时除了X-Real-IP还需要让后端框架开启对X-Forwarded-For的信任否则拿到的是nginx地址。这一点在配置完后最好用后端的日志验证一下。头信息这块的原则是能透传的尽量透传不能乱加的不要乱加。我见过有同学在nginx里手写proxy_set_header X-Forwarded-For $remote_addr结果所有请求的真实IP都变成了nginx自己的IP比不传还糟糕。4. 多服务路由、路径重写与WebSocket4.1 用location做多后端分配真实项目中一个nginx对应多个后端服务是很普遍的。最简单的做法是根据路径区分比如/api/开头的请求给后端A/admin/给后端B其余给默认前端。server { listen 80; server_name example.local; location /api/ { proxy_pass http://127.0.0.1:8081; } location /admin/ { proxy_pass http://127.0.0.1:8082; } location / { proxy_pass http://127.0.0.1:8080; } }location的匹配优先级是精确匹配 前缀匹配^~ 正则匹配~或~* 普通前缀匹配。其中正则匹配是按配置文件里的顺序执行的所以正则规则要放在普通前缀之前免得被普通前缀抢走。这里我想强调一个实践细节在使用反向代理时/api/和/api两个路径在location匹配里不是同一回事。/api不会匹配/api/的前缀规则除非你专门做一个location /api很多接口路由异常就从这种细微差别开始。4.2 路径重写是反向代理里最绕的一个点多服务联调时路径往往对不上。比如前端通过/user-service/访问用户服务但后端实际路径是/user/。这时候需要使用路径替换也就是之前讲的proxy_pass带URI的用法location /user-service/ { proxy_pass http://127.0.0.1:8083/user/; }请求/user-service/list会变成后端的/user/list。注意替换是按前缀来的/user-service被换成/user。但如果URI携带了查询参数比如/user-service/list?page1nginx默认会保留查询参数不需要特殊处理。有些场景还会配合rewrite指令比如把带/index.php的旧路径改成新的location /forum/ { rewrite ^/forum/(.*)$ /$1 break; proxy_pass http://127.0.0.1:8084; }这个地方很容易纠结什么时候用proxy_pass带URI什么时候用rewrite我的判断依据是如果只是前缀替换用proxy_pass的URI参数更简洁如果要做正则级重写、参数重组就用rewrite。两者同时用的时候要记住rewrite在proxy_pass之前执行别把顺序搞反了。4.3 WebSocket需要显式声明升级头WebSocket和普通HTTP请求的兼容方式完全不同它靠HTTP的Upgrade头把协议从http升级到websocket。nginx默认的HTTP代理不会自动处理这个升级过程所以不加配置WebSocket连接大概率握手失败。配置其实很固定location /ws/ { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; }proxy_http_version 1.1非常关键因为HTTP/1.0默认不支持Upgrade头。我把proxy_read_timeout调到3600秒是因为WebSocket长连接如果长时间没消息nginx默认60秒就会切断连接导致前端频繁断线重连。这个参数对于聊天、推送类服务特别重要容易忽略。另外如果WebSocket后端跑在了多个实例上还需要考虑会话保持。因为WebSocket一旦建立所有消息都要发到同一台后端。可以用upstream加ip_hash实现upstream ws_pool { ip_hash; server 127.0.0.1:8080; server 127.0.0.1:8081; }ip_hash根据客户端IP计算哈希让同一客户端的请求始终落到同一台机器避免WebSocket连接分裂。这是做负载均衡时经常配合使用的一个细节。5. 502、404和日志Windows下反向代理故障排查链路反向代理配置好了不等于万事大吉。我在Windows上踩过很多坑这里分享一条完整的排查链路不是直接给你答案而是让你以后遇到同类问题知道从何入手。5.1 先从日志开始别瞎猜nginx的日志在logs目录下access.log记录所有访问请求error.log记录错误信息。配置里可以指定日志级别error_log logs/error.log warn;排查问题时我习惯先把级别临时调到info或debug跑完请求再改回来。因为默认的error级别太“含蓄”很多中间过程看不到。Windows下有个特有注意点logs/error.log这个路径是相对于nginx目录的所以启动nginx时的工作目录必须是nginx根目录这也就是为什么后面注册Windows服务时一定要设置工作目录。否则日志会写到奇怪的地方甚至报错。5.2 502 Bad Gateway的排查过程502是反向代理最常遇到的错误意思是nginx拿到了上游的错误响应或者根本没连上。我一般按下面的顺序排查第一确认上游服务真的活着。直接在浏览器或curl访问后端地址curl http://127.0.0.1:8080/health如果后端自己都打不开那就是后端问题跟nginx无关。第二确认nginx配置里的地址和端口没有写错。尤其是proxy_pass里的IP在Windows本机通信时我建议写127.0.0.1而不是localhost。原因是有时候localhost会被解析成IPv6的::1而你的服务只监听了IPv4的127.0.0.1连不上就返回502。这个坑在windows下非常常见很多人查了半天找不到原因其实就是一个IP解析问题。第三查看error.log。如果看到connect() failed (10061: No connection could be made because the target machine actively refused it)说明nginx确实尝试连接了目标端口但目标服务没有监听或防火墙拒绝了。第四检查防火墙入站规则。Windows防火墙默认会拦截来自外部机器的请求如果nginx和后端在同一台机器上一般不受影响但如果nginx要转发的目标是局域网内的另一台机器就需要在目标机器上放行对应端口。5.3 404、504和Windows平台特有的坑404不一定都是后端没这个接口。很多时候是路径重写出了问题比如proxy_pass的URI把请求路径拼接错了。这种问题在error.log里不一定有明显报错你需要在access.log里看看到底是哪个URI转到了哪个上游再跟后端的实际路由对一下。这也是为什么我一直强调要先理解前缀替换规则。504 Gateway Timeout表示nginx等待上游超时。比如后端某个接口要跑报表耗时超过默认的60秒nginx就主动断开了。解决办法是按需调大proxy_connect_timeout 10s; proxy_read_timeout 300s; proxy_send_timeout 300s;Windows平台还有几个坑容易阴人nginx配置文件的路径分隔符如果写反斜杠\部分指令会解析出错。规则是nginx配置里统一用正斜杠/比如error_log logs/error.log。不要在同一台Windows机器上连续双击多个nginx.exe。每个实例都会申请同样的端口和锁文件结果就是端口被一个隐藏进程占用新实例起不来。管理时只用命令行并且先用tasklist | findstr nginx确认有没有残留进程。Windows下nginx的html目录不能放中文名文件某些场景下有编码问题静态文件路径尽量用ASCII字符避免莫名其妙的乱码和404。我自己的习惯是使用nginx可视化配置工具没太大必要因为配置文件量级并不复杂反而直接改文本更清晰也方便版本管理。6. 让nginx在Windows后台常驻注册为Windows服务6.1 为什么不能只放一个快捷方式到启动文件夹如果只是本地开发命令行启动nginx就够了。但如果你在公司Windows服务器上部署总不能让服务器一重启就有人去点一下exe。很多人会把nginx快捷方式放进启动文件夹这个方案存在的问题是启动时机不可控而且nginx进程有没有起来、日志有没有写到预期位置都没有统一监控。正确的做法是把nginx注册成Windows服务交给服务管理器统一管理开机自动启动支持net start nginx、net stop nginx这样的标准命令。6.2 用NSSM注册服务Windows下把任意exe注册成服务我用得最顺手的是NSSMNon-Sucking Service Manager一个小工具完全免费功能很纯粹。你可以在NSSM官网下载解压后是一个可执行文件。注册命令如下nssm install nginx执行后会弹出图形界面在Application标签页里设置PathC:\nginx\nginx.exeStartup directoryC:\nginxArguments留空然后点Install service。这里最关键的设置是Startup directory。前面说过nginx的日志和配置路径是相对的如果工作目录不对nginx.exe启动后连conf/nginx.conf都找不到更别说写日志了。如果你不喜欢图形界面也可以用命令行直接设置nssm install nginx C:\nginx\nginx.exe nssm set nginx AppDirectory C:\nginx nssm start nginx之后可以通过Windows服务面板或命令行管理服务net start nginx net stop nginx sc query nginx这样nginx就变成了跟其他Windows服务一样的托管进程。服务器重启后会自动拉起nginx异常退出时服务管理器也会根据设置自动重启。6.3 服务化之后的管理建议把nginx注册成服务之后有几个细节值得注意。第一以后修改配置文件不需要重启服务执行一次nginx -s reload即可。但如果nginx是以服务方式运行的需要先找到nginx的PID再用nginx -s reload通知它重载配置。我一般这样操作tasklist | findstr nginx.exe拿到PID后nginx -s reload这个命令会自动读取logs/nginx.pid文件里的PID并发送信号正常情况下不需要手动指定PID。第二要习惯用nginx -t验证配置。实际上在正式reload之前先做一次语法检查已经成为我在Windows上最依赖的习惯。配置改错后如果直接reload轻则配置不生效重则nginx直接拒绝启动影响到线上服务。第三日志轮转要提前规划。Windows下nginx日志会一直增长时间长了容易占满磁盘。NSSM自带日志轮转功能但nginx自己的日志是写文件的更稳妥的做法是用NSSM的Rotate files功能或者自己写计划任务定期归档logs/access.log。如果忘了这事日志文件膨胀到几个GB以后排查问题时打开日志都费劲。还有一个小技巧是给nginx工作进程多开几个worker_processes。Windows版nginx默认也是1个worker如果你的机器是多核可以按CPU核心数适当调大worker_processes 4;但别盲目调到很大Windows下多worker对共享锁和socket处理的额外开销比Linux明显实测下来4到8个就差不多了再往上性能提升有限反而可能引入稳定性问题。另外nginx配置里如果使用了upstream做负载均衡Windows下也可以正常使用这对多实例部署很实用。我之前在一个Windows服务器上挂了三个后端实例nginx按权重分发请求配合ip_hash做会话保持跑了半年没重启过稳定性超出预期。最后再说一个我个人的体会nginx反向代理在Windows上最重要的不是记指令而是理解请求从客户端到后端服务之间的“路径变换”过程。理顺了路径替换、头信息、超时、会话保持这几个核心概念无论环境是Windows还是Linux你都能快速上手。遇到问题时从日志出发一步步反推回配置通常都能快速找到根因。