如何解决Next.js（TypeScript）开启skipLibCheck=false的类型报错问题

该错误是Next.js 11.x版本内置类型定义与React类型定义不兼容导致的：Next.js 11为了支持img标签的loading属性，自行扩展了React的ImgHTMLAttributes接口，给loading属性新增了auto可选值，但你当前使用的React类型定义中loading属性的联合类型不包含auto值。你开启skipLibCheck=false后，TypeScript会检查所有第三方库的类型定义，就会抛出接口合并时类型不一致的错误。

• 方案1：新增全局类型声明抹平冲突
  在项目根目录新建types/next-image.d.ts声明文件，写入以下内容：

import 'react';

declare module 'react' {
  interface ImgHTMLAttributes<T> extends HTMLAttributes<T> {
    loading?: 'auto' | 'eager' | 'lazy';
  }
}

之后修改tsconfig.json的include配置，新增该声明文件的路径：

"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "types/next-image.d.ts"]

该方案不需要修改现有依赖版本，也能保留skipLibCheck=false的全量类型检查规则。

• 方案2：升级Next.js到12及以上版本
  Next.js 12及之后的版本已经官方移除了这个重复的类型扩展逻辑，和官方React类型定义完全对齐，升级后即可直接解决冲突。你可以执行以下命令完成升级：
  yarn add next@12
  升级后建议同步校验其他依赖的兼容性，避免出现额外的运行时问题。

• 方案3：选择性跳过库类型检查
  如果你暂时不想修改代码或者升级依赖，可以在tsconfig.json的compilerOptions中新增skipDefaultLibCheck: true配置，该配置只会跳过TypeScript默认内置库的类型检查，不会影响你自己业务代码的类型检查效果，同时也能解决当前的第三方库类型冲突问题，兼顾类型检查的严格性。

内容的提问来源于stack exchange，提问作者Andreii Pozniakov