Node.js cluster fork场景下动态import导致服务无法启动

云上老周

2026-9-2

问题根因

三个核心问题导致server模块逻辑不执行：

异步函数无异常捕获：runWorkerProcess是async函数，调用时未做catch处理。你写的worker启动pid日志是在await import('./server')之前的同步逻辑，所以能正常输出；一旦动态import过程中出现路径错误、模块初始化报错、依赖冲突，会直接触发Promise reject，未捕获的rejection在Node.js默认配置下不会打印完整错误栈，worker进程静默退出，表现为server内逻辑完全不执行。
主进程提前加载业务依赖：主入口顶层写了大量和server.ts重复的业务依赖引入（express、cors、routes、socket、db等）。ESM的顶层import会在所有分支逻辑执行前完成模块解析和顶层代码执行，这些依赖如果在主进程阶段就完成了初始化，cluster.fork()出来的worker会直接拷贝主进程的模块缓存，动态import server时，ESM检测到依赖模块已存在缓存，不会重新执行server内的初始化逻辑，甚至会因为模块初始化上下文属于主进程触发隐性冲突。
TypeScript环境路径解析问题：如果是TS运行环境（ts-node/tsx）或者TS编译为JS后运行，动态import路径省略.js后缀时，部分moduleResolution配置下会出现模块找不到的错误，同样因为无异常捕获看不到报错。

修复步骤

按顺序操作即可解决：

先给worker启动逻辑加全局异常捕获，把隐藏的错误打出来，这步是优先级最高的调试手段。修改cluster分支判断代码：

cluster.isPrimary ? runPrimaryProcess() : runWorkerProcess().catch(err => {
  logError('worker', `Worker ${process.pid} 启动失败: ${err.stack || err.message}`)
  process.exit(1)
})

清理主入口所有非必要的顶层import，主进程只负责进程调度，不需要加载任何业务相关模块。主进程保留的依赖仅限os、cluster、dotenv、日志工具，所有express、路由、数据库、socket相关的引入全部删掉，避免主进程提前执行模块初始化逻辑，污染fork时的内存状态。
清理后的主入口核心代码参考：

import os from 'os'
import cluster from 'cluster'
import * as dotenv from 'dotenv'
dotenv.config()
import { logSuccess, logError } from './utils/log'

const runPrimaryProcess = () => {
    const processesCount = os.cpus().length
    logSuccess('server', `Primary ${process.pid} is running`)
    logSuccess('server', `Forking Server with ${processesCount} processes \n`)

    for (let index = 0; index < processesCount; index++) cluster.fork()

    cluster.on('exit', (worker, code, _signal) => {
        if (code !== 0 && !worker.exitedAfterDisconnect) {
            logError('cluster', `Worker ${worker.process.pid} died... scheduling another one!`)
            cluster.fork()
        }
    })
}

const runWorkerProcess = async () => {
    logSuccess('worker', `Worker ${process.pid} started`)
    // TS编译为JS运行时路径改为'./server.js'，tsx/ts-node运行可保留'./server'
    await import('./server')
}

cluster.isPrimary ? runPrimaryProcess() : runWorkerProcess().catch(err => {
    logError('worker', `启动异常: ${err.stack}`)
    process.exit(1)
})

适配运行环境的模块解析规则：
- 如果是TS编译为JS后部署运行，动态import路径必须写全后缀为./server.js，不能省略
- 如果是开发环境用tsx/ts-node直接跑TS代码，检查tsconfig.json中compilerOptions.module配置为NodeNext或ES2022，打开ESM模块支持

注意：所有端口监听、数据库连接、socket初始化逻辑必须全部放在worker进程的执行链路中，绝对不能在主进程顶层引入对应模块时触发，否则会出现端口占用、数据库连接复用异常等问题。

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