502错误本质是Nginx无法从后端获取有效响应，根本原因在于代理与上游间的通信链路中断，常见于后端未启动、端口配置错误（如localhost解析为IPv6）、监听地址未绑定0.0.0.0、防火墙拦截、超时设置过短或服务崩溃等场景。
为什么Nginx反向代理返回502 Bad Gateway
502错误本质是Nginx无法成功连接到你配置的proxy_pass后端服务——它发出了请求，但没收到有效响应。不是前端代码问题，也不是跨域配置错，而是Nginx和目标服务之间的“通信链路”断了。
常见触发场景包括：后端服务根本没启动、监听地址/端口写错、服务启在127.0.0.1但Nginx用localhost解析失败、后端进程崩溃、防火墙拦截、或服务响应超时未及时返回。
- 检查后端是否真实运行：
curl -v http://127.0.0.1:3000/health（把端口换成你实际用的） - 确认监听地址：Node.js/Express默认只监听
127.0.0.1，若Nginx在Docker或远程机器上，需改成0.0.0.0:3000 - 查Nginx错误日志：
/var/log/nginx/error.log，里面通常有类似connect() failed (111: Connection refused)或upstream timed out的线索
proxy_pass地址写localhost还是127.0.0.1
绝大多数情况下，必须用127.0.0.1，而不是localhost。这不是风格偏好，是DNS解析引发的真实故障点。
Linux系统中，localhost可能被解析为::1（IPv6地址），而后端服务只监听IPv4的127.0.0.1，导致Nginx尝试连::1:3000却失败，直接报502。
- 正确写法：
proxy_pass http://127.0.0.1:3000; - 错误写法：
proxy_pass http://localhost:3000;（尤其在CentOS/RHEL系系统上高发） - 如果后端必须用域名（如docker compose服务名），确保Nginx容器能通过
docker network解析该域名，且服务已就绪再启动Nginx
timeout设置太短导致502
Nginx默认proxy_read_timeout是60秒，但很多开发环境后端启动慢、首次请求编译耗时长，或接口本身执行超过1分钟（比如导出大文件），就会触发超时并返回502。
这不是后端挂了，是Nginx“等不及”就放弃了。
- 在
location块内显式加大超时：proxy_connect_timeout 300;<br>proxy_send_timeout 300;<br>proxy_read_timeout 300;
- 注意：这些值单位是秒；生产环境不建议无限制调高，但开发/调试阶段设成300是安全的
- 改完记得重载：
nginx -s reload，不是重启
后端服务监听地址没放开
这是最容易被忽略的底层原因：你的Node.js、Koa、Express服务默认只绑定127.0.0.1，意味着它只接受来自本机回环接口的连接。而Nginx虽然也在同一台机器，但某些部署方式（如systemd托管、Docker、或非root用户启动）会让它实际走的是外部网络栈路径，导致连接被拒绝。
验证方式：在服务器上执行netstat -tuln | grep :3000，看输出是不是127.0.0.1:3000。如果是，就危险了。
- Express示例：
app.listen(3000, '0.0.0.0', () => {...}) - Koa示例：
server.listen(3000, '0.0.0.0') - 若用PM2启动，加
--node-args="--host 0.0.0.0"参数（具体依框架而定）
真正生效的监听地址必须是0.0.0.0:3000或[::]:3000，才能被Nginx稳定访问到。否则所有502排查都是在绕弯。
