为多类导出的CommonJS模块编写自定义TS类型不被识别及构造报错怎么办

原类型文件的核心错误 #

• 重复使用export =语法：CommonJS规则下一个模块作用域仅支持一个export =指令，连续声明两个该导出指令时，后一个值会覆盖前一个，最终导出逻辑完全偏离“同时导出两个类”的目标。
• 声明与导出顺序混乱：将export =导出语句写在类定义之前，TypeScript解析时无法找到后续声明的类引用，会触发未定义类型的解析错误。
• 多语法混用冲突：同时使用export =（CommonJS风格）和export default（ES模块风格），二者导出结构不兼容，会导致TS对模块导出结构的解析完全错位。
• 无效前置导入：在declare module "socket.io-mock"块内加入import "socket.io-mock"，会触发递归模块解析逻辑，TS和VSCode会直接忽略该自定义类型定义，回退查找node_modules下的原生模块（即不存在类型的无声明状态）。

修正后的标准类型文件 #

按照socket.io-mock的实际CommonJS源码结构（将SocketMock、SocketClient两个类作为属性挂在module.exports上），调整后的类型声明如下：

// FILE: types/socket.io-mock.d.ts
declare module "socket.io-mock" {
  // 先定义所有类的类型结构
  declare class Emitter {
    constructor(obj?: Partial<Emitter>): Emitter
    _callbacks: { [event: string]: Function[] }
    on: (event: string, callback: (payload?: unknown) => void) => Emitter
    off: (event?: string, fn?: Function) => Emitter
  }

  declare class SocketClient extends Emitter {
    constructor(socketMock: SocketMock): SocketClient
    connected: boolean
    disconnected: boolean
    emit: (eventKey: string, payload?: unknown, ack?: () => void) => void
    disconnect: () => SocketClient
  }

  declare class SocketMock extends Emitter {
    constructor(): SocketMock
    joinedRooms: string[]
    emit: (eventKey: string, payload?: unknown) => void
    // 补充源码中存在的客户端关联属性
    socketClient: SocketClient
  }

  // 匹配实际的CommonJS导出结构：导出对象包含两个类的引用
  const moduleExports: {
    SocketMock: typeof SocketMock
    SocketClient: typeof SocketClient
  }
  export = moduleExports
}

TS与VSCode识别配置说明 #

• 确保tsconfig.json中compilerOptions.typeRoots配置包含自定义d.ts的存放路径，例如将类型文件放在项目根目录的types文件夹下时，配置需包含"./types"路径项。
• 确认开启esModuleInterop配置，该配置会自动适配CommonJS的export =导出逻辑，允许你使用ES模块的具名导入语法import { SocketMock, SocketClient } from "socket.io-mock"，不需要额外的导入适配代码。

运行时报错的本质原因 #

之前触发的TypeError: _socket2.SocketMock is not a constructor，是错误导出逻辑导致的连锁问题：原类型声明的导出结构错位，TS编译时将模块导出值解析为单个类引用，而非实际挂了两个类的导出对象，编译后取到的SocketMock根本不是构造器，自然抛出类型错误。
尝试去掉declare直接在d.ts中写export class的方式之所以会运行报错，是因为.d.ts文件仅承担类型定义职责，不能包含实际运行逻辑，一旦写入真实导出的类实现，TS会将该文件当作实际模块实现参与编译，和node_modules下的真实模块代码产生冲突，运行时自然找不到对应的构造器。

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