一、前言

在開發(fā) TypeScript 項目時，一個非常關鍵的文件就是 tsconfig.json。它不僅定義了項目的根目錄、模塊解析方式，還控制著 TypeScript 編譯器的行為。

本文將帶你全面了解：

• ? tsconfig.json 的作用
• ? 常用編譯選項（compilerOptions）詳解
• ? 不同環(huán)境下的配置建議（開發(fā) / 生產(chǎn)）
• ? 配置繼承與共享設置
• ? 實際開發(fā)中的常見問題與解決方法

并通過完整的代碼示例幫助你掌握如何正確配置 TypeScript 項目。

二、什么是tsconfig.json？

定義：

tsconfig.json 是 TypeScript 項目的配置文件，用于指定項目的編譯選項和行為。

當你在項目根目錄下添加該文件后，TypeScript 編譯器會自動識別并應用這些配置。

作用：

• 指定編譯目標（ES 版本、模塊系統(tǒng)等）
• 控制類型檢查嚴格程度
• 設置輸出目錄
• 支持路徑別名、裝飾器等功能

三、基本結構示例

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    },
    "sourceMap": true,
    "declaration": false,
    "removeComments": true,
    "noEmit": false,
    "watch": false
  },
  "include": ["src/**/*"]
}

四、常用編譯選項詳解

1.target：指定編譯目標版本

"target": "ES2020"

常見值：

• "ES3"（默認）
• "ES5"
• "ES2015"（ES6）
• "ES2020"
• "ESNext"

2.module：指定模塊系統(tǒng)

"module": "ESNext"

常見值：

• "CommonJS"（Node.js 默認）
• "ESNext"（推薦用于現(xiàn)代瀏覽器）
• "UMD"、"AMD" 等

3.lib：指定編譯過程中使用的庫

"lib": ["ES2020", "DOM"]

示例組合：

• 瀏覽器環(huán)境：["ES2020", "DOM"]
• Node.js 環(huán)境：["ES2020", "ES2021.Promise", "ES2021.String"]

4.strict：啟用所有嚴格類型檢查選項

"strict": true

包含以下子選項（開啟后不可單獨關閉）：

• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• strictPropertyInitialization
• noImplicitThis
• alwaysStrict

5.moduleResolution：模塊解析策略

"moduleResolution": "node"

常見值：

• "classic"（舊版）
• "node"（推薦用于 Node.js 或 Webpack 項目）

6.esModuleInterop：允許 CommonJS 和 ES 模塊互操作

"esModuleInterop": true

推薦開啟，避免導入時出現(xiàn) .default 問題。

7.skipLibCheck：跳過類型聲明文件的檢查

"skipLibCheck": true

推薦開啟以加快編譯速度。

8.outDir：指定輸出目錄

"outDir": "./dist"

9.rootDir：指定源碼目錄

"rootDir": "./src"

10.baseUrl與paths：配置路徑別名

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

使用方式：

import utils from '@/utils/index';

11.sourceMap：生成 source map 文件

"sourceMap": true

用于調(diào)試，生產(chǎn)環(huán)境可設為 false。

12.declaration：是否生成.d.ts類型聲明文件

"declaration": true

適用于庫項目，方便別人使用你的包。

13.removeComments：是否移除注釋

"removeComments": true

14.noEmit：是否生成編譯后的文件

"noEmit": false

開發(fā)階段可設為 true，只進行類型檢查。

15.watch：監(jiān)聽文件變化并重新編譯

"watch": true

五、不同環(huán)境的配置建議

六、配置繼承與復用

你可以通過 extends 屬性繼承其他配置文件，便于多個項目共用配置。

{
  "extends": "@myorg/tsconfig-base",
  "compilerOptions": {
    "outDir": "./dist"
  }
}

常見基礎配置包：

• @tsconfig/recommended
• @tsconfig/node18
• 自定義 npm 包（如團隊內(nèi)部統(tǒng)一配置）

七、常見問題與解決方案

八、總結對比表：常用 compilerOptions 對比

九、總結

以上為個人經(jīng)驗，希望能給大家一個參考，也希望大家多多支持腳本之家。

最新評論