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

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

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 和编辑器之间的现有信息，或提供自己的错误信息。

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

严格检查

上一页理解 CAP 理论，以开一家餐厅为例下一页this 陷阱与原理

最后更新于4年前

这有帮助吗？

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中的配置

默认值

["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"

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

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

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 和编辑器之间的现有信息，或提供自己的错误信息。

— 增加了用模板字符串做 SQL 构建器时的风格检查。
— 在目标字符串中提供 CSS 风格检查。
— 在编译器的输出中提供 eslint 的错误信息和修复信息。
— 在 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

注意

sourceMap

是否生成sourcemap

默认值

false

严格检查

上一页理解 CAP 理论，以开一家餐厅为例下一页this 陷阱与原理

最后更新于4年前

这有帮助吗？