Next.js中WebSocket只能在客户端组件useEffect内初始化并管理生命周期，服务端完全不支持；需用useRef存储实例、检查readyState后发送消息，并通过独立服务或现有后端提供WS端点。
Next.js客户端页面里直接用 WebSocket 就行，别碰服务端
next.js 的 app router 中，websocket 只能在客户端组件（或 "use client" 模块）里初始化，服务端组件（包括 generatestaticparams、fetch、getserversideprops）完全不支持。这不是限制，是浏览器 api 的天然边界——websocket 本质就是个 dom api，和服务端 runtime 无关。
常见错误：在服务端组件里写 new WebSocket(...)，会直接报 ReferenceError: WebSocket is not defined；或者试图在 useEffect 外初始化连接，导致 hydration 不一致或多次重复连接。
- 只在带
"use client"的组件顶层作用域外、useEffect内创建实例 - 连接地址必须是真实可访问的 ws/wss URL（如
wss://echo.websocket.org），不能是http://localhost:3000/api/ws这类路径——那是 HTTP 路由，不是 WebSocket 端点 - 如果用本地开发代理（比如
next.config.js的rewrites），它对 WebSocket 无效，得单独配反向代理或改用真实后端地址
useEffect 里建连接 + 清理是唯一可靠模式
手动管理 WebSocket 生命周期的关键是：连接在 useEffect 中建立，关闭逻辑放在返回的清理函数里。跳过这步，轻则内存泄漏，重则页面切走后还在发消息、收消息时 this.readyState === 0 报错。
示例片段（精简核心逻辑）：
"use client";
import { useEffect, useRef } from 'react';
export default function Chat() {
const socketRef = useRef<WebSocket | null>(null);
useEffect(() => {
const socket = new WebSocket("wss://your-ws-endpoint.com");
socketRef.current = socket;
socket.onopen = () => console.log("connected");
socket.onmessage = (e) => console.log("received:", e.data);
socket.onerror = (e) => console.error("ws error", e);
return () => {
if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
socket.close();
}
};
}, []);
return <div>Chat UI</div>;
}
-
useRef存实例，避免useState触发重渲染，也防止闭包捕获旧 socket - 清理函数里判断
readyState再关，避免调用close()时报InvalidStateError - 不要在
onmessage里直接更新 state（尤其用useState），需加if (!mounted) return判断或用useReducer+dispatch配合 ref 控制
Next.js 13+ App Router 下无法用 getServerSideProps 或 API Route 做 WebSocket 服务端
Next.js 的 app/ 目录下，API Routes 是基于 Node.js 的 HTTP handler，不支持升级为 WebSocket 连接（即没法响应 Upgrade: websocket 请求头）。你写的 app/api/ws/route.ts 实际仍是普通 HTTP 接口，强行塞 WebSocket 服务逻辑会失败。
正确做法只有两个：
- 用独立服务：Node.js（
ws库）、Deno、NestJS、甚至云服务（Vercel Edge Functions 不支持 WS，但 AWS Lambda + API Gateway WebSocket API 支持） - 复用现有后端：如果你已有 Express/Fastify 服务，把 WebSocket endpoint 挂在上面，Next.js 客户端直连即可
- 开发时想本地联调？别依赖 Next.js 启动的服务端，单独起一个
wsserver（npx tsx ws-server.ts），前端连ws://localhost:8080
消息发送前务必检查 socket.readyState === WebSocket.OPEN
网络抖动、页面切换、连接未就绪就发消息，都会导致 socket.send() 抛出 InvalidStateError: Failed to execute 'send' on 'WebSocket': Still in CONNECTING state。这个错误不会被 try/catch 捕获（它是异步抛出的），只能靠状态判断预防。
- 发消息前加守卫：
if (socket.readyState !== WebSocket.OPEN) return; - 更健壮的做法：封装一个
sendMessage函数，内部用queue缓存未发消息，等onopen后批量 flush - 别依赖
onopen回调里的send—— 它可能比你预期早触发（比如服务端快速响应），而你的业务逻辑还没准备好
WebSocket 在 Next.js 里没魔法，它就是浏览器原生 API。真正容易卡住的，是误以为框架能帮你接管连接生命周期，或者试图绕过浏览器限制去“服务端建 WS”。把连接逻辑交给客户端、把服务端留给真正的 WebSocket 服务，事情就简单了。
