最小 tsconfig.json

2024-01-24 更新

TypeScript 还有一个无配置文件模式，当然这个模式下默认是不开 strict 的，来看看实际上会造成什么问题：

0. target: "es5"，不使用 tsc 编译的话其实没啥影响
1. alwaysStrict: false，默认不产生 "use strict"
2. noImplicitAny: false，隐式 any 不会报错，所以你可以写下面这个东东

   window.foo = 'bar'
   // 否则你必须标记成
   (window as any).foo = 'bar'

3. noImplicitThis: false，this 不标类型不会报错，所以你可以写下面这个东东

   function foo() { return this.bar }
   // 否则你必须标记成
   function foo(this: { bar: unknown }) { return this.bar }

4. strictNullChecks: false，不会检查 null | undefined，但是目前 VS Code 和 Sublime LSP TypeScript 都是默认开启这个检查的 (有可能是 tsserver 默认开启)，所以实际上可以理解成仍然会检查 null。下面这段代码可以用 tsc 编译过但是常见编辑器里会有提示

   declare const const a: string | nulla: string | null
   var console: Consoleconsole.Console.log(...data: any[]): void
   [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log(a.String.toLowerCase(): string
   Converts all the alphabetic characters in a string to lowercase.toLowerCase())
   'a' is possibly 'null'.

5. strictPropertyInitialization: false，不会检查未初始化的属性

   class Foo {
     bar: string;
     constructor() {
       // Not initializing 'bar' here and no error
     }
   }

6. useUnknownInCatchVariables: false，catch(error) 默认用 any 类型。其实在规范的项目里我希望 error 直接隐式标成 Error，这样 .message 比较容易
7. 你可以正常使用 import { uniq } from "lodash" 和 import.meta.url 等语法
8. 但是不能写 top level await，这个功能必须要设置 module: "ESNext" / "ES2022"

2023-12-18 更新

TypeScript 发展至今积累了许多过时配置项以及重复配置项，本文试图按现在最新的文档，给出最小的 tsconfig.json 配置。

TL;DR

{
  "compilerOptions": {
    "strict": true,
    "target": "ESNext"
  }
}

如果你有第三方库，建议增加以下配置：

{
  "compilerOptions": {
    "strict": true,
    "target": "ESNext",
    "moduleResolution": "Bundler",
    "esModuleInterop": true,
    "types": [],
    "skipLibCheck": true,
    // 可选配置
    "noEmit": true,
    "resolveJsonModule": true,
    "verbatimModuleSyntax": true
  }
}

解释

strict

开启严格模式，比如不允许含有 null 的类型通过检查。

declare const const a: string | nulla: string | null
a.String.length: number
Returns the length of a String object.length
'a' is possibly 'null'.

这个严格模式代替了其他 8 个建议开启的配置项，我就不一一列举了，文末会附上一些更严格的选项，用户按需打开。

target

代码降级和默认 lib，类比 esbuild 的 target，不填是 ES5。

例如，当 target 是 ES5 时，let a = 1 会变成 var a = 1。

如果不使用 tsc 编译出 js 文件，这里的降级对我们没有意义。

当 target 是 ES6 及以上时，会默认设置：

• lib 为 ["DOM", "DOM.Iterable", ...]；
• module 为 ES6，
  • moduleResolution 为 Node。

因此大多数情况下，你只需要设置 target 为 ESNext 即可使用最新的语法和 ESM 环境。

module

使用哪种模块类型，是 ESM 还是 CJS，类比 esbuild 的 format。不填时，当 target 是 ES6 以上时默认是为 ES6。

由于现代前端主流就是推行 ESM，这里设置为以下任何一个变体的即可。

moduleResolution

要求按何种算法搜索 import 后面的路径，使用现代打包器的建议设置为 Bundler。

esModuleInterop

影响如何使用第三方库的默认导出名，使用现代打包器的这里无脑打开即可。

如果你没有第三方库，根本无需这个选项。

types: ["node"]

设置导入哪些污染全局的类型声明，比如 @types/node。默认不填的话所有 node_modules/@types 里的类型都会注入到全局，如果你觉得这个行为慢或者不安全，可以手动设置。

skipLibCheck

所有 d.ts 文件不再报告错误或警告，通常是用来规避一些第三方库的类型冲突问题。

noEmit

打开这个选项主要是为了规避文件名冲突问题，tsc 默认会假设你会运行他来生成目标 js 文件，如果这个生成会覆盖已有文件就会报错。你可以看情况打开这个选项告诉他不会生成 js。

verbatimModuleSyntax

强制要求类型导入必须使用 import type，方便第三方打包器分析文件依赖的时候不产生循环引用。

附：include/exclude/files

这几个选项会用来决定当前项目里有哪些文件，TypeScript 会使用以下几种行为。

• 啥也没设置的话，从 tsconfig.json 当前文件夹递归搜索所有 .ts 文件，跳过默认 exclude 的文件 (比如 node_modules)。
• 设置了 files 就直接用这个数组里的文件，不再搜索。
• 设置了 include 或 exclude 就执行这个搜索算法：glob(include).reject(exclude)。

因此最无脑的选择是直接把 tsconfig.json 放到 src 目录里。

附：超级严格选项

noFallthroughCasesInSwitch: true

不允许直接 fallthrough 到下一个 case，除非加一个 // fallthrough 注释。

noImplicitOverride: true

不允许直接覆盖父类的方法，除非加一个 override 关键字。

noImplicitReturns: true

不允许不写 return。

noPropertyAccessFromIndexSignature: true

不允许用 . 访问未知下标属性。

noUncheckedIndexedAccess: true

访问未知下标属性的时候会自动加上 | undefined。

noUnusedLocals: true

不允许出现未使用的局部变量，真有可以加前缀 _。

noUnusedParameters: true

不允许出现未使用的参数，真有可以加前缀 _。