TypeScript 编译选项 compilerOptions 全部配置项

projects

• incremental

  • 是否启用增量编译。
  • 默认值是false。
  • 当incremental设置为true，TypeScript 编译器会记住上次编译的结果，并只重新编译那些发生了变化的文件。

• composite

  • 是否启用项目组合（Project Composition）功能。
  • 默认值是false。

• tsBuildInfoFile

  • 用于指定 TypeScript 编译器生成的构建信息文件的路径。
  • 默认值是''。
  • 使用示例："tsBuildInfoFile": "./buildInfo.json"。

• disableSourceOfProjectReferenceRedirect

  • 在项目引用中是否禁用源文件重定向。
  • 默认值是false。编译器将根据项目引用的配置进行源文件重定向。
  • 当disableSourceOfProjectReferenceRedirect设置为 true 时，编译器将禁用源文件重定向。

• disableSolutionSearching

  • 是否禁用在多个项目中搜索解决方案的行为。
  • 默认值是false。编译器可能会在多个项目中搜索解决方案，以解决类型引用等问题。
  • 当disableSolutionSearching设置为 true 时，编译器将不会在多个项目中搜索解决方案。

• disableReferencedProjectLoad

  • 是否禁用加载被引用的项目。
  • 默认值是false。编译器会根据项目引用关系加载和处理被引用的项目。
  • 当disableReferencedProjectLoad设置为 true 时，编译器将不会加载被引用的项目。

Language and Environment

• target

  • 指定编译生成的 JavaScript 代码的目标版本。
  • 默认值是 es3。
  • 可选值：‘es3’, ‘es5’, ‘es6’, ‘es2015’, ‘es2016’, ‘es2017’, ‘es2018’, ‘es2019’, ‘es2020’, ‘es2021’, ‘es2022’, ‘es2023’, ‘esnext’。注意： es6 和 es2015 是同一个版本。

• lib

  • 指定编译时包含的内置库文件（宿主环境）。

  • 正常情况下，前端代码在浏览器中运行，是不需要设置lib的。在tsconfig.json中，默认情况下，是被注释的。

  • 默认情况下，lib的默认值取决于目标运行环境（target选项的值）。
    • 如果 target是 es5，默认包含的库有 DOM、ES5、ScriptHost。
    • 如果 target是 es6，默认包含的库会更多一些，以适应 ES6 的特性，如 DOM、ES6、ScriptHost等。
    • 总的来说，默认值会确保包含目标运行环境所需的基本内置库，以便在编译后的代码中可以使用相应的语言特性和运行时支持。
  • 值是数组。使用示例：['es6', 'dom']
  • 可选值：‘es5’, ‘es6’, ‘es2015’, ‘es7’, ‘es2016’, ‘es2017’, ‘es2018’, ‘es2019’, ‘es2020’, ‘es2021’, ‘es2022’, ‘es2023’, ‘esnext’, ‘dom’, ‘dom.iterable’, ‘dom.asynciterable’, ‘webworker’, ‘webworker.importscripts’, ‘webworker.iterable’, ‘webworker.asynciterable’, ‘scripthost’, ‘es2015.core’, ‘es2015.collection’, ‘es2015.generator’, ‘es2015.iterable’, ‘es2015.promise’, ‘es2015.proxy’, ‘es2015.reflect’, ‘es2015.symbol’, ‘es2015.symbol.wellknown’, ‘es2016.array.include’, ‘es2016.intl’, ‘es2017.date’, ‘es2017.object’, ‘es2017.sharedmemory’, ‘es2017.string’, ‘es2017.intl’, ‘es2017.typedarrays’, ‘es2018.asyncgenerator’, ‘es2018.asynciterable’, ‘es2018.intl’, ‘es2018.promise’, ‘es2018.regexp’, ‘es2019.array’, ‘es2019.object’, ‘es2019.string’, ‘es2019.symbol’, ‘es2019.intl’, ‘es2020.bigint’, ‘es2020.date’, ‘es2020.promise’, ‘es2020.sharedmemory’, ‘es2020.string’, ‘es2020.symbol.wellknown’, ‘es2020.intl’, ‘es2020.number’, ‘es2021.promise’, ‘es2021.string’, ‘es2021.weakref’, ‘es2021.intl’, ‘es2022.array’, ‘es2022.error’, ‘es2022.intl’, ‘es2022.object’, ‘es2022.sharedmemory’, ‘es2022.string’, ‘es2022.regexp’, ‘es2023.array’, ‘es2023.collection’, ‘es2023.intl’, ‘esnext.array’, ‘esnext.collection’, ‘esnext.symbol’, ‘esnext.asynciterable’, ‘esnext.intl’, ‘esnext.disposable’, ‘esnext.bigint’, ‘esnext.string’, ‘esnext.promise’, ‘esnext.weakref’, ‘esnext.decorators’, ‘esnext.object’, ‘esnext.regexp’, ‘decorators’, ‘decorators.legacy’。

• jsx

  • 指定如何处理 JSX（JavaScript XML）代码。
  • 可选值及含义：
    • preserve：保留 JSX 代码不变，不进行任何转换。输出文件会带有.jsx扩展名。
    • react：生成的代码会调用React.createElement 或类似的函数来创建 React 元素。输出文件的扩展名为.js。
    • react-native：保留 JSX 为原始的样子，不进行转换。输出文件的扩展名为.js。类似于 react，但针对 React Native 环境进行优化。生成的代码适用于 React Native 应用程序。

• experimentalDecorators

  • 是否启用实验性的装饰器支持。
  • 默认值是false。
  • 当设置为 true 时，TypeScript 编译器将识别和处理装饰器。

• emitDecoratorMetadata

  • 是否在编译过程中生成装饰器元数据。
  • 默认值是false。
  • 当设置为 true 时，TypeScript 编译器会在生成的 JavaScript 代码中包含关于装饰器的元数据。
  • 注意，要使用 emitDecoratorMetadata，通常还需要同时设置 experimentalDecorators 为 true，因为装饰器本身在 TypeScript 中是实验性特性。

• jsxFactory

  • 指定在处理 JSX（JavaScript XML）代码时使用的工厂函数名称。
  • 自定义 JSX 转换：默认情况下，当 jsx 选项设置为 react 时，TypeScript 会使用 React.createElement 作为 JSX 转换的工厂函数。通过设置 jsxFactory，可以指定不同的工厂函数名称，以便与特定的库或框架集成。
  • 避免命名冲突：如果项目中已经存在名为 React 的变量，但它不是 React 库的实例，设置 jsxFactory 可以避免与现有变量的命名冲突，并确保正确的 JSX 转换。

示例：

{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "MyCustomCreateElement"
  }
}

在这个例子中，当处理 JSX 代码时，TypeScript 编译器将使用名为 MyCustomCreateElement 的函数作为工厂函数，而不是默认的 React.createElement。

• jsxFragmentFactory

  • 定在处理 JSX 片段（JSX Fragment）时使用的工厂函数名称。
  • 自定义 JSX 片段处理：当使用 JSX 片段（例如 <> 和 </> 包裹的内容）时，TypeScript 默认会使用 React.Fragment（如果 jsx 选项设置为 react）作为片段的容器。通过设置 jsxFragmentFactory，可以指定不同的工厂函数来创建片段容器。
  • 与特定框架集成：如果项目使用的不是 React 或者需要与特定的前端框架集成，可以通过设置这个选项来指定该框架中用于创建片段的函数。

• jsxImportSource

  • 指定导入 JSX 库的模块路径。
  • 自定义 JSX 实现来源：当使用 JSX 语法时，TypeScript 需要知道从哪个模块导入用于处理 JSX 的函数或对象。通过设置 jsxImportSource，可以指定一个特定的模块路径，以便在编译时正确导入所需的 JSX 处理功能。
  • 支持不同的 JSX 库或框架：如果项目使用的不是默认的 React 库来处理 JSX，或者需要使用自定义的 JSX 实现，可以通过设置这个选项来指定正确的导入路径。

示例：

{
  "compilerOptions": {
    "jsx": "react",
    "jsxImportSource": "my-custom-jsx-library"
  }
}

在这个例子中，当处理 JSX 代码时，TypeScript 编译器将从 "my-custom-jsx-library" 模块导入用于处理 JSX 的函数或对象，而不是默认的 React 库。

• reactNamespace
  • 指定 React 库在全局命名空间中的名称。
  • 处理非默认命名的 React 库：在某些情况下，React 库可能没有被全局安装为 React，而是使用了不同的命名空间。通过设置 reactNamespace，可以告诉 TypeScript 在编译时使用指定的命名空间来识别 React 组件和相关功能。
  • 与旧版本代码或特定环境兼容：如果项目中使用的是旧版本的代码库或者在特定的环境中，React 可能被以不同的方式引入和命名。reactNamespace选项可以帮助 TypeScript 正确地处理这些情况。

示例：

{
  "compilerOptions": {
    "jsx": "react",
    "reactNamespace": "MyCustomReactNamespace"
  }
}

在这个例子中，TypeScript 编译器将在全局命名空间中查找名为 "MyCustomReactNamespace"的对象来识别 React 相关的功能。

• noLib

  • 是否自动包含默认的 TypeScript 库文件（如 lib.d.ts）。
  • 默认值是 false。
  • 当设置为 true后，TypeScript 编译器不会自动包含默认的库文件。开发者需要手动指定要包含的库文件，可以通过在 tsconfig.json中的 files、includes或 references等选项来指定特定的文件或项目，以确保所需的类型定义被包含。

• useDefineForClassFields

  • 控制类字段的初始化方式。
  • 默认值是 false，类字段的初始化可能会在构造函数中进行。
  • 当设置为 true时，类字段的初始化将遵循特定的规则，通常是在类定义中进行初始化。

• moduleDetection

  • 控制模块检测的方式。
  • auto（默认值）：TypeScript 编译器会自动尝试检测模块的类型。它会根据导入语句的形式、文件扩展名等因素来确定模块的格式，例如 CommonJS、ES6 模块等。
  • force：强制编译器将所有文件视为模块，即使没有明确的导入或导出语句。这可以在某些情况下确保一致性，但可能会导致一些意外的结果，特别是对于一些传统的脚本文件。

Modules

• module

  • 指定生成的模块系统类型（指定要使用的模块化的规范）。
  • 默认值是 "commonjs"。
  • 可选值：‘none’, ‘commonjs’, ‘amd’, ‘system’, ‘umd’, ‘es6’, ‘es2015’, ‘es2020’, ‘es2022’, ‘esnext’, ‘node16’, ‘nodenext’, ‘preserve’。

• rootDir

  • 指定 TypeScript 编译器在查找源文件时的根目录。
  • 默认值是 ./ 。

示例：

{
  "compilerOptions": {
    "rootDir": "./src"
  }
}

在这个例子中，TypeScript 编译器将从当前目录下的 src目录开始查找源文件。

• moduleResolution

  • 指定模块解析策略。
  • 默认值是"node"。
  • "node"：这是默认的模块解析策略。它模仿了 Node.js 的模块解析方式，优先在当前目录下查找模块文件，如果找不到，则向上一级目录查找，直到找到模块文件或者到达文件系统的根目录。此外，它还支持使用 node_modules目录来查找第三方模块。
  • "classic"：这种模块解析策略使用传统的 TypeScript 模块解析方式。它根据模块的相对路径或绝对路径来查找模块文件，不依赖于特定的运行时环境。
  • "node16"、"nodenext"：这些是针对特定版本的 Node.js 的模块解析策略。它们在功能上与 "node"类似，但可能会根据不同的 Node.js 版本进行一些调整和优化。

• baseUrl

  • 指定模块解析的基础路径。
  • 默认值是当前工作目录（通常是包含 tsconfig.json 文件的目录）。如果没有显式设置 baseUrl，TypeScript 编译器在解析模块导入时将从当前工作目录开始查找模块文件。
  • 简化模块导入路径：通过设置 baseUrl，可以为项目中的模块导入提供一个相对的基础路径。这使得在导入模块时可以使用相对较短的路径，提高代码的可读性和可维护性。
  • 控制模块查找范围：baseUrl可以限制模块解析器在特定的目录范围内查找模块。这有助于避免模块解析器在不必要的目录中进行搜索，提高编译性能。

项目结构如下：

project/
├── src/
│   ├── modules/
│   │   ├── moduleA.ts
│   │   └── moduleB.ts
│   └── index.ts
└── tsconfig.json

tsconfig.json 配置：

{
  "compilerOptions": {
    "baseUrl": "./src",
    "module": "commonjs",
    "outDir": "./dist"
  }
}

在这个例子中，baseUrl被设置为 ./src。这意味着当在项目中导入模块时，TypeScript 编译器将从 ./src目录开始查找模块。

模块 moduleA位于 ./src/modules/moduleA.ts，可以使用以下方式导入：

import moduleA from 'modules/moduleA';

• paths
  • 指定模块路径的别名。
  • paths没有默认值，默认为一个空对象 {}。
  • 通常，paths选项需要与 baseUrl一起使用。baseUrl指定了模块解析的基础路径，而 paths中的别名是相对于 baseUrl的。
  • 简化模块导入路径：通过设置路径别名，可以使用更简洁、易读的名称来导入模块，而不是使用相对较长的实际路径。这提高了代码的可读性和可维护性。
  • 便于项目重构：如果项目的目录结构发生变化，只需要更新 paths配置中的别名，而不需要在整个项目中修改所有的模块导入路径。

示例：

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

在这个例子中，设置了两个路径别名：

1. "@components/*" 指向 "src/components/*"。这意味着可以使用 @components/SomeComponent来导入位于 src/components/SomeComponent的模块。
2. "@utils/*" 指向 "src/utils/*"。可以使用 @utils/someUtility来导入位于 src/utils/someUtility 的模块。

• rootDirs
  • 指定虚拟目录的路径列表。
  • 默认值是一个空数组 []。

项目结构如下：

project/
├── src/
│   ├── views/
│   │   ├── viewA.ts
│   │   └── viewB.ts
│   └── templates/
│       ├── templateA.ts
│       └── templateB.ts
└── tsconfig.json

tsconfig.json 配置：

{
  "compilerOptions": {
    "rootDirs": ["src/views", "src/templates"]
  }
}

在这个例子中，rootDirs被设置为包含两个目录：src/views和 src/templates。在编译过程中，这两个目录将被视为一个逻辑目录，可以在代码中进行模块导入和引用。
例如，如果在 src/views中有一个模块 viewModule.ts，在 src/templates中有一个模块 templateModule.ts，可以在其他文件中进行如下导入：

import viewModule from 'views/viewModule';
import templateModule from 'templates/templateModule';

• typeRoots
  • 指定声明文件（.d.ts文件）的查找路径。
  • 默认值是 ["node_modules/@types"]。 如果没有显式设置 typeRoots，TypeScript 编译器会在项目的 node_modules/@types目录中查找类型声明文件。这个目录通常是存放第三方库的类型声明的地方。

项目结构：

project/
├── node_modules/
│   └── @types/
│       └── some-library/
│           └── index.d.ts
├── custom-types/
│   └── custom-type.d.ts
└── tsconfig.json

tsconfig.json 配置：

{
  "compilerOptions": {
    "typeRoots": [
      "./node_modules/@types",
      "./custom-types"
    ]
  }
}

设置 typeRoots为 ["./node_modules/@types", "./custom-types"]可以让编译器在这两个目录中查找类型声明文件。

• types
  • 指定需要包含的额外的类型声明文件。
  • 默认值是 []。如果没有显式设置 types，TypeScript 编译器不会自动包含任何特定的额外类型声明文件。它只会根据默认的类型查找规则（如在 node_modules/@types 目录中查找已安装库的类型声明）来解析类型。

示例：

{
  "compilerOptions": {
    "types": ["jquery", "lodash"]
  }
}

types被设置为包含 "jquery"和 "lodash"。这意味着 TypeScript 编译器将包含 jquery和 lodash的类型声明文件。

• allowUmdGlobalAccess

  • 是否允许在 UMD（Universal Module Definition）模块中访问全局变量。
  • 默认值是 false，不允许直接访问全局变量，需要通过适当的导入或其他方式来获取模块中的功能。
  • 当设置为 true时，TypeScript 编译器允许在代码中访问 UMD 模块可能创建的全局变量。

• moduleSuffixes

  • 指定模块文件的后缀名列表。
  • 默认值是 [] 。TypeScript 编译器只会按照默认的模块解析规则查找模块文件，不会尝试不同的后缀名。
  • 后缀名的顺序：moduleSuffixes中后缀名的顺序很重要。编译器会按照列表中的顺序依次尝试查找模块文件。通常，应该将最常用的后缀名放在前面，以提高查找效率。
  • 与其他配置选项的兼容性：moduleSuffixes选项可能需要与其他配置选项（如 moduleResolution、paths等）一起使用，以确保项目的正确编译和模块解析。

示例：

{
  "compilerOptions": {
    "moduleSuffixes": [".js", ".ts", ".json"]
  }
}

在这个例子中，moduleSuffixes被设置为包含 .js、.ts和 .json三个后缀名。当 TypeScript 编译器解析模块导入时，它会尝试查找具有这些后缀名的文件。

• allowImportingTsExtensions
  • 是否允许导入以 .ts为扩展名的文件时省略扩展名。
  • 默认值是 false。在默认情况下，必须在导入语句中明确指定 .ts扩展名才能正确导入 TypeScript 文件。
  • 如果设置为 true，可以在导入语句中省略 .ts扩展名，

示例：

// allowImportingTsExtensions: false
import { someFunction } from './module.ts';

// allowImportingTsExtensions: true
import { someFunction } from './module';

• resolvePackageJsonExports
  • 是否解析 package.json 文件中的 "exports" 字段来确定模块的入口点。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会解析 package.json文件中的 "exports"字段来确定模块入口点。它不会考虑 "exports"字段，按照常规方式查找模块文件。
  • 如果设置为 true时，TypeScript 编译器会根据当前的模块格式（如 "import"对应 ES 模块，"require"对应 CommonJS 模块）选择正确的入口文件进行解析。

示例：

// package.json
{
  "exports": {
    ".": {
      "import": "./esm/index.mjs",
      "require": "./cjs/index.cjs"
    }
  }
}

• resolvePackageJsonImports
  • 是否解析 package.json 文件中的 "imports"字段来确定模块的入口点。
  • 默认值是 false。TypeScript 编译器不会解析 package.json文件中的 "imports"字段来确定模块入口点。它不会考虑 "imports"字段，按照常规方式查找模块文件。
    -如果设置为 true，在导入 "@my-library/some-module"时，TypeScript 编译器会根据 "imports"字段中的配置找到对应的入口文件。

示例：

// package.json
{
  "imports": {
    "@my-library/some-module": "./path/to/specific/entry.js"
  }
}

• customConditions
  • 指定自定义的模块导入条件。
  • 默认值是 [] 。在默认情况下，TypeScript 编译器只会使用内置的模块解析规则，不会考虑任何自定义条件。

例如，如果想要根据不同的环境加载不同的模块，可以设置自定义条件：

{
  "compilerOptions": {
    "customConditions": ["development", "production"]
  }
}

在代码中，可以根据条件进行模块导入：

if (import.meta.env.MODE === "development") {
  const module = await import("./module.dev.js");
} else {
  const module = await import("./module.prod.js");
}

• resolveJsonModule
  • 是否允许导入 .json 文件作为模块。
  • 默认值是 false。在默认情况下，TypeScript 编译器不允许直接导入 .json 文件作为模块。如果要导入 .json 文件，通常需要使用其他方式，如通过 fs模块在运行时读取文件内容。
  • 如果设置为 true，TypeScript 编译器允许直接导入 .json 文件作为模块。

示例：
当 resolveJsonModule为 false时：

// 无法直接导入 json 文件作为模块
// import data from './data.json'; // 会报错
import * as fs from 'fs';
const data = JSON.parse(fs.readFileSync('./data.json', 'utf8'));

当 resolveJsonModule为 true时：

import data from './data.json';
console.log(data);

• allowArbitraryExtensions
  • 是否允许使用任意文件扩展名作为模块导入。
  • 默认值是 false。在默认情况下，TypeScript 编译器只允许使用常见的模块文件扩展名（如 .js、.ts、.json等）进行模块导入。如果尝试使用其他任意扩展名的文件进行导入，会导致编译错误。
  • 如果设置为 true，TypeScript 编译器允许使用任意文件扩展名作为模块导入。

示例：
假设 data.custom文件中包含有效的 JavaScript 或 TypeScript 代码，或者是可以在运行时被正确解析的数据格式。

// 以下导入会报错，因为默认不允许使用.custom 扩展名作为模块
import data from './data.custom'; 

当allowArbitraryExtensions是 false，导入会报错，因为默认不允许使用.custom 扩展名作为模块。
当allowArbitraryExtensions是 true， 导入成功。

• noResolve
  • 是否禁用模块解析。
  • 默认值是 false。在默认情况下，TypeScript 编译器会进行模块解析，尝试找到导入的模块并确定其位置。
  • 如果设置为 true，需要在运行时确保正确地加载和处理那些没有被解析的模块。

    • 注意：设置 noResolve为 true会有很多风险和影响，要在开发过程中采取相应的措施来确保代码的正确性和稳定性。

JavaScript Support

• allowJs

  • 是否允许编译 JavaScript 文件。
  • 默认值是 false。在默认情况下，TypeScript 编译器只处理 .ts、.tsx和 .d.ts文件，不会编译 .js文件。

• checkJs

  • 是否对 JavaScript 文件进行类型检查。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会对 JavaScript 文件进行类型检查。

• maxNodeModuleJsDepth

  • 指定在查找 JavaScript 文件时，在 node_modules目录中搜索的最大深度。
  • 默认值通常是无限制的，即编译器会在 node_modules目录中尽可能深地搜索以找到所需的 JavaScript 文件。
  • 值的类型是number。

Emit

• declaration
  • 是否生成声明文件（.d.ts 文件）。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会生成声明文件。
  • 如果设置为 true，TypeScript 编译器会为每个 .ts文件生成相应的 .d.ts声明文件。这些声明文件包含了类型定义、接口、函数签名等信息，使得其他项目可以在不访问实际的 .ts源代码的情况下使用你的代码的类型信息。

例如，项目中有一个 TypeScript 文件 example.ts：

export function add(a: number, b: number): number {
  return a + b;
}

设置 declaration为 true后，会生成一个 example.d.ts文件：

export declare function add(a: number, b: number): number;

• declarationMap
  • 是否生成声明文件的源映射（.d.ts.map 文件）。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会生成声明文件的源映射文件。
  • declarationMap选项通常与 declaration选项一起使用。如果 declaration为 false，即使开启 declarationMap也不会生成源映射文件，因为没有声明文件可供映射。

假设开启了 declaration和 declarationMap选项，TypeScript 编译器会给.ts文件生成一个 .d.ts声明文件和一个 .d.ts.map源映射文件。

• emitDeclarationOnly

  • 是否只生成声明文件（.d.ts 文件）而不生成任何 JavaScript 输出文件。
  • 默认值是 false。在默认情况下，TypeScript 编译器会同时生成声明文件（如果 declaration选项为 true）和 JavaScript 输出文件。
  • 当设置为 true时，TypeScript 编译器只生成声明文件，不生成任何 JavaScript 输出文件。
  • emitDeclarationOnly选项通常与 declaration选项一起使用。如果 declaration为 false，即使设置 emitDeclarationOnly为 true也不会生成任何文件，因为没有声明文件可供生成。

• sourceMap

  • 是否生成源映射文件（.map 文件）。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会生成源映射文件。

示例：

{
  "compilerOptions": {
    "sourceMap": true
  }
}

sourceMap 设置为 true，TypeScript 编译器编译.ts文件后，除了生成 .js文件外，还会生成一个 .js.map源映射文件。

• inlineSourceMap
  • 是否将源映射信息内联到生成的 JavaScript 文件中。
  • 默认值是 false。在默认情况下，TypeScript 编译器会生成单独的源映射文件（.map文件），不会把源映射信息内联到 JavaScript 文件中。

如果将 inlineSourceMap设置为 true，生成的 JavaScript 文件可能会包含类似以下的注释：

//@ sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJzb...

这表示源映射信息已内联到该文件中。

inlineSourceMap选项可以在一定程度上简化项目部署和减少文件请求，但需要考虑文件大小增加、隐私安全和调试工具支持等问题。

• outFile
  • 指定将多个编译后的 JavaScript 文件合并输出到一个单一的文件中。
  • 默认值是 undefined，即没有默认的输出文件合并行为。在默认情况下，TypeScript 编译器会为每个输入的 TypeScript 文件生成单独的 JavaScript 文件，不会进行合并输出。

在 tsconfig.json文件中设置 outFile选项，指定输出文件的路径和名称。例如：

{
  "compilerOptions": {
    "outFile": "dist/bundle.js"
  }
}

这将把所有编译后的 JavaScript 文件合并输出到 dist/bundle.js文件中。

• outDir
  • 指定编译输出的目录。
  • 默认值是 undefined。在默认情况下，编译后生成的 .js文件会出现在与 .ts相同的目录中。

在 tsconfig.json文件中设置 outDir 选项，指定输出目录的路径。例如：

{
  "compilerOptions": {
    "outDir": "dist"
  }
}

这将把编译生成的文件输出到 dist目录中。

• removeComments

  • 在编译过程中是否删除注释。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会删除注释，生成的 JavaScript 文件中会保留原始 TypeScript 代码中的注释。
  • 如果设置为 true，在编译过程中删除注释，编译后的 JavaScript 文件中不会包含注释。

• noEmit

  • 在编译过程中是否生成输出文件。
  • 默认值是 false。在默认情况下，TypeScript 编译器会生成输出文件，包括 JavaScript 文件（如果设置了相应的输出选项）和声明文件（如果 declaration选项为 true）。
  • 如果设置为 true，TypeScript 编译器只会进行类型检查，不会生成任何输出文件。

• importHelpers

  • 是否引入导入助手函数。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会引入导入助手函数。

例如，如果有以下 TypeScript 代码：

import { add } from './math';

console.log(add(2, 3));

设置 importHelpers为 true ，生成的 JavaScript 代码可能会包含一些额外的函数来处理模块导入，例如：

var __importDefault = (this && this.__importDefault) || function (mod) {
    return (mod && mod.__esModule)? mod : { default: mod };
};
var _math = __importDefault(require('./math'));

console.log(_math.default.add(2, 3));

• downlevelIteration
  • 在将 TypeScript 代码编译为较低版本的 JavaScript（如 ES3、ES5）时，如何处理迭代器和生成器。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会对迭代器和生成器进行特殊处理，直接编译为目标 JavaScript 版本所支持的语法。

如果有以下 TypeScript 代码使用了迭代器：

function* numbers() {
  yield 1;
  yield 2;
  yield 3;
}

for (const num of numbers()) {
  console.log(num);
}

如果将目标 JavaScript 版本设置为 ES5 并且downlevelIteration设置为true，TypeScript 编译器会生成模拟迭代器的代码，以便在 ES5 环境中也能正确运行这段代码。

• sourceRoot
  • 指定调试器应该查找 TypeScript 源文件的根目录。
  • 默认值是 undefined。在默认情况下，调试器可能会尝试根据其他信息（如文件路径和源映射文件中的相对路径）来确定源文件的位置。

项目结构如下：

my-project/
├── src/
│   ├── index.ts
│   ├── utils/
│   │   ├── helper.ts
│   │   └──...
│   └──...
├── dist/
│   ├── index.js
│   ├── utils/
│   │   ├── helper.js
│   │   └──...
│   └──...
├── tsconfig.json
└──...

在 tsconfig.json中设置 sourceRoot：

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "sourceRoot": "src"
  }
}

sourceRoot设置为 "src"，表示调试器在调试生成的 JavaScript 文件时，应该在项目的 src目录中查找对应的 TypeScript 源文件。

• mapRoot
  • 指定调试器查找源映射文件（.map文件）的根目录。
  • 默认值是 undefined。在默认情况下，调试器可能会尝试根据其他信息（如文件路径和源映射文件中的相对路径）来确定源映射文件的位置。

项目结构如下：

project
├── src
│   ├── file1.ts
│   ├── file2.ts
│   └──...
├── dist
│   ├── file1.js
│   ├── file1.js.map
│   ├── file2.js
│   ├── file2.js.map
│   └──...
├── tsconfig.json
└──...

在 tsconfig.json中设置 mapRoot：

{
  "compilerOptions": {
    "sourceMap": true,
    "mapRoot": "mymaps"
  }
}

在这个例子中，源映射文件放置在一个单独的目录mymaps中进行管理，调试器将在 mymaps目录中查找源映射文件。

• inlineSources

  • 是否将原始的 TypeScript 源代码内联到生成的 JavaScript 文件中。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会将原始的 TypeScript 源代码内联到生成的 JavaScript 文件中。

• emitBOM

  • 在生成的输出文件中是否包含字节顺序标记（Byte Order Mark，BOM）。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会在生成的输出文件中包含字节顺序标记。

• newLine

  • 指定生成的输出文件中的换行符类型。
  • 默认值是"LF"，即 Unix/Linux 风格的换行符。
  • 可选值：
    • "CRLF"：表示 Windows 风格的换行符，即回车符（\r）和换行符（\n）的组合。
    • "LF"：表示 Unix/Linux 风格的换行符，即换行符（\n）。
    • "CR"：表示 Mac OS 9 及更早版本的换行符，即回车符（\r）。

• stripInternal

  • 是否禁止在JSDoc注释中发出带有“@internal”的声明。
  • 默认值是false。

• noEmitHelpers

  • 在编译过程中是否生成辅助函数。
  • 默认值是 false。在默认情况下，TypeScript 编译器会生成辅助函数，以确保代码的正确编译和运行。
  • 如果设置为 true，不会生成辅助函数。

• noEmitOnError

  • 在编译过程中遇到错误时是否生成输出文件。
  • 默认值是 false。在默认情况下，在编译过程中遇到错误，TypeScript 编译器仍然会生成输出文件。
  • 如果设置为 true，在编译过程中遇到错误，编译器将不会生成输出文件。

• preserveConstEnums

  • 在编译过程中是否保留常量枚举（const enums）的定义。
  • 默认值是 false。在默认情况下，TypeScript 编译器会在编译过程中对常量枚举进行优化，将其值直接替换为对应的常量表达式，不会保留枚举的定义。
  • 如果设置为 true，常量枚举的定义将在编译后的 JavaScript 代码中保留。

• declarationDir

  • 指定生成声明文件（.d.ts 文件）的输出目录。
  • 默认值是 undefined。声明文件（.d.ts）通常会输出到与对应的 .js文件相同的目录中。
  • 如果设置为 true，生成的声明文件（.d.ts 文件）会单独放在一个单独的目录中。

Interop Constraints

• isolatedModules

  • 是否将每个 TypeScript 文件视为一个独立的模块进行编译。
  • 默认值是 false。在默认情况下，TypeScript 编译器不会将每个文件视为独立的模块进行编译。

• verbatimModuleSyntax

  • 是否使用逐字模块语法。
  • 默认值是 false。在默认情况下，TypeScript 编译器会根据目标环境和其他配置选项对模块语法进行适当的转换和优化。
  • 如果设置为 true，TypeScript 编译器会尽可能保留原始的模块语法，而不进行额外的转换或优化。

• isolatedDeclarations

  • 是否将声明文件（.d.ts）作为独立的文件进行编译。
  • 默认值是 false。在默认情况下，声明文件不是作为独立的编译单元进行处理。
  • 如果设置为 true，明文件将被独立编译。

• allowSyntheticDefaultImports

  • 是否允许使用合成的默认导入。
  • 默认值是 false。在默认情况下，TypeScript 不允许使用合成的默认导入。

• esModuleInterop

  • 用于实现与 CommonJS 和 AMD 等旧的模块系统的互操作性。
  • 默认值是 false。在默认情况下，TypeScript 不会自动启用与旧的模块系统的互操作性。

• preserveSymlinks

  • 在编译过程中是否保留符号链接。
  • 默认值是 false。在默认情况下，TypeScript 编译器会在编译过程中解析符号链接，并将其转换为实际的文件路径。
  • 如果设置为 true，TypeScript 编译器会保留符号链接所指向的原始文件结构。

项目结构如下：

project/
├── src/
│   ├── module1.ts
│   └──...
├── node_modules/
│   ├── symlinked_module/
│   │   ├── module2.ts
│   │   └──...
│   └──...
├── tsconfig.json
└──...

如果设置 preserveSymlinks为 true，在编译过程中，符号链接 node_modules/symlinked_module 将被保留，编译器会将其视为实际的文件路径进行模块解析。

• forceConsistentCasingInFileNames
• 在解析文件路径时是否强制要求文件名的大小写一致。
• 默认值是 false。在默认情况下，TypeScript 编译器不会强制要求文件名的大小写一致。
• 如果设置为 true，在引用文件时，必须使用一致的文件名大小写。

Type Checking

• strict 所有严格模式的总开关。用于开启严格类型检查模式。

  • 默认值是 false。在默认情况下，TypeScript 不会开启严格模式。
  • 如果设置为 true，开启一系列严格的类型检查规则。TypeScript 编译器会在生成的 JavaScript 文件的开头添加 "use strict"; 语句。
  • 具体的严格检查内容：
    • "noImplicitAny" ：禁止隐式的 any类型。在严格模式下，必须显式地指定变量的类型，否则会导致编译错误。
    • "strictNullChecks"：启用严格的空值检查。要求在代码中明确处理可能为 null 或 undefined 的值。
    • "strictFunctionTypes"：对函数类型进行更严格的检查。确保函数参数的类型和返回值的类型与调用者的期望一致。
    • "strictBindCallApply"：对 bind、call 和 apply 的使用进行严格检查。
    • "strictPropertyInitialization"：要要求类的属性在构造函数中进行初始化，或者在属性声明时提供初始值。

• noImplicitAny

  • 是否禁止隐式的 any 类型。
  • 默认值是false。
  • 如果设置为 true，TypeScript 编译器将不允许隐式地将变量类型推断为 any。如果一个变量的类型没有被明确指定，并且无法从上下文推断出具体类型，编译器将报告错误。

• strictNullChecks

  • 是否启用严格的空值检查。
  • 默认值为false。
  • 如果设置为 true，TypeScript 要求开发者明确指定变量是否可以为 null 或 undefined。

• strictFunctionTypes

  • 是否对函数类型进行更严格的检查。
  • 默认值为false。TypeScript 在函数类型检查方面相对较为宽松。
  • 设置为 true的影响：
    1. 函数参数类型检查：
       • 逆变检查：对于函数参数类型，子类型不能赋值给父类型。
       • 重载解析：在函数重载的情况下，更严格的类型检查可以确保正确地选择合适的重载版本。如果函数的参数类型不匹配，编译器会给出更明确的错误提示。
    2. 函数返回值类型检查：
       • 协变检查：对于函数返回值类型，子类型可以赋值给父类型。严格模式下，返回值的类型检查也会更加严格，确保返回值的类型符合函数声明的类型要求。

• strictBindCallApply

  • 是否开启对 bind、call 和 apply 方法的严格类型检查。
  • 默认值为false。TypeScript 在对 bind、call 和 apply 方法的类型检查相对较宽松。
  • 设置为 true的影响：
    • 参数类型检查：当设置为 true时，TypeScript 会对传递给 bind、call 和 apply 方法的参数进行更严格的类型检查。如果参数的类型与函数的期望类型不匹配，将会产生编译错误。
    • 返回值类型推断：在严格模式下，TypeScript 会更准确地推断 bind、call 和 apply 方法的返回值类型。

示例：

function add(a: number, b: number): number {
  return a + b;
}

const boundAdd = add.bind(null, 10);

// 不启用 strictBindCallApply
boundAdd(20); // 返回 30，不会产生编译错误

// 启用 strictBindCallApply
boundAdd(20); 
// 如果 boundAdd 的调用参数类型与 add 函数不匹配，将会产生编译错误

当 strictBindCallApply为 false时，使用 bind 方法创建的函数 boundAdd可以接受不同类型的参数而不会产生编译错误。
当 strictBindCallApply为 true时，参数的类型必须与原始函数 add的期望类型匹配，否则会产生编译错误。

• strictPropertyInitialization

  • 是否开启对类属性的初始化的严格检查。
  • 默认值为false。TypeScript 在属性初始化检查方面相对较宽松。
  • 设置为 true的影响：
    • 构造函数初始化：如果一个类有实例属性，并且 strictPropertyInitialization为 true，那么在构造函数中必须对这些属性进行初始化。否则，编译器会产生错误。
    • 属性声明初始化：除了在构造函数中初始化属性，也可以在属性声明时提供一个初始值。
    • 可选属性处理：对于可选属性，可以使用 ? 表示可能为 null 或 undefined。

• noImplicitThis

  • 是否禁止隐式的 this 类型。
  • 默认值是false。 在默认情况下，TypeScript 在函数类型检查方面相对较为宽松。
  • 如果设置为 true，TypeScript 编译器将不允许在函数内部隐式地使用 this。在函数内部添加更多的类型标注来明确 this 的类型。

• useUnknownInCatchVariables

  • 指定在 catch 语句中捕获的错误变量的类型。
  • 默认值是false。 在默认情况下，在 catch 语句中捕获的错误变量的类型是 any，可以直接访问其属性和方法，不需要进行类型检查。
  • 设置为 true的影响：
    • 类型检查要求：启用 useUnknownInCatchVariables后，在使用捕获的错误变量之前，必须进行类型检查或类型断言。例如，可以使用 if (error instanceof SomeErrorType)或 (error as KnownErrorType)来确定错误的类型，并进行相应的处理。

• alwaysStrict

  • 是否始终以严格模式编译代码。
  • 默认值是false。在默认情况下，不强制以严格模式编译代码。
  • 设置为 true的影响：
    • 语法限制：严格模式下，有一些语法限制和行为变化。例如，不允许使用未声明的变量、不允许使用with语句、函数参数不能重名等。
    • 错误检测：严格模式下，TypeScript 编译器会进行更严格的类型检查和错误检测。

• noUnusedLocals

  • 检查代码中是否存在未使用的局部变量。
  • 默认值是false。在默认情况下，不进行未使用局部变量的检查。
  • 设置为 true的影响：
    • 编译错误：当设置为 true时，如果代码中存在未使用的局部变量，TypeScript 编译器会发出编译错误。

• noUnusedParameters

  • 检查函数参数是否被使用。
  • 默认值是false。在默认情况下，不进行未使用参数的检查。
  • 设置为 true的影响：
    • 编译错误：当设置为 true时，如果函数中存在未使用的参数，TypeScript 编译器会发出编译错误。

• exactOptionalPropertyTypes

  • 是否开启可选属性类型的严格检查。
  • 默认值是false。在默认情况下，可选属性的类型可以是更宽泛的联合类型，包括 undefined 和实际的类型。
  • 设置为 true的影响：
    • 类型声明的变化：启用这个选项后，需要对可选属性的类型声明进行调整。如果之前使用了宽泛的联合类型，现在需要明确指定为 undefined或实际的类型。
    • 编译错误：如果代码中存在不符合严格类型要求的可选属性声明，TypeScript 编译器会发出编译错误。

• noImplicitReturns

  • 是否确保函数中的所有代码路径都有返回值。
  • 默认值是false。在默认情况下，不进行隐式返回值的检查。
  • 如果设置为 true，函数中存在没有返回值的代码路径，TypeScript 编译器会发出编译错误。

• noFallthroughCasesInSwitch

  • 检查在switch语句中是否存在没有break或return等终止语句导致的“穿透”情况。
  • 默认值是false。在默认情况下，不进行“穿透”情况的检查。
  • 如果设置为 true，在switch语句中存在没有终止语句导致的“穿透”情况，TypeScript 编译器会发出编译错误。

• noUncheckedIndexedAccess

  • 是否进行严格的索引访问检查。
  • 默认值是false。在默认情况下，不进行严格的索引访问检查。
  • 如果设置为 true，代码中存在对可能未定义的索引进行访问的情况，TypeScript 编译器会发出编译错误。

示例：

interface MyObject {
  prop1: string;
  prop2: number;
}

const myArray: MyObject[] = [
  { prop1: 'value1', prop2: 1 },
  { prop1: 'value2', prop2: 2 },
];

// 不启用 noUncheckedIndexedAccess
const value1 = myArray[2].prop1; 
// 不会导致编译错误，但在运行时可能会出现 undefined 错误

// 启用 noUncheckedIndexedAccess
const value2 = myArray[2]?.prop1; 
// 使用可选链操作符来处理可能未定义的情况，否则会导致编译错误

• noImplicitOverride
  • 在子类中重写父类方法时，是否开启严格检查。
  • 默认值是false。在默认情况下，允许在子类中隐式地重写父类方法。
  • 如果设置为 true，在子类中重写父类方法时，必须使用override关键字进行明确标识，否则会导致编译错误。

示例：

class Parent {
  method(): void {
    console.log('Parent method');
  }
}

class Child extends Parent {
  // 不启用 noImplicitOverride
  method(): void {
    console.log('Child method');
  }

  // 启用 noImplicitOverride
  override method(): void {
    console.log('Child method with override');
  }
}

• noPropertyAccessFromIndexSignature
  • 是否允许通过索引签名访问对象的属性。
  • 默认值是false。在默认情况下，允许通过索引签名访问对象的属性。
  • 如果设置为 true，不能通过索引签名访问已明确声明的属性。

示例：

interface MyObject {
  name: string;
  [key: string]: string | number;
}

const obj: MyObject = {
  name: 'John',
  age: 30,
};

// 不启用 noPropertyAccessFromIndexSignature
console.log(obj['name']); 
// 不会导致编译错误，但类型推断可能不太准确

// 启用 noPropertyAccessFromIndexSignature
console.log(obj.name); 
// 正确的属性访问方式，否则会导致编译错误

• allowUnusedLabels

  • 是否允许存在未使用的标签（labels）。
  • 默认值是false。在默认情况下，不允许存在未使用的标签。如果代码中有未使用的标签，会导致编译错误。
  • 如果设置为 true，未使用的标签不会导致编译错误。

• allowUnreachableCode

  • 是否允许存在不可达的代码。
  • 默认值是false。在默认情况下，不允许存在不可达的代码。
  • 如果设置为 true，允许在代码中存在理论上不可达的代码部分。不可达的代码不会导致编译错误。

示例：

function exampleFunction(param: boolean) {
  if (param) {
    return "true case";
  } else {
    return "false case";
  }

  // 不启用 allowUnreachableCode
  console.log("This code is unreachable"); 
  // 会导致编译错误

  // 启用 allowUnreachableCode
  console.log("This code is unreachable but allowed"); 
  // 不会导致编译错误
}

Completeness

• skipDefaultLibCheck
  • 是否跳过对默认库（如lib.d.ts）的类型检查。
  • 默认值是false。在默认情况下，会对默认库进行类型检查。
  • 如果设置为 true，可以跳过对默认库的检查。

示例：

// 不启用 skipDefaultLibCheck  会被编译器检查
let str: string = "Hello";
console.log(str.toUpperCase());

// 启用 skipDefaultLibCheck  不会检查
let num: number = 123;
console.log(num.toUpperCase()); 
// 不会导致编译错误，但在运行时会抛出错误，因为 number 类型没有 toUpperCase 方法

• skipLibCheck
  • 是否跳过对所有外部库（包括默认库和自定义库）的类型检查。
  • 默认值是false。在默认情况下，会对外部库进行类型检查。
  • 如果设置为 true，可以跳过对外部库的类型检查。

示例：

// 不启用 skipLibCheck，对外部库中的函数进行调用会进行类型检查。
import { someFunction } from 'external-library';
someFunction();

// 启用 skipLibCheck
import { someOtherFunction } from 'another-external-library';
someOtherFunction(); 
// 即使外部库中存在类型错误，也不会导致编译错误，但在运行时可能会出现问题

以上是学习时的粗浅了解，如果有描述或使用不正确的地方，请各位同学多多提醒~~~