跳转到内容
TypeScript Book

TypeScript 入门

安装

Visual Studio Code 为 TypeScript 语言提供了出色的支持，但不包含 TypeScript 编译器。要安装 TypeScript 编译器，您可以使用包管理器，例如 npm 或 yarn：

Terminal window
npm install typescript --save-dev

或者

Terminal window
yarn add typescript --dev

确保提交生成的锁定文件，以确保每个团队成员使用相同版本的 TypeScript。

要运行TypeScript编译器，可以使用以下命令

Terminal window
npx tsc

或者

Terminal window
yarn tsc

建议按项目安装 TypeScript，而不是全局安装，因为它提供了更可预测的构建过程。但是，对于一次性情况，您可以使用以下命令：

Terminal window
npx tsc

或者安装到全局：

Terminal window
npm install -g typescript

如果您使用的是 Microsoft Visual Studio，则可以在 NuGet 中为 MSBuild 项目获取作为包的 TypeScript。在 NuGet 包管理器控制台中，运行以下命令：

Terminal window
Install-Package Microsoft.TypeScript.MSBuild

在 TypeScript 安装过程中，会安装两个可执行文件：“tsc”作为 TypeScript 编译器，“tsserver”作为 TypeScript 独立服务器。独立服务器包含编译器和语言服务，编辑器和 IDE 可以利用它们来提供智能代码补全。

此外，还有几种兼容 TypeScript 的转译器可用，例如 Babel（通过插件）或 swc。这些转译器可用于将 TypeScript 代码转换为其他目标语言或版本。

TypeScript 7.0 已用 Go 重写，作为编译器和语言服务的原生实现。它使用共享内存多线程和其他优化，使完整构建和编辑器功能更快，从而减少开发期间的反馈时间。

一些 TypeScript 7.0 性能功能可以调整。类型检查可以通过 --checkers 在并行 worker 中运行；更多 worker 可以加快大型项目，但会使用更多内存。重建后的 --watch 模式改进了跨平台文件监视。TypeScript 7.0 目前还不包含编译器 API（截至 2026 年 7 月），因此仍需要 TypeScript 6.0 API 的工具可以通过 @typescript/typescript6 或 npm 别名与 TypeScript 7.0 并行运行。

配置

可以使用 tsc CLI 选项或利用位于项目根目录中名为 tsconfig.json 的专用配置文件来配置 TypeScript。

要生成预填充推荐设置的 tsconfig.json 文件，您可以使用以下命令：

Terminal window
tsc --init

在本地执行 tsc 命令时，TypeScript 将使用最近的 tsconfig.json 文件中指定的配置来编译代码。

以下是使用默认设置运行的 CLI 命令的一些示例：

Terminal window
tsc main.ts // 将一个特定的文件 (main.ts) 编译成 JavaScript
tsc src/*.ts // 将 'src' 文件夹下任意的 .ts 文件编译成 JavaScript
tsc app.ts util.ts --outfile index.js // 将 2 个 TypeScript 文件 (app.ts 和 util.ts) 编译成 1 个 JavaScript 文件 (index.js)

TypeScript 的配置文件

tsconfig.json 文件用于配置 TypeScript 编译器 (tsc)。通常，它会与 package.json 一起放在项目根目录中。

注意：

  • tsconfig.json 即使是 json 格式也接受注释。
  • 建议使用此配置文件而不是命令行选项。

在以下链接中，您可以找到完整的文档及其配置示例：

https://www.typescriptlang.org/tsconfig

https://www.typescriptlang.org/tsconfig/

以下列出了常见且有用的配置：

target

target 属性用于指定 TypeScript 代码应输出或编译到哪个 ECMAScript 版本。对于现代浏览器，ES6 是一个不错的选择。注意：ES5 支持已在 TypeScript 6.0 中弃用，并且在 TypeScript 7.0 中不再受支持。

lib

lib 属性用于指定编译时要包含哪些库文件。TypeScript 会自动包含 target 属性所指定功能的 API，但可以根据特定需求省略或选择特定库。例如，如果您正在开发服务器项目，则可以排除 DOM 库，因为它只在浏览器环境中有用。

strict

strict 选项通过启用更严格的类型检查来提高类型安全性。从 TypeScript 6.0 开始，该选项默认启用；否则，您需要在 tsconfig.json 文件中显式将其设置为 true。启用 strict 后，TypeScript 可以：

  • 为每个源文件发出 use strict
  • 在类型检查过程中考虑 null 和 undefined
  • 在没有类型注释时禁止使用 any
  • 在使用 this 表达式时引发错误，否则 this 会被视为任意类型

module

module 属性用于设置编译器支持的模块系统。运行时，模块加载器会根据指定的模块系统查找并执行依赖项。

JavaScript 中最常用的模块加载器是用于服务器端应用程序的 Node.js CommonJS，以及用于基于浏览器的 Web 应用程序的 AMD 模块加载器 RequireJS。TypeScript 可以为各种模块系统生成代码，包括 UMD、SystemJS、ESNext、ES2015/ES6 和 ES2020。应根据目标环境以及该环境中可用的模块加载机制来选择模块系统。

注意：旧版模块系统（AMD、UMD、SystemJS）支持已在 TypeScript 6.0 中弃用，并且在 TypeScript 7.0 中不再受支持。

moduleResolution

moduleResolution 属性指定模块解析策略。对现代 TypeScript 代码使用 nodenext 或 bundler。classic 仅用于旧版本的 TypeScript（1.6 之前）。

esModuleInterop

esModuleInterop 属性允许从未导出 default 属性的 CommonJS 模块导入默认值。此选项提供兼容性，以确保生成的 JavaScript 能正常工作。启用此选项后，我们可以使用 import MyLibrary from "my-library"，而不是 import * as MyLibrary from "my-library"。

esModuleInterop 最初是可选的，以避免破坏性变更，但长期以来一直是推荐的默认设置。禁用它可能会导致在使用 CommonJS 和 ESM 时出现一些不易察觉的运行时问题。注意：从 TypeScript 6.0 开始，这种更安全的互操作行为始终启用。

在 TypeScript 6.0 中，一些较旧的配置选项和语法形式已被弃用，或经过旧行为的过渡。在 TypeScript 7.0 中，它们会成为硬错误或无操作行为。

已转变为硬错误或无操作行为的弃用项包括：

  • target: es5
  • downlevelIteration
  • moduleResolution: node/node10
  • module: amd/umd/systemjs/none
  • baseUrl
  • moduleResolution: classic
  • 禁用 esModuleInterop 或 allowSyntheticDefaultImports
  • 禁用 alwaysStrict
  • 命名空间声明中的 module 关键字
  • 导入上的 asserts
  • skipDefaultLibCheck 下的 /// <reference no-default-lib />
  • 带有本地 tsconfig.json 的 CLI 文件路径，除非使用 --ignoreConfig

jsx

jsx 属性仅适用于 React 中使用的 .tsx 文件，并控制 JSX 构造如何编译为 JavaScript。一个常见的选项是 preserve，它会编译为 .jsx 文件，保持 JSX 不变，以便可以将其传递给 Babel 等不同工具进行进一步转换。

skipLibCheck

skipLibCheck 属性会阻止 TypeScript 对导入的第三方包进行类型检查。此属性可以减少项目的编译时间。TypeScript 仍会根据这些包提供的类型定义检查您的代码。

files

files 属性向编译器指示必须始终包含在程序中的文件列表。

include

include 属性向编译器指示我们想要包含的文件列表。此属性允许类似 glob 的模式，例如 * 表示任何子目录，_ 表示任何文件名，? 表示可选字符。

exclude

exclude 属性向编译器指示不应包含在编译中的文件列表。这可以包括 node_modules 等文件或测试文件。 注意：tsconfig.json 允许注释。

importHelpers

TypeScript 在为某些高级或低级 JavaScript 功能生成代码时会使用辅助代码。默认情况下，这些辅助代码会复制到使用它们的文件中。importHelpers 选项会从 tslib 模块导入这些辅助代码，从而使 JavaScript 输出更加高效。

迁移到 TypeScript 的建议

对于大型项目，建议采用渐进式过渡，其中 TypeScript 和 JavaScript 代码最初共存。只有小型项目才适合一次性迁移到 TypeScript。

此转变的第一步是将 TypeScript 引入构建流程。这可以通过使用 allowJs 编译器选项来完成，该选项允许 .ts 和 .tsx 文件与现有 JavaScript 文件共存。由于 TypeScript 无法从 JavaScript 文件推断类型时会回退到 any，因此建议在迁移开始时在编译器选项中禁用 noImplicitAny。

第二步是确保您的 JavaScript 测试与 TypeScript 文件一起工作，以便您可以在转换每个模块时运行测试。如果您正在使用 Jest，请考虑使用 ts-jest，它允许您使用 Jest 测试 TypeScript 项目。

第三步是在项目中包含第三方库的类型声明。这些声明可以在第三方库的类型声明文件或专门的声明包中找到，您可以通过 https://www.typescriptlang.org/dt/search 搜索并安装它们：

Terminal window
npm install --save-dev @types/package-name

或者

Terminal window
yarn add --dev @types/package-name

第四步是使用自下而上的方法逐个模块地迁移，遵循从叶开始的依赖关系图。这个想法是开始转换不依赖于其他模块的模块。要可视化依赖关系图，您可以使用 madge 工具。

有一些对转换为 TypeScript 比较友好的模块（外部 API 或规范相关的实用函数和代码），比如 Swagger、GraphQL 或 JSON Schema，它们可以自动生成 TypeScript 类型定义，并在项目中使用。

当没有可用的规范或官方架构时，您可以从原始数据生成类型，例如服务器返回的 JSON。但是，建议从规范而不是数据生成类型，以避免丢失边缘情况。

在迁移过程中，不要进行代码重构，而只专注于向模块添加类型。

第五步是启用”noImplicitAny”，这将强制所有类型都是已知和定义的，从而为您的项目提供更好的 TypeScript 体验。

在迁移过程中，您可以使用 @ts-check 指令，该指令在 JavaScript 文件中启用 TypeScript 类型检查。该指令提供了宽松版本的类型检查，最初可用于识别 JavaScript 文件中的问题。当 @ts-check 包含在文件中时，TypeScript 将尝试使用 JSDoc 风格的注释来推断定义。但是，仅在迁移的早期阶段考虑使用 JSDoc 注释。

考虑在您的 tsconfig.json 文件中将 noEmitOnError 设置为 false，即使报告错误，这也将允许您输出 JavaScript 源代码。