TypeScript自定义canvas.getContext方法出现类型不匹配报错

开发者阿泽

2026-8-27

问题原因

自定义覆盖canvas.getContext时出现ts(2322)类型不匹配，核心原因是：

原生getContext是多重重载函数，类型定义严格约定：传入不同的contextId参数，必须返回对应类型的上下文，比如传"2d"只能返回CanvasRenderingContext2D | null，传"webgl"只能返回WebGLRenderingContext | null，不存在“任意string入参返回所有上下文类型联合”的签名
你当前的实现是单签名函数，入参为string、返回值是所有上下文类型的联合，TS会校验该函数是否能匹配每一个重载签名，显然返回WebGL上下文的实现不可能满足2D上下文的属性要求，因此抛出类型错误。

解决方法

方案1：快速断言（适配仅自定义WebGL上下文的场景）

不需要强行把自定义WebGL上下文断言为所有可能的返回类型，直接对整个赋值的函数做类型断言，跳过逐重载的校验即可，是最简单的处理方式：

// createWebGLContext 只需要返回你实际实现的WebGL上下文即可，不需要多余类型断言
const createWebGLContext = (canvas: HTMLCanvasElement) => {
  // 这里是你自定义的WebGL上下文创建逻辑
  return new WebGLRenderingContext(canvas)
}

// 赋值时直接断言为原生getContext的类型
canvas.getContext = ((type: string) => {
  return createWebGLContext(canvas)
}) as typeof canvas.getContext

方案2：重载实现（类型更严谨）

如果需要保留TS的类型校验能力，可以按照重载签名的要求实现分支逻辑，仅在匹配到webgl类型时返回自定义上下文，其他不支持的类型返回null：

canvas.getContext = ((
  type: '2d' | 'bitmaprenderer' | 'webgl' | 'webgl2',
  options?: unknown
) => {
  switch(type) {
    case 'webgl':
      return createWebGLContext(canvas)
    default:
      // 不支持的上下文类型直接返回null
      return null
  }
}) as typeof canvas.getContext