Next.js与Socket.IO无法连接问题求助

问题根源 #

1. 错误将Socket.IO客户端代码放在API路由文件（api/test.js）中：API路由运行在服务器端，缺少浏览器环境的WebSocket/XHR支持，无法作为Socket客户端发起连接。
2. 客户端初始化未指定正确的服务器地址与Socket路径：io()无参数调用时，在服务器端环境无法自动解析地址，导致日志中hostname、uri等参数显示为undefined。
3. 服务器端Socket.IO未配置匹配路径：默认路径/socket.io与Next.js API路由/api/socket不兼容，客户端无法找到服务端点。

修复步骤 #

1. 迁移客户端代码到前端组件 #

删除api/test.js，将Socket客户端逻辑移至前端页面组件（如pages/index.js或App Router下的app/page.js）：

import { useEffect } from 'react';
import io from 'socket.io-client';

export default function Home() {
  useEffect(() => {
    // 初始化Socket客户端，指定服务器地址与对应路径
    const socket = io('http://localhost:3000', {
      path: '/api/socket/socket.io'
    });

    socket.on('connect', () => {
      console.log('已连接到Socket服务器');
      socket.emit('hello', '客户端测试消息');
    });

    socket.on('hello', (msg) => {
      console.log('收到服务器响应:', msg);
    });

    socket.on('a user connected', () => {
      console.log('有新用户连接');
    });

    // 组件卸载时断开连接
    return () => {
      socket.disconnect();
    };
  }, []);

  return <div>Socket.IO 测试页面</div>;
}

2. 修改服务器端Socket.IO配置 #

更新api/socket.js，为Socket.IO服务器指定匹配的路径：

import { Server } from "socket.io";

const ioHandler = (req, res) => {
    if (!res.socket.server.io) {
        console.log("*首次启动Socket.IO服务器");
        // 配置Socket.IO路径，与客户端保持一致
        const io = new Server(res.socket.server, {
            path: "/api/socket/socket.io"
        });

        io.on("connection", (socket) => {
            console.log("新Socket连接建立");
            socket.broadcast.emit("a user connected");
            socket.on("hello", (msg) => {
                console.log("收到客户端消息:", msg);
                socket.emit("hello", "world!");
            });
        });

        res.socket.server.io = io;
    } else {
        console.log("Socket.IO服务器已在运行");
    }
    res.end();
};

export const config = {
    api: {
        bodyParser: false,
    },
};

export default ioHandler;

3. 验证运行 #

1. 启动Next.js开发服务器：npm run dev
2. 访问http://localhost:3000，打开浏览器控制台，查看是否输出已连接到Socket服务器等日志
3. 多开一个标签页，观察控制台是否输出有新用户连接

关键注意事项 #

• Socket.IO客户端必须运行在浏览器环境，不能放在服务器端的API路由或服务端代码中
• 客户端与服务器端的path配置必须完全一致，否则会出现404错误
• 开发环境下需明确指定服务器地址（如http://localhost:3000），生产环境可使用window.location.origin动态获取

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