Next.js如何在多文件全局使用服务端Socket.io 解决生产IO未定义问题

核心问题成因 #

开发环境可正常运行、生产环境报IO实例未定义的本质原因是：

• Next.js 开发模式下，API路由与自定义Node服务运行在同一热重载进程，模块作用域变量可正常共享
• 生产构建时，API路由会被打包为独立的服务端模块，默认的模块作用域隔离会导致此前在独立文件中定义的IO实例无法被跨模块引用；若生产启动时误用Next.js默认的next start而非自定义server.js，还会出现Socket.io实例根本未初始化的问题

步骤1：调整启动脚本与自定义服务逻辑 #

首先修正package.json的启动配置，避免生产环境误用默认启动命令：

{
  "scripts": {
    "dev": "node server.js",
    "build": "next build",
    "start": "NODE_ENV=production node server.js"
  }
}

调整server.js逻辑，统一适配开发/生产环境，将IO实例挂载到Node全局对象：

// server.js
const { createServer } = require('http')
const { parse } = require('url')
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) => {
    const parsedUrl = parse(req.url, true)
    handle(req, res, parsedUrl)
  })

  // 全局挂载IO实例，避免跨模块引用失效
  if (!globalThis.io) {
    const io = new Server(server, {
      cors: {
        origin: "*", // 按实际需求调整跨域白名单
        methods: ["GET", "POST"]
      }
    })
    globalThis.io = io

    // 在此处添加Socket连接处理逻辑
    io.on('connection', (socket) => {
      console.log('前端客户端已连接，ID：', socket.id)
    })
  }

  const port = process.env.PORT || 3000
  server.listen(port, () => {
    console.log(`> 服务已启动于 http://localhost:${port}`)
  })
})

步骤2：封装IO获取工具函数 #

重构原socketIO.js逻辑，不要直接导出模块作用域的IO实例，改为从全局对象统一获取：

// utils/socketIO.js
export function getIO() {
  if (!globalThis.io) {
    throw new Error('Socket.io实例尚未初始化，请先在server.js中完成挂载')
  }
  return globalThis.io
}

步骤3：调整API路由调用逻辑 #

日志接收接口不要直接引用旧的socketIO导出实例，改用封装的getIO()获取实例：

// pages/api/log.js （App Router模式接口逻辑完全一致）
import { getIO } from '@/utils/socketIO'

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).end('仅支持POST请求')
  }

  const { message } = req.body
  if (!message) {
    return res.status(400).json({ error: '缺少日志message字段' })
  }

  // 触发Socket广播
  const io = getIO()
  io.emit('new-log', {
    message,
    timestamp: new Date().toISOString()
  })

  res.status(200).json({ success: true })
}

关键注意事项 #

• 禁止在模块顶层直接初始化IO实例并导出，生产环境打包时这类模块会被隔离，导致跨文件无法拿到同一个实例
• 必须保证生产环境启动脚本执行的是自定义的server.js，不要用默认的next start，否则Socket.io根本没有绑定到HTTP服务上
• 全局挂载IO实例时一定要加存在性判断，避免热重载或者模块重复加载时创建多个Socket.io实例造成端口冲突
• 若使用Next.js App Router模式的服务端接口，调用逻辑和Pages Router完全一致，均通过封装的getIO()方法从全局获取实例即可

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