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": {