tsconfig.json 配置详解

tsconfig.json 配置全解析（兼容低版本浏览器版）

tsconfig.json 是 TypeScript 项目的核心配置文件，用于定义编译器的编译规则、目标环境、代码检查等核心逻辑。**若需兼容低版本浏览器，务必将 target 配置为 "es5"**，以下按功能模块整理完整配置项，兼顾可读性与实用性：

一、核心编译器选项（compilerOptions）

1. 基础编译配置（Basic Options）

控制编译输出的基础行为，是适配运行环境的核心配置。

配置项	取值/示例	核心说明
target	es5（必选）、es3/es2015/esnext等	指定编译后的JS版本，兼容低版本浏览器必须设为es5
module	commonjs/amd/system/umd/es2015等	指定模块系统规范（Node.js环境常用commonjs）
lib	[“es6”, “dom”]	指定编译时依赖的库文件（如ES6语法、DOM API）
allowJs	true/false	是否允许编译JS文件（默认false）
checkJs	true/false	是否检查JS文件中的语法错误（默认false）
jsx	preserve/react/react-native	指定JSX语法的编译目标（适配Vue/React）
declaration	true/false	是否生成.d.ts类型声明文件（与allowJs互斥）
declarationMap	true/false	是否为.d.ts文件生成SourceMap（便于调试）
sourceMap	true/false	是否生成.map映射文件（关联TS源码与编译后JS）
outFile	“./dist/main.js”	将所有编译结果合并为单个文件（仅支持amd/system模块）
outDir	“./dist”	指定编译后文件的输出目录
rootDir	“./src”	指定编译的根目录（编译器会校验根目录文件完整性）
composite	true/false	是否编译构建引用的子项目（多项目工程用）
incremental	true/false	启用增量编译（提升二次编译速度）
tsBuildInfoFile	“./tsconfig.tsbuildinfo”	存储增量编译缓存信息的文件路径
removeComments	true/false	是否删除编译后JS文件的注释（默认false）
noEmit	true/false	仅做类型检查，不生成编译文件（默认false）
importHelpers	true/false	引入tslib辅助函数（减少编译后代码冗余）
downlevelIteration	true/false	为ES5/ES3环境完整支持for-of、解构等迭代器特性
isolatedModules	true/false	将每个文件视为独立模块（与declaration互斥，默认true）

2. 严格类型检查（Strict Type-Checking Options）

开启后强制严格的类型校验，大幅减少隐式类型错误，生产环境推荐全开启。

配置项	取值	核心说明
strict	true/false	一键开启所有严格检查（开启后以下项均生效，默认false）
noImplicitAny	true/false	禁止变量隐式为any类型（未指定类型则报错）
strictNullChecks	true/false	严格校验null/undefined（不能赋值给非空类型）
strictFunctionTypes	true/false	启用函数参数的双向协变检查（严格校验函数类型）
strictBindCallApply	true/false	严格校验bind/call/apply的参数类型
strictPropertyInitialization	true/false	检查类的非undefined属性是否在构造函数初始化（需配合strictNullChecks）
noImplicitThis	true/false	禁止this隐式为any类型（报错提示）
alwaysStrict	true/false	强制严格模式编译，生成的JS文件添加"use strict"

3. 额外代码质量检查（Additional Checks）

补充校验逻辑错误，提前发现潜在问题。

配置项	取值	核心说明
noUnusedLocals	true/false	检查未使用的局部变量（默认false）
noUnusedParameters	true/false	检查函数中未使用的参数（默认false）
noImplicitReturns	true/false	检查函数是否有遗漏的返回路径（默认false）
noFallthroughCasesInSwitch	true/false	检查switch-case是否遗漏break（默认false）

4. 模块解析配置（Module Resolution Options）

控制模块导入/查找规则，适配不同工程结构。

配置项	取值/示例	核心说明
moduleResolution	node/classic	模块解析策略（Node.js环境用node，默认值）
baseUrl	“./src”	解析非相对模块的基础目录（如import "utils" → 从src查找）
paths	{“@/“: [“./src/“]}	模块路径别名（需配合baseUrl，如@/utils映射src/utils）
rootDirs	[“./src”, “./assets”]	将多个目录视为统一根目录（编译时合并内容）
typeRoots	[“./typings”, “./node_modules/@types”]	指定声明文件的查找目录
types	[“node”, “vue”]	仅加载指定模块的声明文件（默认加载所有typeRoots下的文件）
allowSyntheticDefaultImports	true/false	允许从无默认导出的模块中默认导入（如import React from "react"）
esModuleInterop	true/false	实现CommonJS与ES模块互操作性（解决导入兼容问题）
preserveSymlinks	true/false	不解析符号链接的真实路径（适配webpack/node symlink）

5. Source Map 配置（Source Map Options）

控制调试用的映射文件生成规则。

配置项	取值	核心说明
sourceRoot	“”	指定调试器查找TS源码的路径（写入.map文件）
mapRoot	“”	指定调试器查找.map文件的根路径
inlineSourceMap	true/false	将SourceMap内容内嵌到JS文件（而非单独生成.map）
inlineSources	true/false	将TS源码内容内嵌到JS文件（配合inlineSourceMap）

6. 实验性选项（Experimental Options）

启用TypeScript实验性特性（需谨慎使用）。

配置项	取值	核心说明
experimentalDecorators	true/false	启用装饰器特性（如Vue/Angular装饰器）
emitDecoratorMetadata	true/false	为装饰器提供元数据支持（需配合Reflect API）

二、项目文件管控（根级别配置）

控制编译器需要编译/排除的文件范围，及项目关联规则。

配置项	取值/示例	核心说明
files	[“./src/index.ts”]	指定编译的文件列表（仅支持具体文件，无通配符）
include	[“./src/**/*”]	指定编译的文件/目录（支持通配符，如src下所有文件）
exclude	[“./node_modules”, “./dist”]	排除不编译的文件/目录（默认排除node_modules）
extends	“./base-tsconfig.json”	继承其他tsconfig.json的配置（覆盖当前同名配置）
compileOnSave	true/false	保存文件时自动编译（需VSCode等编辑器支持）
references	[{“path”: “./sub-project”}]	指定引用的子项目（多项目工程用）

总结

1. 兼容低版本浏览器的核心：target 必须设为 "es5"，配合downlevelIteration 完善ES5环境的迭代器支持；
2. 生产环境建议开启strict: true 全量严格检查，避免隐式类型错误；
3. 模块解析优先用moduleResolution: "node"，配合baseUrl+paths 配置路径别名，提升工程化效率；
4. include/exclude 需精准管控编译范围，避免编译node_modules、dist等无关文件。