TypeScript提供的路径别名（paths）功能让我们能用简洁的标识符代替又长又丑的相对路径，比如把../../utils/format写成@utils/format。但很多开发者都踩过同一个坑：启动开发服务器或跑单元测试时一切正常，可一旦用node dist/server.js运行编译产物，控制台立刻抛出 Cannot find module '@utils/format' 之类的错误。要解决这个问题，得先搞清楚别名失效的根本原因。
TypeScript路径别名为何在Node.js中失效？
tsc 编译器在将 TS 源码转换为 JS 时，核心工作只有两项：抹掉类型注解并进行语法降级。对于 import 语句中的模块说明符，比如 import { format } from '@utils/format'，tsc 几乎原封不动地保留下来，并不会去查找 tsconfig.json 中的 paths 配置并把 @utils/format 替换成真正的文件路径。Node.js 运行时加载模块时依赖其自身的解析算法，它不认识 @utils 这种虚拟前缀，只会尝试在 node_modules 中寻找名为 @utils 的包，结果自然是找不到。
有些人会误以为 ts-node 能正常运行就是 tsc 把路径处理好了，其实 ts-node 内部集成了一个解析器，在加载模块时会读取 tsconfig 的 paths 并实时进行映射。同样地，Jest 或 Webpack 也能通过配置来理解别名，但这些都属于特定运行环境提供的增强，而不是 tsc 自带的。因此，当你剥离掉这些工具，直接用最纯粹的 Node 进程执行编译后的代码时，别名就暴露了没有做任何转换的事实。
更让人头疼的是，这种失效往往还表现得特别隐晦：IDE 可以正常跳转、编译零警告，甚至运行部分脚本（如用 ts-node 执行的 seed 脚本）也毫无问题，唯独在生产环境下用 node 启动时崩掉。清楚这一成因之后，我们就可以有针对性地选择解决方案了。
方案一：运行时动态解析——tsconfig-paths
最轻量的解法就是沿用 ts-node 的思路，在运行时注入一个模块钩子，让它按照 tsconfig 中的 paths 信息自动将别名转换为实际路径。tsconfig-paths 这个库就是专门做这件事的。安装后，你可以在启动 Node 应用时通过 -r 参数预加载它的注册脚本：
node -r tsconfig-paths/register dist/server.js
这个注册脚本会劫持 Node 的模块加载流程，当遇到无法解析的说明符时，就根据项目根目录下的 tsconfig.json 中的 baseUrl 和 paths 配置计算出正确的文件位置。它的优点是不需要修改任何源码，也不需要变更构建流程，特别适合已经打包好但不能修改编译产物或者在 CI 环境快速验证的场景。同时，对于同时使用 ts-node 和 tsc 的项目，这个库可以保证本地开发和服务端运行使用同一套解析规则，减少环境差异导致的隐性问题。
不过，这种方式会略微增加启动阶段的性能开销，因为每次 require 或 import 都要走一层额外的映射逻辑。此外，如果你把应用打包成单文件（比如用 pkg 或 ncc），或是部署在 Severless 环境，这种运行时劫持可能并不兼容。此时更推荐编译时转换的方案。
方案二：编译时路径转换——tsc-alias 与 ttypescript
既然问题出在 tsc 没有改写路径，那就在编译完成后额外执行一步专门用于替换别名的工具。tsc-alias 就是这类工具的典型代表。用法也很简单：先正常执行 tsc 生成 JS 文件，然后再运行 tsc-alias，它会遍历输出目录中的所有 .js 和 .d.ts 文件，将 paths 别名重写为可解析的相对路径。你可以在 package.json 的构建脚本中串联这两个命令：
"scripts": {
"build": "tsc && tsc-alias"
}
tsc-alias 支持多种配置，比如通过 CLI 参数指定 tsconfig 路径、输出目录以及是否保留 .d.ts 中的别名等。与运行时方案相比，它的最大优点就是生成后的代码已经完全是标准 Node.js 可以理解的相对路径，无需任何额外的运行时依赖或启动参数，性能毫无影响，安全性也更高。
另一个更彻底的编译时方案是使用 ttypescript（或者 ts-patch）这类能 Hook tsc 编译过程的工具，配合如 @zerollup/ts-transform-paths 等 Transformer 插件，在编译期间实时转换别名。这种方式的优势是所有路径重写都在一次编译中完成，省去了额外的后处理步骤。但代价是需要使用包装后的编译器，对一些特定的编译特性可能存在兼容风险，配置也更为复杂，一般在大型工程或 Monorepo 中较为常见。
无论选择 tsc-alias 还是 Transformer，编译时方案都非常适合生产环境部署，因为你交付的是完全自包含的产物，不需要运行环境做出任何妥协。唯一的不足是，如果开发过程中需要快速重启服务，你可能需要引入类似 nodemon 的文件监听并重新构建，但这在 CI/CD 流程中通常不是问题。
方案三：借助模块别名工具——module-alias
如果你希望运行时解析方案更加轻量，不想在命令行带上长长的参数，也可以使用 module-alias 直接修改 Node 的模块查找行为。这个库允许你在应用的入口文件顶部进行声明，或在 package.json 中通过 _moduleAliases 字段集中配置别名映射。
安装后，你可以在主入口文件开头添加：
require('module-alias/register');
// 或者手动注册
require('module-alias').addAliases({
'@utils': __dirname + '/dist/utils',
'@models': __dirname + '/dist/models'
});
然后直接 node app.js 即可。相较于 tsconfig-paths，module-alias 不依赖于 tsconfig 文件，别名映射完全由你自己掌控，灵活性更高。它的实现原理基于对 Module._resolveFilename 的覆写，所以你还可以将别名指向任意目录，甚至是外部的包。
但这也带来了一个明显的问题：别名配置与 tsconfig 中的 paths 割裂，你需要手动维护两份映射关系，项目变大后很容易出现配置不一致。此外，直接修改 Node 内部方法也可能与某些库产生冲突。因此，除非项目规模较小或者确实需要独立于 TypeScript 配置的别名体系，否则推荐优先使用前两种方案。
总结与选型建议
以上三种方案没有绝对的优劣，关键在于你的具体场景。如果你追求零配置、快速验证，且可以接受启动命令稍长，tsconfig-paths 是最稳妥的选择；如果你的应用需要部署到纯净的 Node 生产环境，并且希望编译产物干净无依赖，那 tsc-alias 这类编译时工具无疑是最佳实践；如果你的别名不只依赖 tsconfig，还需要处理一些运行时动态路径或者希望更灵活地控制映射，module-alias 会是很好的补充。
在实际工作中，很多项目会混合使用：本地开发用 ts-node 配合 tsconfig-paths，保证即时重启的便利；生产构建时通过 tsc-alias 产出标准、高效的 JS 文件，再配套简单的启动脚本。如此一来，你就既能享受路径别名的开发体验，又能避开 Node.js 运行时的模块解析陷阱了。
TypeScript路径别名Node.js运行时tsconfig-paths修改时间：2026-08-12 12:37:16