TypeScript导入Node.js cluster模块isMaster不存在报错如何解决

报错根因 #

• TS2339报错：Node.js v16+ 已废弃cluster.isMaster API，替换为cluster.isPrimary，官方类型定义已移除isMaster属性，调用不存在的属性触发类型校验错误
• 默认导入返回undefined：cluster属于CommonJS规范模块，无默认导出项，TS未开启兼容配置时，默认导入语法无法正确加载模块内容

操作步骤 #

前置检查 #

确保项目已安装Node.js类型依赖，未安装时执行以下命令：
npm install @types/node --save-dev

方案一：命名空间导入（无需修改TS配置，推荐） #

直接使用命名空间导入语法，调用官方推荐的新APIisPrimary即可：

import * as cluster from 'cluster';
import * as os from 'os';

if (cluster.isPrimary) {
  // 主进程逻辑示例：按CPU核心数启动工作进程
  const cpuCount = os.cpus().length;
  for (let i = 0; i < cpuCount; i++) {
    cluster.fork();
  }
} else {
  // 工作进程业务逻辑
}

方案二：默认导入（需修改TS配置） #

如果需要使用默认导入语法，先修改tsconfig.json中的编译配置：

{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

配置生效后即可使用默认导入：

import cluster from 'cluster';

if (cluster.isPrimary) {
  // 主进程逻辑
}

旧版本兼容方案 #

如果必须适配v16以下的Node.js版本，需要继续使用isMaster，可通过类型断言绕过类型校验：

import * as cluster from 'cluster';

if ((cluster as unknown as { isMaster: boolean }).isMaster) {
  // 旧版本兼容逻辑
}

注意：isMaster已被官方标记为废弃属性，无特殊兼容需求优先使用isPrimary，避免后续Node.js版本升级出现运行时错误。

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