Fastify与Socket.IO客户端连接失败排查及解决方案请求

错误原因分析 #

• 冗余依赖干扰：你安装了第三方path包，但Node.js已内置path模块，第三方老旧版本可能导致路径解析异常，间接引发Socket连接路径的404错误。
• 版本兼容性偏差：客户端Socket.IO使用4.6.0，服务器端使用4.7.2，细微版本差异可能导致握手协议不匹配，返回404。
• 缺失显式配置：未明确配置Socket.IO的CORS规则，即使同域场景下，也可能因Fastify默认路由拦截导致连接失败。

修正后的完整实现 #

1. 清理冗余依赖 #

先卸载不必要的第三方path包：

npm uninstall path

保留核心依赖清单：

{
  "fastify": "^4.22.2",
  "fastify-socket.io": "^4.0.0",
  "socket.io": "^4.7.2"
}

2. 服务器端代码（server.js） #

const fastify = require('fastify')
const socketio = require('fastify-socket.io')
const { join } = require('path') // 使用Node.js内置path模块
const { readFile } = require('fs').promises

const app = fastify({ logger: true })

// 注册socket.io并显式配置CORS，避免同域场景下的潜在拦截问题
app.register(socketio, {
  cors: {
    origin: "http://localhost:3000",
    methods: ["GET", "POST"]
  }
})

app.get('/', async (req, reply) => {
  const data = await readFile(join(__dirname, 'index.html'))
  reply.header('content-type', 'text/html; charset=utf-8')
  reply.send(data)
})

// 使用async/await替代回调，适配Fastify v4异步风格
const start = async () => {
  try {
    await app.listen({ port: 3000 })
    // 监听Socket连接事件
    app.io.on('connect', (socket) => {
      console.info('Socket connected!', socket.id)
    })
  } catch (err) {
    app.log.error(err)
    process.exit(1)
  }
}

start()

3. 客户端代码（index.html） #

将Socket.IO CDN版本与服务器端保持一致，并添加错误监听便于排查：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
  </head>
  <body>
    <h1>Look at the server log to see if the connection happened</h1>
  </body>
  <script src="https://cdn.socket.io/4.7.2/socket.io.min.js" integrity="sha384-mZLF4UVrpi/QTWPA7BjNPEnkIfRFn4ZEO3Qt/HFklTJBj/gBOV8G3HcKn4NfQblz" crossorigin="anonymous"></script>
  <script>
    // 显式指定连接地址，避免环境差异导致的路径问题
    const socket = io('http://localhost:3000');
    
    // 监听连接错误，快速定位问题
    socket.on('connect_error', (err) => {
      console.error('Socket连接失败:', err);
    });
  </script>
</html>

验证步骤 #

1. 执行npm install安装依赖
2. 启动服务器：node server.js
3. 访问http://localhost:3000，查看服务器控制台是否输出Socket connected!及对应socket ID

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