OZ
oceanz.site
本页目录35

快速入门

发布于 2026-07-26

安装 TypeScript

说明 TypeScript 的项目级安装、全局安装、npm、pnpm、Yarn、Visual Studio 与 NuGet 等安装方式，并解释 VS Code、tsc 及兼容转译器之间的关系。

TypeScript 不需要像普通桌面软件一样单独下载安装。

在大多数前端和 Node.js 项目中，TypeScript 以 npm 包的形式安装。安装完成后，项目便可以使用 TypeScript 编译器 tsc 进行类型检查，并将 TypeScript 代码转换为 JavaScript。

TypeScript 官方提供三条主要安装路径：

  1. 通过 npm、pnpm 或 Yarn 安装 typescript 包；
  2. 在 Visual Studio 的 MSBuild 项目中通过 NuGet 安装；
  3. 对于不支持 NuGet 的 Visual Studio 项目，安装 TypeScript 扩展。

对于普通的 TypeScript、React、Vue、Next.js 或 Node.js 项目，通常应采用第一种方式。

安装方式概览

使用场景推荐安装方式说明
普通 TypeScript 项目npm、pnpm 或 Yarn将 typescript 安装为项目的开发依赖
临时测试 TypeScriptnpm 全局安装可以在任意目录直接运行 tsc
Visual Studio + MSBuildNuGet安装 Microsoft.TypeScript.MSBuild
不支持 NuGet 的 Visual Studio 项目Visual Studio 扩展为多个 MSBuild 项目提供 TypeScript 支持
VS Code 编辑 TypeScript通常无须额外安装扩展VS Code 内置 TypeScript 语言支持，但项目仍应安装 typescript

对于需要长期维护的项目，优先采用项目级安装。这样可以固定每个项目使用的 TypeScript 版本，并通过 lockfile 保证不同开发环境使用一致的依赖版本。

准备 Node.js

通过 npm、pnpm 或 Yarn 安装 TypeScript 时，需要先准备 Node.js。

Node.js 在这里承担两个作用：

  • 提供 npm 等 JavaScript 包管理工具；
  • 提供运行 TypeScript 编译器所需的 JavaScript 运行环境。

安装完成后，可以执行以下命令检查环境：

node --version
npm --version

能够正常输出版本号，表示 Node.js 和 npm 已经可以使用。

macOS

在 macOS 中，可以选择以下方式安装 Node.js：

  • 从 Node.js 官方网站下载安装包；
  • 使用 Homebrew 安装；
  • 使用 Node.js 版本管理工具，例如 nvm、fnm 或 Volta。

使用 Homebrew 安装：

brew install node

如果需要在多个 Node.js 版本之间切换，更适合使用版本管理工具。对于只需要完成 TypeScript 入门学习的读者，直接安装当前受支持的 Node.js LTS 版本即可。

Windows

在 Windows 中，可以选择以下方式安装 Node.js：

  • 从 Node.js 官方网站下载安装程序；
  • 使用 Windows 包管理器安装；
  • 使用 Node.js 版本管理工具，例如 nvm-windows、fnm 或 Volta。

使用 WinGet 安装 Node.js LTS：

winget install OpenJS.NodeJS.LTS

安装后重新打开 PowerShell、Windows Terminal 或命令提示符，再检查版本：

node --version
npm --version

TypeScript 在 macOS 和 Windows 中使用的是同一个 npm 包。两个操作系统的主要区别是 Node.js 的安装方式，而不是 TypeScript 本身。

项目级安装 TypeScript

项目级安装是正式项目中最常用、也最推荐的方式。

首先进入项目目录。如果还没有 package.json，可以先初始化项目：

mkdir typescript-demo
cd typescript-demo
npm init -y

然后使用 npm、pnpm 或 Yarn 中的任意一种包管理器安装 TypeScript。

使用 npm

npm install --save-dev typescript

可以简写为：

npm install -D typescript

安装完成后，typescript 会出现在 package.json 的 devDependencies 中：

{
  "devDependencies": {
    "typescript": "^7.0.0"
  }
}

实际版本以安装时 npm 解析到的版本为准，不应手动照抄示例中的版本号。

检查项目中安装的 TypeScript 版本：

npx tsc --version

执行 TypeScript 编译器：

npx tsc

npx 会优先查找并执行当前项目 node_modules/.bin 目录中的 tsc。

使用 pnpm

如果项目使用 pnpm，可以执行：

pnpm add --save-dev typescript

可以简写为：

pnpm add -D typescript

检查版本：

pnpm exec tsc --version

执行编译器：

pnpm exec tsc

在项目脚本中，也可以直接写 tsc，再通过 pnpm run 执行。

使用 Yarn

如果项目使用 Yarn，可以执行：

yarn add --dev typescript

检查版本：

yarn tsc --version

执行编译器：

yarn tsc

不同 Yarn 主版本的安装和依赖管理机制存在差异，但安装到项目中的包名仍然是 typescript。

npm、pnpm 和 Yarn 有什么区别

npm、pnpm 和 Yarn 都是 JavaScript 包管理器。它们负责从包注册表下载依赖、记录依赖版本，并根据 lockfile 恢复项目环境。

它们安装的不是三种不同的 TypeScript，而是同一个 typescript npm 包。

包管理器安装命令常见 lockfile执行项目内 tsc
npmnpm install -D typescriptpackage-lock.jsonnpx tsc
pnpmpnpm add -D typescriptpnpm-lock.yamlpnpm exec tsc
Yarnyarn add --dev typescriptyarn.lockyarn tsc

通常不应在同一个项目中混用多个包管理器。例如，一个已经使用 pnpm-lock.yaml 的项目，应继续使用 pnpm，而不是再运行 npm install 并生成 package-lock.json。

对于新建项目，可以根据团队规范或项目脚手架选择：

  • 没有特殊要求时，可以使用 Node.js 自带的 npm；
  • 已经采用 pnpm workspace 或重视磁盘复用时，可以使用 pnpm；
  • 已有 Yarn 工程或团队规范时，继续使用对应版本的 Yarn。

包管理器的选择不会改变 TypeScript 语言本身。

为什么安装到 devDependencies

TypeScript 通常只在开发、类型检查和构建阶段使用，因此一般安装为开发依赖：

npm install -D typescript

应用最终运行的通常是编译后的 JavaScript，而不是依赖 typescript 包完成业务逻辑。

因此，不推荐默认使用下面的命令：

npm install typescript

它会将 TypeScript 记录到 dependencies。这不一定导致程序错误，但通常不能准确表达 TypeScript 在项目中的用途。

安装指定版本

安装最新的稳定版本：

npm install -D typescript

安装指定版本：

npm install -D [email protected]

安装特定主版本或次版本范围：

npm install -D typescript@5
npm install -D typescript@~5.9.0

安装完成后，应提交项目生成的 lockfile，以便其他开发者和持续集成环境安装相同的依赖解析结果。

全局安装 TypeScript

TypeScript 也可以通过 npm 全局安装：

npm install --global typescript

可以简写为：

npm install -g typescript

安装完成后，可以在任意目录直接执行：

tsc --version
tsc hello.ts

全局安装适合：

  • 临时测试一个 TypeScript 文件；
  • 快速验证某个语法；
  • 不依赖具体项目版本的一次性实验。

但长期维护的项目不应只依赖全局安装。原因是不同开发者电脑中的全局 TypeScript 版本可能不同：

开发者 A：全局 TypeScript 5.x
开发者 B：全局 TypeScript 7.x
持续集成：未安装全局 TypeScript

这种差异可能导致类型检查或编译结果不一致。

因此，更稳妥的做法是：

npm install -D typescript
npx tsc

即使电脑中已经全局安装了 TypeScript，正式项目也仍然可以保留项目级的 typescript 依赖。

使用 package.json 脚本执行 TypeScript

项目级安装后，可以在 package.json 中定义脚本：

{
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "dev": "tsc --watch"
  }
}

使用 npm 执行：

npm run build
npm run typecheck
npm run dev

使用 pnpm 执行：

pnpm run build
pnpm run typecheck
pnpm run dev

使用 Yarn 执行：

yarn build
yarn typecheck
yarn dev

包管理器执行项目脚本时，会自动将项目内的 node_modules/.bin 加入命令搜索路径，因此脚本中可以直接写 tsc。

创建 TypeScript 配置文件

安装 TypeScript 后，可以执行：

npx tsc --init

该命令会在项目根目录创建 tsconfig.json。

tsconfig.json 用于描述 TypeScript 项目的编译和类型检查配置，例如：

  • 需要包含哪些源文件；
  • 输出哪一种 JavaScript 版本；
  • 使用哪一种模块系统；
  • 是否启用严格类型检查；
  • 编译结果输出到哪个目录。

安装 TypeScript 和配置 tsconfig.json 是两个不同步骤：

安装 typescript 包
        ↓
项目获得 tsc 编译器
        ↓
创建 tsconfig.json
        ↓
定义当前项目的编译规则

Visual Studio 与 NuGet

如果项目使用 Visual Studio 和 MSBuild，例如某些 ASP.NET Core 项目，可以通过 NuGet 安装 TypeScript 的 MSBuild 集成：

Install-Package Microsoft.TypeScript.MSBuild

可以通过以下入口安装：

  • 在解决方案资源管理器中右键项目，选择管理 NuGet 程序包；
  • 打开 Visual Studio 的 NuGet Package Manager Console，再执行安装命令。

这里安装的是 Microsoft.TypeScript.MSBuild，其目的主要是将 TypeScript 编译流程接入 MSBuild，而不是替代所有 Node.js 项目中的 npm 工具链。

可以将两条路线理解为：

普通前端或 Node.js 项目
└── package.json
    └── typescript npm 包
 
Visual Studio / MSBuild 项目
└── .csproj 等 MSBuild 项目文件
    └── Microsoft.TypeScript.MSBuild

对于不支持 NuGet 的 Visual Studio 项目，可以从 Visual Studio Marketplace 安装 TypeScript 扩展，并在 Visual Studio 中通过以下入口管理：

Extensions → Manage Extensions

如果一个 ASP.NET Core 项目的前端已经使用 npm、Vite、Webpack 或其他现代 JavaScript 构建工具，则通常仍应按照该前端工程自己的 package.json 安装 TypeScript，而不是因为后端使用 .NET 就必然改用 NuGet。

Visual Studio 和 VS Code 不是同一种安装方式

Visual Studio 与 Visual Studio Code 是两个不同的产品。

Visual Studio 是完整 IDE，并且可以通过 NuGet 或 Visual Studio 扩展集成 TypeScript 与 MSBuild。

VS Code 则内置了 TypeScript 和 JavaScript 的语言支持，可以提供：

  • 代码补全；
  • 类型提示；
  • 错误标记；
  • 跳转到定义；
  • 重构；
  • 自动导入。

但是，VS Code 能够识别 .ts 文件，不代表当前项目已经安装了 TypeScript 编译器。

可以将两者区分为：

VS Code 内置 TypeScript 语言服务
└── 改善编辑体验
 
项目中的 typescript 依赖
└── 提供 tsc、类型检查和编译能力

因此，使用 VS Code 开发 TypeScript 时通常无须额外搜索并安装一个普通的“TypeScript 插件”，但仍应在项目中执行：

npm install -D typescript

VS Code 还允许在内置 TypeScript 版本和项目工作区版本之间切换。正式项目通常应优先使用项目中安装的 TypeScript 版本，以保持编辑器诊断与命令行检查一致。

TypeScript 兼容转译器

除了 TypeScript 编译器 tsc，Babel、SWC 和 Sucrase 等工具也能够读取 TypeScript 文件并输出 JavaScript。

它们常用于：

  • 提高代码转换速度；
  • 沿用项目已有的构建链；
  • 将 TypeScript 与 JSX、打包、压缩等流程组合；
  • 由框架统一管理开发服务器和生产构建。

但需要区分两个概念：

类型检查
└── 判断代码是否符合 TypeScript 类型规则
 
代码转换
└── 将 TypeScript 语法转换为 JavaScript

tsc 可以同时承担类型检查和 JavaScript 输出，而 Babel、SWC、Sucrase 等工具通常只负责代码转换，不提供完整的 TypeScript 类型检查。

因此，使用兼容转译器的项目通常仍然需要安装 typescript：

npm install -D typescript

并单独执行类型检查：

npx tsc --noEmit

其中，--noEmit 表示只进行类型检查，不生成 JavaScript 文件。

Babel

Babel 是常见的 JavaScript 转译工具，可以通过 @babel/plugin-transform-typescript 处理 TypeScript 文件。

Babel 主要删除类型语法并输出 JavaScript，不会像 tsc 一样完成完整的 TypeScript 类型检查。

SWC

SWC 是使用 Rust 编写的高性能 JavaScript 和 TypeScript 转译工具，支持许多与 Babel 类似的功能。

部分框架和构建系统会在内部使用 SWC 加快代码转换，但项目仍可能通过 tsc --noEmit 或框架提供的检查命令完成类型检查。

Sucrase

Sucrase 主要面向开发环境中的快速代码转换，原生支持 TypeScript 语法。

它的目标不是完整替代 TypeScript 类型系统，而是在特定开发场景中更快地将代码转换为 JavaScript。

ts-node 和 tsx 是否属于安装方式

ts-node 和 tsx 不属于 TypeScript 编译器本身的安装方式。它们是用于在 Node.js 环境中运行 TypeScript 文件的工具。

例如安装 tsx：

npm install -D typescript tsx

运行 TypeScript 文件：

npx tsx index.ts

安装 ts-node：

npm install -D typescript ts-node

运行：

npx ts-node index.ts

它们解决的是“如何方便地运行 .ts 文件”，而这一篇讨论的核心是“如何安装 TypeScript 工具链”。因此可以将其视为运行方式的补充，而不是与 npm、NuGet 并列的安装路线。

如何选择安装方式

可以按照以下规则选择：

普通前端或 Node.js 项目

推荐项目级安装：

npm install -D typescript

或者使用项目现有的 pnpm、Yarn。

只是临时测试 TypeScript

可以全局安装：

npm install -g typescript

也可以不全局安装，直接创建一个临时项目并使用 npx tsc。

Visual Studio + MSBuild 项目

优先考虑 NuGet：

Install-Package Microsoft.TypeScript.MSBuild

不支持 NuGet 时，再使用 Visual Studio 扩展。

使用 Babel、SWC 或其他构建工具

保留项目级 typescript 依赖，并将类型检查和代码转换拆开：

npx tsc --noEmit

代码转换则由 Babel、SWC、Vite、Webpack 或框架构建命令负责。

检查安装是否成功

项目级安装后：

npx tsc --version

全局安装后：

tsc --version

如果终端提示找不到 tsc：

  1. 确认已经安装 Node.js 和 npm；
  2. 确认当前目录存在 package.json；
  3. 确认 node_modules 中已经安装 typescript；
  4. 项目级安装应使用 npx tsc、pnpm exec tsc 或项目脚本，而不是直接运行全局 tsc；
  5. 安装 Node.js 或全局包后，重新打开终端，让环境变量重新加载。

可以使用以下命令检查项目依赖：

npm ls typescript

使用 pnpm：

pnpm list typescript

使用 Yarn：

yarn why typescript

常见误区

安装 Node.js 就等于安装了 TypeScript

不是。Node.js 通常附带 npm，但 TypeScript 仍需要在项目中单独安装：

npm install -D typescript

VS Code 能提示类型，就说明项目已安装 TypeScript

不是。VS Code 内置了 TypeScript 语言支持，但项目构建仍应使用项目中声明的 TypeScript 依赖。

npm、pnpm 和 Yarn 提供不同版本的 TypeScript

不是。它们只是不同的包管理器，安装的是同一个 typescript 包。

全局安装后，所有项目都不需要再安装 TypeScript

不推荐这样做。正式项目应声明自己的 TypeScript 版本，避免依赖开发者电脑上的全局环境。

Babel 或 SWC 已经处理 .ts，就不再需要 TypeScript

通常不是。Babel 或 SWC 可以转换代码，但完整类型检查一般仍然需要 typescript 和 tsc。

推荐方案

对于大多数读者，可以直接采用以下流程：

mkdir typescript-demo
cd typescript-demo
npm init -y
npm install -D typescript
npx tsc --init
npx tsc --version

核心原则是：

Node.js 提供运行环境
        ↓
npm、pnpm 或 Yarn 安装依赖
        ↓
typescript 包提供 tsc
        ↓
tsconfig.json 定义项目编译规则

相关链接