TypeScript 速查表 on 编程那些事儿

01 起步与工具链

Fri, 27 Mar 2026 10:00:00 +0800

01 起步与工具链

本页回答两个问题：这段 TypeScript 代码怎么跑起来，以及出了问题用什么命令查。

基线：TypeScript 6.0.3，Node.js v24.20.0。所有命令输出均为实测结果。

02 类型系统主干

Fri, 27 Mar 2026 10:00:00 +0800

02 类型系统主干

本页是整套速查表的地基。any / unknown / never / {} / object 这几个概念如果没理清，后面每一页都会看不懂。

所有 ❌ TSxxxx 标注均为 TS 6.0.3 实测错误码，可去 09 错误码反查。

03 收窄与类型守卫

Fri, 27 Mar 2026 10:00:00 +0800

03 收窄与类型守卫

收窄（narrowing）是 TypeScript 最强大的能力：你写普通的 if / switch，编译器自动把宽类型缩到窄类型。

1
2
3
4
5
6


function f(v: string | number) {
 if (typeof v === "string") {
 return v.toUpperCase(); // v 已自动变成 string
 }
 return v.toFixed(2); // v 已自动变成 number
}

这一页讲清楚：什么情况下会收窄、什么情况下会失效。后者才是真正花时间的地方。

04 函数、对象与类

Fri, 27 Mar 2026 10:00:00 +0800

04 函数、对象与类

本页是日常编码里查得最频繁的一页：函数类型怎么写、类成员怎么标、对象形状怎么约束。

所有 ❌ TSxxxx 均为 TS 6.0.3 实测。

函数类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 函数声明
function add(a: number, b: number): number { return a + b; }

// 函数表达式（返回值可推断，通常省略）
const sub = (a: number, b: number) => a - b;

// 箭头函数的返回类型用括号包住参数列表
const mul = (a: number, b: number): number => a * b;

// 类型别名形式的函数类型
type BinOp = (a: number, b: number) => number;
const div: BinOp = (a, b) => a / b; // ✅ 参数类型自动继承，无需重复标 🔥

// 对象里的方法
interface Calc { add(a: number, b: number): number }

参数形态	写法	说明
必需	`(a: number)`	—
可选	`(a?: number)`	必须在必需参数之后
默认值	`(a = 10)`	类型从默认值推断；隐式可选
剩余	`(...rest: number[])`	永远是数组类型
元组剩余	`(...args: [string, number])`	参数个数固定 🔥
`this`	`(this: Window)`	假参数，不占实参位置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 用元组剩余参数约束参数个数
function log(...args: [level: string, msg: string]) { /* ... */ }
log("info", "ok"); // ✅
log("info"); // ❌ TS2554: Expected 2 arguments, but got 1.
log("info", "ok", "x"); // ❌ TS2554: Expected 2 arguments, but got 3.

// 默认值会自动变可选
function greet(name: string, greeting = "Hello") {
 return `${greeting}, ${name}`;
}
greet("A"); // ✅

⚠️ 可选参数与默认值在调用点上等价，但在类型层面有细微差别：a?: number 表示「可以传 undefined」，a = 10 表示「有默认值」。开启 exactOptionalPropertyTypes 时这个区别才会显现（更多见 08）。

05 泛型与类型推断

Fri, 27 Mar 2026 10:00:00 +0800

05 泛型与类型推断

泛型是「类型的参数」。这一页从怎么写讲到编译器怎么推，最后是条件类型与映射类型——TypeScript 类型编程的两块基石。

本页的类型推断结论用 Eq<A, B> 断言逐条实测过（tsc 6.0.3），不是推测。

06 类型层编程配方

Fri, 27 Mar 2026 10:00:00 +0800

06 类型层编程配方

02 讲的是内置工具类型，本页是自己写的常用配方——可以直接抄进项目。

本页所有配方均在 TS 6.0.3 实测编译通过，关键推断结果用 Eq<A, B> 断言验证。

07 模块系统与声明文件

Fri, 27 Mar 2026 10:00:00 +0800

07 模块系统与声明文件

TypeScript 的模块系统是最容易出错的一块：它同时要描述 ES 模块、CommonJS，还要适配各种打包器和 Node 的不同解析规则。

所有 ❌ TSxxxx 均为 TS 6.0.3 实测。

08 tsconfig 全量参考

Fri, 27 Mar 2026 10:00:00 +0800

08 tsconfig 全量参考

tsconfig.json 是 TypeScript 项目里影响最大、又最容易抄错的文件。本页按官方分类组织，重点是6.0 的变化。

本页所有「默认值」「报错码」「选项接受性」均在 TypeScript 6.0.3 用 tsc --showConfig 与真实编译实测确认。

09 诊断与错误码

Fri, 27 Mar 2026 10:00:00 +0800

09 诊断与错误码

报错看不懂时翻这一页。按错误码搜索（Ctrl+F 搜 TS2322）或按症状查找。

本页所有错误码与其原文均在 TypeScript 6.0.3 真实触发并记录。

高频错误码反查表

错误码	原文要点	常见原因	修法
`TS2322`	Type ‘X’ is not assignable to type ‘Y’	万能错误，见下	见下
`TS2345`	Argument of type ‘X’ is not assignable to parameter of type ‘Y’	实参类型不对	检查参数类型，或用守卫收窄
`TS2353`	Object literal may only specify known properties	多余属性检查	删掉多余属性 / 经变量中转 / 改类型
`TS2739`	Type ‘X’ is missing the following properties from type ‘Y’	缺属性	补齐，或改类型为 `Partial`
`TS2741`	Property ‘x’ is missing in type ‘X’ but required in type ‘Y’	缺一个必需属性	补上 🔥 穷举 `Record` 时常见
`TS2375`	…with ’exactOptionalPropertyTypes: true’	给可选属性显式传了 `undefined`	类型加 `\| undefined`，或不传该键
`TS4104`	The type ‘readonly T[]’ is ‘readonly’ and cannot be assigned to the mutable type ‘T[]’	只读数组赋给可变数组	用 `[...ro]` 复制，或改目标为 `readonly`
`TS2540`	Cannot assign to ‘x’ because it is a read-only property	改只读属性	去掉 `readonly`，或用副本

TS2322 的系统排查法——它只是「类型不符」，真正原因在下面那几行：

10 异步与错误处理

Fri, 27 Mar 2026 10:00:00 +0800

10 异步与错误处理

异步代码的类型问题集中在两处：组合子的返回类型（很多人记不清）和错误的类型建模（catch 变量为什么是 unknown）。

组合子返回类型由 Eq<A, B> 断言在 TS 6.0.3 实测确认。

11 运行时校验与边界

Fri, 27 Mar 2026 10:00:00 +0800

11 运行时校验与边界

这是整套速查表里最重要的一页。

TypeScript 的类型在运行时完全不存在。所有「外部来的数据」——HTTP 响应、JSON.parse、localStorage、环境变量、表单、URL 参数、IPC 消息——没有任何一个字节被校验过。

12 测试

Fri, 27 Mar 2026 10:00:00 +0800

12 测试

TypeScript 项目的测试有两类完全不同的测试目标：

目标	测什么	工具
行为测试	运行时行为对不对	Vitest / Jest / `node:test` / Playwright
类型测试	类型推导对不对	`expectTypeOf` / `tsd` / `expect-type`

第二类是 TypeScript 特有的，也是最容易被忽略的——泛型库的类型行为如果不测，重构时悄悄退化你都不会知道。

13 发布带类型的库

Fri, 27 Mar 2026 10:00:00 +0800

13 发布带类型的库

会写 .d.ts 不等于别人能用上你的类型。本页讲的是把类型正确交付给使用者的工程细节。

涉及解析行为的结论均在 TS 6.0.3 + moduleResolution: nodenext 实测。

`package.json` 是类型交付的核心

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "name": "mylib",
 "version": "1.0.0",
 "type": "module",
 "main": "./dist/index.js",
 "types": "./dist/index.d.ts",
 "exports": {
 ".": {
 "types": "./dist/index.d.ts",
 "default": "./dist/index.js"
 }
 },
 "files": ["dist"]
}

字段	作用	还需要吗
`types`（顶层）	老工具的类型入口	✅ 保留，兼容旧 `node10` 解析
`main`	老工具的 JS 入口	✅ 保留，兼容 CJS
`exports`	现代解析的唯一事实来源	✅ 必须有 🔥
`files`	控制发布哪些文件	✅ 别忘了 `dist`
`type`	决定 `.js` 被当作 ESM 还是 CJS	✅ 明确写

⚠️ files 忘了写 dist 会导致发布了没有产物的包——本地测试正常，装到别的项目就报 Cannot find module。这是最常见的发布事故。

14 JSX 与前端类型模式

Fri, 27 Mar 2026 10:00:00 +0800

14 JSX 与前端类型模式

本页只讲类型层面的模式——组件签名、事件类型、Hook 推断。框架用法请查框架文档。

⚠️ 涉及 React 的具体 API 时，本页基于 React 19 的 @types/react。类型包版本不同，细节可能有差异，请以你项目里实际安装的 .d.ts 为准。

15 从 JS 迁移与生态互操作

Fri, 27 Mar 2026 10:00:00 +0800

15 从 JS 迁移与生态互操作

把老 JS 项目搬上 TypeScript，难点不在语法，而在如何在不停工的前提下逐步收紧。

⚠️ 6.0 让迁移变难了一点：strict 默认变为 true、types 默认变为 []。所以从 5.x 升级或从零引入时，第一步应该是显式固定这两个选项，而不是直接吃默认值。详见 08 tsconfig。

16 血泪速查

Fri, 27 Mar 2026 10:00:00 +0800

16 血泪速查

这一页按症状索引，不是按语法索引。出问题时从「我看到的现象」出发查，比从「这是哪个语法」出发快得多。

本页所有「实际发生什么」都在 TS 6.0.3 实测过。

17 编译器与性能

Fri, 27 Mar 2026 10:00:00 +0800

17 编译器与性能

「tsc 好慢」是可以量化定位的，不用猜。本页讲清楚每个诊断指标的含义和对应的解法。

本页所有命令输出格式均在 TS 6.0.3 实测。

编译流水线

理解阶段划分，才能把「慢」定位到具体环节。

TypeScript 速查表 on 编程那些事儿

01 起步与工具链

01 起步与工具链

02 类型系统主干

02 类型系统主干

03 收窄与类型守卫

03 收窄与类型守卫

04 函数、对象与类

04 函数、对象与类

函数类型

05 泛型与类型推断

05 泛型与类型推断

06 类型层编程配方

06 类型层编程配方

07 模块系统与声明文件

07 模块系统与声明文件

08 tsconfig 全量参考

08 tsconfig 全量参考

09 诊断与错误码

09 诊断与错误码

高频错误码反查表

10 异步与错误处理

10 异步与错误处理

11 运行时校验与边界

11 运行时校验与边界

12 测试

12 测试

13 发布带类型的库

13 发布带类型的库

package.json 是类型交付的核心

14 JSX 与前端类型模式

14 JSX 与前端类型模式

15 从 JS 迁移与生态互操作

15 从 JS 迁移与生态互操作

16 血泪速查

16 血泪速查

17 编译器与性能

17 编译器与性能

编译流水线

`package.json` 是类型交付的核心