配置Socket连接时触发TypeError: Cannot read properties of undefined (reading 'server')

核心原因 #

这个错误是因为res.socket为undefined，通常出现在两种场景：

1. 在Next.js App Router（13+版本，app目录下的API路由）中使用了Pages Router的Socket.io挂载方式，App Router的API响应对象不包含socket属性。
2. 在Pages Router中，但NextApiResponseWithSocket类型定义错误，或者API路由文件放置路径不正确。

针对Pages Router的解决步骤 #

如果你的API路由在pages/api目录下：

1. 修正类型定义
   确保@/types/socket-types中的NextApiResponseWithSocket正确扩展Next.js的响应类型：

   import type { NextApiResponse } from 'next';
   import type { Server } from 'socket.io';
   
   export type NextApiResponseWithSocket = NextApiResponse & {
     socket: {
       server: {
         io?: Server;
       };
     };
   };
   

2. 确认文件路径
   确保API路由文件放在pages/api/socket.ts（或对应路径），这样Socket.io的path: "/api/socket"才能匹配。
3. 检查Next.js版本
   确保使用Next.js 12+版本，旧版本的res.socket结构不同。

针对App Router的解决步骤 #

如果你的API路由在app/api目录下：
App Router使用Web标准的Request/Response对象，没有socket属性，需要改用Edge Runtime处理WebSocket：

// app/api/socket/route.ts
import { Server } from 'socket.io';

export const runtime = 'edge';

export async function GET(request: Request) {
  try {
    const { socket, response } = await Deno.upgradeWebSocket(request);
    
    const io = new Server({
      path: '/api/socket',
      addTrailingSlash: false,
    });

    io.on('connection', (socket) => {
      socket.broadcast.emit('userServerConnection');
      socket.on('hello', (msg) => {
        socket.emit('hello', msg);
      });
      socket.on('disconnect', () => {
        console.log('A user disconnected');
        socket.broadcast.emit('userServerDisconnection', socket.id);
      });
    });

    io.attach(socket);
    return response;
  } catch (err) {
    return new Response('WebSocket upgrade failed', { status: 500 });
  }
}

注意：App Router中使用WebSocket需要启用Edge Runtime，且部分部署环境支持此特性。

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