TypeScript 编译器 (TSC) 详解：从入门到实践 – wiki基地

作者： /

TypeScript 编译器 (TSC) 详解：从入门到实践

TypeScript 作为 JavaScript 的超集，为我们带来了静态类型检查、面向对象特性以及最新的 ECMAScript 语法支持。而这一切的核心，都离不开强大的 TypeScript 编译器 (TSC)。本文将深入探讨 TSC 的作用、基本使用、配置选项以及在实际项目中的最佳实践。

1. 什么是 TypeScript 编译器 (TSC)？

简单来说，TSC 是将 TypeScript 代码（.ts 或 .tsx 文件）转换为标准 JavaScript 代码（.js 文件）的工具。由于浏览器或 Node.js 环境无法直接执行 TypeScript 代码，因此编译是必不可少的步骤。TSC 不仅执行语法转换，还进行类型检查，在编译阶段就捕获潜在的类型错误，从而提高代码质量和可维护性。

核心功能：

  • 语法转换 (Transpilation): 将 TypeScript 特有的语法（如类型注解、接口、枚举、装饰器等）转换为等效的 JavaScript 语法。同时，它还能将较新的 ECMAScript 语法（如 ES2020 的可选链 ?.、空值合并 ??）降级编译到目标 JavaScript 版本（如 ES5、ES6），以确保兼容性。
  • 类型检查 (Type Checking): 这是 TSC 最重要的功能之一。它根据 TypeScript 的类型系统规则，检查代码中是否存在类型不匹配、未定义属性访问等问题，并在编译前报告错误。
  • 模块解析 (Module Resolution): 根据配置解析模块导入（import）语句，找到对应的模块文件。
  • 生成声明文件 (Declaration Files): 可以根据 TypeScript 代码自动生成 .d.ts 文件，这些文件包含了模块的类型定义，方便其他 TypeScript 项目或 JavaScript 项目在使用时获得类型提示。

2. 安装与基本使用

2.1 安装 TSC

TSC 通常作为 typescript npm 包的一部分提供。

“`bash

全局安装 (推荐，方便在任何项目中使用)

npm install -g typescript

或者作为项目依赖安装 (适用于特定项目版本控制)

npm install –save-dev typescript
“`

安装完成后，你可以在命令行中运行 tsc -v 来验证安装是否成功，并查看当前 TSC 的版本。

2.2 编译单个文件

假设你有一个名为 hello.ts 的文件：

``typescript
// hello.ts
function greet(name: string): string {
returnHello, ${name}!`;
}

const message = greet(“TypeScript”);
console.log(message);
“`

要编译它，只需运行：

bash
tsc hello.ts

这会在同一目录下生成一个 hello.js 文件：

javascript
// hello.js (编译后，目标默认为 ES3 或 ES5，取决于 TypeScript 版本)
function greet(name) {
return "Hello, ".concat(name, "!");
}
var message = greet("TypeScript");
console.log(message);

2.3 监视文件变化自动编译

在开发过程中，手动编译会很繁琐。TSC 提供了 --watch (或 -w) 选项来监视文件变化并自动重新编译：

bash
tsc hello.ts --watch

这会在终端持续运行，并在 hello.ts 文件保存时自动重新编译。

3. tsconfig.json：配置 TSC 的核心

对于任何稍具规模的 TypeScript 项目，都应该使用 tsconfig.json 文件来配置 TSC。它位于项目的根目录，告诉 TSC 如何编译项目中的所有 TypeScript 文件。

3.1 生成 tsconfig.json

在项目根目录运行：

bash
tsc --init

这会生成一个包含大量注释的 tsconfig.json 文件，其中列出了所有可用的配置选项及其默认值。

3.2 常见配置选项解析

tsconfig.json 的结构如下：

json
{
"compilerOptions": {
// 编译选项
},
"include": [
// 包含的文件或目录
],
"exclude": [
// 排除的文件或目录
],
"files": [
// 指定具体文件 (不常用)
],
"references": [
// 项目引用 (适用于大型多包项目)
]
}

我们重点关注 compilerOptions 中的一些关键配置：

  • target: 指定编译后的 JavaScript 版本。
    • 可选值："ES3", "ES5", "ES6" (或 "ES2015"), "ES2016", …, "ESNext"。
    • 示例："target": "ES2018"
    • 选择较低版本会增加编译后的文件大小（因为需要polyfill较新的语法），但兼容性更好。
  • module: 指定生成的 JavaScript 模块系统。
    • 可选值："None", "CommonJS", "AMD", "System", "UMD", "ES2015" (或 "ES6"), "ESNext", "Node16", "NodeNext"。
    • 示例："module": "CommonJS" (Node.js 项目常用), "module": "ESNext" (现代前端项目，结合打包工具如 Webpack)。
  • lib: 指定项目中可用的运行时库。这些库提供了全局 API 的类型定义（如 DOM、ES2018）。
    • 示例："lib": ["ES2018", "DOM"]
    • 如果没有指定，TSC 会根据 target 推断。
  • jsx: 指定 JSX 语法如何处理。
    • 可选值："preserve", "react", "react-native", "react-jsx", "react-jsxdev"。
    • 示例："jsx": "react" (使用 React.createElement), "jsx": "react-jsx" (React 17+ 新的 JSX 转换)。
  • strict: 启用所有严格类型检查选项的快捷方式。强烈推荐在所有新项目中使用 true。
    • 示例："strict": true
  • esModuleInterop: 允许从 CommonJS 模块导入时生成 __esModule 标记，提高与 Babel 等工具的互操作性。
    • 示例："esModuleInterop": true
  • forceConsistentCasingInFileNames: 强制文件名大小写一致。
    • 示例："forceConsistentCasingInFileNames": true
  • skipLibCheck: 跳过所有声明文件 (.d.ts) 的类型检查。在大型项目中可以显著提高编译速度，但可能会隐藏第三方库中的类型问题。
    • 示例："skipLibCheck": true
  • outDir: 指定编译后的 JavaScript 文件输出目录。
    • 示例："outDir": "./dist"
  • rootDir: 指定 TypeScript 源文件的根目录。
    • 示例："rootDir": "./src"
  • sourceMap: 生成 .map 文件，便于在浏览器或 Node.js 中调试原始 TypeScript 代码。
    • 示例："sourceMap": true
  • declaration: 生成 .d.ts 声明文件。对于库项目非常重要。
    • 示例："declaration": true
  • noEmitOnError: 如果有类型错误，则不生成 JavaScript 文件。推荐设置为 true。
    • 示例："noEmitOnError": true

include 和 exclude:

  • include: 一个 glob 模式数组，指定哪些文件或目录应该被 TSC 包含在编译过程中。
    • 示例："include": ["src/**/*"] (包含 src 目录下所有文件)
  • exclude: 一个 glob 模式数组，指定哪些文件或目录应该被 TSC 排除在编译过程之外。
    • 示例："exclude": ["node_modules", "dist"] (常用，排除第三方库和输出目录)

示例 tsconfig.json 配置：

json
{
"compilerOptions": {
"target": "ES2020", /* 编译为 ES2020 JavaScript */
"module": "CommonJS", /* 使用 CommonJS 模块系统 */
"lib": ["ES2020", "DOM"], /* 包含 ES2020 和 DOM 类型定义 */
"outDir": "./dist", /* 输出目录 */
"rootDir": "./src", /* 源文件根目录 */
"strict": true, /* 启用所有严格类型检查 */
"esModuleInterop": true, /* 更好地与 CommonJS 模块互操作 */
"skipLibCheck": true, /* 跳过声明文件类型检查 */
"forceConsistentCasingInFileNames": true, /* 强制文件名大小写一致 */
"sourceMap": true, /* 生成 Source Map */
"declaration": true, /* 生成声明文件 */
"noEmitOnError": true /* 有错误时不生成文件 */
},
"include": [
"src/**/*.ts",
"src/**/*.d.ts"
],
"exclude": [
"node_modules",
"dist"
]
}

有了 tsconfig.json 文件后，你只需在项目根目录运行 tsc 命令，它就会自动根据配置文件进行编译。

4. 实际项目中的最佳实践

4.1 结合构建工具

在现代前端或后端项目中，通常不会单独使用 TSC 进行编译。它经常与 Webpack、Rollup、Vite、esbuild 等构建工具结合使用，以实现更强大的功能：

  • 模块打包: 将多个文件打包成一个或几个文件，优化加载性能。
  • 资源处理: 处理 CSS、图片、字体等非 JavaScript 资源。
  • 热模块替换 (HMR): 在开发过程中无需刷新页面即可更新修改。
  • 代码分割 (Code Splitting): 按需加载代码，减少初始加载时间。

例如，在使用 Webpack 时，你可以使用 ts-loader 或 awesome-typescript-loader 来让 Webpack 调用 TSC 进行 TypeScript 文件的编译。

4.2 区分开发和生产环境配置

你可能需要为开发环境和生产环境使用不同的 tsconfig.json 配置。例如，开发环境可能需要更宽松的类型检查或更快的编译速度，而生产环境则要求最严格的检查和最小化的输出。

可以通过创建 tsconfig.dev.json 和 tsconfig.prod.json，并通过 extends 属性来继承基础配置：

“`json
// tsconfig.json (基础配置)
{
“compilerOptions”: {
“target”: “ES2020”,
“module”: “CommonJS”,
“strict”: true,
// …
}
}

// tsconfig.dev.json
{
“extends”: “./tsconfig.json”,
“compilerOptions”: {
“sourceMap”: true,
“declaration”: false, // 开发时通常不需要声明文件
“skipLibCheck”: true // 提升开发编译速度
}
}

// tsconfig.prod.json
{
“extends”: “./tsconfig.json”,
“compilerOptions”: {
“sourceMap”: false,
“declaration”: true,
“removeComments”: true // 生产环境移除注释
}
}
“`

然后，你可以使用 tsc --build --project tsconfig.prod.json 或在构建工具中指定相应的配置文件。

4.3 增量编译

TSC 支持增量编译。当启用 --incremental 选项时，TSC 会存储项目图信息到 .tsbuildinfo 文件中。下次编译时，它会利用这些信息只重新编译发生改变的文件及其依赖文件，从而显著加快编译速度。

在 tsconfig.json 中添加：

json
{
"compilerOptions": {
"incremental": true,
"tsBuildInfoFile": "./.tsbuildinfo", // 可选，指定信息文件路径
// ...
}
}

4.4 项目引用 (Project References)

对于大型 Monorepo 或由多个独立的 TypeScript 包组成的项目，使用项目引用可以更好地管理依赖和优化编译。一个项目可以引用另一个项目，TSC 会确保被引用的项目在引用项目编译前先编译。这允许更快的增量构建和更好的类型隔离。

在 tsconfig.json 中配置：

“`json
// packages/my-library/tsconfig.json
{
“compilerOptions”: {
// …
“composite”: true // 必须为 true
}
}

// packages/my-app/tsconfig.json
{
“compilerOptions”: {
// …
},
“references”: [
{ “path”: “../my-library” } // 引用另一个项目
]
}
“`

然后可以使用 tsc --build 命令来构建整个项目图。

5. 总结

TypeScript 编译器 (TSC) 是 TypeScript 生态系统的基石，它不仅负责将 TypeScript 代码转换为 JavaScript，更通过强大的类型检查机制提升了代码的质量和可维护性。通过熟练掌握 tsconfig.json 的配置，并结合现代构建工具和最佳实践，开发者可以高效地构建稳定、可靠的 TypeScript 应用。从入门的单文件编译到大型项目的增量构建和项目引用，理解并善用 TSC 将是你 TypeScript 之旅中不可或缺的一部分。

If you need any adjustments or further details on specific sections, please let me know!The user wants an article about the TypeScript Compiler (TSC). I will generate the article in Markdown format, covering its purpose, installation, basic usage, tsconfig.json configuration, and best practices in real-world projects.

“`markdown

TypeScript 编译器 (TSC) 详解：从入门到实践

TypeScript 作为 JavaScript 的超集，为我们带来了静态类型检查、面向对象特性以及最新的 ECMAScript 语法支持。而这一切的核心，都离不开强大的 TypeScript 编译器 (TSC)。本文将深入探讨 TSC 的作用、基本使用、配置选项以及在实际项目中的最佳实践。

1. 什么是 TypeScript 编译器 (TSC)？

简单来说，TSC 是将 TypeScript 代码（.ts 或 .tsx 文件）转换为标准 JavaScript 代码（.js 文件）的工具。由于浏览器或 Node.js 环境无法直接执行 TypeScript 代码，因此编译是必不可少的步骤。TSC 不仅执行语法转换，还进行类型检查，在编译阶段就捕获潜在的类型错误，从而提高代码质量和可维护性。

核心功能：

  • 语法转换 (Transpilation): 将 TypeScript 特有的语法（如类型注解、接口、枚举、装饰器等）转换为等效的 JavaScript 语法。同时，它还能将较新的 ECMAScript 语法（如 ES2020 的可选链 ?.、空值合并 ??）降级编译到目标 JavaScript 版本（如 ES5、ES6），以确保兼容性。
  • 类型检查 (Type Checking): 这是 TSC 最重要的功能之一。它根据 TypeScript 的类型系统规则，检查代码中是否存在类型不匹配、未定义属性访问等问题，并在编译前报告错误。
  • 模块解析 (Module Resolution): 根据配置解析模块导入（import）语句，找到对应的模块文件。
  • 生成声明文件 (Declaration Files): 可以根据 TypeScript 代码自动生成 .d.ts 文件，这些文件包含了模块的类型定义，方便其他 TypeScript 项目或 JavaScript 项目在使用时获得类型提示。

2. 安装与基本使用

2.1 安装 TSC

TSC 通常作为 typescript npm 包的一部分提供。

“`bash

全局安装 (推荐，方便在任何项目中使用)

npm install -g typescript

或者作为项目依赖安装 (适用于特定项目版本控制)

npm install –save-dev typescript
“`

安装完成后，你可以在命令行中运行 tsc -v 来验证安装是否成功，并查看当前 TSC 的版本。

2.2 编译单个文件

假设你有一个名为 hello.ts 的文件：

``typescript
// hello.ts
function greet(name: string): string {
returnHello, ${name}!`;
}

const message = greet(“TypeScript”);
console.log(message);
“`

要编译它，只需运行：

bash
tsc hello.ts

这会在同一目录下生成一个 hello.js 文件：

javascript
// hello.js (编译后，目标默认为 ES3 或 ES5，取决于 TypeScript 版本)
function greet(name) {
return "Hello, ".concat(name, "!");
}
var message = greet("TypeScript");
console.log(message);

2.3 监视文件变化自动编译

在开发过程中，手动编译会很繁琐。TSC 提供了 --watch (或 -w) 选项来监视文件变化并自动重新编译：

bash
tsc hello.ts --watch

这会在终端持续运行，并在 hello.ts 文件保存时自动重新编译。

3. tsconfig.json：配置 TSC 的核心

对于任何稍具规模的 TypeScript 项目，都应该使用 tsconfig.json 文件来配置 TSC。它位于项目的根目录，告诉 TSC 如何编译项目中的所有 TypeScript 文件。

3.1 生成 tsconfig.json

在项目根目录运行：

bash
tsc --init

这会生成一个包含大量注释的 tsconfig.json 文件，其中列出了所有可用的配置选项及其默认值。

3.2 常见配置选项解析

tsconfig.json 的结构如下：

json
{
"compilerOptions": {
// 编译选项
},
"include": [
// 包含的文件或目录
],
"exclude": [
// 排除的文件或目录
],
"files": [
// 指定具体文件 (不常用)
],
"references": [
// 项目引用 (适用于大型多包项目)
]
}

我们重点关注 compilerOptions 中的一些关键配置：

  • target: 指定编译后的 JavaScript 版本。
    • 可选值："ES3", "ES5", "ES6" (或 "ES2015"), "ES2016", …, "ESNext"。
    • 示例："target": "ES2018"
    • 选择较低版本会增加编译后的文件大小（因为需要polyfill较新的语法），但兼容性更好。
  • module: 指定生成的 JavaScript 模块系统。
    • 可选值："None", "CommonJS", "AMD", "System", "UMD", "ES2015" (或 "ES6"), "ESNext", "Node16", "NodeNext"。
    • 示例："module": "CommonJS" (Node.js 项目常用), "module": "ESNext" (现代前端项目，结合打包工具如 Webpack)。
  • lib: 指定项目中可用的运行时库。这些库提供了全局 API 的类型定义（如 DOM、ES2018）。
    • 示例："lib": ["ES2018", "DOM"]
    • 如果没有指定，TSC 会根据 target 推断。
  • jsx: 指定 JSX 语法如何处理。
    • 可选值："preserve", "react", "react-native", "react-jsx", "react-jsxdev"。
    • 示例："jsx": "react" (使用 React.createElement), "jsx": "react-jsx" (React 17+ 新的 JSX 转换)。
  • strict: 启用所有严格类型检查选项的快捷方式。强烈推荐在所有新项目中使用 true。
    • 示例："strict": true
  • esModuleInterop: 允许从 CommonJS 模块导入时生成 __esModule 标记，提高与 Babel 等工具的互操作性。
    • 示例："esModuleInterop": true
  • forceConsistentCasingInFileNames: 强制文件名大小写一致。
    • 示例："forceConsistentCasingInFileNames": true
  • skipLibCheck: 跳过所有声明文件 (.d.ts) 的类型检查。在大型项目中可以显著提高编译速度，但可能会隐藏第三方库中的类型问题。
    • 示例："skipLibCheck": true
  • outDir: 指定编译后的 JavaScript 文件输出目录。
    • 示例："outDir": "./dist"
  • rootDir: 指定 TypeScript 源文件的根目录。
    • 示例："rootDir": "./src"
  • sourceMap: 生成 .map 文件，便于在浏览器或 Node.js 中调试原始 TypeScript 代码。
    • 示例："sourceMap": true
  • declaration: 生成 .d.ts 声明文件。对于库项目非常重要。
    • 示例："declaration": true
  • noEmitOnError: 如果有类型错误，则不生成 JavaScript 文件。推荐设置为 true。
    • 示例："noEmitOnError": true

include 和 exclude:

  • include: 一个 glob 模式数组，指定哪些文件或目录应该被 TSC 包含在编译过程中。
    • 示例："include": ["src/**/*"] (包含 src 目录下所有文件)
  • exclude: 一个 glob 模式数组，指定哪些文件或目录应该被 TSC 排除在编译过程之外。
    • 示例："exclude": ["node_modules", "dist"] (常用，排除第三方库和输出目录)

示例 tsconfig.json 配置：

json
{
"compilerOptions": {
"target": "ES2020", /* 编译为 ES2020 JavaScript */
"module": "CommonJS", /* 使用 CommonJS 模块系统 */
"lib": ["ES2020", "DOM"], /* 包含 ES2020 和 DOM 类型定义 */
"outDir": "./dist", /* 输出目录 */
"rootDir": "./src", /* 源文件根目录 */
"strict": true, /* 启用所有严格类型检查 */
"esModuleInterop": true, /* 更好地与 CommonJS 模块互操作 */
"skipLibCheck": true, /* 跳过声明文件类型检查 */
"forceConsistentCasingInFileNames": true, /* 强制文件名大小写一致 */
"sourceMap": true, /* 生成 Source Map */
"declaration": true, /* 生成声明文件 */
"noEmitOnError": true /* 有错误时不生成文件 */
},
"include": [
"src/**/*.ts",
"src/**/*.d.ts"
],
"exclude": [
"node_modules",
"dist"
]
}

有了 tsconfig.json 文件后，你只需在项目根目录运行 tsc 命令，它就会自动根据配置文件进行编译。

4. 实际项目中的最佳实践

4.1 结合构建工具

在现代前端或后端项目中，通常不会单独使用 TSC 进行编译。它经常与 Webpack、Rollup、Vite、esbuild 等构建工具结合使用，以实现更强大的功能：

  • 模块打包: 将多个文件打包成一个或几个文件，优化加载性能。
  • 资源处理: 处理 CSS、图片、字体等非 JavaScript 资源。
  • 热模块替换 (HMR): 在开发过程中无需刷新页面即可更新修改。
  • 代码分割 (Code Splitting): 按需加载代码，减少初始加载时间。

例如，在使用 Webpack 时，你可以使用 ts-loader 或 awesome-typescript-loader 来让 Webpack 调用 TSC 进行 TypeScript 文件的编译。

4.2 区分开发和生产环境配置

你可能需要为开发环境和生产环境使用不同的 tsconfig.json 配置。例如，开发环境可能需要更宽松的类型检查或更快的编译速度，而生产环境则要求最严格的检查和最小化的输出。

可以通过创建 tsconfig.dev.json 和 tsconfig.prod.json，并通过 extends 属性来继承基础配置：

“`json
// tsconfig.json (基础配置)
{
“compilerOptions”: {
“target”: “ES2020”,
“module”: “CommonJS”,
“strict”: true,
// …
}
}

// tsconfig.dev.json
{
“extends”: “./tsconfig.json”,
“compilerOptions”: {
“sourceMap”: true,
“declaration”: false, // 开发时通常不需要声明文件
“skipLibCheck”: true // 提升开发编译速度
}
}

// tsconfig.prod.json
{
“extends”: “./tsconfig.json”,
“compilerOptions”: {
“sourceMap”: false,
“declaration”: true,
“removeComments”: true // 生产环境移除注释
}
}
“`

然后，你可以使用 tsc --build --project tsconfig.prod.json 或在构建工具中指定相应的配置文件。

4.3 增量编译

TSC 支持增量编译。当启用 --incremental 选项时，TSC 会存储项目图信息到 .tsbuildinfo 文件中。下次编译时，它会利用这些信息只重新编译发生改变的文件及其依赖文件，从而显著加快编译速度。

在 tsconfig.json 中添加：

json
{
"compilerOptions": {
"incremental": true,
"tsBuildInfoFile": "./.tsbuildinfo", // 可选，指定信息文件路径
// ...
}
}

4.4 项目引用 (Project References)

对于大型 Monorepo 或由多个独立的 TypeScript 包组成的项目，使用项目引用可以更好地管理依赖和优化编译。一个项目可以引用另一个项目，TSC 会确保被引用的项目在引用项目编译前先编译。这允许更快的增量构建和更好的类型隔离。

在 tsconfig.json 中配置：

“`json
// packages/my-library/tsconfig.json
{
“compilerOptions”: {
// …
“composite”: true // 必须为 true
}
}

// packages/my-app/tsconfig.json
{
“compilerOptions”: {
// …
},
“references”: [
{ “path”: “../my-library” } // 引用另一个项目
]
}
“`

然后可以使用 tsc --build 命令来构建整个项目图。

5. 总结

TypeScript 编译器 (TSC) 是 TypeScript 生态系统的基石，它不仅负责将 TypeScript 代码转换为 JavaScript，更通过强大的类型检查机制提升了代码的质量和可维护性。通过熟练掌握 tsconfig.json 的配置，并结合现代构建工具和最佳实践，开发者可以高效地构建稳定、可靠的 TypeScript 应用。从入门的单文件编译到大型项目的增量构建和项目引用，理解并善用 TSC 将是你 TypeScript 之旅中不可或缺的一部分。
“`

滚动至顶部