该项目标题非常典型，属于几乎每个前后端分离项目在部署阶段都会遇到的一类问题：域名就一个，但前端、后端、静态资源全都要挂在同一个入口下，还得保证路由不乱、接口不交叉、缓存不污染。我自己这几年经手过不少类似场景，从最开始的“一刀切用端口区分”到“用子域名拆”，再到后来大多数项目回归到“同域名路径区分”，这条路走下来，遇到过不少坑，也积累了一些值得记录的配置思路。这篇文章就围绕Nginx下的同域名路径区分配置展开，把从设计思路、具体配置到排错经验完整过一遍，希望能给正在部署前后台项目的朋友一些可落地的参考。
1. 整体设计思路：为什么要用同域名加路径区分
1.1 需求场景还原
先说一个最典型的场景：你有一个电商管理系统，包含面向用户的前台商城页面和面向运营人员的后台管理界面，同时这两块都需要调用同一套后端服务接口。你手头只有一个域名，比如example.com，域名证书也买好了。现在的问题是：线下两个应用怎么共存，接口怎么收敛。
用端口区分是最直观的方案——例如前台跑80端口，后台跑8080，接口跑8081。但这样做的问题也很现实：浏览器访问8080端口时，如果后端服务没做跨域支持，前端调用接口会直接报跨域错误，必须得在服务端代码里加跨域中间件，或者在前端开发环境里配proxy。而且用户记忆端口号不友好，域名后面跟一串冒号数字，怎么看都显得不专业。
用子域名区分是另一种方案——shop.example.com指前台，admin.example.com指后台，api.example.com指接口。这个方案在资源充足、DNS配置方便的场景下很干净，隔离性也好。但如果你是企业内部项目，没有便捷的DNS管理权限，或者说只想用一张证书搞定所有入口，那么子域名方案就变成了甜蜜的负担，每加一个子域可能都要多处理一次证书签发和泛域名解析。
于是我最终选择了同域名路径区分：example.com/ 直接承载前台页面，example.com/admin/ 承载后台页面，example.com/api/ 作为后端接口的统一前缀。这样浏览器里只有一个域，不存在跨域问题；证书只需要覆盖主域名即可；用户记忆成本也低，访问后台就在域名后面加一个路径。
1.2 同域名路径区分的核心逻辑
Nginx实现这一方案的核心就是location匹配。location指令支持前缀匹配、精确匹配和正则匹配，我们在一条server块里通过不同的location规则，把不同路径的请求分发到不同目标。
一个常见的合理划分规则是这样：
/对应前台静态资源目录，即前端构建产物中的index.html及JS/CSS等文件；/admin对应后台静态资源目录；/api对应后端服务地址，需要做反向代理转发；- 另外还要考虑浏览器刷新时SPA路由的fallback，也就是前端路由是history模式时，访问一个前端路径比如 /product/list，Nginx找不到这个文件，要统一回退到index.html，由前端JS路由接管。
把这些规则梳理清楚后，整套系统的入口面就变得非常简洁：Nginx是唯一网关，前端资源由Nginx直接托管，后端服务隐藏在网关后面，客户端只能通过/api这唯一通道访问后端。安全性也更可控，可以在网关层统一做限流、IP黑白名单、请求体大小限制，不必在每个后端服务里重复实现。
1.3 相比端口区分和子域名区分的取舍
我用一张对比表来总结三种方案的差异，方便大家按自己实际情况选择。
| 维度 | 端口区分 | 子域名区分 | 同域名路径区分 |
|---|---|---|---|
| 浏览器跨域 | 需要后端跨域配置 | 需要后端跨域配置 | 天然无跨域 |
| 证书管理 | 一张证书即可 | 多张或泛域名证书 | 一张证书即可 |
| 环境切换 | 生产/测试需换端口 | 生产/测试需换域名 | 只需换域名子路径 |
| 配置复杂度 | 低 | 中 | 中 |
| 隔离性 | 好 | 最好 | 一般 |
| 用户记忆成本 | 高 | 中 | 低 |
| 适合场景 | 临时联调、内网接口 | 多独立业务线、大型平台 | 中小型项目、前后台同源 |
从这个对比可以看出来，同域名路径区分特别适合中小规模项目，尤其是以单体应用外加一个后台管理的组合形态。它的隔离性比不上子域名，但对于大多数业务来说已经足够：前端和后台通过路径隔开，接口通过/api前缀统一收敛，Nginx一层做好转发，安全和可维护性都兼顾。
2. 核心配置前的准备：你需要确定的几个关键信息
在实际写Nginx配置之前，有几样东西我建议先花几分钟梳理清楚，否则配置写出来很容易出现路径对不上、接口404这类问题。
2.1 前后台构建产物的目录结构
以最常见的Vue或React项目为例，执行npm run build之后，默认会在项目根目录生成dist目录。dist目录里面有index.html，有static或者assets目录，里面放的是打包后的JS和CSS。
这里有一个很容易被忽略的细节：打包工具的publicPath或base路径。前端代码在本地开发时访问路径是/，但部署到服务器之后，后台访问路径变成了/admin/，这意味着构建产物的静态资源引用路径也必须跟着变化。如果后台项目用的是Vue CLI，配置项是publicPath；如果是Vite，配置项是base；如果是React的Create React App，配置项是homepage或直接改package.json里的homepage字段。我建议把所有环境相关的配置都提取到环境变量里，比如.env.prd里定义VITE_APP_BASE_PATH=/admin/，构建时系统自动读取，好过每次部署前手动改代码。
前台项目如果挂在根路径下，publicPath就用默认的/，不需要额外处理。但如果你同时有多个前台应用，比如用户端和另一个营销活动页，那就也都需要为每个应用配置独立的base路径。
2.2 后端服务接口前缀设计
很多团队的后端服务原本习惯把所有接口都挂在根路径下，比如/user/list、/order/detail。如果Nginx直接把这个请求代理给后端，而location匹配的是/api前缀，就会遇到路径重写的问题。
我个人的经验是，强制约定后端所有接口统一以/api开头，这是一个从设计阶段就需确定的约束。后端在框架层面配置路由前缀，比如Java的Spring Boot里设context-path为/api，Go的Gin里给所有路由注册统一前缀，Node的Express里用app.use('/api', router)。这种方式的最大好处是，Nginx配置基本不用做什么路径重写，直接把location /api/的请求原样转发就完事，出错概率小很多。
但如果后端接口确实没有统一前缀，那么Nginx就需要做路径重写，把/api/user/list改写为/user/list再转发，这就要依赖正则表达式加rewrite或者proxy_pass的某些特性。这个在后面的核心配置部分会详细展开。
2.3 SSL证书准备与域名解析确认
同域名方案最舒服的一点是证书只需要一张。准备证书时确认以下几点：
- 域名的解析记录已经指向当前服务器的公网IP，并且解析生效；
- 证书文件路径准备好，一般会拿到fullchain.pem和privkey.pem两个文件，分别对应证书链和私钥；
- 如果是云厂商申请的免费证书，记得关注证书到期时间，Nginx配置里写上证书路径后，最好验证一下配置文件能正常加载。
我遇到过不少次因为证书文件路径写错导致Nginx reload失败的情况，所以每次配置前我都会先手动确认一下证书文件存在且格式正确。
3. Nginx核心配置实操：从零到一搭建完整方案
3.1 前置要求：Nginx安装与目录规划
假设你的服务器是Linux环境，Nginx已经安装好。我习惯把站点配置文件放在/etc/nginx/conf.d/目录下，每个站点一个文件，命名规则是域名.conf，例如example.com.conf。这个目录里的配置会被Nginx主配置文件nginx.conf中的include /etc/nginx/conf.d/*.conf;自动加载，管理起来非常清晰。
同时也建议规划统一的资源目录，我通常按如下结构组织：
/data/sites/example.com/ ├── web/ # 前台构建产物 │ ├── index.html │ └── assets/ ├── admin/ # 后台构建产物 │ ├── index.html │ └── assets/ └── logs/ # 站点访问日志和错误日志 ├── access.log └── error.log这样部署时直接把前台dist产物拷到web目录，后台dist产物拷到admin目录，干净明了。
3.2 基础版配置：静态资源托管加后端代理
下面先给出一个可用性较高的基础配置，然后逐步解释每个块的作用。
server { listen 80; server_name example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/example.com/privkey.pem; root /data/sites/example.com/web; index index.html; # 后台管理端 location ^~ /admin/ { alias /data/sites/example.com/admin/; try_files $uri $uri/ /admin/index.html; } # 后端接口反向代理 location /api/ { 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; proxy_set_header X-Forwarded-Proto $scheme; } # 前台SPA路由回退 location / { try_files $uri $uri/ /index.html; } # 静态资源缓存策略 location /assets/ { expires 7d; add_header Cache-Control "public, max-age=604800"; access_log off; } access_log /data/sites/example.com/logs/access.log; error_log /data/sites/example.com/logs/error.log; }这个配置里最值得拆解的是location匹配优先级和alias的配合。
先看location的匹配顺序。Nginx匹配location时遵循以下规则：先是精确匹配=，命中后直接使用；然后是^~前缀匹配，一旦命中就不再继续搜索正则；接着是正则匹配，按配置文件里出现的顺序逐一尝试，命中即用；最后才是普通前缀匹配，选择最长匹配的那个。所以在这个配置里，/admin/因为是^~前缀匹配且优先级高于正则，所以会直接落到后台静态资源配置；/api/虽然也是前缀匹配，但因为后面的正则没有匹配它，所以也能正确处理。
再看/admin/用alias而不是root的原因。root会把匹配到的location前缀也拼接在访问路径后面，比如请求/admin/index.html，root配置/data/sites/example.com/admin时，实际查找的文件路径是/data/sites/example.com/admin/admin/index.html，这显然不对。而alias会用alias的路径替换掉location匹配的路径部分，请求/admin/index.html会直接映射到/data/sites/example.com/admin/index.html，符合预期。这个差异是我见过的最常见的路径404原因之一。
3.3 SPA路由回退与refresh问题的处理
前端项目开的是history模式路由时，用户直接访问example.com/product/list。如果这个URL没有对应的真实文件，Nginx默认会返回404，但前端期望的是把这个请求交给index.html，由前端路由重新解析到对应页面。
try_files $uri $uri/ /index.html;这条指令就是用来做这件事的。它的执行逻辑是：先尝试找指定的URI文件，例如$uri就是/product/list，文件不存在；再尝试当目录处理，即$uri/；还不行就回退到最后一个参数/index.html。
这个回退能生效还有一个必要前提：前端package.json或路由配置里没有历史遗留的硬编码路径。如果路由的base不是/，那回退路径要做相应调整。前台挂根路径就用/index.html；后台挂/admin/路径，则回退目标应该是/admin/index.html，并要配合alias配置一起使用。
3.4 后端无统一前缀时的路径重写方案
有些老项目后端接口确实没有/api前缀，这时要么改后端代码统一加前缀，要么在Nginx做路径重写。改代码是最干净的方案，但如果你暂时动不了后端，Nginx的rewrite也能救急。
location /api/ { rewrite ^/api/(.*)$ /$1 break; proxy_pass http://127.0.0.1:8080; }这条rewrite规则把/api/user/list重写为/user/list，break表示停止后续rewrite，直接把重写后的URI代入proxy_pass转发。还有很多团队用的是proxy_pass结尾带路径的写法：
location /api/ { proxy_pass http://127.0.0.1:8080/; }注意这个细节，proxy_pass的URL里如果带了尾随/，那路径里的/api/会被剥离后再拼接到后端地址上。例如请求/api/user/list，proxy_pass为http://127.0.0.1:8080/，实际代理转发的路径是/user/list。如果proxy_pass不带尾随/，则原始URI原样保留，转发的是/api/user/list。这个差别很微妙，经常会把人绕晕，我建议在一开始就用第一性原理想清楚：你到底想让后端收到什么路径。
3.5 后台独享域名路径的边界处理
后台管理端挂在/admin下时，有一个细节要特别注意：当用户访问的是example.com/admin而不带末尾斜杠时，Nginx的处理和访问example.com/admin/是有差别的。
这个差异主要体现在两个地方。第一，如果配置的是alias目录，且访问没有尾斜杠的/admin，Nginx可能按照文件去匹配；第二，即使匹配上了，返回的页面里相对路径的引用也会出现问题。比如index.html里有<script src="./js/app.js">，在/admin/下浏览器会解析为/admin/js/app.js，如果直接在/admin下访问，相对路径的基础就变成了根路径，资源引用就乱了。
所以我通常会在配置里专门为不带斜杠的情况加一个redirect规则，或者用try_files配合做回显。最简单的做法是这样的：
location = /admin { return 301 /admin/; }这样无论用户在地址栏输入什么形式，最终都会规范到/admin/这个标准入口。
4. 配置进阶：缓存、跨域头、WebSocket与多实例负载均衡
基础配置跑通只是第一步。把项目真的推向生产环境时，缓存策略、接口并发、后台实时消息推送这些需求会接踵而来，Nginx配置也需要跟着升级。
4.1 静态资源缓存区分策略
很多团队踩过一个坑：前端发版后，用户浏览器里还残留着旧版本的JS和CSS，页面样式错乱。这个问题的根源是缓存策略太懒，对所有资源都开了长期缓存。正确思路是区分对待：
- 带hash指纹的资源，也就是文件名中带有一串随机字符串的产物，比如
app.3f2b1c.js，可以放心设置长时间缓存，hash变了文件名就变，浏览器自然会拉新文件； - HTML入口文件，也就是index.html，绝不能设置长缓存，否则每次发版用户都拿到旧页面；
- 图片等静态资源，按实际更新频率设置7天或30天缓存即可。
对应到Nginx配置里，就是分别对assets目录和HTML文件做不同的响应头控制。
location /assets/ { expires 30d; add_header Cache-Control "public, max-age=2592000, immutable"; } location = /index.html { add_header Cache-Control "no-store, must-revalidate"; }这里我把assets目录的缓存时间设置成30天，同时加了immutable标识，意思是这个资源在过期前无需向服务器发起任何重新验证请求，有效减少了不必要的请求数量。而index.html则设置成禁止缓存，确保每次访问都能拿到最新入口文件。
4.2 统一加CORS头与请求头透传
虽然同域名方案天然规避了跨域，但如果你有一些客户端应用走的是其他域名，或者某些内部工具需要直接请求接口，那网关层统一加跨域响应头还是很有必要的。
location /api/ { add_header Access-Control-Allow-Origin *; add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"; add_header Access-Control-Allow-Headers "DNT, X-CustomHeader, X-Requested-With, Content-Type, Authorization"; add_header Access-Control-Max-Age 86400; if ($request_method = 'OPTIONS') { return 204; } }这里需要注意的是，如果接口请求中带有身份认证信息，比如Cookie或Authorization头，那么Access-Control-Allow-Origin就不能使用通配符*，必须写死为实际来源域，并加上Access-Control-Allow-Credentials true。这是一个很容易踩的坑，通配符一旦启用，携带Cookie的请求就会被浏览器拦截。
另外，实际项目中客户端的真实IP信息若要传递到后端，务必把X-Real-IP、X-Forwarded-For等请求头在location中配置好，原因在于Nginx转发时，若不修改这些头，后端日志和审计里看到的IP全都是127.0.0.1，排障时你根本无法判断请求来自哪个客户端。
4.3 WebSocket反向代理支持
后台管理系统经常包含在线聊天、工单实时推送、消息通知等能力，这些能力多数由WebSocket实现。Nginx代理WebSocket只需要额外处理几个请求头，让连接支持协议升级。
location /api/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，让Nginx和客户端之间保持长连接，支持协议从http升级到WebSocket；第二个是合理设置proxy_read_timeout，避免服务端超过默认60秒没有消息时，连接被Nginx主动断开。我一般根据业务心跳机制设置成300秒到3600秒不等，原则是大于前端心跳发送间隔，防止连接误断。
4.4 后端多实例负载均衡
接口访问量变大之后，后端起多个实例做负载均衡很常见。Nginx的upstream模块配置起来也很直观。
upstream backend_api { least_conn; server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; server 127.0.0.1:8081 max_fails=3 fail_timeout=30s; keepalive 32; } location /api/ { proxy_pass http://backend_api; proxy_http_version 1.1; proxy_set_header Connection ""; }这里用了least_conn策略，会把新请求分配给当前活跃连接数最少的实例，适合接口耗时差异较大的场景。同时开了keepalive，复用后端连接，降低频繁创建TCP连接的开销。这里要特别提醒，启用keepalive时必须把proxy_http_version设为1.1，并清空Connection头，否则连接复用无法生效。
5. 常见问题与排查技巧实录
部署过程中踩过的坑，比看十遍文档都记得牢。我把自己遇到的最典型问题整理出来，按症状、原因、解决思路排列，方便大家对号入座。
5.1 后端接口404，但Nginx配置看起来没问题
症状：浏览器访问example.com/api/user/list返回404，后台查看Nginx错误日志也没有明显异常。
排查思路：先确认请求到底有没有到后端。在后端服务里临时加一个访问日志输出，如果后端完全没收到请求，那问题肯定在Nginx转发层；如果后端收到了但返回404，说明路径不对。
我遇到过最典型的路径问题就是proxy_pass末尾斜杠造成的路径差异。比如location是/api/，proxy_pass写成了http://127.0.0.1:8080/，请求头中的/api前缀被自动剥掉，而后端路由还是按/api/user/list配置的，结果就404了。这种问题在命令行里用curl验证特别直观：
curl -i http://127.0.0.1:8080/user/list curl -i http://127.0.0.1:8080/api/user/list两个命令分别测一下，很快就能判断出后端期望的路径是哪一种，再反过来调整Nginx配置即可。
5.2 后台刷新页面404
症状：在后台管理界面，点击页面内跳转一切正常，但只要手动刷新某个路由，或者从地址栏直接输入URL访问，就返回404。
原因：后台前端路由是history模式，刷新后的路径例如/admin/order/list，对应的物理文件不存在，Nginx没有正确回退到admin目录下的index.html。
解决方案：检查/admin location的try_files回退目标是否正确。
location ^~ /admin/ { alias /data/sites/example.com/admin/; try_files $uri $uri/ /admin/index.html; }这里有个非常容易犯的错，是把try_files回退目标写成了/index.html，导致返回的是前台首页，页面看起来像404实际是个白屏。因为alias上下文里的回退文件路径要以/admin/index.html为准。补充一个细节，如果你的alias目录内部就是构建产物根目录，try_files的最后一个参数写成/admin/index.html没问题；但如果alias后面直接指向构建产物里的index.html文件，那写法又不一样了。这个要根据实际目录结构灵活调整。
5.3 后台页面能打开但样式全丢
症状：输入example.com/admin/打开页面，HTML渲染出来了，但CSS和JS全部404或者加载了不好的资源。
原因：构建产物的资源引用路径不对。如果后台项目打包时base或publicPath没有设置成/admin/，打包后的HTML里引用的就是/assets/xxx.css，当页面托管在/admin/下时，浏览器请求的是example.com/assets/xxx.css，这个路径没有匹配到/admin的location，自然加载不到资源。
解决方案：修改打包配置，把publicPath或base设为/admin/，重新构建部署。遇到这种情况，最快的验证方式是直接打开浏览器开发者工具，看资源请求的具体URL，对比实际文件和访问路径之间的差异，比猜快得多。
5.4 HTTPS证书配置后重启失败
症状：nginx -t提示证书文件不存在或证书链不完整。
原因：证书文件路径不对或fullchain内容和key不匹配，当然也不能排除编辑器粘贴证书时多了空格的情况。
处理建议：先确认证书文件确实存在，再检查权限，Nginx工作进程要有读权限，最后用openssl验证证书和私钥是否匹配：
openssl x509 -noout -modulus -in fullchain.pem | openssl md5 openssl rsa -noout -modulus -in privkey.pem | openssl md5两个命令输出的hash值一致，说明证书和私钥是匹配的。
5.5 URL带中文字符请求报400
症状：前端有些搜索关键词是中文，生成的URL里带百分号编码，Nginx偶尔报400。
原因：字节流解析时的字符编码问题，常见于代理配置中没有正确传递原始请求URI。
解决方案：确保proxy_pass使用的是变量或原样URI，不要随意拼接。如果用了proxy_pass http://127.0.0.1:8080$request_uri;这样的写法，$request_uri本身包含了完整的原始URI，不会做二次解码，一般能规避这个问题。还有一个相对省事的办法是统一在前端对URL做encodeURIComponent编码。
5.6 Nginx配置验证与热加载
每次修改完配置，不要直接重启Nginx，先执行语法检查。这是我最想强调的习惯。
nginx -t输出nginx: configuration file /etc/nginx/nginx.conf test is successful后再执行：
nginx -s reloadreload是平滑加载，Nginx会重新加载配置但不会中断已有连接，对线上影响极小。相比restart，reload更安全，也不会导致正在处理的请求被强行掐断。
6. 我对这套方案的一些个人体会
同域名路径区分这套Nginx部署方式，我经过多次项目实践后，最大的感触是：配置本身不复杂，复杂度全在路径规划的细节里。如果前后台打包时base路径不一致、后端接口前缀不统一、try_files回退目标写错，任何一个环节出了问题，表现出来的都是404或者白屏，排查起来非常耗时。
所以我强烈建议，项目启动阶段就要把这个部署结构纳入设计约束，而不是等所有代码写完再去想Nginx该怎么配。具体来说，前端要约定好构建产物路径，后台项目无论从什么环境打包，都能通过环境变量切换base路径；后端要统一接口前缀，能改成/api开头就尽早改，成本最低的时机就是项目起步期。
另外一个对日常维护很有用的建议是把Nginx配置纳入版本管理，单独建一个仓库，和前端代码、后端代码一起走发布流程。每次修改配置都能追溯变更记录，回滚也方便。我自己后来都是把Nginx配置文件放在一个独立仓库里，配合自动化发布流程，前端构建完产物上传，配置变更用发布单走审批再reload，整个运维流程清晰很多。
最后再分享一个调试技巧：遇到接口或页面路径问题，先不要急着看浏览器控制台，用curl在服务器本机把请求链路逐一打通，分别直接访问后端服务和通过Nginx域名访问，对比返回结果。一般这样几步试下来，问题基本就定位了。写配置，一次在编辑器里甩出一大段不叫本事，能快速定位并解决线上问题才是真的功力。
