使用compilerOptions的paths配置在Node环境中失效求助

问题说明 #

这个问题和某StackOverflow问题类似，但Node环境下并非重复问题。项目结构如下：

$ tree .                                        
.
├── src
│   ├── main.ts
│   └── utils
│       └── myUtils.ts
└── tsconfig.json

尝试用@前缀导入模块，src/main.ts代码：

import { myLovelyUtilsFunction } from "@folder1/myUtils"
const y = myLovelyUtilsFunction();
console.log(`>>> ${y}`);

tsconfig.json配置：

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": { "@folder1/*": ["utils/*"] },
    "module": "commonjs"
  }
}

代码编译无报错，但Node运行时出现以下错误：

$ npx tsc -p tsconfig.json # <--- 无错误
$ node src/main.js
node:internal/modules/cjs/loader:1078
  throw err;
  ^

Error: Cannot find module '@folder1/myUtils'
Require stack:
< ... 省略 ... > 

问题根源 #

TypeScript的paths别名仅作用于TS编译器，编译后的JS文件里仍保留@folder1/myUtils这类别名路径，但Node.js本身不识别该别名，因此会抛出模块找不到的错误。

解决方法 #

方法1：用tspath转换编译后的路径 #

• 安装依赖：

npm install -g tspath

• 编译TS代码后执行路径转换：

npx tsc -p tsconfig.json && tspath

• 运行JS文件：

node src/main.js

方法2：用module-alias在运行时解析别名 #

• 安装依赖：

npm install module-alias --save

• 修改tsconfig.json，添加输出目录配置：

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": { "@folder1/*": ["utils/*"] },
    "module": "commonjs",
    "outDir": "./dist"
  }
}

• 在项目根目录的package.json中添加别名映射：

{
  "_moduleAliases": {
    "@folder1": "./dist/utils"
  }
}

• 在src/main.ts最顶部引入module-alias：

import 'module-alias/register';

• 编译并运行：

npx tsc -p tsconfig.json && node dist/main.js

方法3：开发环境用ts-node直接运行TS #

如果是开发阶段，不想每次编译后处理路径，可搭配tsconfig-paths：

• 安装依赖：

npm install ts-node tsconfig-paths --save-dev

• 在package.json的scripts中添加命令：

{
  "scripts": {
    "dev": "ts-node -r tsconfig-paths/register src/main.ts"
  }
}

• 执行开发命令：

npm run dev

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