本地环境使用Socket.io出现404错误，如何解决？

问题重现 #

本地开发Socket.io时，客户端请求https://localhost:4000/socket.io/返回404，相关代码及错误信息如下：

客户端代码 #

const socket = io.connect('https://localhost:4000/');
socket.emit('trim-movie/go', data);
socket.on('trim-movie-response', trimResponse);

服务端代码 #

const server = app.listen(port, () => console.log('server is online...'));
const io = socket(server);
io.on("connection", (socket) => {
    socket.on('trim-movie/go', (data) => trimMovie(data, socket));
});

错误提示：

socket.io.js?v=1:1415 GET https://localhost:4000/socket.io/?EIO=4&transport=polling&t=OI2OmiX 404 (Not Found)

排查与解决步骤 #

• 统一客户端与服务端协议
  客户端用了https协议，但本地开发若无有效SSL证书，服务端实际运行在http协议下。要么将客户端连接地址改为http://localhost:4000/，要么为本地服务配置合法SSL证书。

• 确保Socket.io版本完全匹配
  客户端与服务端的Socket.io版本必须一致（比如都使用4.x系列），版本不兼容会导致路由匹配失败。执行命令统一版本：

  # 服务端安装指定版本
  npm install socket.io@4.7.2
  # 客户端同步引入对应版本的脚本（本地文件或CDN）
  

• 排查框架中间件冲突
  若服务端基于Express/Koa等框架，检查是否有中间件拦截所有请求（如自定义路由、静态资源中间件），需确保/socket.io/路径不被拦截。比如Express中可调整中间件顺序，让Socket.io的路由优先处理。

• 验证端口一致性
  确认服务端监听的port变量值为4000，或修改客户端连接地址为服务端实际使用的端口号。

• 修正Socket.io初始化方式
  确保服务端正确传入HTTP服务器实例。以Express为例，新版本Socket.io推荐如下初始化方式：

  const express = require('express');
  const http = require('http');
  const { Server } = require('socket.io');
  
  const app = express();
  const server = http.createServer(app);
  const io = new Server(server);
  
  io.on('connection', (socket) => {
    socket.on('trim-movie/go', (data) => trimMovie(data, socket));
  });
  
  server.listen(4000, () => {
    console.log('server is online...');
  });
  

  旧版本写法require('socket.io')(server)虽仍可用，但使用Server类初始化能避免潜在的路由注册错误。

• 清除浏览器缓存
  浏览器缓存的旧Socket.io客户端脚本可能引发兼容性问题，打开开发者工具勾选「禁用缓存」后刷新页面重试。

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