TypeScript 設定
tsconfig.json 是你的原始碼與 TypeScript 編譯器之間的契約。它決定了編譯器將捕獲哪些類型錯誤、輸出針對什麼語法、模組如何解析,以及建置是否為增量模式。每個團隊都有一個——但大多數團隊把它當作樣板,從專案起始器複製過來後幾乎不再回頭檢視。
這種預設做法讓類型安全白白流失。TypeScript 預設不啟用 strict 旗標。noUncheckedIndexedAccess 可以防止對陣列和索引簽名的靜默 undefined 讀取,但它不在 strict 的範疇內。verbatimModuleSyntax 可以防止在僅轉譯的管線中出現 import/export 不匹配導致的運行時失敗,預設也是停用的。這些缺口不是晦澀的邊緣案例——而是編譯器本可捕獲卻沒有捕獲的整個錯誤類別。
現代 TypeScript 生態系也引入了兩年前還不存在的配置選項:moduleResolution: "Bundler"(TypeScript 5.0)正確地模擬了 Vite、esbuild 和其他打包工具解析模組的方式,取代了仍出現在大多數專案起始器中的舊版 "node" 設定。verbatimModuleSyntax 取代了舊版的 importsNotUsedAsValues 和 preserveValueImports 旗標,將類型 import 紀律整合成一個更清晰的單一選項。
配置不是一次性的設定任務,而是一份活的文件——當 TypeScript 編譯器新增了新的檢查、模組系統演進,以及專案的建置管線改變時,都必須更新它。2022 年正確的 tsconfig.json 在 2024 年可能靜默地遺漏了錯誤。
設計思維
strict 傘形結構,以及為何部分旗標不等同
TypeScript 的 --strict 旗標是啟用一組個別嚴格旗標的縮寫:strictNullChecks、strictFunctionTypes、strictBindCallApply、strictPropertyInitialization、noImplicitAny、noImplicitThis、alwaysStrict 和 useUnknownInCatchVariables。停用 strict 並手動啟用僅 strictNullChecks 的開發者認為他們已復製了嚴格模式的重要部分——但他們沒有。
個別旗標遺漏了兩件事。首先,strict 具有向前相容性:當 TypeScript 在未來版本中新增新的嚴格旗標時,它們會在 strict: true 下自動包含。手動列出個別旗標的專案將靜默地不接收新的檢查。其次,strict 包含旗標之間的交互,這些交互無法通過個別選項重新建立。正確的做法始終是從 strict: true 開始,然後在其上添加額外旗標——絕不要組裝一個臨時的個別嚴格選項集合。
無法立即修復所有嚴格錯誤的專案的遷移路徑是在特定行上使用 // @ts-ignore 或帶有解釋的 @ts-expect-error,而不是全局禁用 strict。一個有 strict: true 和 20 個被壓制錯誤的專案,比一個有 strict: false 的專案處於更好的狀態——那 20 個壓制是可見的、可追蹤的,並且可以增量解決。
target vs. lib vs. module:常見誤解
三個 tsconfig.json 欄位控制輸出,它們常常被混淆:
target— TypeScript 輸出的 JavaScript 語法版本。"ES2022"意味著 TypeScript 將輸出 ES2022 語法(箭頭函數、可選鏈等保持原樣;舊版語法會被降級)。它不意味著你可以使用 ES2022 API。lib— 為運行時環境包含的類型定義。lib中的"ES2022"意味著 TypeScript 知道Array.prototype.at()、Object.hasOwn()和其他 ES2022 API。沒有匹配的lib條目,TypeScript 會將這些報告為未知。module— 輸出的 JavaScript 的模組格式。"ESNext"輸出 ES module 語法(import/export)。"CommonJS"輸出require()/module.exports。
有 target: "ES2022" 但沒有 lib: ["ES2022"] 的專案在使用 Array.prototype.at() 時會看到錯誤,即使運行時支援它。有 lib: ["ES2022"] 但 target: "ES5" 的專案將有類型安全的 Array.prototype.at() 存取,但在 ES5 套件中輸出調用它的程式碼——如果沒有 polyfill 就是運行時錯誤。
實際上:對於使用現代打包工具的瀏覽器應用程式,設定 target: "ES2022"、lib: ["ES2022", "DOM", "DOM.Iterable"] 和 module: "ESNext"。讓打包工具通過自己的配置(例如 Vite 的 build.target 或 Babel 的 @babel/preset-env)處理到實際瀏覽器目標的轉譯。
路徑別名:類型檢查層 vs. 運行時解析
TypeScript 的 paths 欄位在類型檢查時將 import 別名映射到檔案路徑。當編譯器看到 import { Button } from '@/components/Button' 時,它在 paths 中查找 @/*,將其解析為 ['src/*'],並找到 src/components/Button.ts。Import 類型檢查通過。
但這些都不影響輸出的 JavaScript。編譯後的輸出仍然包含 import { Button } from '@/components/Button'——一個 Node.js 或瀏覽器不知道如何解析的裸指定符。打包工具也必須配置以解析同一別名。
這種雙層架構是一種隱匿錯誤類別的頻繁來源:TypeScript 編譯器通過,CI 通過,應用程式在運行時或打包時失敗,出現「Cannot find module '@/components/Button'」錯誤。修復方法是始終在兩個地方配置別名——並在 Vite 專案中使用 vite-tsconfig-paths,它自動讀取 tsconfig.json 的 paths 並將其應用於 Vite 的模組解析,消除了重複。
verbatimModuleSyntax 與僅轉譯管線
TypeScript 的傳統編譯模型在輸出前執行完整的類型檢查。僅轉譯工具(esbuild、SWC、Babel、Vite 的轉換管線)不這樣做——它們逐檔案機械式地剝離類型標註,沒有完整的程式分析。這為類型 import 創建了一個特定的失敗模式。
考慮以下情況:
import { UserRole } from './types'
const check = (role: UserRole) => role === 'admin'如果 UserRole 是類型(不是值),傳統的 TypeScript 編譯器在類型擦除期間會刪除這個 import。逐檔案剝離類型的僅轉譯工具可能會也可能不會刪除這個 import,取決於其實現——它可能會將 import { UserRole } from './types' 輸出到 JavaScript 中,創建一個在運行時對不作為值存在的符號的 import。
verbatimModuleSyntax 通過要求對僅類型 import 使用明確的 import type 語法來解決這個問題。編譯器錯誤立即且可見:「這個 import 從未用作值,必須使用 'import type',因為指定了 'verbatimModuleSyntax'。」開發者學習了這個區別,寫了 import type { UserRole } from './types',僅轉譯工具就有了明確的信號來剝離這個 import。
最佳實踐
必須(MUST)啟用 strict: true 以及三個額外的嚴格性旗標:noUncheckedIndexedAccess、exactOptionalPropertyTypes 和 noImplicitOverride。 這三個旗標不在 strict 傘形結構中,但能捕獲重要的錯誤類別。noUncheckedIndexedAccess 為所有陣列索引存取和索引簽名查找新增 | undefined,強制進行顯式的空值檢查。exactOptionalPropertyTypes 區分屬性設為 undefined 和屬性不存在,防止一類賦值錯誤。noImplicitOverride 要求覆寫基底類別方法的方法上有 override 關鍵字,防止基底類別方法被重命名時的靜默失敗。
必須(MUST)在任何使用僅轉譯建置工具的專案中啟用 verbatimModuleSyntax: true。 這個旗標要求僅類型 import 使用 import type,僅類型重新匯出使用 export type,給予轉譯器一個明確的信號,以便在不執行模組副作用的情況下剝離類型 import。從舊版 importsNotUsedAsValues: "error" 設定遷移的團隊必須(MUST)知道 verbatimModuleSyntax 是一個超集,還強制執行對僅類型重新匯出使用 export type;遷移是機械性的——執行 tsc,修復報告的錯誤,提交。
必須(MUST)使用 vite-tsconfig-paths 同步 tsconfig.json 和 Vite 之間的路徑別名,而不是手動重複。 在 resolve.alias 中手動重複別名製造了一個同步危險:在 tsconfig.json 中添加別名而不更新 vite.config.ts 會產生類型檢查成功和運行時失敗。vite-tsconfig-paths 外掛直接從 tsconfig.json 讀取別名,消除了這整類錯誤。
必須(MUST)以三層結構配置 TypeScript:tsconfig.base.json、tsconfig.json 和 tsconfig.test.json。 Base 檔案定義嚴格性、編譯器行為和模組系統設定,不含 include 或 exclude 項目,並在 monorepo 的所有套件間共享。應用程式設定繼承 base 並新增 baseUrl、paths 和應用程式源碼的 include。測試設定必須(MUST)繼承 base 而非應用程式設定,並在與應用程式路徑隔離的情況下新增測試框架類型和測試檔案模式。
應該(SHOULD)在有多個 TypeScript 套件的 monorepo 中使用帶有 composite: true 和 declarationMap: true 的 project references。 Project references 允許 tsc --build 使用專案圖只重新建置已更改的套件及其依賴項,並在建置消費端應用程式時呈現函式庫套件中的類型錯誤。declarationMap: true 使「跳轉到定義」導航到源文件而不是 .d.ts 聲明——在套件與使用它的應用程式並行開發的 monorepo 中,這對開發者體驗至關重要。
視覺呈現
tsconfig 繼承鏈
以下圖表顯示三層 tsconfig 繼承鏈的結構,以及每層貢獻的內容。
範例
完整的 tsconfig 設定
以下範例展示了 Vite + Vitest 應用程式的完整、可投入生產的 tsconfig 設定。
// tsconfig.base.json
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"noImplicitOverride": true,
"verbatimModuleSyntax": true,
"target": "ES2022",
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"module": "ESNext",
"moduleResolution": "Bundler",
"skipLibCheck": true,
"noEmit": true,
"resolveJsonModule": true,
// isolatedModules 已省略:verbatimModuleSyntax 涵蓋其所有限制,TypeScript 5.5+ 已棄用 isolatedModules
"jsx": "react-jsx"
}
}注意:moduleResolution: "Bundler" 在 TypeScript 5.0 中引入。它正確地模擬了 Vite、esbuild 和其他打包工具使用的模組解析演算法——它們支援 index 檔案、省略副檔名,以及 package.json 中的 exports 欄位,而舊版的 "node" 設定無法準確模擬這些。
// tsconfig.json(應用程式配置,供編輯器和 tsc 使用)
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@components/*": ["src/components/*"],
"@lib/*": ["src/lib/*"]
}
},
"include": ["src/**/*", "vite.config.ts"]
}// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'
export default defineConfig({
plugins: [
react(),
tsconfigPaths(), // 自動從 tsconfig.json 讀取 paths
],
build: {
target: 'es2022',
},
})// tsconfig.test.json(測試配置,供 Vitest 使用)
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"types": ["vitest/globals"]
},
"include": [
"src/**/*.test.ts",
"src/**/*.test.tsx",
"src/**/*.spec.ts",
"src/**/*.spec.tsx"
]
}配置 Vitest 並加入 vite-tsconfig-paths,讓 tsconfig.json 中的路徑別名在測試中也能解析。Vitest 會自動找到最近的 tsconfig.json——不需要在設定中加入 tsconfig 鍵:
// vitest.config.ts
import { defineConfig } from "vitest/config";
import tsconfigPaths from "vite-tsconfig-paths";
export default defineConfig({
plugins: [tsconfigPaths()],
test: {
globals: true,
environment: "jsdom",
},
});在程式碼中使用配置
啟用 noUncheckedIndexedAccess 後,陣列索引存取現在返回 T | undefined:
// src/lib/users.ts
import type { User } from '@/types' // verbatimModuleSyntax 要求使用 import type
const users: User[] = fetchUsers()
// 沒有 undefined 保護的 TypeScript 錯誤:
// const name = users[0].name — Object is possibly 'undefined'
const first = users[0]
if (first !== undefined) {
console.log(first.name) // 安全:first 在這裡是 User
}
// 或使用可選鏈:
const name = users[0]?.name // string | undefined啟用 exactOptionalPropertyTypes 後,可選屬性賦值更嚴格:
interface Config {
timeout?: number // 可以不存在,但不能顯式為 undefined
}
// 使用 exactOptionalPropertyTypes 會出錯:
// const cfg: Config = { timeout: undefined }
// 正確:
const cfg1: Config = {} // 屬性不存在——OK
const cfg2: Config = { timeout: 5000 } // 屬性存在——OK
// 如果你需要允許顯式 undefined:
interface Config2 {
timeout?: number | undefined // 明確允許 undefined 賦值
}常見錯誤
ts-node 未設定 esm: true
在設定了 "module": "ESNext" 的專案中直接使用 ts-node 執行 TypeScript 檔案,即使 tsc 回報無錯誤,在執行期也會出現 SyntaxError: Cannot use import statement in a module。解決方法是在 tsconfig.json 中加入 ts-node 設定:
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "Bundler"
},
"ts-node": {
"esm": true,
"experimentalSpecifierResolution": "node"
}
}注意:
experimentalSpecifierResolution已在 Node.js 21 中移除。在 Node.js 21+ 環境下,建議改用tsx(見下方),或在package.json中設定"type": "module"。
或者改用 tsx(以 esbuild 為底層的 ts-node 替代品),無需額外設定即可處理 ESM 專案。
相關 FEE
- FEE-1600:開發者體驗與工具概覽 — 分類背景:TypeScript 設定是 DX 生命週期中類型安全層的基礎
- FEE-1601:程式碼檢查與靜態分析 — 類型感知的 ESLint 規則(
@typescript-eslint/recommended-type-checked)需要配置了project路徑的tsconfig.json;嚴格的 tsconfig 產生更準確的 lint 結果 - FEE-803:轉譯 — esbuild、SWC 和 Babel 是僅轉譯工具,不進行類型檢查就剝離 TypeScript;
verbatimModuleSyntax和isolatedModules是將 TypeScript 模型與轉譯器行為對齊的 tsconfig 旗標 - FEE-805:Monorepo 工具 — 帶有
composite: true的 project references 是 TypeScript 原生的方法,用於 monorepo 中的增量建置和跨套件類型檢查