转译 TypeScript

TypeScript 是 JavaScript 的一个带类型的超集，它可以转译为普通 JavaScript。它提供了类、模块和接口，有助于构建健壮的组件。

安装 TypeScript 编译器

Visual Studio Code 包含 TypeScript 语言支持，但不包含 TypeScript 编译器 tsc。你需要全局或在工作区中安装 TypeScript 编译器，以便将 TypeScript 源代码转译为 JavaScript (tsc HelloWorld.ts)。

安装 TypeScript 最简单的方法是通过 npm，即 Node.js 包管理器。如果你已安装 npm，可以通过以下方式在你的计算机上全局安装 (-g) TypeScript

npm install -g typescript

你可以通过检查版本或帮助信息来测试安装是否成功。

tsc --version
tsc --help

另一种选择是在你的项目中本地安装 TypeScript 编译器（npm install --save-dev typescript），这样做的好处是可以避免与你可能拥有的其他 TypeScript 项目产生潜在的冲突。

编译器与语言服务

请务必记住，VS Code 的 TypeScript 语言服务与你安装的 TypeScript 编译器是相互独立的。当你打开一个 TypeScript 文件时，可以在语言状态栏中查看 VS Code 使用的 TypeScript 版本。

在本文的后续部分，我们将讨论如何更改 VS Code 所使用的 TypeScript 语言服务版本。

tsconfig.json

通常，任何新 TypeScript 项目的第一步是添加一个 tsconfig.json 文件。tsconfig.json 文件定义了 TypeScript 的项目设置，例如编译器选项和应该包含的文件。要执行此操作，请打开你想存放源码的文件夹，并创建一个名为 tsconfig.json 的新文件。进入该文件后，IntelliSense（⌃Space (Windows, Linux Ctrl+Space)）将为你提供辅助。

一个简单的 tsconfig.json 示例如下，用于 ES5、CommonJS 模块和源映射：

{
  "compilerOptions": {
    "target": "ES5",
    "module": "CommonJS",
    "sourceMap": true
  }
}

现在，当你创建一个 .ts 文件作为项目的一部分时，我们将提供丰富的编辑体验和语法验证。

将 TypeScript 转译为 JavaScript

VS Code 通过内置的任务运行程序与 tsc 集成。我们可以利用它将 .ts 文件转译为 .js 文件。使用 VS Code 任务的另一个好处是，你可以在问题 (Problems) 面板中获得集成的错误和警告检测。让我们一起演练一下如何转译一个简单的 TypeScript Hello World 程序。

第 1 步：创建一个简单的 TS 文件

在空文件夹中打开 VS Code，创建一个 helloworld.ts 文件，并在其中放入以下代码...

let message: string = 'Hello World';
console.log(message);

要测试是否正确安装了 TypeScript 编译器 tsc 以及 Hello World 程序是否正常工作，请打开终端并输入 tsc helloworld.ts。你可以直接在 VS Code 中使用集成终端（⌃` (Windows, Linux Ctrl+`)）。

你现在应该能看到转译出的 helloworld.js JavaScript 文件。如果你安装了 Node.js，可以通过输入 node helloworld.js 来运行它。

第 2 步：运行 TypeScript 构建

从全局终端 (Terminal) 菜单中执行运行构建任务 (Run Build Task)（⇧⌘B (Windows, Linux Ctrl+Shift+B)）。如果你在前面的章节中创建了 tsconfig.json 文件，此时应该会弹出以下选择器：

选择 tsc: build 条目。这将在工作区中生成 HelloWorld.js 和 HelloWorld.js.map 文件。

如果你选择了 tsc: watch，TypeScript 编译器将会监视 TypeScript 文件的更改，并在每次更改时自动运行转译。

在底层，我们将 TypeScript 编译器作为任务运行。使用的命令是：tsc -p .

第 3 步：将 TypeScript 构建设为默认

你也可以将 TypeScript 构建任务定义为默认构建任务，这样在触发运行构建任务 (Run Build Task)（⇧⌘B (Windows, Linux Ctrl+Shift+B)）时可以直接执行它。为此，请从全局终端 (Terminal) 菜单中选择配置默认构建任务 (Configure Default Build Task)。这将显示一个可用构建任务的选择器。选择 TypeScript tsc: build，这会在 .vscode 文件夹中生成以下 tasks.json 文件：

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "type": "typescript",
            "tsconfig": "tsconfig.json",
            "problemMatcher": [
                "$tsc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

请注意，该任务包含一个 group JSON 对象，它将任务的 kind 设置为 build 并将其设为默认。现在，当你选择运行构建任务命令或按下（⇧⌘B (Windows, Linux Ctrl+Shift+B)）时，系统不会提示你选择任务，编译将直接开始。

提示： 你也可以使用 VS Code 的运行/调试功能来运行程序。关于在 VS Code 中运行和调试 Node.js 应用程序的详细信息，请参阅 Node.js 教程。

第 4 步：检查构建问题

VS Code 任务系统还可以通过问题匹配器 (problem matcher) 检测构建问题。问题匹配器会根据特定的构建工具解析构建输出，并提供集成的错误显示和导航功能。VS Code 内置了许多问题匹配器，上面在 tasks.json 中看到的 $tsc 就是 TypeScript 编译器输出的问题匹配器。

例如，如果我们的 TypeScript 文件中存在一个简单的错误（console.log 中多了一个 'g'），我们可能会从 tsc 得到以下输出：

HelloWorld.ts(3,17): error TS2339: Property 'logg' does not exist on type 'Console'.

这会显示在终端面板中（⌃` (Windows, Linux Ctrl+`)），并在终端视图下拉菜单中选择 Tasks - build tsconfig.json。

你可以在状态栏中看到错误和警告的数量。点击错误和警告图标可获取问题列表并导航到相应位置。

你也可以使用键盘打开该列表（⇧⌘M (Windows, Linux Ctrl+Shift+M)）。

提示： 任务为许多操作提供了丰富的支持。有关如何配置任务的更多信息，请查看任务 (Tasks) 主题。

JavaScript 源映射 (Source Map) 支持

TypeScript 调试支持 JavaScript 源映射。要为 TypeScript 文件生成源映射，请使用 --sourcemap 选项进行编译，或在 tsconfig.json 文件中将 sourceMap 属性设置为 true。

同时也支持内联源映射（将内容作为数据 URL 存储而不是作为独立文件），尽管目前不支持内联源码。

生成文件的输出位置

如果将生成的 JavaScript 文件与 TypeScript 源文件放在同一文件夹中，大型项目很快就会变得混乱。你可以使用 outDir 属性为编译器指定输出目录。

{
  "compilerOptions": {
    "target": "ES5",
    "module": "CommonJS",
    "outDir": "out"
  }
}

隐藏派生的 JavaScript 文件

在使用 TypeScript 工作时，你通常不想在资源管理器或搜索结果中看到生成的 JavaScript 文件。VS Code 通过 files.exclude 工作区设置提供了过滤功能，你可以轻松创建一个表达式来隐藏这些派生文件：

**/*.js: { "when": "$(basename).ts" }

该模式将匹配任何 JavaScript 文件 (**/*.js)，但前提是存在一个同名的兄弟 TypeScript 文件。如果 JavaScript 文件被编译到相同位置，资源管理器将不再显示这些派生资源。

在工作区根目录下的 .vscode 文件夹内的 settings.json 文件中添加带有过滤器的 files.exclude 设置。你可以通过命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）中的首选项：打开工作区设置 (JSON) 命令打开工作区 settings.json。

若要从 .ts 和 .tsx 源文件排除生成的 JavaScript 文件，请使用此表达式：

"files.exclude": {
    "**/*.js": { "when": "$(basename).ts" },
    "**/**.js": { "when": "$(basename).tsx" }
}

这是一个小技巧。搜索 Glob 模式被用作键。上述设置使用了两个不同的 Glob 模式来提供两个唯一的键，但搜索结果仍将匹配相同的文件。

使用较新的 TypeScript 版本

VS Code 自带了一个较新的 TypeScript 语言服务稳定版本，并默认使用它在你的工作区中提供 IntelliSense。工作区的 TypeScript 版本与用于编译 *.ts 文件的 TypeScript 版本是独立的。在大多数常见情况下，你可以直接放心使用 VS Code 内置的 TypeScript 版本进行 IntelliSense，但有时你可能需要更改 VS Code 用于 IntelliSense 的 TypeScript 版本。

执行此操作的原因包括：

• 通过切换到 TypeScript 夜间构建版 (typescript@next) 来尝试最新的 TypeScript 特性。
• 确保你用于 IntelliSense 的 TypeScript 版本与用于编译代码的版本一致。

当前的 TypeScript 版本及其安装位置可以显示在状态栏中。选择语言栏状态栏项 ({ })，然后选择 TypeScript 版本旁边的固定图标，使其保留在状态栏中。

如果你想更改工作区中的默认 TypeScript 版本，有几种方法：

使用工作区版本的 TypeScript

如果你的工作区有特定的 TypeScript 版本，你可以通过打开一个 TypeScript 或 JavaScript 文件并点击状态栏中的 TypeScript 版本号，在工作区版本和 VS Code 默认版本之间进行切换。会出现一个消息框询问 VS Code 应该使用哪个版本的 TypeScript：

使用此功能可以在 VS Code 自带的 TypeScript 版本和工作区中的 TypeScript 版本之间切换。你也可以通过TypeScript: Select TypeScript Version 命令触发 TypeScript 版本选择器。

VS Code 会自动检测工作区根目录下 node_modules 中安装的工作区 TypeScript 版本。你还可以通过在用户或工作区设置中配置 js/ts.tsdk.path，明确告诉 VS Code 使用哪个版本的 TypeScript。js/ts.tsdk.path 设置应指向包含 TypeScript tsserver.js 文件的目录。你可以使用 npm list -g typescript 查找 TypeScript 安装位置。tsserver.js 文件通常位于 lib 文件夹中。

例如

{
  "js/ts.tsdk.path": "/usr/local/lib/node_modules/typescript/lib"
}

提示： 要获取特定的 TypeScript 版本，请在 npm 安装期间指定 @version。例如，对于 TypeScript 3.6.0，你应该使用 npm install --save-dev typescript@3.6.0。要预览下一个版本的 TypeScript，请运行 npm install --save-dev typescript@next。

注意，虽然在这些示例中 js/ts.tsdk.path 指向 typescript 内部的 lib 目录，但 typescript 目录必须是一个完整的 TypeScript 安装，其中包含 TypeScript 的 package.json 文件。

你也可以通过添加指向 tsserver.js 文件所在目录的 js/ts.tsdk.path 工作区设置，告诉 VS Code 在特定工作区中使用特定版本的 TypeScript：

{
  "js/ts.tsdk.path": "./node_modules/typescript/lib"
}

js/ts.tsdk.path 工作区设置仅告知 VS Code 存在工作区版本的 TypeScript。要实际开始将工作区版本用于 IntelliSense，你必须运行 TypeScript: Select TypeScript Version 命令并选择该工作区版本。

使用 TypeScript 夜间构建版

在 VS Code 中尝试最新 TypeScript 特性的最简单方法是安装 JavaScript and TypeScript Nightly 扩展。

此扩展会自动用最新的 TypeScript 夜间构建版替换 VS Code 内置的 TypeScript 版本。如果你曾通过 TypeScript: Select TypeScript Version 命令配置过 TypeScript 版本，请务必切回使用 VS Code 的 TypeScript 版本。

混合 TypeScript 和 JavaScript 项目

可以使用混合的 TypeScript 和 JavaScript 项目。要在一个 TypeScript 项目中启用 JavaScript，你可以在 tsconfig.json 中将 allowJs 属性设置为 true。

提示： tsc 编译器不会自动检测 jsconfig.json 文件的存在。请使用 –p 参数让 tsc 使用你的 jsconfig.json 文件，例如 tsc -p jsconfig.json。

大型项目开发

如果你在一个拥有成百上千个 TypeScript 文件的代码库中工作，以下是一些可以提高 VS Code 编辑体验和命令行编译速度的方法。

确保你的 tsconfig 仅包含你关心的文件

在项目的 tsconfig.json 中使用 include 或 files，确保项目仅包含应作为项目一部分的文件。

更多信息关于如何配置项目的 tsconfig.json。

使用项目引用 (Project References) 分割项目

与其将源代码构建为单个庞大的项目，不如通过使用项目引用将其拆分为较小的项目，从而提高性能。这允许 TypeScript 每次仅加载代码库的一个子集，而不是一次性加载全部。

请参阅 TypeScript 文档以获取有关如何使用项目引用及最佳实践的详细信息。

后续步骤

继续阅读以了解：

• 编辑 TypeScript - TypeScript 的特定编辑功能。
• 重构 TypeScript - TypeScript 语言服务提供的有用重构。
• 调试 TypeScript - 为您的 TypeScript 项目配置调试器。

常见问题

如何解决 TypeScript “无法编译外部模块 (Cannot compile external module)” 错误？

如果你遇到该错误，通过在项目的根文件夹中创建一个 tsconfig.json 文件来解决它。tsconfig.json 文件允许你控制 Visual Studio Code 如何编译你的 TypeScript 代码。有关更多信息，请参阅 tsconfig.json 概览。

为什么我在 VS Code 中得到的错误和警告与编译 TypeScript 项目时看到的不同？

VS Code 自带了一个较新的 TypeScript 语言服务稳定版本，它可能与你计算机上全局安装或工作区内本地安装的 TypeScript 版本不匹配。因此，你可能会看到编译器输出与活动 TypeScript 语言服务检测到的错误之间存在差异。有关安装匹配的 TypeScript 版本的详细信息，请参阅使用较新的 TypeScript 版本。

我可以使用 VS 2022 自带的 TypeScript 版本吗？

不能，Visual Studio 2019 和 2022 附带的 TypeScript 语言服务与 VS Code 不兼容。你需要从 npm 安装一个独立的 TypeScript 版本。

为什么有些错误报告为警告？

默认情况下，VS Code TypeScript 会将代码风格问题显示为警告而不是错误。这适用于：

• 变量已声明但从未使用
• 属性已声明但从未读取其值
• 检测到不可达代码
• 未使用的标签
• Switch 语句中的穿透 (Fall through) 情况
• 并非所有代码路径都返回值

将这些视为警告与其他工具（如 TSLint）一致。当你从命令行运行 tsc 时，它们仍会显示为错误。

你可以通过在用户设置中将 "js/ts.reportStyleChecksAsWarnings": false 设置为 false 来禁用此行为。