TypeScript tsconfig.json 整理

引入配置

文件相关的配置确保 TypeScript 能包含正确的文件

include

设置一个包含文件名的数组或匹配规则，指明那些文件是引入到程序中的。文件名基于包含tsconfig.json文件的路径解析

// settings
{
	"include": ["src/**/*", "tests/**/*"]
}

// results
.
├── scripts                ⨯
│   ├── lint.ts            ⨯
│   ├── update_deps.ts     ⨯
│   └── utils.ts           ⨯
├── src                    ✓
│   ├── client             ✓
│   │    ├── index.ts      ✓
│   │    └── utils.ts      ✓
│   ├── server             ✓
│   │    └── index.ts      ✓
├── tests                  ✓
│   ├── app.test.ts        ✓
│   ├── utils.ts           ✓
│   └── tests.d.ts         ✓
├── package.json
├── tsconfig.json
└── yarn.lock

默认值

如果定义了files配置，则为 [ ] ；否则为 [" ** / * "]

exclude

设置一个包含文件名的数组或匹配规则,指明忽略哪些include中的配置

exclude 仅对 include 配置中的文件生效。一个被 exclude 设置的文件依然可以被代码引入依赖，因此，这并不是一个避免文件被使用的设置，这仅仅是用来改变 include 的设置

默认值

["node_modules", "bower_components", "jspm_packages"] 和 outdir

files

设置一个包含文件名的数组，指明包含到程序中的文件。这通常应用于你仅需少量文件时，否则使用include是更好的建议

{
  "compilerOptions": {},
  "files": [
    "core.ts",
    "sys.ts",
    "types.ts",
    "scanner.ts",
    "parser.ts",
    "utilities.ts",
    "binder.ts",
    "checker.ts",
    "tsc.ts"
  ]
}

默认

false

extends

继承通用的设置。如果有重名的设置，则新定义的设置会覆盖被继承的配置。extends 配置对于大型项目的 tcsonfig.json 的复用帮助很大

{
  "compilerOptions": {
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

{
  "extends": "./configs/base",
  "files": ["main.ts", "supplemental.ts"]
}

项目配置

项目配置决定了你希望项目是如何运行的

allowJS

是否允许引入 JavaScript 文件。默认仅允许引入 .ts 和 .tsx 文件

默认

false

checkJS

是否报告 JavaScript 文件中的错误。此选项依赖 allowJS 为 true

例如，根据 TypeScript 自带的 parseFloat 类型定义，这是不正确的 JavaScript：

// parseFloat 仅接受一个字符串作为参数
module.exports.pi = parseFloat(3.124);

当引入到一个 TypeScript 模块：

// @filename: constants.js
module.exports.pi = parseFloat(3.124);

// @filename: index.ts
import { pi } from "./constants";
console.log(pi);Try

你将不会得到任何错误。但是如果你开启了 checkJs 选项，那么你可以从 JavaScript 文件中得到错误信息。

默认

false

declaration

是否要在编译时输出.d.ts文件。.d.ts 文件用于向外部模块描述API的类型定义文件。

当 declaration 设置为 true 时，用编译器执行下面的 TypeScript 代码：

export let helloWorld = "hi";Try

将会生成如下这样的 index.js 文件：

export let helloWorld = "hi";Try

以及一个相应的 helloWorld.d.ts：

export declare let helloWorld: string;

默认值

false

lib

TypeScript 包括一组默认的内建 JS 接口（例如 Math）的类型定义，以及在浏览器环境中存在的对象的类型定义（例如 document）

TypeScript 还包括与你指定的 target 选项相匹配的较新的 JS 特性的 API。例如如果target 为 ES6 或更新的环境，那么 Map 的类型定义是可用的。

最小化的依赖引入能避免下游包被污染的可能性。我们需要谨慎的选择lib需要包含的库。

高阶库

jsx

控制 JSX 在 JavaScript 文件中的输出方式。这只影响 .tsx 文件的 JS 文件输出。

react: 将 JSX 改为等价的对 React.createElement 的调用并生成 .js 文件。
react-jsx: 改为 __jsx 调用并生成 .js 文件。
react-jsxdev: 改为 __jsx 调用并生成 .js 文件。
preserve: 不对 JSX 进行改变并生成 .jsx 文件。
react-native: 不对 JSX 进行改变并生成 .js 文件。

示例代码：

export const helloWorld = () => <h1>Hello world</h1>;

默认为： "react"

export const helloWorld = () => React.createElement("h1", null, "Hello world");Try

保留: "preserve"

export const helloWorld = () => <h1>Hello world</h1>;Try

React Native: "react-native"

export const helloWorld = () => <h1>Hello world</h1>;Try

React 17 转换: "react-jsx"[1]

import { jsx as _jsx } from "react/jsx-runtime";
export const helloWorld = () => _jsx("h1", { children: "Hello world" }, void 0);Try

React 17 开发模式转换: "react-jsxdev"[1]

import { jsxDEV as _jsxDEV } from "react/jsx-dev-runtime";
const _jsxFileName = "/home/runner/work/TypeScript-Website/TypeScript-Website/packages/typescriptlang-org/index.tsx";
export const helloWorld = () => _jsxDEV("h1", { children: "Hello world" },

module

这设置了tsc编译打包的模块系统。改变module同时会影响moduleResolution

示例

// @filename: index.ts
import { valueOfPi } from "./constants";

export const twoPi = valueOfPi * 2;

CommonJS

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.twoPi = void 0;
const constants_1 = require("./constants");
exports.twoPi = constants_1.valueOfPi * 2;

UMD

(function (factory) {
    if (typeof module === "object" && typeof module.exports === "object") {
        var v = factory(require, exports);
        if (v !== undefined) module.exports = v;
    }
    else if (typeof define === "function" && define.amd) {
        define(["require", "exports", "./constants"], factory);
    }
})(function (require, exports) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    exports.twoPi = void 0;
    const constants_1 = require("./constants");
    exports.twoPi = constants_1.valueOfPi * 2;
});

AMD

define(["require", "exports", "./constants"], function (require, exports, constants_1) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    exports.twoPi = void 0;
    exports.twoPi = constants_1.valueOfPi * 2;
});

System

System.register(["./constants"], function (exports_1, context_1) {
    "use strict";
    var constants_1, twoPi;
    var __moduleName = context_1 && context_1.id;
    return {
        setters: [
            function (constants_1_1) {
                constants_1 = constants_1_1;
            }
        ],
        execute: function () {
            exports_1("twoPi", twoPi = constants_1.valueOfPi * 2);
        }
    };
});

ESNext

import { valueOfPi } from "./constants";
export const twoPi = valueOfPi * 2;Try

ES2020

import { valueOfPi } from "./constants";
export const twoPi = valueOfPi * 2;Try

None

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.twoPi = void 0;
const constants_1 = require("./constants");
exports.twoPi = constants_1.valueOfPi * 2;

默认值

如果target 为 ES3 或者 ES5，默认值为 CommonJS

如果target 为 ES6 或者更高，则默认值为 ES6/ES2015

moduleResolution

指定模块解析策略：'node' （Node.js）或 'classic' （在 TypeScript 1.6 版本之前使用）。你可能不需要在新代码中使用 classic。

默认值

如果module为AMD/UMD/System/ES6, 则为 Classic

其他情况下为 Node

noEmit

是否禁止编译生成文件。如果你想使用babel来编译TypeScript，可以设置这个选项为true

默认值

false

outDir

指定编译输出的目录。若没有指定，.js 将被生成至于生成它们的 .ts 文件相同的目录中：

$ tsc

example
├── index.js
└── index.ts

使用类似这样的 tsconfig.json：

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

使用这些配置运行 tsc 时，会将文件移动到指定的 dist 文件夹中：

$ tsc

example
├── dist
│   └── index.js
├── index.ts
└── tsconfig.json

默认值

n/a

outFile

设置打包输出至单个文件中。

除非module为None, System或AMD，否则不能使用 outFile

默认值

n/a

plugins

设置编辑器内运行的语言服务插件列表

语言服务插件是一种基于现有 TypeScript 文件向用户提供额外信息的方法。它们可以改进 TypeScript 和编辑器之间的现有信息，或提供自己的错误信息。

ts-sql-plugin — 增加了用模板字符串做 SQL 构建器时的风格检查。
typescript-styled-plugin — 在目标字符串中提供 CSS 风格检查。
typescript-eslint-language-service — 在编译器的输出中提供 eslint 的错误信息和修复信息。
ts-graphql-plugin — 在 GraphQL 查询目标字符串中提供验证和补全。

removeComments

设置当打包 JavaScript 时，忽略所有 TypeScript 文件中的注释。

例如，这是一个有 JSDoc 注释的 TypeScript 文件：

/** 'Hello world' 的葡萄牙语翻译 */
export const helloWorldPTBR = "Olá Mundo";

当然 removeComments 被设置为 true：

export const helloWorldPTBR = "Olá Mundo";Try

未设置 removeComments 或被设置为 false：

/** 'Hello world' 的葡萄牙语翻译 */
export const helloWorldPTBR = "Olá Mundo";Try

这意味着你的注释将呈现在 JavaScript 中。

默认值

false

rootDir

设定 TypeScript 打包输出的根文件目录。

这么说有点抽象。举例来说，假设你有一些输入文件：

MyProj
├── tsconfig.json
├── core
│   ├── a.ts
│   ├── b.ts
│   ├── sub
│   │   ├── c.ts
├── types.d.ts

rootDir 推断的结构是所有非声明输入文件的最长公共路径，在例子中为 core/。

如果你的 outDir 是 dist，TypeScript 将会生成这样的文件树：

MyProj
├── dist
│   ├── a.ts
│   ├── b.ts
│   ├── sub
│   │   ├── c.ts

但你可能希望让 core 成为输出目录结构的一部分。通过在 tsconfig.json 中指定 rootDir: "."，TypeScript 将会生成这样的文件树：

MyProj
├── dist
│   ├── core
│   │   ├── a.js
│   │   ├── b.js
│   │   ├── sub
│   │   │   ├── c.js

注意

rootDir 不会影响哪些文件被包含在编译中。如果设置了rootDir，但是程序又依赖了rootDir 之外的文件，这个文件会被输出至outDir外。因此，rootDir务必要保证依赖的文件都在rootDir下

sourceMap

是否生成sourcemap

默认值

false

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tsonfig.json.md

tsonfig.json.md

TypeScript tsconfig.json 整理

引入配置

include

exclude

files

extends

项目配置

allowJS

checkJS

declaration

lib

jsx

module

CommonJS

UMD

AMD

System

ESNext

ES2020

None

moduleResolution

noEmit

outDir

outFile

plugins

removeComments

rootDir

sourceMap

严格检查

Files

tsonfig.json.md

Latest commit

History

tsonfig.json.md

File metadata and controls

TypeScript tsconfig.json 整理

引入配置

include

exclude

files

extends

项目配置

allowJS

checkJS

declaration

lib

jsx

module

CommonJS

UMD

AMD

System

ESNext

ES2020

None

moduleResolution

noEmit

outDir

outFile

plugins

removeComments

rootDir

sourceMap

严格检查