TypeScript tsconfig.json 配置速查 — 55+ 个编译器选项附默认值与示例

总开关,一次性启用七个严格检查:noImplicitAny、strictNullChecks、strictFunctionTypes、strictBindCallApply、strictPropertyInitialization、noImplicitThis 和 useUnknownInCatchVariables。新项目必开。老项目用 `// @ts-nocheck` 逐文件迁移。

"strict": true

⚠ 注意 在大型老项目里开启 strict 可能一下冒出几千个错误。迁移期间在最嘈杂的文件顶部加 `// @ts-nocheck`,而不是逐行压制。

当 TS 因缺少类型信息而推断出 `any` 时报错。最常见触发场景是未注解的函数参数:` function foo(x)` 会报错,必须写 `function foo(x: string)`。

"noImplicitAny": true

让 `null` 和 `undefined` 成为独立类型,不再能赋给任何类型。没这个 flag 时,忘记处理 null 是静默 bug。开了之后必须显式检查、用非空断言(`!`),或在联合类型里包含 `null`。

"strictNullChecks": true

⚠ 注意 迁移时最常漏掉的是给可能返回空的函数的返回类型补 `| null | undefined`。

对回调位置的函数参数类型强制逆变检查。能捕获一类微妙 bug:传入的函数只接受比回调期望的更窄的类型。方法声明(非箭头函数)依然按双变处理以保持兼容性。

"strictFunctionTypes": true

对 `bind`、`call`、`apply` 的参数进行严格类型检查。没开时这些方法接受任意 `any` 参数,开了才能根据函数签名正确校验。

"strictBindCallApply": true

对类中声明但未在构造函数里初始化的属性报错。需要同时开 `strictNullChecks`。只有在真正能保证构造函数外初始化顺序时(如依赖注入)才用确定赋值断言(`!`)。

"strictPropertyInitialization": true

⚠ 注意 不要把每个属性都加 `!` 来压掉报错,那样等于没开这个检查。只在生命周期钩子或框架注入初始化的属性上用。

当 `this` 隐式为 `any` 类型时报错。常见于 TS 无法判断 `this` 类型的独立函数和对象字面量里。修复方法:在函数签名中加 `this: ClassName` 参数。

"noImplicitThis": true

让 `catch` 子句的错误变量类型变为 `unknown` 而不是 `any`。强制在访问前先收窄类型,因为 `throw` 可以抛任何值,不只是 `Error` 实例。

"useUnknownInCatchVariables": true

⚠ 注意 用 `if (error instanceof Error)` 或类型守卫处理,不要不加检查直接 `as Error`,因为 `throw "字符串"` 是合法的 JavaScript。

对声明了但从未使用的局部变量报错。故意不用的变量用 `_` 前缀(如回调里的 `_index`)可压制报错而无需删除。

"noUnusedLocals": true

对声明了但从未使用的函数参数报错。和 `noUnusedLocals` 一样,用 `_` 前缀标记故意不用的参数。

"noUnusedParameters": true

当非 void 函数中并非所有代码路径都有 `return` 时报错。防止复杂 if/else 链里漏掉 else 分支的 return 这类经典 bug。

"noImplicitReturns": true

对 switch 里非空且未用 `break`/`return`/`throw` 结束而落空到下一个 case 的情况报错。多个空 case 连写(如 `case X: case Y:`)仍然允许。

"noFallthroughCasesInSwitch": true

区分"属性不存在"和"属性被显式设为 undefined"。可选属性 `x?: string` 只允许赋字符串或完全省略 `x`,把 `obj.x = undefined` 写进去是错误。这是最精确的可选属性建模。

"exactOptionalPropertyTypes": true

⚠ 注意 很多老代码用 `obj.x = undefined` 来"清除"属性。开了这个 flag 必须改为 `delete obj.x`,或把类型改成 `x?: string | undefined`。

在数组下标访问和索引签名访问的返回类型里加入 `undefined`。因为 `arr[5]` 可能越界,TS 要求访问前先检查 `arr[5] !== undefined`。能抓到一类非常常见的运行时错误。

"noUncheckedIndexedAccess": true

⚠ 注意 `strict` 不会自动开这个,要手动选择。在大量操作数组的代码里会比较吵。确定下标一定存在时用 `arr[i]!`(非空断言)。

要求通过索引签名定义的属性必须用方括号(`obj["key"]`)而非点符号(`obj.key`)访问。让"安全"访问(已声明属性)和"动态"访问(索引签名)在视觉上一目了然。

"noPropertyAccessFromIndexSignature": true

控制 TS 生成什么模块格式。`"CommonJS"` 生成 `require()/module.exports`(传统 Node)。`"ESNext"` 生成 `import/export`(打包器用)。`"NodeNext"` 开启完整 Node.js ESM,导入路径需加 `.js` 扩展名。

"module": "NodeNext"

⚠ 注意 Vite/webpack 项目:用 `"ESNext"` + `"moduleResolution": "bundler"`。Node.js ESM:两个都用 `"NodeNext"`。永远不要把 `"ESNext"` module 和 `"node10"` resolution 混用。

决定 TS 怎么查找模块文件。`"bundler"`(TS 5.0+)匹配 Vite/esbuild 等现代打包器,不需要文件扩展名。`"NodeNext"` 对应 Node.js 12+ 解析规则,需要 `.js` 扩展名。`"node10"` 是旧版 Node.js 解析策略。

"moduleResolution": "bundler"

允许导入 `.json` 文件并根据 JSON 结构自动推断类型。用于直接在 TS 里导入配置文件、本地化字符串或静态数据集非常方便。

"resolveJsonModule": true

⚠ 注意 大 JSON 文件会被完整类型检查并打包,可能拖慢编译并增大包体积。超大数据文件考虑运行时再加载。

允许在 import 语句里显式写 `.ts`、`.tsx`、`.mts` 扩展名。要求同时开 `noEmit` 或 `emitDeclarationOnly`,因为 TS 不知道如何处理输出 JS 里的 `.ts` 扩展名。

"allowImportingTsExtensions": true

让 TS 在处理 `.ts` 文件的同时也处理 `.js` 和 `.jsx` 文件。逐步把 JS 项目迁移到 TS 时很有用,可以一次转换一个文件,不需要全部改名。

"allowJs": true

对 `.js` 文件开启类型检查(需要同时开 `allowJs`)。TS 利用类型推断和 JSDoc 注解检查 JavaScript。在 JS 代码库里引入 TS 时的好起点,不必一开始就写 TS 类型注解。

"checkJs": true

强制纯类型导入用 `import type`,纯类型导出用 `export type`;导入类型时不加 `type` 关键字会报错。确保类型导入在编译时被移除,无需 Babel 等工具。替代了 `importsNotUsedAsValues`。

"verbatimModuleSyntax": true

⚠ 注意 需要给所有现有纯类型导入加 `type`,如 `import { Foo }` 改为 `import type { Foo }`。多数编辑器可以通过快速操作自动修复。

控制 TS 怎么判断一个文件是模块还是脚本。`"auto"`:有 `import`/`export` 或 `import.meta` 的文件是模块。`"force"`:所有非声明文件都当模块处理,有助于防止意外的全局声明。

"moduleDetection": "force"

设置 TS 生成的 JS 语言版本。现代项目用 `"ES2022"` 或 `"ESNext"`。影响语法转换(async/await、可选链)和通过 `lib` 可用的内置类型。target 与实际运行环境不匹配会导致微妙错误。

"target": "ES2022"

⚠ 注意 target 设得比实际运行环境高会导致运行时错误。比如 `"ES2022"` 但在 Node 12 上跑,`Array.at()` 等方法不存在。

指定要包含的内置 API 类型声明。不填时 TS 根据 `target` 自动选择。常见补充:`"DOM"` 加浏览器 API,`"DOM.Iterable"` 加可迭代 DOM 集合。Node.js 项目里去掉 `"DOM"` 避免浏览器类型混入。

"lib": ["ES2022", "DOM", "DOM.Iterable"]

指定编译后文件的输出目录。TS 在 `outDir` 里复现源文件的目录结构。与 `rootDir` 配合使用以得到可预期的输出布局。记得把 `outDir` 加到 `.gitignore`。

"outDir": "./dist"

指定 TS 源文件的根目录。与 `outDir` 配合计算输出路径,`rootDir` 下的目录结构会在 `outDir` 里复现。如果 TS 推断错了,显式设为 `"./src"`。

"rootDir": "./src"

在编译输出的 `.js` 文件旁边生成 `.d.ts` 类型声明文件。发布 TypeScript 库时必须开启。配合 `emitDeclarationOnly` 可以只输出类型文件不输出 JS。

"declaration": true

在 `.d.ts` 旁边生成 `.d.ts.map` 文件。让编辑器"跳转到定义"时跳到原始 `.ts` 源文件而非 `.d.ts`。对能访问源码的库使用者来说大幅改善开发体验。

"declarationMap": true

生成 `.js.map` 源映射文件,将编译后的 JS 映射回原始 TS。让调试器和错误报告工具(Sentry 等)显示 TS 行号而非编译后的 JS 行号。生产环境调试必备。

"sourceMap": true

只运行类型检查,不向磁盘写任何输出文件。打包器(Vite、esbuild、webpack)负责编译时的理想配置,TS 只做类型检查。配合 `isolatedModules: true` 可获得最快的类型检查速度。

"noEmit": true

只生成 `.d.ts` 类型文件,不生成 `.js`。发布库时的理想配置:TS 通过 `tsc` 生成类型,打包器生成 JavaScript。需要同时开 `declaration: true`。

"emitDeclarationOnly": true

从生成的 JS 里删掉所有注释。不影响 `.d.ts` 类型声明文件。TS 源码里有大量 JSDoc 注释但想减小输出体积时有用。三斜杠引用指令(`/// <reference>`)始终保留。

"removeComments": true

从 `tslib` 导入辅助函数(`__awaiter`、`__extends`、`__assign` 等)而不是在每个文件里内联生成。当大量文件用到同一个辅助函数时能减小总包体积。需要把 `tslib` 加为依赖。

"importHelpers": true

编译到 ES5/ES3 时对可迭代对象(for...of、展开、解构)生成正确的迭代代码。没开时 TS 用简单但不正确的实现。配合 `importHelpers: true` + `tslib` 避免每个文件都内联迭代器辅助函数。

"downlevelIteration": true

开启 CommonJS 和 ES 模块 `import` 语法的互操作性。没开时 `import React from "react"` 对只导出 `module.exports` 的模块会失败。开了之后 TS 加辅助代码让默认导入对 CJS 模块也能用。自动启用 `allowSyntheticDefaultImports`。

"esModuleInterop": true

⚠ 注意 这会添加运行时辅助函数(`__importDefault`、`__importStar`)。配合 `importHelpers: true` + `tslib` 统一导入,避免每个文件都生成一份。

当模块没有显式 `export default` 时允许 `import Foo from 'module'` 写法。这是纯类型检查 flag,不生成任何运行时代码。开了 `esModuleInterop` 会自动启用。同时需要运行时行为时用 `esModuleInterop`。

"allowSyntheticDefaultImports": true

确保每个文件都能在不依赖其他文件类型信息的情况下独立转译。使用 Babel、esbuild 或 SWC 编译 TS 时必须开启。对只在完整类型信息下才能工作的特性报错:`const enum`、非类型重导出、外部模块声明。

"isolatedModules": true

⚠ 注意 `const enum` 完全不允许,改用普通 `enum` 或 const 对象。所有纯类型导入必须用 `import type` 确保正确移除。

要求所有导入使用被引用文件名的确切大小写。防止只在大小写敏感文件系统(Linux)上出现而在 macOS/Windows 上不报错的 bug。能抓到 `import Foo from "./foo"` 但实际文件是 `Foo.ts` 这类问题。

"forceConsistentCasingInFileNames": true

跳过所有 `.d.ts` 类型声明文件(包括 npm 包里的)的类型检查。防止第三方类型定义不正确或相互冲突导致的错误。显著加快编译速度。几乎所有应用项目都推荐开启。

"skipLibCheck": true

⚠ 注意 这也会跳过你自己的 `.d.ts` 文件。维护库时在库本身的 tsconfig 里保持 `false`,在使用者的 app 里用 `true`。

启用对旧版装饰器语法(Stage 2 装饰器,TS 原始实现)的支持。Angular、NestJS、TypeORM 等框架必须开启。注意:TS 5.0 已单独添加了对 TC39 官方装饰器标准的支持。

"experimentalDecorators": true

为带有装饰器的声明生成设计时类型元数据。使用反射的依赖注入容器(NestJS、InversifyJS)必须开启。需要同时开 `experimentalDecorators: true` 以及运行时引入 `reflect-metadata` polyfill。

"emitDecoratorMetadata": true

控制 JSX 语法如何转换。`"react-jsx"`(React 17+):使用自动运行时,无需每个文件都 `import React`。`"react"`(旧版):每个 JSX 文件都需要 `import React`。`"preserve"`:保留 JSX 让打包器处理。`"react-native"`:和 preserve 一样但输出 `.js` 扩展名。

"jsx": "react-jsx"

指定使用 `"jsx": "react-jsx"` 时从哪个模块导入 `jsx` 和 `jsxs` 工厂函数。Preact 用 `"preact"`,SolidJS 用 `"solid-js"`,Vue 3 用 `"vue"` 等。可以用 `/** @jsxImportSource preact */` 在单个文件里覆盖。

"jsxImportSource": "preact"

使用 `"jsx": "react"` 旧版转换时指定 JSX 元素创建函数。Preact 改为 `"h"`,React 默认是 `"React.createElement"`。使用新版 `"react-jsx"` 转换时此选项无关。

"jsxFactory": "h"

设置解析非相对模块名的基础目录。设为 `"."` 或 `"./src"` 后,可以写 `import Button from "components/Button"` 而不是一串 `../../`。通常与 `paths` 配合使用。

"baseUrl": "."

⚠ 注意 TS 只处理类型解析那一侧。打包器(Vite 的 `resolve.alias`、webpack 的 `resolve.alias`)也需要配置对应别名,运行时才能实际解析到正确文件。

将模块名模式映射到文件位置。启用 `@/*` → `./src/*` 这类路径别名。每个模式映射到一组备用路径。需要同时设置 `baseUrl`。

"paths": { "@/*": ["./src/*"] }

⚠ 注意 `paths` 只影响类型检查,TS 不会改写输出 JS 里的导入路径。必须在打包器里配置对应别名才能在运行时正确解析。

让 TS 把多个目录当成合并成一个虚拟根目录来处理。在 monorepo 或多目录在运行时合并的构建系统中很有用。允许这些目录之间进行相对路径导入。

"rootDirs": ["./src", "./generated"]

启用项目引用,让 `tsc --build` 在多包仓库里只重新构建发生变化的包。要求 `declaration: true`,并创建 `.tsbuildinfo` 缓存文件。TypeScript monorepo 增量构建的基础。

"composite": true

把构建信息保存到 `.tsbuildinfo` 文件,后续构建跳过未改变的文件。在大型项目里显著加快 TS 编译速度。记得把 `.tsbuildinfo` 加到 `.gitignore`。

"incremental": true

指定 `.tsbuildinfo` 增量构建缓存文件的路径。同时构建多个 tsconfig 可能写到相同默认位置时需要修改,或者要把缓存存到 CI 特定目录时也用到。

"tsBuildInfoFile": "./.tsbuildinfo"