TypeScript 严格模式:286 个错误怎么分类清零
打开 strict 和 noUncheckedIndexedAccess 后,pnpm check:types 报了 286 个错误,涉及 65 个文件。第一次看会以为要改 286 处逻辑;按错误产生的位置分组后,真正会改变运行时行为的只占一部分,其余是类型声明、字面量推断和编译器误报。
现象:先按错误来源分组,不要按文件排队
迁移前先做一次完整类型检查,把诊断按错误码和位置归组。下面六类覆盖了这次迁移的绝大多数问题,处理顺序也按“是否可能改变运行时行为”排列:
| 类别 | 典型表现 | 先做什么 |
|---|---|---|
| 严格索引访问 | Object is possibly 'undefined'、Type 'undefined' is not assignable | 补缺失值语义 |
| unknown 扩散 | 参数类型退化成 {},调用点连环报错 | 在源头收窄一次 |
| 外部数据边界 | JSON、接口结果被直接 as 成业务类型 | 加运行时校验 |
| DOM 事件 | EventTarget 不能赋给 HTMLInputElement | 用 instanceof 收窄 |
| 库声明与字面量 | 找不到声明文件、rel 被拓宽成 string | 补最小声明或用 as const |
| 资源生命周期 | loading task 被当成 document | 修正变量和释放对象 |
先修索引访问、DOM 事件和资源生命周期,因为它们可能真的是空值或清理 bug;unknown 扩散和库声明多数是类型层问题;数据边界最危险,因为一旦用 as 压过去,错误会被推迟到用户输入到达时才出现。
索引访问:arr[0] 不再是 T
strict 不包含 noUncheckedIndexedAccess,这个选项要单独打开。打开后,数组下标、正则捕获组、splice 返回值都会多出 undefined:
const match = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(input)
const body = match[1]
if (body.length === 3) {
// 错误:body 可能是 undefined
}
错误不是让你在每个下标后面加 !,而是逼你回答:这个位置缺值时,业务上应该怎么办。
const body = match?.[1]
if (!body) return null
const expanded = body.length === 3
? [...body].map(ch => ch + ch).join('')
: body
音频采样、像素数组这类数值索引更常见:
const value = channel[index]
if (value > peak) {
peak = value
// 错误:value 可能是 undefined
}
处理方式取决于“缺值是否合法”:
| 场景 | 推荐写法 | 说明 |
|---|---|---|
| 缺值非法,调用方应保证 | if (!item) throw new Error(...) | 把不变量写出来,而不是藏进断言 |
| 缺值合法,有业务默认值 | channel[index] ?? 0 | 确认 0 不会被误当成真实样本 |
| 已提前检查,且长度不变 | items[i]! | 只证明已存在的不变量;断言不会创造值 |
| 索引来自外部输入 | 显式分支或范围检查 | 不要假定数组长度 |
一种很常见的“假修复”是 Number.parseInt(args[0]!, 10)。它能过编译,但 args[0] 为 undefined 时 parseInt 得到 NaN,后面再靠 || 1 兜底。缺值在字符串层就应该明确:
const density = Number.parseInt(args[0] ?? '', 10)
const direction = Number.parseInt(args[1] ?? '', 10) || 1
如果缺值非法,直接报错比静默变成 NaN 更好。非空断言只适合“前面已经检查过、且中间没有异步或重新赋值”的位置;它不会让运行时多出一个值。
数组交换也常被严格索引访问拦住:
const current = list[i]!
const other = list[j]!
list[i] = other
list[j] = current
临时变量不是为了绕过检查,而是把两次读取之间“值仍然存在”的不变量固定下来。直接写 [list[i], list[j]] = [list[j]!, list[i]!] 虽然有时能过,但读起来更费劲,也更容易在边界条件下出错。
unknown 扩散:在源头收窄,不要在调用点断言
第三方类型经常带索引签名:
interface LocaleLike {
code: string
[key: string]: unknown
}
从这种对象上读 iso,得到的是 unknown。如果 composable 直接把它返回,调用方拿到的类型会退化成 unknown,甚至在某些推导里变成 {},于是每个使用它的函数都报参数类型错误。
错误做法是在每个调用点写 as string:
const iso = computed(() => locales.value.find(item => item.code === code)?.iso as string)
这等于把同一个假设复制到全项目,还顺手把 undefined 也假装成了字符串。更好的做法是在返回值处收窄一次:
function pickIso(locales: LocaleLike[], code: string): string {
const iso = locales.find(item => item.code === code)?.iso
return typeof iso === 'string' ? iso : 'zh-CN'
}
如果要在 computed 里做,也可以把返回类型写出来:
const iso = computed<string>(() => {
const value = locales.value.find(item => item.code === code)?.iso
return typeof value === 'string' ? value : 'zh-CN'
})
这样 unknown 被关在函数内部,调用方拿到的是明确的 string。unknown 比 any 好,是因为它强制你面对不确定性;但如果在调用点反复断言,最后的效果和 any 差不多。
数据边界:生成的类型不是运行时校验
JSON.parse 和 response.json() 返回 any,很多项目会直接写:
const article = await response.json() as Article
这行代码没有检查任何字段。后端返回 null、字段改名、tags 从数组变成字符串时,TypeScript 都不会在运行时拦住,错误会在页面渲染或数组方法调用时才爆出来。
根据 JSON 样本生成 TypeScript 类型很方便,比如用 JSON 转 TypeScript 类型 从一段响应推出接口。但生成器做的是“按值的形状猜”:
- 多个数组元素会合并,某个字段只在其中一个元素出现,就会被标成可选;
- 空数组推不出元素类型,只能标成
unknown; - 同名字段类型冲突时,会合并成 union,并提示推断可能不准。
这些规则决定了生成结果是一份“样本假设”,不是接口契约。真正的数据边界仍要校验:
interface Article {
id: number
title: string
tags?: string[]
}
function isArticle(value: unknown): value is Article {
if (typeof value !== 'object' || value === null) return false
const record = value as Record<string, unknown>
return typeof record.id === 'number'
&& typeof record.title === 'string'
&& (record.tags === undefined
|| (Array.isArray(record.tags) && record.tags.every(tag => typeof tag === 'string')))
}
const payload: unknown = await response.json()
if (!isArticle(payload)) {
throw new Error('文章数据结构不符合预期')
}
这里的 as Record<string, unknown> 是在确认“它是对象”之后做的局部收窄,范围有限;如果字段很多,可以换成 schema 校验器,但原则一样:先得到 unknown,校验通过后再进入业务类型。
DOM 事件:一次 instanceof 胜过五次 as
文件选择、拖放、输入框事件里经常出现这种写法:
function handleFileChange(event: Event) {
loadFile((event.target as HTMLInputElement).files?.[0])
event.target.value = ''
}
event.target 的静态类型是 EventTarget | null,as HTMLInputElement 只是让编译器闭嘴,没有检查运行时对象。事件从按钮、自定义元素或空目标冒泡过来时,.files 和 .value 都可能不存在;同一行里的两次断言还会让错误位置变得模糊。
用 instanceof 把类型检查和运行时检查合成一次:
function handleFileChange(event: Event) {
if (!(event.target instanceof HTMLInputElement)) return
const input = event.target
const file = input.files?.[0]
if (!file) return
loadFile(file)
input.value = ''
}
input 收窄后可以直接复用,读文件和清空输入框都在同一个确定的类型上完成。跨 shadow DOM 时 event.target 可能被重定向,这时可以用 event.composedPath()[0] 再判断,但不要因为少见场景就退回无检查的断言。
库声明与字面量:补事实,不补 any
第三方包没有类型时,编译器会报 Could not find a declaration file。优先装官方或社区维护的 @types/*;确实没有时,再写最小声明:
declare module 'some-widget' {
export interface Options {
theme?: 'light' | 'dark'
}
export function mount(el: HTMLElement, options?: Options): {
destroy(): void
}
}
只声明实际用到的成员,不要把整个模块声明成 any。shim 是一份对外部包的承诺,升级包版本时要一起检查;如果只是为了让错误消失而写 any,等于把类型检查从项目里挖掉一块。
另一类错误来自字面量拓宽。下面这段代码里,数组字面量会把 rel 推断成 string,而 API 需要的是具体字面量联合类型:
useHead({
link: [
{ rel: 'canonical', href: canonicalUrl },
// 错误:string 不能赋给 'canonical' | 'alternate' | ...
],
})
在值后面加 as const 就够了:
useHead({
link: [
{ rel: 'canonical' as const, href: canonicalUrl },
{ rel: 'alternate' as const, hreflang: 'x-default', href: canonicalUrl },
],
})
as const 只收窄字面量,不改变运行时值,也不掩盖数据结构问题。它和 as SomeType 不是一回事:前者让推断更精确,后者是在向编译器作保证。
还有一种是库的类型定义没覆盖某个字段。例如当前版本的 useSeoMeta 类型里没有 keywords,关键词可以走普通 meta:
const keywords = computed(() => toValue(options.keywords))
useHead({
meta: computed(() => keywords.value
? [{ name: 'keywords', content: keywords.value }]
: []),
})
不要因为一个字段缺失就给整个 options 加 as any;单独绕开缺字段的 API,其他字段仍然保留检查。类似的“找不到类型”问题有时和自动导入有关,可以对照 Nuxt 自动导入的静默冲突 排查,但不要把两个问题混成一个。
标准库本身的类型也会变化。TypeScript 5.7 起,TypedArray 带上了 buffer 泛型:Float32Array 默认是 Float32Array<ArrayBufferLike>,而 Web Audio 的 copyToChannel 要求 Float32Array<ArrayBuffer>。如果数据接口只写 Float32Array[],调用处就会报错。正确的修法是在接口上写清楚:
interface AudioSlice {
channels: Float32Array<ArrayBuffer>[]
sampleRate: number
}
这比在调用处写 as any 更准确,因为它说明的是“这段音频确实由普通 ArrayBuffer 承载”,而不是“别检查了”。
资源生命周期:类型错误也可能是真 bug
pdf.js 的 getDocument() 返回的是 PDFDocumentLoadingTask,不是 PDFDocumentProxy。如果函数名叫 openDoc,调用方很容易把返回值当成 document:
const doc = pdfjs.getDocument({ data })
const page = await doc.getPage(1)
// 错误:loading task 上没有 getPage
这时候不要给 doc 加断言,而要把两个阶段分开:
const task = pdfjs.getDocument({ data })
try {
const doc = await task.promise
const page = await doc.getPage(1)
// 使用 page 和 doc
} finally {
await task.destroy()
}
task 负责加载和取消,doc 负责页面内容;页面还在使用时不能提前 destroy,取消加载则应该销毁 task。严格模式在这里帮上忙,是因为变量名和实际对象不一致时,类型检查会先暴露出来;如果直接 as PDFDocumentProxy,真正的问题会被推迟到运行时。
验证:0 个错误之外,还要看怎么清零
迁移后重新执行:
pnpm check:types
这次仓库的结果是退出码 0,没有 TypeScript 诊断,只剩 Nuxt 的图标收集日志。迁移统计如下:
| 检查项 | 迁移前 | 迁移后 |
|---|---|---|
pnpm check:types 错误 | 286 | 0 |
| 涉及文件 | 65 | - |
新增 @ts-ignore / @ts-expect-error | - | 0 |
新增 as any | - | 0 |
“0 个错误”不是唯一指标。如果 0 是靠 @ts-ignore 或 as any 换来的,只是把错误推迟到运行时。迁移结束后可以统计一遍抑制指令和 any 的数量,把 check:types 放进持续集成,要求新代码不能让错误数回升。
还有一类报错需要单独判断:它可能不是代码错。迁移中遇到过非 async <script setup> 里 reactive 表单配合模板 v-model 的模板类型报错,运行时逻辑正常。处理这类问题先做最小复现,确认是 vue-tsc 的模板推断问题后,再考虑改成 ref 表单或显式泛型:
interface FormState {
title: string
description: string
}
const form = ref<FormState>({
title: '',
description: '',
})
改动要留下原因,并且仍然让 check:types 通过。不能因为“可能是编译器误报”就把整个表单改成 any;无法证明是误报时,按真实错误处理。
FAQ
strict: true 是否包含 noUncheckedIndexedAccess?
不包含。strict 主要打开 strictNullChecks、noImplicitAny 等一组检查,noUncheckedIndexedAccess 是独立选项,需要单独开启。它会显著增加索引访问的报错量,适合在基础空值检查稳定后再加。
为什么不直接用 any 或 @ts-ignore 快速清零?
它们会让后续代码失去检查:any 会把污染传给调用方,@ts-ignore 只压住当前行。短期看错误数变成 0,长期看是把编译期问题挪到用户输入到达时才出现。确实需要临时绕过时,应该限定在一行、写清原因,并记录清理计划。
! 非空断言什么时候可以接受?
只在“前面已经证明值存在,且中间没有异步、重新赋值或外部修改”时使用。外部输入、数组长度可变、异步回调之后都不适合。能用 ?? 表达默认值,或能用 if 写出不变量时,优先用它们。
大项目应该按文件迁移还是按错误类型迁移?
按错误类型。先修工具函数和 DOM 事件这类叶子节点,再修数据边界,最后处理第三方声明和框架类型。不要和功能开发混在同一个提交里,否则很难判断错误数变化是迁移带来的还是新代码带来的。
严格模式迁移的目标不是把 286 变成 0,而是让每个 0 都有理由:该判空的判空,该校验的校验,该断言的断言。先跑一次完整类型检查,把错误按来源分组,再从会影响运行时的那几类开始,逐组验证。更多 Vue、Nuxt 与前端工程化文章见 前端开发。
評論
還沒有評論,來說兩句吧