生产环境pm2集群模式下tsconfig-paths无法正常工作的问题

集群模式启动失败原因 #

pm2集群模式下，主进程fork子进程时，可能未正确继承项目根目录的模块查找环境变量，导致子进程无法找到node_modules中的ts-node模块。更关键的是：生产环境完全没必要用ts-node处理已编译好的JS文件——tsc已经将TypeScript转译为可直接执行的JavaScript，再用ts-node注册器属于冗余操作，反而增加了启动风险。

生产环境路径映射优化方案 #

核心思路：在编译阶段就将路径别名转换为相对路径，避免依赖运行时的tsconfig-paths工具，让编译后的代码可直接被Node.js执行。

步骤1：安装编译阶段路径转换工具 #

安装tsc-alias（用于在ts编译后替换路径别名）：

npm install --save-dev tsc-alias

步骤2：完善tsconfig.json的路径配置 #

在compilerOptions中添加paths字段，明确别名映射：

{
    "ts-node": {
        "files": true
    },
    "include": ["src/**/*"],
    "compilerOptions": {
        "target": "es6",
        "module": "commonjs",
        "moduleResolution": "node",
        "baseUrl": "./src",
        "paths": {
            "TestModules": ["./TestModules"]
        },
        "sourceMap": true,
        "outDir": "./dist/src",
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "strict": true,
        "skipLibCheck": true
    }
}

步骤3：优化package.json脚本 #

修改脚本，让生产环境直接运行编译后的JS文件，开发环境保留ts-node快速启动：

{
  "name": "nodejs",
  "version": "1.0.0",
  "description": "",
  "main": "dist/src/app.js",
  "scripts": {
        "start": "if [ \"${NODE_ENV}\" = production ]; then npm run start:prod; else npm run start:dev;fi",
        "start:prod": "node dist/src/app.js",
        "start:dev": "ts-node -r tsconfig-paths/register src/app.ts",
        "build": "npm run clean && tsc && tsc-alias && npm run copy-files",
        "clean": "rm -rf ./dist",
        "copy-files": "cp ./package.json ./dist; cp ./tsconfig.json ./dist;"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",  
    "devDependencies": {
        "typescript": "^4.5.5",
        "tsc-alias": "^1.8.8"
    },
    "dependencies": {
        "ts-node": "^10.7.0",
        "tsconfig-paths": "^3.14.1"
    }
}

步骤4：修改pm2集群配置 #

直接指向编译后的JS文件，移除不必要的interpreter_args：

{
  "apps": [{
    "name": "test",
    "script": "./dist/src/app.js",
    "instances": 2,
    "exec_mode": "cluster",
    "env": {
      "NODE_ENV": "production"
    },
    "cwd": "./" // 确保工作目录为项目根目录，避免路径歧义
  }]
}

验证效果 #

执行npm run build后，查看dist/src/app.js，原代码中的import { ModuleA, ModuleB } from 'TestModules';会被转换为相对路径的require语句，无需依赖任何运行时路径工具即可直接执行。此时用pm2启动集群模式，不会再出现模块找不到的问题。

内容的提问来源于stack exchange，提问作者Nathanaël Spriet