React+TypeScript项目执行yarn build时出现key props类型错误

问题原因 #

React中的key是内部特殊属性，不会作为props传递给组件本身。若你使用的Image组件（自定义或第三方）的Props类型定义中未包含key，TypeScript会判定你传递了一个组件不接受的属性，从而抛出 Property 'key' does not exist on type 'IntrinsicAttributes & PropTypes' 错误。

解决方案 #

1. 移除不必要的key属性 #

如果Image组件不是在列表循环中渲染，key属性完全多余——key的核心作用是帮助React识别列表元素的变化，单个组件无需添加。直接删除key={Math.random()}即可解决错误：

return (
  <Image
    src={loading ? undefined : userID || fileID || type === 'my-pic' ? (isError ? avatar : img) : avatar}
    fallback={
      fullName
        ? fullName
            ?.split(' ')
            .map((s) => s[0])
            .slice(0, 2)
            .join()
        : avatar
    }
    placeholder={<Skeleton.Image active className="w-full h-full" />}
    width={width}
    height={height}
    className={className}
    preview={preview && !isError}
  />
);

2. 调整自定义组件的Props类型（若Image是你维护的组件） #

若你需要保留key（比如强制组件重新渲染的场景），修改Image组件的Props类型定义，让它兼容key：

import type { Key, ReactNode } from 'react';

// 方式1：直接添加key属性
interface ImageProps {
  src?: string;
  fallback?: ReactNode;
  placeholder?: ReactNode;
  width?: number | string;
  height?: number | string;
  className?: string;
  preview?: boolean;
  key?: Key; // 加入key的类型定义
}

// 方式2：继承React内置属性（更简便）
import type { ComponentPropsWithoutRef } from 'react';

interface ImageProps extends ComponentPropsWithoutRef<'img'> {
  fallback?: ReactNode;
  placeholder?: ReactNode;
  preview?: boolean;
}

3. 处理第三方组件的类型问题 #

如果Image是第三方组件（如Ant Design的Image）：

• 先检查组件版本与你的React/TypeScript版本是否兼容，版本不匹配常导致类型异常，尝试更新组件：

  yarn add antd@latest # 根据实际组件包名调整
  

• 若确定组件支持key但类型定义缺失，可临时用类型断言绕过（不推荐长期使用）：

  return (
    <Image
      {...({ key: Math.random() } as any)}
      src={loading ? undefined : userID || fileID || type === 'my-pic' ? (isError ? avatar : img) : avatar}
      fallback={
        fullName
          ? fullName
              ?.split(' ')
              .map((s) => s[0])
              .slice(0, 2)
              .join()
          : avatar
      }
      placeholder={<Skeleton.Image active className="w-full h-full" />}
      width={width}
      height={height}
      className={className}
      preview={preview && !isError}
    />
  );
  

内容的提问来源于stack exchange，提问作者Mohammad Hosein Rostami