tsconfig.json的速查表和完整解释

站长

2023年09月18日 23:50 · 阅读数 15

原文地址：www.totaltypescript.com/tsconfig-ch…

文章主要包括基本选项、严格性、是否使用TypeScript进行转译、是否在DOM中运行代码、是否为库构建以及是否在Monorepo中为库构建，每个部分都详细列举了相关的配置选项及其作用，并提供了相关链接以便读者进一步了解、并更容易配置TypeScript。

1、配置速查表如下：

{

  "compilerOptions": {

    /* Base Options: */

    "esModuleInterop": true,

    "skipLibCheck": true,

    "target": "es2022",

    "verbatimModuleSyntax": true,

    "allowJs": true,

    "resolveJsonModule": true,

    "moduleDetection": "force",
    

    /* Strictness */

    "strict": true,

    "noUncheckedIndexedAccess": true,
    

    /* If transpiling with TypeScript: */

    "moduleResolution": "NodeNext",

    "module": "NodeNext",

    "outDir": "dist",
    

    /* If NOT transpiling with TypeScript: */

    "moduleResolution": "Bundler",

    "module": "ESNext",

    "noEmit": true,
    

    /* If your code runs in the DOM: */

    "lib": ["es2022", "dom", "dom.iterable"],
    

    /* If your code doesn't run in the DOM: */

    "lib": ["es2022"],
    

    /* If you're building for a library: */

    "declaration": true,
    

    /* If you're building for a library in a monorepo: */

    "composite": true,

    "sourceMap": true,

    "declarationMap": true

  }

}

2、各部分配置详解

2.1 基本选项配置

{

  "compilerOptions": {

    "esModuleInterop": true,

    "skipLibCheck": true,

    "target": "es2022",

    "verbatimModuleSyntax": true,

    "allowJs": true,

    "resolveJsonModule": true,

    "moduleDetection": "force"

  }

}

esModuleInterop：有助于修复 CommonJS 和 ES Modules 之间的一些不兼容之处。
skipLibCheck：跳过对 .d.ts 文件的类型检查。这对性能很重要，否则会检查所有的 node_modules。
target：你要目标的 JavaScript 版本。我建议选择 es2022 而不是 esnext，以获得更稳定的支持。
verbatimModuleSyntax：在 .cts 和 .mts 文件中，此选项会使 import 和 export 语法更加严格，产生严格的错误。
allowJs 和 resolveJsonModule：允许你导入 .js 和 .json 文件。这总是很有用的。
moduleDetection：此选项强制 TypeScript 将所有文件视为模块。这有助于避免“无法重新声明块范围变量”的错误。

2.2 严格性配置

{

  "compilerOptions": {

    "strict": true,

    "noUncheckedIndexedAccess": true

  }
}

strict：启用所有严格的类型检查选项。不可或缺。
noUncheckedIndexedAccess：防止在没有首先检查数组或对象是否已定义的情况下访问它们。这是防止运行时错误的绝佳方法，应该真正包含在严格选项中。

大部分人推荐在 tsconfig.json 的基本配置中包括严格性选项，这是一个精彩的存储 TSConfig 选项的仓库。这些选项包括许多我认为有点“啰嗦”的规则，比如 noImplicitReturns、noUnusedLocals、noUnusedParameters 和 noFallthroughCasesInSwitch。我建议只有在你需要这些规则时才将它们添加到你的 tsconfig.json 中。

2.3 使用typeScript代码转义

{

  "compilerOptions": {

    "moduleResolution": "NodeNext",

    "module": "NodeNext",

    "outDir": "dist"

  }
}

moduleResolution：告诉 TypeScript 如何解析模块。如果你编写的代码是用于在 Node.js 中运行的话，NodeNext 是最佳选项。
module：告诉 TypeScript 使用什么模块语法。如果是针对 Node.js 编写的代码，NodeNext 是最佳选项。
outDir：告诉 TypeScript 将编译后的 JavaScript 文件放在何处。"dist" 是我首选的约定，但你也可以根据自己的需求选择其他目录。

2.4 代码检查工具

{

  "compilerOptions": {

    "moduleResolution": "Bundler",

    "module": "ESNext",

    "noEmit": true

  }
}

moduleResolution：如果你编写的代码意图与类似 Webpack、Rollup、Babel、SWC 或 ESBuild 等工具一起捆绑，那么 "Bundler" 是最佳选项，因为它最符合模块捆绑工具的处理方式。
module：如果你的代码意图与这些工具一起捆绑，那么 "ESNext" 是最佳选项，因为它最接近捆绑工具对模块的处理方式。

2.5 是否运行在DOM中

{

  "compilerOptions": {

    "lib": ["es2022", "dom", "dom.iterable"]
  }
}

lib：告诉 TypeScript 包含哪些内置类型。为了稳定性，"es2022" 是最佳选项。而 "dom" 和 "dom.iterable" 提供了用于 window、document 等的类型定义。

2.6 不运行在DOM中

{

  "compilerOptions": {

    "lib": ["es2022"]
  }
}

2.7 构建库

{

  "compilerOptions": {

    "declaration": true
  }
}

declaration 选项告诉 TypeScript 生成 .d.ts 文件。这是为了让库能够在你创建的 .js 文件上获得自动完成功能所必需的。

2.8 在monorepo中构建库

{

  "compilerOptions": {

    "declaration": true,

    "composite": true,

    "sourceMap": true,

    "declarationMap": true
  }
}

composite：告诉 TypeScript 生成 .tsbuildinfo 文件。这告诉 TypeScript 你的项目是 monorepo 的一部分，也有助于缓存构建以提高运行速度。
sourceMap 和 declarationMap：告诉 TypeScript 生成源映射（source maps）和声明映射（declaration maps）。这些是为了让你的库的使用者在调试时能够通过 "跳转到定义" 功能跳转到原始源代码。