JavaScript / TypeScript / 知识点
TypeScript 速查手册
手册条目
识别和减少 any 带来的类型风险。
处理 any 类型
any 会关闭当前值及其传播链上的类型检查。处理重点不是一次性清零,而是先找到输入边界,再把 any 收紧为具体类型、泛型或 unknown,让错误重新回到编译期。
什么时候需要处理
看到显式 any、未标注参数产生的隐式 any、第三方库缺少类型声明,或一个 any 继续污染多个变量时,应优先处理。先修复外部输入、接口响应和公共函数返回值,因为这些位置最容易扩大影响范围。
识别与收紧
开启 strict 和 noImplicitAny 可拦截隐式 any,但显式 any 仍会通过编译。已知结构使用接口或类型别名;类型由调用方决定时使用泛型;来源不可信时改用 unknown 并执行类型收窄;第三方模块无类型时则补充声明文件或封装适配层。
主示例
下面保留一个不安全函数用于对比,并用 unknown 加类型守卫阻断错误数据。
type User = {
name: string;
};
function unsafeUpperName(value: any): string {
return value.name.toUpperCase();
}
function isUser(value: unknown): value is User {
if (typeof value !== "object" || value === null) return false;
return typeof (value as Record<string, unknown>).name === "string";
}
function safeUpperName(value: unknown): string {
if (!isUser(value)) return "INVALID_USER";
return value.name.toUpperCase();
}
console.log(unsafeUpperName({ name: "Ada" }));
console.log(safeUpperName({ name: "Lin" }));
console.log(safeUpperName({ name: 123 }));运行命令:
npx tsc any-demo.ts --strict --target ES2020 --module commonjs && node any-demo.js预期输出:
ADA
LIN
INVALID_USER前两行是合法对象的转换结果,第三行说明错误结构已被守卫拦截。若把最后一次调用改成 unsafeUpperName({ name: 123 }),编译仍会通过,但运行时会因数字没有 toUpperCase 方法而抛出异常。
风险与边界
把 any 直接断言成目标类型只会绕过检查,不会验证运行时数据。输入结构与断言不一致时,可能产生线上 TypeError、错误计算或脏数据传播。安全替代方案是先接收为 unknown,再通过类型守卫、解析函数或模式校验库确认结构。
第三方库暂时只能返回 any 时,应将其限制在单一适配层中。适配层负责校验并返回具体类型,不要让 any 暴露到业务函数参数、公共返回值或共享状态中。
排障清单
- 搜索
: any、as any、Array<any>以及返回值为any的公共函数。 - 检查
any是否进入对象、数组、Promise 或回调参数并继续传播。 - 开启
strict和noImplicitAny,重新编译以暴露隐式问题。 - 对暂时无法移除的
any标注来源和边界,并优先封装而不是继续扩散。
安全处理未知来源的数据类型。
使用 unknown 类型
unknown 适合接收接口响应、JSON、消息载荷、异常对象等未知输入。它允许保存任意值,但在读取属性、调用方法或参与运算前必须先收窄,因此比 any 更适合作为系统边界类型。
基本语法
任何值都能赋给 unknown,但 unknown 不能直接赋给具体类型,也不能直接访问属性。使用前需要通过 typeof、instanceof、判空、自定义类型守卫或模式校验完成收窄。
let value: unknown = "ready";
if (typeof value === "string") {
console.log(value.toUpperCase());
}预期输出:
READY高频用法
未知数据进入程序时先声明为 unknown,在边界校验函数中一次性确认结构,业务代码只接收校验后的具体类型。捕获异常时也可使用 catch (error: unknown),再判断它是否为 Error,避免假设所有异常都具有 message 属性。
主示例
下面解析一段 JSON,并通过类型守卫验证字段类型。JSON.parse 的结果先放入 unknown,防止未校验的数据直接进入业务逻辑。
type Product = {
id: number;
name: string;
};
function isProduct(value: unknown): value is Product {
if (typeof value !== "object" || value === null) return false;
const record = value as Record<string, unknown>;
return typeof record.id === "number"
&& typeof record.name === "string";
}
function parseProduct(raw: string): Product | null {
const value: unknown = JSON.parse(raw);
return isProduct(value) ? value : null;
}
const valid = parseProduct('{"id":101,"name":"Keyboard"}');
const invalid = parseProduct('{"id":"101","name":"Keyboard"}');
console.log(valid?.name ?? "INVALID_PRODUCT");
console.log(invalid?.name ?? "INVALID_PRODUCT");运行命令:
npx tsc unknown-demo.ts --strict --target ES2020 --module commonjs && node unknown-demo.js预期输出:
Keyboard
INVALID_PRODUCT第一行表示字段类型符合约束;第二行表示 id 实际为字符串,校验失败并返回 null。生产代码可以返回包含错误字段和原因的结果对象,便于记录和定位无效输入。
风险与边界
将 unknown 直接写成 value as Product 会失去安全收益。输入与断言不一致时,错误会延迟到属性访问或业务计算阶段。安全替代方案是使用类型守卫;复杂嵌套数据则应使用运行时模式校验工具,并保留详细失败原因。
类型守卫本身也可能写错。若只判断属性存在而不检查属性类型,编译器仍会信任错误结论。关键输入应覆盖合法值、缺少字段、错误类型、数组和 null 等测试场景。
排障清单
- 遇到“对象的类型为 unknown”时,不要直接改成
any,先确认所需的收窄条件。 - 访问对象属性前先排除
null,因为typeof null的结果也是object。 - 使用
in运算符前,先确认当前值是非空对象。 - 校验函数应返回具体类型或明确的失败结果,避免业务层重复执行类型断言。
通过条件类型和映射类型扩展类型能力。
编写类型工具
当内置的 Partial、Pick、Omit 无法表达项目规则时,用条件类型判断输入类型,用映射类型遍历、筛选或改写属性。目标是把重复的类型约束集中成可复用工具,同时保持编译错误可读、推导结果可验证。
基本语法
条件类型写作 T extends U ? X : Y,适合按类型特征选择结果;映射类型写作 [K in keyof T],适合批量处理属性。映射时可用 readonly、?、-readonly、-? 修改修饰符,也可通过 as 重映射键名或过滤属性。
infer 只能出现在条件类型的 extends 分支中,用于提取数组元素、函数返回值或 Promise 内部值。条件类型接收联合类型时默认逐成员分发;需要整体判断时,将两侧包成元组,例如 [T] extends [U]。
主示例
下面同时演示条件类型、移除可选与空值、按值类型筛选键,以及从映射结果中提取键联合。保存为 type-tools.ts。
type ApiResult<T> = T extends Error
? { ok: false; message: string }
: { ok: true; data: T };
type NonNullableFields<T> = {
// -? 先移除可选标记,再排除 null 与 undefined。
[K in keyof T]-?: Exclude<T[K], null | undefined>;
};
type PickByValue<T, V> = {
// 通过 as 将不匹配的键映射为 never,从结果中删除。
[K in keyof T as T[K] extends V ? K : never]: T[K];
};
type NullableKeys<T> = {
[K in keyof T]-?: null extends T[K] ? K : never;
}[keyof T];
interface RawUser {
id: number;
name: string | null;
email?: string;
active: boolean;
}
type CleanUser = NonNullableFields<RawUser>;
type BooleanFields = PickByValue<RawUser, boolean>;
type RawUserNullableKey = NullableKeys<RawUser>;
function normalizeUser(user: RawUser): CleanUser {
// 类型工具不补运行时数据,必须在实现中提供默认值。
return {
id: user.id,
name: user.name ?? "anonymous",
email: user.email ?? "unknown@example.com",
active: user.active
};
}
const clean = normalizeUser({ id: 7, name: null, active: true });
const flags: BooleanFields = { active: true };
const nullableKey: RawUserNullableKey = "name";
const result: ApiResult<CleanUser> = { ok: true, data: clean };
console.log(JSON.stringify(clean));
console.log(JSON.stringify(flags));
console.log(nullableKey);
console.log(JSON.stringify(result));在已安装 TypeScript 的项目目录运行:
npx tsc type-tools.ts --strict --target ES2020 --module commonjs --outDir dist
node dist/type-tools.js预期输出:
{"id":7,"name":"anonymous","email":"unknown@example.com","active":true}
{"active":true}
name
{"ok":true,"data":{"id":7,"name":"anonymous","email":"unknown@example.com","active":true}}NonNullableFields 只改变静态类型,因此示例中的 normalizeUser 仍要真实补齐缺失值。PickByValue 的结果只有 active,而 NullableKeys 将各属性映射为键或 never,再通过索引访问合并为 "name"。
高频模式
提取容器内部类型时,可写 type Element<T> = T extends readonly (infer U)[] ? U : never。批量生成只读、可选或必填版本时,优先在一个映射类型里增删修饰符,避免为每个接口复制定义。
过滤属性时,把不需要的键重映射为 never;改名时在 as 后生成模板字面量键。处理联合类型前先确认是否需要分发:逐成员转换保留默认写法,整体判断则使用 [T] extends [U]。
风险与边界
类型工具只在编译阶段生效,不能验证接口响应、配置文件或用户输入。把未知数据直接断言成工具类型会产生“编译通过、运行时报错”;安全做法是先做运行时校验,再把校验后的值交给类型系统。
递归条件类型、巨型联合和多层键重映射会显著增加 Types、Instantiations 与检查时间。出现类型实例化过深或编辑器卡顿时,应限制递归层数、拆分中间类型,并避免让公共泛型接收无界 any。
启用 exactOptionalPropertyTypes 后,prop?: T 与 prop: T | undefined 的赋值语义不同。编写会修改可选性的工具时,要在目标项目的真实编译选项下添加类型测试,不能只凭编辑器悬浮结果判断。
排障清单
- 结果意外变成联合:检查条件类型是否对联合类型发生了分发。
- 结果意外变成
never:逐层检查键过滤条件,以及输入是否已被any或never污染。 - 可选属性没有变必填:确认映射类型使用了
-?,并检查属性值中是否仍包含undefined。 - 编译明显变慢:运行
tsc --extendedDiagnostics,重点观察Types、Instantiations和Check time。 - 推导结果难以阅读:为关键中间结果命名,并用赋值测试或
satisfies固定预期结构。
兼容性
映射类型键重映射 as 需要 TypeScript 4.1 及以上。工具类型应跟随项目的 strict、exactOptionalPropertyTypes 等选项测试;同一份定义在不同编译选项下可能产生不同的可赋值行为。
提升大型 TypeScript 项目的编译效率。
优化 TypeScript 项目构建
大型项目编译变慢时,先区分文件规模、类型检查、声明输出和模块解析哪一段耗时,再启用增量缓存与项目引用。最终应让未变化的包跳过检查和输出,而不是依靠关闭严格检查换取表面速度。
先定位耗时
在真实构建配置上采集诊断数据,不要只比较编辑器体感。命令成功时会正常生成产物,并在末尾打印编译阶段统计。
npx tsc -p tsconfig.json --extendedDiagnostics --pretty false预期输出结构如下,数值会随机器与项目变化:
Files: <N>
Memory used: <KB>K
Parse time: <SECONDS>s
Bind time: <SECONDS>s
Check time: <SECONDS>s
Emit time: <SECONDS>s
Total time: <SECONDS>sFiles 异常增大通常说明 include 过宽、生成目录被纳入或依赖被源码导入;Check time 占比高应检查复杂泛型与巨型联合;Emit time 高则重点检查声明文件、声明映射和 source map。优化前后应使用同一机器、同一提交和冷热缓存条件对比。
拆分构建图
项目引用把代码库拆成有向依赖图,tsc -b 按依赖顺序构建,只重建过期节点。公共包应位于上游,应用包位于下游,并禁止循环引用。

下面的 Bash 示例会在临时目录创建两个引用项目、执行首次构建、运行产物并验证增量缓存。需要能够访问 npm registry;脚本不会修改当前项目文件。
set -euo pipefail
workdir="$(mktemp -d)"
mkdir -p "$workdir"/packages/{core,app}/src "$workdir"/.cache
cd "$workdir"
npm init -y >/dev/null 2>&1
npm install --save-dev typescript >/dev/null 2>&1
cat > tsconfig.base.json <<'JSON'
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"strict": true,
"declaration": true,
"incremental": true,
"skipLibCheck": true
}
}
JSON
cat > tsconfig.json <<'JSON'
{
"files": [],
"references": [
{ "path": "./packages/core" },
{ "path": "./packages/app" }
]
}
JSON
cat > packages/core/tsconfig.json <<'JSON'
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"composite": true,
"rootDir": "src",
"outDir": "dist",
"tsBuildInfoFile": "../../.cache/core.tsbuildinfo"
},
"include": ["src/**/*.ts"]
}
JSON
cat > packages/app/tsconfig.json <<'JSON'
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"composite": true,
"rootDir": "src",
"outDir": "dist",
"tsBuildInfoFile": "../../.cache/app.tsbuildinfo"
},
"references": [{ "path": "../core" }],
"include": ["src/**/*.ts"]
}
JSON
cat > packages/core/src/index.ts <<'TS'
export function double(value: number): number {
return value * 2;
}
TS
cat > packages/app/src/index.ts <<'TS'
import { double } from "../../core/dist";
console.log(double(21));
TS
# tsc -b 会先构建 core,再构建依赖它的 app。
npx tsc -b --pretty false
node packages/app/dist/index.js
test -f .cache/core.tsbuildinfo
test -f .cache/app.tsbuildinfo
echo CACHE_READY
# 文件未变化时,第二次构建复用 build info。
npx tsc -b --pretty false
echo INCREMENTAL_REBUILD_OK预期输出:
42
CACHE_READY
INCREMENTAL_REBUILD_OK首次构建会生成两个 dist 目录和两个 .tsbuildinfo 文件。第二次执行 tsc -b 时没有源文件或配置变化,因此对应项目会被判定为最新状态;需要观察判定过程时,可追加 --verbose,其中时间与路径会因环境不同而变化。示例为保持自包含而从 core/dist 导入,真实仓库应通过包名与 exports 暴露公共入口。
配置优先级
| 配置或动作 | 适用情况 | 验证方式 |
|---|---|---|
incremental 与 tsBuildInfoFile |
单项目重复编译 | 第二次构建无变化时总耗时下降,缓存文件存在 |
composite 与 references |
多包仓库或分层服务 | tsc -b 按依赖顺序构建,修改上游只触发受影响下游 |
收紧 include |
Files 数量异常大 |
--listFilesOnly 中不再出现测试产物、生成目录和无关源码 |
skipLibCheck |
第三方声明文件检查占时明显 | Check time 下降,业务源码错误仍会报告 |
| 类型检查与转译分离 | 打包器已负责生成 JavaScript | CI 独立运行 tsc --noEmit,打包步骤不重复调用 TypeScript emit |
exclude 不能阻止被源码显式导入的文件进入程序;真正缩小编译范围要同时修正导入边界。声明文件和 source map 只在发布链路需要时生成,开发态可使用单独配置关闭,避免每次本地检查都支付输出成本。
高频优化路径
先用 --extendedDiagnostics 建立基线,再用 --listFilesOnly 排除无关文件。多包仓库应优先建立清晰的包边界和单向引用,然后统一使用根目录 tsc -b,避免每个包各自启动编译器并重复解析公共依赖。
若打包器负责快速转译,可让开发构建只生成 JavaScript,另起进程执行 tsc --noEmit 做类型检查。该方案减少重复 emit,但不会降低类型系统本身的 Check time;复杂条件类型、超大联合和重复实例化仍需从类型设计上处理。
CI 缓存至少应包含 TypeScript 版本、锁文件、相关 tsconfig 和源码变化信息。编译器升级、路径映射调整或输出目录变化后,应主动清理旧 .tsbuildinfo 与产物,再重新建立基线。
风险与边界
启用 skipLibCheck 时,第三方 .d.ts 之间的冲突可能被隐藏,后果是升级依赖后问题延迟到业务引用处才暴露。安全做法是在日常开发启用它提速,同时在依赖升级或发布检查中定期关闭并执行完整类型检查。
项目引用要求依赖图无环且上游可生成声明文件。包之间直接穿透导入对方 src,会破坏输出边界并让增量判定失去意义;生产项目应通过包入口或声明输出引用,并用 lint 或模块边界规则阻止跨层导入。
缓存键不完整时,CI 可能恢复与当前编译器或配置不兼容的产物,表现为反复全量重建、声明文件不匹配或运行时加载旧文件。安全替代方案是完善缓存键,并在 TypeScript、锁文件或构建配置变化时清理缓存。
排障清单
- 第二次仍全量构建:用
tsc -b --verbose查看哪个输入、配置或输出被判定为过期。 - 文件数量异常:运行
tsc -p tsconfig.json --listFilesOnly,检查生成目录、测试夹具和跨包源码导入。 - 模块解析耗时或结果异常:使用
--traceResolution定位重复查找、错误的paths和多份类型包。 Check time高:用--generateTrace <PATH>采集跟踪,重点检查递归条件类型、巨型联合与重复泛型实例化。- 缓存行为可疑:删除
dist与.tsbuildinfo后重建;若冷构建正常,再检查缓存键和并发写入。 - 内存持续增长:确认没有把整个仓库纳入单一项目,并减少不必要的声明映射、测试类型和全局类型包。
解决编译配置、类型缺失和解析异常问题。
排查 TypeScript 类型配置问题
当项目出现 Cannot find module、Cannot find name、编辑器与命令行结论不一致,或同一仓库在不同机器上表现不同,先确认实际使用的 TypeScript 版本和最终生效配置,再判断是文件未纳入、环境类型缺失、模块解析不匹配,还是声明包本身有问题。不要先用 skipLibCheck 或随意修改 paths 掩盖根因。
先固定诊断入口
在仓库根目录使用项目本地的 tsc,避免全局版本与锁文件中的版本不一致。--showConfig 会展开 extends 并输出最终配置,--noEmit 只做类型检查,不写入构建产物。
npx tsc --version
npx tsc -p tsconfig.json --showConfig > .tsconfig.effective.json
npx tsc -p tsconfig.json --noEmit预期输出
Version <VERSION>
<无输出表示检查通过;失败时会输出 TSxxxx 诊断>打开 .tsconfig.effective.json,重点核对 files、include、exclude、compilerOptions.types、lib、module 和 moduleResolution。路径、版本号与诊断行号会因项目而不同。

按错误类型定位
TS2307: Cannot find module 优先检查包是否安装、包是否自带声明、moduleResolution 是否匹配运行方式,以及包的 exports 是否允许当前入口。不要一看到该错误就创建 declare module "*",这会把真实类型问题降级成 any。
npx tsc -p tsconfig.json --traceResolution > resolution.log 2>&1
grep -n "目标包名" resolution.log | head预期输出
<LINE>:======== Resolving module '目标包名' from '<PATH>' ========
<LINE>:Module name '目标包名' was successfully resolved to '<PATH>'若最后是未解析成功,向上查看尝试过的文件、package.json、exports 条件和搜索目录。若日志显示解析成功但仍报错,继续检查该入口导出的类型是否与导入写法一致。
TS2688: Cannot find type definition file 或 Cannot find name 'process' 通常与环境类型有关。先确认依赖存在,再检查 types 是否把全局声明限制掉。
npm install --save-dev @types/node --silent && npm ls --depth=0 typescript @types/node预期输出
<PROJECT>@<VERSION> <PATH>
├── @types/node@<VERSION>
└── typescript@<VERSION>如果配置中存在 "types": [],Node 全局变量不会自动进入全局作用域;需要显式加入 "node"。浏览器项目则应核对 lib 是否包含所需的 DOM 库,而不是安装无关的 @types 包。
修复配置
下面是 Node 项目的片段示例,依赖项目已经安装 typescript 与 @types/node。module 与 moduleResolution 使用同一类 Node 模式,避免编译期解析规则与运行时规则分离。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"types": ["node"],
"noEmit": true
},
"include": ["src/**/*.ts"]
}生效行为:只检查 src 下的 TypeScript 文件,加载 Node 全局类型,并按现代 Node 的 ESM/CJS 规则解析模块。保存后执行 npx tsc -p tsconfig.json --noEmit;无输出且退出码为 0 才表示配置层面的检查通过。
文件是否被纳入可直接用编译器解释,不要仅凭目录结构猜测。
npx tsc -p tsconfig.json --listFilesOnly | grep -E "src/|@types"预期输出
<PATH>/node_modules/@types/node/index.d.ts
<PATH>/src/index.ts缺少目标源码时检查 include、exclude、files 和配置文件所在目录;include 的相对路径以当前 tsconfig.json 所在目录为基准。
风险与边界
启用 skipLibCheck 只会跳过声明文件之间的检查。触发条件是第三方 .d.ts 冲突或依赖树中存在重复类型;后果是构建暂时变绿,但不兼容声明可能继续传播。安全替代方案是先定位冲突包、统一版本或使用包管理器的覆盖机制,再把该选项作为有期限的临时措施。
设置 typeRoots 会改写默认的类型包搜索范围。目录写错时,原本可见的 node_modules/@types 会整体消失。除非确实维护私有类型目录,否则优先使用 types 精确声明需要的全局类型;必须使用 typeRoots 时同时包含项目实际的 node_modules/@types 路径。
paths 只影响 TypeScript 的解析,不会自动改写已输出 JavaScript 的导入路径。触发条件是使用 @app/* 等别名但运行器、测试器或打包器没有同样映射;后果是类型检查通过、运行时却报模块不存在。安全替代方案是在 Node、测试框架和打包器中配置同一别名,或改用运行时能够原生解析的包入口。
排障清单
按顺序检查:项目本地 tsc 版本是否一致;--showConfig 是否指向预期配置;目标文件是否出现在 --listFilesOnly;缺失名称属于 Node、DOM、测试框架还是自定义全局;依赖是否自带声明或需要对应 @types;module 与 moduleResolution 是否匹配运行环境;--traceResolution 最终命中了哪个入口;编辑器是否使用工作区 TypeScript 版本。
修改后始终以 npx tsc -p <PATH> --noEmit 的退出码为准。编辑器仍残留旧错误时,再重启 TypeScript 语言服务;不要通过删除锁文件来“刷新”依赖,因为这可能同时升级多个包并扩大故障范围,优先使用锁文件配合 npm ci 复现。
兼容性
单仓库有多个 tsconfig.json 时必须显式传 -p <PATH>;项目引用或 monorepo 可用 npx tsc -b --verbose 查看各子项目的构建顺序。Node 直接运行项目使用 Node 模式,交给打包器处理的项目再评估 moduleResolution: "Bundler";不要把两种解析模型混在同一个配置中。
速查结论:先固定编译器版本和生效配置,再按“文件范围 → 环境类型 → 模块解析 → 声明兼容”逐层排除,最后用 --noEmit 验证。