Node.js Typescript配置baseUrl后运行无法解析根路径导入如何解决

问题原因 #

TypeScript 编译器和 VS Code 可以识别 tsconfig.json 中的 baseUrl 配置完成路径解析，但 Node.js 运行时本身不支持 TS 的路径映射规则，所以直接运行代码时会找不到对应模块。

修复步骤 #

步骤1：完善 tsconfig.json 路径映射配置 #

在你现有的 compilerOptions 中新增 paths 配置，明确根路径别名的映射规则：

{
  "compilerOptions": {
    // 保留你原有所有配置不变
    "baseUrl": ".",
    "paths": {
      "src/*": ["./src/*"]
    }
  }
}

步骤2：解决开发环境运行问题（nodemon 直接运行 TS 文件） #

使用 tsconfig-paths 工具让 Node 运行时识别 TS 的路径映射：

• 安装开发依赖
  npm install --save-dev ts-node tsconfig-paths
• 修改启动命令
  将原启动命令替换为：
  nodemon --exec "node -r tsconfig-paths/register -r ts-node/register ./src/app.ts"
  配置后运行启动命令即可正常识别 src/xxx 格式的导入路径。

步骤3：解决生产环境编译后运行问题 #

如果需要编译为 JS 后部署运行，使用 tsc-alias 在编译阶段自动将绝对路径替换为相对路径：

• 安装开发依赖
  npm install --save-dev tsc-alias
• 修改 package.json 中的编译命令

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

执行 npm run build 后编译出的 build 目录下的 JS 文件已经自动替换为正确的相对路径，直接执行 node build/app.js 即可正常运行。

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