Next.js API中Socket.IO监听器热重载不生效的原因

项目代码 #

前端页面（pages/index.tsx） #

let socket: Socket;
const Home: NextPage = () => {
  useEffect(() => {
    async function socketInit() {
      // 启动服务
      await fetch("http://localhost:3000/api/socket");

      // 连接Socket
      socket = io();
      socket.on("connect", () => {
        console.log("hello");
      });
    }

    socketInit();
  }, []);

  return (
    <button
      onClick={() => {
        socket.emit("test");
      }}
    >
      hello
    </button>
  );
};

后端API路由（pages/api/socket.ts） #

export default function handler(
  req: NextApiRequest,
  res: Res
) {
  if (res.socket.server.io) { res.end(); return; }

  const io = new IOServer(res.socket.server);
  res.socket.server.io = io;
  io.on('connection', socket => {
    socket.on('test', () => {
      console.log("1");  // 修改为"2"后，不重启开发服务器就不会生效
    });
  });

  res.end();
}

问题 #

服务器端的test事件监听回调修改后，无法通过Next.js的热重载更新，只有重启开发服务器才会生效，这是为什么？

原因解析 #

• 核心问题出在Socket.IO服务的单例初始化逻辑：第一次请求/api/socket时，会创建IOServer实例并挂载到res.socket.server.io上，后续所有请求都会触发if (res.socket.server.io)的判断，直接返回而不执行后续的服务初始化代码。
• Next.js的热重载仅会重新编译并替换修改后的API路由模块，但Socket.IO服务实例已经在第一次请求时就绑定到了底层服务器进程中，新编译的模块代码没有机会被执行——因为后续请求都走了提前返回的分支，不会重新初始化服务，自然也不会加载新的事件监听回调。
• 总结：Socket.IO服务一旦初始化就会常驻服务器进程，热重载更新的新代码无法覆盖已经在运行的服务实例，必须重启进程才能加载新的监听逻辑。

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