使用nodemon构建应用时TSC无法编译路径别名的问题

问题背景 #

当前使用的tsconfig.json配置：

{
  "compilerOptions": {
    "rootDirs": ["src"],
    "outDir": "./dist",
    "lib": ["ES2015"],
    "target": "ES2015",
    "module": "commonjs",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "baseUrl": "./",
    "types": ["node", "jest"],
    "paths": {
      "@features/*": ["src/features/*"],
      "@api/*": ["src/api/*"],
      "@constants/*": ["src/constants/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "src/**/*.test.ts"]
}

package.json脚本配置：

{
  "scripts": {
    "start:build": "tsc -w",
    "start:run": "nodemon dist/server.js",
    "start": "concurrently npm:start:*"
  },
  "devDependencies": {
    "concurrently": "7.6.0",
    "nodemon": "2.0.20",
    "typescript": "4.9.4"
  }
}

执行npm start时出现以下错误：

[run] Error: Cannot find module '@features/user/user.routes'
[run] Require stack:
[run] - system/dist/api/routes.js
[run] - system/dist/api/app.js
[run] - system/dist/server.js

问题出在src/api/routes.ts的导入语句：

import Router from 'express'
import userRoutes from '@features/user/user.routes';

const router = Router()

router.use('/users', userRoutes)

export default router;

疑问：是否需要添加额外插件？此前版本使用别名无此问题。

核心原因 #

TypeScript的paths别名仅作用于编译阶段的类型检查和模块解析，不会修改编译后JS文件中的导入路径。Node.js运行时无法识别这些自定义别名，因此会抛出模块找不到的错误。

解决方法 #

方案一：编译阶段替换别名（推荐） #

使用tsc-alias工具，在TypeScript编译完成后自动将别名替换为实际相对路径，无需运行时额外处理：

1. 安装开发依赖：

npm install --save-dev tsc-alias

2. 修改package.json的脚本，添加别名监听命令：

"scripts": {
  "start:build": "tsc -w",
  "start:alias": "tsc-alias -w",
  "start:run": "nodemon dist/server.js",
  "start": "concurrently npm:start:*"
}

3. 重新执行npm start，编译后的JS文件中别名会被替换为正确的相对路径，Node.js可正常识别模块。

方案二：运行时注册别名映射 #

使用module-alias在运行时为Node.js注册别名映射：

1. 安装依赖及类型声明：

npm install module-alias
npm install --save-dev @types/module-alias

2. 在package.json中添加别名与编译后路径的映射：

"_moduleAliases": {
  "@features": "./dist/features",
  "@api": "./dist/api",
  "@constants": "./dist/constants"
}

3. 在项目入口文件server.ts的最顶部添加注册代码：

import 'module-alias/register';

4. 重新编译运行，Node.js会通过module-alias解析别名对应的模块。

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