TypeScript 严格模式:286 个错误怎么分类清零

2026-11-19 前端开发 有希 37 次浏览

打开 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 错误2860
涉及文件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 与前端工程化文章见 前端开发。

评论

登录后即可参与评论

还没有评论,来说两句吧

相关文章