Nginx本地代理需配对解决路径重写、请求头透传及WebSocket支持：/api/路径转发需注意proxy_pass末尾斜杠；必须添加Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto等头；WebSocket需设proxy_http_version 1.1及Upgrade、Connection头。
在本地开发前后端分离项目时，用 Nginx 的 proxy_pass 做反向代理，能绕过浏览器跨域限制，让前端请求像调用同源接口一样访问后端服务。关键不是单纯写一行 proxy_pass，而是配对解决路径重写、请求头透传、WebSocket 支持等实际问题。
基础代理配置（解决跨域和路径转发）
假设前端运行在 http://localhost:3000，后端 API 服务在 http://localhost:8080，希望所有以 /api/ 开头的请求都转给后端：
location /api/ {
proxy_pass http://localhost:8080/;
}
注意末尾斜杠：
- proxy_pass http://localhost:8080/; → 会把 /api/users 转为 /users（自动剥离 /api 前缀）
- proxy_pass http://localhost:8080;（无末尾斜杠）→ 会把 /api/users 转为 /api/users（原样转发，后端需匹配带 /api 的路径）
必须补充的代理头（否则后端拿不到真实 IP 和协议）
默认情况下，后端看到的 Remote-Addr 是 Nginx 本机地址，X-Forwarded-For 和 X-Forwarded-Proto 为空。加上这些头才能正确识别用户来源和 HTTPS 状态：
-
proxy_set_header Host $host;—— 保持原始 Host，避免后端基于 Host 做路由或跳转出错 -
proxy_set_header X-Real-IP $remote_addr;—— 传递真实客户端 IP -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;—— 支持多层代理链 -
proxy_set_header X-Forwarded-Proto $scheme;—— 让后端知道请求是 http 还是 https
支持 WebSocket（如后端有实时通信接口）
如果后端用了 WebSocket（比如 /ws 或 /socket.io），默认 HTTP 代理会断开连接。需显式升级协议并透传相关头：
-
proxy_http_version 1.1;—— 必须设为 1.1，HTTP/1.0 不支持 upgrade -
proxy_set_header Upgrade $http_upgrade;—— 透传 Upgrade 请求头 -
proxy_set_header Connection "upgrade";—— 强制建立长连接
完整示例：
location /ws/ {
proxy_pass http://localhost:8080/ws/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
常见坑与调试建议
- 前端代码里请求地址写相对路径（如
fetch('/api/user')），不要写死http://localhost:8080/api/user - Nginx 配置改完必须执行
nginx -t检查语法，再nginx -s reload生效 - 查看 Nginx 错误日志（通常是
/usr/local/var/log/nginx/error.log或/var/log/nginx/error.log）定位 502/504 问题 - 用浏览器开发者工具的 Network 面板确认请求是否真正发到了
/api/路径，响应状态码是否为 200
