typescript路徑別名問題詳解與前世今生的故事

更新時間：2022年07月06日 09:02:18 作者：hopgoldy

我們都知道只有正確引用路徑,Typescript才不會提示報錯,這篇文章主要給大家介紹了關(guān)于typescript路徑別名問題詳解與前世今生的故事,文中通過示例代碼介紹的非常詳細(xì),需要的朋友可以參考下

前言

最近在 typescript 項(xiàng)目上踩了不少坑，打算寫幾篇文章記錄一下。

本篇文章就來梳理一下 ts 的相關(guān)技術(shù)棧 tsc、ts-node、ts-node-dev 中的路徑別名問題，從開發(fā)到打包階，不僅告訴你坑在哪，怎么解決，還會還會告訴你為什么會有這個坑以及坑背后的故事。

開始探索

本篇文章會以一個空項(xiàng)目開始，由淺入深的告訴你會遇到的各種問題，有興趣的同學(xué)可以跟著往下做一下：

首先找一個空文件夾，請出本文的核心嘉賓 ts-node：

npm install ts-node typescript

然后完善一下項(xiàng)目，添加一個相當(dāng)基礎(chǔ)的 tsconfig.json：

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

然后在 package.json 里加入我們的 ts-node 執(zhí)行命令，執(zhí)行后 ts-node 就會去讀 index.ts 并執(zhí)行：

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

這樣一個 typescript 開發(fā)環(huán)境就準(zhǔn)備就緒了，然后我們新建 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))

這些代碼很簡單，導(dǎo)出了一個加法函數(shù)，然后在 index.ts 里引用并打印了出來，現(xiàn)在我們執(zhí)行 npm run dev 就可以看到如下結(jié)果：

沒毛病，一切正常，現(xiàn)在我們通過路徑別名引入 utils：

// 把 utils 的引入換成了 @ 路徑別名
import { plus } from "@/utils";

然后再來執(zhí)行一下：

出問題了，找不到對應(yīng)的模塊，這個問題其實(shí)不在 ts-node，而是因?yàn)?tsc 在編譯代碼時不會去把路徑別名替換成對應(yīng)的相對路徑，所以 ts-node 用 tsc 編譯完然后轉(zhuǎn)交給 node 執(zhí)行的時候自然就找不到 @/ 這個目錄了。

解決起來很簡單，只需要安裝一個包：

npm install tsconfig-paths

然后在 package.json 里改一下 dev 命令即可，這里的 -r 實(shí)際上是 node 的命令行參數(shù)，有興趣的可以去看一下這個：Command-line API | Node.js v16.15.1 Documentation (nodejs.org)：

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

然后再執(zhí)行就發(fā)現(xiàn)正常了：

ts-node-dev 使用路徑別名

很多同學(xué)在開發(fā) ts 項(xiàng)目的時候都是使用 nodemon 監(jiān)聽文件變更，然后使用 ts-node 執(zhí)行代碼。比如這樣：

"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 還有個好處就是 它會緩存 tsc 的編譯過程，所以熱更新速度比 nodemon + ts-node 快了很多。非常推薦大家試用一下。

關(guān)于路徑別名的打包問題

還沒完，我們現(xiàn)在只解決了開發(fā)時的問題。如果路徑別名是 tsc 負(fù)責(zé)的話，那么打包時也會遇到這個問題。現(xiàn)在我們就來看一下打包時會怎樣。

首先，在命令行執(zhí)行 npx tsc，然后去 ./dist/index.js 里看一下打包后的成果：

果然，tsc 沒有把我們的路徑別名轉(zhuǎn)換成實(shí)際的相對路徑。那么執(zhí)行 node ./dist/index.js 時肯定會報錯找不到 @/utils，所以該如何解決這個問題呢？

一般來說有兩種方法，先說菜一點(diǎn)的，我們剛才提到 tsconfig-paths/register 實(shí)際上是用于 node 的一個包，那么這里自然也可以這么用，在 package.json 里添加如下命令（記得安裝 cross-env ）：

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

然后再執(zhí)行就可以了：

簡單解釋一下，這里用環(huán)境變量 TS_NODE_BASEURL 覆蓋了 tsconfig.json 里的 baseurl，來讓查找路徑別名指向的目錄時可以找到正確的（編譯后）的文件。后面就是正常的 node -r 引用對應(yīng)包然后執(zhí)行文件。

但是這種操作屬于“運(yùn)行時”處理，相信很多人都會覺得不舒服。所以更簡單的方法是在編譯代碼時就一勞永逸的替換掉路徑別名，就是下面這種方法（推薦）：

我們可以安裝 npm install tsc-alias 這個包，用于替換路徑別名，用法也很簡單，跟在 tsc 后面就可以了：

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

現(xiàn)在執(zhí)行 npm run build 之后就可以看到路徑別名已經(jīng)被替換成相對路徑了：

當(dāng)然，這個只是比較簡單的解決方式之一，你也可以根據(jù)項(xiàng)目的實(shí)際情況來，比如使用 webpack 或者 vite，又或者你可以看下文末參考小節(jié)里的第一個鏈接來了解更多的解決方法。

tsc 為什么不會轉(zhuǎn)換路徑別名？

文章寫到這里，我們已經(jīng)解決了 ts 項(xiàng)目中的路徑別名問題，但是相信很多人依舊有一個困惑：tsc 為什么不在編譯的時候直接把路徑別名替換掉？

在網(wǎng)上搜索相關(guān)的問題，能找到的大多都是如何解決這個問題，而對這個問題起因的解釋卻很少，我在搜索解決方法的時候也只看到有人說，這件事啊，說來話長了。

這不由得勾起了我的興趣，在詳細(xì)搜索之后，我找到了這篇討論，卻沒想到居然是一篇橫跨三年的故事。下面我們就大致了解一下這個問題的前世今生，如果你感興趣的話也可以直接去看一下：Module path maps are not resolved in emitted code · Issue #10866

故事要從 2016 年 9 月說起，當(dāng)時的 typescript 還在 2.1 開發(fā)版。有人在試用了 tsconfig 中的 paths 配置時也遭遇了相同的困惑，他便提交了一個 issue 來詢問這個問題（事實(shí)上，最早的 issue 記錄可以追溯到 2016 年 7 月份，不過問題相同，這里不再贅述）。

沒過兩天，有兩位 ts 貢獻(xiàn)者先后回復(fù)到：你有沒有同時在用一些 webpack 之類的打包工具？另一位則簡單介紹了這么做是 有意為之的，paths 配置項(xiàng)的本意是想為一些第三方包提供特殊的引入渠道，使得 ts 可以獲得更多類型信息，所以這不是個問題。

但是很顯然，圍觀者的 ?? 表明大家都不是很能接受這個觀點(diǎn)。

在解釋之后，貢獻(xiàn)者給本 issue 添加了 Working as Intended（按預(yù)期工作）標(biāo)簽并把問題標(biāo)記為完成，同時 issue 作者也表明可以理解，并善意的給后來者介紹了自己已經(jīng)通過 module-alias 解決了問題。

但是圍觀者顯然沒有被說服，大家開始陸續(xù)在這個 issue 下評論，一些人在介紹自己使用的解決辦法，一些人在挺 ts，但是更多的人在吐槽這個設(shè)計(jì)太糟糕了，自己實(shí)在想不明白，希望有人能解釋一下。

這個討論足足持續(xù)了兩年多，期間很多人 @ ts 貢獻(xiàn)者并表示已經(jīng)過去兩年時間了，希望可以重新考慮下這個令人困惑的設(shè)計(jì)。甚至有人在 reddit 上發(fā)了帖子：Path maps cannot be resolved by tsc / Works as intended - what a joke。

時間來到 2019 年 2 月份，issue 最開始回復(fù)的一位貢獻(xiàn)者站出來發(fā)出了一段長文進(jìn)行了解釋。大致意思就是，ts 在編譯中修改路徑這些字面值是不切實(shí)際的。ts 的工作重點(diǎn)應(yīng)該是如何更好的和其他更擅長此類工作的模塊相互協(xié)作，而不是為了支持更靈活的配置來自己實(shí)現(xiàn)這些功能，更別提可能會因此生成出“崩壞”的代碼。

同一天，ts 組成員 DanielRosenwasser 再次明確表示了：哪怕將來可能會優(yōu)化這里的開發(fā)體驗(yàn)，ts 也不會修改用戶寫下的路徑。隨后便鎖定了這個問題。

至此，這個故事便畫上了句號。

現(xiàn)在了解了事情的前因后果，我們就可以來總結(jié)一下這個問題的根本原因了。

tsc 不轉(zhuǎn)換路徑別名的根本原因

站在開發(fā)者的角度看，我們希望可以用更少的工具完成更多的事情，這無可厚非。但是站在 ts 本身的角度看，typescript 只是開發(fā)階段使用的一個工具。它的核心目的也是優(yōu)化開發(fā)體驗(yàn)，在開發(fā)時以強(qiáng)類型對代碼進(jìn)行約束。換句話說就是 ts 表示我是負(fù)責(zé)開發(fā)的，打包工作不是我的強(qiáng)項(xiàng)，我大概編譯一下，去掉我的類型，剩下的打包工作交給更專業(yè)的工具來做。

所以我們可以把 tsc 編譯后的代碼看作是一種“中間產(chǎn)物”，typescript 期望用戶可以使用更貼近自己需求的工具將這些代碼二次編譯為實(shí)際的生產(chǎn)代碼。

現(xiàn)在我們回頭看一下 ts hankbook 中關(guān)于路徑別名的介紹：

可以看到，paths 配置項(xiàng)的本意是為了給一些模塊提供特殊的引入渠道。注意，此處引入的包只是你開發(fā)時需要的，而不一定是生產(chǎn)時使用的。

例如，我們可以在開發(fā)時（使用 ts 開發(fā)時）引入一些開發(fā)模式的包，而在生產(chǎn)時則使用壓縮過的 .min.js 包，更甚者我們可能會選擇在生產(chǎn)時使用 cdn 來鏈接這些包而不是直接引入。

如果 tsc 自己會轉(zhuǎn)換這些路徑別名，那么后續(xù)的打包工具就無從得知這個包是需要特殊對待的。在這些打包工具眼里這些引入的第三方代碼和你自己寫的代碼是地位相同的。

更危險的情況下，如果 paths 引入的這個包是只能用在開發(fā)環(huán)境下的，那么直接轉(zhuǎn)換路徑別名就相當(dāng)于把開發(fā)包編譯到代碼包然后發(fā)布到生產(chǎn)環(huán)境里，從而導(dǎo)致程序崩潰的風(fēng)險。這也是為什么 kitsonk 最后說：