JavaScript / TypeScript / 系统课时
排查常见类型错误
排查常见类型错误
类型错误最有效的处理方式不是反复改写代码,而是先确认编译器看到的“来源类型”和“目标类型”。本节用一个最小示例建立排查顺序,并覆盖赋值失败、推断过宽、类型不兼容与模块解析失败四类高频问题。
学习目标
- 能从 TypeScript 错误信息中定位来源类型、目标类型和首个根因。
- 能识别对象字面量推断过宽,并用显式类型或
satisfies收紧约束。 - 能用模块解析检查定位“找不到模块”问题,而不是盲目修改导入路径。
先读懂首个错误
TypeScript 的后续错误经常是第一个错误的连锁反应。排查时先执行完整类型检查,只处理最靠前、最接近根因的一条,再重新编译。对 TS2322 这类赋值错误,重点看“Type A is not assignable to type B”:A 是实际来源类型,B 是代码要求的目标类型。
下面的示例同时演示直接赋值失败和对象属性推断过宽。
type ThemeOptions = {
mode: "dark" | "light";
retry: number;
};
// 错误一:字符串不能赋给 number。
const retryCount: number = "3";
// 错误二:普通对象属性会被拓宽为 string。
const inferred = { mode: "dark", retry: 3 };
const options: ThemeOptions = inferred;
console.log(options.mode, retryCount);在项目目录执行:
npx tsc --noEmit index.ts --pretty false预期输出
<TS_FILE_PATH>(7,<VALUE>): error TS2322: Type 'string' is not assignable to type 'number'.
<TS_FILE_PATH>(11,<VALUE>): error TS2322: Type '{ mode: string; retry: number; }' is not assignable to type 'ThemeOptions'.行号和列号会随文件内容变化,但两个错误都指向同一件事:实际推断出的类型不能赋给目标类型。
修复推断过宽而不丢失校验
如果对象就是某个配置形状,最直接的做法是给变量显式标注类型;如果还希望保留字面量自身更具体的推断,可以使用 satisfies。同时,数据来源本身是字符串时,应显式转换,而不是用类型断言掩盖问题。
type ThemeOptions = {
mode: "dark" | "light";
retry: number;
};
const retryCount = Number("3");
// satisfies 会检查结构,同时保留 mode 的字面量类型 "dark"。
const options = {
mode: "dark",
retry: retryCount,
} satisfies ThemeOptions;
console.log(options.mode, options.retry);运行类型检查和程序:
npx tsc index.ts --outDir dist --pretty false && node dist/index.js预期输出
dark 3这类修复优先改变数据或约束本身。只有在你确实掌握编译器无法证明的外部事实时,才考虑 as 断言;把 as any 当作通用修复会直接绕过类型系统。
按来源定位类型不兼容
遇到复杂泛型、联合类型或函数参数不兼容时,不要只盯着整条错误文本。先把表达式拆成中间变量,并临时给关键变量加显式类型,让错误缩小到一个边界。若错误来自第三方 API,再检查其声明文件中的参数、返回值和泛型约束,而不是仅按运行时行为猜类型。

这张流程图的重点是把“类型关系问题”和“模块解析问题”分开。前者看值与约束,后者看编译器如何寻找文件或包,两者不要混在同一条修复路径里。
模块找不到时看解析证据
TS2307: Cannot find module ... 不一定表示文件不存在。常见根因还包括文件名大小写不一致、包未安装、包的 exports 或类型声明未暴露目标入口,以及 moduleResolution 与运行环境不匹配。
先确认导入名,再让编译器输出解析过程。下面是片段示例,需要在实际出现 TS2307 的项目根目录执行:
npx tsc --noEmit --traceResolution预期结果
======== Resolving module '<MODULE_SPECIFIER>' from '<PATH>'. ========
...
======== Module name '<MODULE_SPECIFIER>' was not resolved. ========
<TS_FILE_PATH>(<VALUE>,<VALUE>): error TS2307: Cannot find module '<MODULE_SPECIFIER>' or its corresponding type declarations.如果最后是未解析成功,就沿着 trace 中实际尝试过的路径逐项检查;不要靠反复添加扩展名或切换配置碰运气。完成修复后再次执行 npx tsc --noEmit,只有在首个错误消失且没有新增类型错误时,才说明本次排查真正闭环。