HTML不提供图片资源管理功能，需通过data-属性语义化标记、JSON数据驱动渲染、统一相对路径、错误监听上报等机制实现系统化管理。
HTML 本身不提供“图片资源管理”功能，它只是声明和引用图片的媒介；真正能系统化整理素材的，是围绕 HTML 构建的一套约定 + JS 控制逻辑 + 目录结构约束。关键不是写多少
用语义化 data- 属性标记图片类型与用途
靠文件名或目录区分“头像/封面/示意图”太脆弱，容易误删或错配。给
- 统一加
data-category：比如
document.querySelectorAll('img[data-category="team-headshot"]')一键选中所有团队头像 - 避免用 class 做分类：class 是样式层概念，混用会导致 CSS 选择器污染，且无法表达层级（如
team-headshot-v2vsteam-headshot-legacy） - 配合
data-source记录原始出处：比如data-source="figma-export-20261002"，迁移或审计时可追溯生成来源
把图片配置从 HTML 中抽离成 JSON 数组驱动
硬编码 srcset。用纯数据驱动渲染，HTML 只保留容器，JS 负责生成。
- 定义一个
assets/images.json，内容类似：
[
{
"id": "hero-banner",
"src": "images/hero-1920.jpg",
"webp": "images/hero-1920.webp",
"avif": "images/hero-1920.avif",
"alt": "首页横幅：秋季新品发布",
"category": "marketing"
}
]
- 页面加载后用 JS 读取该 JSON，遍历生成
sizes、type严格一致 - 开发阶段改图只需动 JSON 和文件，不碰 HTML；上线前还可加校验：检查 JSON 中每个
src对应文件是否存在、尺寸是否超限
批量监听加载失败并自动上报缺失路径
本地开发时图片 404 不报错，只显示小图标，等上线才发现首页 banner 全是占位图。必须让错误可见、可统计、可回溯。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 全局监听不能只靠
onerror内联写法： - 用 JS 统一注册事件，并记录完整上下文：
document.querySelectorAll('img').forEach(img => {
img.addEventListener('error', e => {
console.warn('[IMG FAIL]', img.src, 'in', img.closest('[data-category]')?.dataset.category);
// 这里可发到日志服务，或存入 localStorage 供 QA 导出
});
});
- 开发时快速筛查：在控制台运行
Array.from(document.images).filter(i => i.naturalWidth === 0 && i.src)，直接列出所有“请求成功但内容为空”的图片——这类问题onerror完全不触发
路径必须全相对，且以 HTML 文件为基准计算
这是团队协作中最常破防的一点：A 在根目录写 src="images/logo.png"，B 把页面挪到 /about/ 下，结果所有图 404，还查不出原因。
- 所有路径去掉开头的
/和./，直接写images/logo.png—— 浏览器默认以当前 HTML 所在目录为起点解析 - 禁止混用路径写法：
../assets/team.jpg和assets/team.jpg在不同入口页行为完全不同，CI 构建时可能通过，本地调试却全挂 - 构建工具（如 Vite）支持别名，但 HTML 中不能用
@/assets/这类写法——它只在 JS/CSS 中生效，HTML 的src是运行时由浏览器解析的，不走构建流程
真正的素材整理，不是把图堆进文件夹，而是让每张图在 HTML 生态里有唯一 ID、可验证路径、可追踪用途、可批量替换。一旦路径和语义脱钩，再多的自动化脚本也救不回混乱的引用关系。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
