Node运行TypeScript项目提示找不到@helpers模块如何解决

• TypeScript 自带编译器tsc不会自动转换tsconfig.json中配置的paths路径别名，编译输出的JS文件会原样保留@helpers/checkArgs这类自定义别名写法，而Node.js 原生不识别这类别名，运行时直接抛出模块找不到错误。
• src/app.ts中import User from 'models/user'属于无前缀绝对路径导入，Node.js 默认只会去node_modules目录下查找名为models的第三方包，不会主动扫描项目源码目录，你之前设置NODE_PATH时路径匹配逻辑不对，自然无法生效。

任选以下一种方案即可解决问题： #

方案1：编译后自动替换别名（适合需要提前编译JS的生产场景） #

1. 安装开发依赖tsc-alias，用来在编译完成后自动替换JS文件中的路径别名：

npm install -D tsc-alias

2. 补全tsconfig.json中的paths配置，把models目录的映射加上，否则models/user的导入无法被TS识别：

{
    "compilerOptions": {
        "experimentalDecorators": true,
        "outDir": "./build",
        "allowJs": false,
        "target": "es6",
        "module": "CommonJS",
        "esModuleInterop": true,
        "moduleResolution": "node",
        "baseUrl": "./src",
        "paths": {
            "@helpers/*": ["helpers/*"],
            "models/*": ["models/*"]
        }
    },
    "include": ["./src/**/*"]
}

3. 修改package.json中的构建和启动脚本，让编译完成后自动执行别名替换：

{
  "scripts": {
    "build": "tsc && tsc-alias",
    "start": "node build/app.js"
  }
}

4. 重新执行npm run build编译后，再启动项目就不会报模块找不到的错误。

方案2：直接用TS运行时启动（适合开发场景，无需提前编译） #

如果不想每次修改代码后都重新编译，可以直接用原生支持TS语法和路径别名的运行时工具：

1. 安装开发依赖tsx：

npm install -D tsx

2. 和方案1一样补全tsconfig.json里的paths配置，加上models/*的映射。
3. 配置启动脚本直接跑TS源码：

{
  "scripts": {
    "dev": "tsx src/app.ts",
    "start": "tsx src/app.ts"
  }
}

执行对应命令即可直接启动项目，不需要额外编译步骤。 #

不推荐的NODE_PATH方案说明 #

如果坚持要用NODE_PATH解决，必须满足两个条件：

• 启动时NODE_PATH要指向编译后的build目录，命令为NODE_PATH=./build node build/app.js（Windows环境需要用cross-env跨平台设置环境变量）
• 所有@helpers/开头的自定义别名导入要全部改成普通目录导入或者相对路径，因为NODE_PATH只能识别真实存在的目录名，无法识别你自定义的@前缀别名。
  这种方式维护成本极高，文件层级较深时相对路径写法非常繁琐，不建议使用。

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