TypeScript路径别名失效原因及多场景解决方案

前言

近期在TypeScript项目开发中遇到诸多挑战，特此整理系列文章进行记录。

本文重点梳理TypeScript技术栈中tsc、ts-node及ts-node-dev工具下的路径别名问题。内容涵盖从开发环境到打包构建的完整流程，不仅提供具体的解决方案，还将深入剖析问题产生的根源及其背后的技术演变故事。

开始探索

本文将通过构建一个空项目，由浅入深地演示开发过程中可能遇到的各类问题。读者可以跟随以下步骤进行实操：

首先准备一个空文件夹，引入本文的核心工具ts-node：

npm install ts-node typescript

接着完善项目配置，添加基础的tsconfig.json文件：

{
    "compilerOptions": {
        "outDir": "dist",
        "skipLibCheck": true,
        "strict": true,
        "noEmit": false,
        "module": "CommonJS",
        "baseUrl": ".",
        "paths": {
            "@/*": ["./*"]
        }
    },
    "include": [ "**/*.ts"],
}

随后在package.json中配置ts-node的执行命令，运行该命令后，ts-node将读取并执行index.ts文件：

"scripts": {
    "dev": "ts-node --files ./index.ts"
}

至此，TypeScript开发环境已准备就绪。接下来新建index.ts和utils.ts文件：

utils.ts

export const plus = (a: number, b: number): number => a + b;

index.ts

import { plus } from "./utils";

console.log(plus(1, 1))

上述代码逻辑简单，主要导出一个加法函数并在index.ts中调用打印。执行npm run dev命令后，控制台输出结果如下：

运行正常。现在尝试通过路径别名引入utils模块：

// 把 utils 的引入换成了 @ 路径别名
import { plus } from "@/utils";

再次执行命令：

此时出现报错，提示找不到对应模块。该问题并非ts-node本身缺陷，而是tsc在编译代码时不会将路径别名自动替换为相对路径。因此，当ts-node调用tsc编译后交由Node.js执行时，自然无法解析@/目录。

解决方法很简单，只需安装一个依赖包：

npm install tsconfig-paths

然后在package.json中修改dev命令即可。这里的-r参数是Node.js的命令行选项，具体含义可参考Node.js官方文档：Command-line API | Node.js v16.15.1 Documentation (nodejs.org)：

"dev": "ts-node -r tsconfig-paths/register --files ./index.ts"

再次执行命令，问题已解决：

ts-node-dev使用路径别名

许多开发者在TypeScript项目中习惯使用nodemon监听文件变更，并结合ts-node执行代码。配置方式如下：

"dev": "nodemon -e ts --exec ts-node -r tsconfig-paths/register --files ./index.ts"

实际上，可以使用更简洁的工具ts-node-dev来实现相同功能。安装npm install ts-node-dev后，可将上述命令简化为：

"dev": "tsnd -r tsconfig-paths/register --respawn ./index.ts"

官方文档中明确提到：

So you just combine node-dev and ts-node options (see docs of those packages)

因此，我们可以沿用解决ts-node路径别名问题的相同方法来处理ts-node-dev。

此外，除了配置更简洁外，ts-node-dev还有一个显著优势：它会缓存tsc的编译过程，因此热更新速度远快于nodemon结合ts-node的组合。非常推荐大家试用。

关于路径别名的打包问题

目前仅解决了开发环境的问题。如果路径别名由tsc负责，那么打包阶段同样会面临此问题。接下来我们查看打包时的具体表现。

首先在命令行执行npx tsc，然后检查./dist/index.js目录下的打包结果：

果然，tsc并未将路径别名转换为实际的相对路径。因此，执行node ./dist/index.js时必然报错找不到@/utils。该如何解决这一问题呢？

通常有两种方法。先介绍较为基础的一种：刚才提到的tsconfig-paths/register实际上是Node.js的一个包，这里同样适用。在package.json中添加如下命令（需确保已安装cross-env）：

"scripts": {
    "start": "cross-env TS_NODE_BASEURL=./dist node -r tsconfig-paths/register .\\dist\\index.js"
}

随后执行该命令即可：

简单解释一下，这里通过环境变量TS_NODE_BASEURL覆盖了tsconfig.json中的baseurl配置，使得查找路径别名指向的目录时能定位到正确的（编译后）文件。后续步骤则是正常的node命令引用对应包并执行文件。

然而，这种操作属于“运行时”处理，许多人可能会觉得不够优雅。因此，更简单的方法是在编译代码时就一劳永逸地替换掉路径别名，即下面推荐的方法：

我们可以安装npm install tsc-alias包，专门用于替换路径别名。用法非常简单，紧跟在tsc命令之后即可：

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

现在执行npm run build命令后，可以看到路径别名已被成功替换为相对路径：

当然，这只是较为简单的解决方式之一。读者可根据项目实际情况选择其他方案，例如使用webpack或vite，或者参考文末参考小节中的第一个链接了解更多解决方法。

tsc为什么不会转换路径别名？

文章至此，我们已经解决了TypeScript项目中的路径别名问题。但相信许多人仍有一个困惑：为什么tsc不在编译时直接替换路径别名？

在网上搜索相关问题，大多聚焦于如何解决，而对问题起因的解释却寥寥无几。我在搜索解决方法时，只看到有人感叹此事“说来话长”。

这勾起了我的兴趣。经过详细搜索，我找到了一篇讨论，没想到竟是一篇横跨三年的故事。下面我们就大致了解一下这个问题的前世今生，感兴趣的话也可以直接查阅：Module path maps are not resolved in emitted code · Issue #10866

故事要从2016年9月说起，当时TypeScript还在2.1开发版。有人试用tsconfig中的paths配置时遭遇了相同的困惑，便提交了一个issue询问（事实上，最早的issue记录可追溯到2016年7月，但问题相同，此处不再赘述）。

没过两天，两位TypeScript贡献者先后回复：你是否同时在用webpack等打包工具？另一位则简要介绍这是“有意为之”。paths配置项的本意是为一些第三方包提供特殊的引入渠道，使TypeScript能获取更多类型信息，因此这并非问题。

但显然，围观者的👎表明大家对此观点接受度不高。

解释之后，贡献者给该issue添加了Working as Intended（按预期工作）标签并将问题标记为完成。同时，issue作者表示理解，并善意地向后来者介绍自己已通过module-alias解决了问题。

但围观者显然未被说服，大家陆续在该issue下评论。一些人介绍自己的解决办法，一些人挺TypeScript，但更多人吐槽该设计糟糕，实在想不通，希望有人能解释清楚。

这场讨论持续了两年多，期间许多人@TypeScript贡献者，表示已过去两年，希望重新考虑这个令人困惑的设计。甚至有人在reddit上发帖：Path maps cannot be resolved by tsc / Works as intended - what a joke。

时间来到2019年2月，issue最初回复的一位贡献者站出来发表长文解释。大致意思是，TypeScript在编译中修改路径这些字面值是不切实际的。TypeScript的工作重点应是更好地与其他更擅长此类工作的模块协作，而非为了支持更灵活的配置自行实现这些功能，更别提可能因此生成“崩坏”的代码。

同日，TypeScript组成员DanielRosenwasser再次明确表示：即使未来可能优化这里的开发体验，TypeScript也不会修改用户写下的路径。随后便锁定了该问题。

至此，这个故事画上了句号。

现在了解了事情的前因后果，我们就可以来总结一下这个问题的根本原因了。

tsc不转换路径别名的根本原因

站在开发者角度，我们希望用更少的工具完成更多事情，这无可厚非。但站在TypeScript本身角度，它只是开发阶段使用的工具。其核心目的是优化开发体验，在开发时以强类型约束代码。换句话说，TypeScript表示自己是负责开发的，打包工作并非其强项，它大概编译一下，去掉类型信息，剩下的打包工作交给更专业的工具来做。

因此，我们可以将tsc编译后的代码视为一种“中间产物”，TypeScript期望用户使用更贴近需求的工具将这些代码二次编译为实际的生产代码。

现在我们回头看一下TypeScript手册中关于路径别名的介绍：

可以看到，paths配置项的本意是为一些模块提供特殊的引入渠道。注意，此处引入的包只是开发时需要的，而不一定是生产时使用的。

例如，我们可以在开发时（使用TypeScript开发时）引入一些开发模式的包，而在生产时则使用压缩过的.min.js包，更甚者我们可能会选择在生产时使用cdn链接这些包而不是直接引入。

如果tsc自己会转换这些路径别名，那么后续的打包工具就无从得知这个包是需要特殊对待的。在这些打包工具眼里，这些引入的第三方代码和你自己写的代码地位相同。

更危险的情况下，如果paths引入的这个包是只能用在开发环境下的，那么直接转换路径别名就相当于把开发包编译到代码包然后发布到生产环境里，从而导致程序崩溃的风险。这也是为什么kitsonk最后说：

Just because TypeScript can be configured to resolve modules in flexible ways doesn't not mean that TypeScript emits "broken code".

Daniel Rosenwasser最后也提到，paths配置项允许用户自己选择引入的是何种格式的包，例如AMD或是systemjs。在开发阶段这无关紧要，而在打包阶段，用哪种格式的包应该交给更专业的打包工具来选择。

换一个角度看这个问题，使用者希望TypeScript必须一丝不苟地把自己的TypeScript代码翻译成JavaScript代码，之前执行什么样，转换成JavaScript代码后执行就得什么样。而自己替换路径别名这件事就开了个口子，编译器居然把一个根本不可能变化的字面值给改了？

现在好了，如果你是tsc，现在甲方又想让你保证代码的准确性，又因为懒想让你自己修改代码。你怎么干？你能怎么干？

当然是不干。毕竟霸哥也说过：

我宁愿什么都不做，也不愿犯错。

总结

本文介绍了怎么解决TypeScript项目中的路径别名问题以及为什么会有这个问题。本来打算简单写一下，没想到还是洋洋洒洒几千字出去了。

其实原因上面说了这么多，总结起来也就一句话：路径别名替换这件事我不干也有更专业的人来干，我要干了可能会出问题，出了问题你们还得骂我。

参考

• typescript - tsc - doesn't compile alias paths - Stack Overflow
• Module path maps are not resolved in emitted code · Issue #10866 · microsoft/TypeScript · GitHub
• Path maps cannot be resolved by tsc / Works as intended - what a joke : typescript (reddit.com)
• TypeScript: Documentation - Module Resolution (typescriptlang.org)
• 解决typescript 在 node.js 下使用别名（paths）无效的问题

到此这篇关于typescript路径别名问题的文章就介绍到这了,更多相关typescript路径别名问题内容请搜索本站以前的文章或继续浏览下面的相关文章希望大家以后多多支持本站！