Typescript学习教程，从入门到精通，TypeScript 配置管理与编译器详解（19）

TypeScript 配置管理与编译器详解

本文将详细介绍 TypeScript 的配置管理与编译器相关知识，包括安装编译器、编译选项、tsconfig.json 配置、工程引用等，并结合具体案例代码进行说明。

---

一、TypeScript 编译器安装与使用

1. 安装编译器

TypeScript 编译器 (tsc) 可以通过 npm 全局或本地安装：

# 全局安装 TypeScript 编译器
npm install -g typescript

# 或者在项目中本地安装
npm install --save-dev typescript

2. 编译程序

安装完成后，可以使用 tsc 命令进行编译：

# 编译单个文件
tsc app.ts

# 编译并输出到指定目录
tsc app.ts --outDir dist

# 编译整个项目（根据 tsconfig.json）
tsc

3. 编译选项

TypeScript 提供了丰富的编译选项，用于控制编译过程和行为。可以通过命令行参数或配置文件 (tsconfig.json) 进行设置。

常用编译选项：

• --target 或 -t：指定 ECMAScript 目标版本（如 ES5, ES6）。
• --module 或 -m：指定模块系统（如 commonjs, amd, es6）。
• --strict：启用所有严格类型检查选项。
• --outDir：指定输出目录。
• --sourceMap：生成源映射文件。
• --noImplicitAny：在表达式和声明上有隐含的 any 类型时报错。

4. 编译选项风格

编译选项可以通过命令行参数或 tsconfig.json 文件进行设置。推荐使用 tsconfig.json 进行配置，以便更好地管理项目。

---

二、tsconfig.json 配置详解

tsconfig.json 是 TypeScript 项目的配置文件，定义了编译选项、包含的文件、排除的文件等。

1. 使用配置文件

在项目根目录创建 tsconfig.json 文件：

{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist",
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

2. 编译选项列表

以下是一些常用的 compilerOptions：

• target: 指定 ECMAScript 目标版本（如 ES5, ES6）。
• module: 指定模块系统（如 commonjs, amd, es6）。
• strict: 启用所有严格类型检查选项。
• outDir: 指定输出目录。
• sourceMap: 生成源映射文件。
• noImplicitAny: 在表达式和声明上有隐含的 any 类型时报错。
• jsx: 指定 JSX 代码的生成方式（如 react）。
• allowJs: 允许编译 JavaScript 文件。

3. 编译文件列表

使用 include 和 exclude 来指定需要编译的文件和排除的文件。

{
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

4. 声明文件列表

使用 files 指定需要编译的具体文件：

{
  "files": ["index.ts", "utils.ts"]
}

5. 继承配置文件

可以通过 extends 继承其他配置文件：

{
  "extends": "./configs/base.json",
  "compilerOptions": {
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

6. 工程引用

工程引用允许将大型项目拆分为多个子项目，每个子项目有自己的 tsconfig.json，并通过 references 进行引用。

示例：

项目结构：

project/
├── tsconfig.json
├── packages/
│   ├── utils/
│   │   ├── tsconfig.json
│   │   └── index.ts
│   └── app/
│       ├── tsconfig.json
│       └── index.ts

packages/utils/tsconfig.json:

{
  "compilerOptions": {
    "composite": true,
    "outDir": "../../dist/utils",
    "rootDir": "."
  },
  "include": ["index.ts"]
}

packages/app/tsconfig.json:

{
  "compilerOptions": {
    "composite": true,
    "outDir": "../../dist/app",
    "rootDir": ".",
    "module": "commonjs",
    "target": "ES6"
  },
  "references": [
    {
      "path": "../utils"
    }
  ],
  "include": ["index.ts"]
}

项目根目录 tsconfig.json:

{
  "files": [],
  "references": [
    {
      "path": "./packages/utils"
    },
    {
      "path": "./packages/app"
    }
  ]
}

7. --build 与 solution 模式

使用 tsc --build（简称 tsc -b）可以构建多个工程。solution 模式允许在根目录的 tsconfig.json 中管理多个子工程。

示例：

tsc --build

这将根据根目录的 tsconfig.json 构建所有引用的子工程。

---

三、JavaScript 类型检查与编译

1. 编译 JavaScript

TypeScript 编译器可以编译 JavaScript 文件，但需要启用 allowJs 选项。

tsconfig.json:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "outDir": "./dist",
    "target": "ES6",
    "module": "commonjs"
  },
  "include": ["src/**/*"]
}

2. JavaScript 类型检查

通过 checkJs 选项，可以在编译 JavaScript 文件时进行类型检查。

示例：

src/index.js:

// @ts-check
const greet = (name) => {
  console.log(`Hello, ${name}!`);
};

greet(123); // Error: Argument of type '123' is not assignable to parameter of type 'string'.

3. JSDoc 与类型

在 JavaScript 中使用 JSDoc 注释来提供类型信息。

示例：

src/utils.js:

/**
 * Adds two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
  return a + b;
}

module.exports = { add };

src/index.js:

// @ts-check
const { add } = require('./utils');

console.log(add(2, 3)); // 5
console.log(add('2', '3')); // Error: Argument of type 'string' is not assignable to parameter of type 'number'.

4. 三斜线指令

三斜线指令用于在 TypeScript 文件中引入声明文件或模块。

常用三斜线指令：

• /// <reference path="" />: 引入声明文件。
• /// <reference types="" />: 引入类型声明包。
• /// <reference lib="" />: 引入内置库声明。

示例：

src/index.ts:

/// <reference path="./globals.d.ts" />

/// <reference types="node" />

/// <reference lib="es2015" />

function greet(name: string): void {
  console.log(`Hello, ${name}!`);
}

greet("World");

src/globals.d.ts:

declare var global: any;

---

四、案例代码

1. 基本编译示例

项目结构：

project/
├── tsconfig.json
├── src/
│   ├── index.ts
│   └── utils.ts

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist",
    "sourceMap": true
  },
  "include": ["src/**/*"]
}

src/index.ts:

import { greet } from './utils';

greet("World");

src/utils.ts:

export function greet(name: string): void {
  console.log(`Hello, ${name}!`);
}

编译命令：

tsc

输出：

Hello, World!

2. 工程引用示例

项目结构：

project/
├── tsconfig.json
├── packages/
│   ├── utils/
│   │   ├── tsconfig.json
│   │   └── index.ts
│   └── app/
│       ├── tsconfig.json
│       └── index.ts

packages/utils/tsconfig.json:

{
  "compilerOptions": {
    "composite": true,
    "outDir": "../../dist/utils",
    "rootDir": "."
  },
  "include": ["index.ts"]
}

packages/utils/index.ts:

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

packages/app/tsconfig.json:

{
  "compilerOptions": {
    "composite": true,
    "outDir": "../../dist/app",
    "rootDir": ".",
    "module": "commonjs",
    "target": "ES6",
    "strict": true
  },
  "references": [
    {
      "path": "../utils"
    }
  ],
  "include": ["index.ts"]
}

packages/app/index.ts:

/// <reference types="node" />

import { add } from '../utils';

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

项目根目录 tsconfig.json:

{
  "files": [],
  "references": [
    {
      "path": "./packages/utils"
    },
    {
      "path": "./packages/app"
    }
  ]
}

编译命令：

tsc --build

输出：

5

3. JavaScript 类型检查示例

项目结构：

project/
├── tsconfig.json
├── src/
│   ├── index.js
│   └── utils.js

tsconfig.json:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "outDir": "./dist",
    "target": "ES6",
    "module": "commonjs"
  },
  "include": ["src/**/*"]
}

src/index.js:

// @ts-check
const { add } = require('./utils');

console.log(add(2, 3));
console.log(add('2', '3')); // Error: Argument of type 'string' is not assignable to parameter of type 'number'.

src/utils.js:

/**
 * Adds two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
  return a + b;
}

module.exports = { add };

编译命令：

tsc

输出：

5
error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

---

五、总结

本文详细介绍了 TypeScript 的配置管理与编译器相关知识，包括安装编译器、编译选项、tsconfig.json 配置、工程引用以及 JavaScript 类型检查等。通过具体的案例代码和详细注释，帮助读者更好地理解和应用这些知识。