07.4 阶段 3:TypeScript 工程化
所属:全栈开发面试题库 / 学习路径 / 07 Node.js 全栈
本页目录
一、阶段定位
阶段 2 解决了"代码怎么拆成模块、依赖怎么装",但代码还是 JavaScript——类型错误要到运行时才暴露。本阶段引入 TypeScript:在 Node 项目里落地类型安全,掌握 tsconfig 关键项、类型系统基础与构建工具取舍。这是从"能跑"到"可维护"的分水岭。
与前后阶段的衔接:往上接 阶段 2 模块体系与包管理,tsconfig.json 的 moduleResolution 直接决定按 CJS 还是 ESM 规则解析,不理解模块体系会看不懂 tsconfig。往下接 阶段 4 Web 框架主线,NestJS 是重度 TypeScript 框架,没有本阶段基础会卡在装饰器与 DI 上。
本阶段原有的四个卡点,展开成可判断的现象依据:
- strict 关闭后到处用 any,类型形同虚设。判断标准:代码里
: any满天飞,tsc不报错但实际运行时类型错;或干脆"strict": false把整个检查关掉。 - paths 别名只配了 tsconfig 没配运行时解析。判断标准:tsconfig 配了
@/utils,tsc编译通过,但node dist/app.js报Cannot find module '@/utils'。 - 把类型体操当目的,业务代码可读性下降。判断标准:业务函数返回类型写了三层嵌套条件类型,新人接手看不懂,而其实用一个接口或泛型就够了。
- 混淆类型编译与类型擦除的时机。判断标准:以为
interface会编译成运行时代码;写typeof x以为是运行时typeof;或问"泛型在运行时怎么获取类型"。
二、阶段目标与投入
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
| 能写一个 strict 模式通过的 tsconfig.json,关键项都理解 | tsc --noEmit 0 错误 |
| 能用类型收窄让联合类型在分支里被收窄到具体类型 | 写一个 typeof x === "string" 分支内访问字符串方法 |
能写带约束的泛型函数,能解释 extends 约束 |
写一个 getProp<T, K extends keyof T> 函数 |
| 能写一个条件类型并解释推断过程 | 写 type MaybeArray<T> = T | T[],能讲清何时用 |
| 能为函数与模块写 d.ts,能消费第三方类型包 | import lodash from "lodash" 有类型提示 |
| 能说明 tsc 与 esbuild/tsup 的分工,类型检查单独跑 | 构建用 esbuild,检查用 tsc --noEmit |
建议学时:
- 全职(每天 4–6 小时):2 周,约 55 小时。tsconfig 10 小时、类型收窄与 strict 10 小时、泛型 15 小时、条件/映射类型与工具类型 10 小时、d.ts 与构建工具 10 小时。
- 在职(每天 2 小时):5–6 周。泛型与条件类型是面试重灾区,要留够。
学时分配建议:tsconfig 15%、类型收窄 15%、泛型 25%、条件类型与工具类型 20%、d.ts 与类型包 10%、构建工具取舍 15%。
三、先修自检
| 先修项 | 合格标准 | 不合格时回到 |
|---|---|---|
| JavaScript 语法 | 能写函数、对象、数组、async/await | 07.1 阶段 0 |
| 模块体系 | 知道 CJS 与 ESM 差异 | 07.3 阶段 2 |
| Node 基本运行 | node script.js 正常 |
07.1 阶段 0 |
| npm 安装 | npm install 正常 |
07.3 阶段 2 |
| 命令行 | 会跑 npx | 07.1 阶段 0 |
四、知识地图
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| tsconfig | target、strict、moduleResolution、paths、outDir、sourceMap |
能讲清原理 | 03.3 TypeScript |
| 类型收窄 | typeof、instanceof、in、字面量收窄、可辨识联合 |
会用 | 03.3 TypeScript |
| 泛型 | T、extends 约束、keyof、默认类型 |
能讲清原理 | 03.3 TypeScript |
| 条件类型 | T extends U ? X : Y、分布式条件 |
能讲清原理 | 03.3 TypeScript |
| 映射类型 | [K in keyof T]、as 重映射 |
会用 | 03.3 TypeScript |
| infer | 在条件类型里推断位置 | 会用 | 03.3 TypeScript |
| 工具类型 | Partial、Required、Pick、Omit、ReturnType |
会用 | 03.3 TypeScript |
| d.ts | 类型声明、declare、第三方类型包 |
会用 | 03.3 TypeScript |
| 构建工具 | tsc、esbuild、tsup、swc、tsc --noEmit |
会用 | 03.3 TypeScript |
进度管理建议:tsconfig、泛型、条件类型必须到"能讲清原理",其余到"会用"。类型体操是工具不是目的,业务代码优先用接口与工具类型。
五、分模块精讲
5.1 tsconfig 关键项
为什么需要它:tsconfig.json 决定 TypeScript 怎么编译、检查哪些项、按什么规则解析模块。配错一个 moduleResolution,整个项目就跑不起来。
核心机制:
target:编译成哪个 JS 版本。Node LTS 用ES2022即可,Node 20+ 支持 ES2023。module:输出模块格式。Node 用 ESM 选NodeNext(或ESNext),CJS 选CommonJS。moduleResolution:怎么解析模块。Node 项目用NodeNext(按 Node 真实规则);旧选项node是 CJS 规则、bundler是给打包器用的。strict:总开关,打开后所有严格检查开启。包含noImplicitAny、strictNullChecks、strictFunctionTypes等。生产项目必须开。paths+baseUrl:路径别名,如@/utils/*映射到src/utils/*。只影响类型检查与 tsc 编译输出,运行时不生效。outDir:编译输出目录;rootDir:源码根目录。sourceMap:生成.map文件,调试用。esModuleInterop:允许import express from "express"这种默认导入 CJS 模块的写法,必须开。
最小可运行示例:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"outDir": "dist",
"rootDir": "src",
"sourceMap": true,
"resolveJsonModule": true,
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
},
"include": ["src/**/*"]
}
# 只检查不输出(CI 用)
tsc --noEmit
# 编译输出
tsc
# 运行
node dist/app.js
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
node dist/app.js 报 Cannot find module '@/utils' |
paths 别名运行时不解析 | 用 tsconfig-paths 或改相对路径,或用 tsup 打包 |
moduleResolution 与 module 不匹配 |
NodeNext 配错 | 两者都用 NodeNext |
strictNullChecks 关了 |
类型形同虚设 | 打开 strict,逐个修 |
CJS 模块 import express from 报错 |
没开 esModuleInterop | 加 "esModuleInterop": true |
面试考法:"tsconfig 里 strict 包含哪些检查""moduleResolution 怎么选"。答到 noImplicitAny、strictNullChecks、strictFunctionTypes;Node 项目用 NodeNext。
5.2 类型收窄与 strict
为什么需要它:TypeScript 的价值在于"知道某个分支里变量是什么类型"。不会收窄,联合类型永远停留在 A | B,你什么都访问不了。
核心机制:
typeof x === "string":把收窄到 string。x instanceof Date:收窄到 Date。"prop" in x:收窄到有该属性的类型。- 可辨识联合:成员都有一个字面量字段(如
type: "a" | "b"),按该字段 switch 即可收窄。 - strictNullChecks:
string | null在访问方法前必须先判 null。 - 非空断言
x!:告诉编译器"这里 x 不是 null",但它不做运行时检查,乱用就是 bug。
最小可运行示例:
type Shape =
| { kind: "circle"; radius: number }
| { kind: "rect"; width: number; height: number };
function area(s: Shape): number {
switch (s.kind) {
case "circle":
return Math.PI * s.radius * s.radius; // s 被收窄到 circle
case "rect":
return s.width * s.height; // s 被收窄到 rect
}
}
// strictNullChecks
function greet(name: string | null) {
if (name === null) name = "guest";
console.log(name.toUpperCase()); // 收窄后是 string
}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
s 在分支里访问不了属性 |
没收窄 | 加 switch 按可辨识字段 |
Cannot read property of null |
非空断言 ! 乱用 |
加真实 null 判断 |
| 联合类型无法访问共有属性 | 两类型没有共有字段 | 用类型守卫或拆分函数 |
面试考法:"什么是可辨识联合""typeof 与 instanceof 收窄区别"。答到字面量字段 + switch;typeof 判原始类型,instanceof 判类实例。
5.3 泛型与约束
为什么需要它:泛型让函数既能接受任意类型,又保留输入输出类型的对应关系。不会泛型,就写不出 getUserById(id): Promise<User> 这种有类型的函数。
核心机制:
<T>是类型参数,调用时由实参推断。T extends U约束 T 必须是 U 的子类型。keyof T:取 T 的所有键的联合类型。T[K]:索引访问,取 T 在 K 位置的类型。- 默认类型:
T = string。
最小可运行示例:
// 取对象属性,保留返回类型
function getProp<T, K extends keyof T>(obj: T, key: K): T[K] {
return obj[key];
}
const user = { name: "Ann", age: 18 };
const name = getProp(user, "name"); // type: string
const age = getProp(user, "age"); // type: number
// getProp(user, "email"); // 报错:"email" 不在 keyof T 里
// 泛型约束:要求参数有 length
function logLength<T extends { length: number }>(x: T): T {
console.log(x.length);
return x;
}
logLength("hello"); // 5
logLength([1,2,3]); // 3
// logLength(123); // 报错:number 没有 length
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
T 被推断成 {} 失去类型 |
没加约束 | 用 T extends ... 限制 |
函数返回 any |
没写泛型返回类型 | 显式写 <T> 或让推断 |
keyof T 报错 |
T 不是对象类型 | 约束 T extends object |
面试考法:"泛型 extends 与 interface extends 区别""keyof 怎么用"。答到约束类型参数与继承接口;keyof 取键联合。
5.4 条件类型、映射类型与 infer
为什么需要它:工具类型(Partial、Pick 等)全是条件类型与映射类型实现的。理解它们,才能读懂类型库、写自己的高级类型。
核心机制:
- 条件类型:
T extends U ? X : Y,T 满足 U 取 X,否则取 Y。 - 分布式条件:T 是联合类型时,会逐个成员分发判断。
- 映射类型:
{ [K in keyof T]: NewType },遍历 T 的键重写。 infer:在条件类型里推断位置,常用于提取函数返回类型、Promise 类型。
最小可运行示例:
// 条件类型:判断是否是数组
type IsArray<T> = T extends Array<infer U> ? true : false;
type A = IsArray<number[]>; // true
type B = IsArray<string>; // false
// infer 提取 Promise 类型
type Awaited2<T> = T extends Promise<infer U> ? U : T;
type C = Awaited2<Promise<number>>; // number
// 映射类型:把所有属性变可选
type Partial2<T> = { [K in keyof T]?: T[K] };
// 把所有属性变只读
type Readonly2<T> = { readonly [K in keyof T]: T[K] };
// 内置工具类型
type User = { name: string; age: number };
type PartialUser = Partial<User>; // { name?: string; age?: number }
type NameOnly = Pick<User, "name">; // { name: string }
type WithoutAge = Omit<User, "age">; // { name: string }
type UserKeys = keyof User; // "name" | "age"
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 条件类型不分发 | T 被包在元组里 [T] extends [U] |
去掉包裹,或故意包裹防分发 |
| infer 位置错 | 推断不在 extends 左边 | 把要推断的位置用 infer U 占位 |
| 业务代码用太复杂类型 | 把类型体操当目的 | 拆成接口或工具类型,可读性优先 |
面试考法:"实现一个 Partial""infer 怎么用"。答到映射类型 + 可选标记;infer 在条件类型 extends 子句里提取。
5.5 d.ts 与第三方类型包
为什么需要它:不是所有包都自带类型声明。TypeScript 通过 @types/* 包或项目内 d.ts 文件获取类型。
核心机制:
- 自带类型:包根有
.d.ts文件或 package.json 的"types"字段。 - 外部类型:
@types/lodash、@types/express,安装后自动被 TS 发现。 - 项目内声明:写
declare module "xxx"给没类型的包兜底;或写declare const config: {...}给全局常量。 - 类型只在编译期存在,运行时完全擦除。
interface不会编译成任何 JS 代码。
最小可运行示例:
# 安装类型包
npm install -D lodash @types/lodash
// src/types/legacy.d.ts
declare module "legacy-pkg" {
export function doSomething(input: string): number;
}
// 使用
import _ from "lodash";
_.chunk([1,2,3], 2); // 有类型提示
import { doSomething } from "legacy-pkg";
doSomething("abc");
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
Could not find a declaration file for module |
包没自带类型 | npm i -D @types/xxx,或写 d.ts |
| 类型声明不生效 | d.ts 不在 include 范围 | 把 src 加入 include |
interface 运行时 undefined |
类型被擦除 | interface 只在编译期,运行时用 class |
面试考法:"interface 与 type 区别""类型会不会编译到运行时"。答到 interface 可合并、type 是别名;类型全部擦除。
5.6 构建工具取舍:tsc、esbuild、tsup、swc
为什么需要它:tsc 是官方编译器,类型检查和转译都做,但慢。生产构建常用 esbuild/swc 只转译不检查,类型检查单独跑。
核心机制:
tsc:完整类型检查 + 转译。慢,但可靠。适合 CI 检查。esbuild:用 Go 写的转译器,只做语法转换(TS→JS),不做类型检查。快 10–100 倍。tsup:基于 esbuild 的打包器,适合发库,自动生成 d.ts。swc:Rust 写的,类似 esbuild,速度快。- 标准分工:
tsc --noEmit做类型检查,esbuild或tsup做打包/转译。
最小可运行示例:
{
"scripts": {
"typecheck": "tsc --noEmit",
"build": "tsup src/index.ts --format cjs,esm --dts",
"dev": "tsup src/index.ts --watch"
}
}
# 类型检查(CI 门禁)
npm run typecheck
# 构建(快)
npm run build
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| esbuild 构建后类型错误没报 | esbuild 不检查类型 | 单独跑 tsc --noEmit |
| tsup 没生成 d.ts | 没加 --dts |
加 --dts 选项 |
| tsc 太慢 | 全量编译 | 用 tsc --build 增量,或换 esbuild |
面试考法:"为什么生产用 esbuild 而不是 tsc"。答到 esbuild 不做类型检查所以快;类型检查单独跑在 CI。
5.7 paths 别名与运行时解析
为什么需要它:tsconfig 的 paths 在编译后会被擦除,运行时 Node 找不到 @/utils。这是 TS 项目最常见的坑。
核心机制:
- paths 只影响 TS 类型检查。tsc 编译输出的 JS 里
import "@/utils"还是原样。 - 解决方式:
- 用
tsup/esbuild打包时把别名解析成相对路径。 - 用
tsconfig-paths在运行时注册 hook。 - 不用别名,直接用相对路径。
- 用
最小可运行示例:
# 方案 1:tsup 打包时解析
tsup src/index.ts --alias:@=src
# 产物里 @/utils 变成 ./utils
# 方案 2:运行时 hook
node -r tsconfig-paths/register dist/index.js
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 编译过了,运行时找不到 | paths 不解析 | 用 tsup 别名或 tsconfig-paths |
| tsconfig-paths 在生产报模块错 | 生产没装 tsconfig-paths | 打包时解析,或不用别名 |
面试考法:"paths 别名运行时怎么办"。答到三种方案:打包解析、tsconfig-paths、相对路径。
六、分层练习
6.1 复现型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 写 tsconfig | 配一个 strict + NodeNext 的 tsconfig | tsc --noEmit 0 错误 |
1 小时 |
| 类型收窄 | 用可辨识联合写一个 Shape switch | 每个分支访问对应属性 | 0.5 小时 |
| 泛型函数 | 写一个 getProp<T, K extends keyof T> |
调用时类型正确推断 | 1 小时 |
| 实现 Partial | 用映射类型写 Partial2<T> |
所有属性变可选 | 0.5 小时 |
| d.ts 兜底 | 给一个无类型的包写 declare module | import 有提示 | 0.5 小时 |
6.2 改造型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 关掉 any | 给定满屏 any 的代码,改成具体类型 | 0 个 any,tsc 通过 | 2 小时 |
| 修 paths 运行时 | 给定编译过但运行时找不到别名的项目 | 用 tsup 打包后运行成功 | 1.5 小时 |
| 修 strictNullChecks | 给定 string | null 没判空的代码 |
每个分支都收窄 | 1 小时 |
| 拆复杂类型 | 给定三层嵌套条件类型,拆成工具类型 | 可读性提升,行为不变 | 1 小时 |
| 加类型包 | 给一个 JS 项目逐步加 @types | tsc 通过,有提示 | 1 小时 |
6.3 设计型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| TS 工具库迁移 | 把一个纯 JS 工具库改成 TS,strict 通过 | tsc 0 错误,产物含 d.ts | 4 小时 |
| 泛型 API 设计 | 设计一个带约束的泛型请求函数 | 输入参数与返回类型对应 | 3 小时 |
| 构建流水线 | 配 tsc --noEmit + tsup 构建脚本 |
CI 先检查后构建 | 2 小时 |
| 条件类型工具 | 写一个 DeepPartial<T> 递归嵌套可选 |
嵌套对象也变可选 | 2 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
Cannot find module '@/xxx' |
paths 运行时不解析 | 看编译产物 import 路径 | 用 tsup 别名或 tsconfig-paths |
tsc --noEmit 报类型错误 |
代码没遵守 strict | 看错误信息逐行修 | 加类型、收窄、修 any |
node dist/app.js 模块找不到 |
module 与 moduleResolution 不匹配 | 看 tsconfig 配置 | 都用 NodeNext |
| esbuild 构建不报错但运行时错 | esbuild 不检查类型 | 单独跑 tsc --noEmit | 加 typecheck 脚本 |
Could not find declaration file |
包无类型 | 看包是否自带 types | 装 @types/xxx 或写 d.ts |
interface 运行时 undefined |
类型被擦除 | 看是不是把 interface 当 class | 运行时用 class |
| CJS 默认导入报错 | 没开 esModuleInterop | 看 tsconfig | 加 esModuleInterop |
非空断言 ! 乱用 |
运行时还是 null | 看实际数据 | 加真实判空逻辑 |
八、出口条件
全部勾选后再进入 阶段 4 Web 框架主线。
- [ ] 能写一个 strict + NodeNext 的 tsconfig,关键项都能解释
- [ ] 能用 typeof/instanceof/in 与可辨识联合收窄类型
- [ ] 能写带 extends 约束的泛型函数,能解释 keyof
- [ ] 能写条件类型与映射类型,用 infer 提取 Promise 返回类型
- [ ] 能用工具类型(Partial/Pick/Omit/ReturnType)改写接口
- [ ] 能为无类型包写 d.ts,能说明类型在运行时被擦除
- [ ] 能配
tsc --noEmit+tsup构建流水线,说明为什么要分开 - [ ] 排障表八个现象,随机抽三个能在 5 分钟内给出排查路径
自测题:
tsconfig.json的strict打开后包含哪些检查?- 要点:noImplicitAny、strictNullChecks、strictFunctionTypes、strictBindCallApply、alwaysStrict 等。
paths别名为什么编译过了运行时找不到?怎么解决?- 要点:paths 只影响类型检查,编译后原样保留。解决:tsup 打包时解析、tsconfig-paths hook、或用相对路径。
interface在运行时存在吗?- 要点:不存在。TypeScript 类型全部擦除,运行时看不到任何 interface/type。
- 写一个
Partial<T>的实现。- 要点:
{ [K in keyof T]?: T[K] }。
- 要点:
T extends U ? X : Y在 T 是联合类型时会发生什么?- 要点:分布式条件,逐个成员分发判断;要防分发用
[T] extends [U]。
- 要点:分布式条件,逐个成员分发判断;要防分发用
- esbuild 为什么比 tsc 快?代价是什么?
- 要点:esbuild 只做语法转译不做类型检查;代价是类型错误要单独跑 tsc --noEmit。
keyof T与T[K]分别取什么?- 要点:keyof 取 T 所有键的联合类型;T[K] 取 K 位置属性的类型。