Skip to content
FEE
Frontend Engineering Essentials
Entry Level

tsconfig 與嚴格模式 ​

tsconfig.json 是 TypeScript 編譯器的設定檔。它控制哪些檔案被納入編譯、輸出哪個 JavaScript 版本、如何解析模組匯入(module resolution),以及執行哪些型別檢查。這個檔案是專案 TypeScript 行為的單一權威來源——其內容決定了編譯器能捕捉哪些錯誤、產生什麼 JavaScript 輸出,以及專案如何與編輯器、打包工具和 CI 流程整合。

大多數專案只需要不到二十個 tsconfig.json 選項就能達到正確且高效的設定。tsconfig 參考文件的選項範圍很廣——涵蓋語言功能、輸出控制、模組解析和診斷行為——但絕大多數選項都可以保留預設值。理解最重要的十個選項,並知道常見的錯誤設定為何發生,能防止那些讓 TypeScript 價值大打折扣的隱性型別檢查缺口。設定有誤的 tsconfig 本身不會產生編譯器錯誤;編譯器只是靜默地無法捕捉原本應該捕捉到的錯誤。

最關鍵的設定決策集中在兩個核心關注點:嚴格度(strictness)和模組解析(module resolution)。嚴格度控制編譯器如何積極地檢查 null 解引用、隱式 any 和函式參數的型別變異性。模組解析控制編譯器如何解讀匯入路徑,以及其對這些路徑的理解是否與執行環境或打包工具一致。這兩個關注點對於幾乎所有專案都有正確答案,而兩者也都經常被設定錯誤——錯誤的方式在執行時產生 bug 之前是完全不可見的。不可見性正是其危險之處:這兩種錯誤設定都不會產生關於自身的編譯器錯誤。

第三個關注點是專案參考(project references),當程式碼庫成長為 monorepo 中的多個套件時,它就變得相關。專案參考讓 TypeScript 能理解套件之間的相依關係、啟用增量編譯(incremental compilation),並在不需要將所有套件一起編譯的情況下產生準確的跨套件型別。與嚴格度和模組解析一樣,專案參考有其正確的設定方式,這種方式並不是一眼就能看出的,而設定錯誤的代價——隱性的建置順序問題或套件邊界之間的過時型別——最終以除錯時間的形式支付,而不是以編譯器錯誤的形式浮現。

設計思維 ​

strict 旗標作為一個整體 ​

strict: true 不是單一的編譯器檢查——它是一個同時啟用一組相關檢查的總括旗標。在 TypeScript 5.x 中,這個總括旗標涵蓋 noImplicitAny、strictNullChecks、strictFunctionTypes、strictBindCallApply、strictPropertyInitialization、noImplicitThis、alwaysStrict 和 useUnknownInCatchVariables。每個檢查都針對一種不同的型別安全缺口。noImplicitAny 防止 TypeScript 無法推斷更具體型別時,變數靜默地接收 any 型別;沒有它,每個未標注型別的參數都變成 any,型別系統的保證就無聲地崩潰了。strictNullChecks 防止 null 和 undefined 值流入期待具體值的位置;沒有它,每種型別都隱含地包含 null | undefined,編譯器就無法標記造成大多數 JavaScript 執行時例外的 null 解引用。strictFunctionTypes 對函式參數型別強制逆變性(contravariance),而不是允許 TypeScript 早期型別系統為了向後相容而容許的不健全共變性(covariance)。

總括設計是刻意為之且具前瞻性的。當 TypeScript 在未來版本添加新的嚴格檢查時,它們會自動加入 strict: true 之下。一個啟用了 strict: true 的專案,在升級 TypeScript 時會自動獲得未來的型別安全改進,而無需明確列舉每個新旗標。一個只啟用了個別旗標而省略總括旗標的專案,被鎖定在它明確列舉的檢查中。當 TypeScript 5.2 添加新的嚴格檢查時,該專案的升級不包含這個檢查;新類別的錯誤不會被偵測,而且團隊無法知道他們缺少了什麼,因為 tsconfig 看起來是完整的。

在已有 strict: true 的專案中,為了讓錯誤消失而禁用特定嚴格旗標,是一種隨時間累積的型別技術債。一旦團隊學到個別嚴格旗標可以被禁用,這個模式就會蔓延:每個遇到不方便的嚴格錯誤的工程師都會禁用相關旗標而不是修復底層程式碼,被禁用的檢查集合持續增長。經過幾次這樣的決策後,專案在頂層有 strict: true,但有一組 noImplicitAny: false 和 strictNullChecks: false 覆蓋,取消了大部分效果。tsconfig 看起來是嚴格的,但幾乎沒有提供任何保護。面對嚴格模式錯誤的正確回應始終是修復錯誤所指出的程式碼——這個錯誤是編譯器在報告宣告型別與執行時行為不符。

將遺留程式碼庫導入嚴格模式的實際做法是:在第一次執行時啟用 strict: true 通常會產生數百甚至數千個錯誤。推薦的方法是在僅供新檔案使用的獨立 tsconfig 中啟用嚴格模式,並透過將現有檔案移入嚴格模式 config 的 include 模式來逐步遷移。TypeScript 的 @ts-expect-error 指令可以標記已知的預先存在的錯誤供後續解決,而不是全域地抑制檢查。通往完整嚴格模式的路徑,在被視為一個有追蹤進度的遷移專案而不是必須一次性切換的旗標時,是可以管理的。

模組解析:大多數設定混淆的根源 ​

moduleResolution 選項控制 TypeScript 在搜尋對應匯入陳述式的型別時,如何解讀匯入路徑。這個選項必須獨立於 module 選項設定——module 選項控制 TypeScript 輸出的 JavaScript 格式。兩個選項相互影響但並不相同:module: "ESNext" 並不意味著 moduleResolution: "bundler",只設定其中一個而不明確設定另一個,會讓第二個保留其預設值,而這個預設值可能不適合專案的環境。module 和 moduleResolution 的組合必須保持一致:TypeScript 在組合矛盾時會產生診斷,但在組合僅僅對專案的執行時不是最優時不會產生診斷。

傳統的 "node" 解析演算法是為早期 Node.js 中的 CommonJS 模組系統設計的。它透過遍歷父目錄來搜尋 node_modules,將目錄匯入視為指向目錄的 index.js,並讀取 package.json 的 main 欄位。它不讀取 exports 欄位。package.json 中的 exports 欄位是現代套件如何為不同環境提供不同模組進入點的方式——ESM 對 CommonJS、瀏覽器對 Node.js、開發對生產。當 TypeScript 使用 "node" 解析而套件使用 exports 作為其主要 API 介面時,TypeScript 可能解析到錯誤的進入點或完全找不到套件,而打包工具——確實讀取 exports 的那個——則正確解析。結果是一個打包和執行都正確但產生虛假 TypeScript 錯誤的程式碼庫,或者更糟:TypeScript 解析到與打包工具不同的進入點,匯入看似針對過時或不正確的型別進行了型別檢查。

"bundler" 解析在 TypeScript 5.0 中引入,模擬了 Vite 和 webpack 等打包工具實際解析匯入的方式。它讀取 exports 欄位、理解條件式導出,並允許相對匯入中不帶副檔名,因為打包工具會添加副檔名。這是前端專案和任何由打包工具在 TypeScript 原始碼和執行時之間進行中介的全端專案的正確選擇。"node16" 和 "nodenext" 模擬 Node.js 自身的 ESM 解析演算法,它也讀取 exports 欄位,但要求相對匯入中明確帶有副檔名,這與 Node.js 自身對 ESM 的要求一致。在 "bundler" 和 "node16" 之間的正確選擇,完全取決於執行時的模組解析是由打包工具還是由 Node.js 直接執行。

正確設定 moduleResolution 是消除現代 TypeScript 專案中虛假「模組找不到」錯誤最有效的單一步驟。一個次要但重要的步驟是確保 module 與 moduleResolution 一致地設定。對於使用 "bundler" 解析的 Vite 專案,module: "ESNext" 是正確的。對於使用 "node16" 解析的 Node.js 專案,module: "Node16" 或 "NodeNext" 是正確的。混合這些設定——例如 module: "CommonJS" 搭配 moduleResolution: "bundler"——可能產生 TypeScript 錯誤或靜默的行為差異,因為輸出的 JavaScript 格式與解析模型對執行時匯入工作方式的假設不符。

module 和 moduleResolution 的交互是 GitHub 和 Stack Overflow 上報告的大多數「在打包工具中有效但 TypeScript 抱怨」錯誤的根源。當一個團隊升級到使用 exports 的現代套件而 TypeScript 突然找不到它時,解決方案幾乎從來不是降級套件——而是將 moduleResolution 升級到 "bundler" 或 "node16"。一旦做出這個更改,整類虛假的匯入錯誤就消失了,專案的 TypeScript 設定就準確地模擬了執行時將要做的事情。 moduleResolution: "bundler" 與打包工具解析模型的對齊,也是準確型別檢查條件式導出(conditional exports)的先決條件——這類套件針對 ESM 和 CommonJS 消費者暴露不同的 API;"bundler" 解析遵循 exports map 中的 import 條件,而 "node" 解析則完全忽略這些條件,導致 TypeScript 和打包工具針對相同匯入解析到不同的型別,產生難以診斷的型別與執行時行為差異。 在 tsconfig 審查清單中加入「確認 moduleResolution 值與執行時環境或打包工具相符」這一條,可防止新專案或遷移後的專案在設定上採用過時的預設值,讓解析設定的正確性成為啟動階段就被驗證的屬性,而非在首次遇到虛假匯入錯誤時才被追溯修正。 當 TypeScript 版本升級時,確認 strict: true 涵蓋的旗標集合是否新增了項目,以及是否有原本無錯誤的程式碼因新的嚴格檢查而產生錯誤,是升級流程不可略過的驗收步驟;這些新增的錯誤是型別系統告知「此處有潛在問題」的訊號,應優先修復而非以 @ts-expect-error 暫時壓制。

適用於 monorepo 的專案參考 ​

擁有多個套件的大型程式碼庫——一個設計系統函式庫、共享工具套件,以及一個或多個應用套件——面臨著單一 tsconfig 無法有效解決的 TypeScript 編譯挑戰。如果每個套件都包含在單一的編譯中,TypeScript 必須一起處理所有套件的所有原始碼檔案。這消除了在套件邊界進行增量建置的可能性,讓強制套件間可見性規則變得不可能,並導致編譯時間隨程式碼庫的總規模而增長,而不是隨著變更的規模而增長。對於一個擁有十個套件、合計十萬行程式碼的 monorepo,更改一個套件中的工具函式會觸發所有十個套件的完整重新編譯。

如果每個套件都有自己的 tsconfig 並獨立編譯,TypeScript 不理解套件之間的相依關係,無法在不要求每個套件預先編譯的情況下提供準確的跨套件型別檢查。這產生了一個工程師必須按相依順序在每個套件中執行 tsc 才能對下游套件進行型別檢查的工作流程——一個既容易出錯又緩慢的手動過程。

TypeScript 專案參考解決了這兩個問題。每個套件都有自己的 tsconfig.json,並啟用 composite: true。composite 旗標指示 TypeScript 在已編譯的輸出旁產生 .d.ts 宣告檔案,並儲存一個記錄編譯狀態以供增量建置使用的 .tsbuildinfo 檔案。根目錄的 tsconfig 透過 references 陣列將每個套件列為參考。當編譯器處理下游套件時,它讀取上游被參考套件的預建宣告檔案,而不是重新處理它們的原始碼。這意味著更改一個套件中的檔案只需要重新編譯該套件以及傳遞依賴它的套件——而不是整個 monorepo。

專案參考也透過 tsc --build 模式啟用建置排序,該模式讀取參考圖並確定正確的編譯順序。這消除了下游套件在其上游相依項尚未建置之前就開始編譯的建置失敗類別。tsc --build --watch 將此擴展到增量監視模式:它監視所有套件的檔案變更,並只重新編譯受影響的子圖,使內部開發迴圈與整個 monorepo 是單一套件一樣快速,同時保持套件邊界隔離。

tsconfig.json 中的 paths 選項透過啟用在開發期間解析到套件原始碼目錄的匯入別名,來補充專案參考。當 TypeScript 語言伺服器透過 paths 將 @design-system/components 追蹤到原始碼(而不是到已編譯的輸出)時,「跳轉到定義」導航和跨套件邊界的重新命名重構都能正確工作。在建置時,tsc --build 使用來自專案參考的已編譯宣告檔案;paths 映射僅用於開發體驗。理解這種區別——paths 用於語言伺服器,references 用於建置——是 monorepo TypeScript 設定的關鍵,其中編輯器體驗和建置輸出都是正確的。

最佳實踐 ​

必須(MUST)在每個專案的 tsconfig.json 中啟用 strict: true,且絕不以單獨啟用個別旗標的方式取代總括設定。 嚴格模式(strict mode)是 TypeScript 型別系統能捕捉其設計目標 bug 的最低門檻——null 解引用、隱式 any、函式參數變異性。為了讓錯誤消失而禁用特定檢查是一種累積的型別技術債:一旦團隊學到嚴格檢查可以被禁用,這個模式就會蔓延。每個被禁用的檢查都是編譯器將永久不再捕捉的一類 bug,只要該檢查持續被禁用。遷移遺留程式碼庫時,使用分階段的方法——在獨立設定中對新檔案啟用嚴格模式——而不是全域地禁用檢查。

必須(MUST)對於使用 Vite、webpack 或其他打包工具的專案將 moduleResolution 設定為 "bundler",對於直接在 Node.js 上執行的專案設定為 "node16" 或 "nodenext"。 傳統預設值 "node" 解析不理解 package.json 中的 exports 欄位,導致 TypeScript 與打包工具或執行環境的模組解析方式不同。這種不一致對於使用 exports 欄位的套件產生虛假的「模組找不到」錯誤,更危險的是,它導致 TypeScript 針對與打包工具實際載入的不同進入點進行型別檢查。由此產生的執行時 bug 在它之前沒有任何編譯器警告;編譯器和打包工具都回報成功,而使用中的型別與執行的程式碼不符。

應該(SHOULD)將 tsconfig.json 放在專案根目錄,並在 monorepo 的套件之間使用 extends 共享基礎設定。 共享基礎設定(tsconfig.base.json)在一個地方捕捉共同選項——strict、target、lib、moduleResolution。套件層級的設定擴展基礎設定並添加特定套件的選項,如 outDir、rootDir 和 paths。這防止了套件間的選項偏移(option drift):如果基礎設定是嚴格度和解析設定的權威來源,就沒有機會讓一個套件靜默地禁用所有其他套件都執行的檢查。當基礎設定更新時,所有套件在其下次建置時都會收到變更,保持整個 monorepo 的 TypeScript 行為一致。

應該(SHOULD)在 tsconfig.json 中使用 paths 定義匯入路徑別名(path aliases),並保持其與打包工具的別名設定同步。 像 @/components/Button 這樣的匯入別名必須在 tsconfig.json(讓 TypeScript 能解析匯入的型別)和打包工具設定(讓打包工具能在建置時解析模組)中都宣告。當這兩個設定不同步時——因為其中一個被更新而另一個沒有——TypeScript 接受匯入為型別安全的,而打包工具在建置時拒絕它。在 CI 中將兩個設定視為同時變更的單一單元,最好是驗證別名定義在兩個設定中的一致性,或從單一事實來源生成兩者,可以防止這類不一致在生產環境中出現。

視覺呈現 ​

以下圖表展示 TypeScript 匯入的模組解析決策樹,對比 "node"(傳統)解析與 "bundler"(現代)解析。關鍵分歧點是 exports 欄位的檢查:傳統解析完全跳過它,這導致了與使用條件式導出來為不同環境提供不同進入點的現代套件的不一致。

紅色路徑不是編譯錯誤——它是成功編譯但解析到錯誤的模組進入點。這就是為什麼在消費使用 exports 欄位的套件的現代專案中使用 moduleResolution: "node" 是危險的而不僅僅是不方便:編譯器不報告任何錯誤,而使用中的型別可能與打包工具實際載入的模組不符。黃色路徑表示解析成功但使用了可能未能反映套件在當前環境預期 API 的後備方案。

識別這類錯誤設定的實用診斷方法:如果專案使用 moduleResolution: "node" 並安裝了任何過去兩三年由活躍維護的函式庫發布的套件,請檢查該套件的 package.json 是否有 exports 欄位。如果該欄位存在,且套件中 TypeScript 的 types 或 typings 欄位指向的路徑與 exports 為 import 條件指定的路徑不同,那麼 TypeScript 就是在針對與打包工具不同的進入點進行解析。解決方法是將 moduleResolution 升級到 "bundler" 或 "node16"——而不是手動覆蓋套件的型別解析。

範例 ​

以下範例展示了一個真實的 monorepo 設定:一個共享基礎設定、一個函式庫套件設定,以及一個使用 Vite 的應用套件設定。這個結構啟用了嚴格型別檢查、正確的模組解析,以及透過專案參考實現的跨套件型別安全。

基礎設定位於 monorepo 根目錄,捕捉所有套件共享的選項。monorepo 中的每個套件都擴展這個檔案,這意味著在這裡更改 strict 或 moduleResolution 會傳播到每個地方:

json
// tsconfig.base.json(monorepo 根目錄)
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "lib": ["ES2022"],
    "moduleResolution": "bundler",
    "module": "ESNext",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true
  }
}

函式庫套件擴展基礎設定並添加特定套件的輸出設定。composite: true 旗標是專案參考運作的必要條件——它指示 TypeScript 在輸出旁產生宣告檔案,並儲存啟用增量建置的建置清單:

json
// packages/ui/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "paths": {
      "@ui/*": ["./src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

應用套件擴展基礎設定、參考函式庫套件,並添加特定應用的選項。references 陣列告訴 TypeScript 在對應用進行型別檢查時使用函式庫套件的預建宣告檔案:

json
// packages/app/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "paths": {
      "@ui/*": ["../ui/src/*"],
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
  "references": [
    { "path": "../ui" }
  ]
}

根目錄的 tsconfig 列舉所有套件作為參考。這使 tsc --build 能確定正確的編譯順序,並增量地編譯整個 monorepo:

json
// tsconfig.json(monorepo 根目錄)
{
  "files": [],
  "references": [
    { "path": "./packages/ui" },
    { "path": "./packages/app" }
  ]
}

對於 Vite 應用,打包工具設定必須反映 tsconfig.json 中定義的 paths 別名。這兩個設定是一個配對:TypeScript 使用 paths 進行型別解析;Vite 使用 alias 在建置時進行模組解析。當它們不一致時,專案進入一個 TypeScript 和 Vite 對匯入解析結果不一致的分裂狀態:

typescript
// packages/app/vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';
// ESM 環境中 __dirname 不可用;使用 import.meta.dirname(Node 20.11+ / Vite 5+)
const __dirname = import.meta.dirname;

export default defineConfig({
  resolve: {
    alias: {
      // 必須與 tsconfig.json paths 完全一致
      '@ui': path.resolve(__dirname, '../ui/src'),
      '@': path.resolve(__dirname, './src'),
    },
  },
});

應用中的 TypeScript 原始碼檔案從兩個別名匯入,由於別名定義是同步的,兩者在 TypeScript 和 Vite 中都正確解析:

typescript
// packages/app/src/features/Dashboard.tsx
import { Button } from '@ui/components/Button';   // 透過專案參考 + paths 別名解析
import { useTheme } from '@/hooks/useTheme';       // 透過本地 paths 別名解析

export function Dashboard() {
  const theme = useTheme();
  return (
    <div style={{ background: theme.background }}>
      <Button variant="primary">開始使用</Button>
    </div>
  );
}

對於不使用 monorepo 的單套件專案,tsconfig 更簡單,但同樣的兩個原則適用。Vite 專案需要 strict: true 和 moduleResolution: "bundler",並且應該將 target 和 lib 設定為反映它實際需要支援的環境。將 target 設定得更高(例如 "ES2022")意味著 TypeScript 不會降級現代語法如可選鏈(optional chaining)或空值合併(nullish coalescing),因為這些結構在目標環境中原生可用。設定 lib 控制 TypeScript 認為可用的瀏覽器和 DOM API;僅目標為 Node.js 的專案應使用不帶 DOM 型別的 "lib": ["ES2022"],而瀏覽器專案應使用 "lib": ["ES2022", "DOM", "DOM.Iterable"]。

為了說明嚴格模式能捕捉而非嚴格設定會遺漏的錯誤,考慮一個處理使用者輸入的函式。有了 strict: true,TypeScript 強制在使用可空輸入之前進行檢查:

typescript
// 有了 strict: true,TypeScript 在整個過程中強制 null 安全
function formatUserName(user: { firstName: string; lastName: string | null }): string {
  // 錯誤:物件可能是 'null' —— strictNullChecks 會捕捉這個
  // return `${user.firstName} ${user.lastName.trim()}`;

  // 正確:在存取之前檢查 null
  const last = user.lastName ? ` ${user.lastName.trim()}` : '';
  return `${user.firstName}${last}`;
}

// 有了 strict: true,TypeScript 捕捉參數中的隱式 any
function processItems(items) { // 錯誤:參數 'items' 隱含地具有 'any' 型別
  return items.map((item) => item.id); // item 也是 any —— 型別安全喪失
}

// 修正版本
function processItemsTyped(items: Array<{ id: string }>): string[] {
  return items.map((item) => item.id); // item.id 被正確地型別化為 string
}

以下範例展示了一個分階段嚴格模式遷移設定。當在現有專案中一次性啟用 strict: true 不可行時,為新程式碼提供獨立的 tsconfig 是一個遷移路徑。新檔案放置在 src/new/(或適合專案的模式)下,只由嚴格設定涵蓋。現有檔案在個別遷移之前繼續在舊版設定下編譯:

json
// tsconfig.strict.json —— 用於新程式碼
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  },
  "include": [
    "src/new/**/*",
    "src/utils/**/*"
  ]
}
json
// tsconfig.json —— 現有程式碼的舊版設定
{
  "compilerOptions": {
    "target": "ES2022",
    "moduleResolution": "bundler",
    "module": "ESNext",
    "strict": false,          // 遷移期間暫緩其餘嚴格旗標
    "noImplicitAny": true     // 全程保持此旗標啟用
  },
  "include": ["src/**/*"],
  "exclude": ["src/new/**/*", "src/utils/**/*"]
}

CI 同時執行 tsc --project tsconfig.strict.json --noEmit 和 tsc --project tsconfig.json --noEmit。新程式碼必須滿足嚴格設定;現有程式碼逐檔遷移,錯誤修復後將每個檔案從舊版 include 移至嚴格 include。當所有檔案都已遷移完成時,tsconfig.json 被刪除,tsconfig.strict.json 成為唯一的設定。

常見錯誤 ​

設定 strict: false 或單獨禁用特定嚴格旗標以讓錯誤消失是在推遲而不是解決型別技術債。strict: true 所浮現的錯誤不是誤報——它們識別了宣告型別與執行時行為不符的程式碼。禁用 strictNullChecks 以避免可空型別錯誤,意味著編譯器將不再標記 null 解引用,而這是 TypeScript 程式碼庫中最常見的執行時例外來源之一。這些錯誤從建置輸出中消失;bug 仍然留在程式碼中。這個錯誤在大型程式碼庫中特別具有破壞性,因為累積的型別技術債使得之後重新啟用嚴格模式越來越困難:每次重新啟用的檢查都會浮現一類自檢查被禁用以來一直在累積的潛在 bug,而且團隊現在必須審查和修復比從一開始就維持嚴格模式時更大得多的問題範圍。

在消費現代 ESM 套件的專案中使用 "module": "commonjs" 搭配 "moduleResolution": "node",會阻止 TypeScript 讀取這些套件 package.json 中的 exports 欄位。這種組合曾是 CommonJS 時代 Node.js 專案的標準設定,許多專案模板和教學仍然推薦它。在安裝依賴 exports 作為主要進入點的套件的現代專案中,這種組合導致 TypeScript 要麼完全找不到套件,要麼解析到一個不反映套件當前 API 的過時 main 欄位進入點。打包工具使用自己的解析邏輯並確實讀取 exports,載入正確的進入點;TypeScript 的型別來自不同的、較舊的進入點。由此產生的不一致——TypeScript 不報告錯誤,但使用中的型別與執行的程式碼不符——是最難診斷的 bug 類別之一,因為編譯器和打包工具都回報成功,而這種差異只有在執行時值的形狀與 TypeScript 宣稱的不符時才變得可見。

忘記同步 tsconfig.json 和打包工具設定之間的路徑別名(path aliases),會造成 TypeScript 和打包工具對匯入解析結果不一致的分裂狀態。當 tsconfig.json 定義 "@/components": ["./src/components"] 而 vite.config.ts 定義 '@': path.resolve(__dirname, './src') 時,兩個設定使用不同的別名粒度。對於簡單的匯入路徑,這些可能恰好產生相同的結果,但當別名定義真正不一致時——因為一個被更新而另一個沒有——TypeScript 接受打包工具在建置時拒絕的匯入,或反之亦然。這個錯誤很微妙,因為它只在設定變更後才浮現,而不是在專案首次設定時。在 CI 中加入一個驗證兩個設定中別名定義一致性的步驟——或者更好,從單一事實來源生成兩者——可以防止這類不一致在生產環境中出現。

相關 FEE ​

  • FEE-1700 — TypeScript 總覽
  • FEE-1705 — 宣告檔案與 DefinitelyTyped
  • FEE-800 — Build Tooling Overview

參考資料 ​