TypeScript – 型別宣告與整合

第三方套件型別錯誤處理（moduleResolution）

---

簡介

在使用 TypeScript 開發大型前端或 Node.js 專案時，第三方套件的型別資訊往往是影響開發體驗與程式安全性的關鍵。
即使套件本身已經提供了 *.d.ts 定義檔，或是社群維護的 @types 套件，仍然會因為 模組解析（moduleResolution） 的設定不當，導致編譯器找不到型別或產生衝突錯誤。

本篇文章將說明：

1. moduleResolution 的兩種主要模式 (node、classic) 與它們的差異。
2. 為什麼第三方套件會出現型別錯誤，以及常見的根源。
3. 實務上如何透過 tsconfig.json、路徑映射（paths）與自訂型別宣告，解決或避免 這類問題。

適合 初學者到中級開發者，讓你在導入或升級套件時，能快速定位型別錯誤，保持編譯順暢。

---

核心概念

1. moduleResolution 基本原理

TypeScript 需要把 匯入語句 (import … from …) 轉換成實際的檔案路徑，才能載入相對應的型別資訊。
moduleResolution 告訴編譯器要採用哪套解析規則，主要有兩種：

模式	主要特性	典型使用情境
node	依照 Node.js 的模組解析規則（node_modules、package.json 的 main、exports）	現代前端框架、Node.js 專案
classic	早期 TypeScript 的自訂規則，只支援相對路徑與非 Node 風格的檔案結構	老舊專案或特定教學環境

⚠️ 重點：大多數新專案應該使用 node，除非有特殊需求才切換到 classic。

1.1 tsconfig.json 設定範例

{
  "compilerOptions": {
    "moduleResolution": "node",   // ← 這裡指定解析模式
    "baseUrl": "./src",           // 路徑基礎目錄，配合 paths 使用
    "paths": {
      "@utils/*": ["utils/*"]     // 別名映射，讓 import 更簡潔
    },
    "strict": true,
    "esModuleInterop": true
  }
}

小技巧：若專案中同時使用 CommonJS 與 ES Module，esModuleInterop 可以減少 default 匯入的型別衝突。

---

2. 為什麼會出現「找不到型別」的錯誤？

2.1 缺少 @types 套件

許多純 JavaScript 套件（如 lodash、moment）在 npm 上只有執行檔，沒有內建型別。
如果沒有安裝對應的 @types，編譯器會顯示：

Cannot find module 'lodash' or its corresponding type declarations.

2.2 型別檔位置不在解析範圍

即使安裝了 @types，若 tsconfig.json 的 typeRoots、baseUrl、paths 設定不當，也會讓編譯器忽略這些檔案。

2.3 套件的 package.json 沒有正確導出型別

某些套件在 package.json 中使用 types 或 typings 欄位指向型別檔，但路徑寫錯或檔案遺失，會產生 型別找不到 的錯誤。

2.4 多版本衝突

在 monorepo 或使用 npm link 時，可能同時存在兩個不同版本的同一套件，導致型別檔不一致，編譯器會報出 duplicate identifier 或 type incompatibility。

---

3. 解決方案與實作範例

以下示範 5 個常見情境，從最簡單的安裝型別套件，到自訂型別宣告與路徑映射，完整解決第三方套件的型別錯誤。

3.1 安裝官方或社群提供的型別套件

# 以 lodash 為例
npm install lodash
npm install -D @types/lodash   # 安裝型別定義

// src/example1.ts
import _ from "lodash";

const arr = [1, 2, 3, 4];
const evens = _.filter(arr, n => n % 2 === 0); // ✅ 正確的型別推斷

說明：安裝完 @types/lodash 後，編譯器即能讀取 node_modules/@types/lodash/index.d.ts，提供完整的函式簽名與泛型支援。

3.2 使用 paths 別名解決深層路徑與型別衝突

假設專案結構：

src/
  components/
    Button/
      index.ts
      Button.d.ts   // 手寫型別檔

tsconfig.json：

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"]
    }
  }
}

使用方式：

// src/pages/home.ts
import Button from "@components/Button";

Button.render(); // ✅ 會自動取得 Button.d.ts 的型別

技巧：別名同時適用於 程式碼 與 型別檔，只要 paths 正確，moduleResolution 為 node 時即可順利解析。

3.3 手動撰寫型別宣告（declare module）

當套件沒有型別檔且找不到對應的 @types，可以自行建立 全域宣告檔（如 src/types/custom.d.ts）：

// src/types/custom.d.ts
declare module "my-legacy-lib" {
  export function init(config: { apiKey: string }): void;
  export const version: string;
}

// src/main.ts
import { init, version } from "my-legacy-lib";

init({ apiKey: "12345" });
console.log(version);

注意：declare module 必須放在 全域型別檔 中（include 或 files 欄位需包含），否則編譯器不會載入。

3.4 調整 typeRoots 與 types 讓型別檔只被限定範圍載入

若專案同時使用多個第三方型別套件，且不希望全部自動載入（避免衝突），可以這樣設定：

{
  "compilerOptions": {
    "typeRoots": ["./src/types", "./node_modules/@types"], // 只搜尋這兩個目錄
    "types": ["node", "lodash"] // 明確列出要載入的套件型別
  }
}

這樣即使 @types/express 也安裝在 node_modules/@types，只要不在 types 陣列裡，就不會被編譯器載入，減少不必要的型別衝突。

3.5 針對 monorepo 多版本衝突的解決方案

在 monorepo 中，各子套件可能依賴不同版本的 react，導致型別不相容。解法之一是 使用 pnpm 的 hoist 或 在根目錄設定 resolutions，確保所有子套件使用相同的版本：

// package.json (根目錄)
{
  "workspaces": ["packages/*"],
  "resolutions": {
    "react": "18.2.0",
    "@types/react": "18.0.28"
  }
}

同時在 tsconfig.json 加上 paths 強制指向單一版本：

{
  "compilerOptions": {
    "paths": {
      "react": ["./node_modules/react"],
      "@types/react": ["./node_modules/@types/react"]
    }
  }
}

結果：所有子套件在編譯時都會解析到同一個 react 型別，避免 Duplicate identifier 'Component' 等衝突。

---

常見陷阱與最佳實踐

陷阱	說明	解法
忘記安裝 @types	編譯時找不到型別，卻以為套件本身已支援	安裝 npm i -D @types/xxx，或自行 declare module
moduleResolution 設為 classic	只能解析相對路徑，第三方套件會失效	改為 node（除非有特殊需求）
paths 與實際檔案不對應	別名映射錯誤，導致編譯器找不到檔案	檢查 baseUrl、paths 的相對位置，使用 tsc --traceResolution 觀察解析過程
型別檔與套件版本不匹配	@types 版本低於套件本身，型別缺失或錯誤	鎖定 @types 版本與套件相同的主版本號
全域型別檔未被 include	declare module 不會被編譯器載入	在 tsconfig.json 中加入 "include": ["src/**/*.ts", "src/types/**/*.d.ts"]

最佳實踐 Checklist

1. 檢查 moduleResolution：預設使用 node，除非有舊專案需求。
2. 確保 @types：對每個純 JS 套件，都先搜尋 @types，若無則自行宣告。
3. 使用 paths 別名：提升匯入可讀性，同時避免相對路徑錯誤。
4. 限定型別範圍：透過 typeRoots、types 控制載入的型別，降低衝突機率。
5. CI 檢查：在 CI pipeline 加入 tsc --noEmit，確保型別錯誤在合併前被捕捉。

---

實際應用場景

場景 1：引入第三方 UI 套件（如 antd）時的型別衝突

antd 自身提供型別，但如果同時安裝了舊版的 @types/react，會出現 Property 'children' does not exist on type 'IntrinsicAttributes'。
解法：升級 @types/react 至與 react 同版，或在 tsconfig.json 明確設定 types: ["react", "react-dom", "antd"]。

場景 2：在 Node.js 後端使用 dotenv（無型別）與自訂 config 模組

npm i dotenv
npm i -D @types/dotenv

// src/config/index.ts
import * as dotenv from "dotenv";

dotenv.config(); // ✅ 取得環境變數型別提示

export const DB_URL = process.env.DB_URL as string;

如果忘記安裝 @types/dotenv，編譯會直接報錯，導致部署失敗。提前安裝型別 可以在開發階段即捕捉錯誤。

場景 3：Monorepo 中共享工具函式庫

在 packages/utils 中提供 formatDate，其他套件透過別名 @utils 匯入：

// packages/utils/tsconfig.json
{
  "compilerOptions": {
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

根目錄 tsconfig.json：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@utils/*": ["packages/utils/src/*"]
    }
  }
}

這樣一旦 formatDate 的簽名變更，所有使用者會立刻在編譯時收到錯誤提示，確保 API 變更的可追蹤性。

---

總結

• moduleResolution 是 TypeScript 能否正確載入第三方套件型別的核心設定，絕大多數情況應使用 node。
• 第三方套件的型別錯誤往往來自 缺少 @types、路徑映射錯誤、版本不匹配 或 多版本衝突，只要針對這些根源逐一檢查，即可快速定位問題。
• 透過 paths 別名、typeRoots/types 限制範圍、手寫 declare module，可以在不改變原始套件的情況下，為專案提供穩定且可維護的型別支援。
• 最佳實踐：在專案初始化時即設定 moduleResolution: "node"、安裝必要的 @types、建立全域型別檔、並在 CI 中加入型別檢查，能大幅降低日後因型別錯誤導致的部署失敗或維護成本。

掌握上述概念與技巧後，你將能在 任何第三方套件 中自信地使用 TypeScript，讓開發流程更順暢、程式碼更安全。祝你寫程式快快樂樂，型別錯誤說走就走！ 🚀