在React应用开发中，图片资源加载失败是经常会遇到的情况，无论是本地资源路径错误、远程资源失效还是网络波动，都可能导致img标签无法正常渲染图片，出现空白或者破碎的图标，严重影响页面的视觉效果和用户体验。为图片加载失败时设置默认图像，实现优雅降级，是优化这类问题的有效手段。
方案一：使用原生img的onerror事件
原生img标签提供了onerror事件，当图片加载失败时就会触发该事件，我们可以在事件回调中替换图片的src为默认图像的地址。在React中可以直接给img标签绑定onError事件（注意React中事件名采用驼峰命名）。
示例代码如下：
import React from 'react';
const ImageWithFallback = ({ src, fallbackSrc, alt }) => {
// 处理图片加载失败的事件
const handleImageError = (e) => {
// 避免默认图也加载失败时无限循环触发onerror
if (e.target.src !== fallbackSrc) {
e.target.src = fallbackSrc;
}
};
return (
<img
src={src}
alt={alt}
onError={handleImageError}
style={{ width: '200px', height: '200px', objectFit: 'cover' }}
/>
);
};
export default ImageWithFallback;
使用时只需要传入原始图片地址、默认图片地址和alt属性即可：
<ImageWithFallback src="https://ipipp.com/broken-image.jpg" fallbackSrc="https://ipipp.com/default-avatar.jpg" alt="用户头像" />
方案二：封装自定义Hooks实现
如果项目中多处需要使用图片降级功能，重复写onError事件逻辑会比较冗余，我们可以封装一个自定义Hooks来复用逻辑。
import { useState } from 'react';
const useImageFallback = (originalSrc, fallbackSrc) => {
const [imgSrc, setImgSrc] = useState(originalSrc);
const handleError = () => {
// 只在当前图片不是默认图的时候才替换，避免循环
if (imgSrc !== fallbackSrc) {
setImgSrc(fallbackSrc);
}
};
return { imgSrc, handleError };
};
export default useImageFallback;
在组件中使用这个Hooks：
import React from 'react';
import useImageFallback from './useImageFallback';
const UserCard = () => {
const { imgSrc, handleError } = useImageFallback(
'https://ipipp.com/user-avatar.jpg',
'https://ipipp.com/default-avatar.jpg'
);
return (
<div className="user-card">
<img
src={imgSrc}
alt="用户头像"
onError={handleError}
style={{ width: '100px', height: '100px', borderRadius: '50%' }}
/>
<p>用户名</p>
</div>
);
};
export default UserCard;
方案三：高阶组件封装
如果项目中有很多不同的图片组件都需要降级能力，也可以使用高阶组件来统一包装，让被包装的组件自动具备图片加载失败降级的能力。
import React from 'react';
const withImageFallback = (WrappedComponent, fallbackSrc) => {
return (props) => {
const handleError = (e) => {
if (e.target.src !== fallbackSrc) {
e.target.src = fallbackSrc;
}
};
return <WrappedComponent {...props} onError={handleError} />;
};
};
export default withImageFallback;
使用高阶组件包装原生img标签：
import React from 'react';
import withImageFallback from './withImageFallback';
const FallbackImg = withImageFallback('img', 'https://ipipp.com/default-image.jpg');
const Gallery = () => {
return (
<div className="gallery">
<FallbackImg
src="https://ipipp.com/photo1.jpg"
alt="风景1"
style={{ width: '150px', margin: '10px' }}
/>
<FallbackImg
src="https://ipipp.com/photo2.jpg"
alt="风景2"
style={{ width: '150px', margin: '10px' }}
/>
</div>
);
};
export default Gallery;
注意事项
- 一定要判断当前图片地址是否已经是指定的默认图，避免默认图也加载失败时无限触发onerror事件，造成死循环。
- 默认图像的地址最好使用稳定的CDN资源或者本地静态资源，确保默认图本身可以正常加载。
- 如果图片需要设置跨域属性，记得在img标签上添加
crossOrigin属性，避免默认图加载出现跨域问题。 - 对于动态切换图片src的场景，需要在src变化时重置图片的加载状态，避免还显示之前的默认图。
不同方案的选择建议
如果只是单个或者少量图片需要降级功能，直接使用原生onError事件处理即可，简单直接；如果项目中多处需要复用降级逻辑，优先选择自定义Hooks方案，更符合React的函数式组件开发习惯；如果项目中存在很多类组件或者需要统一包装多个不同类型的图片相关组件，可以选择高阶组件方案。