TrueGrowth/docs/RETRY_IMAGE_COMPONENT_LESSONS.md

Retry Image Component Lessons

背景

图片生成任务完成后，远端文件或本地虚拟缓存路径可能短时间不可读，直接使用 <img> 会出现一次性加载失败的破图。任务队列已有 RetryImage，但其他生成图展示入口仍散落使用原生 <img> 或 CSS background-image。

经验

• 生成结果图统一使用公共 RetryImage，不要在各页面重复写 onError 重试。
• RetryImage 的失败通知应在重试耗尽后触发，避免外层第一次 onError 就切到失败占位。
• 列表、缩略图、画廊等紧凑 UI 默认关闭 skeleton，直接保持原 <img> 布局，避免额外 wrapper 撑乱尺寸。
• 需要 ref/onLoad 的媒体预览主图，可以通过 forwardRef 接入 RetryImage，保留自适应缩放逻辑。
• CSS background-image 不会触发组件重试，生成锚点这类背景预览要改成真实图片节点。
• 素材库类长列表仍应保留懒加载；可在 LazyImage 进入视口后下沉复用 RetryImage，兼顾性能和容错。
• 视频封面已有 VideoPosterPreview 专用重试逻辑，不必强行替换。
• 用户上传预览、本地帧图、品牌图标、画布内部图片元素不属于“生成后短时间不可读”的主风险面，除非出现实际问题，不应扩大替换范围。

替换优先级

1. 任务结果缩略图、批量生图预览、生成历史。
2. 工作流首尾帧、角色参考图、漫画/PPT/Markdown 生成图。
3. 媒体预览主图和缩略图队列。
4. 素材库和提示词历史中的生成图复用入口。

验证建议

• 跑 pnpm nx run drawnix:typecheck。
• 跑图片任务重试相关测试。
• 检查紧凑缩略图容器是否因 wrapper 发生尺寸变化。
• 搜索剩余 <img> 时按来源判断，不要机械替换所有图片节点。