TypeScript 安装教程：用 npm 安装并查看版本

TypeScript 是一个名为 typescript 的 npm 包。把它安装到你的项目中，然后检查它能否正常工作：

npm install --save-dev typescript
npx tsc --version

Version 7.0.2

这个包提供了 tsc 命令，也就是 TypeScript 编译器。安装它需要 Node.js 和 npm（npm 随 Node.js 一起提供）；可以从 nodejs.org 或系统的包管理器获取 Node.js，并用 node --version 检查。

想试试 TypeScript，什么都不用装。下面这段代码直接在你的浏览器里编译运行：

function add(a: number, b: number): number {
    return a + b;
}

console.log(`2 + 3 = ${add(2, 3)}`);

在项目中安装 TypeScript

推荐的方式是本地安装，作为项目的开发依赖：

mkdir hello-ts
cd hello-ts
npm init -y
npm install --save-dev typescript

npm install --save-dev typescript（简写为 npm i -D typescript）会把编译器放进 node_modules，并记录到 package.json 中：

{
    "devDependencies": {
        "typescript": "^7.0.2"
    }
}

它是开发依赖，因为只有构建代码时才需要它，运行代码时并不需要。任何人克隆项目后运行 npm install，都会得到同一个版本的编译器。

运行本地编译器时要加上 npx 前缀，它会在 node_modules/.bin 中查找命令：

npx tsc --version

在 package.json 的 scripts 中可以直接写 tsc 而不用 npx，因为 npm 会为脚本把 node_modules/.bin 加入 PATH：

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

之后 npm run build 负责编译，npm run typecheck 只检查类型、不写出任何文件。

查看 TypeScript 版本

npm ls typescript

hello-ts@1.0.0 /home/ana/hello-ts
└── typescript@7.0.2

如果 npx tsc --version 和 tsc --version 输出的版本不同，说明项目有自己的编译器，而全局的那个更旧或更新。对项目构建起作用的是项目自己的版本。

全局安装 TypeScript

全局安装后，在任何终端里都能直接使用 tsc 命令，不需要 npx：

npm install -g typescript
tsc --version

在 macOS 和 Linux 上，如果 Node.js 是系统级安装的，这一步可能会因为 EACCES 权限错误而失败。通过 nvm 或 fnm 这类版本管理器安装 Node.js 可以避免这个问题，不建议使用 sudo npm install -g。

全局命令适合快速试验。真正的项目还是要保留一个本地安装：这样 package.json 会记录版本，全局编译器的更新也不会改变项目的构建方式。

用 pnpm、Yarn 或 Bun 安装

每个 JavaScript 包管理器安装的都是同一个包：

pnpm add -D typescript
yarn add -D typescript
bun add -d typescript

分别用 pnpm tsc、yarn tsc 或 bunx tsc 运行编译器。

用 tsc --init 创建 tsconfig.json

tsconfig.json 文件把一个文件夹标记为 TypeScript 项目，并保存编译器选项。生成一个：

npx tsc --init

Created a new tsconfig.json

You can learn more at https://aka.ms/tsconfig

生成的文件（TypeScript 7）会开启 strict 和另外几项检查，使用 "module": "nodenext" 和 "target": "esnext"，并以注释形式列出 rootDir 和 outDir。取消这两行的注释，让编译器从 src 读取、向 dist 输出：

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        "strict": true
    }
}

这只是精简后的样子；真实的文件包含更多选项，每项都带注释。tsconfig 页面 解释了它们的作用。在同一个文件夹中再次运行 npx tsc --init 会报错 error TS5054: A 'tsconfig.json' file is already defined，所以它永远不会覆盖你的设置。

编译你的第一个文件

创建 src/index.ts：

function greet(name: string): string {
    return `Hello, ${name}!`;
}

const names = ["Ada", "Grace", "Linus"];
for (const name of names) {
    console.log(greet(name));
}

然后编译并运行：

npx tsc
node dist/index.js

Hello, Ada!
Hello, Grace!
Hello, Linus!

不带参数的 npx tsc 会读取 tsconfig.json，对其中包含的每个文件做类型检查，并把输出写到 dist。在生成的设置下，每个文件都会得到一个 index.js，外加 index.d.ts（类型声明）和 .map 文件（source map）。

关于输出，有两点需要知道：

• 默认情况下，类型错误不会阻止输出。 tsc 会报告错误、以非零退出码退出，但仍然写出 JavaScript。设置 "noEmitOnError": true 后，有错误时就什么都不写。
• 存在 tsconfig.json 时，不要传入文件名。 npx tsc src/index.ts 会报错 error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. 直接运行 npx tsc；如果确实想用默认设置编译单个文件，就加上 --ignoreConfig。

监视模式

--watch（简写 -w）让编译器一直运行，每当文件变化就重新编译：

npx tsc --watch

06:28:22 AM - Starting compilation in watch mode...

06:28:22 AM - Found 0 errors. Watching for file changes.

把它开在编辑器旁边的终端里。按 Ctrl+C 停止。

安装指定版本的 TypeScript

在 @ 后面写上版本：

npm install --save-dev typescript@7.0.2   # an exact version
npm install --save-dev typescript@6       # the newest 6.x
npm install --save-dev typescript@latest  # the newest stable release
npm install --save-dev typescript@next    # nightly builds of the next version

TypeScript 6 是最后一个用 JavaScript 编写编译器的版本。一些调用编译器 JavaScript API 的工具仍然需要它，TypeScript 7 页面 对此有介绍，也讲了如何升级。

编辑器配置

VS Code 内置了 TypeScript 支持：打开一个 .ts 文件，不用安装任何东西就有错误下划线、自动补全、悬停查看类型和重命名。想在编辑器里也享受 TypeScript 7 的速度，TypeScript 团队发布了一个专门的扩展，可以把 VS Code 切换到原生的 TypeScript 7 语言服务器。WebStorm 和其他 JetBrains IDE 开箱即支持 TypeScript，Neovim、Vim、Emacs、Zed 和 Sublime Text 则通过各自的 LSP 支持使用 TypeScript 语言服务器。

常见的安装错误

This is not the tsc command you are looking for。 你在没有安装 TypeScript 的文件夹中运行了 npx tsc，于是 npx 拉取了一个恰好叫 tsc 的已废弃包。用 npm install --save-dev typescript 安装真正的编译器。

tsc: command not found，或在 Windows 上提示 'tsc' is not recognized as an internal or external command。 TypeScript 没有全局安装，或者全局 npm 文件夹不在你的 PATH 中。在有本地安装的项目中使用 npx tsc，或者全局安装后打开一个新终端。

error TS2591: Cannot find name 'process'（或 require；__dirname 报的是 TS2304）。Node.js 自身 API 的类型放在一个单独的包里。用 npm install --save-dev @types/node 安装它，然后在 compilerOptions 中加上 "types": ["node"]：TypeScript 7 不再自动加载所有已安装的 @types 包。

error TS5011: The common source directory of 'tsconfig.json' is './src'。 你的文件在 src 中，设置了 outDir 却没有设置 rootDir。加上 "rootDir": "./src"。

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'。 npm init -y 会在 package.json 中写入 "type": "commonjs"，于是 tsc --init 生成的配置（"module": "nodenext" 加上 verbatimModuleSyntax）把每个 .ts 文件都当作 CommonJS，而 CommonJS 中不允许 import 和 export。把它改成 "type": "module"，并在相对导入中写上 .js 扩展名：import { add } from "./math.js"。