Monorepo中TypeScript声明文件不符合预期问题

核心原因 #

TypeScript的全局模块声明合并机制导致了这个问题。你在项目a和项目b中都直接使用declare module "node:events"重写EventEmitter类，这属于全局模块增强操作。在Monorepo环境下，TypeScript会自动合并所有packages目录下的同模块声明，所以项目b的类型检查环境中同时包含了两个项目对EventEmitter的修改，最终出现交叉类型污染。

解决方案 #

方案1：实现独立子类（推荐） #

避免全局修改node:events模块，每个项目创建自己的Emitter子类，继承原生EventEmitter并附加专属类型：

项目a示例：

// src/ChatBotEmitter.ts
import { EventEmitter } from 'node:events';
import type { ChatBotEvents } from './types';

export class ChatBotEmitter extends EventEmitter {
  on<K extends keyof ChatBotEvents>(event: K, listener: (...args: ChatBotEvents[K]) => void): this;
  on<S extends string | symbol>(event: Exclude<S, keyof ChatBotEvents>, listener: (...args: any[]) => void): this;
  on(event: string | symbol, listener: (...args: any[]) => void): this {
    return super.on(event, listener);
  }

  emit<K extends keyof ChatBotEvents>(event: K, ...args: ChatBotEvents[K]): boolean;
  emit<S extends string | symbol>(event: Exclude<S, keyof ChatBotEvents>, ...args: any[]): boolean;
  emit(event: string | symbol, ...args: any[]): boolean {
    return super.emit(event, ...args);
  }

  // 同理实现off、once、removeAllListeners方法
}

项目b示例：

// src/PubSubEmitter.ts
import { EventEmitter } from 'node:events';
import type { PubSubEvents } from './types';

export class PubSubEmitter extends EventEmitter {
  on<K extends keyof PubSubEvents>(event: K, listener: (...args: PubSubEvents[K]) => void): this;
  on<S extends string | symbol>(event: Exclude<S, keyof PubSubEvents>, listener: (...args: any[]) => void): this;
  on(event: string | symbol, listener: (...args: any[]) => void): this {
    return super.on(event, listener);
  }

  // 同理实现其他方法
}

这种方式让两个项目的Emitter类型完全独立，从根源避免类型污染。

方案2：通过tsconfig隔离类型环境 #

在每个项目的tsconfig.json中严格控制类型文件的范围，确保项目b不会加载项目a的声明文件：

// 项目b/tsconfig.json
{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"], // 仅加载自身类型目录
    // 其他编译配置
  },
  "include": ["./src/**/*"],
  "exclude": ["../packages/a/**/*"] // 明确排除项目a的所有文件
}

同时确保两个项目的package.json中没有互相依赖（若存在依赖，TypeScript会自动引入依赖项目的类型定义）。

方案3：优化全局模块扩展（不推荐） #

如果必须使用全局模块增强，不要重写整个EventEmitter类，而是仅扩展需要的方法，并通过类型守卫区分不同项目的Emitter：

// 项目a/index.d.ts
declare module "node:events" {
  interface EventEmitter {
    on<K extends keyof ChatBotEvents>(event: K, listener: (...args: ChatBotEvents[K]) => void): this;
    emit<K extends keyof ChatBotEvents>(event: K, ...args: ChatBotEvents[K]): boolean;
  }
}

这种方式需要在代码中额外添加类型断言或守卫，容易引发新的类型问题，仅作为临时兼容方案。

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