Next.js与Flutter的Socket连接实现方案咨询

核心适配思路 #

Next.js的Socket服务多挂载在API路由或App Router的Route Handler上，而非独立端口，所以Flutter客户端需要直接对接对应路由地址，而非传统的端口直连方式。

步骤1：确认Next.js Socket服务的正确配置 #

以socket.io结合Next.js Pages API路由为例，服务端代码（pages/api/socket.js）需明确Socket路径并配置CORS：

import { Server } from "socket.io";

export default function handler(req, res) {
  if (!res.socket.server.io) {
    const io = new Server(res.socket.server, {
      path: "/api/socket", // 必须与API路由路径匹配
      cors: {
        origin: ["http://localhost:5000", "你的Flutter真机IP/域名"], // 限制允许的客户端来源
        methods: ["GET", "POST"]
      }
    });

    res.socket.server.io = io;

    io.on("connection", (socket) => {
      socket.on("client_msg", (data) => {
        socket.emit("server_res", `收到Flutter消息：${data}`);
      });
    });
  }
  res.end();
}

先通过Next.js客户端测试连接正常后，再进行Flutter端配置。

步骤2：Flutter客户端的连接实现 #

使用socket_io_client包，连接时指定完整的Next.js服务地址和Socket路径：

import 'package:socket_io_client/socket_io_client.dart' as IO;

void initSocket() {
  // 替换为你的Next.js服务地址，开发环境通常是http://localhost:3000
  IO.Socket socket = IO.io(
    'http://localhost:3000',
    IO.OptionBuilder()
        .setTransports(['websocket']) // 强制使用WebSocket传输，避免轮询问题
        .setPath('/api/socket') // 必须与Next.js服务端的path一致
        .enableAutoConnect()
        .build(),
  );

  socket.onConnect((_) {
    print('已连接到Next.js Socket服务');
    socket.emit('client_msg', 'Hello from Flutter');
  });

  socket.on('server_res', (data) {
    print('服务端响应：$data');
  });

  socket.onDisconnect((_) => print('连接断开'));
}

• 开发环境中，若Flutter运行在真机上，需将Next.js服务地址替换为电脑的局域网IP（如http://192.168.1.100:3000）
• 生产环境需替换为正式部署的Next.js域名

步骤3：常见问题排查 #

• CORS报错：检查Next.js服务端的cors.origin配置，确保包含Flutter客户端的访问地址
• 连接超时：先测试Flutter能否访问Next.js的API路由（如http://localhost:3000/api/socket），确认服务正常运行
• 版本不兼容：保证服务端socket.io与Flutter端socket_io_client版本匹配（如服务端用4.x，客户端也选4.x系列）

可选方案：Next.js启动独立端口Socket服务 #

若更习惯传统端口式Socket服务，可通过自定义server.js启动独立服务：

const { createServer } = require('http');
const next = require('next');
const { Server } = require('socket.io');

const dev = process.env.NODE_ENV !== 'production';
const app = next({ dev });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  const server = createServer((req, res) => {
    handle(req, res);
  });

  const io = new Server(server, {
    cors: {
      origin: "*" // 生产环境需限制来源
    }
  });

  io.on('connection', (socket) => {
    console.log('客户端已连接');
    // 处理Socket事件逻辑
  });

  server.listen(3000, () => {
    console.log('> 服务运行在http://localhost:3000');
  });
});

这种模式下，Flutter客户端直接连接http://localhost:3000即可，无需指定路径。

内容的提问来源于stack exchange，提问作者Thi Ha Zaw