TypeScript的常用配置详解

TypeScript 配置文件（tsconfig.json）是 TypeScript 项目的核心控制文件，tsconfig.json的作用是告诉TypeScript编译器如何编译项目中的TypeScript文件。它可以定义编译规则（如目标版本、模块类型等）和文件范围（包含/排除的文件路径）‌，以下是其关键配置项的详细解析：

1.创建 TypeScript 的配置文件 tsconfig.json 

1：通过命令行生成（推荐） 

npm install -g typescript  # 全局安装
# 或
npm install typescript --save-dev  # 本地安装

//在项目根目录运行初始化命令
tsc --init

此时会在当前目录自动生成 tsconfig.json 文件，包含默认配置 

2：手动创建

1. ‌在项目根目录新建文件‌
   手动创建文件并命名为 tsconfig.json。

2. ‌填写基础配置

{
  "compilerOptions": {
    // 基础配置示例
    "target": "ES6",
    "module": "CommonJS",
    "strict": true,
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

验证配置文件是否生效

1. ‌运行编译命令‌：

   tsc # 编译所有 TypeScript 文件

2. ‌检查输出‌
   编译后的文件会出现在 outDir 指定的目录（如 dist/）。

2. 文件结构

tsconfig.json 的基本结构如下：

{
  "compilerOptions": {
    /* 配置选项 */
  },
  "vueCompilerOptions":{
    /* Vue 特定配置）*/
   },
    "watchOptions": {
     /* ：仅在 TypeScript 持续编译模式（tsc --watch）中生效，配置文件监视的行为。*/

     },//监控选项
    "typeAcquisition":{
      /* 类型获取 */

      }
 
  "include": ["**/*.ts"],// 显式包含需要编译的文件或目录包括业务文件和类型声明文件（支持通配符 **）

  "exclude": ["node_modules"], // 排除不需要编译的文件（通常配合 include 使用）
  "files": ["file1.ts", "file2.ts"]  //显式列出需要编译的文件（不推荐，除非项目很小）,优先级比include高,
   "extends":{
      /* 继承其他配置文件*/
      },
     "references":{
      /* 项目间引用配置*/
     }
}

1. 核心配置项 (compilerOptions)

基础配置

选项	描述	可选值	默认值	示例值
target	指定编译后的 JavaScript 版本 ECMAScript	(ES3/ES5/ES2015/ES2016/ES2020/ESNext) ESNext 表示会使用最新的 ECMAScript 标准特性	"ES3"	"ES2015"
module	指定编译后的模块类型	(commonjs、es2015、esnext、umd、system等)	"commonjs"	"ES2015"
outDir	生成编译后文件的目录		"./"	"dist"
rootDir	指定源码根目录（需与 outDir 配合，避免输出目录混乱）		"src"	"src"

类型检查 

strict	启用所有严格类型检查（等价于 strictNullChecks + strictFunctionTypes 等）	false	true
strictNullChecks	禁用 null 和 undefined 的隐式分配	false	true
noImplicitAny	禁止隐式 any 类型	false	true
noImplicitReturns	要求所有函数路径都有返回值	false	true
noUnusedLocals	报告未使用的局部变量	false	true
noUnusedParameters	报告未使用的参数	false	true

模块和模块解析

选项	描述	默认值	示例值
moduleResolution	模块解析策略 (node 或 nodenext)， 设置为 Node 表示会按照 Node.js 的模块解析策略来查找和加载模块。这意味着它会先在当前目录下查找 node_modules 文件夹中的模块，然后按照一定层级向上查找，类似于 Node.js 运行环境中 require 函数查找模块的方式（但这里针对的是使用 import 等模块语法的情况）	"node"	"nodenext"（用于 ESM）
baseUrl	模块解析的基路径，用于相对模块路径 (配合 paths)	"./"	"src"
paths	配置路径别名（需要配合 baseUrl）	{}	"@/*": ["src/*"]
esModuleInterop	允许导入 CommonJS 模块作为 ES6 模块	false	true（推荐）
allowSyntheticDefaultImports	允许从 CommonJS 模块默认导入 (import React from 'react')	false	true

 输出控制

选项	描述	默认值	示例值
declaration	生成 .d.ts 类型定义文件	false	true
sourceMap	生成 source map 文件	false	true
removeComments	移除 TypeScript 代码中的注释	false	true
moduleSuffix	指定模块后缀，如 .js 或 .mjs	.js	.mjs

 JSX 相关

选项	描述	可选值	默认值	示例值
jsx	指定 JSX 的编译模式	(react、preserve、react-jsx 等)"preserve" 保留 JSX 以供其他工具处理，"react" 编译为 React.createElement 调用，"react-jsx" 和 "react-jsxdev" 针对 React 17 及以后	"react"	"react-jsx"
jsxFactory	指定 JSX 的 factory 函数 (如 h 或 jsx)		"React.createElement"	"h"
jsxFragmentFactory	指定 JSX Fragment 的 factory 函数		"React.Fragment"	"Fragment"

 其他

选项	描述	默认值	示例值
lib	指定要包含的库文件（如 DOM、ES2015）	根据 target 自动推断	["ES2020", "DOM"]
incremental	启用增量编译，加快后续编译速度	false	true
downlevelIteration	在 target 低于 ES6 时，启用迭代器 (for...of)	false	true

 2.watchOptions

仅在 TypeScript 持续编译模式（tsc --watch）中生效，配置文件监视的行为 

子选项	描述	默认值	示例值
poll	使用轮询方式监视文件变化（替代系统事件监听），适用于旧系统或不可靠的文件系统	false 或 "deprecated"	1000（每秒轮询一次）
fallbackPolling	在默认 poll 不可用时的轮询频率（如某些文件系统）	500 ms	2000
ignoreWatch	忽略监视文件夹（必须是绝对路径或相对于 rootDir 的路径）	[]	["/path/to/folder"]
drop	忽略文件系统事件，仅触发重新编译（适合移动/重命名文件后需强制重新扫描）	false	true
excludeDirectories	排除某些目录的监视（相对路径或绝对路径）	[]	["node_modules", "di

3. typeAcquisition：类型自动获取配置

控制 TypeScript 是否自动下载或发现项目中使用的第三方库的类型定义（如 @types/node）。

子选项	描述	默认值	示例值
enable	是否启用自动下载类型定义	true	false（禁用自动下载）
include	指定需要自动安装的包名称（例如 "lodash"、"react"）	[]	["axios", "express"]
exclude	排除不需要自动安装的包名称	[]	["marked"]

4. references: 项目引用配置（Project References）

用于大型项目拆分，通过项目间引用实现 增量编译，提高编译速度。

用于引用其他的 tsconfig.json 文件，这里表示当前的 tsconfig.json 文件会引用配置目录下的的 tsconfig.app.json 和 tsconfig.node.json 这两个配置文件

子选项	描述	默认值	示例值
enable	是否启用自动下载类型定义	true	false（禁用自动下载）
include	指定需要自动安装的包名称（例如 "lodash"、"react"）	[]	["axios", "express"]
exclude	排除不需要自动安装的包名称	[]	["marked"]