TypeScript 編譯與設定 — `compilerOptions.skipLibCheck`

簡介

在大型前端或 Node.js 專案中，TypeScript 的型別檢查是提升程式碼品質的重要工具。然而，當專案同時依賴多個第三方套件（尤其是那些帶有自己的 .d.ts 宣告檔）時，型別檢查的成本會顯著上升。
skipLibCheck 這個 tsconfig.json 的編譯選項，正是為了在 不影響開發者自訂程式碼的型別安全 前提下，減少編譯時間與不必要的型別衝突。

本文將深入說明 skipLibCheck 的作用機制、實作範例、常見陷阱以及在實務專案中的最佳使用方式，幫助你在 保持開發效率與型別正確性之間取得平衡。

核心概念

什麼是 `skipLibCheck`？

skipLibCheck（全名 skip type checking of declaration files）是一個布林值：

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

true：編譯器會 跳過所有 .d.ts 宣告檔（即「函式庫」的型別定義檔）的型別檢查。
false（預設）：編譯器會對每一個宣告檔進行完整的型別檢查。

為什麼要跳過？
大多數情況下，我們信任第三方套件的型別宣告已經正確；而檢查這些檔案往往只會消耗大量 CPU 時間，且容易因套件版本不一致而產生「無關」的錯誤訊息。

`skipLibCheck` 的運作流程

讀取 tsconfig.json，判斷 skipLibCheck 的值。
若為 true，編譯器在 建立型別檢查圖（type‑checking graph） 時，直接把所有外部 .d.ts 檔視為 已通過，不再遞迴檢查其內部結構。
仍會檢查 專案內部的 .ts / .tsx 檔案，以及 自訂的 .d.ts（若它們不在 node_modules/@types 路徑下）。

關鍵點：skipLibCheck 不會跳過 JSX、JS、或自訂型別 的檢查，只針對 外部宣告檔 生效。

程式碼範例

以下示範三個常見情境，說明 skipLibCheck 開啟與關閉的差異。

範例 1：基本 `tsconfig.json`

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "skipLibCheck": true,   // ← 讓編譯更快
    "esModuleInterop": true
  },
  "include": ["src"]
}

說明：開啟 skipLibCheck 後，即使 node_modules/@types/lodash 中有舊版型別衝突，編譯仍會順利通過。

範例 2：`skipLibCheck` 為 `false` 時的衝突

# 安裝兩個相依套件，其中一個帶有舊版 lodash 型別
npm i lodash@4.17.21 @types/lodash@4.14.168

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

const arr: number[] = _.range(5); // 正常使用 lodash.range

執行 tsc（skipLibCheck: false）會得到：

error TS2354: This syntax requires an imported helper but module 'lodash' cannot be found.

原因：@types/lodash 的型別檔與實際的 lodash 套件版本不匹配，導致型別檢查失敗。若將 skipLibCheck 設為 true，此錯誤會被忽略。

範例 3：自訂 `.d.ts` 不受 `skipLibCheck` 影響

// types/custom.d.ts
declare module "my-lib" {
  export function foo(bar: string): number;
}

// src/app.ts
import { foo } from "my-lib";

const result = foo(123); // ❌ 編譯錯誤：參數類型不符合

即使 skipLibCheck 為 true，自訂的宣告檔仍會被檢查，因此會得到：

error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

結論：skipLibCheck 只會「跳過」外部宣告檔的檢查，不會讓你的自訂型別失去保護。

範例 4：大型單頁應用（SPA）加速編譯

// tsconfig.prod.json (production build)
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "skipLibCheck": true,
    "sourceMap": false,
    "removeComments": true
  }
}

在 CI/CD 流程中使用此設定，可將 整個專案（含數百個第三方套件）的型別檢查時間 從 2 分鐘減少到 約 40 秒，而功能測試仍能捕捉自家程式碼的錯誤。

範例 5：與 `noEmitOnError` 結合使用

{
  "compilerOptions": {
    "skipLibCheck": true,
    "noEmitOnError": true   // 若自家程式碼出錯，仍不產出 JS
  }
}

這樣的組合保證了 即使跳過函式庫檢查，也不會因自家程式碼錯誤而產出不正確的 JavaScript。

常見陷阱與最佳實踐

陷阱	可能的後果	建議的解決方案
過度依賴 `skipLibCheck`，導致錯過第三方套件的型別 bug	在執行階段出現未預期的錯誤，尤其是新版套件的破壞性變更	僅在穩定的套件版本或已自行驗證的函式庫上使用；若套件頻繁更新，考慮暫時關閉此選項以確認型別相容性
在 monorepo 中只在根 `tsconfig.json` 開啟 `skipLibCheck`	子套件的型別檢查仍會被執行，造成編譯時間不一致	在每個子套件的 `tsconfig.json` 中明確設定 `skipLibCheck`，或使用 `references` 共享設定
與 `strict` 系列選項混用時誤以為已完全關閉檢查	仍會收到自訂程式碼的錯誤訊息，產生「設定失效」的錯覺	了解 `skipLibCheck` 只影響外部宣告檔，其他 `strict` 選項仍然有效
忘記將 `skipLibCheck` 設為 `false` 於 CI	本地開發快，但 CI 中因型別衝突失敗，導致部署無法通過	在 CI 中使用不同的 `tsconfig`（例如 `tsconfig.ci.json`）將 `skipLibCheck` 設為 `false`，確保所有型別衝突被捕捉

最佳實踐

先行測試：在本機開啟 skipLibCheck，確認編譯速度提升；之後在 CI 中關閉，觀測是否有新型別衝突產生。
版本鎖定：使用 package-lock.json 或 yarn.lock 鎖定第三方套件版本，減少因套件升級帶來的型別不相容。
搭配 typeRoots：若僅想跳過特定套件的檢查，可將該套件的型別檔移出 typeRoots，或自行建立 最小化的自訂宣告檔（只保留必要的型別）。
監控編譯時間：在 package.json 中加入 npm run build:time，使用 time tsc 觀測 skipLibCheck 前後的差異，作為是否保留的判斷依據。

實際應用場景

1. 大型企業前端單頁應用（SPA）

情境：專案使用 React + Ant Design + lodash，總共超過 150 個第三方套件。
挑戰：每次 npm install 後，tsc --noEmit 需要近 2 分鐘才能完成，影響 CI/CD 效率。
解決：在 tsconfig.prod.json 中開啟 skipLibCheck，將編譯時間縮短至 30 秒，同時在 單元測試 中加入 型別快照測試（tsd）確保關鍵套件的型別仍正確。

2. 多語言（Mono‑repo）後端服務

情境：Node.js 微服務共用一套 @types/node，但每個服務的 TypeScript 目標不同（ES2017、ES2020）。
挑戰：@types/node 裡的某些全域宣告在較舊的目標下會產生衝突。
解決：在根 tsconfig.json 開啟 skipLibCheck，同時在每個服務的 tsconfig.json 中加入 lib 陣列，只保留必要的 ECMAScript 標準，避免不必要的型別檢查。

3. 開發中快速原型（Prototype）

情境：開發者需要在 1 小時內驗證一個概念，使用大量的第三方 UI 套件。
挑戰：型別檢查的訊息過多，干擾開發流程。
解決：臨時在 tsconfig.json 設定 "skipLibCheck": true，等概念驗證完成後再恢復預設設定，確保正式程式碼仍受完整型別檢查。

總結

skipLibCheck 是 針對外部宣告檔 的型別檢查開關，能顯著縮短編譯時間、降低因套件版本不一致產生的噪音。
它不會減弱自家程式碼的型別安全，也不會影響 strict、noEmitOnError 等其他嚴格模式。
在 大型專案、CI/CD 高頻率建構 或 快速原型開發 時特別有用；但在 需要確保第三方型別正確（例如金融、醫療等高風險領域）時，建議暫時關閉或在 CI 中額外檢查。
透過 版本鎖定、分離設定檔、型別快照測試 等配套措施，可在保有開發效率的同時，仍維持對型別錯誤的警覺。

善用 skipLibCheck，讓 TypeScript 成為 快速、可靠且易於維護 的開發利器。祝你在 TypeScript 的世界裡寫出更乾淨、更安全的程式碼！

TypeScript 編譯與設定 — compilerOptions.skipLibCheck

簡介