如何解决npm workspaces monorepo中前后端TypeScript代码的类型冲突？

在npm Workspaces monorepo中同时维护客户端和服务端包时，由于依赖提升机制，服务端的@types/node会被安装到根node_modules，导致客户端TypeScript同时加载DOM和Node的全局类型，出现类似setTimeout返回类型不匹配的错误（浏览器中返回number，Node中返回Timeout）。

以下是几种从架构层面解决问题的方案：

方案一：在客户端tsconfig中明确禁用自动加载全局类型包 #

在客户端的tsconfig.json的compilerOptions中添加"types": []，让TypeScript只加载你指定的lib类型（比如ES2022、DOM），不再自动加载根目录下的所有@types包：

{
  "compilerOptions": {
    "lib": ["ES2022", "DOM"],
    "types": [],
    // 其他配置...
  }
}

这个方案最简洁，不需要改动依赖结构，直接通过TypeScript配置隔离冲突类型。

方案二：阻止服务端@types/node的依赖提升 #

如果需要更严格的依赖隔离，可以在服务端包的package.json中配置installConfig，禁止@types/node被提升到根目录：

{
  "devDependencies": {
    "@types/node": "^20.0.0"
  },
  "installConfig": {
    "hoist": false
  }
}

执行npm install后，@types/node会被安装在服务端包的本地node_modules中，客户端不会读取到该类型定义，从根源避免冲突。缺点是可能会增加依赖重复安装的体积。

临时兼容方案（不推荐作为长期架构） #

如果只是临时解决，可以在客户端代码中使用类型断言，但这只是绕过问题而非从架构上解决：

const timeout: number = setTimeout(() => {}, 1000) as unknown as number;

验证方案有效性 #

修改配置后，重新执行tsc编译客户端代码，setTimeout的类型会恢复为浏览器环境的number，冲突错误即可消除。

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