做 Web 开发的人多多少少都遇到过这种场景Node.js 服务在本地跑得好好的一旦想上线、想给同事演示、想在同一台机器上多跑几个服务立刻就开始乱了——端口冲突、环境不一致、代码依赖装不上、服务器上少个环境变量就是跑不起来。我自己折腾了几轮之后现在固定下来的一套方案就是Docker 跑服务Nginx 做统一入口Node.js 专心写业务。这个组合的好处非常直接环境一致性彻底解决流量管理收口到 Nginx业务代码不用管部署细节。这篇就按我实际操作的路径从零开始把一个 Node.js 服务封装成 Docker 镜像再用 Nginx 容器反向代理到宿主机 80 端口整套跑通。这套内容适合谁一是刚接触 Docker、想找个真实项目练手的开发者二是手动部署搞烦了、想规范化发布流程的小团队三是想把多个 Node 服务统一管理、但还没想清楚怎么搭入口层的同学。配合 Docker Compose 一起讲你只需要两台容器——一台跑 Node.js一台跑 Nginx最后对外只暴露一个 80 端口所有请求先进 Nginx再按规则转发给 Node.js链路清清楚楚。文章尽量不绕弯子每一步都能直接复制到终端里执行。1. 整体设计思路为什么要用 Nginx 反向代理 Node.js1.1 反向代理解决的核心痛点Node.js 默认监听方式很纯粹应用直接绑定某个端口比如 3000启动后就在那个端口上等待请求。小范围使用没问题但遇到下面几种情况就开始难受了服务数量一多每个服务占一个端口前端和外部调用方根本记不住Node 实例直接对外缺少请求头过滤、访问控制、超时管理这些入口级能力静态资源JS、CSS、图片也走 Node 业务逻辑白白消耗应用进程的资源需要升级或重启 Node 服务时外部请求会直接打到正在重启的端口上出现短暂不可用。引入反向代理后Nginx 变成了所有外部流量的总机。它监听 80 或 443外部请求进来后由 Nginx 根据路径或域名决定分发给哪个 Node 服务。从调用方的视角看后端地址永远是固定的 Nginx 入口从 Node 应用视角看它只需要老老实实在容器里监听一个内部端口不用关心自己在公网上的形态。打个好理解的比方Node.js 是办公室里的各个业务组Nginx 是前台。来访者不用知道每个业务组在哪个工位端口统一到前台80 端口报到前台再按事由把人引导到具体工位。前台还能做来访登记日志、排队限流、拦无关人员安全策略而这些功能都不需要业务组自己实现。1.2 为什么选 Docker 来做这套组合其实反向代理的方案很多直接用宿主机装 Nginx 也能实现同样的效果。但加上 Docker 之后有三个角度的收益是肉眼可见的环境一致性本地、测试机、生产机的 Node 版本、系统依赖完全一致Dockerfile 就是环境的唯一真相来源彻底告别在我机器上是好的。隔离与清理每个服务一个容器端口、文件系统、进程全部隔离不要用了直接删容器、删镜像不污染宿主机环境。编排能力多个容器之间的网络互联、依赖关系、自动重启用 Docker Compose 一个文件就能管理比手工敲命令维护彼此关联的进程可靠得多。我踩过不少坑之后发现这套组合最舒服的一点是问题域被切开了。Node 代码出问题去查 Node 容器请求转发不对去查 Nginx 配置网络不通去查 Docker 网络。每一层都足够简单排查路径也非常清晰。2. 环境准备先装好 Docker 这只“集装箱”2.1 各平台安装方式和验证命令Docker 官方提供了三套主流方案选哪个取决于你的操作系统。Windows推荐装 Docker Desktop。安装前建议先把 WSL2 搞定Docker Desktop 的后端会基于 Hyper-V 或 WSL2 运行。装上以后设置里记得开启Use the WSL 2 based engine。打开终端验证docker --version docker compose versionmacOS同样用 Docker Desktop下载安装包拖进 Applications 就行基本上零配置Docker 菜单栏图标变绿就说明引擎在正常跑。Linux以 Ubuntu 为例官方推荐用 apt 仓库安装旧版本先卸载然后按官方文档添加 Docker 的 apt 源或者图省事直接拉官方安装脚本curl -fsSL https://get.docker.com | sudo sh sudo usermod -aG docker $USER注意第二行把当前用户加进 docker 组这样不用每次敲 sudo。改完要重新登录终端才生效。装好之后最重要的一步验证是跑一次 hello-worlddocker run hello-world能正常打印出 Hello from Docker! 并且没有权限报错环境就相当稳了。2.2 顺手优化镜像拉取速度docker pull默认从官方 Docker Hub 拉取在国内网络条件下经常很慢特别是 node 这种基础镜像动不动几百兆。我的做法是提前配好镜像加速器国内各大云厂商都有容器镜像加速服务注册之后在控制台可以拿到专属加速地址。以 Docker Desktop 为例在 Settings - Docker Engine 里编辑配置{ registry-mirrors: [https://你的加速器地址] }Linux 用户则编辑/etc/docker/daemon.json同样加registry-mirrors字段然后执行sudo systemctl restart docker。配好之后拉镜像速度会有质的提升这是非常值得提前做的一步不然第一次构建镜像就会卡在等待下载上很消磨耐心。3. 快速搭建一个 Node.js 服务作为实验对象3.1 初始化项目结构和依赖反代的对象总得先存在。我先在本地建一个最小的 Node.js 项目目录结构尽量贴近真实项目但又不引入多余复杂度node-docker-demo/ ├── package.json ├── src/ │ └── index.js初始化mkdir node-docker-demo cd node-docker-demo npm init -y这个 demo 我不打算用 Express 这种框架直接用 Node 内置的http模块写一个响应 JSON 的接口这样能减少依赖、聚焦在 Docker 和 Nginx 这条主线上。如果你习惯用 Express思路完全一样启动命令不变镜像构建一样能通。3.2 写一个能返回业务数据的 HTTP 服务核心代码写在src/index.js里const http require(http); const server http.createServer((req, res) { if (req.url /health) { res.writeHead(200, { Content-Type: application/json }); res.end(JSON.stringify({ status: ok, service: node-docker-demo })); return; } res.writeHead(200, { Content-Type: application/json }); res.end(JSON.stringify({ message: Hello from Node.js inside Docker, path: req.url })); }); const port process.env.PORT || 3000; server.listen(port, () { console.log(server is running at http://localhost:${port}); });这里有两个要点端口不要写死用process.env.PORT || 3000。后面在 Docker 里通过环境变量控制端口会比改代码灵活得多。加了一个/health健康检查路径。实际部署时负载均衡和监控系统会用到这里提前埋好后面排查 Nginx 转发问题时也能用它快速验证 Node 服务到底通不通。package.json 里把启动命令补上{ scripts: { start: node src/index.js } }本地可以先跑一下npm start浏览器访问http://localhost:3000看到 JSON 返回就说明业务代码没问题接下来进入容器化环节。4. 用 Dockerfile 把 Node.js 服务打包成镜像4.1 Dockerfile 的关键写法与踩坑点在项目根目录创建Dockerfile这是整个容器化流程的核心文件。我推荐的初始版本FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --omitdev COPY src ./src ENV PORT3000 EXPOSE 3000 CMD [node, src/index.js]逐行解释一下为什么这么写node:20-alpine基于 Alpine Linux 的 Node 官方镜像体积比完整版小很多构建和拉取都快。选 LTS 版本号不要选最新大版本生产项目追求稳定。WORKDIR /app设置容器内的工作目录。后续所有相对路径都基于它避免代码散落在根目录。COPY package*.json ./先拷贝依赖描述文件这时候还没拷源码利用的是 Docker 层缓存机制只要 package.json 没变后面构建时这一层直接走缓存省时间。RUN npm ci --omitdevnpm ci比npm install更适合 CI/镜像构建场景它会严格按照 package-lock.json 安装不会改变依赖版本--omitdev表示不装 devDependencies。COPY src ./src源码一般放最后拷贝因为源码改动频率最高这样能最大化利用缓存。ENV PORT3000设置容器内默认端口与代码里的process.env.PORT呼应。EXPOSE 3000这个指令更多是文档性质的告诉 Docker 该容器运行时监听 3000 端口。真正端口映射还是要靠docker run -p或 Compose 里的 ports 配置。CMD [node, src/index.js]容器启动后的默认命令。注意这里用了 exec 形式直接执行 node 进程而不是npm start省掉一层 sh 进程容器内的 PID 1 就是 node信号处理更标准。别忘了加.dockerignore文件把不必要的本地文件排除在外node_modules npm-debug.log .git .env不加这个的后果是构建上下文会把node_modules一起发给 Docker 守护进程既慢又跟镜像里新装的依赖产生混淆。我第一次就踩过这个坑镜像构建每次都等半天后来才发现是本地 node_modules 太大。4.2 构建镜像并验证容器运行在项目根目录执行docker build -t node-docker-demo .-t是给镜像打标签方便后面引用。构建完成之后先跑一个前台容器看日志docker run --rm -p 3000:3000 node-docker-demo能看到 node 打印的启动日志再访问http://localhost:3000返回 JSON说明镜像本身没问题。--rm表示测试完退出即删容器避免留下一堆垃圾容器。确认没问题后改成后台运行docker run -d --name node-app -p 3000:3000 node-docker-demo注意到这里我们其实只用到了 Docker还没有任何反向代理。如果你只是想保证开发环境一致到这一步就已经有价值了但真正的生产形态需要把对外入口从 3000 端口收敛到 80 端口这正是下一节的主角。5. Nginx 反向代理与容器网络配置5.1 Nginx 配置文件的思路和坑现在需要一个 Nginx 容器来接收外部请求然后转发给 Node 容器。难点不在于 Nginx 本身而在于Nginx 容器怎么找到 Node 容器。容器之间通信有几种方式早期常用--link现在已经不推荐最正规的做法是创建自定义 Docker 网络让两个容器在同一个网络里直接用容器名互相访问。Docker 内置 DNS 会自动把容器名解析成对应 IP。先创建一个自定义网络docker network create app-net把已经存在的 node-app 容器连进去docker network connect app-net node-app然后准备 Nginx 的配置文件。我在项目目录下建一个nginx/文件夹放nginx.confevents {} http { upstream node_servers { server node-app:3000; } server { listen 80; location / { proxy_pass http://node_servers; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location /health { proxy_pass http://node_servers/health; } } }几个关键点upstream node_servers里写node-app:3000这里node-app就是 Node 容器的名称。Docker 网络会让它自动解析到对应容器 IP这是容器互联最优雅的地方。proxy_pass http://node_servers;表示把请求转发给 upstream 定义的一组后端。proxy_set_header必须写全。Node 应用要拿客户端真实 IP 和原始 Host依赖这些头部。不加的话后端看到的 IP 会全是 Nginx 容器的 IP做日志分析或限流时直接乱套。location /health单独拎出来反代方便将来对健康检查路径做差异化处理比如不放行到外部。如果你之前没写过 Nginx 配置可能会疑惑为什么文件里没有http {}之外的默认内容。这里是精简版但结构是完整的events必须有http块里定义 server。日志、gzip、静态资源等生产参数可以根据需要补。5.2 启动 Nginx 容器并完成连通验证启动 Nginx 容器时要用-v把本地的配置文件挂载进容器这样做的好处是改配置不用重新构建镜像docker run -d \ --name nginx-proxy \ -p 80:80 \ -v $(pwd)/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \ --network app-net \ nginx:stable-alpine各部分说明-p 80:80宿主机 80 端口映射到容器 80。-v $(pwd)/nginx/nginx.conf:/etc/nginx/nginx.conf:ro挂载配置:ro表示容器内只读避免容器内误改宿主机文件。--network app-net和 Node 容器进同一个网络。镜像用nginx:stable-alpine同样是体积优先。此时访问http://localhost不写端口号直接 80 端口应该能看到 Node 服务返回的 JSON。如果你能看到说明一条完整的链路已经通了浏览器/curl - 宿主机 80 - Nginx 容器 - Node 容器 - 业务代码。这里我想特别强调一下 X-Forwarded-For 头的作用。不加这个头的时候Node 里用req.connection.remoteAddress取到的永远是 Nginx 容器的 IP所有请求看起来都来自同一个地址。加了之后Nginx 会在转发时把原始客户端 IP 追加在请求头里Node 应用读取 X-Forwarded-For 头才能拿到真实来源。对做访问日志、风控、地域分析的应用来说这一行配置可以直接决定数据准确度。6. 用 Docker Compose 把两条“船”编排在一起6.1 编写 docker-compose.yml到这一步基础设施已经能跑了但靠两条docker run命令手动维护终究不是长久之计。Docker Compose 可以让你用一个 YAML 文件声明所有容器、网络、挂载、依赖关系。以后在另一台机器上复现环境只需要这一个文件外加目录里的源码和 Nginx 配置。我建议在项目根目录创建docker-compose.ymlversion: 3.8 services: node-app: build: context: . dockerfile: Dockerfile container_name: node-app environment: - PORT3000 networks: - app-net restart: unless-stopped nginx: image: nginx:stable-alpine container_name: nginx-proxy ports: - 80:80 volumes: - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro depends_on: - node-app networks: - app-net restart: unless-stopped networks: app-net: driver: bridge几个要点解释一下不再需要手动docker build了Compose 会读取build.context和build.dockerfile自动构建 node 镜像。depends_on控制启动顺序确保 Nginx 在 Node 后面启动。但要注意它只保证容器启动了不代表 Node 进程已经就绪。对于本项目这种秒级启动的应用问题不大如果 Node 启动需要做初始化应该配 healthcheck 配合依赖等待。restart: unless-stopped是生产环境的好习惯服务崩溃或机器重启后会自动拉起减少人工介入。端口映射只放在 Nginx 这一层Node 容器不映射任何宿主机端口外部只能通过 80 访问。这才是真正实现了端口收敛。关于depends_on我想多说一句因为 Nginx 启动时如果发现 upstream 里没有可用的后端它不会崩顶多返回 502后续 Node 启动完就会自动恢复。所以depends_on在这里是兜底优化不是严格必需。服务端容器编排里有个更严谨的做法是加 healthcheck这里不展开但如果你将来部署依赖重一点的中间件一定要研究一下。6.2 一键启动和验证效果动手之前先把手工启动的两个容器停掉避免端口冲突docker stop nginx-proxy node-app docker rm nginx-proxy node-app然后用 Compose 一键拉起docker compose up -d --build执行后 Docker 会先构建 node 镜像再拉取 nginx 镜像然后按依赖顺序启动两个容器。查看状态docker compose ps正常输出两个服务STATUS 是 Up。再访问http://localhost依然能拿到 JSON访问http://localhost/health能看到{status:ok}。这时候我建议你顺手测试一下后端挂了会怎样把 node 容器停掉再访问 80 端口会看到 502 Bad Gateway把 node 容器重新启动稍等几秒再访问服务自动恢复。这个现象能直观理解反向代理的价值——它是入口后端恢复后无需重启 Nginx 就能自动回到正常状态。7. 实战中高频踩坑与排查技巧7.1 502 Bad Gateway先定位是 DNS 还是后端502 是这套组合里最常见的错误看到它的第一反应不要慌按下面顺序排查在 Nginx 容器内部测试后端是否可达docker exec -it nginx-proxy sh wget -qO- http://node-app:3000/health如果能拿到响应说明容器网络通信没问题问题出在 Nginx 配置或 Node 服务本身如果报Host not found或者无法连接说明两个容器不在同一网络里或者 Node 容器没启动。检查 Node 容器日志docker logs node-app看有没有进程崩溃或端口未监听的报错。确认 Nginx 配置文件有没有语法错误docker exec nginx-proxy nginx -t这条命令会检查配置语法如果报错会精确到行号。改完配置后执行docker exec nginx-proxy nginx -s reload热加载新配置不需要重启容器。7.2 端口占用与宿主机冲突启动时如果报port is already allocated说明宿主机 80 或 3000 端口被别的程序占了。Linux 上排查sudo lsof -i :80 sudo lsof -i :3000找到占用进程后选择要么停掉占用的服务要么改端口映射比如把 Nginx 的映射改成8080:80访问时用http://localhost:8080验证。如果你在 Windows/macOS 上使用 Docker Desktop还要注意是不是有别的开发服务器占了端口。7.3 镜像构建和依赖安装故障构建镜像时最常见的坑有两个一是npm ci报错说 package-lock.json 不存在或版本不一致。解决方案是先本地跑npm install生成 lock 文件确认后提交到仓库。二是COPY package*.json ./这一步报找不到文件。多半是构建上下文不对确认你执行的docker build命令是在项目根目录而不是在子目录。一个简单的验证方式看构建输出上下文路径是不是包含你的 package.json。如果依赖源下载慢可以配置 npm 的国内镜像源比如把 registry 指向 npmmirror 提供的地址然后把npm ci配合自定义源使用。注意这是改动 npm 层面的配置和 Docker 镜像加速器是两回事不要混淆。7.4 实践建议日志先行排查任何容器问题时第一条命令永远是看日志docker logs -f --tail 100 node-app docker logs -f --tail 100 nginx-proxyNginx 容器里访问日志和错误日志默认输出到 stdout容器内部路径是/var/log/nginx/access.log和/var/log/nginx/error.log但docker logs能直接看到。观察错误日志里有没有connect() failed、no live upstreams之类的关键信息排查速度会快很多。根据我的经验80% 的反向代理问题都是三板斧网络不在同一网络、配置文件路径挂载错误、后端服务没起来。顺着这个思路查很少会卡住。写在最后的一点实战体会整套 Docker Nginx Node.js 的组合跑通之后你会发现部署这件事变得特别顺手。代码改完重新 build 一次镜像Nginx 配置要调整就改本地文件再挂载进去两个容器的状态用docker compose ps一眼就能看到。以后再接入新的 Node 服务只需要复制一套服务配置改端口和路径规则就行完全不用操心环境变量和依赖污染的问题。我自己的体会是这套架构还有一个隐藏收益它倒逼你把代码和环境分离。因为容器是一次性的任何运行时的东西都得显式声明你原来靠手工在服务器上执行几条命令才搭起来的环境现在全变成了代码。这对于团队协作、新人上手、以及后续做 CI/CD 流水线都是一个特别扎实的基础。下一步你可以顺着这个方向尝试接入 HTTPS在 Nginx 里配证书、多实例 Node 负载均衡或者把 Nginx 日志接入集中采集系统。路还很长但地基已经打稳了。