TypeScript 速查表

TypeScript 速查表

这不是教程，是字典。教程教你走路，字典只在你卡住时递上一根拐杖。所以本页写得密、写得短、写得没什么耐心——每一条都假设你已经会编程，只是记不清 TypeScript 里这个动作该怎么写。

风格上参考 Rust Language Cheat Sheet，但内容完全按 TypeScript 重写：TS 的类型系统是图灵完备的、类型在运行时完全不存在、结构化类型带来了一堆「看起来能过、其实错得离谱」的兼容，还有一整套只存在于类型层面的编程技巧。照搬没有意义，该不一样的地方就让它不一样。

版本基线：TypeScript 6.0.3（本机 tsc --version 实测），示例默认按 TS 6.0 的新默认值编写——strict 已默认开启、target 已默认 ES2025。凡 TS 5.x 才引入的特性标 🆕，凡 6.0 中已废弃的写法标 🗑️ 并给出替代方案。

图例说明

关于 // ✅ / // ❌ 注解：它们标的是编译器实际行为。标 // ❌ TS2322: 的地方写的是真实错误码，可以在 09 诊断与错误码 里反查。注释使用中文，但代码标识符与报错原文保持英文，方便直接搜索。

目录导航

第一层：语法主干

第二层：工程与配置

第三层：落地场景

心智模型：先建立这五条

TypeScript 的坑，九成来自没建立下面这几个模型。先把它们背下来，往后每一页都会轻松很多。

一、类型在运行时不存在

这是最重要的一条。tsc 做的所有事情——检查、推断、报错——都发生在编译期；它产出的 JavaScript 里一个类型都不剩。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

interface User { name: string; age: number }

function greet(u: User) {
  return `Hello, ${u.name.toUpperCase()}`;
}

// 编译产物（注意类型标注全部消失）
// function greet(u) {
//   return `Hello, ${u.name.toUpperCase()}`;
// }

推论（每一条都导致过生产事故）：

这就是为什么本速查表专门有 11 运行时校验与边界——类型系统管不到数据入口，那一层只能靠运行时校验。💭

二、结构化类型：看形状，不看名字

TS 用的是结构化类型（structural typing），也叫「鸭子类型」：只要形状对得上，就认为类型兼容，类型叫什么名字、在哪定义的都不重要。

1
2
3
4

interface Point { x: number; y: number }
class Vec2 { constructor(public x: number, public y: number) {} }

const v: Point = new Vec2(1, 2);   // ✅ 合法！Vec2 从没声明 implements Point

这跟 Java/C#/Swift 的名义类型（nominal typing）截然相反，好处是灵活，代价是：

三、类型空间与值空间是两套东西

同一个名字 Foo 可以同时是类型和值，也可以只是其中之一。理解这个能解释大量「为什么这里写得那里写不得」：

1
2
3
4
5
6
7
8
9

interface Foo { a: number }        // 只有类型空间有 Foo
const Foo = { a: 1 };              // 值空间也有 Foo（与上面同名，互不冲突）
type T = Foo;                      // ✅ 用类型
const v = Foo;                     // ✅ 用值

class Bar { a = 1 }                // Bar 同时在两个空间
type TB = Bar;                     // ✅ 类型
const b = new Bar();               // ✅ 值
type I = InstanceType<typeof Bar>; // ✅ 从值空间取回类型

最典型的踩坑是 typeof 有两副面孔：

1
2
3
4

const config = { host: "localhost", port: 8080 };

type Config = typeof config;   // { host: string; port: number }
type Wrong  = typeof config === "object";  // ❌ 类型位置不能写比较表达式

四、类型注解是约束，不是保证

1

const data: User = await res.json();  // ⚠️ 这里没有任何检查发生

res.json() 返回 any，把 any 赋给 User 不会报错，因为 any 可以赋给任何类型。运行时数据长什么样，TS 一无所知。

安全与不安全的入口对照：

五、TS 是不完备的：有漏洞，也有误报

TS 的设计目标里明确写着「不追求类型系统完备性」，它优先考虑的是「能很好地描述 JavaScript 里真实存在的模式」。所以：

对待漏洞的正确态度：知道它们在哪，用在明确知道安全的边界上，而不是当成日常工具。as 用多了，你就只是写了个带注解的 JavaScript。💭

你好，TypeScript

先让第一行代码跑起来。TS 本身不能直接运行——它要么被编译成 JS，要么由运行时/工具即时擦除类型。

• tsc 编译（最标准）
• Node 原生运行 🆕
• tsx / ts-node（开发期）
• 打包器 / 测试运行器

1
2
3
4

npm install -D typescript
npx tsc --init              # 生成 tsconfig.json
npx tsc                     # 按 tsconfig 编译
node dist/index.js          # 运行产物

1

npx tsc --noEmit            # 只检查，不输出任何文件

1

node index.ts               # 直接运行，无需任何依赖

1

node --experimental-transform-types index.ts

1
2
3

npx tsx index.ts            # 推荐：基于 esbuild，快，ESM 支持好
npx ts-node index.ts        # 老牌，配置项多，ESM 支持历史上比较绕
npx ts-node --esm index.ts  # ESM 模式（新版可省略）

「零配置」下 TS 6.0 已经替你开了什么

6.0 最大的变化之一是默认值大幅变严。如果你不写 tsconfig.json（或写个空的 {}），实际生效的是这些——全部在 TS 6.0.3 实测：

types 这一条最坑：6.0 起不再自动把 node_modules/@types 下所有包塞进全局，于是升级后常见「突然找不到 process / Buffer / describe」：

1
2
3
4
5

// ❌ 升级 6.0 后报：Cannot find name 'process'
{ }

// ✅ 显式声明要哪些全局类型包
{ "compilerOptions": { "types": ["node"] } }

完整的 6.0 废弃与默认值变更清单，连同可直接抄的配置模板，都在 08 tsconfig 全量参考。

TypeScript 6.0 废弃速览

这些在 6.0 里已经报错（不是警告），必须改。报错码：TS5101（选项废弃）、TS5107（取值废弃）。

临时续命（仅作迁移过渡，7.0 会彻底移除）：

1

{ "compilerOptions": { "ignoreDeprecations": "6.0" } }

官方迁移信息汇总：tsc 报错里会直接给出 https://aka.ms/ts6 📘

版本时间线速查

怎么用这份速查表