Next.js项目需通过Nginx反向代理实现WebSocket实时通信：配置proxy_http_version 1.1、Upgrade/Connection头及长超时，前端连接wss://example.com/api/ws，后端独立运行于8080端口。
Next.js 项目默认以 SSR 或静态导出方式运行，但若需 WebSocket 实时通信（如聊天、通知、协作编辑），必须通过反向代理将 WebSocket 请求透传到后端服务。Nginx 本身不处理 WebSocket 逻辑，而是作为桥梁，正确升级 HTTP 连接并转发帧。关键在于配置 HTTP 协议升级头 和 长连接保活，否则连接会立即关闭或 502/504。
1. 构建并启动 Next.js 应用（含 WebSocket 后端）
Next.js 官方不内置 WebSocket 服务器，需自行集成（如用 ws、socket.io 或 Express + http.Server）。常见做法是：
- 在
pages/api/ws.ts或独立 Node.js 服务（如server.js）中启动 WebSocket 服务，监听非 3000 端口（例如8080）； - 确保 Next.js 的
dev或start服务与 WebSocket 服务分离运行（避免端口冲突）； - 若使用
getServerSideProps或 API Routes 触发实时逻辑，注意它们仍是无状态 HTTP 请求，不能替代长连接。
2. Nginx 配置 WebSocket 反向代理
假设 Next.js 已构建为生产静态文件（next build && next export）并托管在 /var/www/next-app，同时 WebSocket 后端运行在 localhost:8080。Nginx 配置需分两部分：
-
静态资源与路由代理：将
/指向 Next.js 导出的 HTML/JS/CSS； -
WebSocket 路径代理：将
/api/ws（或你定义的路径）代理至后端，并显式启用协议升级。
示例配置（/etc/nginx/sites-available/next-app）：
upstream websocket_backend {
server localhost:8080;
}
<p>server {
listen 80;
server_name example.com;</p><pre class="brush:php;toolbar:false;"># Next.js 静态文件服务
root /var/www/next-app/out;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
# WebSocket 代理（关键：保留 Upgrade 头 + 设置 Connection）
location /api/ws {
proxy_pass http://websocket_backend;
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;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 防止超时断连
proxy_read_timeout 86400;
proxy_send_timeout 86400;
}
}
⚠️ 注意：proxy_http_version 1.1 和 Upgrade/Connection 头缺一不可，否则 WebSocket 握手失败；proxy_read_timeout 建议设为大值，避免空闲连接被 Nginx 关闭。
3. 前端 WebSocket 连接地址写法
浏览器中不能直接连 ws://localhost:8080（跨域且非生产地址）。应统一走 Nginx 域名：
- 开发时可配
next.config.js的env或publicRuntimeConfig注入WEBSOCKET_URL: "wss://example.com/api/ws"； - 若部署 HTTPS，必须用
wss://（Nginx 自动处理 TLS 终止，后端仍用ws://）； - 连接时检查
event.target.url是否匹配代理路径，避免因路径不一致导致 404。
4. 补充：若用 Next.js App Router + Server Components
Server Components 本身不支持客户端 WebSocket 调用，实时能力仍需依赖前端 JS 初始化连接。但可在服务端（如 API Route）用 fetch 主动推送事件给 WebSocket 后端（例如收到表单提交后广播消息），实现“服务端触发 + 客户端接收”的混合模型。此时 Nginx 仅代理前端 WebSocket 连接，不参与服务端间通信。
