Node.js + TypeScript路径别名配置失败，求解决方法

问题本质 #

• TypeScript的paths只是编译期别名，编译后的JS文件里仍保留@util/logger这类自定义别名，但Node.js的ESM模块系统并不识别它们。
• ESM强制要求导入必须使用完整文件扩展名（比如.js），这也是直接用./util/logger会报错、加上.js就能正常运行的核心原因。

两种靠谱解决方法 #

方法一：用tsc-alias替换编译后的别名 #

直接在编译完成后，将TS里的别名转换为Node能识别的带扩展名相对路径：

1. 安装依赖：

npm i -D tsc-alias

2. 修改package.json的脚本命令：

{
  "scripts": {
    "start": "nodemon",
    "build": "tsc && tsc-alias"
  }
}

3. 更新nodemon.json的执行逻辑：

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

编译完成后，dist目录下的JS文件会自动把import logger from '@util/logger'替换为import logger from './util/logger.js'，Node即可正常加载模块。

方法二：用ESM加载器在运行时解析别名 #

如果不想修改编译后的文件，可以通过加载器在Node运行时处理别名和扩展名问题：

1. 安装依赖：

npm i -D @esbuild-kit/esm-loader

2. 调整tsconfig.json的模块配置，适配ESM解析规则：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "Node16", // 或ESNext
    "moduleResolution": "Node16",
    "rootDir": "./src",
    "baseUrl": "./",
    "paths": {
      "@util/*": ["./src/util/*"]
    },
    "outDir": "./dist",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true
  }
}

3. 修改nodemon的启动命令，指定使用加载器：

{
  "watch": ["src"],
  "ext": "ts",
  "exec": "tsc && node --loader @esbuild-kit/esm-loader dist/index.js"
}

加载器会在Node运行时自动解析自定义别名，同时补全必要的文件扩展名。

关于module-alias失效的说明 #

module-alias是为CommonJS模块设计的工具，在ESM模式下需要额外配置package.json的imports字段，配置复杂度远高于上述两种方法，因此不优先推荐。

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