在Moleculer中测试Socket.IO时出现404 Not Found错误排查

问题背景 #

我创建了基于Moleculer的Socket.IO演示服务，使用moleculer-web和moleculer-io mixins，客户端连接时出现404 Not Found错误，且localhost:3000下仅存在/list-aliases接口，无/socket.io路径。

服务端代码（services/socketiodemo.service.js） #

"use strict";

const ApiGateway = require("moleculer-web");
const SocketIOService = require("moleculer-io");

module.exports = {
  name: "socketiodemo",
  mixins: [ApiGateway, SocketIOService],
  settings: {
    io: {
      path: "/socket.io",
      cors: true 
    }
  },
  events: {
    "socket.connected" (ctx) {
      console.log(`Socket ${ctx.socket.id} connected to ${ctx.nodeID}.` );
      ctx.emit("hello", "Connected successfully!");
    },
    "socket.disconnected" (ctx) {
      console.log(`Socket ${ctx.socket.id} disconnected from ${ctx.nodeID}`)
    },
    "socket.message" (ctx, data) {
      console.log(`Socket ${ctx.socket.id} sent message: ${data}`);
      ctx.broadcast("message", data);
    },
  },
}

客户端HTML代码 #

<!DOCTYPE html>
<html>
    <head>
        <title>Socket.IO Client Example</title>
        <script src="https://cdn.socket.io/socket.io-3.0.3.min.js"></script>
        <script>
            const socket = io("http://localhost:3000", {
                path: "/socket.io",
            });
            socket.on("message", function (message) {
                console.log("Incoming message: ", message);
            });
            socket.on("hello", function (message) {
                console.log("Connected to server: ", message);
            });
            function sendMessage() {
                const input = document.getElementById("message-input");
                const message = input.value;
                socket.emit("message", message);
                input.value = "";
            }
        </script>
    </head>
    <body>
        <div>
            <input
                type="text"
                id="message-input"
                placeholder="Enter message..."
            />
            <button onclick="sendMessage()">Send</button>
        </div>
    </body>
</html>

问题解答 #

1. 为何会出现404错误？ #

404错误的核心原因是服务端未正确注册/socket.io路径，客户端请求该路径时找不到对应的处理逻辑，因此返回404。具体触发点在于：

• 同时使用ApiGateway和SocketIOService mixin时，SocketIOService未成功将Socket.IO端点挂载到ApiGateway的HTTP服务器上；
• 可能存在mixin初始化顺序问题：SocketIOService依赖ApiGateway创建的HTTP服务器实例，若初始化流程异常，会导致Socket.IO无法完成挂载；
• ApiGateway默认仅开放/list-aliases接口，若未配置路由放行/socket.io路径，请求会被ApiGateway拦截。

2. 为何没有/socket.io路径，该问题是否与404错误相关？ #

没有/socket.io路径和404错误直接相关——正是因为服务端未注册这个路径，客户端请求时才会返回404。导致路径未注册的具体原因包括：

• mixin配置关联不足：SocketIOService需要与ApiGateway的HTTP服务器实例绑定，部分版本的moleculer-io需要显式配置才能完成关联；
• ApiGateway路由限制：默认路由仅开放/list-aliases，未允许/socket.io路径的请求通过，导致Socket.IO端点无法对外暴露；
• moleculer-io配置未生效：settings.io中的path配置可能未被正确读取，导致Socket.IO未挂载到指定路径。

修复建议 #

1. 添加ApiGateway路由配置：
   修改服务端settings，新增路由放行/socket.io路径：

   settings: {
     // ApiGateway路由配置
     routes: [
       {
         path: "/socket.io",
         methods: ["GET", "POST", "OPTIONS"],
         authentication: false,
         authorization: false,
       }
     ],
     // Socket.IO配置
     io: {
       path: "/socket.io",
       cors: true 
     }
   },
   

2. 验证依赖版本兼容性：
   确保moleculer-io与moleculer-web版本匹配，避免因版本不兼容导致挂载失败；
3. 添加初始化日志：
   在服务启动时添加日志，确认Socket.IO实例是否成功挂载到指定路径。

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