企业官网建设流程全解析

1. location匹配规则：转发配置里最容易被忽略的地基

不要急着去看proxy_pass怎么写。URL转发能不能按你设想的方向走，百分之八十取决于location匹配这一步。我见过太多人拿着"为什么我的/api请求跑到index.html去了"这种问题来问，翻配置文件一看，location / 写在了最前面，正则也没用对，转发目标自然全乱套。

先明确一个概念：Nginx里的"路由匹配"，本质上是针对请求URI的location指令匹配。它不像后端框架那样有Controller层路由表，而是在HTTP层直接按你写的规则去比对URI，命中哪块就把请求交给哪块处理。理解了这一点，下面这些规则就顺了。

1.1 五种匹配方式，一张表记住优先级

location后面的修饰符决定了这个规则的匹配方式。这里先给出完整对照，再逐个说人话。

真正匹配时的判定顺序是这样走的：

1. 先把所有=精确匹配拎出来，URI完全一致就直接用，根本不给后面的规则机会。
2. 再查普通前缀匹配（包括^~和没修饰符的），记住一个关键点：取匹配到的最长前缀，而不是按配置文件里的书写顺序。如果这个最长前缀带^~，OK，直接停止，正则不用看了。
3. 如果最长前缀没有^~，那就继续按顺序检查所有正则~和~*，第一个命中的正则胜出，不管它匹配的字符长度是多少。
4. 正则也没命中，才回头用第2步里那个最长普通前缀。

这里有个特别容易踩的坑：正则匹配按书写顺序执行，所以你把location ~ \.php$写在location ~ \.(jpg|png)$前面，那同样命中这两个正则的请求，永远只会走php那个。规则之间不是按"谁更具体"竞争，而是按"谁先出现"竞争。

1.2 匹配流程推演：一个请求到底走哪条规则

假设配置里有下面这几个location：

server { listen 80; location = /login { return 200 'exact login'; } location ^~ /static/ { return 200 'static prefix'; } location ~ \.(jpg|png|gif)$ { return 200 'image regex'; } location /api/ { return 200 'api prefix'; } location / { return 200 'default'; } }

现在逐个推演请求URI的走向：

• /login：精确匹配=命中，返回 exact login。即使后面有location /这种万能前缀，也轮不到它。
• /static/logo.png：普通前缀里/static/和/都能命中，但/static/更长，且带^~，所以直接用 static prefix 返回，正则里的\.(png)$根本没机会执行。
• /api/user：普通前缀/api/命中，常规正则里没有匹配项，最终走 api prefix。这里如果加一条location ~ /api的正则，结果就不一样了，正则会抢先。
• /images/avatar.jpg：普通前缀只有/命中，但后面的正则有\.(jpg)$命中，所以最终走 image regex，而不是默认的/。

这个推演过程请务必自己多过几遍，尤其是^~的作用，它不是为了"更精确"，而是为了屏蔽正则干扰。典型的用法就是静态资源目录：你肯定不希望/static/js/app.js被某个正则规则半路截胡。

1.3 最容易模糊的=和^~场景

=在实践里用得不算多，但一旦用就要用对。它适合那种"绝对路径路由"的场景，比如精准拦截某个特殊的URL：

location = /favicon.ico { log_not_found off; access_log off; }

这个配置几乎是所有站点必备的，精确匹配到favicon请求后直接静默处理，不产生404日志噪音。还有像/robots.txt、/.well-known/下的某些固定路径，也适合用=单独摘出来。

^~则建议在配置静态资源目录、文件上传目录、甚至某些跟正则规则容易混淆的路径时多用。比如你要给某个后台管理路径做单独的静态文件映射，又怕正则干扰，^~就是你的保险锁。

我在实际项目中见过一个反例：有人把字体文件请求写到location ~* \.(eot|ttf|woff|svg)$，结果和前端框架自带的location /assets/冲突，导致子目录下的字体总是404。最后排查半天，就是正则优先级把前缀匹配压住了。解决方式也很简单，把静态目录改成location ^~ /assets/就立刻安静了。

2. proxy_pass转发逻辑：斜杠、URI替换与身份信息传递

location匹配完了，接下来才是转发重头戏：proxy_pass。这一步的坑主要集中在两个地方：URI到底怎么拼、转发后后端拿到的信息是否完整。很多人配出来接口能通，但路径多了一段少了一段，大部分都是斜杠问题。

2.1 带斜杠与不带斜杠：转发路径的两种语义

这是proxy_pass最核心的规则。你可以把proxy_pass的目标地址分成两种形态：

• 不带URI形态：proxy_pass http://backend:8080;（地址里只有协议、域名、端口，没有路径）
• 带URI形态：proxy_pass http://backend:8080/;或proxy_pass http://backend:8080/newpath/;（地址里有路径，哪怕只是一个斜杠）

这两个形态下的URI拼接逻辑完全相反：

口诀是：不带URI，原样转发；带URI，前缀替换。

前缀替换的意思是：location匹配到的那一段路径（比如/api/），会被替换成proxy_pass里面写的URI（比如/或/new/），剩下的路径部分原封不动拼在后面。

我用场景化方式再拆一遍。前端请求/api/user，后端服务实际期望的是/user，那配置应该是：

location /api/ { proxy_pass http://192.168.1.10:8080/; }

如果后端期望的也是/api/user，那就别画蛇添足加斜杠：

location /api/ { proxy_pass http://192.168.1.10:8080; }

这里有个隐蔽的细节：如果把location写成location /api而不是location /api/，再配上带斜杠的proxy_pass，那请求/api/user匹配到/api后，替换掉的是/api这部分，结果变成/user，前缀斜杠被吞了。这种小差别线上排查特别费时间，建议从一开始就统一风格：location路径结尾带不带斜杠，一定要和proxy_pass里的URI配合考虑，不要随手写。

2.2 正则location与proxy_pass的冲突

需要注意一个硬性限制：当location是用正则形式（~或~*）匹配的时候，proxy_pass后面不能带URI部分。也就是说：

location ~ ^/api/(.*)$ { proxy_pass http://backend:8080/v2/$1; # 这样写不合法 }

正则location想重写路径，正确做法是搭配rewrite：

location ~ ^/api/(.*)$ { rewrite ^/api/(.*)$ /v2/$1 break; proxy_pass http://backend:8080; }

rewrite配合break标志改写URI后，proxy_pass再原样转发，这样就能实现路径重组。这个组合拳在网关改造、接口版本迁移时特别实用。

2.3 转发后后端还能拿到客户端真实IP吗

热词里那个"ip头部的五元组信息 nginx转发会带吗"，其实问的就是这个。先说结论：TCP层面的五元组在转发后必然改变，因为nginx跟后端建立了新的TCP连接，后端看到的源IP是nginx所在机器的IP，源端口也是nginx随机分配的端口。你没法在传输层保留客户端的原始IP和端口。

但应用层可以用请求头把这层信息补回来。常规做法是加这几个header：

proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

• $remote_addr：直连nginx的客户端IP，也就是真实用户IP（如果前面还有一层CDN或LB，这里就是那层设备的IP）。
• $proxy_add_x_forwarded_for：把$remote_addr追加到已有的X-Forwarded-For头后面，形成链路记录。每经过一层代理就追加一个IP，所以后端拿到的是一个逗号分隔的IP列表，最左侧通常是最原始的客户端IP。

后端Java服务里获取真实IP的写法一般是优先取X-Forwarded-For的第一个非unknown地址：

String ip = request.getHeader("X-Forwarded-For"); if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) { ip = request.getHeader("X-Real-IP"); } if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) { ip = request.getRemoteAddr(); }

还有一个容易踩的：如果后端服务本身也按域名做虚拟主机分流，那你需要显式传递Host头。默认Nginx会传客户端请求里的Host，但有时候你想让它固定成某个内部域名，可以：

proxy_set_header Host api.internal.svc;

除非明确知道自己在做什么，否则建议先保留$host，等后端报"Invalid Host header"这类错误时再针对性调整。

3. 真实场景中的URL转发配置：多应用、SPA与动静分离

规则讲完，落到实际部署。这部分我把最常见的几类转发需求串起来，直接给可抄的配置。

3.1 一个域名下同时部署前端和后端：路径分流

最常见的场景：https://example.com/是前端页面，https://example.com/api/是后端接口，两者共用80/443端口。用location路径分流最合适：

server { listen 80; server_name example.com; location / { proxy_pass http://127.0.0.1:3000; # 前端Node服务，或静态文件目录 } location /api/ { proxy_pass http://127.0.0.1:8080; # 后端Java/Go服务 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }

这个配置的好处是浏览器不用跨域，前端代码里直接请求/api/xxx走同源策略，后端也不用配CORS。如果后端接口路径本身不带/api前缀，记得按前面说的前缀替换规则，把proxy_pass改成http://127.0.0.1:8080/。

3.2 多个项目共用一个Nginx：多server与多location的选择

手里有好几个Web项目要同时部署，一共两种隔离方式：

• 不同域名或端口：用多个server块，每个server配自己的server_name和listen。
• 同域名不同路径：用多个location，各自指向不同的上游或目录。

我建议按业务边界来选。如果几个项目面向的用户群体不同、未来域名要独立、SSL证书要分开管理，那必须用server隔离。如果只是同一个站点下的功能模块（比如门户站和后台管理），用location路径区分更省事。

下面是一份"一个nginx挂两个前端+一个后端"的完整示例：

server { listen 80; server_name www.example.com; # 门户网站，部署到 /var/www/portal location / { root /var/www/portal; index index.html; try_files $uri $uri/ /index.html; } # 后台管理系统，独立单页应用 location /admin/ { alias /var/www/admin/; index index.html; try_files $uri $uri/ /admin/index.html; } # 后端接口统一走 /api location /api/ { proxy_pass http://127.0.0.1:8080; } }

这里用了alias而不是root，是因为/admin/目录下的文件实际存放在/var/www/admin/，而静态资源的URI路径里包含/admin/这个前缀，alias能把URI里的/admin/直接映射到物理路径，root则会把完整的URI路径拼到root后面，导致找错文件。

3.3 SPA刷新404：try_files的经典用法

Vue、React这类单页应用部署后，用户访问首页没问题，但一刷新/user/123这个路由就404。原因很简单：浏览器请求的是/user/123，静态服务器上根本没有这个文件，Nginx直接返回404。

解决办法就是用try_files把不存在的路径全部重写回index.html，由前端路由自己接管：

location / { root /var/www/portal; index index.html; try_files $uri $uri/ /index.html; }

解释一下try_files的匹配逻辑：先尝试按原始URI找文件（$uri），找不到就尝试找目录（$uri/），再找不到就内部重定向到/index.html。这样前端路由就能在JS层解析URL并渲染对应组件。

后端接口的location不要加try_files，否则接口路径落到前端路由里，会出现接口返回HTML的诡异问题。你要是碰到过"接口返回了index.html内容"，十有八九就是try_files写到了/api/里面。

3.4 静态资源分离与缓存

为了减轻后端压力，图片、CSS、JS这些静态资源可以直接交给Nginx处理。可以把匹配规则和缓存头组合起来：

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ { expires 7d; add_header Cache-Control "public, max-age=604800"; access_log off; try_files $uri =404; }

这里正则不区分大小写，.JPG也能命中。expires 7d让浏览器缓存7天，减少重复请求。注意如果这些资源被反向代理到CDN或对象存储，那这里要改成proxy_pass，把缓存头放在proxy层控制。

4. 转发之外的收尾设置：响应头、请求体与超时控制

URL转发通了，不代表就完事了。生产环境里经常遇到的"Nginx转发后响应头泄漏""上传大文件直接断连""长连接莫名断开"，都来自这一节的内容。

4.1 隐藏响应头和版本号

默认情况下Nginx会在响应头里带上Server: nginx/1.24.0，后端如果用了PHP之类的语言，还会带X-Powered-By。这些信息等于告诉别人你用的是哪个版本，方便别人按版本找漏洞，所以能隐藏就隐藏。

server_tokens off; proxy_hide_header X-Powered-By;

server_tokens off之后，Server头仍然存在，但版本号没了，只显示nginx。proxy_hide_header的作用是禁止把后端的某个响应头转发给客户端。注意这里不是彻底删掉后端响应里的头，而是"不透传给客户端"。

如果想加一个自己的服务标识，可以：

add_header X-Server-Name "my-nginx-01" always;

always参数确保即使是4xx/5xx响应也带上这个头，否则默认只在2xx/3xx时添加。

4.2 请求体大小与上传超时：为什么超过1G就断

Nginx默认允许的客户端请求体大小只有1MB。有人上传大文件超过1G，请求直接被Nginx挡掉，表现就是"请求没到后端就断了"，日志里能看到413 Request Entity Too Large。

如果你明确要支持大文件上传，调整这组参数：

server { client_max_body_size 1024m; client_body_timeout 60s; client_body_buffer_size 16k; location /upload/ { proxy_pass http://127.0.0.1:8080; proxy_read_timeout 300s; proxy_send_timeout 300s; proxy_connect_timeout 60s; } }

• client_max_body_size：请求体上限，按业务需求调整，不传大文件就别乱调大。
• client_body_timeout：读取客户端请求体的超时时间，网络差的时候防止连接一直挂着。
• proxy_read_timeout：等待后端响应的时间，不是整个请求的最长时间。后端处理一个接口要3分钟，这个值就得大于180s，否则Nginx会主动断开，返回504。
• proxy_send_timeout：Nginx向后端发送请求数据的超时时间，上传大文件时尤其重要。
• proxy_connect_timeout：与后端建立TCP连接的超时时间，后端负载高、accept队列满时容易触发。

热词里那个"为什么超过1g nginx就断呢"，基本就是client_max_body_size没调、proxy_read_timeout太短、或者后端本身有上传大小限制三个原因之一。排查时先看Nginx错误日志是411（Length Required）、413（Body Too Large）还是504（Gateway Timeout），方向完全不同。

4.3 WebSocket与SSE长连接转发

如果转发目标涉及WebSocket或SSE，默认配置会导致连接频繁断开。

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; }

Connection "upgrade"是WebSocket握手的硬性要求。proxy_http_version 1.1也很关键，因为默认Nginx向后端发起的是HTTP/1.0请求，而HTTP/1.0不支持Upgrade头。proxy_read_timeout不调大的话，空闲的连接会被Nginx按默认60秒掐断，前端会错误触发断线重连逻辑。

SSE（Server-Sent Events）则要关掉代理缓冲，否则事件流会被攒着一次性推给客户端：

location /events/ { proxy_pass http://127.0.0.1:8080; proxy_buffering off; proxy_cache off; proxy_set_header Connection ''; proxy_http_version 1.1; proxy_read_timeout 3600s; }

proxy_buffering off是SSE的关键，它让响应内容边到边转，不做缓冲积累。如果不清除Connection头，后端keep-alive和SSE可能会互相干扰。

5. 排查调试三板斧：499/502/504与实时日志追踪

配置写得再熟练，线上出了问题也得有条不紊地查。这一章把Nginx转发问题最常见的定位路径完整走一遍。

5.1 先跑这三条命令

nginx -t nginx -T tail -f /var/log/nginx/error.log

nginx -t检查语法，报错会精确到文件和行号。nginx -T输出解析合并后的完整配置，这一步特别有用：有时候你改了某个子配置文件，但主配置里没include，或者多个文件里重复定义了同一个server块，自己看半天看不出来，nginx -T直接展示最终生效的版本。日志级别的动态调整也很实用：

error_log /var/log/nginx/error.log notice;

改成debug级别能看到upstream连接、SSL握手、header传递的完整流程，但生产环境别长期开，日志量太大。

5.2 手把手定位一次502

假设配置了API转发，访问时返回502。502的意思是Nginx作为网关，没法从上游（后端服务）拿到有效响应。按这条链路查：

1. 看error.log里的具体报错。最常见的两种：

   • connect() failed (111: Connection refused) while connecting to upstream：后端端口根本没监听，或者监听地址不是nginx访问的那个。检查后端是否启动、监听地址是0.0.0.0还是127.0.0.1、端口是否一致。
   • connect() failed (113: No route to host)：网络不通，防火墙或安全组把端口挡了。这时候先curl -v http://127.0.0.1:8080/health在Nginx服务器上验证，curl能通再查nginx配置，curl也不通那就是后端网络问题。

2. 确认后端是否健康。在Nginx所在机器上执行：

curl -I http://127.0.0.1:8080/api/health

如果curl正常，再用Nginx转发一次，对比看看。如果curl也502，说明是后端服务本身的问题，Nginx配置再正确也没用。

3. 检查proxy_pass是否写对了。注意目标地址后面的路径部分会导致全部路径变掉，先用最简单的proxy_pass http://127.0.0.1:8080;排除斜杠问题。

5.3 499和504到底是谁的锅

• 499：客户端在Nginx等待后端响应期间主动断开了连接。常见于用户刷新页面、取消请求、或者客户端超时设置比Nginx的proxy_read_timeout短。查这个状态码时重点看两点：一是访问日志里499出现时对应URL是不是耗时特别长，二是前端的请求超时配置是否需要调整。
• 504：Nginx等待后端响应超过了proxy_read_timeout的设定值。这是明晃晃的"后端太慢"。重点排查后端接口逻辑、数据库查询、第三方调用，同时可以适当调大proxy_read_timeout作为缓解。
• 502：后端响应无效或无法连接。除了上面说的连接拒绝，还可能是后端返回了非法响应头、FastCGI进程崩了。如果是PHP-FPM场景，常见原因是fastcgi_pass配置的socket路径不对。

5.4 自定义日志格式：把转发细节打出来

默认的access.log格式看不到upstream信息，排查问题不够用。建议自定义一个log_format：

log_format upstream '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent upstream:$upstream_addr ' 'upstream_status:$upstream_status upstream_response_time:$upstream_response_time ' 'request_time:$request_time'; access_log /var/log/nginx/access.log upstream;

加了$upstream_addr、$upstream_status、$upstream_response_time之后，日志里能直接看到：

• 请求被转发到哪个后端地址（$upstream_addr）
• 后端返回的状态码（$upstream_status）——5xx到底是Nginx返回的还是后端返回的，一眼分辨
• 后端处理耗时（$upstream_response_time）和Nginx整体耗时（$request_time）对比，能快速判断瓶颈在哪层

我遇到过日志里$upstream_status显示200但$status是502的情况——那是后端已经把响应发回来了，但Nginx在接收响应时出了问题，多半是响应头格式异常或后端连接提前关闭，排查方向就完全不一样了。

5.5 查看PID与进程、平滑重载

热词里有"怎么看当前nginx的pid"，这属于运维基本功。三种方式：

cat /var/run/nginx.pid ps aux | grep nginx nginx -s stop

nginx -s reload是平滑重载配置，原理是master进程重新读取配置，然后向worker进程发送信号，让旧worker处理完手头请求后优雅退出，新worker按新配置接管。改完配置先nginx -t再nginx -s reload，这条流程熟了，日常操作基本无感。如果改了配置但没生效，先想是不是没reload、或者改的不是被include的文件。

我在实际工作里养成了一个习惯：每次改配置文件前先把当前版本备份一份，文件名带时间戳；每次reload完去看一眼error.log有没有新的warn级日志。这个习惯帮我避免过很多次"改完配置发现线上流量走错上游"的事故。配置转发这件事，规则本身并不复杂，真正考验人的是面对一条错误日志时，能不能沿着请求从客户端到Nginx再到后端的路径，一步一步把问题卡在某一层。