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 文件中的错误。此选项依赖 allowJStrue

例如,根据 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。

默认值

如果moduleAMD/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

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

除非moduleNone, SystemAMD,否则不能使用 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/

如果你的 outDirdist,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

严格检查