编译 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 任务的另一个好处是，你可以在问题面板中获得集成的错误和警告检测。让我们逐步完成转译一个简单的 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 构建

从全局终端菜单执行运行生成任务（⇧⌘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 构建任务定义为默认构建任务，以便在触发运行生成任务（⇧⌘B (Windows, Linux Ctrl+Shift+B)）时直接执行它。为此，请从全局终端菜单中选择配置默认生成任务。这将显示一个包含可用生成任务的选择器。选择 TypeScript tsc: build，这将生成以下 tasks.json 文件，位于 .vscode 文件夹中

{
    // 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 任务系统还可以通过问题匹配器检测构建问题。问题匹配器基于特定的构建工具解析构建输出，并提供集成的issue显示和导航。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)。

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

JavaScript 源代码地图支持

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 编译到同一位置，文件资源管理器将不再显示 JavaScript 的派生资源。

在工作区 settings.json 文件中添加带有筛选器的 files.exclude 设置，该文件位于工作区根目录的 .vscode 文件夹中。你可以通过命令面板（⇧⌘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 nightly 构建 (typescript@next) 来尝试最新的 TypeScript 功能。
• 确保你用于 IntelliSense 的 TypeScript 版本与你用于编译代码的版本相同。

当你从语言状态栏固定版本号并查看 TypeScript 文件时，活动 TypeScript 版本及其安装位置可以显示在状态栏中

如果要更改工作区中的默认 TypeScript 版本，你有几个选项

使用工作区版本的 TypeScript

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

使用此选项可在 VS Code 附带的 TypeScript 版本和你工作区中的 TypeScript 版本之间切换。你还可以使用 TypeScript: 选择 TypeScript 版本命令触发 TypeScript 版本选择器。

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

例如

{
  "typescript.tsdk": "/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。

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

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

{
  "typescript.tsdk": "./node_modules/typescript/lib"
}

typescript.tsdk 工作区设置仅告诉 VS Code 工作区版本的 TypeScript 存在。要实际开始使用工作区版本进行 IntelliSense，你必须运行 TypeScript: 选择 TypeScript 版本命令并选择工作区版本。

使用 TypeScript nightly 构建

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

此扩展程序会自动将 VS Code 的内置 TypeScript 版本替换为最新的 TypeScript nightly 构建。只需确保你切换回使用 VS Code 的 TypeScript 版本，如果你已使用 TypeScript: 选择 TypeScript 版本命令配置了 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 的更多信息。

使用项目引用分解你的项目

你可以通过使用项目引用将源代码分解为较小的项目，从而提高性能，而不是将源代码结构化为单个大型项目。这允许 TypeScript 一次仅加载你的代码库的子集，而不是加载整个代码库。

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

后续步骤

继续阅读以了解

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

常见问题

如何解决 TypeScript “无法编译外部模块”错误？

如果你收到该错误，请通过在项目的根文件夹中创建 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 中的 case 贯穿
• 并非所有代码路径都返回值

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

你可以通过在你的用户设置中设置 "typescript.reportStyleChecksAsWarnings": false 来禁用此行为。