[Module Resolution](https://www.typescriptlang.org/docs/handbook/module-resolution.html)

模組解析是編譯器用來確定匯入所指內容的過程。考慮像 import { a } from "moduleA"; 這樣的匯入語句。為了檢查 a 的任何使用，編譯器需要確切地知道它代表什麼，並且需要檢查它的定義 moduleA。

此時，編譯器會問“moduleA 的形狀是什麼？”雖然這聽起來很簡單，但 moduleA 可以在您自己的 .ts/.tsx 檔案之一中定義，或者在您的程式碼所依賴的 .d.ts 中定義。

首先，編譯器會嘗試定位一個代表匯入模組的檔案。為此，編譯器遵循兩種不同策略之一：classical 或 Node。這些策略告訴編譯器去哪裡尋找 moduleA。

如果這不起作用並且模組名稱是非相關的（在“moduleA”的情況下，它是），那麼編譯器將嘗試定位一個環境模組宣告。接下來我們將介紹非相對匯入。

最後，如果編譯器無法解析模組，它將記錄一個錯誤。在這種情況下，錯誤類似於錯誤 TS2307：找不到模組 'moduleA'。

# Relative vs. Non-relative module imports

根據模組引用是相對的還是非相對的，模組匯入的解析方式不同。

相對匯入是以 /、./ 或 ../ 開頭的匯入。 一些例子包括：

* import Entry from "./components/Entry";
* import { DefaultHeaders } from "../constants/http";
* import "/mod";

任何其他匯入都被認為是非相關的。 一些例子包括：

* import * as $ from "jquery";
* import { Component } from "@angular/core";

相對匯入是相對於匯入檔案解析的，無法解析為環境模組宣告。 您應該對自己的模組使用相對匯入，以保證在執行時保持其相對位置。

# Module Resolution Strategies

有兩種可能的模組解析策略：Node 和 Classic。 您可以使用 --moduleResolution 標誌來指定模組解析策略。 如果未指定，則 --module commonjs 預設為 Node，否則預設為 Classic（包括 --module 設定為 amd、system、umd、es2015、esnext 等時）。

注意：Node 模組解析是 TypeScript 社群中最常用的，推薦用於大多數專案。 如果您在 TypeScript 中遇到匯入和匯出的解析問題，請嘗試設定 moduleResolution: "node" 以檢視它是否解決了問題。

## Classical 解析策略

這曾經是 TypeScript 的預設解析策略。 如今，這種策略主要是為了向後相容。

相對匯入將相對於匯入檔案進行解析。 因此，在原始檔 /root/src/folder/A.ts 中 import { b } from "./moduleB" 將導致以下查詢：

* /root/src/folder/moduleB.ts
* /root/src/folder/moduleB.d.ts

然而，對於非相關模組匯入，編譯器從包含匯入檔案的目錄開始沿著目錄樹向上走，試圖找到匹配的定義檔案。

例如：

在原始檔 /root/src/folder/A.ts 中，對 moduleB 的非相對匯入，例如 import { b } from "moduleB"，將導致嘗試使用以下位置來定位 "moduleB"：

```sql
/root/src/folder/moduleB.ts
/root/src/folder/moduleB.d.ts
/root/src/moduleB.ts
/root/src/moduleB.d.ts
/root/moduleB.ts
/root/moduleB.d.ts
/moduleB.ts
/moduleB.d.ts
```

## Node 模式

這種解析策略試圖在執行時模仿 Node.js 模組解析機制。 Node.js 模組文件中概述了完整的 Node.js 解析演算法。

Node.js 如何解析模組？

要了解 TS 編譯器將遵循哪些步驟，瞭解 Node.js 模組非常重要。傳統上，Node.js 中的匯入是透過呼叫名為 require 的函式來執行的。 Node.js 採取的行為將根據 require 是相對路徑還是非相對路徑而有所不同。

相對路徑相當簡單。例如，讓我們考慮一個位於 /root/src/moduleA.js 的檔案，其中包含 import var x = require("./moduleB"); Node.js 按以下順序解析該匯入：

* 詢問名為 /root/src/moduleB.js 的檔案是否存在。
* 詢問資料夾 /root/src/moduleB 是否包含指定“主”模組的名為 package.json 的檔案。在我們的示例中，如果 Node.js 發現檔案 /root/src/moduleB/package.json 包含 { "main": "lib/mainModule.js" }，那麼 Node.js 將引用 /root/src/moduleB/lib/mainModule.js。
* 詢問資料夾 /root/src/moduleB 是否包含名為 index.js 的檔案。該檔案被隱式視為該資料夾的“主”模組。

但是，對非相關模組名稱的解析以不同的方式執行。 Node 將在名為 node_modules 的特殊資料夾中查詢您的模組。 node_modules 資料夾可以與當前檔案位於同一級別，也可以在目錄鏈中的更高階別。 Node 將沿著目錄鏈向上遍歷，檢視每個 node_modules，直到找到您嘗試載入的模組。

按照我們上面的例子，考慮 /root/src/moduleA.js 是否使用非相對路徑並匯入 var x = require("moduleB");。然後，Node 會嘗試將 moduleB 解析為每個位置，直到一個位置正常工作。

(1) /root/src/node_modules/moduleB.js
(2) /root/src/node_modules/moduleB/package.json（如果它指定了“main”屬性）
(3) /root/src/node_modules/moduleB/index.js

(4) /root/node_modules/moduleB.js
(5) /root/node_modules/moduleB/package.json（如果它指定了“main”屬性）
(6) /root/node_modules/moduleB/index.js

(7) /node_modules/moduleB.js
(8) /node_modules/moduleB/package.json（如果它指定了“main”屬性）
(9) /node_modules/moduleB/index.js

請注意，Node.js 在步驟 (4) 和 (7) 中跳轉了一個目錄。

您可以在 Node.js 文件中閱讀有關從 node_modules 載入模組的更多資訊。

# How TypeScript resolves modules

TypeScript 將模仿 Node.js 執行時解析策略，以便在編譯時定位模組的定義檔案。為此，TypeScript 在 Node 的解析邏輯上覆蓋了 TypeScript 原始檔副檔名（.ts、.tsx 和 .d.ts）。 TypeScript 還將使用 package.json 中名為“types”的欄位來反映“main”的用途——編譯器將使用它來查詢要查閱的“main”定義檔案。

例如，像 /root/src/moduleA.ts 中的 import { b } from "./moduleB" 這樣的匯入語句將導致嘗試以下位置來定位 "./moduleB"：

(1)/root/src/moduleB.ts
(2)/root/src/moduleB.tsx
(3)/root/src/moduleB.d.ts
(4)/root/src/moduleB/package.json（如果它指定了“types”屬性）
(5)/root/src/moduleB/index.ts
(6)/root/src/moduleB/index.tsx
(7)/root/src/moduleB/index.d.ts

回想一下，Node.js 查詢名為 moduleB.js 的檔案，然後是適用的 package.json，然後是 index.js。

同樣，非相對匯入將遵循 Node.js 解析邏輯，首先查詢檔案，然後查詢適用的資料夾。因此，在原始檔 /root/src/moduleA.ts 中 import { b } from "moduleB" 將導致以下查詢：

```sql
/root/src/node_modules/moduleB.ts
/root/src/node_modules/moduleB.tsx
/root/src/node_modules/moduleB.d.ts
/root/src/node_modules/moduleB/package.json（如果它指定了“types”屬性）
/root/src/node_modules/@types/moduleB.d.ts
/root/src/node_modules/moduleB/index.ts
/root/src/node_modules/moduleB/index.tsx
/root/src/node_modules/moduleB/index.d.ts

/root/node_modules/moduleB.ts
/root/node_modules/moduleB.tsx
/root/node_modules/moduleB.d.ts
/root/node_modules/moduleB/package.json（如果它指定了“types”屬性）
/root/node_modules/@types/moduleB.d.ts
/root/node_modules/moduleB/index.ts
/root/node_modules/moduleB/index.tsx
/root/node_modules/moduleB/index.d.ts

/node_modules/moduleB.ts
/node_modules/moduleB.tsx
/node_modules/moduleB.d.ts
/node_modules/moduleB/package.json（如果它指定了“types”屬性）
/node_modules/@types/moduleB.d.ts
/node_modules/moduleB/index.ts
/node_modules/moduleB/index.tsx
/node_modules/moduleB/index.d.ts
```

不要被這裡的步驟數嚇倒——TypeScript 仍然只在步驟 (9) 和 (17) 中兩次跳轉目錄。這實際上並不比 Node.js 本身所做的更復雜。

# Additional module resolution flags

專案源佈局有時與輸出佈局不匹配。 通常一組構建步驟會生成最終輸出。 其中包括將 .ts 檔案編譯為 .js，以及將依賴項從不同的源位置複製到單個輸出位置。 最終結果是模組在執行時的名稱可能與包含其定義的原始檔的名稱不同。 或者最終輸出中的模組路徑可能在編譯時與其對應的原始檔路徑不匹配。

TypeScript 編譯器有一組額外的標誌來通知編譯器預期發生在源上的轉換以生成最終輸出。

需要注意的是，編譯器不會執行任何這些轉換； 它只是使用這些資訊來指導將模組匯入解析到其定義檔案的過程。

# Base Url

在使用 AMD 模組載入器的應用程式中，使用 baseUrl 是一種常見做法，其中模組在執行時“部署”到單個資料夾。 這些模組的原始碼可以位於不同的目錄中，但是構建指令碼會將它們放在一起。

設定 baseUrl 通知編譯器在哪裡可以找到模組。 假定所有具有非相對名稱的模組匯入都與 baseUrl 相關。

baseUrl 的值確定為：

(1)baseUrl 命令列引數的值（如果給定的路徑是相對的，則根據當前目錄計算）

(2)'tsconfig.json' 中 baseUrl 屬性的值（如果給定的路徑是相對的，則根據 'tsconfig.json' 的位置計算）

請注意，相對模組匯入不會受到設定 baseUrl 的影響，因為它們總是相對於它們的匯入檔案進行解析。

您可以在 RequireJS 和 SystemJS 文件中找到有關 baseUrl 的更多文件。

# path mapping

有時模組並不直接位於 baseUrl 下。例如，對模組“jquery”的匯入將在執行時轉換為“node_modules/jquery/dist/jquery.slim.min.js”。載入器使用對映配置在執行時將模組名稱對映到檔案，請參閱 RequireJs 文件和 SystemJS 文件。

TypeScript 編譯器支援使用 tsconfig.json 檔案中的“paths”屬性宣告此類對映。 以下是如何為 jquery 指定“paths”屬性的示例。

```json
{
  "compilerOptions": {
    "baseUrl": ".", // This must be specified if "paths" is.
    "paths": {
      "jquery": ["node_modules/jquery/dist/jquery"] // This mapping is relative to "baseUrl"
    }
  }
}
```

# 如何檢查 TypeScript 模組解析過程

如前所述，編譯器在解析模組時可以訪問當前資料夾之外的檔案。 在診斷模組未解析的原因或解析為不正確的定義時，這可能很困難。 使用 --traceResolution 啟用編譯器模組解析跟蹤可以深入瞭解模組解析過程中發生的情況。

假設我們有一個使用 typescript 模組的示例應用程式。

app.ts has an import like import * as ts from "typescript".

```typescript

│   tsconfig.json
├───node_modules
│   └───typescript
│       └───lib
│               typescript.d.ts
└───src
        app.ts
```

使用如下命令列編譯：

> tsc --traceResolution

結果：

```sql
======== Resolving module 'typescript' from 'src/app.ts'. ========
Module resolution kind is not specified, using 'NodeJs'.
Loading module 'typescript' from 'node_modules' folder.
File 'src/node_modules/typescript.ts' does not exist.
File 'src/node_modules/typescript.tsx' does not exist.
File 'src/node_modules/typescript.d.ts' does not exist.
File 'src/node_modules/typescript/package.json' does not exist.
File 'node_modules/typescript.ts' does not exist.
File 'node_modules/typescript.tsx' does not exist.
File 'node_modules/typescript.d.ts' does not exist.
Found 'package.json' at 'node_modules/typescript/package.json'.
'package.json' has 'types' field './lib/typescript.d.ts' that references 'node_modules/typescript/lib/typescript.d.ts'.
File 'node_modules/typescript/lib/typescript.d.ts' exist - use it as a module resolution result.
======== Module name 'typescript' was successfully resolved to 'node_modules/typescript/lib/typescript.d.ts'. ========
```

觸發模組解析的原始碼位置：

> ======== Resolving module ‘typescript’ from ‘src/app.ts’. ========

模組解析策略：

> Module resolution kind is not specified, using ‘NodeJs’.

Loading of types from npm packages:

‘package.json’ has ‘types’ field ‘./lib/typescript.d.ts’ that references ‘node_modules/typescript/lib/typescript.d.ts’.

最後成功解析的輸出：

======== Module name ‘typescript’ was successfully resolved to ‘node_modules/typescript/lib/typescript.d.ts’. ========

TypeScript 裡的 module 解析過程 - Module Resolution

相關文章