企业官网建设流程全解析

做后端开发或者运维的朋友，肯定都跟 Nginx 的location和proxy_pass打过交道。表面上看这两个指令都不难理解：location用来匹配请求路径，proxy_pass用来把请求转发给后端。但实际配置起来，遇到路径被截断、404、斜杠多一个少一个、正则匹配不生效这类问题，往往就是没有把这两个指令的联动逻辑彻底吃透。

这篇文章我会从一个偏实操的角度，把location匹配规则和proxy_pass转发行为掰开了讲清楚。不光是告诉你语法长什么样，还会说明每一个坑背后的原理是什么。无论你是刚接触 Nginx 的初级开发者，还是已经写过不少配置但偶尔还会被“路径问题”折磨的熟练工，这篇内容应该都能帮你省下不少排查时间。我会给出大量可直接复制的配置片段和真实场景，都是我实测下来比较稳妥的写法。

1. 核心概念：location匹配规则与proxy_pass转发逻辑的基础理解

很多人配置 Nginx 时会把location和proxy_pass当成两个独立部分来写，先写好 location 前缀，再填一个 upstream 地址进去。但实际出问题的时候，极大概率是因为这两者的组合关系没有理顺。尤其是proxy_pass后面到底带不带路径，这会直接决定后端收到的最终 URI 是什么样。

1.1 location前缀匹配与正则匹配的优先级

location指令的匹配方式看起来有很多种，常用的大概可以分为四类：

• location = /path：精确匹配，优先级最高。
• location ^~ /path：前缀匹配，并且一旦命中就不再继续检查正则表达式。
• location ~ /path和location ~* /path：正则匹配，前者区分大小写，后者不区分。
• location /path：普通前缀匹配，优先级最低，而且后续还会继续看正则。

优先级由高到低是这样的：精确匹配（=） → 前缀且强制终止（^~） → 正则匹配（~或~*，按配置文件顺序） → 普通前缀匹配（不带任何修饰符）。

这里有一个常见的误区：普通前缀匹配并不是“谁先写在前面谁生效”，也不是“最长匹配优先”。举例来说，如果同时有location /api/和location /api/v1/，一个请求/api/v1/users会优先落在/api/v1/这个 location 上，因为前缀更长。但如果有一个正则location ~ ^/api/存在，即使它写在普通前缀匹配的前面，请求最终仍然会匹配到正则规则，因为普通前缀匹配结束后还要给正则在最后再检查一次机会。

我实际排障中遇到过很多次“为什么我明明写了/api/的 location 却不生效”的疑问，最后检查下来基本都是因为这个优先级顺序。理解匹配流程，建议直接看官方文档里描述的那条规则链：先精确，再普通前缀选最长，记录最长命中项；如果有^~则直接用它；然后按顺序执行正则，一旦命中就使用该正则结果；全部正则没命中才用之前记录的最长前缀结果。

1.2 proxy_pass带URI与不带URI的本质区别

proxy_pass最简单的写法是proxy_pass http://backend;，后面不带任何路径，这种写法表示 Nginx 接收到请求之后，会把完整的原始 URI 直接转发给后端。

另一种写法是proxy_pass http://backend/;，注意斜杠，或者proxy_pass http://backend/some/path;，这种写法属于带 URI 的形式。带 URI 时，Nginx 的行为就会发生一个关键变化：它会用 URI 中写明的路径，替换掉当前 location 匹配到的那一段前缀。

这个替换逻辑是整个proxy_pass最容易让人困惑的地方，我举一个很典型的例子来说明。假设配置是：

location /api/ { proxy_pass http://backend/; }

客户端请求/api/user/list时，Nginx 会把前缀/api/替换成/，然后传给后端的地址就是/user/list。所以这里的实际效果不是“去掉/api/前缀”，严格来说应该是“用/替换掉匹配到的/api/这段字符串”。

如果proxy_pass里写的是http://backend/newapi/;，那么/api/user/list会被替换成/newapi/user/list。看到这里你应该能理解了：proxy_pass带 URI 时，它干的活就是对请求路径做一次“字符串替换”，替换的源就是当前 location 匹配到的那一段前缀，替换的目标就是proxy_pass中紧跟 host 后面的路径。

1.3 为什么理解“替换逻辑”比死记规则更重要

网上关于proxy_pass的配置写法有很多现成答案，比如“不带斜杠就是原样转发，带斜杠就去掉前缀”，这句话在大多数场景下能蒙对，但它掩盖了真正的原理。当你遇到复杂路径重写、前端和后端路径约定不一致、网关统一加前缀等场景时，只靠口诀是没法灵活变通的。

就拿我经手过的一个模拟项目来说，前端部署在/app/路径下，后端接口统一挂在/service/路径下，但前端代码里发请求的路径是/api/user/list。这种情况下，配置要做两件事：第一，用location /app/api/去匹配前端的业务请求；第二，proxy_pass里带 URI 写成http://backend/service/;，这样替换逻辑就变成了/app/api/被替换成/service/，后端收到的完整 URI 是/service/user/list。如果只是靠“去掉前缀”的口诀，这里很容易搞错。

理解了替换逻辑之后，你可以把任意前后端路径映射关系转化成“location 前缀”和“proxy_pass 目标前缀”的一一对应，遇到问题直接在纸上把替换过程写一遍，很多坑就不会踩了。

2. 语法细节与匹配流程拆解

上一节已经讲了核心的替换逻辑，这一节我会把语法层面的细节再补完整，包括正则捕获组在proxy_pass里的用法，以及几个容易让人头大的边界情况。

2.1 location匹配规则语法与优先级

先来看一个比较典型的配置片段：

server { listen 80; server_name example.test; location = /healthz { return 200 'ok'; } location ^~ /static/ { root /data/www; } location ~ \.(png|jpg|css|js)$ { root /data/assets; } location /api/ { proxy_pass http://backend/; } }

请求/healthz精确匹配，返回ok，不会进入任何其他规则。

请求/static/img/logo.png会命中^~ /static/，因为^~的规则明确表示一旦匹配到这个前缀，就不要再继续检查正则了，所以即使.png也符合后面的正则规则，最终仍然由^~的 location 处理。

请求/api/users同时满足location /api/这个普通前缀，如果配置里没有其他正则匹配/api开头的路径，就会落到这个 location 上。

这里要提醒一下：正则匹配是按配置文件中的书写顺序逐个尝试的，第一个命中的正则会被使用，所以多个正则之间的先后顺序也是会影响行为的。平时写配置时，尽量把精确的正则写在前面，宽泛的正则写在后面，避免出现预期之外的命中。

2.2 proxy_pass的URI替换规则详解

上一章已经提到proxy_pass带 URI 和不带 URI 的区别，这里我再系统地列一下常见组合的最终效果，方便对照排查。

第一行是不带 URI 的写法，后端收到的是完整原始 URI，没有做任何替换。第二行和第三行是带 URI 的写法，替换效果非常直观。第四行是带 URI 但路径恰好和 location 前缀一致的情况，所以最终结果看起来和第一行一样，容易让人误以为是一样的机制。

这里有一个容易踩坑的点：如果在proxy_pass中使用了变量，那么即使后面没有写路径，行为也会发生变化。比如：

location /api/ { proxy_pass http://backend$request_uri; }

这种情况下因为使用了$request_uri变量，Nginx 会把$request_uri值拼接到 upstream 地址后面，所以后端收到的 URI 是包含原始查询参数在内的完整 URI，而不是经过 location 替换后的 URI。这个特性在做某些特殊透传场景时有用，但日常配置不建议滥用，否则很容易出现路径不符合直觉的情况。

2.3 正则捕获组在proxy_pass中的引用

当location使用正则匹配时，proxy_pass可以引用正则捕获组，也就是形如$1、$2的变量。这个功能在路径重映射时非常实用。

例如这样一个配置：

location ~ ^/api/user/(\d+)$ { proxy_pass http://backend/service/user/$1; }

请求/api/user/123时，正则里捕获到123，proxy_pass的目标变为http://backend/service/user/123，后端收到/service/user/123。

这里特别要注意引用的限制：如果proxy_pass后面不带 URI，比如proxy_pass http://backend;，那么配置里不能引用$1这类捕获组，因为请求会原样转发，捕获组没有实际意义。只有带 URI 时才能直接在路径里使用捕获组。换句话说，想让正则捕获组驱动目标路径，proxy_pass后面必须带具体的路径部分。

还有一点值得注意：当location是正则匹配时，proxy_pass不带 URI 会原样转发原始 URI；带 URI 时，替换规则依然是“用目标 URI 替换匹配到的那一段”，但因为正则匹配的是整个路径，所以替换效果等同于把整个请求路径替换成新的路径。这也是正则类 location 下，proxy_pass带不带路径的差异比前缀匹配表现得更加明显的原因。

3. 关键场景实操：接口网关、前端代理、静态资源分离

前两章把原理讲清楚了，这一章我们进入实际场景。我会列几个我工作中经常配置的模式，每一个都是完整可复制的。

3.1 反向代理后端API：最容易被坑的斜杠问题

先看一个最常见的场景，后端接口服务跑在一台内网服务器上，需要把/api/开头的请求都转发过去。很多人的第一版配置长这样：

location /api/ { proxy_pass http://backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }

这个配置里proxy_pass不带 URI，所以请求/api/users会完整地以/api/users转发给后端。如果后端服务的路由里恰好有/api前缀，那么这段配置是没问题的。但现实里后端网关往往不希望自带业务前缀，这时候你会发现所有接口都 404。

正确的改法是：

location /api/ { proxy_pass http://backend/; }

把/api/前缀替换成/，这样请求/api/users到后端就变成/users，后端只需要按业务路径定义路由即可。

这里我建议项目组提前约定一套规范：所有经由 Nginx 转发的内部接口服务，统一认为 Nginx 会负责“剥掉前缀”或“改写前缀”，后端不感知外部前缀。这样前后端联调时，路径映射关系一目了然，不会出现改了前端路由不得不改后端路由的连锁反应。

需要注意的是，proxy_pass http://backend/末尾的斜杠是必须的，如果漏掉写成http://backend而不带斜杠，又是另一种行为。强烈建议写完配置后，用nginx -t检查语法，再实际用curl验证一下后端收到的路径。

3.2 前端history路由配置：try_files与proxy_pass配合

现在前端项目大多使用 Vue Router 或 React Router 的 history 模式，刷新页面时如果路径不是/，直接请求服务器会返回 404，因为服务器上根本没有那个文件路径。这种场景下 Nginx 的典型配置思路是：静态文件交给 Nginx 直接服务，其他路径交给前端渲染服务或统一回退到入口 HTML。

一种常见的做法是用try_files：

server { listen 80; server_name web.example.test; root /data/webapp/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://backend/; proxy_set_header Host $host; } }

location /负责所有非/api/的请求：如果文件存在就直接返回文件，如果不存在就回退到index.html，由前端路由接管。location /api/负责接口转发，这样前端页面和接口请求走不同的处理逻辑，互不干扰。

如果你的前端应用不是纯静态部署，而是跑在一个 Node 服务上，那么可以不用try_files，直接把非 API 的请求全部 proxy 到 Node 服务：

location / { proxy_pass http://node_app; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /api/ { proxy_pass http://backend/; }

这里要注意location /的优先级最低，location /api/更具体，所以 API 请求会优先命中/api/的规则，不会被错误转发到 Node 服务。这种配置方式我实测下来很稳，前端、接口各自职责分明。

3.3 静态资源分离：alias与proxy_pass的选择边界

静态资源分离的需求也很常见，比如图片、CSS、JS 等文件希望存放在独立存储服务器或 CDN，请求/static/前缀时直接转发，不需要进入业务后端。

最简单的做法是：

location /static/ { proxy_pass http://storage_server/static/; }

这里带上/static/路径，保证后端收到的请求中仍然包含静态资源子目录。如果你想去掉前缀，就写成proxy_pass http://storage_server/;，两种做法都可以，取决于存储服务器上的目录结构。

这个场景下很多人会把proxy_pass和alias混淆。alias是 Nginx 本地文件路径映射用的，比如：

location /static/ { alias /data/storage/; }

请求/static/logo.png时会直接读取本地文件/data/storage/logo.png。而proxy_pass是把请求转发给另外一台服务，两者完全不同。如果你的资源本来就存放在当前 Nginx 服务器的磁盘上，用alias或root就够；如果资源在独立的存储服务上，才用proxy_pass。这个边界值得心里有数，因为不少人在小型项目里会把本地静态文件路径配置错，排查半天发现其实是要加alias的场景。

4. 常见Nginx location和proxy_pass疑难杂症排查

这一章我会把实际工作中遇到的典型问题整理一遍，每一条都是真实踩坑后的经验，希望能帮你少走弯路。

4.1 URI被莫名截断或路径重叠

现象：接口请求打过去，后端收到的路径跟自己预期不一致，比如多了一段前缀，少了某个层级。

原因一般就两种：第一，proxy_pass带不带 URI 的语义没搞清楚，导致替换结果不对；第二，location匹配到的不是你以为的那条规则，可能是正则或其他 location 抢先了。

排查方法第一步是用curl加-v参数直接请求 Nginx，然后在后端服务的访问日志里查看实际路径。如果后端不方便打日志，可以临时在某台测试服务器起一个简单回显服务，把所有请求路径原样返回，这样 Nginx 转发出什么路径一目了然。

第二步是检查location匹配情况。你可以在配置里临时给每个 location 加一个独立的响应头，比如：

location /api/ { add_header X-Location api-prefix always; proxy_pass http://backend/; }

请求后看响应头里出现的是哪个标记，就能快速识别实际命中的 location。

4.2 代理后路径重置导致404

现象：请求通过 Nginx 转发到了后端，后端处理完返回 302 或其他重定向响应，Location 头指向了一个 Nginx 无法正确处理的路径，客户端跳转后出现 404。

这个问题的根源通常在proxy_redirect默认行为上。后端应用在生成重定向地址时，很可能用的是后端自己的地址，例如http://backend/login，但这个地址对客户端来说不可达，客户端直接拿着它访问当然会失败。

解决办法是配置proxy_redirect，把后端返回的重定向地址改写成前端可访问的地址：

proxy_redirect http://backend/ /;

或者更精确地写成：

proxy_redirect http://backend/login /login;

如果你使用的是 HTTP 协议且后端没有特殊定制，默认proxy_redirect会按照proxy_pass的地址改写。但在前后端域名不一致、端口不一致的场景下，显式配置proxy_redirect几乎是必须的。我建议在做接入层代理时，始终留意后端返回的 Location 头，必要时通过curl -i把响应头打印出来核对一遍。

4.3 重写规则与proxy_pass同时使用的顺序问题

rewrite和proxy_pass一起用时，很多人对先后顺序会比较迷糊。实际上 Nginx 处理请求时，rewrite在proxy_pass之前执行。rewrite改写掉了 URI，后续proxy_pass按改写后的 URI 进行转发。

举个例子：

location /old/ { rewrite ^/old/(.*)$ /new/$1 break; proxy_pass http://backend; }

请求/old/user经过 rewrite 后，Nginx 内部 URI 变为/new/user，因为proxy_pass不带 URI，所以后端收到/new/user。

如果把proxy_pass改成带 URI 的形式：

location /old/ { rewrite ^/old/(.*)$ /new/$1 break; proxy_pass http://backend/prefix/; }

由于 rewrite 已经把 URI 改成了/new/user，location 匹配到的前缀/old/本来已经不存在了，这时proxy_pass带 URI 会做一次新的替换，把当前 URI 中匹配到的旧前缀替换成新前缀。因为当前 URI 是/new/user，不再包含/old/，所以实际效果是直接使用完整 URI 拼接在 host 后面，结果为/prefix/new/user。这一点非常隐蔽，实战中遇到路径叠加的情况，多数都是 rewrite 和 proxy_pass 一起用导致的双重改写。

我的建议是：用rewrite做路径标准化时，尽量让proxy_pass保持最简单的方式，要么统一不带 URI，如果要带 URI，就一定要明确知道改写后的 URI 是什么，并且把替换结果在脑子里推演一遍。

4.4 常见问题速查表

5. 调试技巧与配置规范建议

当问题变得难以定位时，靠肉眼看配置已经不够了。这一章我会分享一些实际工作中验证 location 和 proxy_pass 组合行为的方法，以及一套让配置文件更可维护的组织方式。

5.1 用调试日志和curl命令验证匹配结果

调试第一步永远是检查语法：

nginx -t

这个命令会告诉你配置文件有没有语法错误，但它不会告诉你匹配结果对不对。想看匹配结果，最直接的办法是把日志级别临时调高：

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

开启 debug 级别之后，日志里会详细输出每个请求经历过的 location 匹配过程。但我建议只在调试阶段临时开启，调试完成马上关掉，因为 debug 日志量非常大，生产环境长期开吃不消。

更轻量级的验证方式是准备一个回显目标。在测试环境起一个最简单的 HTTP 服务，任何请求进来都把请求路径原样响应回去，然后用 curl 请求 Nginx 的各个路径，观察响应里显示的 URI 和查询参数。这样可以快速确认 proxy_pass 的替换效果是否符合预期。

我在实际操作中还常用一个技巧：给每个 location 临时加上不同的响应头或块注释，利用响应头的差异来判断请求到底落在哪个规则里。这个办法比看日志直观很多，也适合和其他同事协作排查。

5.2 配置文件的组织与规划思路

配置代理多了之后，最怕的就是所有规则堆在一个文件里，几百行 nginx.conf 翻起来非常痛苦。我通常会这样组织：

# 主配置 include /etc/nginx/conf.d/*.conf; # 单独的 upstream 定义文件 # conf.d/upstreams.conf upstream backend_api { server 10.0.0.11:8080; keepalive 32; } # 站点配置 # conf.d/example.conf server { listen 80; server_name example.test; location /api/ { proxy_pass http://backend_api/; include /etc/nginx/proxy_params; } }

把proxy_set_header这类通用参数抽到一个独立的proxy_params文件里，所有 location 直接 include，这样不会每段配置都重复一大串头信息。upstream 单独定义，好处是后端地址变更时只需要修改一处，不需要在多个 location 里来回找。

我还习惯在 location 上方加注释，写明这个规则服务的业务方是谁、期望的转发效果是什么。比如：

# 前端页面：/app/ 路径下部署的 SPA，刷新回退 index.html location /app/ { try_files $uri $uri/ /app/index.html; }

这种注释在半年后自己回来看配置时价值非常大，更不用说团队协作了。

6. 补充经验：连接复用、安全头透传与长期配置维护

最后这一章属于锦上添花的部分。理清 location 和 proxy_pass 的基本规则之后，再关注一些细节，生产环境里会省掉不少麻烦。

6.1 upstream keepalive与性能发烫点

很多人在配置proxy_pass时只关心路径，忽略了后端连接复用的问题。默认情况下，Nginx 和后端服务之间的连接是短连接，每次请求都重新建立 TCP 连接。在并发请求较高时，这既增加延迟也增加系统资源消耗。

解决办法是在 upstream 中配置 keepalive：

upstream backend_api { server 10.0.0.11:8080; keepalive 32; } location /api/ { proxy_pass http://backend_api/; proxy_http_version 1.1; proxy_set_header Connection ""; }

注意keepalive是 upstream 块的参数，不是 server 或 location 里的指令。同时要让代理使用 HTTP/1.1 协议，并清空 Connection 头，否则连接复用不会生效。这个配置对接口类服务收益非常明显，我有一次在模拟压测中对比过，开启后 Nginx 到后端的握手开销显著下降，整体吞吐提升了不少。

6.2 请求头透传与安全头隐藏的几个细节

代理模式下，后端通常需要知道客户端的真实 IP 等信息，所以X-Forwarded-For、X-Real-IP这类头部一般都会透传。比较容易被忽略的是 Host 头。

如果proxy_pass指向的是 upstream 抽象，且 upstream 里的主机名和用户请求的域名不同，后端拿到的 Host 可能不对。通常我们期望后端感知到的是用户访问的域名，这时需要显式设置：

proxy_set_header Host $host;

另一方面，后端响应中如果有不希望暴露的头部，可以用proxy_hide_header隐藏。比如后端返回的版本号、内部错误信息字段，不想透传给客户端，可以：

proxy_hide_header X-Powered-By;

代理层是安全边界的一部分，有些潜在泄密点需要在配置层面就提前堵住，而不是等到出现事故再回查。

6.3 配置变更的长期维护节奏

经验告诉我，每次调整 location 或 proxy_pass 之前，先把变更点列清楚，明确这几个问题的答案：希望哪些路径走到哪个后端？proxy_pass要不要带路径？带的话替换后的 URI 是什么？后端是否能接受这个 URI？然后按照“先nginx -t，再小流量验证，最后全量 reload”的顺序操作。

对于测试环境，甚至可以准备一个专门的回显后端，专门用来验证路径变化。我强烈建议每一个维护过 Nginx 的人都在本地保留一组最小可复现的配置模板，下次遇到新项目直接基于模板改，比从零开始写要可靠得多。配置这东西，踩过几次坑之后就会明白，所有奇奇怪怪的 404 和路径错乱，归根到底都是没有把“匹配”和“替换”两步拆开来想。把这两步在脑子里走顺了，Nginx 的路由代理基本就掌握大半了。