如何解决TypeScript构建过程中的路径别名解析问题？

核心原因 #

TypeScript的tsconfig.json中配置的paths仅用于类型检查和编辑器代码提示，TypeScript编译器（tsc）本身不会将代码中的路径别名替换为实际相对路径。编译后的JS文件里依然保留@/xxx这类别名，而Node.js无法识别这些自定义别名，因此会抛出模块找不到的错误。

解决方案 #

方案1：使用tsc-alias替换编译后的路径别名

这是最直接的解决方案，tsc-alias会在tsc编译完成后，自动将dist目录下所有JS文件中的别名替换为实际相对路径。

1. 安装开发依赖：

npm install tsc-alias --save-dev

2. 修改package.json中的构建脚本：

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

3. 执行构建命令：

npm run build

编译完成后，dist目录下的代码会自动把@/utils/helper替换成./utils/helper这类实际路径，Node.js就能正常解析模块了。

方案2：使用module-alias实现运行时别名解析

如果不想修改编译后的文件，可以通过module-alias在Node.js运行时动态解析别名。

1. 安装依赖：

npm install module-alias --save

2. 修改tsconfig.json，启用JSON模块解析：

{
  "compilerOptions": {
    // 原有配置...
    "resolveJsonModule": true
  }
}

3. 在package.json中添加别名映射：

"_moduleAliases": {
  "@": "./dist/src"
}

4. 在项目入口文件（src/index.ts）的最顶部添加注册代码：

import 'module-alias/register';

之后编译并运行代码，Node.js会通过module-alias自动识别@别名对应的实际路径。

方案3：手动配置（不推荐，仅作参考）

如果不想使用第三方工具，可以手动在tsconfig.json中配置baseUrl结合相对路径，但这会失去别名的简洁性，仅适合小型项目。

关于tsconfig-paths的说明 #

你之前尝试的tsconfig-paths主要用于直接运行TS代码（比如用ts-node执行时），而非编译后的JS代码。如果要使用它，正确的运行命令是：

npx ts-node -r tsconfig-paths/register src/index.ts

但对于生产环境的构建产物，还是推荐使用tsc-alias来替换路径，避免依赖运行时的别名解析工具。

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