为何收到502 Bad Gateway？附Node.js+Nginx部署用Dockerfile

阿华AIGC实验室

2026-5-26

排查Node.js + Nginx Docker部署的502 Bad Gateway错误

嘿，我来帮你搞定这个502问题！这种情况在Docker部署Node+Nginx的场景里特别常见，咱们一步步捋清楚可能的诱因：

首先先看你提供的Dockerfile——我注意到builder阶段只完成了依赖安装，但没有把应用代码复制到容器的/opt/app目录！这会导致Node容器里根本没有你的业务代码，服务自然启动不起来，Nginx转发请求时就会返回502。你需要在builder阶段的末尾加上这段代码：

# 复制本地应用代码到容器目录
COPY . /opt/app
# 切换到应用工作目录
WORKDIR /opt/app

接下来，咱们梳理其他高频出错点：

端口不匹配问题
- 确认你的Node应用监听的端口（比如默认的3000），和Nginx配置里proxy_pass指向的端口完全一致。比如Nginx配置应该是这样的：
```
location / {
    proxy_pass http://node-app:3000; # node-app是Node容器的自定义服务名，端口要和Node应用监听的一致
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
```
- 同时，Node应用代码里要确保监听0.0.0.0而不是localhost，不然容器外部（包括Nginx容器）根本访问不到服务：
```
app.listen(3000, '0.0.0.0', () => {
    console.log('Server running on port 3000');
});
```
容器网络连通性
- 一定要保证Nginx容器和Node容器在同一个Docker网络里。你可以先创建一个专属网络：docker network create app-network，然后启动两个容器时都加上--network app-network参数，同时给Node容器设置--name node-app（对应Nginx配置里的服务名）。
Node应用启动失败
- 查看Node容器的日志，确认应用是否真的正常启动了：docker logs <你的Node容器名>。如果有依赖缺失、代码语法错误，都会导致服务启动失败，Nginx转发时就会返回502。
Nginx配置语法错误
- 检查Nginx配置文件是否有语法问题：docker exec <你的Nginx容器名> nginx -t，如果有错误会提示具体位置，修复后重启Nginx容器：docker restart <你的Nginx容器名>。

最后给你补一个完整的多阶段构建Dockerfile示例，方便你参考：

# 构建阶段：安装依赖并打包应用
FROM node:latest as builder
MAINTAINER Cristi Boariu <cristiboariu@gmail.com>

# 利用package.json缓存依赖
ADD package.json /tmp/package.json
RUN cd /tmp && npm install

# 准备应用目录并复制依赖
RUN mkdir -p /opt/app && cp -a /tmp/node_modules /opt/app/

# 复制应用代码并切换工作目录
COPY . /opt/app
WORKDIR /opt/app

# 生产运行阶段：用轻量的Alpine镜像
FROM node:alpine
COPY --from=builder /opt/app /opt/app
WORKDIR /opt/app
EXPOSE 3000
CMD ["npm", "start"]

内容的提问来源于stack exchange，提问作者Cristian Boariu