如何在TypeScript中正确解析路径别名？Node.js 18项目遇问题

一、解决运行时模块找不到问题 #

TypeScript的paths仅用于编译时类型校验，不会替换输出代码中的别名路径，导致Node无法识别@tools/*。用tsc-alias处理别名替换：

• 安装依赖：

  npm install -D tsc-alias
  

• 修改package.json添加构建脚本：

  {
    "scripts": {
      "build": "tsc && tsc-alias"
    }
  }
  

• 执行npm run build后，dist目录中的别名会被替换为相对路径，此时运行node ./dist/main.js即可正常执行。

二、理清ESM核心配置逻辑 #

1. 三个核心配置的作用 #

• package.json的type: "module"：告知Node项目采用ESM规范，.js文件默认按ESM解析，仅支持import/export语法。
• tsconfig.json的module: "ESNext"：指定TS编译后的模块格式为ESNext，保留最新ESM语法，适配Node的ESM支持。
• tsconfig.json的moduleResolution: "ESNext"：采用Node原生的ESM模块解析规则（如强制.js后缀、支持package exports），与type: "module"完全匹配。

2. 解决ts-node与chalk的冲突 #

• ts-node适配ESM：安装ts-node后，运行时需添加--esm参数，修改脚本：

  {
    "scripts": {
      "dev:ts": "ts-node --esm src/main.ts"
    }
  }
  

• chalk兼容ESM：chalk v5+本身为ESM模块，无需修改module配置，直接通过import chalk from 'chalk'导入即可；若使用旧版CommonJS chalk，已开启的esModuleInterop: true会自动处理兼容。

三、搭建完整工作流 #

1. 生产构建流程 #

编写带路径别名的TS代码 → 执行npm run build（TS编译+别名替换） → 运行node ./dist/main.js

2. 开发热重载流程 #

方案一：nodemon全量监听

• 安装依赖：

  npm install -D nodemon
  

• 创建nodemon.json：

  {
    "watch": ["src"],
    "ext": "ts",
    "exec": "tsc && tsc-alias && node ./dist/main.js"
  }
  

• 添加脚本：

  {
    "scripts": {
      "dev": "nodemon"
    }
  }
  

方案二：轻量监听（tsc + node watch）

• 安装跨平台并行工具concurrently：

  npm install -D concurrently
  

• 添加脚本：

  {
    "scripts": {
      "dev": "concurrently \"tsc -w\" \"tsc-alias -w\" \"node --watch ./dist/main.js\""
    }
  }
  

该方案通过TS自动编译、别名实时替换、Node自动重启实现热重载，性能更优。

内容的提问来源于stack exchange，提问作者Islam Y-