Nginx反向代理总出问题?别慌,我们一起来排雷

说实话,做前端开发的朋友,尤其是用Vue.js或者React搞单页应用的,几乎都绕不开Nginx反向代理这个坎。您是不是也遇到过这种情况?本地开发环境跑得好好的,一部署到服务器上,接口请求就404了。或者明明配了代理,浏览器控制台却一直报跨域错误。坦白讲,这些问题我当年也没少踩坑。

今天我们不聊虚的,就直接拿几个最常见的Nginx反向代理配置问题开刀。不管您是在做Vue.js教程里的实战项目,还是跟着Ant Design教程搭后台管理系统,只要涉及到前后端分离部署,这篇内容都能帮您省下几个小时的排查时间。

代理路径配错了,接口请求全打水漂

先来说一个最典型的问题。您是不是这样配的:location /api { proxy_pass http://backend-server:8080; },然后前端代码里请求写的是 /api/user/list。结果一访问,后端收到的请求变成了 /user/list,那个 /api 前缀莫名其妙消失了!

其实这是Nginx代理路径匹配的一个小陷阱。当proxy_pass后面的地址不带斜杠时,Nginx会把location匹配到的路径部分保留下来。但如果您写成 proxy_pass http://backend-server:8080/; 注意最后那个斜杠,Nginx就会把 /api 替换掉。

就拿我们团队最近做的一个Vue.js后台管理项目来说,前端用Ant Design Pro搭建,接口请求统一加了 /api 前缀。后端同学说接口路径就是 /user/list,没有 /api。我们当时就在Nginx里写成了带斜杠的proxy_pass,结果所有请求都正常了。您看,就差一个斜杠,折腾了半小时。

所以记住这个口诀:proxy_pass带斜杠,location路径被替换;不带斜杠,路径全保留。您根据后端实际接口路径来决定用哪种方式就好。

跨域问题解决了,但Cookie和Session丢了

跨域这个问题,做前后端分离的同学太熟悉了。您可能已经在Nginx里加了 add_header Access-Control-Allow-Origin *; 这样的配置。但新的问题来了:用户登录后,后续请求死活拿不到Session,一直提示未登录。

坦白讲,这通常是因为代理没有正确转发Cookie相关的头部信息。Nginx默认不会转发Cookie给后端,您需要显式配置。比如说在location块里加上 proxy_set_header Cookie $http_cookie; 这样才能把浏览器的Cookie传给后端服务。

还有一个坑是域名问题。如果您的前端域名是 www.example.com,后端接口通过代理走的是同一个域名,那没问题。但如果代理配置里不小心写死了后端的内网IP或者另一个域名,浏览器就会认为这是跨域请求,Cookie自然带不上。

我们之前帮一个客户排查问题,他们用Vue.js教程里的方案做登录,前端一直提示401。查了半天发现是Nginx代理时把Host头改了,后端Session域对不上。后来加上 proxy_set_header Host $host; 和 proxy_set_header X-Real-IP $remote_addr; 这两行,问题立刻消失。所以您配置代理时,这几个header转发一定要加上。

静态资源加载失败,页面白屏或样式错乱

这个问题在部署Vue.js或React打包后的项目时特别常见。您打开页面,发现JS和CSS文件全部404,页面一片空白。打开Network面板一看,请求路径是 /static/js/app.xxxx.js,但服务器上文件明明放在 /dist/static/ 目录下。

其实这就是Nginx的root和alias指令用混了。root会把location的路径拼接到文件路径后面,而alias会直接替换location路径。比如说:

  • 用 root /var/www/dist; 配合 location /static/,Nginx会去找 /var/www/dist/static/ 目录下的文件。
  • 用 alias /var/www/dist/static/; 配合 location /static/,Nginx会直接去 /var/www/dist/static/ 找文件。

就拿Ant Design教程里常见的后台项目来说,打包后静态资源通常放在dist/static目录下。我们一般会这样配:location /static/ { alias /var/www/dist/static/; },这样路径就完全对上了。如果您用root,那就得确保目录结构是 /var/www/dist/static/static/ 这种嵌套,显然不合理。

还有一个容易忽略的点是try_files指令。对于Vue.js这种单页应用,所有路由都应该指向index.html。您需要在location / 里加上 try_files $uri $uri/ /index.html; 否则用户刷新页面或者直接访问某个路由时,Nginx会去找对应的物理文件,找不到就报404。这个配置能帮您解决90%的前端路由刷新404问题。

总结:配置检查清单和下一步行动

聊了这么多,其实Nginx反向代理的常见问题就那么几类:路径匹配、头部转发、静态资源定位。您每次改完配置,记得用 nginx -t 测试一下语法,然后 nginx -s reload 平滑重启。别小看这两步,能帮您避免很多低级错误。

如果您现在正在跟着某个Vue.js教程或者JavaScript教程做项目,不妨打开您的Nginx配置文件,对照下面几点检查一遍:proxy_pass后面有没有多余的斜杠?Cookie和Host头有没有正确转发?静态资源的alias路径对不对?单页应用有没有配try_files?

说实话,这些问题我第一次配的时候全中过。但搞明白之后,以后不管部署什么前后端分离项目,十分钟就能搞定。如果您也想彻底掌握Nginx反向代理,建议您拿一个实际项目练手,把今天提到的这几个配置都试一遍。遇到报错别慌,打开浏览器控制台和Nginx错误日志,答案就在里面。动手试试吧!