如何在Node.js中使用TypeScript扩展ws库的WebSocket类型？

我明白你遇到的困扰——尝试给ws库的WebSocket实例添加自定义id属性时，TypeScript一直报错，而且直接扩展模块还会干扰原有类型。别担心，这是因为模块扩展的写法有细节需要注意，下面给你两种可靠的解决方案：

方案一：正确扩展ws模块的WebSocket接口 #

这种方法能全局给WebSocket类型添加id属性，不需要每次都做类型断言，是最推荐的方式。

1. 创建一个专门的类型扩展文件（比如ws-types.d.ts或者ws-extensions.ts），确保文件处于模块环境（也就是里面要有import/export语句，否则TypeScript会把它当成全局声明，无法正确合并已有类型）：

// ws-extensions.ts
import { WebSocket } from "ws";

// 扩展ws模块中的WebSocket接口
declare module "ws" {
  interface WebSocket {
    id: string;
  }
}

2. 在你的WebSocket服务器入口文件中，导入这个扩展文件（不需要导入具体内容，只要确保它被TypeScript加载即可）：

// server.ts
import "./ws-extensions"; // 先加载类型扩展
import { WebSocketServer } from "ws";
import { v4 as uuidv4 } from "uuid";

const wss = new WebSocketServer({ port: 8080 });

wss.on("connection", (socket) => {
  const id = uuidv4();
  socket.id = id; // 现在TypeScript不会报错了！

  socket.on("message", (data) => {
    console.log(`收到来自 ${socket.id} 的消息: ${data}`);
  });
});

为什么之前的写法会出问题？ #

你之前直接写declare module "ws"但没有先导入ws的类型，TypeScript会认为你在重新定义整个ws模块，而不是合并到已有的DefinitelyTyped类型中，这就会导致原有WebSocket的其他类型定义被覆盖或干扰。先导入ws的类型再扩展，TypeScript才会正确合并接口。

方案二：使用类型断言快速解决（适合临时场景） #

如果你不想全局扩展类型，也可以在使用时给socket做类型断言，这种方式更灵活但需要每次手动处理：

import { WebSocketServer, WebSocket } from "ws";
import { v4 as uuidv4 } from "uuid";

const wss = new WebSocketServer({ port: 8080 });

wss.on("connection", (socket) => {
  const id = uuidv4();
  // 断言socket为包含id属性的WebSocket类型
  const typedSocket = socket as WebSocket & { id: string };
  typedSocket.id = id;

  typedSocket.on("message", (data) => {
    console.log(`收到来自 ${typedSocket.id} 的消息: ${data}`);
  });
});

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