前后端分离部署：Nginx 静态资源服务与反向代理完整配置

1. 前言在前后端分离架构成为主流的今天前端项目独立打包为静态资源后端项目以 API 接口形式提供服务二者独立开发、独立部署前端项目构建的生产资源不再打包内嵌到后端服务甚至后端代码中。但在实际落地时往往会面临几个核心问题浏览器跨域限制、静态资源高效分发、统一访问入口、前端路由适配等。Nginx 凭借高性能、高并发的特性成为解决上述问题的首选方案它既可以作为静态资源服务器托管前端打包产物直接响应页面、样式、脚本等资源请求也可以作为反向代理服务器将 API 请求按规则转发至后端服务天然解决浏览器跨域问题同时统一对外访问入口。本文将从架构原理出发完成 Nginx 静态资源服务与反向代理的完整配置并验证响应页面访问和API接口请求效果。2. 整体架构与核心原理2.1. 请求流向架构在 Nginx 统一入口的架构下所有请求先到达 Nginx再由 Nginx 根据路由规则进行分流整体请求链路如下浏览器发起请求 → 到达 Nginx 服务统一端口、统一域名Nginx 匹配请求路径若为页面、JS、CSS、图片等静态资源请求Nginx 直接读取本地磁盘的前端打包文件返回给浏览器若为 API 接口请求通常请求路径带统一前缀如/api/Nginx 将请求转发给后端应用服务拿到响应后再返回给浏览器这种「动静分离」的架构既降低了后端服务的静态资源压力也让前端资源可以利用 Nginx 的缓存、压缩能力提升加载速度。2.2. 关于跨域的说明在这种架构下前端页面和 API 接口是同一个域名、同一个端口浏览器天然不存在跨域问题不需要额外配置 CORS 响应头。只有当接口和页面不同源、且需要直接调用时才需要配置跨域头。2.3. 核心实现依赖Nginx 实现两大功能核心依赖server块与location块的路由匹配能力静态资源核心指令root指定资源路径反向代理核心指令proxy_pass指定后端服务地址3. 前置环境准备3.1. 环境说明操作系统OpenEuler 22.03 LTSNginx 版本nginx/1.21.5Nginx 配置文件默认路径/etc/nginx/nginx.conf网页根目录前端打包产物放置目录/usr/share/nginx/html包含 index.html、assets 目录等后端服务地址本地启动的 SpringBoot 服务地址为localhost:80803.2. 基础操作命令配置修改后必须先校验语法再平滑重载避免服务中断# 校验配置文件语法是否正确sudonginx-t# 平滑重载配置不中断现有连接sudosystemctl reload nginx# 查看 Nginx 运行状态systemctl status nginx3.3. 前端项目部署说明开发完成的 Vue3 项目执行生产构建命令产物默认输出到项目根目录的dist文件夹中。部署前端项目时将该dist目录下所有内容不包括dist文件夹本身部署到Nginx网页根目录中。4. Nginx核心配置server { listen 80; listen [::]:80; server_name _; # 1. 静态资源根目录前端项目构建生成的静态资源的部署位置 root /usr/share/nginx/html; # 2. API 反向代理匹配所有 /api/ 开头的请求转发给后端服务 location /api/ { proxy_pass http://localhost:8080/; } }5. 验证Nginx功能先单独验证 Nginx 静态资源服务能力再单独验证反向代理转发能力最后做前后端全链路联调。这种方式能快速定位问题出在前端文件、Nginx 配置还是后端服务避免混在一起盲目排查。5.1. 验证静态资源服务Vue 页面5.1.1. 验证目标确认 Nginx 能正确返回 Vue 打包的页面、JS/CSS/ 图片等静态资源。5.1.2. 验证步骤5.1.2.1. 文件完整性检查确认index.html、assets文件夹等打包产物路径与Nginx配置中root的路径完全一致。5.1.2.2. 首页访问验证浏览器直接访问http://localhost/正常结果页面完整渲染无空白、无样式丢失5.1.2.3. 静态资源加载验证按F12打开浏览器开发者工具 → 切换到「网咯」面板刷新页面所有.js、.css、图片等静态资源状态码均为200无404响应头中Server字段为nginx确认资源由Nginx返回5.2. 验证反向代理SpringBoot API5.2.1. 验证前提先绕过Nginx直接访问后端接口确认SpringBoot服务本身正常。直接访问后端接口 http://localhost:8080/user 确认能正常返回数据。若直连都不通先排查后端服务无需验证Nginx。5.2.2. 验证步骤5.2.2.1. 代理连通性验证通过Nginx访问API接口和直接访问接口对比查看访问结果是否一致.访问路径http://localhost/api/user正常结果返回的数据与直连后端完全一致HTTP状态码为200响应头中Server为nginx证明流量经过Nginx转发5.2.2.2. 查看 Nginx 访问日志access.logNginx日志能看到/api/user的请求记录状态码200sudotail-f-n1000/var/log/nginx/access.log5.2.2.3. 查看后端服务访问日志后端日志后端服务能收到/user的请求并打印日志对应nginx.conf中带斜杠的proxy_pass配置5.2.3. 常见异常状态记录5.2.3.1. Nginx未启动时请求代理API接口连接失败访问路径http://localhost/api/user5.2.3.2. 访问不存在的接口404访问不存在的接口应返回状态码404确认404由后端返回而非Nginx直接访问后端不存在的接口http://localhost:8080/role通过 Nginx 访问不存在的接口http://localhost/api/role5.2.3.3. 访问 Nginx 未匹配的路径404对于nginx.conf中没有匹配的路径Nginx会直接响应状态码404 。访问 Nginx 未匹配的路径http://localhost/unmatched-path5.2.3.4. 停掉后端服务后再访问接口502停掉后端服务后再访问接口Nginx应返回502 Bad Gateway证明代理规则匹配成功只是后端不可达。5.3. 页面调用接口全流程验证模拟真实用户访问场景验证前端页面经由 Nginx 同源转发调用后端接口确认不存在跨域问题接口返回数据可正常在页面渲染展示。Vue3 打包产物部署在 Nginx 后页面点击按钮触发 Axios 请求调用后端 API完整链路效果见下文。5.3.1. Axios请求的消息头请求头和响应头5.3.2. Axios请求的响应体5.3.3. 访问日志127.0.0.1 - -[18/Aug/2026:00:24:18 0800]GET /api/user HTTP/1.120051http://localhost/Mozilla/5.0 (X11; Linux aarch64; rv:102.0) Gecko/20100101 Firefox/102.0-6. 参考文章Vue3项目创建和开发运行效果请参考如下文章《新建 Vue3 项目测试 API 接口查询用户列表》